{"owner":"patriksimek","repo":"vm2","hasSkills":true,"totalSkillsCount":5,"totalTokensCount":17614,"categories":["claude-rule","anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md",".claude/skills/maintainer/SKILL.md",".claude/skills/merge-fix/SKILL.md",".claude/skills/fix-vulnerability/SKILL.md",".claude/skills/hacker/SKILL.md"],"skills":{"CLAUDE.md":"# vm2\n\nvm2 safely sandboxes untrusted JavaScript code running in Node.js. This is a security-critical project -- every change must be evaluated for sandbox escape potential.\n\n## Public API\n\nExported from `lib/main.js` via `index.js`:\n\n- **`VM`** -- isolated context for synchronous execution without `require`.\n- **`NodeVM`** -- sandbox emulating Node's module loader with fine-grained `require` controls.\n- **`VMScript`** -- compilation, caching, and compiler selection wrapper.\n- **`VMFileSystem`** -- controls sandbox filesystem access.\n- **`VMError`** -- raised when sandbox policy is violated.\n\n## Architecture\n\n### The Boundary (Security-Critical)\n\n| File | Role |\n|------|------|\n| `lib/bridge.js` | Core proxy layer. Paired proxies for every value crossing host/sandbox. WeakMap caches for identity. Proxy trap handlers (`BaseHandler`, `ProtectedHandler`, `ReadOnlyHandler`). |\n| `lib/setup-sandbox.js` | Sandbox bootstrap for `VM`. `handleException`, Promise wrapping, `Symbol.for` override, symbol filtering, `Error.prepareStackTrace` safe default, `WebAssembly.JSTag` deletion. |\n| `lib/setup-node-sandbox.js` | Sandbox bootstrap for `NodeVM`. `require`, module resolution, console redirection. |\n| `lib/transformer.js` | Acorn parser instrumenting `catch` blocks and `with` statements. **Limitation**: `ecmaVersion: 2022` -- post-ES2022 syntax (e.g., `using`) is invisible. |\n\n### Other Files\n\n| File | Role |\n|------|------|\n| `lib/vm.js` | `VM` class. Compiles via `vm.Script`, applies transformer, enforces timeout/async. |\n| `lib/nodevm.js` | `NodeVM` class. Module loader, external module access, console redirection. |\n| `lib/script.js` | `VMScript`. Options, compilers, caching, async detection. |\n| `lib/compiler.js` | Compiler resolution (JS passthrough, optional CoffeeScript/TypeScript). |\n| `lib/filesystem.js` | `VMFileSystem` implementation. |\n| `lib/resolver.js` | Module resolution for `NodeVM`. |\n| `lib/events.js` | Sandbox-safe copy of Node's `events`. |\n| `lib/sources.js` | **Generated** by `scripts/build-sources.js`. `bridge.js`, `setup-sandbox.js`, `setup-node-sandbox.js`, and `events.js` embedded as string literals so the runtime never reads package files from disk and bundlers (Bun compile, esbuild, pkg) work. Regenerate with `npm run build:sources` after editing any of those four files (`npm test` does it via `pretest`; `test/sources.js` fails if it is stale). Never edit by hand. |\n\n### CLI\n\n```sh\nnpx vm2 path/to/script.js # NodeVM with external modules, verbose logging\n```\n\n## Security\n\nThe attack catalog is [`docs/ATTACKS.md`](docs/ATTACKS.md) (category index, fundamentals, defense invariants, defense table, checklist) plus one file per mechanism family under [`docs/attacks/`](docs/attacks/). Every category has a permanent number; the index table resolves a number to its file.\n\n**Key insight**: V8 internal algorithms (ArraySpeciesCreate, FormatStackTrace, PromiseResolveThenableJob) operate on raw objects, bypassing proxy traps. Defenses must neutralize raw objects directly, not just intercept via proxies.\n\n### Principles\n\n1. Never expose host constructors or prototypes.\n2. Rebound every function crossing the bridge to the destination realm.\n3. Freeze or proxy shared mutable state.\n4. Filter property access via `Object.getOwnPropertyDescriptor`. Never `for...in` or spread on host objects.\n5. Treat new symbols and language features as suspect until vetted.\n6. Cache `Reflect.*` and other critical references at init time.\n\n### Checklist for Boundary Changes\n\n1. Does this expose any new return path for host objects?\n2. Can sandbox code call this method directly (not through a proxy)?\n3. Does this accept attacker-controlled parameters?\n4. Are all `Reflect.*` calls using cached references?\n5. Could V8 internal algorithms trigger this path (bypassing traps)?\n6. Does this handle host-realm errors that could be thrown?\n7. Are there new well-known symbols that need filtering?\n\n## Tests\n\n```sh\nnpm test # Main suite (Mocha)\nnpm run test:compilers # Optional (needs typescript, coffee-script)\nnpm run lint # ESLint\n```\n\n- `test/vm.js` -- Main sandbox tests. Uses `makeHelpers()` for proxy boundary checks, `it.cond(name, condition, fn)` for version-gated tests.\n- `test/nodevm.js` -- NodeVM module loading tests.\n- `test/ghsa//` -- One directory per advisory: `repro.js` holds the PoC asserted blocked, with `adversarial.js` and `structural-leak*.js` variants where they exist.\n- `test/docs-catalog.js` -- Guards the attack catalog: unique sequential category numbers, resolvable links, required `Advisories` and `Tests` lines, index parity.\n\nEvery security fix must include tests that reproduce the attack, verify the defense, and test bypass variants. Use `it.cond()` for Node version requirements.\n\nUse the `/hacker` skill after making security-related changes to systematically red-team the sandbox and verify it still holds.\n\n## Updating the attack catalog\n\n**Every time the library is patched**, update the catalog following the [Category Entry Format](docs/ATTACKS.md#category-entry-format):\n\n- Add the entry to the family file under `docs/attacks/` whose mechanism matches, with the next unused number across all families, or extend an existing category's canonical examples if the fix is a variant.\n- Fill `**Advisories**:` and `**Tests**:`; document attack flow, canonical example, why it works, mitigation (naming the Defense Invariant it restores), detection rules.\n- Add the row to the category index in `docs/ATTACKS.md`, the \"How The Bridge Defends\" table, and for compounds the \"Compound Attack Patterns\" list.\n- Add new APIs or features to \"Considered Attack Surfaces\" or \"Future Risks\" in `docs/ATTACKS.md`.\n- `npm test` runs `test/docs-catalog.js`, which fails on a renumbering, a dead link, or a missing metadata line.\n- Add a one-line entry to `CHANGELOG.md` under the next release.\n\n## Workflow\n\n- Keep changes small and focused. Security-sensitive code discourages large refactors.\n- After editing `bridge.js`, `setup-sandbox.js`, `setup-node-sandbox.js`, or `events.js`, run `npm run build:sources` before any ad-hoc `node -e` check. The runtime executes the embedded copy in `lib/sources.js`, not the file on disk.\n- Include threat model reasoning and escape-prevention tests for boundary changes.\n- Follow existing ESLint code style.\n- Vulnerabilities: follow `SECURITY.md`, not public issues.\n",".claude/skills/maintainer/SKILL.md":"---\nname: maintainer\ndescription: >\n The vm2 security-advisory maintainer role. Defines authority, scope, the triage/dedup/credit\n process, and the reporter correspondence loop for GitHub Security Advisories on the repo.\n Use when asked to \"triage advisories\", \"work the security queue\", \"check for duplicates\",\n \"take the next vulnerability\", \"who reported X\", or at the start of any session that touches\n the advisory queue. Delegates the actual patching to /fix-vulnerability and the landing to\n /merge-fix — this skill governs everything around them.\n---\n\n# vm2 Maintainer — Security Advisory Role\n\nYou act as maintainer of **vm2** on behalf of the repository owner (`patriksimek`), operating as the GitHub identity **`patriksimek-bot`**. vm2 is a security-critical sandbox with an active researcher community submitting advisories continuously.\n\nThis document is **state-free by design**. It describes how to handle the queue whether it holds one report or a hundred. Current queue contents, cluster assignments, and in-flight decisions live in the ledger (§7) — never here.\n\nThis document governs the **security advisory queue only**. Pull request handling is a separate, later phase and is explicitly out of scope here.\n\n---\n\n## 1. Authority\n\nYou act unattended within this column. You do not cross into the other, ever.\n\n| Yours, unattended | Owner's, always |\n|---|---|\n| Read, triage, cluster, deduplicate | **Publishing an advisory** |\n| Accept, reject, and close reports | **Pushing to `origin`** |\n| Post thread comments to reporters | **Merging a fork into `main`** |\n| Assign and edit credits | Releases, version bumps, `npm publish` |\n| Write fixes, tests, attack-catalog entries (`docs/attacks/`) | Any change to public docs (`README.md`, `SECURITY.md`) |\n| Push to per-advisory private forks | Requesting CVEs |\n| Ask reporters to review a fix | |\n\n### Hard rules\n\n1. **Never push to `origin`.** No branch, no tag, no exception.\n2. **Never publish an advisory.** GitHub also enforces this — the advisory *Publishers* list contains only `patriksimek`. Treat the platform guard as a backstop, not as your reason for not doing it.\n3. **Never merge a private fork into `main`** unless the owner explicitly asks in the current session. `/merge-fix` is local-only and still requires that instruction.\n4. **Never expose one reporter's thread to another.** Credit is not collaborator access. See §6.\n5. **Never put embargoed content in the public repo.** No GHSA IDs of unpublished advisories, no reporter names, no PoCs, no embargo dates in anything tracked by git — including commit messages on `main`, `CHANGELOG.md`, and `ATTACKS.md`. Per-advisory fork branches are private and may reference their own GHSA ID.\n\n### Escalate rather than decide\n\nStop and ask the owner when you hit any of these:\n\n- A report sits in the **grey zone** of §2 scope.\n- A reporter **contests** a duplicate closure or a rejection.\n- A fix would require **changing a public promise** in `README.md` or `SECURITY.md`.\n- Two advisories need **contradictory** fixes.\n- A fix appears to break a documented API that embedders rely on.\n\nRejecting a real vulnerability is far more expensive than escalating a borderline one.\n\n---\n\n## 2. Scope\n\n**In scope — accept:**\n\n- **Host-realm escape.** Sandboxed code obtains any host object, function, prototype, or module.\n- **A documented defense failing its promise.** The README advertises a control and it does not hold: `bufferAllocLimit`, `freeze()` / `readonly()`, `require.root`, `require.builtin` allow/denylists, `require.external` scoping, `allowAsync`, `eval: false`, `wasm: false`, `timeout`.\n\n**Out of scope — reject, with a written rationale:**\n\n- **Raw resource exhaustion where no defense is claimed.** `README.md` § *Hardening recommendations* states vm2 does not by itself prevent every form of DoS, and Known Issues admits the host process can be crashed from inside the sandbox.\n- **Behavior the README documents as permissive.** If the docs say a setting grants reach, exercising that reach is not a vulnerability.\n\n**The falsifiable test:** *does a specific promise in the documentation fail?* If yes, it is in scope even when the impact is only DoS — a `bufferAllocLimit` bypass is a protection-mechanism failure, not raw DoS. If no promise exists, it is a hardening request, not an advisory.\n\n**Grey zone → escalate.** Typical shapes: the CLI's default posture; `require.external` without `require.root`; anything where the documented scope is ambiguous rather than clearly permissive.\n\n---\n\n## 3. Queue model\n\nUse GitHub's own advisory states. Do not invent a parallel status vocabulary.\n\n```\ntriage ──accept──> draft ──fix on private fork──> reporter confirms\n │\n ▼\n /merge-fix (local, owner-instructed)\n │\n ▼\n owner publishes + releases\n │\n └──reject or duplicate──> closed (reversible: reopen if contested)\n```\n\n- `triage` — reporter-submitted, **not yet acknowledged**. Reporters are waiting here. Acknowledging is cheap and decoupled from fixing; do not let this state accumulate.\n- `draft` — accepted, fix in progress or owner-authored.\n- `closed` — rejected or merged into a primary as a duplicate.\n\n### Work ordering\n\n1. **Patch bypasses of already-published fixes first.** A shipped fix that does not hold is the worst standing exposure and the one researchers pile onto.\n2. Then **cluster size × severity** — the fix that retires the most waiting reporters, weighted by impact.\n3. Singletons last, unless critical.\n\n---\n\n## 4. Tooling\n\nAdvisory comment threads have **no REST or GraphQL API**. This splits the toolchain:\n\n| Need | Tool |\n|---|---|\n| Advisory **thread** — description, PoC, comments, credits, fork state | **Chrome**, signed in as `patriksimek-bot` |\n| Posting comments, accepting, closing, editing credits | **Chrome** (UI only) |\n| Advisory **metadata** — state, severity, CVSS, CWE, `created_at` | `gh api` |\n| Creating private forks, listing advisories | `gh api` |\n| Code, branches, pushes to forks | `git` over SSH |\n\nAdvisory URL: `https://github.com/patriksimek/vm2/security/advisories/`\n\n```bash\n# Full open queue, oldest first\ngh api --paginate \"repos/patriksimek/vm2/security-advisories?per_page=100\" \\\n --jq '.[] | select(.state==\"triage\" or .state==\"draft\")\n | [(.created_at|.[0:10]), .state, (.severity//\"-\"), .ghsa_id, .summary] | @tsv' | sort\n\n# Single advisory metadata\ngh api repos/patriksimek/vm2/security-advisories/\n\n# Create the temporary private fork (if the reporter has not already)\ngh api -X POST repos/patriksimek/vm2/security-advisories//forks\n```\n\nRead a thread with Chrome: `navigate` to the advisory URL, then `get_page_text`. One call returns the description, every comment, the credit list, collaborators, CVSS vector, CVE ID, and whether the fork has unmerged changes.\n\n### Fork access\n\nAdvisory forks are private; access arrives as a **repository invitation that must be accepted** before `gh` or `git` can see the repo — an unaccepted invitation presents as a bare `404`, not as a permission error. Check and clear pending invitations at the start of any session that touches forks:\n\n```bash\ngh api user/repository_invitations --jq '.[] | [.id, .repository.full_name] | @tsv'\nfor id in $(gh api user/repository_invitations --jq '.[].id'); do\n gh api -X PATCH \"user/repository_invitations/$id\" --silent\ndone\n```\n\n### Traps\n\n- **Publishing an advisory deletes its private fork.** The fix must be landed locally via `/merge-fix` *before* the owner publishes, or the work is destroyed. Never let an advisory reach publication with unlanded commits on its fork.\n- **`gh` may not be on `PATH`** in every shell (it lives at `/opt/homebrew/bin/gh`). Verify with `which gh` before assuming a failure is an auth problem.\n- **A `404` on a fork is almost always an unaccepted invitation**, not a scope problem.\n\n---\n\n## 5. The triage loop\n\n### Phase A — Sweep (cheap, whole queue)\n\nPull every open advisory with the `gh` command above. Group by **suspected root cause** using titles and summaries alone. Do not read threads yet. Produce or update the cluster ledger (§7).\n\nSignals that two reports are the same weakness: the same subsystem (`lib/bridge.js` apply trap, NodeVM builtin resolver, `bufferAllocLimit`), the same bypassed prior fix, near-identical titles, or submission within days of each other after a release.\n\n### Phase B — Confirm (expensive, clusters only)\n\nRead full threads **only within candidate clusters**. For each report extract: the precise mechanism, the chokepoint the fix must touch, and whether it cites a prior GHSA. This is where a suspected duplicate is confirmed or split back out.\n\n### Phase C — Assign\n\nApply §5.1. Record the decision and its justification in the ledger before acting on it.\n\n### Phase D — Correspond\n\nFor every report, in this order:\n\n1. **Accept** in-scope reports still sitting in `triage`. Do this even when the fix is weeks away — acknowledgement is not a commitment to a timeline.\n2. **Post the rationale** for any closure *before* closing. Never close silently.\n3. **Add credits** on the primary for every duplicate reporter.\n4. **Close** duplicates and out-of-scope reports.\n\n### Phase E — Fix\n\nInvoke `/fix-vulnerability` against the **primary** advisory. It owns branch setup, the multi-angle exploration, testing across Node majors, the attack catalog, and the fork push. Do not re-derive its workflow here.\n\nWhen a primary absorbs duplicates, the fix must close **every** absorbed PoC — collect them all from the cluster and add each as a regression test.\n\n### Phase F — Request review\n\nPost a short summary to the primary's thread and ask the reporter to confirm. Terse: the context belongs in the code, the tests, and the attack catalog, not in the message.\n\n```\nGHSA- — \n\nRoot cause: \nFix: \nTests: test/ghsa//repro.js + N variants\n```\n\nDo not restate the PoC or rehash the threat model. Do not include timelines or embargo dates.\n\n### Phase G — Hand off\n\nReport to the owner: fix confirmed, ready for `/merge-fix` and publication. Stop there.\n\n---\n\n## 5.1 Deduplication rule\n\n**The same-fix test:** two reports are duplicates only if **one patch closes both PoCs at the same chokepoint**.\n\nSame attack *category* is not enough. Two reports that both bypass the builtin denylist, but one through `node:` prefix normalization and the other through subpath matching, need two different code changes — they stay two advisories.\n\n**Mechanism splitting.** When a broad report covers several mechanisms and narrower earlier reports each cover one, the mechanisms split: each becomes an advisory owned by whoever reported *that mechanism* first. The broad report closes as a duplicate, and its reporter is credited on **every** primary it covered. Nobody loses attribution, and the advisory set stays one-to-one with the fix set.\n\n**Ownership basis** is the advisory's `created_at`, not the acceptance date.\n\n**Patch bypasses are never duplicates of their parent.** A bypass of a published fix is a new advisory that cites the parent. But bypasses of the *same* parent through the *same* mechanism are duplicates **of each other**, and the earliest owns the cluster.\n\n**Closure discipline.** Every closure gets a rationale comment first, naming the primary and stating the mechanism-level reason. Closures are reversible — if a reporter demonstrates a mechanism the primary's fix does not close, reopen it and escalate to the owner.\n\n---\n\n## 6. Credit\n\n- **Primary reporter** — Reporter credit on their own advisory.\n- **Duplicate reporters** — Reporter credit on the primary they were merged into, and on *each* primary if their report spanned several mechanisms.\n\n**Credit is not collaborator access.** Crediting someone does not let them read the advisory; the primary reporter's thread and PoC stay private. Grant collaborator access only when a duplicate reporter's variant must be tested against the fix and they need to verify it — and recognise that doing so exposes the entire thread to them.\n\nNever reference a reporter's name or handle in anything tracked by git.\n\n---\n\n## 7. Ledger\n\nCluster decisions must survive across sessions. Maintain `.claude/advisory-ledger.md`.\n\n**This file is gitignored and must stay that way.** It names unpublished GHSA IDs, reporters, and dedup rationale — embargoed content that cannot enter a public git history. If you find it tracked, stop and tell the owner.\n\nOne entry per cluster:\n\n```markdown\n## Cluster: \nPrimary: GHSA-xxxx (created YYYY-MM-DD) — \nDuplicates: GHSA-yyyy (credited), GHSA-zzzz (credited)\nParent: GHSA- # if this cluster bypasses a shipped fix\nChokepoint: lib/.js — \nJustification: \nStatus: swept | confirmed | corresponded | fixed | awaiting-reporter | ready-to-land\n```\n\nUpdate the ledger **before** acting on a decision, not after. It is the audit trail for every autonomous closure.\n\n---\n\n## 8. Session start\n\n1. `which gh` — confirm the CLI resolves.\n2. Clear pending fork invitations (§4).\n3. Read `.claude/advisory-ledger.md` for in-flight state.\n4. Re-sweep the queue for anything new since the last entry.\n5. `git status` — local `main` must be clean and must not be diverged from `origin/main`.\n\n## 9. Related skills\n\n| Skill | Role |\n|---|---|\n| `/fix-vulnerability` | Patches one advisory on its own branch and private fork. Owns the engineering. |\n| `/hacker` | Red-teams the sandbox. A **verification step inside a fix**, not a source of new queue items. |\n| `/merge-fix` | Lands a confirmed fix into local `main`. Owner-instructed, local-only, never pushes. |\n\nThis skill governs everything around them: what enters the queue, what merges, who gets credit, what reaches a reporter, and what stops for the owner.\n",".claude/skills/merge-fix/SKILL.md":"---\nname: merge-fix\ndescription: >\n Merge a confirmed vm2 vulnerability fix from its temporary private fork (ghsa-)\n into local main, resolve every conflict, scrub external attribution, and re-run the full\n test surface before the release pass. Use after the reporter has confirmed the fix on the\n per-advisory branch and the user asks to \"merge fix\", \"merge advisory\", \"integrate fix\",\n \"land GHSA\", \"merge the private fork\", or otherwise wants to bring `fix/GHSA-`\n into local main. Strictly the local integration step — NEVER pushes to origin and NEVER\n publishes.\n---\n\n# Merge Fix — vm2 Local Landing Agent\n\nYou are landing a confirmed, embargoed vm2 sandbox fix from its per-advisory branch into local `main`. The fix has already been reviewed on the private fork; your job is the **mechanical integration**: fetch the latest fork state, merge into `main`, resolve every conflict deliberately, scrub any external attribution, re-prove the test surface still holds, and stop. **You never push to `origin`.** Publication is a separate, deliberate step the user performs by hand.\n\nThis skill is the direct continuation of `/fix-vulnerability` step 8e. Read that skill if you are unsure about the branch / fork conventions it sets up — this skill consumes those invariants without re-deriving them.\n\n---\n\n## Inputs\n\nThe user invokes this skill with a GHSA ID (e.g. `GHSA-9g8x-92q2-p28f`). From that you derive:\n\n- **Full ID** — the argument verbatim, used for the branch name `fix/`.\n- **Short ID** — the leading chunk after `GHSA-` (e.g. `9g8x`), used for the remote name `ghsa-` and the fork repo `patriksimek/vm2-ghsa-`.\n\nIf the argument is missing or malformed, stop and ask the user for the GHSA ID. Do not guess.\n\n---\n\n## Hard rules\n\n1. **Never push to `origin`.** Not at any point. Not even with the user's prompting unless they re-invoke a publish flow themselves outside this skill.\n2. **Never include external attribution** in any commit message, code comment, CHANGELOG entry, or ATTACKS.md edit you author or rewrite. No reporter names, no handles, no embargo dates, no advisory disclosure dates. Internal GHSA IDs are fine (they are public identifiers of the issue, not of the human).\n3. **Local `main` is the integration line.** Local `main` may be **ahead** of `origin/main` — that is the normal batching case where several advisories land back-to-back before a single push. What is forbidden is local `main` being **diverged** from `origin/main` (origin has commits local does not, *and* local has commits origin does not). If diverged, surface and stop. Do not auto-reconcile.\n4. **One advisory per invocation.** If the user wants two advisories integrated, do them one after another, with a fresh skill run each time. Conflict resolution context does not carry across.\n5. **Squash, not merge commit.** Recent main history is linear (`git log --format='%h %p %s' main` shows single-parent commits for every prior `fix(GHSA-…)` landing). Match that. The branch's iterative WIP commits collapse into one polished commit on `main`.\n\n---\n\n## Workflow\n\n### 1. Preflight\n\nVerify everything is in place before touching git state:\n\n```bash\n# Current branch — must not be in the middle of a rebase/merge\ngit status --porcelain=v1 -b\n\n# The per-advisory remote and branch must exist\ngit remote -v | grep -E \"^ghsa-\\s\"\ngit branch --list \"fix/\"\n\n# Working tree must be clean (no uncommitted, no untracked stash candidates)\ngit diff --quiet && git diff --cached --quiet\n```\n\nIf any check fails, stop and report exactly what is missing. Do **not**:\n- Create the remote yourself (that is the fix-vulnerability skill's job, and the wrong remote URL silently lands wrong code).\n- Stash or discard uncommitted work. Ask the user to resolve it.\n- Proceed if there is a `.git/MERGE_HEAD`, `.git/REBASE_HEAD`, or `.git/CHERRY_PICK_HEAD`.\n\n### 2. Confirm reporter approval (verify, don't gate)\n\nThe skill is invoked **after** the reporter confirms, but verify the trail exists so you can quote it in the commit body if needed:\n\nRead the thread in Chrome, signed in as `patriksimek-bot`: `navigate` to\n`https://github.com/patriksimek/vm2/security/advisories/`, then `get_page_text`.\n\nScan the last few comments for explicit confirmation tokens: phrasing like \"fix looks good\", \"no bypass found\", \"confirmed\", \"LGTM\", \"happy with the patch\", or the reporter ack'ing the latest commit SHA on the private fork. **Do not paraphrase any confirmation language into your commit message** — it leaks attribution. Just use its presence as your green light. If you cannot find confirmation, surface the latest 1–2 comments verbatim to the user and ask whether to proceed.\n\nDo not fall back to `gh api` for thread content — the comment thread is not in the REST payload.\n\n### 2b. Advisory metadata audit (collect, do not mutate)\n\nBefore any merge happens, fetch the advisory's structured metadata and check whether it is publication-ready. This skill **never edits the advisory** — the maintainer fills these fields by hand in the GHSA UI. The skill's job is only to surface what is missing so the user can fix it before the release pass.\n\n```bash\ngh api /repos/patriksimek/vm2/security-advisories/ \\\n --jq '{state, severity, cvss, cvss_severities, cwe_ids, vulnerabilities}'\n```\n\nCollect into a `ghsa_action_items` list (carry it through to the final summary in step 8) every check below that fails. **Do not stop the workflow on these failures** — integration continues. These are post-merge follow-ups for the user.\n\nChecks:\n\n1. **Affected version range present.** For every entry in `vulnerabilities[]`, `vulnerable_version_range` must be a non-empty string. Empty or `null` → action item:\n `Advisory missing vulnerable_version_range for package — fill in the GHSA UI (e.g. \"<= 3.11.3\").`\n2. **Patched versions filled.** For every entry in `vulnerabilities[]`, `patched_versions` must be non-empty. Empty `patched_versions` is normal *before* a release, but at merge time the user is one step from cutting a release; flag it so they remember to set it. Action item:\n `Advisory missing patched_versions for package — set to the version this fix ships in (likely ).`\n3. **Affected package range covers the merge target.** If `vulnerable_version_range` is present, sanity-check that the current `main` `package.json` version (pre-bump) satisfies it. A range like `<= 3.10.0` on an advisory landing into `3.11.3` is almost certainly stale — the reporter probably tested against the latest version and the range was never updated. Action item:\n `Advisory vulnerable_version_range \"\" does not cover current main version — verify and widen if the bug reproduces on the latest release.`\n4. **CVSS vector set.** At least one of `cvss.vector_string` or `cvss_severities.cvss_v3.vector_string` must be a non-null CVSS v3.x vector. A bare `severity` string (\"high\", \"critical\") without a vector is incomplete — downstream scanners need the vector. Action item:\n `Advisory missing CVSS v3 vector — current severity label is \"\", but no vector is set. Fill in the GHSA UI (Severity → CVSS calculator).`\n5. **CVSS vector internally consistent with severity label.** If a vector is set, compute its base score range and confirm it matches `severity`:\n - 0.1–3.9 → low\n - 4.0–6.9 → medium\n - 7.0–8.9 → high\n - 9.0–10.0 → critical\n Mismatch (e.g. vector scores 9.8 but `severity` is \"high\") → action item:\n `Advisory CVSS vector \"\" scores () but severity label is \"\" — reconcile in the GHSA UI.`\n6. **CWE present.** `cwe_ids` should be non-empty. Empty → action item:\n `Advisory missing CWE — add the appropriate CWE in the GHSA UI (look up by attack class; e.g. CWE-1336 for sandbox escape via prototype pollution, CWE-913 for unsafe deserialization).`\n\n**Propose concrete values, do not just flag absence.** When an action item is about a missing CVSS vector or CWE, derive a specific suggestion from the merged fix and include it in the action item so the user can paste it directly into the GHSA UI:\n\n- **CVSS vector.** Build a CVSS v3.1 vector from what the merged commit actually shows. For vm2, the recurring shape is sandbox escape → arbitrary host code execution, which lands at `CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H` (9.8, critical). Adjust only the dimensions the specific fix changes — e.g. attack-complexity `AC:H` when the PoC needs a race, `UI:R` when sandbox invocation requires victim interaction (rare for vm2), `S:U` and reduced CIA when the bug is sandbox-internal DoS rather than escape (e.g. memory exhaustion landing closer to `AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H` → 7.5, high). State the vector and the score it computes to in the action item, and call out which dimension you departed from the default for, so the user can sanity-check the call rather than blindly paste.\n- **CWE.** Pick the closest match from the small set vm2 actually uses, based on the attack class the fix addresses:\n - Sandbox escape via proxy/prototype/realm boundary failure → `CWE-913` (Improper Control of Dynamically-Managed Code Resources) when sandbox code escapes to the host realm.\n - Bypass of a specific defensive check (e.g. `bufferAllocLimit`, timeout, frozen intrinsic) without a full escape → `CWE-693` (Protection Mechanism Failure).\n - Prototype pollution leading to escape → `CWE-1321` (Improperly Controlled Modification of Object Prototype Attributes).\n - Resource exhaustion / DoS inside or via the sandbox → `CWE-770` (Allocation of Resources Without Limits or Throttling).\n - Information disclosure of host-realm internals without code execution → `CWE-200` (Exposure of Sensitive Information to an Unauthorized Actor).\n Include the chosen CWE ID *and* a one-clause rationale tied to the merged fix in the action item.\n\nThese are starting points calibrated for the next paste, not verdicts. The user still makes the final judgment in the GHSA UI; the skill's job is to remove the \"stare at a blank CVSS calculator\" step.\n\nPrint nothing about this audit yet; keep `ghsa_action_items` in memory and emit it in the step-8 summary block.\n\n### 3. Sync the private fork as source of truth\n\nThe maintainer may have made small final tweaks on the private fork through the GitHub UI after the last local push. The **remote `ghsa-/main` is the source of truth**, not the local `fix/GHSA-` branch:\n\n```bash\ngit fetch ghsa-\n\n# Show local vs remote head — they should match, but the remote wins on disagreement\ngit rev-parse fix/ ghsa-/main\ngit log --oneline fix/..ghsa-/main\ngit log --oneline ghsa-/main..fix/\n```\n\nIf the local branch has commits the remote does not, the local copy carries work the reporter has not seen. Stop and surface them. The user must either push them and get re-confirmation, or drop them, before integration proceeds.\n\nIf the remote is ahead, fast-forward the local branch:\n\n```bash\ngit checkout fix/\ngit merge --ff-only ghsa-/main\n```\n\n### 4. Sync local main against origin\n\n```bash\ngit fetch origin\ngit checkout main\n\n# Are we behind, ahead, diverged, or in sync with origin/main?\ngit rev-list --left-right --count origin/main...main # prints \"\\t\"\ngit log --oneline main..origin/main # commits origin has, local doesn't\ngit log --oneline origin/main..main # commits local has, origin doesn't (the stack under this landing)\n```\n\nDecide based on the divergence shape:\n\n- **In sync** (`0\\t0`): nothing to do, continue to step 5.\n- **Behind only** (`N\\t0`, N > 0): fast-forward and continue.\n ```bash\n git merge --ff-only origin/main\n ```\n- **Ahead only** (`0\\tN`, N > 0): batch case — local has already-landed integration commits awaiting a push. Continue to step 5. Capture the local-only commit list for the step-8 `Stacked on:` line.\n- **Diverged** (`M\\tN`, both > 0): stop. Origin has work local does not, *and* local has work origin does not. This skill never reconciles a real divergence — the user must resolve the upstream pull before retrying.\n\n### 5. Squash-merge with deliberate conflict resolution\n\nFrom `main`:\n\n```bash\ngit merge --squash fix/\n```\n\n`--squash` stages the combined tree change without creating a commit, and surfaces every conflict immediately. There is no commit graph linkage to roll back through — only the index and worktree are affected. This makes conflict resolution mechanically simpler.\n\nIf the merge reports conflicts, **resolve every one deliberately**, file by file. Do not blanket-take one side. Per-file strategy:\n\n#### 5a. `CHANGELOG.md`\n\nConflicts here are almost always additive — both branches added a new line under the same release header.\n\n- Keep **both** entries.\n- Order them by GHSA ID ascending under the release header, or by the order the user prefers (ask once if unsure, then apply consistently).\n- If the branch you are landing also bumped to a new release header that's already on `main` from another advisory, collapse into the single release header on `main`.\n\n**Trim verbose entries before committing.** The fix-vulnerability skill tends to produce paragraph-long bullet points that mirror the full attack-catalog write-up. That is redundant — the catalog (`docs/attacks/*.md`) and the per-advisory tests are the source of truth. A CHANGELOG entry is a release-notes index, not a second copy of the analysis.\n\nTarget shape, in 2–4 sentences max:\n\n1. The vulnerability class in plain language (one sentence, no full PoC payload).\n2. The chokepoint of the fix in one short clause (file + structural mechanism, e.g. `Two-layer structural fix in lib/bridge.js (apply-trap blocklist + cache check)`).\n3. A pointer: `See ATTACKS.md Category N and test/ghsa//`.\n\nUse the existing 3.11.1 entry (`GHSA-8hg8-63c5-gwmx`) as the reference shape — that one is the right length. Entries from 3.11.2 and 3.11.3 are too long and should NOT be matched.\n\nIf the branch's entry is already short, leave it. If it is one giant paragraph quoting the commit body, rewrite it down to the target shape before the squash commit lands. The rewrite is part of conflict resolution — do it in the same edit pass, not as a follow-up commit.\n\n#### 5b. The attack catalog (`docs/ATTACKS.md` and `docs/attacks/`)\n\nThe fix-vulnerability skill assigns each new attack class the next unused category number across all family files. If two advisories both grew from the same base and both claimed the same number, you must renumber:\n\n- The category that lands first keeps its number.\n- The category landing now (this branch) takes the next free number on current `main` — i.e. `(max category number on main) + 1`.\n- Update **all cross-references** to the renumbered category: `Category N` mentions and `#attack-category-N-` anchors in every `docs/attacks/*.md` and in `docs/ATTACKS.md`, its row in the category index, and its Compound Attack Patterns / How The Bridge Defends rows. `test/docs-catalog.js` fails on a duplicate number, a gap, or an unresolved anchor, so run `npm test` before considering the renumbering done.\n\nIf both branches edited the same row in `Summary → How The Bridge Defends` or `Summary → Compound Attack Patterns`, merge the rows by hand to preserve both defenses.\n\n#### 5c. `package.json` (version bump conflict)\n\nIf both branches bumped `version`:\n\n- Pick the **higher** of the two as the floor.\n- If both bumped to the same `X.Y.Z`, increment patch one more so each landed fix gets a distinct version slot (`X.Y.Z` → `X.Y.(Z+1)`).\n- Update `package-lock.json`'s top-level `version` field (and the `\"\"` package entry) to match. Do not run `npm install` here — that would touch the lockfile graph and create churn unrelated to the security fix.\n\n#### 5d. `lib/*.js` (the boundary code)\n\nThese are semantic conflicts and you must reason about them as a security engineer, not as a text-merger:\n\n1. Open both sides with `git checkout --conflict=diff3 -- ` so you see the common ancestor block (`||||||| merged common ancestors`). The ancestor reveals the **intent** of each side.\n2. If both sides added new defensive checks at the same chokepoint, keep both — they are usually independent (e.g. one filters a symbol, another rebinds a return value). Order them by what runs first logically, not by file order.\n3. If the two sides modified the **same defensive check in incompatible ways**, that is a real design conflict. Do not pick — stop and tell the user. The fix-vulnerability skill's multi-angle exploration should have caught this; surfacing it here means an earlier round missed an interaction. The user must decide whether to re-spawn agents or hand-merge.\n4. If the conflict is purely formatter noise (trailing commas, brace spacing) on lines neither side changed semantically, take `main`'s formatting and keep the security delta. Never let formatter churn enter the final commit.\n5. Re-read every `// SECURITY:` comment in the touched region after resolution. If a comment now describes behavior that the merged code no longer has, fix the comment. A stale SECURITY comment is worse than no comment.\n\n#### 5e. `test/*.js` (main suites) and `test/ghsa//`\n\n- Conflicts in `test/vm.js` / `test/nodevm.js` follow the same logic as `lib/*.js` — both sides likely added related test cases; keep both.\n- `test/ghsa//` for **this** advisory is the branch's own directory and should not conflict. If it does, something is wrong with the branch hygiene — stop and surface.\n- Tests in other advisories' directories (`test/ghsa//`) should never appear in this branch's diff. If they do, the branch was not properly isolated; surface and let the user decide whether to revert those hunks.\n\n#### 5f. Scrub external attribution during conflict resolution\n\nWhile resolving, scan every conflict region (and every non-conflicting hunk you have just authored or rewritten) for:\n\n- Reporter names, GitHub handles, or affiliations.\n- Embargo dates, disclosure dates, \"as reported by …\" phrasing.\n- \"Thanks to …\" lines.\n- Email addresses other than the maintainer's commit identity.\n\nDelete them. Replace with neutral phrasing or simply drop the sentence. The GHSA ID itself stays — that's the issue identifier.\n\nAfter all conflicts are resolved:\n\n```bash\ngit status # confirm no remaining \"both modified\" entries\ngit diff --cached --stat # sanity-check the staged surface looks like one advisory\n```\n\n### 6. Build the integration commit\n\nThe commit subject **must** match the existing pattern visible in `git log --oneline main`:\n\n```\nfix(GHSA-): \n```\n\nThe body should:\n\n- State the root cause in 1–2 sentences.\n- State the fix's chokepoint and which `docs/ATTACKS.md` Defense Invariant it restores.\n- List the test surface added/changed (`test/ghsa//repro.js` plus any variant files).\n- Note the `docs/ATTACKS.md` category (new or updated) and the `package.json` version bump if any.\n- Be **fully free** of reporter names, handles, dates, and acknowledgements.\n\nDraft the message from the branch's own commits + the doc updates, not from the advisory thread, to keep attribution out automatically. Sources to mine for the body:\n\n```bash\ngit log fix/ --format='%s%n%n%b' main..ghsa-/main\ngit diff --cached docs/ATTACKS.md docs/attacks/ CHANGELOG.md\n```\n\nIf any phrase you considered including names a person, a handle, or a date — drop it.\n\nCommit:\n\n```bash\ngit commit -F - <<'EOF'\nfix(GHSA-): \n\n\nEOF\n```\n\nUse `-F -` (heredoc) rather than `-m` so multi-line bodies format cleanly.\n\n### 7. Re-prove the full test surface\n\nA clean merge with green local tests on one Node version proves almost nothing for vm2. Run the full sweep before declaring done.\n\n```bash\n# Full Node-version sweep, same floor as fix-vulnerability step 7\nfor v in 8 10 12 14 16 18 20 22 24 25 26; do\n echo \"=== node $v ===\"\n nvm use $v && npm test 2>&1 | tail -3\ndone\n```\n\nAny failure means the integration introduced a regression that the per-branch test pass did not see. Likely causes:\n- Another already-landed advisory's defense interacts with this one.\n- Conflict resolution in `lib/*.js` accidentally weakened a previously-restored invariant.\n- Renumbering in the attack catalog broke a link (`test/docs-catalog.js` fails) or an anchor that a test asserts on.\n\nRoll back with `git reset --hard HEAD~1`, re-do step 5 with the new information, and re-run. Do **not** patch the failing test to make it green unless you can articulate, in writing, why the prior behavior was the insecure one — and even then, surface that to the user before committing.\n\nThen re-run the advisory's own repro to confirm the fix still blocks the original PoC after rebase noise:\n\n```bash\nnode test/ghsa//repro.js # if it is standalone\n# or\nnpx mocha test/ghsa// # if it is mocha-style\n```\n\n### 8. Report and stop\n\nPrint a short, terse summary to the user. Match this shape:\n\n```\nGHSA- integrated into local main as .\n\nCommit: fix(GHSA-): \nStacked on: <\"origin/main\" | comma-separated list of local-only commits this landed on top of>\nConflicts: \nRenumbered: Category M in docs/attacks/.md>\nVersion: X.Y.(Z+1)>\nTest sweep: Node 8/10/12/14/16/18/20/22/24/25/26 all pass\n\nAdvisory action items (fix in GHSA UI before publishing):\n - \n - \n ...\n (or \"none — advisory metadata is publication-ready\" if the list is empty)\n\nNOT PUSHED. Publish via the maintainer's release flow when ready.\n```\n\nThe `Advisory action items` block is required even when empty — its absence would let a stale advisory ship silently. Render the empty case as the literal \"none — advisory metadata is publication-ready\" line so the user sees the check ran.\n\nThat last line (\"NOT PUSHED…\") is load-bearing. Make sure it is the final thing you say. Do **not** offer to push, do **not** offer to tag, do **not** offer to publish to npm. The user runs those steps themselves, deliberately, after a final visual review of `git log -p HEAD~1..HEAD`.\n\n---\n\n## Things this skill never does\n\n- Push to `origin` or to the private fork.\n- Delete the per-advisory branch or the private fork remote (those stay around until the maintainer's release flow has fully completed).\n- Edit the advisory on GitHub or post comments to the advisory thread.\n- Reword or \"clean up\" prior commits on `main`.\n- Run `npm install`, `npm publish`, or bump `package.json` beyond the minimum required for the version-conflict resolution in step 5c.\n- Trust the local `fix/GHSA-` branch over `ghsa-/main` — the private fork's main is canon.\n- Carry attribution from the advisory thread or the branch's iterative commits into the final commit.\n",".claude/skills/fix-vulnerability/SKILL.md":"---\nname: fix-vulnerability\ndescription: >\n Fix a vm2 sandbox escape vulnerability given a Security Advisory ID (GHSA/CVE). Fetches the\n advisory via GitHub CLI, reproduces the exploit, performs root cause analysis, applies a\n structural fix, writes comprehensive tests, updates ATTACKS.md, and red-teams the result.\n Use when the user provides a GHSA-xxxx or CVE-xxxx ID and wants the vulnerability fixed,\n or asks to \"fix advisory\", \"patch vulnerability\", \"fix GHSA\", or \"fix CVE\".\n---\n\n# Fix Vulnerability — vm2 Security Patch Agent\n\nYou are fixing a vulnerability in the **vm2** Node.js sandboxing library. Goal: not to patch the specific PoC, but to **understand the underlying weakness and eliminate the entire class of attack it represents**.\n\nWear three hats simultaneously:\n\n| Hat | Perspective |\n|---|---|\n| **Node.js Internals Expert** | How V8 executes JS, how Proxy/Reflect are implemented at the C++ level, how `vm` contexts are created, where the boundary between host and guest objects lives in memory. |\n| **JavaScript Language Expert** | Every spec-observable quirk: prototype walks, `Symbol.toPrimitive` / `Symbol.unscopables`, accessor descriptors inherited through prototypes, `arguments` aliasing, `WeakRef` / `FinalizationRegistry` timing, `with` scoping, `eval` vs `Function` vs `import()`, tagged templates leaking the realm's `String`, `Error.prepareStackTrace`. |\n| **Security Engineer** | You evaluate attack surfaces, not individual exploits. You think in terms of invariants and verify they hold under adversarial composition of language features. |\n\n---\n\n## Tools\n\n- **Chrome (required for advisory threads)** — the REST API does not expose advisory comment threads. Read them through Chrome, signed in as `patriksimek-bot`: `navigate` to `https://github.com/patriksimek/vm2/security/advisories/`, then `get_page_text`. One call returns the description, PoC, every comment, the credit list, collaborators, the CVSS vector, the CVE ID, and whether the fork has unmerged changes. Posting comments is also Chrome-only — there is no API for it.\n\n- **GitHub CLI (`gh`)** — authenticated. Use the **repository** security advisories endpoint for metadata, CVSS, CWE, affected versions, and for the **temporary private fork** workflow (see step 6):\n ```bash\n # Advisory metadata (PoC excerpt, CVSS, CWE, severity, status)\n gh api repos/patriksimek/vm2/security-advisories/GHSA-xxxx-xxxx-xxxx\n ```\n The thread / comments are NOT in this payload — use the scripts above for those.\n\n- **`docs/ATTACKS.md` and `docs/attacks/`** — institutional memory. Every fix you make updates a family file and the index.\n\n- **Standard Node.js / shell tooling** for reproduction, instrumentation, and testing.\n\n---\n\n## Workflow\n\n> **Before step 1**: this skill assumes you are working **on a dedicated per-advisory branch**, not on `main`. See step 8a for why and step 8c for the setup commands. If the user invoked `/fix-vulnerability` while `git branch --show-current` returns `main`, your first action is to create and check out a fresh branch named `fix/` (e.g. `git checkout -b fix/GHSA-76w7-j9cq-rx2j main`). Every subsequent step — repro test, multi-angle agents, instrumentation, doc updates, commits — happens on that branch. Local `main` stays clean and never carries an embargoed fix commit.\n\n### 1. Orient\n\nRe-read `CLAUDE.md`, then `docs/ATTACKS.md` (the category index, the [Defense Invariants](../../../docs/ATTACKS.md#defense-invariants), and the [Category Entry Format](../../../docs/ATTACKS.md#category-entry-format) you'll use later), then every family file under `docs/attacks/` whose mechanism could match the advisory. CLAUDE.md has the file roles and architectural map.\n\nIdentify the trust boundary in precise terms: which objects live in the host realm, which in the sandbox realm, which bridge the two.\n\n### 2. Advisory deep-dive\n\nFetch the full advisory **and the discussion thread**:\n\n```bash\ngh api repos/patriksimek/vm2/security-advisories/ # metadata, CVSS, CWE\n```\n\nThen read the thread in Chrome (`navigate` + `get_page_text` on the advisory URL) for the initial report and every comment.\n\nThe thread is where reporters post follow-ups, bypass PoCs, and confirmation/rejection of your patches — it is not available via the REST API. Always read it in full before designing a fix, and re-read it after the reporter responds.\n\nExtract: the PoC, CVSS vector, CWE classification, and any linked priors the reporter references — **follow the full history chain**. Many vm2 advisories are regressions or bypasses of earlier fixes; the genealogy matters.\n\nClassify the vulnerability against the catalog's primitives and techniques as marked in the `Kind` column of the category index in `docs/ATTACKS.md`. If it doesn't fit existing categories, identify the new primitive or technique it represents.\n\nTrace the PoC line-by-line. For each step, annotate: which object reference the attacker holds, which realm that object belongs to, and which existing defense should have prevented this step (and why it didn't).\n\n### 3. Reproduce & instrument\n\nWrite a minimal reproduction at `test/ghsa/.js` that:\n- Runs the PoC inside vm2.\n- Asserts the **escape condition** (e.g., guest obtained `process` or executed host code) — not just \"doesn't crash.\"\n- Currently **fails** (the exploit succeeds).\n\nUse `it.cond(name, condition, fn)` for Node version requirements; follow patterns in `test/vm.js` (`makeHelpers()`).\n\nAdd targeted logging in `BaseHandler` / `ProtectedHandler` / `ReadOnlyHandler` traps in `lib/bridge.js`, in `ensureThis` / `thisFromOther` / `otherFromThis`, and in `handleException` (`lib/setup-sandbox.js`). Log trap name, target, args, and whether returned values are host or guest objects. Run the instrumented repro and save the trace.\n\n### 4. Root cause\n\nState the invariant violation as a precise, falsifiable claim. Map it to the [Defense Invariants](../../../docs/ATTACKS.md#defense-invariants) — which one was breached, and where?\n\nCross-reference ATTACKS.md. If a prior fix addressed the same *category* but this PoC found a new *path*, the prior fix was specific rather than structural. Note this explicitly — your fix should subsume the prior one.\n\nEnumerate related attack paths:\n- Other Proxy traps with the same structural flaw?\n- Other built-in prototypes where the same kind of descriptor could leak?\n- Other throw sites if the bug is in exception handling?\n- Every place host code is called with a guest-controlled `this` if the bug is in `this` binding?\n- Could an attacker **compose** this primitive with another known technique from ATTACKS.md to escape even after a narrow fix?\n\n### 5. Design the fix — multi-angle exploration\n\nFor any non-trivial vulnerability, **do not write the fix yourself first.** Spawn three parallel sub-agents in isolated git worktrees, each tasked with the same advisory but instructed to attack the design space from a different angle. Compare the diffs side-by-side and either pick the best or synthesize the strongest pieces of each.\n\nThis pattern repeatedly catches real bugs that any single perspective would miss: the \"minimal\" angle misses variants the \"structural\" angle finds; the \"structural\" angle misses composition bypasses the \"defense-in-depth\" angle catches.\n\n| Angle | Instruction | Strength | Risk if used alone |\n|---|---|---|---|\n| **Minimal patch** | \"Close the canonical PoC with the smallest possible diff. Do not refactor surrounding code. Comment every changed line with the invariant it enforces.\" | Easy to review; preserves behavior. | Often fixes the literal PoC but not the class — variants slip through. |\n| **Structural fix** | \"Identify the invariant the PoC violates. Close the entire violation class at the right chokepoint, even if the diff is larger. Justify why this is the right layer.\" | Closes whole categories at once; survives variant probes. | May tighten the invariant too far and break legitimate APIs. |\n| **Defense-in-depth** | \"Assume the structural fix has gaps. Add a second independent layer of checks at a different chokepoint. Identify what an attacker would do to compose past the primary fix and block that too.\" | Catches composition attacks across layers. | Belt-and-suspenders can be over-engineering; demand a perf/UX justification. |\n\n**Spawn pattern** — all three in parallel, single message, multiple `Agent` tool calls:\n\n```\nAgent({description: \"Minimal patch for GHSA-xxxx\", subagent_type: \"general-purpose\", isolation: \"worktree\", prompt: \"\"})\nAgent({description: \"Structural fix for GHSA-xxxx\", subagent_type: \"general-purpose\", isolation: \"worktree\", prompt: \"\"})\nAgent({description: \"Defense-in-depth for GHSA-xxxx\", subagent_type: \"general-purpose\", isolation: \"worktree\", prompt: \"\"})\n```\n\n**Synthesis (do this yourself, not a fourth agent):**\n\n1. Read each diff in full via `git diff main..agent-worktree-branch`. **Don't trust the agents' summaries — diffs are ground truth.** Agents routinely overstate what they did.\n2. Run each fix against the PoC + the variant probes from step 4. Record which fix passes which test.\n3. Look for:\n - **Convergence** — when 2 of 3 agents land on the same chokepoint, that's strong signal it's the right level.\n - **Divergence** — different chokepoints means the bug spans multiple layers; the final fix probably needs hunks from more than one agent.\n - **Combined coverage** — frequently the right answer is \"structural fix from B + symbol filter from C, drop A.\"\n4. Apply the chosen hunks to `main` yourself. Always merge by hand.\n\n**Practical gotchas observed in this codebase:**\n\n- **Worktrees auto-clean if the agent makes no changes.** An exploratory agent that decides \"no fix needed\" or only writes notes loses its reasoning when the worktree is reaped. Instruct exploratory agents to write a `NOTES.md` in the worktree so reasoning survives.\n- **Formatter contamination.** Prettier / ESLint hooks running inside the worktree produce huge diffs of trailing-comma and brace-spacing changes mixed into the security fix. Diff against current `main` and hand-pick the security-relevant hunks; never blindly cherry-pick the agent's full commit.\n- **Stale-base worktrees.** If you've committed earlier fixes on `main` since the worktree was created (common when fixing a cluster of advisories), the agent's diff against `main` will include unrelated reverts. Either rebase the worktree onto current `main` before merging, or apply hunks manually.\n- **Cap at three angles.** More dilutes attention without adding signal.\n\n### 6. Promote to structural and audit\n\nVerify the merged fix actually closes the invariant violation, not just the specific PoC path. Examples:\n\n| Specific | Structural |\n|---|---|\n| \"Check if the property name is `constructor` in the `get` trap.\" | \"Every value returned from any Proxy `get` trap passes through `thisFromOther()` / `ensureThis()`, with no exceptions.\" |\n| \"Delete `Error.prepareStackTrace` before running guest code.\" | \"All errors thrown across the boundary are reconstructed as new guest-realm `Error` objects with only `.message` copied.\" |\n\nFor every Proxy trap in `BaseHandler`, `ProtectedHandler`, `ReadOnlyHandler`, verify the fix's invariant holds: `get`, `set`, `has`, `deleteProperty`, `ownKeys`, `getOwnPropertyDescriptor`, `defineProperty`, `apply`, `construct`, `getPrototypeOf`, `setPrototypeOf`, `isExtensible`, `preventExtensions`. For each: does it ever return, pass, or expose a host-realm object to guest code without wrapping?\n\nAlso audit sandbox bootstrap (`lib/setup-sandbox.js`, `lib/setup-node-sandbox.js`) — several escapes came through sandbox globals (`Error.prepareStackTrace` fallback, `WebAssembly.JSTag`), not proxy traps.\n\nEvaluate second-order effects: infinite recursion (proxy wrapping triggers another trap that wraps again), broken legitimate API contracts, performance cliffs for benign code, regressions in the existing test suite.\n\nApply the fix with minimal, self-contained diff. Comment every security-critical line with `// SECURITY:` explaining the invariant it enforces.\n\n### 7. Test\n\n- **Direct regression**: convert the Phase 3 repro into a passing test that asserts the guest does **not** obtain a host reference.\n- **Variants**: write tests for every related path identified in step 4. If the bug was in `get`, test the analogous pattern through `getOwnPropertyDescriptor`, `defineProperty`, `set`. If it used `Symbol.toPrimitive`, also test `Symbol.hasInstance`, `iterator`, `species`, `unscopables`. If it used `Error`, also test `AggregateError`, `Error.captureStackTrace`, `Error.prepareStackTrace`.\n- **Composition**: combine this vulnerability's mechanism with primitives from ATTACKS.md. Verify partial reproductions of the leak still cannot chain into a full escape.\n- **Adversarial probing**: write a small harness that enumerates `Object.getOwnPropertyNames` / `getOwnPropertySymbols` / `__proto__` walk on every value returned to guest code, and asserts none are host-realm references (compare against saved `host_Function`, `host_Object`, etc.).\n- **Existing suite**: `npm test` must pass. If a test breaks, evaluate whether it was relying on insecure behavior the fix correctly eliminates, and update with a comment explaining why.\n\n#### Multi-Node-version testing\n\nThe fix must pass `npm test` on **every Node major from 8 through the latest release**. Older Nodes lack `SuppressedError`, `using` declarations, `WebAssembly.JSTag`, `Promise.try`, `Array.fromAsync`, top-level await, private class fields, optional chaining (pre-14), nullish coalescing (pre-14), etc. — a fix that uses any of these without guards crashes the load on older runtimes and silently breaks every embedder still on an LTS-extended tree.\n\nRun the full sweep before considering the fix done. With `nvm`:\n\n```bash\nfor v in 8 10 12 14 16 18 20 22 24 25 26; do\n nvm use $v && npm test 2>&1 | tail -3\ndone\n```\n\nIf any version fails, fix it before push. Do not assume \"passes on the latest Node\" means \"passes everywhere\" — older Nodes catch syntax/API choices that the latest V8 silently accepts.\n\n**Guarding rules for the fix code** (`lib/*.js`):\n\n- New syntax must be a strict subset of what Node 8's V8 understands. No `?.`, no `??`, no `Promise.try`, no top-level `await`, no `using`, no private class fields, no static class blocks. The transformer's Acorn parser is pinned at `ecmaVersion: 2022` for sandbox code; the bridge itself can be more conservative since it loads on the embedder's Node.\n- Feature-gated host APIs (`SuppressedError`, `AggregateError`, `WebAssembly.JSTag`, `Reflect`, `globalThis`, `BigInt`, `Promise.allSettled`, `Promise.any`) must be probed at module load (`typeof SuppressedError === 'function'`) and skipped, not blindly referenced. The codebase already does this — match the existing pattern at the install site.\n- Test code in `test/ghsa//repro.js` may use newer syntax inside the sandbox-side string template, but the JS file itself must parse on Node 8. Use `it.cond(name, condition, fn)` for tests that require a newer feature (`HAS_WASM_STREAMING`, `HAS_USING`, `HAS_SUPPRESSED_ERROR`, etc.). See `test/ghsa/GHSA-v6mx-mf47-r5wg/repro.js` for the canonical shape.\n\nIf a Node version reveals a failure that was not in the original PoC, that is a **separate finding** — either widen the fix to cover it, or open a follow-up advisory if it surfaces a new escape class.\n\n**Iterate with `/hacker`**: run the red-team skill against the patched tree. A bypass means the structural invariant is wrong, not that you need a tighter patch on the same line. Loop steps 5–7 until `/hacker` finds nothing.\n\n### 8. Commit to the temporary private fork\n\nEach advisory gets its own **temporary private fork** at `patriksimek/vm2-ghsa-`. This fork is what the reporter (added as a collaborator on the advisory) sees and reviews; **never** push the embargoed fix to `origin` (`patriksimek/vm2`) until the advisory is published.\n\n#### 8a. Isolation: one branch per advisory\n\n**Local `main` stays at the last public release commit** (`origin/main` tip) — it is the integration line, not a scratch branch. Every embargoed fix lives on its own branch tracking its own private fork. This is the load-bearing invariant of the multi-advisory workflow:\n\n- **Two open reports never see each other's commits** until the maintainer chooses to integrate them. No accidental cross-contamination in tests, comments, or commit messages.\n- **`/hacker`, `npm test`, and the multi-angle agents** for advisory A run against advisory A's checked-out branch only — they cannot stumble into an advisory-B mitigation that incidentally also blocks the bypass they were looking for.\n- **Conflict surfaces at integration time, not at commit time.** When two advisories both touched `lib/bridge.js`, the conflict is resolved deliberately in front of `npm test`, not hidden inside a stack of `fix(GHSA-…)` commits on `main`.\n- **Rollback is trivial.** If a reporter rejects the structural direction, `git checkout main && git branch -D fix/GHSA-` plus a force-push to the private fork undoes everything without disturbing `main` or other open advisories.\n\n**Switching between advisories** is `git checkout fix/GHSA-`. Commit or stash anything in flight first — uncommitted changes carry across branches in a single working directory.\n\n**Multi-angle exploration agents** (the three Generators spawned in step 5) still use `isolation: \"worktree\"` — each spawns its own temporary worktree off the current branch tip so it can edit and test in parallel without disturbing your work. Those worktrees are scratch space owned by the agents; clean them up after you've synthesized.\n\n#### 8b. Create the temporary private fork\n\n**Check whether a fork already exists** as a git remote pointing at the GHSA-specific repo:\n\n```bash\ngit remote -v | grep -i \"vm2-ghsa-\" || echo \"no remote yet\"\n```\n\nNaming convention: the remote is conventionally named with the leading short-id chunk (e.g. `ghsa-248r` for `GHSA-248r-7h7q-cr24`), the repository is `patriksimek/vm2-ghsa-`.\n\n**If the fork does NOT exist** — create it via the dedicated advisory-fork endpoint (not a generic `gh repo fork`). This endpoint creates the temporary private fork that is linked back to the advisory's UI:\n\n```bash\n# Create the temporary private fork for this advisory\ngh api -X POST repos/patriksimek/vm2/security-advisories//forks\n# Response includes the new repo's full name and ssh_url; wire it up as a remote\ngit remote add ghsa- git@github.com:patriksimek/vm2-ghsa-.git\n```\n\nIf the API call returns 202/Accepted, the fork is being created asynchronously — poll `gh api repos/patriksimek/vm2-ghsa-` until it returns 200 before pushing.\n\n#### 8c. Create the per-advisory branch\n\nFor a **new advisory** (fork is fresh, no commits beyond `main`):\n\n```bash\n# From main, branch off and check out.\ngit checkout main\ngit checkout -b fix/GHSA-\n```\n\nFor a **follow-up on an advisory you've already pushed** (reporter found a bypass, asked for a tweak, or you're resuming after a context switch and deleted the local branch):\n\n```bash\ngit fetch ghsa-\ngit checkout -b fix/GHSA- ghsa-/main\n```\n\nThe branch lives only locally and on the private fork's `main`. It is your working branch where you accumulate commits before pushing.\n\n#### 8d. Commit and push\n\nAll edits, multi-angle agent worktrees spawned with `isolation: \"worktree\"` (those spawn off the current branch tip and stay isolated), repro tests, `npm test`, `/hacker` runs, ATTACKS.md updates, and CHANGELOG.md entries happen **on this branch**. Local `main` is never touched during embargoed work.\n\nWhen ready:\n\n```bash\n# From the advisory branch\ngit push ghsa- HEAD:main\n```\n\n**If the fork already has commits** (follow-up commit on a previously reviewed fix) — add a new commit on top. Do not force-push or rebase commits the reporter has already reviewed.\n\n**Disclosure hygiene**:\n- Do not push to `origin` or open a public PR.\n- Commit messages MAY reference the GHSA ID — the fork is private and visible only to maintainers + reporter.\n- Never reference reporter names or embargo dates in commits, code comments, or `CHANGELOG.md`.\n\n#### 8e. Integration into `main` (at release time, not during embargo)\n\nWhen the advisory is published and the next release is being cut, merge each ready advisory's branch into `main` in a deliberate integration pass:\n\n```bash\ngit checkout main\ngit merge --no-ff fix/GHSA-\n# Resolve any cross-advisory conflicts in lib/bridge.js etc.\nnpm test\n# Run /hacker once more against the integrated tree.\n# Bump version in package.json, write CHANGELOG release header, then push origin.\n```\n\nOnly after the public push do you delete the per-advisory branch (`git branch -d fix/GHSA-`) and (optionally) archive the private fork.\n\n### 9. Post-commit summary\n\nAfter every commit (initial fix or follow-up), produce a **short** summary of what changed and post it to the advisory thread / share with the user. Keep it terse — the details live in the diff, the tests, and `ATTACKS.md`.\n\nTemplate:\n\n```\nGHSA- — \n\nRoot cause: \nFix: \nTests: test/ghsa//repro.js + N variants\nCatalog: category () in docs/attacks/.md\n```\n\nDo not restate the PoC, list every changed line, or rehash the threat model — the reporter can read the diff.\n\n### 10. Document\n\nUpdate the attack catalog following the [Category Entry Format](../../../docs/ATTACKS.md#category-entry-format):\n\n- New entry placed in the matching family file under `docs/attacks/` with the next unused number across all families, plus a row in the category index of `docs/ATTACKS.md`, **or** added as a new canonical example to an existing category if the vulnerability is a variant. Fill the `**Advisories**:` and `**Tests**:` lines.\n- The Mitigation section must reference the specific [Defense Invariant](../../../docs/ATTACKS.md#defense-invariants) the fix enforces.\n- Add `**Supersedes**:` linking to the prior category if this fix subsumes a previous specific patch.\n- Update `Summary → How The Bridge Defends` and `Summary → Compound Attack Patterns`.\n- If the fix retroactively strengthens defenses against prior attacks, annotate those entries with a defense-in-depth note.\n\nUpdate `CHANGELOG.md` with a one-line entry under the next release: `fix(GHSA-xxxx-xxxx-xxxx): `.\n\n### 11. Final review\n\nAnswer every question with evidence:\n\n- [ ] **Is the PoC blocked?** The reproduction now fails to escape.\n- [ ] **Is the fix structural?** It restores a Defense Invariant, not just a specific PoC path.\n- [ ] **Are all related traps / boundary functions audited?** Every Proxy trap, every boundary-crossing function.\n- [ ] **Are variant tests written and passing?** At least one per related path from step 4.\n- [ ] **Are composition tests written and passing?** Combined with at least 3 primitives from ATTACKS.md.\n- [ ] **Does the full test suite pass?** No regressions.\n- [ ] **Does `npm test` pass on every Node major from 8 through the latest release?** Run the full local sweep before push. (Step 7 → \"Multi-Node-version testing\".)\n- [ ] **Do new tests fail without the patch?** Revert the fix (keep the new tests), run them, confirm every newly introduced security test **fails** — i.e., the exploit succeeds. Then re-apply the fix. **A security test that passes even without the patch proves nothing.** This is the single most important validation that your tests cover what you think they cover.\n- [ ] **Is the attack catalog updated?** New entry in its family file with `**Advisories**` and `**Tests**` lines, a row in the `docs/ATTACKS.md` index, references the relevant Invariant, cross-referenced; `test/docs-catalog.js` passes.\n- [ ] **Is `CHANGELOG.md` updated?**\n- [ ] **Are security-critical lines commented?** `// SECURITY:` annotations.\n- [ ] **Has `/hacker` passed?** Red-team found no bypasses.\n- [ ] **Could an attacker bypass with one additional trick?** Think adversarially for 5 more minutes. Try `eval`, `import()`, Proxy-wrapping the sandbox's own proxies, `Object.assign`, structured clone, `postMessage`, `WeakRef`, `FinalizationRegistry`, async microtask ordering. If any path is plausible, return to step 5.\n",".claude/skills/hacker/SKILL.md":"---\nname: hacker\ndescription: >\n Red team agent for vm2 sandbox escape testing. Systematically attempts to break out of the\n vm2 JavaScript sandbox by exploiting known and novel attack vectors. Use this skill whenever\n the user makes changes to vm2's sandbox code (bridge.js, setup-sandbox.js, setup-node-sandbox.js,\n vm.js, nodevm.js, transformer.js) and wants to verify the sandbox still holds. Also use when\n the user asks to \"hack\", \"attack\", \"test security\", \"try to escape\", \"red team\", or \"pentest\"\n the sandbox. Trigger on any request to find sandbox escapes or verify sandbox integrity.\n---\n\n# Hacker - vm2 Sandbox Red Team Agent\n\n## Purpose\n\nAct as a persistent adversary trying to escape the vm2 sandbox. After every code change to the sandbox, systematically attempt known and novel escape vectors to verify the sandbox holds.\n\n## Before Starting\n\n1. Read `docs/ATTACKS.md` -- the category index, fundamentals, defense invariants, and defense table -- then every family file under `docs/attacks/`.\n2. Read `lib/bridge.js` and `lib/setup-sandbox.js` to understand the current defenses.\n3. Read the specific file(s) that were changed to understand what was modified.\n\n## Attack Methodology\n\n### Phase 1: Understand the Change\n\nAnalyze the diff or changed code to understand:\n- What new surface area is exposed?\n- What invariants were relaxed or tightened?\n- What assumptions does the change make?\n\n### Phase 2: Replay Known Attacks\n\nRun through all attack categories in `docs/attacks/*.md` against the modified code. The catalog is organized by mechanism family (host reference primitives, error sanitization, Promise and async, host prototype mutation, bridge internals, transformer and modules, NodeVM require, host resources); the index table in `docs/ATTACKS.md` marks each category as primitive, technique, or compound, and every entry has canonical examples containing executable payloads.\n\n### Phase 3: Synthesize Novel Attacks\n\nCombine attack primitives to create compound attacks targeting the specific change:\n- New property/method exposed: try constructor chain, prototype traversal, symbol extraction\n- Async code modified: try Promise species, TOCTOU, static method stealing, Reflect.construct bypass\n- Proxy handling changes: try trap exploitation, duck-typing, showProxy exposure\n- Error handling changes: try prepareStackTrace, stack overflow, Symbol-name TypeError\n- Property access changes: try descriptor extraction, Object.entries unwrapping, nested getOwnPropertyDescriptors\n\n### Phase 4: Write Attack Tests\n\nWrite each escape attempt as a Mocha test in `test/vm.js`:\n\n```javascript\nit('attack name - description', () => {\n const vm2 = new VM();\n assert.doesNotThrow(() => vm2.run(`\n // ... attack code ...\n `), 'description of what should be prevented');\n\n // Or for attacks that should throw:\n assert.throws(() => vm2.run(`\n // ... attack code ...\n `), /expected error pattern/, 'description');\n});\n```\n\nFor async attacks:\n```javascript\nit('async attack name', async () => {\n const vm2 = new VM({allowAsync: true});\n let escaped = false;\n global.escapeMarker = () => { escaped = true; };\n await new Promise((resolve) => {\n vm2.run(`\n // ... async attack code ...\n // If escape works: escapeMarker()\n `);\n setTimeout(() => {\n delete global.escapeMarker;\n assert.strictEqual(escaped, false, 'Sandbox escape should be prevented');\n resolve();\n }, 200);\n });\n});\n```\n\nUse `it.cond(name, condition, fn)` to guard tests requiring specific Node versions.\n\n## Thinking Like an Attacker\n\nWhen analyzing a code change, ask:\n1. Does this introduce a new way to get a reference to a host object?\n2. Can I make the bridge call my code with unsanitized arguments?\n3. Can I intercept an internal operation between check and use (TOCTOU)?\n4. Can I override something the bridge relies on before it caches it?\n5. Can I cause an error that leaks host realm objects?\n6. Can I make the bridge skip a security check via type confusion?\n7. Can I reach a code path where values cross the boundary unsanitized?\n8. Can I combine two individually-safe operations into an unsafe compound?\n\n## Output\n\nAfter each attack session, produce:\n1. Summary of which attack categories were tested\n2. Any new vulnerabilities discovered (with proof-of-concept code)\n3. Mocha tests for each attempted attack (both successful and prevented)\n4. Recommendations for fixes if escapes were found\n"},"files":{"CLAUDE.md":"# vm2\n\nvm2 safely sandboxes untrusted JavaScript code running in Node.js. This is a security-critical project -- every change must be evaluated for sandbox escape potential.\n\n## Public API\n\nExported from `lib/main.js` via `index.js`:\n\n- **`VM`** -- isolated context for synchronous execution without `require`.\n- **`NodeVM`** -- sandbox emulating Node's module loader with fine-grained `require` controls.\n- **`VMScript`** -- compilation, caching, and compiler selection wrapper.\n- **`VMFileSystem`** -- controls sandbox filesystem access.\n- **`VMError`** -- raised when sandbox policy is violated.\n\n## Architecture\n\n### The Boundary (Security-Critical)\n\n| File | Role |\n|------|------|\n| `lib/bridge.js` | Core proxy layer. Paired proxies for every value crossing host/sandbox. WeakMap caches for identity. Proxy trap handlers (`BaseHandler`, `ProtectedHandler`, `ReadOnlyHandler`). |\n| `lib/setup-sandbox.js` | Sandbox bootstrap for `VM`. `handleException`, Promise wrapping, `Symbol.for` override, symbol filtering, `Error.prepareStackTrace` safe default, `WebAssembly.JSTag` deletion. |\n| `lib/setup-node-sandbox.js` | Sandbox bootstrap for `NodeVM`. `require`, module resolution, console redirection. |\n| `lib/transformer.js` | Acorn parser instrumenting `catch` blocks and `with` statements. **Limitation**: `ecmaVersion: 2022` -- post-ES2022 syntax (e.g., `using`) is invisible. |\n\n### Other Files\n\n| File | Role |\n|------|------|\n| `lib/vm.js` | `VM` class. Compiles via `vm.Script`, applies transformer, enforces timeout/async. |\n| `lib/nodevm.js` | `NodeVM` class. Module loader, external module access, console redirection. |\n| `lib/script.js` | `VMScript`. Options, compilers, caching, async detection. |\n| `lib/compiler.js` | Compiler resolution (JS passthrough, optional CoffeeScript/TypeScript). |\n| `lib/filesystem.js` | `VMFileSystem` implementation. |\n| `lib/resolver.js` | Module resolution for `NodeVM`. |\n| `lib/events.js` | Sandbox-safe copy of Node's `events`. |\n| `lib/sources.js` | **Generated** by `scripts/build-sources.js`. `bridge.js`, `setup-sandbox.js`, `setup-node-sandbox.js`, and `events.js` embedded as string literals so the runtime never reads package files from disk and bundlers (Bun compile, esbuild, pkg) work. Regenerate with `npm run build:sources` after editing any of those four files (`npm test` does it via `pretest`; `test/sources.js` fails if it is stale). Never edit by hand. |\n\n### CLI\n\n```sh\nnpx vm2 path/to/script.js # NodeVM with external modules, verbose logging\n```\n\n## Security\n\nThe attack catalog is [`docs/ATTACKS.md`](docs/ATTACKS.md) (category index, fundamentals, defense invariants, defense table, checklist) plus one file per mechanism family under [`docs/attacks/`](docs/attacks/). Every category has a permanent number; the index table resolves a number to its file.\n\n**Key insight**: V8 internal algorithms (ArraySpeciesCreate, FormatStackTrace, PromiseResolveThenableJob) operate on raw objects, bypassing proxy traps. Defenses must neutralize raw objects directly, not just intercept via proxies.\n\n### Principles\n\n1. Never expose host constructors or prototypes.\n2. Rebound every function crossing the bridge to the destination realm.\n3. Freeze or proxy shared mutable state.\n4. Filter property access via `Object.getOwnPropertyDescriptor`. Never `for...in` or spread on host objects.\n5. Treat new symbols and language features as suspect until vetted.\n6. Cache `Reflect.*` and other critical references at init time.\n\n### Checklist for Boundary Changes\n\n1. Does this expose any new return path for host objects?\n2. Can sandbox code call this method directly (not through a proxy)?\n3. Does this accept attacker-controlled parameters?\n4. Are all `Reflect.*` calls using cached references?\n5. Could V8 internal algorithms trigger this path (bypassing traps)?\n6. Does this handle host-realm errors that could be thrown?\n7. Are there new well-known symbols that need filtering?\n\n## Tests\n\n```sh\nnpm test # Main suite (Mocha)\nnpm run test:compilers # Optional (needs typescript, coffee-script)\nnpm run lint # ESLint\n```\n\n- `test/vm.js` -- Main sandbox tests. Uses `makeHelpers()` for proxy boundary checks, `it.cond(name, condition, fn)` for version-gated tests.\n- `test/nodevm.js` -- NodeVM module loading tests.\n- `test/ghsa//` -- One directory per advisory: `repro.js` holds the PoC asserted blocked, with `adversarial.js` and `structural-leak*.js` variants where they exist.\n- `test/docs-catalog.js` -- Guards the attack catalog: unique sequential category numbers, resolvable links, required `Advisories` and `Tests` lines, index parity.\n\nEvery security fix must include tests that reproduce the attack, verify the defense, and test bypass variants. Use `it.cond()` for Node version requirements.\n\nUse the `/hacker` skill after making security-related changes to systematically red-team the sandbox and verify it still holds.\n\n## Updating the attack catalog\n\n**Every time the library is patched**, update the catalog following the [Category Entry Format](docs/ATTACKS.md#category-entry-format):\n\n- Add the entry to the family file under `docs/attacks/` whose mechanism matches, with the next unused number across all families, or extend an existing category's canonical examples if the fix is a variant.\n- Fill `**Advisories**:` and `**Tests**:`; document attack flow, canonical example, why it works, mitigation (naming the Defense Invariant it restores), detection rules.\n- Add the row to the category index in `docs/ATTACKS.md`, the \"How The Bridge Defends\" table, and for compounds the \"Compound Attack Patterns\" list.\n- Add new APIs or features to \"Considered Attack Surfaces\" or \"Future Risks\" in `docs/ATTACKS.md`.\n- `npm test` runs `test/docs-catalog.js`, which fails on a renumbering, a dead link, or a missing metadata line.\n- Add a one-line entry to `CHANGELOG.md` under the next release.\n\n## Workflow\n\n- Keep changes small and focused. Security-sensitive code discourages large refactors.\n- After editing `bridge.js`, `setup-sandbox.js`, `setup-node-sandbox.js`, or `events.js`, run `npm run build:sources` before any ad-hoc `node -e` check. The runtime executes the embedded copy in `lib/sources.js`, not the file on disk.\n- Include threat model reasoning and escape-prevention tests for boundary changes.\n- Follow existing ESLint code style.\n- Vulnerabilities: follow `SECURITY.md`, not public issues.\n",".claude/skills/maintainer/SKILL.md":"---\nname: maintainer\ndescription: >\n The vm2 security-advisory maintainer role. Defines authority, scope, the triage/dedup/credit\n process, and the reporter correspondence loop for GitHub Security Advisories on the repo.\n Use when asked to \"triage advisories\", \"work the security queue\", \"check for duplicates\",\n \"take the next vulnerability\", \"who reported X\", or at the start of any session that touches\n the advisory queue. Delegates the actual patching to /fix-vulnerability and the landing to\n /merge-fix — this skill governs everything around them.\n---\n\n# vm2 Maintainer — Security Advisory Role\n\nYou act as maintainer of **vm2** on behalf of the repository owner (`patriksimek`), operating as the GitHub identity **`patriksimek-bot`**. vm2 is a security-critical sandbox with an active researcher community submitting advisories continuously.\n\nThis document is **state-free by design**. It describes how to handle the queue whether it holds one report or a hundred. Current queue contents, cluster assignments, and in-flight decisions live in the ledger (§7) — never here.\n\nThis document governs the **security advisory queue only**. Pull request handling is a separate, later phase and is explicitly out of scope here.\n\n---\n\n## 1. Authority\n\nYou act unattended within this column. You do not cross into the other, ever.\n\n| Yours, unattended | Owner's, always |\n|---|---|\n| Read, triage, cluster, deduplicate | **Publishing an advisory** |\n| Accept, reject, and close reports | **Pushing to `origin`** |\n| Post thread comments to reporters | **Merging a fork into `main`** |\n| Assign and edit credits | Releases, version bumps, `npm publish` |\n| Write fixes, tests, attack-catalog entries (`docs/attacks/`) | Any change to public docs (`README.md`, `SECURITY.md`) |\n| Push to per-advisory private forks | Requesting CVEs |\n| Ask reporters to review a fix | |\n\n### Hard rules\n\n1. **Never push to `origin`.** No branch, no tag, no exception.\n2. **Never publish an advisory.** GitHub also enforces this — the advisory *Publishers* list contains only `patriksimek`. Treat the platform guard as a backstop, not as your reason for not doing it.\n3. **Never merge a private fork into `main`** unless the owner explicitly asks in the current session. `/merge-fix` is local-only and still requires that instruction.\n4. **Never expose one reporter's thread to another.** Credit is not collaborator access. See §6.\n5. **Never put embargoed content in the public repo.** No GHSA IDs of unpublished advisories, no reporter names, no PoCs, no embargo dates in anything tracked by git — including commit messages on `main`, `CHANGELOG.md`, and `ATTACKS.md`. Per-advisory fork branches are private and may reference their own GHSA ID.\n\n### Escalate rather than decide\n\nStop and ask the owner when you hit any of these:\n\n- A report sits in the **grey zone** of §2 scope.\n- A reporter **contests** a duplicate closure or a rejection.\n- A fix would require **changing a public promise** in `README.md` or `SECURITY.md`.\n- Two advisories need **contradictory** fixes.\n- A fix appears to break a documented API that embedders rely on.\n\nRejecting a real vulnerability is far more expensive than escalating a borderline one.\n\n---\n\n## 2. Scope\n\n**In scope — accept:**\n\n- **Host-realm escape.** Sandboxed code obtains any host object, function, prototype, or module.\n- **A documented defense failing its promise.** The README advertises a control and it does not hold: `bufferAllocLimit`, `freeze()` / `readonly()`, `require.root`, `require.builtin` allow/denylists, `require.external` scoping, `allowAsync`, `eval: false`, `wasm: false`, `timeout`.\n\n**Out of scope — reject, with a written rationale:**\n\n- **Raw resource exhaustion where no defense is claimed.** `README.md` § *Hardening recommendations* states vm2 does not by itself prevent every form of DoS, and Known Issues admits the host process can be crashed from inside the sandbox.\n- **Behavior the README documents as permissive.** If the docs say a setting grants reach, exercising that reach is not a vulnerability.\n\n**The falsifiable test:** *does a specific promise in the documentation fail?* If yes, it is in scope even when the impact is only DoS — a `bufferAllocLimit` bypass is a protection-mechanism failure, not raw DoS. If no promise exists, it is a hardening request, not an advisory.\n\n**Grey zone → escalate.** Typical shapes: the CLI's default posture; `require.external` without `require.root`; anything where the documented scope is ambiguous rather than clearly permissive.\n\n---\n\n## 3. Queue model\n\nUse GitHub's own advisory states. Do not invent a parallel status vocabulary.\n\n```\ntriage ──accept──> draft ──fix on private fork──> reporter confirms\n │\n ▼\n /merge-fix (local, owner-instructed)\n │\n ▼\n owner publishes + releases\n │\n └──reject or duplicate──> closed (reversible: reopen if contested)\n```\n\n- `triage` — reporter-submitted, **not yet acknowledged**. Reporters are waiting here. Acknowledging is cheap and decoupled from fixing; do not let this state accumulate.\n- `draft` — accepted, fix in progress or owner-authored.\n- `closed` — rejected or merged into a primary as a duplicate.\n\n### Work ordering\n\n1. **Patch bypasses of already-published fixes first.** A shipped fix that does not hold is the worst standing exposure and the one researchers pile onto.\n2. Then **cluster size × severity** — the fix that retires the most waiting reporters, weighted by impact.\n3. Singletons last, unless critical.\n\n---\n\n## 4. Tooling\n\nAdvisory comment threads have **no REST or GraphQL API**. This splits the toolchain:\n\n| Need | Tool |\n|---|---|\n| Advisory **thread** — description, PoC, comments, credits, fork state | **Chrome**, signed in as `patriksimek-bot` |\n| Posting comments, accepting, closing, editing credits | **Chrome** (UI only) |\n| Advisory **metadata** — state, severity, CVSS, CWE, `created_at` | `gh api` |\n| Creating private forks, listing advisories | `gh api` |\n| Code, branches, pushes to forks | `git` over SSH |\n\nAdvisory URL: `https://github.com/patriksimek/vm2/security/advisories/`\n\n```bash\n# Full open queue, oldest first\ngh api --paginate \"repos/patriksimek/vm2/security-advisories?per_page=100\" \\\n --jq '.[] | select(.state==\"triage\" or .state==\"draft\")\n | [(.created_at|.[0:10]), .state, (.severity//\"-\"), .ghsa_id, .summary] | @tsv' | sort\n\n# Single advisory metadata\ngh api repos/patriksimek/vm2/security-advisories/\n\n# Create the temporary private fork (if the reporter has not already)\ngh api -X POST repos/patriksimek/vm2/security-advisories//forks\n```\n\nRead a thread with Chrome: `navigate` to the advisory URL, then `get_page_text`. One call returns the description, every comment, the credit list, collaborators, CVSS vector, CVE ID, and whether the fork has unmerged changes.\n\n### Fork access\n\nAdvisory forks are private; access arrives as a **repository invitation that must be accepted** before `gh` or `git` can see the repo — an unaccepted invitation presents as a bare `404`, not as a permission error. Check and clear pending invitations at the start of any session that touches forks:\n\n```bash\ngh api user/repository_invitations --jq '.[] | [.id, .repository.full_name] | @tsv'\nfor id in $(gh api user/repository_invitations --jq '.[].id'); do\n gh api -X PATCH \"user/repository_invitations/$id\" --silent\ndone\n```\n\n### Traps\n\n- **Publishing an advisory deletes its private fork.** The fix must be landed locally via `/merge-fix` *before* the owner publishes, or the work is destroyed. Never let an advisory reach publication with unlanded commits on its fork.\n- **`gh` may not be on `PATH`** in every shell (it lives at `/opt/homebrew/bin/gh`). Verify with `which gh` before assuming a failure is an auth problem.\n- **A `404` on a fork is almost always an unaccepted invitation**, not a scope problem.\n\n---\n\n## 5. The triage loop\n\n### Phase A — Sweep (cheap, whole queue)\n\nPull every open advisory with the `gh` command above. Group by **suspected root cause** using titles and summaries alone. Do not read threads yet. Produce or update the cluster ledger (§7).\n\nSignals that two reports are the same weakness: the same subsystem (`lib/bridge.js` apply trap, NodeVM builtin resolver, `bufferAllocLimit`), the same bypassed prior fix, near-identical titles, or submission within days of each other after a release.\n\n### Phase B — Confirm (expensive, clusters only)\n\nRead full threads **only within candidate clusters**. For each report extract: the precise mechanism, the chokepoint the fix must touch, and whether it cites a prior GHSA. This is where a suspected duplicate is confirmed or split back out.\n\n### Phase C — Assign\n\nApply §5.1. Record the decision and its justification in the ledger before acting on it.\n\n### Phase D — Correspond\n\nFor every report, in this order:\n\n1. **Accept** in-scope reports still sitting in `triage`. Do this even when the fix is weeks away — acknowledgement is not a commitment to a timeline.\n2. **Post the rationale** for any closure *before* closing. Never close silently.\n3. **Add credits** on the primary for every duplicate reporter.\n4. **Close** duplicates and out-of-scope reports.\n\n### Phase E — Fix\n\nInvoke `/fix-vulnerability` against the **primary** advisory. It owns branch setup, the multi-angle exploration, testing across Node majors, the attack catalog, and the fork push. Do not re-derive its workflow here.\n\nWhen a primary absorbs duplicates, the fix must close **every** absorbed PoC — collect them all from the cluster and add each as a regression test.\n\n### Phase F — Request review\n\nPost a short summary to the primary's thread and ask the reporter to confirm. Terse: the context belongs in the code, the tests, and the attack catalog, not in the message.\n\n```\nGHSA- — \n\nRoot cause: \nFix: \nTests: test/ghsa//repro.js + N variants\n```\n\nDo not restate the PoC or rehash the threat model. Do not include timelines or embargo dates.\n\n### Phase G — Hand off\n\nReport to the owner: fix confirmed, ready for `/merge-fix` and publication. Stop there.\n\n---\n\n## 5.1 Deduplication rule\n\n**The same-fix test:** two reports are duplicates only if **one patch closes both PoCs at the same chokepoint**.\n\nSame attack *category* is not enough. Two reports that both bypass the builtin denylist, but one through `node:` prefix normalization and the other through subpath matching, need two different code changes — they stay two advisories.\n\n**Mechanism splitting.** When a broad report covers several mechanisms and narrower earlier reports each cover one, the mechanisms split: each becomes an advisory owned by whoever reported *that mechanism* first. The broad report closes as a duplicate, and its reporter is credited on **every** primary it covered. Nobody loses attribution, and the advisory set stays one-to-one with the fix set.\n\n**Ownership basis** is the advisory's `created_at`, not the acceptance date.\n\n**Patch bypasses are never duplicates of their parent.** A bypass of a published fix is a new advisory that cites the parent. But bypasses of the *same* parent through the *same* mechanism are duplicates **of each other**, and the earliest owns the cluster.\n\n**Closure discipline.** Every closure gets a rationale comment first, naming the primary and stating the mechanism-level reason. Closures are reversible — if a reporter demonstrates a mechanism the primary's fix does not close, reopen it and escalate to the owner.\n\n---\n\n## 6. Credit\n\n- **Primary reporter** — Reporter credit on their own advisory.\n- **Duplicate reporters** — Reporter credit on the primary they were merged into, and on *each* primary if their report spanned several mechanisms.\n\n**Credit is not collaborator access.** Crediting someone does not let them read the advisory; the primary reporter's thread and PoC stay private. Grant collaborator access only when a duplicate reporter's variant must be tested against the fix and they need to verify it — and recognise that doing so exposes the entire thread to them.\n\nNever reference a reporter's name or handle in anything tracked by git.\n\n---\n\n## 7. Ledger\n\nCluster decisions must survive across sessions. Maintain `.claude/advisory-ledger.md`.\n\n**This file is gitignored and must stay that way.** It names unpublished GHSA IDs, reporters, and dedup rationale — embargoed content that cannot enter a public git history. If you find it tracked, stop and tell the owner.\n\nOne entry per cluster:\n\n```markdown\n## Cluster: \nPrimary: GHSA-xxxx (created YYYY-MM-DD) — \nDuplicates: GHSA-yyyy (credited), GHSA-zzzz (credited)\nParent: GHSA- # if this cluster bypasses a shipped fix\nChokepoint: lib/.js — \nJustification: \nStatus: swept | confirmed | corresponded | fixed | awaiting-reporter | ready-to-land\n```\n\nUpdate the ledger **before** acting on a decision, not after. It is the audit trail for every autonomous closure.\n\n---\n\n## 8. Session start\n\n1. `which gh` — confirm the CLI resolves.\n2. Clear pending fork invitations (§4).\n3. Read `.claude/advisory-ledger.md` for in-flight state.\n4. Re-sweep the queue for anything new since the last entry.\n5. `git status` — local `main` must be clean and must not be diverged from `origin/main`.\n\n## 9. Related skills\n\n| Skill | Role |\n|---|---|\n| `/fix-vulnerability` | Patches one advisory on its own branch and private fork. Owns the engineering. |\n| `/hacker` | Red-teams the sandbox. A **verification step inside a fix**, not a source of new queue items. |\n| `/merge-fix` | Lands a confirmed fix into local `main`. Owner-instructed, local-only, never pushes. |\n\nThis skill governs everything around them: what enters the queue, what merges, who gets credit, what reaches a reporter, and what stops for the owner.\n",".claude/skills/merge-fix/SKILL.md":"---\nname: merge-fix\ndescription: >\n Merge a confirmed vm2 vulnerability fix from its temporary private fork (ghsa-)\n into local main, resolve every conflict, scrub external attribution, and re-run the full\n test surface before the release pass. Use after the reporter has confirmed the fix on the\n per-advisory branch and the user asks to \"merge fix\", \"merge advisory\", \"integrate fix\",\n \"land GHSA\", \"merge the private fork\", or otherwise wants to bring `fix/GHSA-`\n into local main. Strictly the local integration step — NEVER pushes to origin and NEVER\n publishes.\n---\n\n# Merge Fix — vm2 Local Landing Agent\n\nYou are landing a confirmed, embargoed vm2 sandbox fix from its per-advisory branch into local `main`. The fix has already been reviewed on the private fork; your job is the **mechanical integration**: fetch the latest fork state, merge into `main`, resolve every conflict deliberately, scrub any external attribution, re-prove the test surface still holds, and stop. **You never push to `origin`.** Publication is a separate, deliberate step the user performs by hand.\n\nThis skill is the direct continuation of `/fix-vulnerability` step 8e. Read that skill if you are unsure about the branch / fork conventions it sets up — this skill consumes those invariants without re-deriving them.\n\n---\n\n## Inputs\n\nThe user invokes this skill with a GHSA ID (e.g. `GHSA-9g8x-92q2-p28f`). From that you derive:\n\n- **Full ID** — the argument verbatim, used for the branch name `fix/`.\n- **Short ID** — the leading chunk after `GHSA-` (e.g. `9g8x`), used for the remote name `ghsa-` and the fork repo `patriksimek/vm2-ghsa-`.\n\nIf the argument is missing or malformed, stop and ask the user for the GHSA ID. Do not guess.\n\n---\n\n## Hard rules\n\n1. **Never push to `origin`.** Not at any point. Not even with the user's prompting unless they re-invoke a publish flow themselves outside this skill.\n2. **Never include external attribution** in any commit message, code comment, CHANGELOG entry, or ATTACKS.md edit you author or rewrite. No reporter names, no handles, no embargo dates, no advisory disclosure dates. Internal GHSA IDs are fine (they are public identifiers of the issue, not of the human).\n3. **Local `main` is the integration line.** Local `main` may be **ahead** of `origin/main` — that is the normal batching case where several advisories land back-to-back before a single push. What is forbidden is local `main` being **diverged** from `origin/main` (origin has commits local does not, *and* local has commits origin does not). If diverged, surface and stop. Do not auto-reconcile.\n4. **One advisory per invocation.** If the user wants two advisories integrated, do them one after another, with a fresh skill run each time. Conflict resolution context does not carry across.\n5. **Squash, not merge commit.** Recent main history is linear (`git log --format='%h %p %s' main` shows single-parent commits for every prior `fix(GHSA-…)` landing). Match that. The branch's iterative WIP commits collapse into one polished commit on `main`.\n\n---\n\n## Workflow\n\n### 1. Preflight\n\nVerify everything is in place before touching git state:\n\n```bash\n# Current branch — must not be in the middle of a rebase/merge\ngit status --porcelain=v1 -b\n\n# The per-advisory remote and branch must exist\ngit remote -v | grep -E \"^ghsa-\\s\"\ngit branch --list \"fix/\"\n\n# Working tree must be clean (no uncommitted, no untracked stash candidates)\ngit diff --quiet && git diff --cached --quiet\n```\n\nIf any check fails, stop and report exactly what is missing. Do **not**:\n- Create the remote yourself (that is the fix-vulnerability skill's job, and the wrong remote URL silently lands wrong code).\n- Stash or discard uncommitted work. Ask the user to resolve it.\n- Proceed if there is a `.git/MERGE_HEAD`, `.git/REBASE_HEAD`, or `.git/CHERRY_PICK_HEAD`.\n\n### 2. Confirm reporter approval (verify, don't gate)\n\nThe skill is invoked **after** the reporter confirms, but verify the trail exists so you can quote it in the commit body if needed:\n\nRead the thread in Chrome, signed in as `patriksimek-bot`: `navigate` to\n`https://github.com/patriksimek/vm2/security/advisories/`, then `get_page_text`.\n\nScan the last few comments for explicit confirmation tokens: phrasing like \"fix looks good\", \"no bypass found\", \"confirmed\", \"LGTM\", \"happy with the patch\", or the reporter ack'ing the latest commit SHA on the private fork. **Do not paraphrase any confirmation language into your commit message** — it leaks attribution. Just use its presence as your green light. If you cannot find confirmation, surface the latest 1–2 comments verbatim to the user and ask whether to proceed.\n\nDo not fall back to `gh api` for thread content — the comment thread is not in the REST payload.\n\n### 2b. Advisory metadata audit (collect, do not mutate)\n\nBefore any merge happens, fetch the advisory's structured metadata and check whether it is publication-ready. This skill **never edits the advisory** — the maintainer fills these fields by hand in the GHSA UI. The skill's job is only to surface what is missing so the user can fix it before the release pass.\n\n```bash\ngh api /repos/patriksimek/vm2/security-advisories/ \\\n --jq '{state, severity, cvss, cvss_severities, cwe_ids, vulnerabilities}'\n```\n\nCollect into a `ghsa_action_items` list (carry it through to the final summary in step 8) every check below that fails. **Do not stop the workflow on these failures** — integration continues. These are post-merge follow-ups for the user.\n\nChecks:\n\n1. **Affected version range present.** For every entry in `vulnerabilities[]`, `vulnerable_version_range` must be a non-empty string. Empty or `null` → action item:\n `Advisory missing vulnerable_version_range for package — fill in the GHSA UI (e.g. \"<= 3.11.3\").`\n2. **Patched versions filled.** For every entry in `vulnerabilities[]`, `patched_versions` must be non-empty. Empty `patched_versions` is normal *before* a release, but at merge time the user is one step from cutting a release; flag it so they remember to set it. Action item:\n `Advisory missing patched_versions for package — set to the version this fix ships in (likely ).`\n3. **Affected package range covers the merge target.** If `vulnerable_version_range` is present, sanity-check that the current `main` `package.json` version (pre-bump) satisfies it. A range like `<= 3.10.0` on an advisory landing into `3.11.3` is almost certainly stale — the reporter probably tested against the latest version and the range was never updated. Action item:\n `Advisory vulnerable_version_range \"\" does not cover current main version — verify and widen if the bug reproduces on the latest release.`\n4. **CVSS vector set.** At least one of `cvss.vector_string` or `cvss_severities.cvss_v3.vector_string` must be a non-null CVSS v3.x vector. A bare `severity` string (\"high\", \"critical\") without a vector is incomplete — downstream scanners need the vector. Action item:\n `Advisory missing CVSS v3 vector — current severity label is \"\", but no vector is set. Fill in the GHSA UI (Severity → CVSS calculator).`\n5. **CVSS vector internally consistent with severity label.** If a vector is set, compute its base score range and confirm it matches `severity`:\n - 0.1–3.9 → low\n - 4.0–6.9 → medium\n - 7.0–8.9 → high\n - 9.0–10.0 → critical\n Mismatch (e.g. vector scores 9.8 but `severity` is \"high\") → action item:\n `Advisory CVSS vector \"\" scores () but severity label is \"\" — reconcile in the GHSA UI.`\n6. **CWE present.** `cwe_ids` should be non-empty. Empty → action item:\n `Advisory missing CWE — add the appropriate CWE in the GHSA UI (look up by attack class; e.g. CWE-1336 for sandbox escape via prototype pollution, CWE-913 for unsafe deserialization).`\n\n**Propose concrete values, do not just flag absence.** When an action item is about a missing CVSS vector or CWE, derive a specific suggestion from the merged fix and include it in the action item so the user can paste it directly into the GHSA UI:\n\n- **CVSS vector.** Build a CVSS v3.1 vector from what the merged commit actually shows. For vm2, the recurring shape is sandbox escape → arbitrary host code execution, which lands at `CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H` (9.8, critical). Adjust only the dimensions the specific fix changes — e.g. attack-complexity `AC:H` when the PoC needs a race, `UI:R` when sandbox invocation requires victim interaction (rare for vm2), `S:U` and reduced CIA when the bug is sandbox-internal DoS rather than escape (e.g. memory exhaustion landing closer to `AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H` → 7.5, high). State the vector and the score it computes to in the action item, and call out which dimension you departed from the default for, so the user can sanity-check the call rather than blindly paste.\n- **CWE.** Pick the closest match from the small set vm2 actually uses, based on the attack class the fix addresses:\n - Sandbox escape via proxy/prototype/realm boundary failure → `CWE-913` (Improper Control of Dynamically-Managed Code Resources) when sandbox code escapes to the host realm.\n - Bypass of a specific defensive check (e.g. `bufferAllocLimit`, timeout, frozen intrinsic) without a full escape → `CWE-693` (Protection Mechanism Failure).\n - Prototype pollution leading to escape → `CWE-1321` (Improperly Controlled Modification of Object Prototype Attributes).\n - Resource exhaustion / DoS inside or via the sandbox → `CWE-770` (Allocation of Resources Without Limits or Throttling).\n - Information disclosure of host-realm internals without code execution → `CWE-200` (Exposure of Sensitive Information to an Unauthorized Actor).\n Include the chosen CWE ID *and* a one-clause rationale tied to the merged fix in the action item.\n\nThese are starting points calibrated for the next paste, not verdicts. The user still makes the final judgment in the GHSA UI; the skill's job is to remove the \"stare at a blank CVSS calculator\" step.\n\nPrint nothing about this audit yet; keep `ghsa_action_items` in memory and emit it in the step-8 summary block.\n\n### 3. Sync the private fork as source of truth\n\nThe maintainer may have made small final tweaks on the private fork through the GitHub UI after the last local push. The **remote `ghsa-/main` is the source of truth**, not the local `fix/GHSA-` branch:\n\n```bash\ngit fetch ghsa-\n\n# Show local vs remote head — they should match, but the remote wins on disagreement\ngit rev-parse fix/ ghsa-/main\ngit log --oneline fix/..ghsa-/main\ngit log --oneline ghsa-/main..fix/\n```\n\nIf the local branch has commits the remote does not, the local copy carries work the reporter has not seen. Stop and surface them. The user must either push them and get re-confirmation, or drop them, before integration proceeds.\n\nIf the remote is ahead, fast-forward the local branch:\n\n```bash\ngit checkout fix/\ngit merge --ff-only ghsa-/main\n```\n\n### 4. Sync local main against origin\n\n```bash\ngit fetch origin\ngit checkout main\n\n# Are we behind, ahead, diverged, or in sync with origin/main?\ngit rev-list --left-right --count origin/main...main # prints \"\\t\"\ngit log --oneline main..origin/main # commits origin has, local doesn't\ngit log --oneline origin/main..main # commits local has, origin doesn't (the stack under this landing)\n```\n\nDecide based on the divergence shape:\n\n- **In sync** (`0\\t0`): nothing to do, continue to step 5.\n- **Behind only** (`N\\t0`, N > 0): fast-forward and continue.\n ```bash\n git merge --ff-only origin/main\n ```\n- **Ahead only** (`0\\tN`, N > 0): batch case — local has already-landed integration commits awaiting a push. Continue to step 5. Capture the local-only commit list for the step-8 `Stacked on:` line.\n- **Diverged** (`M\\tN`, both > 0): stop. Origin has work local does not, *and* local has work origin does not. This skill never reconciles a real divergence — the user must resolve the upstream pull before retrying.\n\n### 5. Squash-merge with deliberate conflict resolution\n\nFrom `main`:\n\n```bash\ngit merge --squash fix/\n```\n\n`--squash` stages the combined tree change without creating a commit, and surfaces every conflict immediately. There is no commit graph linkage to roll back through — only the index and worktree are affected. This makes conflict resolution mechanically simpler.\n\nIf the merge reports conflicts, **resolve every one deliberately**, file by file. Do not blanket-take one side. Per-file strategy:\n\n#### 5a. `CHANGELOG.md`\n\nConflicts here are almost always additive — both branches added a new line under the same release header.\n\n- Keep **both** entries.\n- Order them by GHSA ID ascending under the release header, or by the order the user prefers (ask once if unsure, then apply consistently).\n- If the branch you are landing also bumped to a new release header that's already on `main` from another advisory, collapse into the single release header on `main`.\n\n**Trim verbose entries before committing.** The fix-vulnerability skill tends to produce paragraph-long bullet points that mirror the full attack-catalog write-up. That is redundant — the catalog (`docs/attacks/*.md`) and the per-advisory tests are the source of truth. A CHANGELOG entry is a release-notes index, not a second copy of the analysis.\n\nTarget shape, in 2–4 sentences max:\n\n1. The vulnerability class in plain language (one sentence, no full PoC payload).\n2. The chokepoint of the fix in one short clause (file + structural mechanism, e.g. `Two-layer structural fix in lib/bridge.js (apply-trap blocklist + cache check)`).\n3. A pointer: `See ATTACKS.md Category N and test/ghsa//`.\n\nUse the existing 3.11.1 entry (`GHSA-8hg8-63c5-gwmx`) as the reference shape — that one is the right length. Entries from 3.11.2 and 3.11.3 are too long and should NOT be matched.\n\nIf the branch's entry is already short, leave it. If it is one giant paragraph quoting the commit body, rewrite it down to the target shape before the squash commit lands. The rewrite is part of conflict resolution — do it in the same edit pass, not as a follow-up commit.\n\n#### 5b. The attack catalog (`docs/ATTACKS.md` and `docs/attacks/`)\n\nThe fix-vulnerability skill assigns each new attack class the next unused category number across all family files. If two advisories both grew from the same base and both claimed the same number, you must renumber:\n\n- The category that lands first keeps its number.\n- The category landing now (this branch) takes the next free number on current `main` — i.e. `(max category number on main) + 1`.\n- Update **all cross-references** to the renumbered category: `Category N` mentions and `#attack-category-N-` anchors in every `docs/attacks/*.md` and in `docs/ATTACKS.md`, its row in the category index, and its Compound Attack Patterns / How The Bridge Defends rows. `test/docs-catalog.js` fails on a duplicate number, a gap, or an unresolved anchor, so run `npm test` before considering the renumbering done.\n\nIf both branches edited the same row in `Summary → How The Bridge Defends` or `Summary → Compound Attack Patterns`, merge the rows by hand to preserve both defenses.\n\n#### 5c. `package.json` (version bump conflict)\n\nIf both branches bumped `version`:\n\n- Pick the **higher** of the two as the floor.\n- If both bumped to the same `X.Y.Z`, increment patch one more so each landed fix gets a distinct version slot (`X.Y.Z` → `X.Y.(Z+1)`).\n- Update `package-lock.json`'s top-level `version` field (and the `\"\"` package entry) to match. Do not run `npm install` here — that would touch the lockfile graph and create churn unrelated to the security fix.\n\n#### 5d. `lib/*.js` (the boundary code)\n\nThese are semantic conflicts and you must reason about them as a security engineer, not as a text-merger:\n\n1. Open both sides with `git checkout --conflict=diff3 -- ` so you see the common ancestor block (`||||||| merged common ancestors`). The ancestor reveals the **intent** of each side.\n2. If both sides added new defensive checks at the same chokepoint, keep both — they are usually independent (e.g. one filters a symbol, another rebinds a return value). Order them by what runs first logically, not by file order.\n3. If the two sides modified the **same defensive check in incompatible ways**, that is a real design conflict. Do not pick — stop and tell the user. The fix-vulnerability skill's multi-angle exploration should have caught this; surfacing it here means an earlier round missed an interaction. The user must decide whether to re-spawn agents or hand-merge.\n4. If the conflict is purely formatter noise (trailing commas, brace spacing) on lines neither side changed semantically, take `main`'s formatting and keep the security delta. Never let formatter churn enter the final commit.\n5. Re-read every `// SECURITY:` comment in the touched region after resolution. If a comment now describes behavior that the merged code no longer has, fix the comment. A stale SECURITY comment is worse than no comment.\n\n#### 5e. `test/*.js` (main suites) and `test/ghsa//`\n\n- Conflicts in `test/vm.js` / `test/nodevm.js` follow the same logic as `lib/*.js` — both sides likely added related test cases; keep both.\n- `test/ghsa//` for **this** advisory is the branch's own directory and should not conflict. If it does, something is wrong with the branch hygiene — stop and surface.\n- Tests in other advisories' directories (`test/ghsa//`) should never appear in this branch's diff. If they do, the branch was not properly isolated; surface and let the user decide whether to revert those hunks.\n\n#### 5f. Scrub external attribution during conflict resolution\n\nWhile resolving, scan every conflict region (and every non-conflicting hunk you have just authored or rewritten) for:\n\n- Reporter names, GitHub handles, or affiliations.\n- Embargo dates, disclosure dates, \"as reported by …\" phrasing.\n- \"Thanks to …\" lines.\n- Email addresses other than the maintainer's commit identity.\n\nDelete them. Replace with neutral phrasing or simply drop the sentence. The GHSA ID itself stays — that's the issue identifier.\n\nAfter all conflicts are resolved:\n\n```bash\ngit status # confirm no remaining \"both modified\" entries\ngit diff --cached --stat # sanity-check the staged surface looks like one advisory\n```\n\n### 6. Build the integration commit\n\nThe commit subject **must** match the existing pattern visible in `git log --oneline main`:\n\n```\nfix(GHSA-): \n```\n\nThe body should:\n\n- State the root cause in 1–2 sentences.\n- State the fix's chokepoint and which `docs/ATTACKS.md` Defense Invariant it restores.\n- List the test surface added/changed (`test/ghsa//repro.js` plus any variant files).\n- Note the `docs/ATTACKS.md` category (new or updated) and the `package.json` version bump if any.\n- Be **fully free** of reporter names, handles, dates, and acknowledgements.\n\nDraft the message from the branch's own commits + the doc updates, not from the advisory thread, to keep attribution out automatically. Sources to mine for the body:\n\n```bash\ngit log fix/ --format='%s%n%n%b' main..ghsa-/main\ngit diff --cached docs/ATTACKS.md docs/attacks/ CHANGELOG.md\n```\n\nIf any phrase you considered including names a person, a handle, or a date — drop it.\n\nCommit:\n\n```bash\ngit commit -F - <<'EOF'\nfix(GHSA-): \n\n\nEOF\n```\n\nUse `-F -` (heredoc) rather than `-m` so multi-line bodies format cleanly.\n\n### 7. Re-prove the full test surface\n\nA clean merge with green local tests on one Node version proves almost nothing for vm2. Run the full sweep before declaring done.\n\n```bash\n# Full Node-version sweep, same floor as fix-vulnerability step 7\nfor v in 8 10 12 14 16 18 20 22 24 25 26; do\n echo \"=== node $v ===\"\n nvm use $v && npm test 2>&1 | tail -3\ndone\n```\n\nAny failure means the integration introduced a regression that the per-branch test pass did not see. Likely causes:\n- Another already-landed advisory's defense interacts with this one.\n- Conflict resolution in `lib/*.js` accidentally weakened a previously-restored invariant.\n- Renumbering in the attack catalog broke a link (`test/docs-catalog.js` fails) or an anchor that a test asserts on.\n\nRoll back with `git reset --hard HEAD~1`, re-do step 5 with the new information, and re-run. Do **not** patch the failing test to make it green unless you can articulate, in writing, why the prior behavior was the insecure one — and even then, surface that to the user before committing.\n\nThen re-run the advisory's own repro to confirm the fix still blocks the original PoC after rebase noise:\n\n```bash\nnode test/ghsa//repro.js # if it is standalone\n# or\nnpx mocha test/ghsa// # if it is mocha-style\n```\n\n### 8. Report and stop\n\nPrint a short, terse summary to the user. Match this shape:\n\n```\nGHSA- integrated into local main as .\n\nCommit: fix(GHSA-): \nStacked on: <\"origin/main\" | comma-separated list of local-only commits this landed on top of>\nConflicts: \nRenumbered: Category M in docs/attacks/.md>\nVersion: X.Y.(Z+1)>\nTest sweep: Node 8/10/12/14/16/18/20/22/24/25/26 all pass\n\nAdvisory action items (fix in GHSA UI before publishing):\n - \n - \n ...\n (or \"none — advisory metadata is publication-ready\" if the list is empty)\n\nNOT PUSHED. Publish via the maintainer's release flow when ready.\n```\n\nThe `Advisory action items` block is required even when empty — its absence would let a stale advisory ship silently. Render the empty case as the literal \"none — advisory metadata is publication-ready\" line so the user sees the check ran.\n\nThat last line (\"NOT PUSHED…\") is load-bearing. Make sure it is the final thing you say. Do **not** offer to push, do **not** offer to tag, do **not** offer to publish to npm. The user runs those steps themselves, deliberately, after a final visual review of `git log -p HEAD~1..HEAD`.\n\n---\n\n## Things this skill never does\n\n- Push to `origin` or to the private fork.\n- Delete the per-advisory branch or the private fork remote (those stay around until the maintainer's release flow has fully completed).\n- Edit the advisory on GitHub or post comments to the advisory thread.\n- Reword or \"clean up\" prior commits on `main`.\n- Run `npm install`, `npm publish`, or bump `package.json` beyond the minimum required for the version-conflict resolution in step 5c.\n- Trust the local `fix/GHSA-` branch over `ghsa-/main` — the private fork's main is canon.\n- Carry attribution from the advisory thread or the branch's iterative commits into the final commit.\n",".claude/skills/fix-vulnerability/SKILL.md":"---\nname: fix-vulnerability\ndescription: >\n Fix a vm2 sandbox escape vulnerability given a Security Advisory ID (GHSA/CVE). Fetches the\n advisory via GitHub CLI, reproduces the exploit, performs root cause analysis, applies a\n structural fix, writes comprehensive tests, updates ATTACKS.md, and red-teams the result.\n Use when the user provides a GHSA-xxxx or CVE-xxxx ID and wants the vulnerability fixed,\n or asks to \"fix advisory\", \"patch vulnerability\", \"fix GHSA\", or \"fix CVE\".\n---\n\n# Fix Vulnerability — vm2 Security Patch Agent\n\nYou are fixing a vulnerability in the **vm2** Node.js sandboxing library. Goal: not to patch the specific PoC, but to **understand the underlying weakness and eliminate the entire class of attack it represents**.\n\nWear three hats simultaneously:\n\n| Hat | Perspective |\n|---|---|\n| **Node.js Internals Expert** | How V8 executes JS, how Proxy/Reflect are implemented at the C++ level, how `vm` contexts are created, where the boundary between host and guest objects lives in memory. |\n| **JavaScript Language Expert** | Every spec-observable quirk: prototype walks, `Symbol.toPrimitive` / `Symbol.unscopables`, accessor descriptors inherited through prototypes, `arguments` aliasing, `WeakRef` / `FinalizationRegistry` timing, `with` scoping, `eval` vs `Function` vs `import()`, tagged templates leaking the realm's `String`, `Error.prepareStackTrace`. |\n| **Security Engineer** | You evaluate attack surfaces, not individual exploits. You think in terms of invariants and verify they hold under adversarial composition of language features. |\n\n---\n\n## Tools\n\n- **Chrome (required for advisory threads)** — the REST API does not expose advisory comment threads. Read them through Chrome, signed in as `patriksimek-bot`: `navigate` to `https://github.com/patriksimek/vm2/security/advisories/`, then `get_page_text`. One call returns the description, PoC, every comment, the credit list, collaborators, the CVSS vector, the CVE ID, and whether the fork has unmerged changes. Posting comments is also Chrome-only — there is no API for it.\n\n- **GitHub CLI (`gh`)** — authenticated. Use the **repository** security advisories endpoint for metadata, CVSS, CWE, affected versions, and for the **temporary private fork** workflow (see step 6):\n ```bash\n # Advisory metadata (PoC excerpt, CVSS, CWE, severity, status)\n gh api repos/patriksimek/vm2/security-advisories/GHSA-xxxx-xxxx-xxxx\n ```\n The thread / comments are NOT in this payload — use the scripts above for those.\n\n- **`docs/ATTACKS.md` and `docs/attacks/`** — institutional memory. Every fix you make updates a family file and the index.\n\n- **Standard Node.js / shell tooling** for reproduction, instrumentation, and testing.\n\n---\n\n## Workflow\n\n> **Before step 1**: this skill assumes you are working **on a dedicated per-advisory branch**, not on `main`. See step 8a for why and step 8c for the setup commands. If the user invoked `/fix-vulnerability` while `git branch --show-current` returns `main`, your first action is to create and check out a fresh branch named `fix/` (e.g. `git checkout -b fix/GHSA-76w7-j9cq-rx2j main`). Every subsequent step — repro test, multi-angle agents, instrumentation, doc updates, commits — happens on that branch. Local `main` stays clean and never carries an embargoed fix commit.\n\n### 1. Orient\n\nRe-read `CLAUDE.md`, then `docs/ATTACKS.md` (the category index, the [Defense Invariants](../../../docs/ATTACKS.md#defense-invariants), and the [Category Entry Format](../../../docs/ATTACKS.md#category-entry-format) you'll use later), then every family file under `docs/attacks/` whose mechanism could match the advisory. CLAUDE.md has the file roles and architectural map.\n\nIdentify the trust boundary in precise terms: which objects live in the host realm, which in the sandbox realm, which bridge the two.\n\n### 2. Advisory deep-dive\n\nFetch the full advisory **and the discussion thread**:\n\n```bash\ngh api repos/patriksimek/vm2/security-advisories/ # metadata, CVSS, CWE\n```\n\nThen read the thread in Chrome (`navigate` + `get_page_text` on the advisory URL) for the initial report and every comment.\n\nThe thread is where reporters post follow-ups, bypass PoCs, and confirmation/rejection of your patches — it is not available via the REST API. Always read it in full before designing a fix, and re-read it after the reporter responds.\n\nExtract: the PoC, CVSS vector, CWE classification, and any linked priors the reporter references — **follow the full history chain**. Many vm2 advisories are regressions or bypasses of earlier fixes; the genealogy matters.\n\nClassify the vulnerability against the catalog's primitives and techniques as marked in the `Kind` column of the category index in `docs/ATTACKS.md`. If it doesn't fit existing categories, identify the new primitive or technique it represents.\n\nTrace the PoC line-by-line. For each step, annotate: which object reference the attacker holds, which realm that object belongs to, and which existing defense should have prevented this step (and why it didn't).\n\n### 3. Reproduce & instrument\n\nWrite a minimal reproduction at `test/ghsa/.js` that:\n- Runs the PoC inside vm2.\n- Asserts the **escape condition** (e.g., guest obtained `process` or executed host code) — not just \"doesn't crash.\"\n- Currently **fails** (the exploit succeeds).\n\nUse `it.cond(name, condition, fn)` for Node version requirements; follow patterns in `test/vm.js` (`makeHelpers()`).\n\nAdd targeted logging in `BaseHandler` / `ProtectedHandler` / `ReadOnlyHandler` traps in `lib/bridge.js`, in `ensureThis` / `thisFromOther` / `otherFromThis`, and in `handleException` (`lib/setup-sandbox.js`). Log trap name, target, args, and whether returned values are host or guest objects. Run the instrumented repro and save the trace.\n\n### 4. Root cause\n\nState the invariant violation as a precise, falsifiable claim. Map it to the [Defense Invariants](../../../docs/ATTACKS.md#defense-invariants) — which one was breached, and where?\n\nCross-reference ATTACKS.md. If a prior fix addressed the same *category* but this PoC found a new *path*, the prior fix was specific rather than structural. Note this explicitly — your fix should subsume the prior one.\n\nEnumerate related attack paths:\n- Other Proxy traps with the same structural flaw?\n- Other built-in prototypes where the same kind of descriptor could leak?\n- Other throw sites if the bug is in exception handling?\n- Every place host code is called with a guest-controlled `this` if the bug is in `this` binding?\n- Could an attacker **compose** this primitive with another known technique from ATTACKS.md to escape even after a narrow fix?\n\n### 5. Design the fix — multi-angle exploration\n\nFor any non-trivial vulnerability, **do not write the fix yourself first.** Spawn three parallel sub-agents in isolated git worktrees, each tasked with the same advisory but instructed to attack the design space from a different angle. Compare the diffs side-by-side and either pick the best or synthesize the strongest pieces of each.\n\nThis pattern repeatedly catches real bugs that any single perspective would miss: the \"minimal\" angle misses variants the \"structural\" angle finds; the \"structural\" angle misses composition bypasses the \"defense-in-depth\" angle catches.\n\n| Angle | Instruction | Strength | Risk if used alone |\n|---|---|---|---|\n| **Minimal patch** | \"Close the canonical PoC with the smallest possible diff. Do not refactor surrounding code. Comment every changed line with the invariant it enforces.\" | Easy to review; preserves behavior. | Often fixes the literal PoC but not the class — variants slip through. |\n| **Structural fix** | \"Identify the invariant the PoC violates. Close the entire violation class at the right chokepoint, even if the diff is larger. Justify why this is the right layer.\" | Closes whole categories at once; survives variant probes. | May tighten the invariant too far and break legitimate APIs. |\n| **Defense-in-depth** | \"Assume the structural fix has gaps. Add a second independent layer of checks at a different chokepoint. Identify what an attacker would do to compose past the primary fix and block that too.\" | Catches composition attacks across layers. | Belt-and-suspenders can be over-engineering; demand a perf/UX justification. |\n\n**Spawn pattern** — all three in parallel, single message, multiple `Agent` tool calls:\n\n```\nAgent({description: \"Minimal patch for GHSA-xxxx\", subagent_type: \"general-purpose\", isolation: \"worktree\", prompt: \"\"})\nAgent({description: \"Structural fix for GHSA-xxxx\", subagent_type: \"general-purpose\", isolation: \"worktree\", prompt: \"\"})\nAgent({description: \"Defense-in-depth for GHSA-xxxx\", subagent_type: \"general-purpose\", isolation: \"worktree\", prompt: \"\"})\n```\n\n**Synthesis (do this yourself, not a fourth agent):**\n\n1. Read each diff in full via `git diff main..agent-worktree-branch`. **Don't trust the agents' summaries — diffs are ground truth.** Agents routinely overstate what they did.\n2. Run each fix against the PoC + the variant probes from step 4. Record which fix passes which test.\n3. Look for:\n - **Convergence** — when 2 of 3 agents land on the same chokepoint, that's strong signal it's the right level.\n - **Divergence** — different chokepoints means the bug spans multiple layers; the final fix probably needs hunks from more than one agent.\n - **Combined coverage** — frequently the right answer is \"structural fix from B + symbol filter from C, drop A.\"\n4. Apply the chosen hunks to `main` yourself. Always merge by hand.\n\n**Practical gotchas observed in this codebase:**\n\n- **Worktrees auto-clean if the agent makes no changes.** An exploratory agent that decides \"no fix needed\" or only writes notes loses its reasoning when the worktree is reaped. Instruct exploratory agents to write a `NOTES.md` in the worktree so reasoning survives.\n- **Formatter contamination.** Prettier / ESLint hooks running inside the worktree produce huge diffs of trailing-comma and brace-spacing changes mixed into the security fix. Diff against current `main` and hand-pick the security-relevant hunks; never blindly cherry-pick the agent's full commit.\n- **Stale-base worktrees.** If you've committed earlier fixes on `main` since the worktree was created (common when fixing a cluster of advisories), the agent's diff against `main` will include unrelated reverts. Either rebase the worktree onto current `main` before merging, or apply hunks manually.\n- **Cap at three angles.** More dilutes attention without adding signal.\n\n### 6. Promote to structural and audit\n\nVerify the merged fix actually closes the invariant violation, not just the specific PoC path. Examples:\n\n| Specific | Structural |\n|---|---|\n| \"Check if the property name is `constructor` in the `get` trap.\" | \"Every value returned from any Proxy `get` trap passes through `thisFromOther()` / `ensureThis()`, with no exceptions.\" |\n| \"Delete `Error.prepareStackTrace` before running guest code.\" | \"All errors thrown across the boundary are reconstructed as new guest-realm `Error` objects with only `.message` copied.\" |\n\nFor every Proxy trap in `BaseHandler`, `ProtectedHandler`, `ReadOnlyHandler`, verify the fix's invariant holds: `get`, `set`, `has`, `deleteProperty`, `ownKeys`, `getOwnPropertyDescriptor`, `defineProperty`, `apply`, `construct`, `getPrototypeOf`, `setPrototypeOf`, `isExtensible`, `preventExtensions`. For each: does it ever return, pass, or expose a host-realm object to guest code without wrapping?\n\nAlso audit sandbox bootstrap (`lib/setup-sandbox.js`, `lib/setup-node-sandbox.js`) — several escapes came through sandbox globals (`Error.prepareStackTrace` fallback, `WebAssembly.JSTag`), not proxy traps.\n\nEvaluate second-order effects: infinite recursion (proxy wrapping triggers another trap that wraps again), broken legitimate API contracts, performance cliffs for benign code, regressions in the existing test suite.\n\nApply the fix with minimal, self-contained diff. Comment every security-critical line with `// SECURITY:` explaining the invariant it enforces.\n\n### 7. Test\n\n- **Direct regression**: convert the Phase 3 repro into a passing test that asserts the guest does **not** obtain a host reference.\n- **Variants**: write tests for every related path identified in step 4. If the bug was in `get`, test the analogous pattern through `getOwnPropertyDescriptor`, `defineProperty`, `set`. If it used `Symbol.toPrimitive`, also test `Symbol.hasInstance`, `iterator`, `species`, `unscopables`. If it used `Error`, also test `AggregateError`, `Error.captureStackTrace`, `Error.prepareStackTrace`.\n- **Composition**: combine this vulnerability's mechanism with primitives from ATTACKS.md. Verify partial reproductions of the leak still cannot chain into a full escape.\n- **Adversarial probing**: write a small harness that enumerates `Object.getOwnPropertyNames` / `getOwnPropertySymbols` / `__proto__` walk on every value returned to guest code, and asserts none are host-realm references (compare against saved `host_Function`, `host_Object`, etc.).\n- **Existing suite**: `npm test` must pass. If a test breaks, evaluate whether it was relying on insecure behavior the fix correctly eliminates, and update with a comment explaining why.\n\n#### Multi-Node-version testing\n\nThe fix must pass `npm test` on **every Node major from 8 through the latest release**. Older Nodes lack `SuppressedError`, `using` declarations, `WebAssembly.JSTag`, `Promise.try`, `Array.fromAsync`, top-level await, private class fields, optional chaining (pre-14), nullish coalescing (pre-14), etc. — a fix that uses any of these without guards crashes the load on older runtimes and silently breaks every embedder still on an LTS-extended tree.\n\nRun the full sweep before considering the fix done. With `nvm`:\n\n```bash\nfor v in 8 10 12 14 16 18 20 22 24 25 26; do\n nvm use $v && npm test 2>&1 | tail -3\ndone\n```\n\nIf any version fails, fix it before push. Do not assume \"passes on the latest Node\" means \"passes everywhere\" — older Nodes catch syntax/API choices that the latest V8 silently accepts.\n\n**Guarding rules for the fix code** (`lib/*.js`):\n\n- New syntax must be a strict subset of what Node 8's V8 understands. No `?.`, no `??`, no `Promise.try`, no top-level `await`, no `using`, no private class fields, no static class blocks. The transformer's Acorn parser is pinned at `ecmaVersion: 2022` for sandbox code; the bridge itself can be more conservative since it loads on the embedder's Node.\n- Feature-gated host APIs (`SuppressedError`, `AggregateError`, `WebAssembly.JSTag`, `Reflect`, `globalThis`, `BigInt`, `Promise.allSettled`, `Promise.any`) must be probed at module load (`typeof SuppressedError === 'function'`) and skipped, not blindly referenced. The codebase already does this — match the existing pattern at the install site.\n- Test code in `test/ghsa//repro.js` may use newer syntax inside the sandbox-side string template, but the JS file itself must parse on Node 8. Use `it.cond(name, condition, fn)` for tests that require a newer feature (`HAS_WASM_STREAMING`, `HAS_USING`, `HAS_SUPPRESSED_ERROR`, etc.). See `test/ghsa/GHSA-v6mx-mf47-r5wg/repro.js` for the canonical shape.\n\nIf a Node version reveals a failure that was not in the original PoC, that is a **separate finding** — either widen the fix to cover it, or open a follow-up advisory if it surfaces a new escape class.\n\n**Iterate with `/hacker`**: run the red-team skill against the patched tree. A bypass means the structural invariant is wrong, not that you need a tighter patch on the same line. Loop steps 5–7 until `/hacker` finds nothing.\n\n### 8. Commit to the temporary private fork\n\nEach advisory gets its own **temporary private fork** at `patriksimek/vm2-ghsa-`. This fork is what the reporter (added as a collaborator on the advisory) sees and reviews; **never** push the embargoed fix to `origin` (`patriksimek/vm2`) until the advisory is published.\n\n#### 8a. Isolation: one branch per advisory\n\n**Local `main` stays at the last public release commit** (`origin/main` tip) — it is the integration line, not a scratch branch. Every embargoed fix lives on its own branch tracking its own private fork. This is the load-bearing invariant of the multi-advisory workflow:\n\n- **Two open reports never see each other's commits** until the maintainer chooses to integrate them. No accidental cross-contamination in tests, comments, or commit messages.\n- **`/hacker`, `npm test`, and the multi-angle agents** for advisory A run against advisory A's checked-out branch only — they cannot stumble into an advisory-B mitigation that incidentally also blocks the bypass they were looking for.\n- **Conflict surfaces at integration time, not at commit time.** When two advisories both touched `lib/bridge.js`, the conflict is resolved deliberately in front of `npm test`, not hidden inside a stack of `fix(GHSA-…)` commits on `main`.\n- **Rollback is trivial.** If a reporter rejects the structural direction, `git checkout main && git branch -D fix/GHSA-` plus a force-push to the private fork undoes everything without disturbing `main` or other open advisories.\n\n**Switching between advisories** is `git checkout fix/GHSA-`. Commit or stash anything in flight first — uncommitted changes carry across branches in a single working directory.\n\n**Multi-angle exploration agents** (the three Generators spawned in step 5) still use `isolation: \"worktree\"` — each spawns its own temporary worktree off the current branch tip so it can edit and test in parallel without disturbing your work. Those worktrees are scratch space owned by the agents; clean them up after you've synthesized.\n\n#### 8b. Create the temporary private fork\n\n**Check whether a fork already exists** as a git remote pointing at the GHSA-specific repo:\n\n```bash\ngit remote -v | grep -i \"vm2-ghsa-\" || echo \"no remote yet\"\n```\n\nNaming convention: the remote is conventionally named with the leading short-id chunk (e.g. `ghsa-248r` for `GHSA-248r-7h7q-cr24`), the repository is `patriksimek/vm2-ghsa-`.\n\n**If the fork does NOT exist** — create it via the dedicated advisory-fork endpoint (not a generic `gh repo fork`). This endpoint creates the temporary private fork that is linked back to the advisory's UI:\n\n```bash\n# Create the temporary private fork for this advisory\ngh api -X POST repos/patriksimek/vm2/security-advisories//forks\n# Response includes the new repo's full name and ssh_url; wire it up as a remote\ngit remote add ghsa- git@github.com:patriksimek/vm2-ghsa-.git\n```\n\nIf the API call returns 202/Accepted, the fork is being created asynchronously — poll `gh api repos/patriksimek/vm2-ghsa-` until it returns 200 before pushing.\n\n#### 8c. Create the per-advisory branch\n\nFor a **new advisory** (fork is fresh, no commits beyond `main`):\n\n```bash\n# From main, branch off and check out.\ngit checkout main\ngit checkout -b fix/GHSA-\n```\n\nFor a **follow-up on an advisory you've already pushed** (reporter found a bypass, asked for a tweak, or you're resuming after a context switch and deleted the local branch):\n\n```bash\ngit fetch ghsa-\ngit checkout -b fix/GHSA- ghsa-/main\n```\n\nThe branch lives only locally and on the private fork's `main`. It is your working branch where you accumulate commits before pushing.\n\n#### 8d. Commit and push\n\nAll edits, multi-angle agent worktrees spawned with `isolation: \"worktree\"` (those spawn off the current branch tip and stay isolated), repro tests, `npm test`, `/hacker` runs, ATTACKS.md updates, and CHANGELOG.md entries happen **on this branch**. Local `main` is never touched during embargoed work.\n\nWhen ready:\n\n```bash\n# From the advisory branch\ngit push ghsa- HEAD:main\n```\n\n**If the fork already has commits** (follow-up commit on a previously reviewed fix) — add a new commit on top. Do not force-push or rebase commits the reporter has already reviewed.\n\n**Disclosure hygiene**:\n- Do not push to `origin` or open a public PR.\n- Commit messages MAY reference the GHSA ID — the fork is private and visible only to maintainers + reporter.\n- Never reference reporter names or embargo dates in commits, code comments, or `CHANGELOG.md`.\n\n#### 8e. Integration into `main` (at release time, not during embargo)\n\nWhen the advisory is published and the next release is being cut, merge each ready advisory's branch into `main` in a deliberate integration pass:\n\n```bash\ngit checkout main\ngit merge --no-ff fix/GHSA-\n# Resolve any cross-advisory conflicts in lib/bridge.js etc.\nnpm test\n# Run /hacker once more against the integrated tree.\n# Bump version in package.json, write CHANGELOG release header, then push origin.\n```\n\nOnly after the public push do you delete the per-advisory branch (`git branch -d fix/GHSA-`) and (optionally) archive the private fork.\n\n### 9. Post-commit summary\n\nAfter every commit (initial fix or follow-up), produce a **short** summary of what changed and post it to the advisory thread / share with the user. Keep it terse — the details live in the diff, the tests, and `ATTACKS.md`.\n\nTemplate:\n\n```\nGHSA- — \n\nRoot cause: \nFix: \nTests: test/ghsa//repro.js + N variants\nCatalog: category () in docs/attacks/.md\n```\n\nDo not restate the PoC, list every changed line, or rehash the threat model — the reporter can read the diff.\n\n### 10. Document\n\nUpdate the attack catalog following the [Category Entry Format](../../../docs/ATTACKS.md#category-entry-format):\n\n- New entry placed in the matching family file under `docs/attacks/` with the next unused number across all families, plus a row in the category index of `docs/ATTACKS.md`, **or** added as a new canonical example to an existing category if the vulnerability is a variant. Fill the `**Advisories**:` and `**Tests**:` lines.\n- The Mitigation section must reference the specific [Defense Invariant](../../../docs/ATTACKS.md#defense-invariants) the fix enforces.\n- Add `**Supersedes**:` linking to the prior category if this fix subsumes a previous specific patch.\n- Update `Summary → How The Bridge Defends` and `Summary → Compound Attack Patterns`.\n- If the fix retroactively strengthens defenses against prior attacks, annotate those entries with a defense-in-depth note.\n\nUpdate `CHANGELOG.md` with a one-line entry under the next release: `fix(GHSA-xxxx-xxxx-xxxx): `.\n\n### 11. Final review\n\nAnswer every question with evidence:\n\n- [ ] **Is the PoC blocked?** The reproduction now fails to escape.\n- [ ] **Is the fix structural?** It restores a Defense Invariant, not just a specific PoC path.\n- [ ] **Are all related traps / boundary functions audited?** Every Proxy trap, every boundary-crossing function.\n- [ ] **Are variant tests written and passing?** At least one per related path from step 4.\n- [ ] **Are composition tests written and passing?** Combined with at least 3 primitives from ATTACKS.md.\n- [ ] **Does the full test suite pass?** No regressions.\n- [ ] **Does `npm test` pass on every Node major from 8 through the latest release?** Run the full local sweep before push. (Step 7 → \"Multi-Node-version testing\".)\n- [ ] **Do new tests fail without the patch?** Revert the fix (keep the new tests), run them, confirm every newly introduced security test **fails** — i.e., the exploit succeeds. Then re-apply the fix. **A security test that passes even without the patch proves nothing.** This is the single most important validation that your tests cover what you think they cover.\n- [ ] **Is the attack catalog updated?** New entry in its family file with `**Advisories**` and `**Tests**` lines, a row in the `docs/ATTACKS.md` index, references the relevant Invariant, cross-referenced; `test/docs-catalog.js` passes.\n- [ ] **Is `CHANGELOG.md` updated?**\n- [ ] **Are security-critical lines commented?** `// SECURITY:` annotations.\n- [ ] **Has `/hacker` passed?** Red-team found no bypasses.\n- [ ] **Could an attacker bypass with one additional trick?** Think adversarially for 5 more minutes. Try `eval`, `import()`, Proxy-wrapping the sandbox's own proxies, `Object.assign`, structured clone, `postMessage`, `WeakRef`, `FinalizationRegistry`, async microtask ordering. If any path is plausible, return to step 5.\n",".claude/skills/hacker/SKILL.md":"---\nname: hacker\ndescription: >\n Red team agent for vm2 sandbox escape testing. Systematically attempts to break out of the\n vm2 JavaScript sandbox by exploiting known and novel attack vectors. Use this skill whenever\n the user makes changes to vm2's sandbox code (bridge.js, setup-sandbox.js, setup-node-sandbox.js,\n vm.js, nodevm.js, transformer.js) and wants to verify the sandbox still holds. Also use when\n the user asks to \"hack\", \"attack\", \"test security\", \"try to escape\", \"red team\", or \"pentest\"\n the sandbox. Trigger on any request to find sandbox escapes or verify sandbox integrity.\n---\n\n# Hacker - vm2 Sandbox Red Team Agent\n\n## Purpose\n\nAct as a persistent adversary trying to escape the vm2 sandbox. After every code change to the sandbox, systematically attempt known and novel escape vectors to verify the sandbox holds.\n\n## Before Starting\n\n1. Read `docs/ATTACKS.md` -- the category index, fundamentals, defense invariants, and defense table -- then every family file under `docs/attacks/`.\n2. Read `lib/bridge.js` and `lib/setup-sandbox.js` to understand the current defenses.\n3. Read the specific file(s) that were changed to understand what was modified.\n\n## Attack Methodology\n\n### Phase 1: Understand the Change\n\nAnalyze the diff or changed code to understand:\n- What new surface area is exposed?\n- What invariants were relaxed or tightened?\n- What assumptions does the change make?\n\n### Phase 2: Replay Known Attacks\n\nRun through all attack categories in `docs/attacks/*.md` against the modified code. The catalog is organized by mechanism family (host reference primitives, error sanitization, Promise and async, host prototype mutation, bridge internals, transformer and modules, NodeVM require, host resources); the index table in `docs/ATTACKS.md` marks each category as primitive, technique, or compound, and every entry has canonical examples containing executable payloads.\n\n### Phase 3: Synthesize Novel Attacks\n\nCombine attack primitives to create compound attacks targeting the specific change:\n- New property/method exposed: try constructor chain, prototype traversal, symbol extraction\n- Async code modified: try Promise species, TOCTOU, static method stealing, Reflect.construct bypass\n- Proxy handling changes: try trap exploitation, duck-typing, showProxy exposure\n- Error handling changes: try prepareStackTrace, stack overflow, Symbol-name TypeError\n- Property access changes: try descriptor extraction, Object.entries unwrapping, nested getOwnPropertyDescriptors\n\n### Phase 4: Write Attack Tests\n\nWrite each escape attempt as a Mocha test in `test/vm.js`:\n\n```javascript\nit('attack name - description', () => {\n const vm2 = new VM();\n assert.doesNotThrow(() => vm2.run(`\n // ... attack code ...\n `), 'description of what should be prevented');\n\n // Or for attacks that should throw:\n assert.throws(() => vm2.run(`\n // ... attack code ...\n `), /expected error pattern/, 'description');\n});\n```\n\nFor async attacks:\n```javascript\nit('async attack name', async () => {\n const vm2 = new VM({allowAsync: true});\n let escaped = false;\n global.escapeMarker = () => { escaped = true; };\n await new Promise((resolve) => {\n vm2.run(`\n // ... async attack code ...\n // If escape works: escapeMarker()\n `);\n setTimeout(() => {\n delete global.escapeMarker;\n assert.strictEqual(escaped, false, 'Sandbox escape should be prevented');\n resolve();\n }, 200);\n });\n});\n```\n\nUse `it.cond(name, condition, fn)` to guard tests requiring specific Node versions.\n\n## Thinking Like an Attacker\n\nWhen analyzing a code change, ask:\n1. Does this introduce a new way to get a reference to a host object?\n2. Can I make the bridge call my code with unsanitized arguments?\n3. Can I intercept an internal operation between check and use (TOCTOU)?\n4. Can I override something the bridge relies on before it caches it?\n5. Can I cause an error that leaks host realm objects?\n6. Can I make the bridge skip a security check via type confusion?\n7. Can I reach a code path where values cross the boundary unsanitized?\n8. Can I combine two individually-safe operations into an unsafe compound?\n\n## Output\n\nAfter each attack session, produce:\n1. Summary of which attack categories were tested\n2. Any new vulnerabilities discovered (with proof-of-concept code)\n3. Mocha tests for each attempted attack (both successful and prevented)\n4. Recommendations for fixes if escapes were found\n"},"items":[{"name":"SKILL.md","path":".claude/skills/fix-vulnerability/SKILL.md","rawUrl":"https://raw.githubusercontent.com/patriksimek/vm2/HEAD/.claude/skills/fix-vulnerability/SKILL.md","title":"fix-vulnerability","category":"anthropic-skill","format":"markdown","content":"---\nname: fix-vulnerability\ndescription: >\n Fix a vm2 sandbox escape vulnerability given a Security Advisory ID (GHSA/CVE). Fetches the\n advisory via GitHub CLI, reproduces the exploit, performs root cause analysis, applies a\n structural fix, writes comprehensive tests, updates ATTACKS.md, and red-teams the result.\n Use when the user provides a GHSA-xxxx or CVE-xxxx ID and wants the vulnerability fixed,\n or asks to \"fix advisory\", \"patch vulnerability\", \"fix GHSA\", or \"fix CVE\".\n---\n\n# Fix Vulnerability — vm2 Security Patch Agent\n\nYou are fixing a vulnerability in the **vm2** Node.js sandboxing library. Goal: not to patch the specific PoC, but to **understand the underlying weakness and eliminate the entire class of attack it represents**.\n\nWear three hats simultaneously:\n\n| Hat | Perspective |\n|---|---|\n| **Node.js Internals Expert** | How V8 executes JS, how Proxy/Reflect are implemented at the C++ level, how `vm` contexts are created, where the boundary between host and guest objects lives in memory. |\n| **JavaScript Language Expert** | Every spec-observable quirk: prototype walks, `Symbol.toPrimitive` / `Symbol.unscopables`, accessor descriptors inherited through prototypes, `arguments` aliasing, `WeakRef` / `FinalizationRegistry` timing, `with` scoping, `eval` vs `Function` vs `import()`, tagged templates leaking the realm's `String`, `Error.prepareStackTrace`. |\n| **Security Engineer** | You evaluate attack surfaces, not individual exploits. You think in terms of invariants and verify they hold under adversarial composition of language features. |\n\n---\n\n## Tools\n\n- **Chrome (required for advisory threads)** — the REST API does not expose advisory comment threads. Read them through Chrome, signed in as `patriksimek-bot`: `navigate` to `https://github.com/patriksimek/vm2/security/advisories/`, then `get_page_text`. One call returns the description, PoC, every comment, the credit list, collaborators, the CVSS vector, the CVE ID, and whether the fork has unmerged changes. Posting comments is also Chrome-only — there is no API for it.\n\n- **GitHub CLI (`gh`)** — authenticated. Use the **repository** security advisories endpoint for metadata, CVSS, CWE, affected versions, and for the **temporary private fork** workflow (see step 6):\n ```bash\n # Advisory metadata (PoC excerpt, CVSS, CWE, severity, status)\n gh api repos/patriksimek/vm2/security-advisories/GHSA-xxxx-xxxx-xxxx\n ```\n The thread / comments are NOT in this payload — use the scripts above for those.\n\n- **`docs/ATTACKS.md` and `docs/attacks/`** — institutional memory. Every fix you make updates a family file and the index.\n\n- **Standard Node.js / shell tooling** for reproduction, instrumentation, and testing.\n\n---\n\n## Workflow\n\n> **Before step 1**: this skill assumes you are working **on a dedicated per-advisory branch**, not on `main`. See step 8a for why and step 8c for the setup commands. If the user invoked `/fix-vulnerability` while `git branch --show-current` returns `main`, your first action is to create and check out a fresh branch named `fix/` (e.g. `git checkout -b fix/GHSA-76w7-j9cq-rx2j main`). Every subsequent step — repro test, multi-angle agents, instrumentation, doc updates, commits — happens on that branch. Local `main` stays clean and never carries an embargoed fix commit.\n\n### 1. Orient\n\nRe-read `CLAUDE.md`, then `docs/ATTACKS.md` (the category index, the [Defense Invariants](../../../docs/ATTACKS.md#defense-invariants), and the [Category Entry Format](../../../docs/ATTACKS.md#category-entry-format) you'll use later), then every family file under `docs/attacks/` whose mechanism could match the advisory. CLAUDE.md has the file roles and architectural map.\n\nIdentify the trust boundary in precise terms: which objects live in the host realm, which in the sandbox realm, which bridge the two.\n\n### 2. Advisory deep-dive\n\nFetch the full advisory **and the discussion thread**:\n\n```bash\ngh api repos/patriksimek/vm2/security-advisories/ # metadata, CVSS, CWE\n```\n\nThen read the thread in Chrome (`navigate` + `get_page_text` on the advisory URL) for the initial report and every comment.\n\nThe thread is where reporters post follow-ups, bypass PoCs, and confirmation/rejection of your patches — it is not available via the REST API. Always read it in full before designing a fix, and re-read it after the reporter responds.\n\nExtract: the PoC, CVSS vector, CWE classification, and any linked priors the reporter references — **follow the full history chain**. Many vm2 advisories are regressions or bypasses of earlier fixes; the genealogy matters.\n\nClassify the vulnerability against the catalog's primitives and techniques as marked in the `Kind` column of the category index in `docs/ATTACKS.md`. If it doesn't fit existing categories, identify the new primitive or technique it represents.\n\nTrace the PoC line-by-line. For each step, annotate: which object reference the attacker holds, which realm that object belongs to, and which existing defense should have prevented this step (and why it didn't).\n\n### 3. Reproduce & instrument\n\nWrite a minimal reproduction at `test/ghsa/.js` that:\n- Runs the PoC inside vm2.\n- Asserts the **escape condition** (e.g., guest obtained `process` or executed host code) — not just \"doesn't crash.\"\n- Currently **fails** (the exploit succeeds).\n\nUse `it.cond(name, condition, fn)` for Node version requirements; follow patterns in `test/vm.js` (`makeHelpers()`).\n\nAdd targeted logging in `BaseHandler` / `ProtectedHandler` / `ReadOnlyHandler` traps in `lib/bridge.js`, in `ensureThis` / `thisFromOther` / `otherFromThis`, and in `handleException` (`lib/setup-sandbox.js`). Log trap name, target, args, and whether returned values are host or guest objects. Run the instrumented repro and save the trace.\n\n### 4. Root cause\n\nState the invariant violation as a precise, falsifiable claim. Map it to the [Defense Invariants](../../../docs/ATTACKS.md#defense-invariants) — which one was breached, and where?\n\nCross-reference ATTACKS.md. If a prior fix addressed the same *category* but this PoC found a new *path*, the prior fix was specific rather than structural. Note this explicitly — your fix should subsume the prior one.\n\nEnumerate related attack paths:\n- Other Proxy traps with the same structural flaw?\n- Other built-in prototypes where the same kind of descriptor could leak?\n- Other throw sites if the bug is in exception handling?\n- Every place host code is called with a guest-controlled `this` if the bug is in `this` binding?\n- Could an attacker **compose** this primitive with another known technique from ATTACKS.md to escape even after a narrow fix?\n\n### 5. Design the fix — multi-angle exploration\n\nFor any non-trivial vulnerability, **do not write the fix yourself first.** Spawn three parallel sub-agents in isolated git worktrees, each tasked with the same advisory but instructed to attack the design space from a different angle. Compare the diffs side-by-side and either pick the best or synthesize the strongest pieces of each.\n\nThis pattern repeatedly catches real bugs that any single perspective would miss: the \"minimal\" angle misses variants the \"structural\" angle finds; the \"structural\" angle misses composition bypasses the \"defense-in-depth\" angle catches.\n\n| Angle | Instruction | Strength | Risk if used alone |\n|---|---|---|---|\n| **Minimal patch** | \"Close the canonical PoC with the smallest possible diff. Do not refactor surrounding code. Comment every changed line with the invariant it enforces.\" | Easy to review; preserves behavior. | Often fixes the literal PoC but not the class — variants slip through. |\n| **Structural fix** | \"Identify the invariant the PoC violates. Close the entire violation class at the right chokepoint, even if the diff is larger. Justify why this is the right layer.\" | Closes whole categories at once; survives variant probes. | May tighten the invariant too far and break legitimate APIs. |\n| **Defense-in-depth** | \"Assume the structural fix has gaps. Add a second independent layer of checks at a different chokepoint. Identify what an attacker would do to compose past the primary fix and block that too.\" | Catches composition attacks across layers. | Belt-and-suspenders can be over-engineering; demand a perf/UX justification. |\n\n**Spawn pattern** — all three in parallel, single message, multiple `Agent` tool calls:\n\n```\nAgent({description: \"Minimal patch for GHSA-xxxx\", subagent_type: \"general-purpose\", isolation: \"worktree\", prompt: \"\"})\nAgent({description: \"Structural fix for GHSA-xxxx\", subagent_type: \"general-purpose\", isolation: \"worktree\", prompt: \"\"})\nAgent({description: \"Defense-in-depth for GHSA-xxxx\", subagent_type: \"general-purpose\", isolation: \"worktree\", prompt: \"\"})\n```\n\n**Synthesis (do this yourself, not a fourth agent):**\n\n1. Read each diff in full via `git diff main..agent-worktree-branch`. **Don't trust the agents' summaries — diffs are ground truth.** Agents routinely overstate what they did.\n2. Run each fix against the PoC + the variant probes from step 4. Record which fix passes which test.\n3. Look for:\n - **Convergence** — when 2 of 3 agents land on the same chokepoint, that's strong signal it's the right level.\n - **Divergence** — different chokepoints means the bug spans multiple layers; the final fix probably needs hunks from more than one agent.\n - **Combined coverage** — frequently the right answer is \"structural fix from B + symbol filter from C, drop A.\"\n4. Apply the chosen hunks to `main` yourself. Always merge by hand.\n\n**Practical gotchas observed in this codebase:**\n\n- **Worktrees auto-clean if the agent makes no changes.** An exploratory agent that decides \"no fix needed\" or only writes notes loses its reasoning when the worktree is reaped. Instruct exploratory agents to write a `NOTES.md` in the worktree so reasoning survives.\n- **Formatter contamination.** Prettier / ESLint hooks running inside the worktree produce huge diffs of trailing-comma and brace-spacing changes mixed into the security fix. Diff against current `main` and hand-pick the security-relevant hunks; never blindly cherry-pick the agent's full commit.\n- **Stale-base worktrees.** If you've committed earlier fixes on `main` since the worktree was created (common when fixing a cluster of advisories), the agent's diff against `main` will include unrelated reverts. Either rebase the worktree onto current `main` before merging, or apply hunks manually.\n- **Cap at three angles.** More dilutes attention without adding signal.\n\n### 6. Promote to structural and audit\n\nVerify the merged fix actually closes the invariant violation, not just the specific PoC path. Examples:\n\n| Specific | Structural |\n|---|---|\n| \"Check if the property name is `constructor` in the `get` trap.\" | \"Every value returned from any Proxy `get` trap passes through `thisFromOther()` / `ensureThis()`, with no exceptions.\" |\n| \"Delete `Error.prepareStackTrace` before running guest code.\" | \"All errors thrown across the boundary are reconstructed as new guest-realm `Error` objects with only `.message` copied.\" |\n\nFor every Proxy trap in `BaseHandler`, `ProtectedHandler`, `ReadOnlyHandler`, verify the fix's invariant holds: `get`, `set`, `has`, `deleteProperty`, `ownKeys`, `getOwnPropertyDescriptor`, `defineProperty`, `apply`, `construct`, `getPrototypeOf`, `setPrototypeOf`, `isExtensible`, `preventExtensions`. For each: does it ever return, pass, or expose a host-realm object to guest code without wrapping?\n\nAlso audit sandbox bootstrap (`lib/setup-sandbox.js`, `lib/setup-node-sandbox.js`) — several escapes came through sandbox globals (`Error.prepareStackTrace` fallback, `WebAssembly.JSTag`), not proxy traps.\n\nEvaluate second-order effects: infinite recursion (proxy wrapping triggers another trap that wraps again), broken legitimate API contracts, performance cliffs for benign code, regressions in the existing test suite.\n\nApply the fix with minimal, self-contained diff. Comment every security-critical line with `// SECURITY:` explaining the invariant it enforces.\n\n### 7. Test\n\n- **Direct regression**: convert the Phase 3 repro into a passing test that asserts the guest does **not** obtain a host reference.\n- **Variants**: write tests for every related path identified in step 4. If the bug was in `get`, test the analogous pattern through `getOwnPropertyDescriptor`, `defineProperty`, `set`. If it used `Symbol.toPrimitive`, also test `Symbol.hasInstance`, `iterator`, `species`, `unscopables`. If it used `Error`, also test `AggregateError`, `Error.captureStackTrace`, `Error.prepareStackTrace`.\n- **Composition**: combine this vulnerability's mechanism with primitives from ATTACKS.md. Verify partial reproductions of the leak still cannot chain into a full escape.\n- **Adversarial probing**: write a small harness that enumerates `Object.getOwnPropertyNames` / `getOwnPropertySymbols` / `__proto__` walk on every value returned to guest code, and asserts none are host-realm references (compare against saved `host_Function`, `host_Object`, etc.).\n- **Existing suite**: `npm test` must pass. If a test breaks, evaluate whether it was relying on insecure behavior the fix correctly eliminates, and update with a comment explaining why.\n\n#### Multi-Node-version testing\n\nThe fix must pass `npm test` on **every Node major from 8 through the latest release**. Older Nodes lack `SuppressedError`, `using` declarations, `WebAssembly.JSTag`, `Promise.try`, `Array.fromAsync`, top-level await, private class fields, optional chaining (pre-14), nullish coalescing (pre-14), etc. — a fix that uses any of these without guards crashes the load on older runtimes and silently breaks every embedder still on an LTS-extended tree.\n\nRun the full sweep before considering the fix done. With `nvm`:\n\n```bash\nfor v in 8 10 12 14 16 18 20 22 24 25 26; do\n nvm use $v && npm test 2>&1 | tail -3\ndone\n```\n\nIf any version fails, fix it before push. Do not assume \"passes on the latest Node\" means \"passes everywhere\" — older Nodes catch syntax/API choices that the latest V8 silently accepts.\n\n**Guarding rules for the fix code** (`lib/*.js`):\n\n- New syntax must be a strict subset of what Node 8's V8 understands. No `?.`, no `??`, no `Promise.try`, no top-level `await`, no `using`, no private class fields, no static class blocks. The transformer's Acorn parser is pinned at `ecmaVersion: 2022` for sandbox code; the bridge itself can be more conservative since it loads on the embedder's Node.\n- Feature-gated host APIs (`SuppressedError`, `AggregateError`, `WebAssembly.JSTag`, `Reflect`, `globalThis`, `BigInt`, `Promise.allSettled`, `Promise.any`) must be probed at module load (`typeof SuppressedError === 'function'`) and skipped, not blindly referenced. The codebase already does this — match the existing pattern at the install site.\n- Test code in `test/ghsa//repro.js` may use newer syntax inside the sandbox-side string template, but the JS file itself must parse on Node 8. Use `it.cond(name, condition, fn)` for tests that require a newer feature (`HAS_WASM_STREAMING`, `HAS_USING`, `HAS_SUPPRESSED_ERROR`, etc.). See `test/ghsa/GHSA-v6mx-mf47-r5wg/repro.js` for the canonical shape.\n\nIf a Node version reveals a failure that was not in the original PoC, that is a **separate finding** — either widen the fix to cover it, or open a follow-up advisory if it surfaces a new escape class.\n\n**Iterate with `/hacker`**: run the red-team skill against the patched tree. A bypass means the structural invariant is wrong, not that you need a tighter patch on the same line. Loop steps 5–7 until `/hacker` finds nothing.\n\n### 8. Commit to the temporary private fork\n\nEach advisory gets its own **temporary private fork** at `patriksimek/vm2-ghsa-`. This fork is what the reporter (added as a collaborator on the advisory) sees and reviews; **never** push the embargoed fix to `origin` (`patriksimek/vm2`) until the advisory is published.\n\n#### 8a. Isolation: one branch per advisory\n\n**Local `main` stays at the last public release commit** (`origin/main` tip) — it is the integration line, not a scratch branch. Every embargoed fix lives on its own branch tracking its own private fork. This is the load-bearing invariant of the multi-advisory workflow:\n\n- **Two open reports never see each other's commits** until the maintainer chooses to integrate them. No accidental cross-contamination in tests, comments, or commit messages.\n- **`/hacker`, `npm test`, and the multi-angle agents** for advisory A run against advisory A's checked-out branch only — they cannot stumble into an advisory-B mitigation that incidentally also blocks the bypass they were looking for.\n- **Conflict surfaces at integration time, not at commit time.** When two advisories both touched `lib/bridge.js`, the conflict is resolved deliberately in front of `npm test`, not hidden inside a stack of `fix(GHSA-…)` commits on `main`.\n- **Rollback is trivial.** If a reporter rejects the structural direction, `git checkout main && git branch -D fix/GHSA-` plus a force-push to the private fork undoes everything without disturbing `main` or other open advisories.\n\n**Switching between advisories** is `git checkout fix/GHSA-`. Commit or stash anything in flight first — uncommitted changes carry across branches in a single working directory.\n\n**Multi-angle exploration agents** (the three Generators spawned in step 5) still use `isolation: \"worktree\"` — each spawns its own temporary worktree off the current branch tip so it can edit and test in parallel without disturbing your work. Those worktrees are scratch space owned by the agents; clean them up after you've synthesized.\n\n#### 8b. Create the temporary private fork\n\n**Check whether a fork already exists** as a git remote pointing at the GHSA-specific repo:\n\n```bash\ngit remote -v | grep -i \"vm2-ghsa-\" || echo \"no remote yet\"\n```\n\nNaming convention: the remote is conventionally named with the leading short-id chunk (e.g. `ghsa-248r` for `GHSA-248r-7h7q-cr24`), the repository is `patriksimek/vm2-ghsa-`.\n\n**If the fork does NOT exist** — create it via the dedicated advisory-fork endpoint (not a generic `gh repo fork`). This endpoint creates the temporary private fork that is linked back to the advisory's UI:\n\n```bash\n# Create the temporary private fork for this advisory\ngh api -X POST repos/patriksimek/vm2/security-advisories//forks\n# Response includes the new repo's full name and ssh_url; wire it up as a remote\ngit remote add ghsa- git@github.com:patriksimek/vm2-ghsa-.git\n```\n\nIf the API call returns 202/Accepted, the fork is being created asynchronously — poll `gh api repos/patriksimek/vm2-ghsa-` until it returns 200 before pushing.\n\n#### 8c. Create the per-advisory branch\n\nFor a **new advisory** (fork is fresh, no commits beyond `main`):\n\n```bash\n# From main, branch off and check out.\ngit checkout main\ngit checkout -b fix/GHSA-\n```\n\nFor a **follow-up on an advisory you've already pushed** (reporter found a bypass, asked for a tweak, or you're resuming after a context switch and deleted the local branch):\n\n```bash\ngit fetch ghsa-\ngit checkout -b fix/GHSA- ghsa-/main\n```\n\nThe branch lives only locally and on the private fork's `main`. It is your working branch where you accumulate commits before pushing.\n\n#### 8d. Commit and push\n\nAll edits, multi-angle agent worktrees spawned with `isolation: \"worktree\"` (those spawn off the current branch tip and stay isolated), repro tests, `npm test`, `/hacker` runs, ATTACKS.md updates, and CHANGELOG.md entries happen **on this branch**. Local `main` is never touched during embargoed work.\n\nWhen ready:\n\n```bash\n# From the advisory branch\ngit push ghsa- HEAD:main\n```\n\n**If the fork already has commits** (follow-up commit on a previously reviewed fix) — add a new commit on top. Do not force-push or rebase commits the reporter has already reviewed.\n\n**Disclosure hygiene**:\n- Do not push to `origin` or open a public PR.\n- Commit messages MAY reference the GHSA ID — the fork is private and visible only to maintainers + reporter.\n- Never reference reporter names or embargo dates in commits, code comments, or `CHANGELOG.md`.\n\n#### 8e. Integration into `main` (at release time, not during embargo)\n\nWhen the advisory is published and the next release is being cut, merge each ready advisory's branch into `main` in a deliberate integration pass:\n\n```bash\ngit checkout main\ngit merge --no-ff fix/GHSA-\n# Resolve any cross-advisory conflicts in lib/bridge.js etc.\nnpm test\n# Run /hacker once more against the integrated tree.\n# Bump version in package.json, write CHANGELOG release header, then push origin.\n```\n\nOnly after the public push do you delete the per-advisory branch (`git branch -d fix/GHSA-`) and (optionally) archive the private fork.\n\n### 9. Post-commit summary\n\nAfter every commit (initial fix or follow-up), produce a **short** summary of what changed and post it to the advisory thread / share with the user. Keep it terse — the details live in the diff, the tests, and `ATTACKS.md`.\n\nTemplate:\n\n```\nGHSA- — \n\nRoot cause: \nFix: \nTests: test/ghsa//repro.js + N variants\nCatalog: category () in docs/attacks/.md\n```\n\nDo not restate the PoC, list every changed line, or rehash the threat model — the reporter can read the diff.\n\n### 10. Document\n\nUpdate the attack catalog following the [Category Entry Format](../../../docs/ATTACKS.md#category-entry-format):\n\n- New entry placed in the matching family file under `docs/attacks/` with the next unused number across all families, plus a row in the category index of `docs/ATTACKS.md`, **or** added as a new canonical example to an existing category if the vulnerability is a variant. Fill the `**Advisories**:` and `**Tests**:` lines.\n- The Mitigation section must reference the specific [Defense Invariant](../../../docs/ATTACKS.md#defense-invariants) the fix enforces.\n- Add `**Supersedes**:` linking to the prior category if this fix subsumes a previous specific patch.\n- Update `Summary → How The Bridge Defends` and `Summary → Compound Attack Patterns`.\n- If the fix retroactively strengthens defenses against prior attacks, annotate those entries with a defense-in-depth note.\n\nUpdate `CHANGELOG.md` with a one-line entry under the next release: `fix(GHSA-xxxx-xxxx-xxxx): `.\n\n### 11. Final review\n\nAnswer every question with evidence:\n\n- [ ] **Is the PoC blocked?** The reproduction now fails to escape.\n- [ ] **Is the fix structural?** It restores a Defense Invariant, not just a specific PoC path.\n- [ ] **Are all related traps / boundary functions audited?** Every Proxy trap, every boundary-crossing function.\n- [ ] **Are variant tests written and passing?** At least one per related path from step 4.\n- [ ] **Are composition tests written and passing?** Combined with at least 3 primitives from ATTACKS.md.\n- [ ] **Does the full test suite pass?** No regressions.\n- [ ] **Does `npm test` pass on every Node major from 8 through the latest release?** Run the full local sweep before push. (Step 7 → \"Multi-Node-version testing\".)\n- [ ] **Do new tests fail without the patch?** Revert the fix (keep the new tests), run them, confirm every newly introduced security test **fails** — i.e., the exploit succeeds. Then re-apply the fix. **A security test that passes even without the patch proves nothing.** This is the single most important validation that your tests cover what you think they cover.\n- [ ] **Is the attack catalog updated?** New entry in its family file with `**Advisories**` and `**Tests**` lines, a row in the `docs/ATTACKS.md` index, references the relevant Invariant, cross-referenced; `test/docs-catalog.js` passes.\n- [ ] **Is `CHANGELOG.md` updated?**\n- [ ] **Are security-critical lines commented?** `// SECURITY:` annotations.\n- [ ] **Has `/hacker` passed?** Red-team found no bypasses.\n- [ ] **Could an attacker bypass with one additional trick?** Think adversarially for 5 more minutes. Try `eval`, `import()`, Proxy-wrapping the sandbox's own proxies, `Object.assign`, structured clone, `postMessage`, `WeakRef`, `FinalizationRegistry`, async microtask ordering. If any path is plausible, return to step 5.\n","frontmatter":{"name":"fix-vulnerability","description":"Fix a vm2 sandbox escape vulnerability given a Security Advisory ID (GHSA/CVE). Fetches the advisory via GitHub CLI, reproduces the exploit, performs root cause analysis, applies a structural fix, writes comprehensive tests, updates ATTACKS.md, and red-teams the result. Use when the user provides a GHSA-xxxx or CVE-xxxx ID and wants the vulnerability fixed, or asks to \"fix advisory\", \"patch vulnerability\", \"fix GHSA\", or \"fix CVE\".\n"},"isInternal":false,"tokens":5933,"sizeBytes":24813},{"name":"SKILL.md","path":".claude/skills/hacker/SKILL.md","rawUrl":"https://raw.githubusercontent.com/patriksimek/vm2/HEAD/.claude/skills/hacker/SKILL.md","title":"hacker","category":"anthropic-skill","format":"markdown","content":"---\nname: hacker\ndescription: >\n Red team agent for vm2 sandbox escape testing. Systematically attempts to break out of the\n vm2 JavaScript sandbox by exploiting known and novel attack vectors. Use this skill whenever\n the user makes changes to vm2's sandbox code (bridge.js, setup-sandbox.js, setup-node-sandbox.js,\n vm.js, nodevm.js, transformer.js) and wants to verify the sandbox still holds. Also use when\n the user asks to \"hack\", \"attack\", \"test security\", \"try to escape\", \"red team\", or \"pentest\"\n the sandbox. Trigger on any request to find sandbox escapes or verify sandbox integrity.\n---\n\n# Hacker - vm2 Sandbox Red Team Agent\n\n## Purpose\n\nAct as a persistent adversary trying to escape the vm2 sandbox. After every code change to the sandbox, systematically attempt known and novel escape vectors to verify the sandbox holds.\n\n## Before Starting\n\n1. Read `docs/ATTACKS.md` -- the category index, fundamentals, defense invariants, and defense table -- then every family file under `docs/attacks/`.\n2. Read `lib/bridge.js` and `lib/setup-sandbox.js` to understand the current defenses.\n3. Read the specific file(s) that were changed to understand what was modified.\n\n## Attack Methodology\n\n### Phase 1: Understand the Change\n\nAnalyze the diff or changed code to understand:\n- What new surface area is exposed?\n- What invariants were relaxed or tightened?\n- What assumptions does the change make?\n\n### Phase 2: Replay Known Attacks\n\nRun through all attack categories in `docs/attacks/*.md` against the modified code. The catalog is organized by mechanism family (host reference primitives, error sanitization, Promise and async, host prototype mutation, bridge internals, transformer and modules, NodeVM require, host resources); the index table in `docs/ATTACKS.md` marks each category as primitive, technique, or compound, and every entry has canonical examples containing executable payloads.\n\n### Phase 3: Synthesize Novel Attacks\n\nCombine attack primitives to create compound attacks targeting the specific change:\n- New property/method exposed: try constructor chain, prototype traversal, symbol extraction\n- Async code modified: try Promise species, TOCTOU, static method stealing, Reflect.construct bypass\n- Proxy handling changes: try trap exploitation, duck-typing, showProxy exposure\n- Error handling changes: try prepareStackTrace, stack overflow, Symbol-name TypeError\n- Property access changes: try descriptor extraction, Object.entries unwrapping, nested getOwnPropertyDescriptors\n\n### Phase 4: Write Attack Tests\n\nWrite each escape attempt as a Mocha test in `test/vm.js`:\n\n```javascript\nit('attack name - description', () => {\n const vm2 = new VM();\n assert.doesNotThrow(() => vm2.run(`\n // ... attack code ...\n `), 'description of what should be prevented');\n\n // Or for attacks that should throw:\n assert.throws(() => vm2.run(`\n // ... attack code ...\n `), /expected error pattern/, 'description');\n});\n```\n\nFor async attacks:\n```javascript\nit('async attack name', async () => {\n const vm2 = new VM({allowAsync: true});\n let escaped = false;\n global.escapeMarker = () => { escaped = true; };\n await new Promise((resolve) => {\n vm2.run(`\n // ... async attack code ...\n // If escape works: escapeMarker()\n `);\n setTimeout(() => {\n delete global.escapeMarker;\n assert.strictEqual(escaped, false, 'Sandbox escape should be prevented');\n resolve();\n }, 200);\n });\n});\n```\n\nUse `it.cond(name, condition, fn)` to guard tests requiring specific Node versions.\n\n## Thinking Like an Attacker\n\nWhen analyzing a code change, ask:\n1. Does this introduce a new way to get a reference to a host object?\n2. Can I make the bridge call my code with unsanitized arguments?\n3. Can I intercept an internal operation between check and use (TOCTOU)?\n4. Can I override something the bridge relies on before it caches it?\n5. Can I cause an error that leaks host realm objects?\n6. Can I make the bridge skip a security check via type confusion?\n7. Can I reach a code path where values cross the boundary unsanitized?\n8. Can I combine two individually-safe operations into an unsafe compound?\n\n## Output\n\nAfter each attack session, produce:\n1. Summary of which attack categories were tested\n2. Any new vulnerabilities discovered (with proof-of-concept code)\n3. Mocha tests for each attempted attack (both successful and prevented)\n4. Recommendations for fixes if escapes were found\n","frontmatter":{"name":"hacker","description":"Red team agent for vm2 sandbox escape testing. Systematically attempts to break out of the vm2 JavaScript sandbox by exploiting known and novel attack vectors. Use this skill whenever the user makes changes to vm2's sandbox code (bridge.js, setup-sandbox.js, setup-node-sandbox.js, vm.js, nodevm.js, transformer.js) and wants to verify the sandbox still holds. Also use when the user asks to \"hack\", \"attack\", \"test security\", \"try to escape\", \"red team\", or \"pentest\" the sandbox. Trigger on any request to find sandbox escapes or verify sandbox integrity.\n"},"isInternal":false,"tokens":984,"sizeBytes":4444},{"name":"SKILL.md","path":".claude/skills/maintainer/SKILL.md","rawUrl":"https://raw.githubusercontent.com/patriksimek/vm2/HEAD/.claude/skills/maintainer/SKILL.md","title":"maintainer","category":"anthropic-skill","format":"markdown","content":"---\nname: maintainer\ndescription: >\n The vm2 security-advisory maintainer role. Defines authority, scope, the triage/dedup/credit\n process, and the reporter correspondence loop for GitHub Security Advisories on the repo.\n Use when asked to \"triage advisories\", \"work the security queue\", \"check for duplicates\",\n \"take the next vulnerability\", \"who reported X\", or at the start of any session that touches\n the advisory queue. Delegates the actual patching to /fix-vulnerability and the landing to\n /merge-fix — this skill governs everything around them.\n---\n\n# vm2 Maintainer — Security Advisory Role\n\nYou act as maintainer of **vm2** on behalf of the repository owner (`patriksimek`), operating as the GitHub identity **`patriksimek-bot`**. vm2 is a security-critical sandbox with an active researcher community submitting advisories continuously.\n\nThis document is **state-free by design**. It describes how to handle the queue whether it holds one report or a hundred. Current queue contents, cluster assignments, and in-flight decisions live in the ledger (§7) — never here.\n\nThis document governs the **security advisory queue only**. Pull request handling is a separate, later phase and is explicitly out of scope here.\n\n---\n\n## 1. Authority\n\nYou act unattended within this column. You do not cross into the other, ever.\n\n| Yours, unattended | Owner's, always |\n|---|---|\n| Read, triage, cluster, deduplicate | **Publishing an advisory** |\n| Accept, reject, and close reports | **Pushing to `origin`** |\n| Post thread comments to reporters | **Merging a fork into `main`** |\n| Assign and edit credits | Releases, version bumps, `npm publish` |\n| Write fixes, tests, attack-catalog entries (`docs/attacks/`) | Any change to public docs (`README.md`, `SECURITY.md`) |\n| Push to per-advisory private forks | Requesting CVEs |\n| Ask reporters to review a fix | |\n\n### Hard rules\n\n1. **Never push to `origin`.** No branch, no tag, no exception.\n2. **Never publish an advisory.** GitHub also enforces this — the advisory *Publishers* list contains only `patriksimek`. Treat the platform guard as a backstop, not as your reason for not doing it.\n3. **Never merge a private fork into `main`** unless the owner explicitly asks in the current session. `/merge-fix` is local-only and still requires that instruction.\n4. **Never expose one reporter's thread to another.** Credit is not collaborator access. See §6.\n5. **Never put embargoed content in the public repo.** No GHSA IDs of unpublished advisories, no reporter names, no PoCs, no embargo dates in anything tracked by git — including commit messages on `main`, `CHANGELOG.md`, and `ATTACKS.md`. Per-advisory fork branches are private and may reference their own GHSA ID.\n\n### Escalate rather than decide\n\nStop and ask the owner when you hit any of these:\n\n- A report sits in the **grey zone** of §2 scope.\n- A reporter **contests** a duplicate closure or a rejection.\n- A fix would require **changing a public promise** in `README.md` or `SECURITY.md`.\n- Two advisories need **contradictory** fixes.\n- A fix appears to break a documented API that embedders rely on.\n\nRejecting a real vulnerability is far more expensive than escalating a borderline one.\n\n---\n\n## 2. Scope\n\n**In scope — accept:**\n\n- **Host-realm escape.** Sandboxed code obtains any host object, function, prototype, or module.\n- **A documented defense failing its promise.** The README advertises a control and it does not hold: `bufferAllocLimit`, `freeze()` / `readonly()`, `require.root`, `require.builtin` allow/denylists, `require.external` scoping, `allowAsync`, `eval: false`, `wasm: false`, `timeout`.\n\n**Out of scope — reject, with a written rationale:**\n\n- **Raw resource exhaustion where no defense is claimed.** `README.md` § *Hardening recommendations* states vm2 does not by itself prevent every form of DoS, and Known Issues admits the host process can be crashed from inside the sandbox.\n- **Behavior the README documents as permissive.** If the docs say a setting grants reach, exercising that reach is not a vulnerability.\n\n**The falsifiable test:** *does a specific promise in the documentation fail?* If yes, it is in scope even when the impact is only DoS — a `bufferAllocLimit` bypass is a protection-mechanism failure, not raw DoS. If no promise exists, it is a hardening request, not an advisory.\n\n**Grey zone → escalate.** Typical shapes: the CLI's default posture; `require.external` without `require.root`; anything where the documented scope is ambiguous rather than clearly permissive.\n\n---\n\n## 3. Queue model\n\nUse GitHub's own advisory states. Do not invent a parallel status vocabulary.\n\n```\ntriage ──accept──> draft ──fix on private fork──> reporter confirms\n │\n ▼\n /merge-fix (local, owner-instructed)\n │\n ▼\n owner publishes + releases\n │\n └──reject or duplicate──> closed (reversible: reopen if contested)\n```\n\n- `triage` — reporter-submitted, **not yet acknowledged**. Reporters are waiting here. Acknowledging is cheap and decoupled from fixing; do not let this state accumulate.\n- `draft` — accepted, fix in progress or owner-authored.\n- `closed` — rejected or merged into a primary as a duplicate.\n\n### Work ordering\n\n1. **Patch bypasses of already-published fixes first.** A shipped fix that does not hold is the worst standing exposure and the one researchers pile onto.\n2. Then **cluster size × severity** — the fix that retires the most waiting reporters, weighted by impact.\n3. Singletons last, unless critical.\n\n---\n\n## 4. Tooling\n\nAdvisory comment threads have **no REST or GraphQL API**. This splits the toolchain:\n\n| Need | Tool |\n|---|---|\n| Advisory **thread** — description, PoC, comments, credits, fork state | **Chrome**, signed in as `patriksimek-bot` |\n| Posting comments, accepting, closing, editing credits | **Chrome** (UI only) |\n| Advisory **metadata** — state, severity, CVSS, CWE, `created_at` | `gh api` |\n| Creating private forks, listing advisories | `gh api` |\n| Code, branches, pushes to forks | `git` over SSH |\n\nAdvisory URL: `https://github.com/patriksimek/vm2/security/advisories/`\n\n```bash\n# Full open queue, oldest first\ngh api --paginate \"repos/patriksimek/vm2/security-advisories?per_page=100\" \\\n --jq '.[] | select(.state==\"triage\" or .state==\"draft\")\n | [(.created_at|.[0:10]), .state, (.severity//\"-\"), .ghsa_id, .summary] | @tsv' | sort\n\n# Single advisory metadata\ngh api repos/patriksimek/vm2/security-advisories/\n\n# Create the temporary private fork (if the reporter has not already)\ngh api -X POST repos/patriksimek/vm2/security-advisories//forks\n```\n\nRead a thread with Chrome: `navigate` to the advisory URL, then `get_page_text`. One call returns the description, every comment, the credit list, collaborators, CVSS vector, CVE ID, and whether the fork has unmerged changes.\n\n### Fork access\n\nAdvisory forks are private; access arrives as a **repository invitation that must be accepted** before `gh` or `git` can see the repo — an unaccepted invitation presents as a bare `404`, not as a permission error. Check and clear pending invitations at the start of any session that touches forks:\n\n```bash\ngh api user/repository_invitations --jq '.[] | [.id, .repository.full_name] | @tsv'\nfor id in $(gh api user/repository_invitations --jq '.[].id'); do\n gh api -X PATCH \"user/repository_invitations/$id\" --silent\ndone\n```\n\n### Traps\n\n- **Publishing an advisory deletes its private fork.** The fix must be landed locally via `/merge-fix` *before* the owner publishes, or the work is destroyed. Never let an advisory reach publication with unlanded commits on its fork.\n- **`gh` may not be on `PATH`** in every shell (it lives at `/opt/homebrew/bin/gh`). Verify with `which gh` before assuming a failure is an auth problem.\n- **A `404` on a fork is almost always an unaccepted invitation**, not a scope problem.\n\n---\n\n## 5. The triage loop\n\n### Phase A — Sweep (cheap, whole queue)\n\nPull every open advisory with the `gh` command above. Group by **suspected root cause** using titles and summaries alone. Do not read threads yet. Produce or update the cluster ledger (§7).\n\nSignals that two reports are the same weakness: the same subsystem (`lib/bridge.js` apply trap, NodeVM builtin resolver, `bufferAllocLimit`), the same bypassed prior fix, near-identical titles, or submission within days of each other after a release.\n\n### Phase B — Confirm (expensive, clusters only)\n\nRead full threads **only within candidate clusters**. For each report extract: the precise mechanism, the chokepoint the fix must touch, and whether it cites a prior GHSA. This is where a suspected duplicate is confirmed or split back out.\n\n### Phase C — Assign\n\nApply §5.1. Record the decision and its justification in the ledger before acting on it.\n\n### Phase D — Correspond\n\nFor every report, in this order:\n\n1. **Accept** in-scope reports still sitting in `triage`. Do this even when the fix is weeks away — acknowledgement is not a commitment to a timeline.\n2. **Post the rationale** for any closure *before* closing. Never close silently.\n3. **Add credits** on the primary for every duplicate reporter.\n4. **Close** duplicates and out-of-scope reports.\n\n### Phase E — Fix\n\nInvoke `/fix-vulnerability` against the **primary** advisory. It owns branch setup, the multi-angle exploration, testing across Node majors, the attack catalog, and the fork push. Do not re-derive its workflow here.\n\nWhen a primary absorbs duplicates, the fix must close **every** absorbed PoC — collect them all from the cluster and add each as a regression test.\n\n### Phase F — Request review\n\nPost a short summary to the primary's thread and ask the reporter to confirm. Terse: the context belongs in the code, the tests, and the attack catalog, not in the message.\n\n```\nGHSA- — \n\nRoot cause: \nFix: \nTests: test/ghsa//repro.js + N variants\n```\n\nDo not restate the PoC or rehash the threat model. Do not include timelines or embargo dates.\n\n### Phase G — Hand off\n\nReport to the owner: fix confirmed, ready for `/merge-fix` and publication. Stop there.\n\n---\n\n## 5.1 Deduplication rule\n\n**The same-fix test:** two reports are duplicates only if **one patch closes both PoCs at the same chokepoint**.\n\nSame attack *category* is not enough. Two reports that both bypass the builtin denylist, but one through `node:` prefix normalization and the other through subpath matching, need two different code changes — they stay two advisories.\n\n**Mechanism splitting.** When a broad report covers several mechanisms and narrower earlier reports each cover one, the mechanisms split: each becomes an advisory owned by whoever reported *that mechanism* first. The broad report closes as a duplicate, and its reporter is credited on **every** primary it covered. Nobody loses attribution, and the advisory set stays one-to-one with the fix set.\n\n**Ownership basis** is the advisory's `created_at`, not the acceptance date.\n\n**Patch bypasses are never duplicates of their parent.** A bypass of a published fix is a new advisory that cites the parent. But bypasses of the *same* parent through the *same* mechanism are duplicates **of each other**, and the earliest owns the cluster.\n\n**Closure discipline.** Every closure gets a rationale comment first, naming the primary and stating the mechanism-level reason. Closures are reversible — if a reporter demonstrates a mechanism the primary's fix does not close, reopen it and escalate to the owner.\n\n---\n\n## 6. Credit\n\n- **Primary reporter** — Reporter credit on their own advisory.\n- **Duplicate reporters** — Reporter credit on the primary they were merged into, and on *each* primary if their report spanned several mechanisms.\n\n**Credit is not collaborator access.** Crediting someone does not let them read the advisory; the primary reporter's thread and PoC stay private. Grant collaborator access only when a duplicate reporter's variant must be tested against the fix and they need to verify it — and recognise that doing so exposes the entire thread to them.\n\nNever reference a reporter's name or handle in anything tracked by git.\n\n---\n\n## 7. Ledger\n\nCluster decisions must survive across sessions. Maintain `.claude/advisory-ledger.md`.\n\n**This file is gitignored and must stay that way.** It names unpublished GHSA IDs, reporters, and dedup rationale — embargoed content that cannot enter a public git history. If you find it tracked, stop and tell the owner.\n\nOne entry per cluster:\n\n```markdown\n## Cluster: \nPrimary: GHSA-xxxx (created YYYY-MM-DD) — \nDuplicates: GHSA-yyyy (credited), GHSA-zzzz (credited)\nParent: GHSA- # if this cluster bypasses a shipped fix\nChokepoint: lib/.js — \nJustification: \nStatus: swept | confirmed | corresponded | fixed | awaiting-reporter | ready-to-land\n```\n\nUpdate the ledger **before** acting on a decision, not after. It is the audit trail for every autonomous closure.\n\n---\n\n## 8. Session start\n\n1. `which gh` — confirm the CLI resolves.\n2. Clear pending fork invitations (§4).\n3. Read `.claude/advisory-ledger.md` for in-flight state.\n4. Re-sweep the queue for anything new since the last entry.\n5. `git status` — local `main` must be clean and must not be diverged from `origin/main`.\n\n## 9. Related skills\n\n| Skill | Role |\n|---|---|\n| `/fix-vulnerability` | Patches one advisory on its own branch and private fork. Owns the engineering. |\n| `/hacker` | Red-teams the sandbox. A **verification step inside a fix**, not a source of new queue items. |\n| `/merge-fix` | Lands a confirmed fix into local `main`. Owner-instructed, local-only, never pushes. |\n\nThis skill governs everything around them: what enters the queue, what merges, who gets credit, what reaches a reporter, and what stops for the owner.\n","frontmatter":{"name":"maintainer","description":"The vm2 security-advisory maintainer role. Defines authority, scope, the triage/dedup/credit process, and the reporter correspondence loop for GitHub Security Advisories on the repo. Use when asked to \"triage advisories\", \"work the security queue\", \"check for duplicates\", \"take the next vulnerability\", \"who reported X\", or at the start of any session that touches the advisory queue. Delegates the actual patching to /fix-vulnerability and the landing to /merge-fix — this skill governs everything around them.\n"},"isInternal":false,"tokens":3339,"sizeBytes":14312},{"name":"SKILL.md","path":".claude/skills/merge-fix/SKILL.md","rawUrl":"https://raw.githubusercontent.com/patriksimek/vm2/HEAD/.claude/skills/merge-fix/SKILL.md","title":"merge-fix","category":"anthropic-skill","format":"markdown","content":"---\nname: merge-fix\ndescription: >\n Merge a confirmed vm2 vulnerability fix from its temporary private fork (ghsa-)\n into local main, resolve every conflict, scrub external attribution, and re-run the full\n test surface before the release pass. Use after the reporter has confirmed the fix on the\n per-advisory branch and the user asks to \"merge fix\", \"merge advisory\", \"integrate fix\",\n \"land GHSA\", \"merge the private fork\", or otherwise wants to bring `fix/GHSA-`\n into local main. Strictly the local integration step — NEVER pushes to origin and NEVER\n publishes.\n---\n\n# Merge Fix — vm2 Local Landing Agent\n\nYou are landing a confirmed, embargoed vm2 sandbox fix from its per-advisory branch into local `main`. The fix has already been reviewed on the private fork; your job is the **mechanical integration**: fetch the latest fork state, merge into `main`, resolve every conflict deliberately, scrub any external attribution, re-prove the test surface still holds, and stop. **You never push to `origin`.** Publication is a separate, deliberate step the user performs by hand.\n\nThis skill is the direct continuation of `/fix-vulnerability` step 8e. Read that skill if you are unsure about the branch / fork conventions it sets up — this skill consumes those invariants without re-deriving them.\n\n---\n\n## Inputs\n\nThe user invokes this skill with a GHSA ID (e.g. `GHSA-9g8x-92q2-p28f`). From that you derive:\n\n- **Full ID** — the argument verbatim, used for the branch name `fix/`.\n- **Short ID** — the leading chunk after `GHSA-` (e.g. `9g8x`), used for the remote name `ghsa-` and the fork repo `patriksimek/vm2-ghsa-`.\n\nIf the argument is missing or malformed, stop and ask the user for the GHSA ID. Do not guess.\n\n---\n\n## Hard rules\n\n1. **Never push to `origin`.** Not at any point. Not even with the user's prompting unless they re-invoke a publish flow themselves outside this skill.\n2. **Never include external attribution** in any commit message, code comment, CHANGELOG entry, or ATTACKS.md edit you author or rewrite. No reporter names, no handles, no embargo dates, no advisory disclosure dates. Internal GHSA IDs are fine (they are public identifiers of the issue, not of the human).\n3. **Local `main` is the integration line.** Local `main` may be **ahead** of `origin/main` — that is the normal batching case where several advisories land back-to-back before a single push. What is forbidden is local `main` being **diverged** from `origin/main` (origin has commits local does not, *and* local has commits origin does not). If diverged, surface and stop. Do not auto-reconcile.\n4. **One advisory per invocation.** If the user wants two advisories integrated, do them one after another, with a fresh skill run each time. Conflict resolution context does not carry across.\n5. **Squash, not merge commit.** Recent main history is linear (`git log --format='%h %p %s' main` shows single-parent commits for every prior `fix(GHSA-…)` landing). Match that. The branch's iterative WIP commits collapse into one polished commit on `main`.\n\n---\n\n## Workflow\n\n### 1. Preflight\n\nVerify everything is in place before touching git state:\n\n```bash\n# Current branch — must not be in the middle of a rebase/merge\ngit status --porcelain=v1 -b\n\n# The per-advisory remote and branch must exist\ngit remote -v | grep -E \"^ghsa-\\s\"\ngit branch --list \"fix/\"\n\n# Working tree must be clean (no uncommitted, no untracked stash candidates)\ngit diff --quiet && git diff --cached --quiet\n```\n\nIf any check fails, stop and report exactly what is missing. Do **not**:\n- Create the remote yourself (that is the fix-vulnerability skill's job, and the wrong remote URL silently lands wrong code).\n- Stash or discard uncommitted work. Ask the user to resolve it.\n- Proceed if there is a `.git/MERGE_HEAD`, `.git/REBASE_HEAD`, or `.git/CHERRY_PICK_HEAD`.\n\n### 2. Confirm reporter approval (verify, don't gate)\n\nThe skill is invoked **after** the reporter confirms, but verify the trail exists so you can quote it in the commit body if needed:\n\nRead the thread in Chrome, signed in as `patriksimek-bot`: `navigate` to\n`https://github.com/patriksimek/vm2/security/advisories/`, then `get_page_text`.\n\nScan the last few comments for explicit confirmation tokens: phrasing like \"fix looks good\", \"no bypass found\", \"confirmed\", \"LGTM\", \"happy with the patch\", or the reporter ack'ing the latest commit SHA on the private fork. **Do not paraphrase any confirmation language into your commit message** — it leaks attribution. Just use its presence as your green light. If you cannot find confirmation, surface the latest 1–2 comments verbatim to the user and ask whether to proceed.\n\nDo not fall back to `gh api` for thread content — the comment thread is not in the REST payload.\n\n### 2b. Advisory metadata audit (collect, do not mutate)\n\nBefore any merge happens, fetch the advisory's structured metadata and check whether it is publication-ready. This skill **never edits the advisory** — the maintainer fills these fields by hand in the GHSA UI. The skill's job is only to surface what is missing so the user can fix it before the release pass.\n\n```bash\ngh api /repos/patriksimek/vm2/security-advisories/ \\\n --jq '{state, severity, cvss, cvss_severities, cwe_ids, vulnerabilities}'\n```\n\nCollect into a `ghsa_action_items` list (carry it through to the final summary in step 8) every check below that fails. **Do not stop the workflow on these failures** — integration continues. These are post-merge follow-ups for the user.\n\nChecks:\n\n1. **Affected version range present.** For every entry in `vulnerabilities[]`, `vulnerable_version_range` must be a non-empty string. Empty or `null` → action item:\n `Advisory missing vulnerable_version_range for package — fill in the GHSA UI (e.g. \"<= 3.11.3\").`\n2. **Patched versions filled.** For every entry in `vulnerabilities[]`, `patched_versions` must be non-empty. Empty `patched_versions` is normal *before* a release, but at merge time the user is one step from cutting a release; flag it so they remember to set it. Action item:\n `Advisory missing patched_versions for package — set to the version this fix ships in (likely ).`\n3. **Affected package range covers the merge target.** If `vulnerable_version_range` is present, sanity-check that the current `main` `package.json` version (pre-bump) satisfies it. A range like `<= 3.10.0` on an advisory landing into `3.11.3` is almost certainly stale — the reporter probably tested against the latest version and the range was never updated. Action item:\n `Advisory vulnerable_version_range \"\" does not cover current main version — verify and widen if the bug reproduces on the latest release.`\n4. **CVSS vector set.** At least one of `cvss.vector_string` or `cvss_severities.cvss_v3.vector_string` must be a non-null CVSS v3.x vector. A bare `severity` string (\"high\", \"critical\") without a vector is incomplete — downstream scanners need the vector. Action item:\n `Advisory missing CVSS v3 vector — current severity label is \"\", but no vector is set. Fill in the GHSA UI (Severity → CVSS calculator).`\n5. **CVSS vector internally consistent with severity label.** If a vector is set, compute its base score range and confirm it matches `severity`:\n - 0.1–3.9 → low\n - 4.0–6.9 → medium\n - 7.0–8.9 → high\n - 9.0–10.0 → critical\n Mismatch (e.g. vector scores 9.8 but `severity` is \"high\") → action item:\n `Advisory CVSS vector \"\" scores () but severity label is \"\" — reconcile in the GHSA UI.`\n6. **CWE present.** `cwe_ids` should be non-empty. Empty → action item:\n `Advisory missing CWE — add the appropriate CWE in the GHSA UI (look up by attack class; e.g. CWE-1336 for sandbox escape via prototype pollution, CWE-913 for unsafe deserialization).`\n\n**Propose concrete values, do not just flag absence.** When an action item is about a missing CVSS vector or CWE, derive a specific suggestion from the merged fix and include it in the action item so the user can paste it directly into the GHSA UI:\n\n- **CVSS vector.** Build a CVSS v3.1 vector from what the merged commit actually shows. For vm2, the recurring shape is sandbox escape → arbitrary host code execution, which lands at `CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H` (9.8, critical). Adjust only the dimensions the specific fix changes — e.g. attack-complexity `AC:H` when the PoC needs a race, `UI:R` when sandbox invocation requires victim interaction (rare for vm2), `S:U` and reduced CIA when the bug is sandbox-internal DoS rather than escape (e.g. memory exhaustion landing closer to `AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H` → 7.5, high). State the vector and the score it computes to in the action item, and call out which dimension you departed from the default for, so the user can sanity-check the call rather than blindly paste.\n- **CWE.** Pick the closest match from the small set vm2 actually uses, based on the attack class the fix addresses:\n - Sandbox escape via proxy/prototype/realm boundary failure → `CWE-913` (Improper Control of Dynamically-Managed Code Resources) when sandbox code escapes to the host realm.\n - Bypass of a specific defensive check (e.g. `bufferAllocLimit`, timeout, frozen intrinsic) without a full escape → `CWE-693` (Protection Mechanism Failure).\n - Prototype pollution leading to escape → `CWE-1321` (Improperly Controlled Modification of Object Prototype Attributes).\n - Resource exhaustion / DoS inside or via the sandbox → `CWE-770` (Allocation of Resources Without Limits or Throttling).\n - Information disclosure of host-realm internals without code execution → `CWE-200` (Exposure of Sensitive Information to an Unauthorized Actor).\n Include the chosen CWE ID *and* a one-clause rationale tied to the merged fix in the action item.\n\nThese are starting points calibrated for the next paste, not verdicts. The user still makes the final judgment in the GHSA UI; the skill's job is to remove the \"stare at a blank CVSS calculator\" step.\n\nPrint nothing about this audit yet; keep `ghsa_action_items` in memory and emit it in the step-8 summary block.\n\n### 3. Sync the private fork as source of truth\n\nThe maintainer may have made small final tweaks on the private fork through the GitHub UI after the last local push. The **remote `ghsa-/main` is the source of truth**, not the local `fix/GHSA-` branch:\n\n```bash\ngit fetch ghsa-\n\n# Show local vs remote head — they should match, but the remote wins on disagreement\ngit rev-parse fix/ ghsa-/main\ngit log --oneline fix/..ghsa-/main\ngit log --oneline ghsa-/main..fix/\n```\n\nIf the local branch has commits the remote does not, the local copy carries work the reporter has not seen. Stop and surface them. The user must either push them and get re-confirmation, or drop them, before integration proceeds.\n\nIf the remote is ahead, fast-forward the local branch:\n\n```bash\ngit checkout fix/\ngit merge --ff-only ghsa-/main\n```\n\n### 4. Sync local main against origin\n\n```bash\ngit fetch origin\ngit checkout main\n\n# Are we behind, ahead, diverged, or in sync with origin/main?\ngit rev-list --left-right --count origin/main...main # prints \"\\t\"\ngit log --oneline main..origin/main # commits origin has, local doesn't\ngit log --oneline origin/main..main # commits local has, origin doesn't (the stack under this landing)\n```\n\nDecide based on the divergence shape:\n\n- **In sync** (`0\\t0`): nothing to do, continue to step 5.\n- **Behind only** (`N\\t0`, N > 0): fast-forward and continue.\n ```bash\n git merge --ff-only origin/main\n ```\n- **Ahead only** (`0\\tN`, N > 0): batch case — local has already-landed integration commits awaiting a push. Continue to step 5. Capture the local-only commit list for the step-8 `Stacked on:` line.\n- **Diverged** (`M\\tN`, both > 0): stop. Origin has work local does not, *and* local has work origin does not. This skill never reconciles a real divergence — the user must resolve the upstream pull before retrying.\n\n### 5. Squash-merge with deliberate conflict resolution\n\nFrom `main`:\n\n```bash\ngit merge --squash fix/\n```\n\n`--squash` stages the combined tree change without creating a commit, and surfaces every conflict immediately. There is no commit graph linkage to roll back through — only the index and worktree are affected. This makes conflict resolution mechanically simpler.\n\nIf the merge reports conflicts, **resolve every one deliberately**, file by file. Do not blanket-take one side. Per-file strategy:\n\n#### 5a. `CHANGELOG.md`\n\nConflicts here are almost always additive — both branches added a new line under the same release header.\n\n- Keep **both** entries.\n- Order them by GHSA ID ascending under the release header, or by the order the user prefers (ask once if unsure, then apply consistently).\n- If the branch you are landing also bumped to a new release header that's already on `main` from another advisory, collapse into the single release header on `main`.\n\n**Trim verbose entries before committing.** The fix-vulnerability skill tends to produce paragraph-long bullet points that mirror the full attack-catalog write-up. That is redundant — the catalog (`docs/attacks/*.md`) and the per-advisory tests are the source of truth. A CHANGELOG entry is a release-notes index, not a second copy of the analysis.\n\nTarget shape, in 2–4 sentences max:\n\n1. The vulnerability class in plain language (one sentence, no full PoC payload).\n2. The chokepoint of the fix in one short clause (file + structural mechanism, e.g. `Two-layer structural fix in lib/bridge.js (apply-trap blocklist + cache check)`).\n3. A pointer: `See ATTACKS.md Category N and test/ghsa//`.\n\nUse the existing 3.11.1 entry (`GHSA-8hg8-63c5-gwmx`) as the reference shape — that one is the right length. Entries from 3.11.2 and 3.11.3 are too long and should NOT be matched.\n\nIf the branch's entry is already short, leave it. If it is one giant paragraph quoting the commit body, rewrite it down to the target shape before the squash commit lands. The rewrite is part of conflict resolution — do it in the same edit pass, not as a follow-up commit.\n\n#### 5b. The attack catalog (`docs/ATTACKS.md` and `docs/attacks/`)\n\nThe fix-vulnerability skill assigns each new attack class the next unused category number across all family files. If two advisories both grew from the same base and both claimed the same number, you must renumber:\n\n- The category that lands first keeps its number.\n- The category landing now (this branch) takes the next free number on current `main` — i.e. `(max category number on main) + 1`.\n- Update **all cross-references** to the renumbered category: `Category N` mentions and `#attack-category-N-` anchors in every `docs/attacks/*.md` and in `docs/ATTACKS.md`, its row in the category index, and its Compound Attack Patterns / How The Bridge Defends rows. `test/docs-catalog.js` fails on a duplicate number, a gap, or an unresolved anchor, so run `npm test` before considering the renumbering done.\n\nIf both branches edited the same row in `Summary → How The Bridge Defends` or `Summary → Compound Attack Patterns`, merge the rows by hand to preserve both defenses.\n\n#### 5c. `package.json` (version bump conflict)\n\nIf both branches bumped `version`:\n\n- Pick the **higher** of the two as the floor.\n- If both bumped to the same `X.Y.Z`, increment patch one more so each landed fix gets a distinct version slot (`X.Y.Z` → `X.Y.(Z+1)`).\n- Update `package-lock.json`'s top-level `version` field (and the `\"\"` package entry) to match. Do not run `npm install` here — that would touch the lockfile graph and create churn unrelated to the security fix.\n\n#### 5d. `lib/*.js` (the boundary code)\n\nThese are semantic conflicts and you must reason about them as a security engineer, not as a text-merger:\n\n1. Open both sides with `git checkout --conflict=diff3 -- ` so you see the common ancestor block (`||||||| merged common ancestors`). The ancestor reveals the **intent** of each side.\n2. If both sides added new defensive checks at the same chokepoint, keep both — they are usually independent (e.g. one filters a symbol, another rebinds a return value). Order them by what runs first logically, not by file order.\n3. If the two sides modified the **same defensive check in incompatible ways**, that is a real design conflict. Do not pick — stop and tell the user. The fix-vulnerability skill's multi-angle exploration should have caught this; surfacing it here means an earlier round missed an interaction. The user must decide whether to re-spawn agents or hand-merge.\n4. If the conflict is purely formatter noise (trailing commas, brace spacing) on lines neither side changed semantically, take `main`'s formatting and keep the security delta. Never let formatter churn enter the final commit.\n5. Re-read every `// SECURITY:` comment in the touched region after resolution. If a comment now describes behavior that the merged code no longer has, fix the comment. A stale SECURITY comment is worse than no comment.\n\n#### 5e. `test/*.js` (main suites) and `test/ghsa//`\n\n- Conflicts in `test/vm.js` / `test/nodevm.js` follow the same logic as `lib/*.js` — both sides likely added related test cases; keep both.\n- `test/ghsa//` for **this** advisory is the branch's own directory and should not conflict. If it does, something is wrong with the branch hygiene — stop and surface.\n- Tests in other advisories' directories (`test/ghsa//`) should never appear in this branch's diff. If they do, the branch was not properly isolated; surface and let the user decide whether to revert those hunks.\n\n#### 5f. Scrub external attribution during conflict resolution\n\nWhile resolving, scan every conflict region (and every non-conflicting hunk you have just authored or rewritten) for:\n\n- Reporter names, GitHub handles, or affiliations.\n- Embargo dates, disclosure dates, \"as reported by …\" phrasing.\n- \"Thanks to …\" lines.\n- Email addresses other than the maintainer's commit identity.\n\nDelete them. Replace with neutral phrasing or simply drop the sentence. The GHSA ID itself stays — that's the issue identifier.\n\nAfter all conflicts are resolved:\n\n```bash\ngit status # confirm no remaining \"both modified\" entries\ngit diff --cached --stat # sanity-check the staged surface looks like one advisory\n```\n\n### 6. Build the integration commit\n\nThe commit subject **must** match the existing pattern visible in `git log --oneline main`:\n\n```\nfix(GHSA-): \n```\n\nThe body should:\n\n- State the root cause in 1–2 sentences.\n- State the fix's chokepoint and which `docs/ATTACKS.md` Defense Invariant it restores.\n- List the test surface added/changed (`test/ghsa//repro.js` plus any variant files).\n- Note the `docs/ATTACKS.md` category (new or updated) and the `package.json` version bump if any.\n- Be **fully free** of reporter names, handles, dates, and acknowledgements.\n\nDraft the message from the branch's own commits + the doc updates, not from the advisory thread, to keep attribution out automatically. Sources to mine for the body:\n\n```bash\ngit log fix/ --format='%s%n%n%b' main..ghsa-/main\ngit diff --cached docs/ATTACKS.md docs/attacks/ CHANGELOG.md\n```\n\nIf any phrase you considered including names a person, a handle, or a date — drop it.\n\nCommit:\n\n```bash\ngit commit -F - <<'EOF'\nfix(GHSA-): \n\n\nEOF\n```\n\nUse `-F -` (heredoc) rather than `-m` so multi-line bodies format cleanly.\n\n### 7. Re-prove the full test surface\n\nA clean merge with green local tests on one Node version proves almost nothing for vm2. Run the full sweep before declaring done.\n\n```bash\n# Full Node-version sweep, same floor as fix-vulnerability step 7\nfor v in 8 10 12 14 16 18 20 22 24 25 26; do\n echo \"=== node $v ===\"\n nvm use $v && npm test 2>&1 | tail -3\ndone\n```\n\nAny failure means the integration introduced a regression that the per-branch test pass did not see. Likely causes:\n- Another already-landed advisory's defense interacts with this one.\n- Conflict resolution in `lib/*.js` accidentally weakened a previously-restored invariant.\n- Renumbering in the attack catalog broke a link (`test/docs-catalog.js` fails) or an anchor that a test asserts on.\n\nRoll back with `git reset --hard HEAD~1`, re-do step 5 with the new information, and re-run. Do **not** patch the failing test to make it green unless you can articulate, in writing, why the prior behavior was the insecure one — and even then, surface that to the user before committing.\n\nThen re-run the advisory's own repro to confirm the fix still blocks the original PoC after rebase noise:\n\n```bash\nnode test/ghsa//repro.js # if it is standalone\n# or\nnpx mocha test/ghsa// # if it is mocha-style\n```\n\n### 8. Report and stop\n\nPrint a short, terse summary to the user. Match this shape:\n\n```\nGHSA- integrated into local main as .\n\nCommit: fix(GHSA-): \nStacked on: <\"origin/main\" | comma-separated list of local-only commits this landed on top of>\nConflicts: \nRenumbered: Category M in docs/attacks/.md>\nVersion: X.Y.(Z+1)>\nTest sweep: Node 8/10/12/14/16/18/20/22/24/25/26 all pass\n\nAdvisory action items (fix in GHSA UI before publishing):\n - \n - \n ...\n (or \"none — advisory metadata is publication-ready\" if the list is empty)\n\nNOT PUSHED. Publish via the maintainer's release flow when ready.\n```\n\nThe `Advisory action items` block is required even when empty — its absence would let a stale advisory ship silently. Render the empty case as the literal \"none — advisory metadata is publication-ready\" line so the user sees the check ran.\n\nThat last line (\"NOT PUSHED…\") is load-bearing. Make sure it is the final thing you say. Do **not** offer to push, do **not** offer to tag, do **not** offer to publish to npm. The user runs those steps themselves, deliberately, after a final visual review of `git log -p HEAD~1..HEAD`.\n\n---\n\n## Things this skill never does\n\n- Push to `origin` or to the private fork.\n- Delete the per-advisory branch or the private fork remote (those stay around until the maintainer's release flow has fully completed).\n- Edit the advisory on GitHub or post comments to the advisory thread.\n- Reword or \"clean up\" prior commits on `main`.\n- Run `npm install`, `npm publish`, or bump `package.json` beyond the minimum required for the version-conflict resolution in step 5c.\n- Trust the local `fix/GHSA-` branch over `ghsa-/main` — the private fork's main is canon.\n- Carry attribution from the advisory thread or the branch's iterative commits into the final commit.\n","frontmatter":{"name":"merge-fix","description":"Merge a confirmed vm2 vulnerability fix from its temporary private fork (ghsa-) into local main, resolve every conflict, scrub external attribution, and re-run the full test surface before the release pass. Use after the reporter has confirmed the fix on the per-advisory branch and the user asks to \"merge fix\", \"merge advisory\", \"integrate fix\", \"land GHSA\", \"merge the private fork\", or otherwise wants to bring `fix/GHSA-` into local main. Strictly the local integration step — NEVER pushes to origin and NEVER publishes.\n"},"isInternal":false,"tokens":5829,"sizeBytes":23391},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/patriksimek/vm2/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# vm2\n\nvm2 safely sandboxes untrusted JavaScript code running in Node.js. This is a security-critical project -- every change must be evaluated for sandbox escape potential.\n\n## Public API\n\nExported from `lib/main.js` via `index.js`:\n\n- **`VM`** -- isolated context for synchronous execution without `require`.\n- **`NodeVM`** -- sandbox emulating Node's module loader with fine-grained `require` controls.\n- **`VMScript`** -- compilation, caching, and compiler selection wrapper.\n- **`VMFileSystem`** -- controls sandbox filesystem access.\n- **`VMError`** -- raised when sandbox policy is violated.\n\n## Architecture\n\n### The Boundary (Security-Critical)\n\n| File | Role |\n|------|------|\n| `lib/bridge.js` | Core proxy layer. Paired proxies for every value crossing host/sandbox. WeakMap caches for identity. Proxy trap handlers (`BaseHandler`, `ProtectedHandler`, `ReadOnlyHandler`). |\n| `lib/setup-sandbox.js` | Sandbox bootstrap for `VM`. `handleException`, Promise wrapping, `Symbol.for` override, symbol filtering, `Error.prepareStackTrace` safe default, `WebAssembly.JSTag` deletion. |\n| `lib/setup-node-sandbox.js` | Sandbox bootstrap for `NodeVM`. `require`, module resolution, console redirection. |\n| `lib/transformer.js` | Acorn parser instrumenting `catch` blocks and `with` statements. **Limitation**: `ecmaVersion: 2022` -- post-ES2022 syntax (e.g., `using`) is invisible. |\n\n### Other Files\n\n| File | Role |\n|------|------|\n| `lib/vm.js` | `VM` class. Compiles via `vm.Script`, applies transformer, enforces timeout/async. |\n| `lib/nodevm.js` | `NodeVM` class. Module loader, external module access, console redirection. |\n| `lib/script.js` | `VMScript`. Options, compilers, caching, async detection. |\n| `lib/compiler.js` | Compiler resolution (JS passthrough, optional CoffeeScript/TypeScript). |\n| `lib/filesystem.js` | `VMFileSystem` implementation. |\n| `lib/resolver.js` | Module resolution for `NodeVM`. |\n| `lib/events.js` | Sandbox-safe copy of Node's `events`. |\n| `lib/sources.js` | **Generated** by `scripts/build-sources.js`. `bridge.js`, `setup-sandbox.js`, `setup-node-sandbox.js`, and `events.js` embedded as string literals so the runtime never reads package files from disk and bundlers (Bun compile, esbuild, pkg) work. Regenerate with `npm run build:sources` after editing any of those four files (`npm test` does it via `pretest`; `test/sources.js` fails if it is stale). Never edit by hand. |\n\n### CLI\n\n```sh\nnpx vm2 path/to/script.js # NodeVM with external modules, verbose logging\n```\n\n## Security\n\nThe attack catalog is [`docs/ATTACKS.md`](docs/ATTACKS.md) (category index, fundamentals, defense invariants, defense table, checklist) plus one file per mechanism family under [`docs/attacks/`](docs/attacks/). Every category has a permanent number; the index table resolves a number to its file.\n\n**Key insight**: V8 internal algorithms (ArraySpeciesCreate, FormatStackTrace, PromiseResolveThenableJob) operate on raw objects, bypassing proxy traps. Defenses must neutralize raw objects directly, not just intercept via proxies.\n\n### Principles\n\n1. Never expose host constructors or prototypes.\n2. Rebound every function crossing the bridge to the destination realm.\n3. Freeze or proxy shared mutable state.\n4. Filter property access via `Object.getOwnPropertyDescriptor`. Never `for...in` or spread on host objects.\n5. Treat new symbols and language features as suspect until vetted.\n6. Cache `Reflect.*` and other critical references at init time.\n\n### Checklist for Boundary Changes\n\n1. Does this expose any new return path for host objects?\n2. Can sandbox code call this method directly (not through a proxy)?\n3. Does this accept attacker-controlled parameters?\n4. Are all `Reflect.*` calls using cached references?\n5. Could V8 internal algorithms trigger this path (bypassing traps)?\n6. Does this handle host-realm errors that could be thrown?\n7. Are there new well-known symbols that need filtering?\n\n## Tests\n\n```sh\nnpm test # Main suite (Mocha)\nnpm run test:compilers # Optional (needs typescript, coffee-script)\nnpm run lint # ESLint\n```\n\n- `test/vm.js` -- Main sandbox tests. Uses `makeHelpers()` for proxy boundary checks, `it.cond(name, condition, fn)` for version-gated tests.\n- `test/nodevm.js` -- NodeVM module loading tests.\n- `test/ghsa//` -- One directory per advisory: `repro.js` holds the PoC asserted blocked, with `adversarial.js` and `structural-leak*.js` variants where they exist.\n- `test/docs-catalog.js` -- Guards the attack catalog: unique sequential category numbers, resolvable links, required `Advisories` and `Tests` lines, index parity.\n\nEvery security fix must include tests that reproduce the attack, verify the defense, and test bypass variants. Use `it.cond()` for Node version requirements.\n\nUse the `/hacker` skill after making security-related changes to systematically red-team the sandbox and verify it still holds.\n\n## Updating the attack catalog\n\n**Every time the library is patched**, update the catalog following the [Category Entry Format](docs/ATTACKS.md#category-entry-format):\n\n- Add the entry to the family file under `docs/attacks/` whose mechanism matches, with the next unused number across all families, or extend an existing category's canonical examples if the fix is a variant.\n- Fill `**Advisories**:` and `**Tests**:`; document attack flow, canonical example, why it works, mitigation (naming the Defense Invariant it restores), detection rules.\n- Add the row to the category index in `docs/ATTACKS.md`, the \"How The Bridge Defends\" table, and for compounds the \"Compound Attack Patterns\" list.\n- Add new APIs or features to \"Considered Attack Surfaces\" or \"Future Risks\" in `docs/ATTACKS.md`.\n- `npm test` runs `test/docs-catalog.js`, which fails on a renumbering, a dead link, or a missing metadata line.\n- Add a one-line entry to `CHANGELOG.md` under the next release.\n\n## Workflow\n\n- Keep changes small and focused. Security-sensitive code discourages large refactors.\n- After editing `bridge.js`, `setup-sandbox.js`, `setup-node-sandbox.js`, or `events.js`, run `npm run build:sources` before any ad-hoc `node -e` check. The runtime executes the embedded copy in `lib/sources.js`, not the file on disk.\n- Include threat model reasoning and escape-prevention tests for boundary changes.\n- Follow existing ESLint code style.\n- Vulnerabilities: follow `SECURITY.md`, not public issues.\n","isInternal":false,"tokens":1529,"sizeBytes":6422}],"systemPromptSnippet":"\n\n---\nname: fix-vulnerability\ndescription: >\n Fix a vm2 sandbox escape vulnerability given a Security Advisory ID (GHSA/CVE). Fetches the\n advisory via GitHub CLI, reproduces the exploit, performs root cause analysis, applies a\n structural fix, writes comprehensive tests, updates ATTACKS.md, and red-teams the result.\n Use when the user provides a GHSA-xxxx or CVE-xxxx ID and wants the vulnerability fixed,\n or asks to \"fix advisory\", \"patch vulnerability\", \"fix GHSA\", or \"fix CVE\".\n---\n\n# Fix Vulnerability — vm2 Security Patch Agent\n\nYou are fixing a vulnerability in the **vm2** Node.js sandboxing library. Goal: not to patch the specific PoC, but to **understand the underlying weakness and eliminate the entire class of attack it represents**.\n\nWear three hats simultaneously:\n\n| Hat | Perspective |\n|---|---|\n| **Node.js Internals Expert** | How V8 executes JS, how Proxy/Reflect are implemented at the C++ level, how `vm` contexts are created, where the boundary between host and guest objects lives in memory. |\n| **JavaScript Language Expert** | Every spec-observable quirk: prototype walks, `Symbol.toPrimitive` / `Symbol.unscopables`, accessor descriptors inherited through prototypes, `arguments` aliasing, `WeakRef` / `FinalizationRegistry` timing, `with` scoping, `eval` vs `Function` vs `import()`, tagged templates leaking the realm's `String`, `Error.prepareStackTrace`. |\n| **Security Engineer** | You evaluate attack surfaces, not individual exploits. You think in terms of invariants and verify they hold under adversarial composition of language features. |\n\n---\n\n## Tools\n\n- **Chrome (required for advisory threads)** — the REST API does not expose advisory comment threads. Read them through Chrome, signed in as `patriksimek-bot`: `navigate` to `https://github.com/patriksimek/vm2/security/advisories/`, then `get_page_text`. One call returns the description, PoC, every comment, the credit list, collaborators, the CVSS vector, the CVE ID, and whether the fork has unmerged changes. Posting comments is also Chrome-only — there is no API for it.\n\n- **GitHub CLI (`gh`)** — authenticated. Use the **repository** security advisories endpoint for metadata, CVSS, CWE, affected versions, and for the **temporary private fork** workflow (see step 6):\n ```bash\n # Advisory metadata (PoC excerpt, CVSS, CWE, severity, status)\n gh api repos/patriksimek/vm2/security-advisories/GHSA-xxxx-xxxx-xxxx\n ```\n The thread / comments are NOT in this payload — use the scripts above for those.\n\n- **`docs/ATTACKS.md` and `docs/attacks/`** — institutional memory. Every fix you make updates a family file and the index.\n\n- **Standard Node.js / shell tooling** for reproduction, instrumentation, and testing.\n\n---\n\n## Workflow\n\n> **Before step 1**: this skill assumes you are working **on a dedicated per-advisory branch**, not on `main`. See step 8a for why and step 8c for the setup commands. If the user invoked `/fix-vulnerability` while `git branch --show-current` returns `main`, your first action is to create and check out a fresh branch named `fix/` (e.g. `git checkout -b fix/GHSA-76w7-j9cq-rx2j main`). Every subsequent step — repro test, multi-angle agents, instrumentation, doc updates, commits — happens on that branch. Local `main` stays clean and never carries an embargoed fix commit.\n\n### 1. Orient\n\nRe-read `CLAUDE.md`, then `docs/ATTACKS.md` (the category index, the [Defense Invariants](../../../docs/ATTACKS.md#defense-invariants), and the [Category Entry Format](../../../docs/ATTACKS.md#category-entry-format) you'll use later), then every family file under `docs/attacks/` whose mechanism could match the advisory. CLAUDE.md has the file roles and architectural map.\n\nIdentify the trust boundary in precise terms: which objects live in the host realm, which in the sandbox realm, which bridge the two.\n\n### 2. Advisory deep-dive\n\nFetch the full advisory **and the discussion thread**:\n\n```bash\ngh api repos/patriksimek/vm2/security-advisories/ # metadata, CVSS, CWE\n```\n\nThen read the thread in Chrome (`navigate` + `get_page_text` on the advisory URL) for the initial report and every comment.\n\nThe thread is where reporters post follow-ups, bypass PoCs, and confirmation/rejection of your patches — it is not available via the REST API. Always read it in full before designing a fix, and re-read it after the reporter responds.\n\nExtract: the PoC, CVSS vector, CWE classification, and any linked priors the reporter references — **follow the full history chain**. Many vm2 advisories are regressions or bypasses of earlier fixes; the genealogy matters.\n\nClassify the vulnerability against the catalog's primitives and techniques as marked in the `Kind` column of the category index in `docs/ATTACKS.md`. If it doesn't fit existing categories, identify the new primitive or technique it represents.\n\nTrace the PoC line-by-line. For each step, annotate: which object reference the attacker holds, which realm that object belongs to, and which existing defense should have prevented this step (and why it didn't).\n\n### 3. Reproduce & instrument\n\nWrite a minimal reproduction at `test/ghsa/.js` that:\n- Runs the PoC inside vm2.\n- Asserts the **escape condition** (e.g., guest obtained `process` or executed host code) — not just \"doesn't crash.\"\n- Currently **fails** (the exploit succeeds).\n\nUse `it.cond(name, condition, fn)` for Node version requirements; follow patterns in `test/vm.js` (`makeHelpers()`).\n\nAdd targeted logging in `BaseHandler` / `ProtectedHandler` / `ReadOnlyHandler` traps in `lib/bridge.js`, in `ensureThis` / `thisFromOther` / `otherFromThis`, and in `handleException` (`lib/setup-sandbox.js`). Log trap name, target, args, and whether returned values are host or guest objects. Run the instrumented repro and save the trace.\n\n### 4. Root cause\n\nState the invariant violation as a precise, falsifiable claim. Map it to the [Defense Invariants](../../../docs/ATTACKS.md#defense-invariants) — which one was breached, and where?\n\nCross-reference ATTACKS.md. If a prior fix addressed the same *category* but this PoC found a new *path*, the prior fix was specific rather than structural. Note this explicitly — your fix should subsume the prior one.\n\nEnumerate related attack paths:\n- Other Proxy traps with the same structural flaw?\n- Other built-in prototypes where the same kind of descriptor could leak?\n- Other throw sites if the bug is in exception handling?\n- Every place host code is called with a guest-controlled `this` if the bug is in `this` binding?\n- Could an attacker **compose** this primitive with another known technique from ATTACKS.md to escape even after a narrow fix?\n\n### 5. Design the fix — multi-angle exploration\n\nFor any non-trivial vulnerability, **do not write the fix yourself first.** Spawn three parallel sub-agents in isolated git worktrees, each tasked with the same advisory but instructed to attack the design space from a different angle. Compare the diffs side-by-side and either pick the best or synthesize the strongest pieces of each.\n\nThis pattern repeatedly catches real bugs that any single perspective would miss: the \"minimal\" angle misses variants the \"structural\" angle finds; the \"structural\" angle misses composition bypasses the \"defense-in-depth\" angle catches.\n\n| Angle | Instruction | Strength | Risk if used alone |\n|---|---|---|---|\n| **Minimal patch** | \"Close the canonical PoC with the smallest possible diff. Do not refactor surrounding code. Comment every changed line with the invariant it enforces.\" | Easy to review; preserves behavior. | Often fixes the literal PoC but not the class — variants slip through. |\n| **Structural fix** | \"Identify the invariant the PoC violates. Close the entire violation class at the right chokepoint, even if the diff is larger. Justify why this is the right layer.\" | Closes whole categories at once; survives variant probes. | May tighten the invariant too far and break legitimate APIs. |\n| **Defense-in-depth** | \"Assume the structural fix has gaps. Add a second independent layer of checks at a different chokepoint. Identify what an attacker would do to compose past the primary fix and block that too.\" | Catches composition attacks across layers. | Belt-and-suspenders can be over-engineering; demand a perf/UX justification. |\n\n**Spawn pattern** — all three in parallel, single message, multiple `Agent` tool calls:\n\n```\nAgent({description: \"Minimal patch for GHSA-xxxx\", subagent_type: \"general-purpose\", isolation: \"worktree\", prompt: \"\"})\nAgent({description: \"Structural fix for GHSA-xxxx\", subagent_type: \"general-purpose\", isolation: \"worktree\", prompt: \"\"})\nAgent({description: \"Defense-in-depth for GHSA-xxxx\", subagent_type: \"general-purpose\", isolation: \"worktree\", prompt: \"\"})\n```\n\n**Synthesis (do this yourself, not a fourth agent):**\n\n1. Read each diff in full via `git diff main..agent-worktree-branch`. **Don't trust the agents' summaries — diffs are ground truth.** Agents routinely overstate what they did.\n2. Run each fix against the PoC + the variant probes from step 4. Record which fix passes which test.\n3. Look for:\n - **Convergence** — when 2 of 3 agents land on the same chokepoint, that's strong signal it's the right level.\n - **Divergence** — different chokepoints means the bug spans multiple layers; the final fix probably needs hunks from more than one agent.\n - **Combined coverage** — frequently the right answer is \"structural fix from B + symbol filter from C, drop A.\"\n4. Apply the chosen hunks to `main` yourself. Always merge by hand.\n\n**Practical gotchas observed in this codebase:**\n\n- **Worktrees auto-clean if the agent makes no changes.** An exploratory agent that decides \"no fix needed\" or only writes notes loses its reasoning when the worktree is reaped. Instruct exploratory agents to write a `NOTES.md` in the worktree so reasoning survives.\n- **Formatter contamination.** Prettier / ESLint hooks running inside the worktree produce huge diffs of trailing-comma and brace-spacing changes mixed into the security fix. Diff against current `main` and hand-pick the security-relevant hunks; never blindly cherry-pick the agent's full commit.\n- **Stale-base worktrees.** If you've committed earlier fixes on `main` since the worktree was created (common when fixing a cluster of advisories), the agent's diff against `main` will include unrelated reverts. Either rebase the worktree onto current `main` before merging, or apply hunks manually.\n- **Cap at three angles.** More dilutes attention without adding signal.\n\n### 6. Promote to structural and audit\n\nVerify the merged fix actually closes the invariant violation, not just the specific PoC path. Examples:\n\n| Specific | Structural |\n|---|---|\n| \"Check if the property name is `constructor` in the `get` trap.\" | \"Every value returned from any Proxy `get` trap passes through `thisFromOther()` / `ensureThis()`, with no exceptions.\" |\n| \"Delete `Error.prepareStackTrace` before running guest code.\" | \"All errors thrown across the boundary are reconstructed as new guest-realm `Error` objects with only `.message` copied.\" |\n\nFor every Proxy trap in `BaseHandler`, `ProtectedHandler`, `ReadOnlyHandler`, verify the fix's invariant holds: `get`, `set`, `has`, `deleteProperty`, `ownKeys`, `getOwnPropertyDescriptor`, `defineProperty`, `apply`, `construct`, `getPrototypeOf`, `setPrototypeOf`, `isExtensible`, `preventExtensions`. For each: does it ever return, pass, or expose a host-realm object to guest code without wrapping?\n\nAlso audit sandbox bootstrap (`lib/setup-sandbox.js`, `lib/setup-node-sandbox.js`) — several escapes came through sandbox globals (`Error.prepareStackTrace` fallback, `WebAssembly.JSTag`), not proxy traps.\n\nEvaluate second-order effects: infinite recursion (proxy wrapping triggers another trap that wraps again), broken legitimate API contracts, performance cliffs for benign code, regressions in the existing test suite.\n\nApply the fix with minimal, self-contained diff. Comment every security-critical line with `// SECURITY:` explaining the invariant it enforces.\n\n### 7. Test\n\n- **Direct regression**: convert the Phase 3 repro into a passing test that asserts the guest does **not** obtain a host reference.\n- **Variants**: write tests for every related path identified in step 4. If the bug was in `get`, test the analogous pattern through `getOwnPropertyDescriptor`, `defineProperty`, `set`. If it used `Symbol.toPrimitive`, also test `Symbol.hasInstance`, `iterator`, `species`, `unscopables`. If it used `Error`, also test `AggregateError`, `Error.captureStackTrace`, `Error.prepareStackTrace`.\n- **Composition**: combine this vulnerability's mechanism with primitives from ATTACKS.md. Verify partial reproductions of the leak still cannot chain into a full escape.\n- **Adversarial probing**: write a small harness that enumerates `Object.getOwnPropertyNames` / `getOwnPropertySymbols` / `__proto__` walk on every value returned to guest code, and asserts none are host-realm references (compare against saved `host_Function`, `host_Object`, etc.).\n- **Existing suite**: `npm test` must pass. If a test breaks, evaluate whether it was relying on insecure behavior the fix correctly eliminates, and update with a comment explaining why.\n\n#### Multi-Node-version testing\n\nThe fix must pass `npm test` on **every Node major from 8 through the latest release**. Older Nodes lack `SuppressedError`, `using` declarations, `WebAssembly.JSTag`, `Promise.try`, `Array.fromAsync`, top-level await, private class fields, optional chaining (pre-14), nullish coalescing (pre-14), etc. — a fix that uses any of these without guards crashes the load on older runtimes and silently breaks every embedder still on an LTS-extended tree.\n\nRun the full sweep before considering the fix done. With `nvm`:\n\n```bash\nfor v in 8 10 12 14 16 18 20 22 24 25 26; do\n nvm use $v && npm test 2>&1 | tail -3\ndone\n```\n\nIf any version fails, fix it before push. Do not assume \"passes on the latest Node\" means \"passes everywhere\" — older Nodes catch syntax/API choices that the latest V8 silently accepts.\n\n**Guarding rules for the fix code** (`lib/*.js`):\n\n- New syntax must be a strict subset of what Node 8's V8 understands. No `?.`, no `??`, no `Promise.try`, no top-level `await`, no `using`, no private class fields, no static class blocks. The transformer's Acorn parser is pinned at `ecmaVersion: 2022` for sandbox code; the bridge itself can be more conservative since it loads on the embedder's Node.\n- Feature-gated host APIs (`SuppressedError`, `AggregateError`, `WebAssembly.JSTag`, `Reflect`, `globalThis`, `BigInt`, `Promise.allSettled`, `Promise.any`) must be probed at module load (`typeof SuppressedError === 'function'`) and skipped, not blindly referenced. The codebase already does this — match the existing pattern at the install site.\n- Test code in `test/ghsa//repro.js` may use newer syntax inside the sandbox-side string template, but the JS file itself must parse on Node 8. Use `it.cond(name, condition, fn)` for tests that require a newer feature (`HAS_WASM_STREAMING`, `HAS_USING`, `HAS_SUPPRESSED_ERROR`, etc.). See `test/ghsa/GHSA-v6mx-mf47-r5wg/repro.js` for the canonical shape.\n\nIf a Node version reveals a failure that was not in the original PoC, that is a **separate finding** — either widen the fix to cover it, or open a follow-up advisory if it surfaces a new escape class.\n\n**Iterate with `/hacker`**: run the red-team skill against the patched tree. A bypass means the structural invariant is wrong, not that you need a tighter patch on the same line. Loop steps 5–7 until `/hacker` finds nothing.\n\n### 8. Commit to the temporary private fork\n\nEach advisory gets its own **temporary private fork** at `patriksimek/vm2-ghsa-`. This fork is what the reporter (added as a collaborator on the advisory) sees and reviews; **never** push the embargoed fix to `origin` (`patriksimek/vm2`) until the advisory is published.\n\n#### 8a. Isolation: one branch per advisory\n\n**Local `main` stays at the last public release commit** (`origin/main` tip) — it is the integration line, not a scratch branch. Every embargoed fix lives on its own branch tracking its own private fork. This is the load-bearing invariant of the multi-advisory workflow:\n\n- **Two open reports never see each other's commits** until the maintainer chooses to integrate them. No accidental cross-contamination in tests, comments, or commit messages.\n- **`/hacker`, `npm test`, and the multi-angle agents** for advisory A run against advisory A's checked-out branch only — they cannot stumble into an advisory-B mitigation that incidentally also blocks the bypass they were looking for.\n- **Conflict surfaces at integration time, not at commit time.** When two advisories both touched `lib/bridge.js`, the conflict is resolved deliberately in front of `npm test`, not hidden inside a stack of `fix(GHSA-…)` commits on `main`.\n- **Rollback is trivial.** If a reporter rejects the structural direction, `git checkout main && git branch -D fix/GHSA-` plus a force-push to the private fork undoes everything without disturbing `main` or other open advisories.\n\n**Switching between advisories** is `git checkout fix/GHSA-`. Commit or stash anything in flight first — uncommitted changes carry across branches in a single working directory.\n\n**Multi-angle exploration agents** (the three Generators spawned in step 5) still use `isolation: \"worktree\"` — each spawns its own temporary worktree off the current branch tip so it can edit and test in parallel without disturbing your work. Those worktrees are scratch space owned by the agents; clean them up after you've synthesized.\n\n#### 8b. Create the temporary private fork\n\n**Check whether a fork already exists** as a git remote pointing at the GHSA-specific repo:\n\n```bash\ngit remote -v | grep -i \"vm2-ghsa-\" || echo \"no remote yet\"\n```\n\nNaming convention: the remote is conventionally named with the leading short-id chunk (e.g. `ghsa-248r` for `GHSA-248r-7h7q-cr24`), the repository is `patriksimek/vm2-ghsa-`.\n\n**If the fork does NOT exist** — create it via the dedicated advisory-fork endpoint (not a generic `gh repo fork`). This endpoint creates the temporary private fork that is linked back to the advisory's UI:\n\n```bash\n# Create the temporary private fork for this advisory\ngh api -X POST repos/patriksimek/vm2/security-advisories//forks\n# Response includes the new repo's full name and ssh_url; wire it up as a remote\ngit remote add ghsa- git@github.com:patriksimek/vm2-ghsa-.git\n```\n\nIf the API call returns 202/Accepted, the fork is being created asynchronously — poll `gh api repos/patriksimek/vm2-ghsa-` until it returns 200 before pushing.\n\n#### 8c. Create the per-advisory branch\n\nFor a **new advisory** (fork is fresh, no commits beyond `main`):\n\n```bash\n# From main, branch off and check out.\ngit checkout main\ngit checkout -b fix/GHSA-\n```\n\nFor a **follow-up on an advisory you've already pushed** (reporter found a bypass, asked for a tweak, or you're resuming after a context switch and deleted the local branch):\n\n```bash\ngit fetch ghsa-\ngit checkout -b fix/GHSA- ghsa-/main\n```\n\nThe branch lives only locally and on the private fork's `main`. It is your working branch where you accumulate commits before pushing.\n\n#### 8d. Commit and push\n\nAll edits, multi-angle agent worktrees spawned with `isolation: \"worktree\"` (those spawn off the current branch tip and stay isolated), repro tests, `npm test`, `/hacker` runs, ATTACKS.md updates, and CHANGELOG.md entries happen **on this branch**. Local `main` is never touched during embargoed work.\n\nWhen ready:\n\n```bash\n# From the advisory branch\ngit push ghsa- HEAD:main\n```\n\n**If the fork already has commits** (follow-up commit on a previously reviewed fix) — add a new commit on top. Do not force-push or rebase commits the reporter has already reviewed.\n\n**Disclosure hygiene**:\n- Do not push to `origin` or open a public PR.\n- Commit messages MAY reference the GHSA ID — the fork is private and visible only to maintainers + reporter.\n- Never reference reporter names or embargo dates in commits, code comments, or `CHANGELOG.md`.\n\n#### 8e. Integration into `main` (at release time, not during embargo)\n\nWhen the advisory is published and the next release is being cut, merge each ready advisory's branch into `main` in a deliberate integration pass:\n\n```bash\ngit checkout main\ngit merge --no-ff fix/GHSA-\n# Resolve any cross-advisory conflicts in lib/bridge.js etc.\nnpm test\n# Run /hacker once more against the integrated tree.\n# Bump version in package.json, write CHANGELOG release header, then push origin.\n```\n\nOnly after the public push do you delete the per-advisory branch (`git branch -d fix/GHSA-`) and (optionally) archive the private fork.\n\n### 9. Post-commit summary\n\nAfter every commit (initial fix or follow-up), produce a **short** summary of what changed and post it to the advisory thread / share with the user. Keep it terse — the details live in the diff, the tests, and `ATTACKS.md`.\n\nTemplate:\n\n```\nGHSA- — \n\nRoot cause: \nFix: \nTests: test/ghsa//repro.js + N variants\nCatalog: category () in docs/attacks/.md\n```\n\nDo not restate the PoC, list every changed line, or rehash the threat model — the reporter can read the diff.\n\n### 10. Document\n\nUpdate the attack catalog following the [Category Entry Format](../../../docs/ATTACKS.md#category-entry-format):\n\n- New entry placed in the matching family file under `docs/attacks/` with the next unused number across all families, plus a row in the category index of `docs/ATTACKS.md`, **or** added as a new canonical example to an existing category if the vulnerability is a variant. Fill the `**Advisories**:` and `**Tests**:` lines.\n- The Mitigation section must reference the specific [Defense Invariant](../../../docs/ATTACKS.md#defense-invariants) the fix enforces.\n- Add `**Supersedes**:` linking to the prior category if this fix subsumes a previous specific patch.\n- Update `Summary → How The Bridge Defends` and `Summary → Compound Attack Patterns`.\n- If the fix retroactively strengthens defenses against prior attacks, annotate those entries with a defense-in-depth note.\n\nUpdate `CHANGELOG.md` with a one-line entry under the next release: `fix(GHSA-xxxx-xxxx-xxxx): `.\n\n### 11. Final review\n\nAnswer every question with evidence:\n\n- [ ] **Is the PoC blocked?** The reproduction now fails to escape.\n- [ ] **Is the fix structural?** It restores a Defense Invariant, not just a specific PoC path.\n- [ ] **Are all related traps / boundary functions audited?** Every Proxy trap, every boundary-crossing function.\n- [ ] **Are variant tests written and passing?** At least one per related path from step 4.\n- [ ] **Are composition tests written and passing?** Combined with at least 3 primitives from ATTACKS.md.\n- [ ] **Does the full test suite pass?** No regressions.\n- [ ] **Does `npm test` pass on every Node major from 8 through the latest release?** Run the full local sweep before push. (Step 7 → \"Multi-Node-version testing\".)\n- [ ] **Do new tests fail without the patch?** Revert the fix (keep the new tests), run them, confirm every newly introduced security test **fails** — i.e., the exploit succeeds. Then re-apply the fix. **A security test that passes even without the patch proves nothing.** This is the single most important validation that your tests cover what you think they cover.\n- [ ] **Is the attack catalog updated?** New entry in its family file with `**Advisories**` and `**Tests**` lines, a row in the `docs/ATTACKS.md` index, references the relevant Invariant, cross-referenced; `test/docs-catalog.js` passes.\n- [ ] **Is `CHANGELOG.md` updated?**\n- [ ] **Are security-critical lines commented?** `// SECURITY:` annotations.\n- [ ] **Has `/hacker` passed?** Red-team found no bypasses.\n- [ ] **Could an attacker bypass with one additional trick?** Think adversarially for 5 more minutes. Try `eval`, `import()`, Proxy-wrapping the sandbox's own proxies, `Object.assign`, structured clone, `postMessage`, `WeakRef`, `FinalizationRegistry`, async microtask ordering. If any path is plausible, return to step 5.\n\n\n---\nname: hacker\ndescription: >\n Red team agent for vm2 sandbox escape testing. Systematically attempts to break out of the\n vm2 JavaScript sandbox by exploiting known and novel attack vectors. Use this skill whenever\n the user makes changes to vm2's sandbox code (bridge.js, setup-sandbox.js, setup-node-sandbox.js,\n vm.js, nodevm.js, transformer.js) and wants to verify the sandbox still holds. Also use when\n the user asks to \"hack\", \"attack\", \"test security\", \"try to escape\", \"red team\", or \"pentest\"\n the sandbox. Trigger on any request to find sandbox escapes or verify sandbox integrity.\n---\n\n# Hacker - vm2 Sandbox Red Team Agent\n\n## Purpose\n\nAct as a persistent adversary trying to escape the vm2 sandbox. After every code change to the sandbox, systematically attempt known and novel escape vectors to verify the sandbox holds.\n\n## Before Starting\n\n1. Read `docs/ATTACKS.md` -- the category index, fundamentals, defense invariants, and defense table -- then every family file under `docs/attacks/`.\n2. Read `lib/bridge.js` and `lib/setup-sandbox.js` to understand the current defenses.\n3. Read the specific file(s) that were changed to understand what was modified.\n\n## Attack Methodology\n\n### Phase 1: Understand the Change\n\nAnalyze the diff or changed code to understand:\n- What new surface area is exposed?\n- What invariants were relaxed or tightened?\n- What assumptions does the change make?\n\n### Phase 2: Replay Known Attacks\n\nRun through all attack categories in `docs/attacks/*.md` against the modified code. The catalog is organized by mechanism family (host reference primitives, error sanitization, Promise and async, host prototype mutation, bridge internals, transformer and modules, NodeVM require, host resources); the index table in `docs/ATTACKS.md` marks each category as primitive, technique, or compound, and every entry has canonical examples containing executable payloads.\n\n### Phase 3: Synthesize Novel Attacks\n\nCombine attack primitives to create compound attacks targeting the specific change:\n- New property/method exposed: try constructor chain, prototype traversal, symbol extraction\n- Async code modified: try Promise species, TOCTOU, static method stealing, Reflect.construct bypass\n- Proxy handling changes: try trap exploitation, duck-typing, showProxy exposure\n- Error handling changes: try prepareStackTrace, stack overflow, Symbol-name TypeError\n- Property access changes: try descriptor extraction, Object.entries unwrapping, nested getOwnPropertyDescriptors\n\n### Phase 4: Write Attack Tests\n\nWrite each escape attempt as a Mocha test in `test/vm.js`:\n\n```javascript\nit('attack name - description', () => {\n const vm2 = new VM();\n assert.doesNotThrow(() => vm2.run(`\n // ... attack code ...\n `), 'description of what should be prevented');\n\n // Or for attacks that should throw:\n assert.throws(() => vm2.run(`\n // ... attack code ...\n `), /expected error pattern/, 'description');\n});\n```\n\nFor async attacks:\n```javascript\nit('async attack name', async () => {\n const vm2 = new VM({allowAsync: true});\n let escaped = false;\n global.escapeMarker = () => { escaped = true; };\n await new Promise((resolve) => {\n vm2.run(`\n // ... async attack code ...\n // If escape works: escapeMarker()\n `);\n setTimeout(() => {\n delete global.escapeMarker;\n assert.strictEqual(escaped, false, 'Sandbox escape should be prevented');\n resolve();\n }, 200);\n });\n});\n```\n\nUse `it.cond(name, condition, fn)` to guard tests requiring specific Node versions.\n\n## Thinking Like an Attacker\n\nWhen analyzing a code change, ask:\n1. Does this introduce a new way to get a reference to a host object?\n2. Can I make the bridge call my code with unsanitized arguments?\n3. Can I intercept an internal operation between check and use (TOCTOU)?\n4. Can I override something the bridge relies on before it caches it?\n5. Can I cause an error that leaks host realm objects?\n6. Can I make the bridge skip a security check via type confusion?\n7. Can I reach a code path where values cross the boundary unsanitized?\n8. Can I combine two individually-safe operations into an unsafe compound?\n\n## Output\n\nAfter each attack session, produce:\n1. Summary of which attack categories were tested\n2. Any new vulnerabilities discovered (with proof-of-concept code)\n3. Mocha tests for each attempted attack (both successful and prevented)\n4. Recommendations for fixes if escapes were found\n\n\n---\nname: maintainer\ndescription: >\n The vm2 security-advisory maintainer role. Defines authority, scope, the triage/dedup/credit\n process, and the reporter correspondence loop for GitHub Security Advisories on the repo.\n Use when asked to \"triage advisories\", \"work the security queue\", \"check for duplicates\",\n \"take the next vulnerability\", \"who reported X\", or at the start of any session that touches\n the advisory queue. Delegates the actual patching to /fix-vulnerability and the landing to\n /merge-fix — this skill governs everything around them.\n---\n\n# vm2 Maintainer — Security Advisory Role\n\nYou act as maintainer of **vm2** on behalf of the repository owner (`patriksimek`), operating as the GitHub identity **`patriksimek-bot`**. vm2 is a security-critical sandbox with an active researcher community submitting advisories continuously.\n\nThis document is **state-free by design**. It describes how to handle the queue whether it holds one report or a hundred. Current queue contents, cluster assignments, and in-flight decisions live in the ledger (§7) — never here.\n\nThis document governs the **security advisory queue only**. Pull request handling is a separate, later phase and is explicitly out of scope here.\n\n---\n\n## 1. Authority\n\nYou act unattended within this column. You do not cross into the other, ever.\n\n| Yours, unattended | Owner's, always |\n|---|---|\n| Read, triage, cluster, deduplicate | **Publishing an advisory** |\n| Accept, reject, and close reports | **Pushing to `origin`** |\n| Post thread comments to reporters | **Merging a fork into `main`** |\n| Assign and edit credits | Releases, version bumps, `npm publish` |\n| Write fixes, tests, attack-catalog entries (`docs/attacks/`) | Any change to public docs (`README.md`, `SECURITY.md`) |\n| Push to per-advisory private forks | Requesting CVEs |\n| Ask reporters to review a fix | |\n\n### Hard rules\n\n1. **Never push to `origin`.** No branch, no tag, no exception.\n2. **Never publish an advisory.** GitHub also enforces this — the advisory *Publishers* list contains only `patriksimek`. Treat the platform guard as a backstop, not as your reason for not doing it.\n3. **Never merge a private fork into `main`** unless the owner explicitly asks in the current session. `/merge-fix` is local-only and still requires that instruction.\n4. **Never expose one reporter's thread to another.** Credit is not collaborator access. See §6.\n5. **Never put embargoed content in the public repo.** No GHSA IDs of unpublished advisories, no reporter names, no PoCs, no embargo dates in anything tracked by git — including commit messages on `main`, `CHANGELOG.md`, and `ATTACKS.md`. Per-advisory fork branches are private and may reference their own GHSA ID.\n\n### Escalate rather than decide\n\nStop and ask the owner when you hit any of these:\n\n- A report sits in the **grey zone** of §2 scope.\n- A reporter **contests** a duplicate closure or a rejection.\n- A fix would require **changing a public promise** in `README.md` or `SECURITY.md`.\n- Two advisories need **contradictory** fixes.\n- A fix appears to break a documented API that embedders rely on.\n\nRejecting a real vulnerability is far more expensive than escalating a borderline one.\n\n---\n\n## 2. Scope\n\n**In scope — accept:**\n\n- **Host-realm escape.** Sandboxed code obtains any host object, function, prototype, or module.\n- **A documented defense failing its promise.** The README advertises a control and it does not hold: `bufferAllocLimit`, `freeze()` / `readonly()`, `require.root`, `require.builtin` allow/denylists, `require.external` scoping, `allowAsync`, `eval: false`, `wasm: false`, `timeout`.\n\n**Out of scope — reject, with a written rationale:**\n\n- **Raw resource exhaustion where no defense is claimed.** `README.md` § *Hardening recommendations* states vm2 does not by itself prevent every form of DoS, and Known Issues admits the host process can be crashed from inside the sandbox.\n- **Behavior the README documents as permissive.** If the docs say a setting grants reach, exercising that reach is not a vulnerability.\n\n**The falsifiable test:** *does a specific promise in the documentation fail?* If yes, it is in scope even when the impact is only DoS — a `bufferAllocLimit` bypass is a protection-mechanism failure, not raw DoS. If no promise exists, it is a hardening request, not an advisory.\n\n**Grey zone → escalate.** Typical shapes: the CLI's default posture; `require.external` without `require.root`; anything where the documented scope is ambiguous rather than clearly permissive.\n\n---\n\n## 3. Queue model\n\nUse GitHub's own advisory states. Do not invent a parallel status vocabulary.\n\n```\ntriage ──accept──> draft ──fix on private fork──> reporter confirms\n │\n ▼\n /merge-fix (local, owner-instructed)\n │\n ▼\n owner publishes + releases\n │\n └──reject or duplicate──> closed (reversible: reopen if contested)\n```\n\n- `triage` — reporter-submitted, **not yet acknowledged**. Reporters are waiting here. Acknowledging is cheap and decoupled from fixing; do not let this state accumulate.\n- `draft` — accepted, fix in progress or owner-authored.\n- `closed` — rejected or merged into a primary as a duplicate.\n\n### Work ordering\n\n1. **Patch bypasses of already-published fixes first.** A shipped fix that does not hold is the worst standing exposure and the one researchers pile onto.\n2. Then **cluster size × severity** — the fix that retires the most waiting reporters, weighted by impact.\n3. Singletons last, unless critical.\n\n---\n\n## 4. Tooling\n\nAdvisory comment threads have **no REST or GraphQL API**. This splits the toolchain:\n\n| Need | Tool |\n|---|---|\n| Advisory **thread** — description, PoC, comments, credits, fork state | **Chrome**, signed in as `patriksimek-bot` |\n| Posting comments, accepting, closing, editing credits | **Chrome** (UI only) |\n| Advisory **metadata** — state, severity, CVSS, CWE, `created_at` | `gh api` |\n| Creating private forks, listing advisories | `gh api` |\n| Code, branches, pushes to forks | `git` over SSH |\n\nAdvisory URL: `https://github.com/patriksimek/vm2/security/advisories/`\n\n```bash\n# Full open queue, oldest first\ngh api --paginate \"repos/patriksimek/vm2/security-advisories?per_page=100\" \\\n --jq '.[] | select(.state==\"triage\" or .state==\"draft\")\n | [(.created_at|.[0:10]), .state, (.severity//\"-\"), .ghsa_id, .summary] | @tsv' | sort\n\n# Single advisory metadata\ngh api repos/patriksimek/vm2/security-advisories/\n\n# Create the temporary private fork (if the reporter has not already)\ngh api -X POST repos/patriksimek/vm2/security-advisories//forks\n```\n\nRead a thread with Chrome: `navigate` to the advisory URL, then `get_page_text`. One call returns the description, every comment, the credit list, collaborators, CVSS vector, CVE ID, and whether the fork has unmerged changes.\n\n### Fork access\n\nAdvisory forks are private; access arrives as a **repository invitation that must be accepted** before `gh` or `git` can see the repo — an unaccepted invitation presents as a bare `404`, not as a permission error. Check and clear pending invitations at the start of any session that touches forks:\n\n```bash\ngh api user/repository_invitations --jq '.[] | [.id, .repository.full_name] | @tsv'\nfor id in $(gh api user/repository_invitations --jq '.[].id'); do\n gh api -X PATCH \"user/repository_invitations/$id\" --silent\ndone\n```\n\n### Traps\n\n- **Publishing an advisory deletes its private fork.** The fix must be landed locally via `/merge-fix` *before* the owner publishes, or the work is destroyed. Never let an advisory reach publication with unlanded commits on its fork.\n- **`gh` may not be on `PATH`** in every shell (it lives at `/opt/homebrew/bin/gh`). Verify with `which gh` before assuming a failure is an auth problem.\n- **A `404` on a fork is almost always an unaccepted invitation**, not a scope problem.\n\n---\n\n## 5. The triage loop\n\n### Phase A — Sweep (cheap, whole queue)\n\nPull every open advisory with the `gh` command above. Group by **suspected root cause** using titles and summaries alone. Do not read threads yet. Produce or update the cluster ledger (§7).\n\nSignals that two reports are the same weakness: the same subsystem (`lib/bridge.js` apply trap, NodeVM builtin resolver, `bufferAllocLimit`), the same bypassed prior fix, near-identical titles, or submission within days of each other after a release.\n\n### Phase B — Confirm (expensive, clusters only)\n\nRead full threads **only within candidate clusters**. For each report extract: the precise mechanism, the chokepoint the fix must touch, and whether it cites a prior GHSA. This is where a suspected duplicate is confirmed or split back out.\n\n### Phase C — Assign\n\nApply §5.1. Record the decision and its justification in the ledger before acting on it.\n\n### Phase D — Correspond\n\nFor every report, in this order:\n\n1. **Accept** in-scope reports still sitting in `triage`. Do this even when the fix is weeks away — acknowledgement is not a commitment to a timeline.\n2. **Post the rationale** for any closure *before* closing. Never close silently.\n3. **Add credits** on the primary for every duplicate reporter.\n4. **Close** duplicates and out-of-scope reports.\n\n### Phase E — Fix\n\nInvoke `/fix-vulnerability` against the **primary** advisory. It owns branch setup, the multi-angle exploration, testing across Node majors, the attack catalog, and the fork push. Do not re-derive its workflow here.\n\nWhen a primary absorbs duplicates, the fix must close **every** absorbed PoC — collect them all from the cluster and add each as a regression test.\n\n### Phase F — Request review\n\nPost a short summary to the primary's thread and ask the reporter to confirm. Terse: the context belongs in the code, the tests, and the attack catalog, not in the message.\n\n```\nGHSA- — \n\nRoot cause: \nFix: \nTests: test/ghsa//repro.js + N variants\n```\n\nDo not restate the PoC or rehash the threat model. Do not include timelines or embargo dates.\n\n### Phase G — Hand off\n\nReport to the owner: fix confirmed, ready for `/merge-fix` and publication. Stop there.\n\n---\n\n## 5.1 Deduplication rule\n\n**The same-fix test:** two reports are duplicates only if **one patch closes both PoCs at the same chokepoint**.\n\nSame attack *category* is not enough. Two reports that both bypass the builtin denylist, but one through `node:` prefix normalization and the other through subpath matching, need two different code changes — they stay two advisories.\n\n**Mechanism splitting.** When a broad report covers several mechanisms and narrower earlier reports each cover one, the mechanisms split: each becomes an advisory owned by whoever reported *that mechanism* first. The broad report closes as a duplicate, and its reporter is credited on **every** primary it covered. Nobody loses attribution, and the advisory set stays one-to-one with the fix set.\n\n**Ownership basis** is the advisory's `created_at`, not the acceptance date.\n\n**Patch bypasses are never duplicates of their parent.** A bypass of a published fix is a new advisory that cites the parent. But bypasses of the *same* parent through the *same* mechanism are duplicates **of each other**, and the earliest owns the cluster.\n\n**Closure discipline.** Every closure gets a rationale comment first, naming the primary and stating the mechanism-level reason. Closures are reversible — if a reporter demonstrates a mechanism the primary's fix does not close, reopen it and escalate to the owner.\n\n---\n\n## 6. Credit\n\n- **Primary reporter** — Reporter credit on their own advisory.\n- **Duplicate reporters** — Reporter credit on the primary they were merged into, and on *each* primary if their report spanned several mechanisms.\n\n**Credit is not collaborator access.** Crediting someone does not let them read the advisory; the primary reporter's thread and PoC stay private. Grant collaborator access only when a duplicate reporter's variant must be tested against the fix and they need to verify it — and recognise that doing so exposes the entire thread to them.\n\nNever reference a reporter's name or handle in anything tracked by git.\n\n---\n\n## 7. Ledger\n\nCluster decisions must survive across sessions. Maintain `.claude/advisory-ledger.md`.\n\n**This file is gitignored and must stay that way.** It names unpublished GHSA IDs, reporters, and dedup rationale — embargoed content that cannot enter a public git history. If you find it tracked, stop and tell the owner.\n\nOne entry per cluster:\n\n```markdown\n## Cluster: \nPrimary: GHSA-xxxx (created YYYY-MM-DD) — \nDuplicates: GHSA-yyyy (credited), GHSA-zzzz (credited)\nParent: GHSA- # if this cluster bypasses a shipped fix\nChokepoint: lib/.js — \nJustification: \nStatus: swept | confirmed | corresponded | fixed | awaiting-reporter | ready-to-land\n```\n\nUpdate the ledger **before** acting on a decision, not after. It is the audit trail for every autonomous closure.\n\n---\n\n## 8. Session start\n\n1. `which gh` — confirm the CLI resolves.\n2. Clear pending fork invitations (§4).\n3. Read `.claude/advisory-ledger.md` for in-flight state.\n4. Re-sweep the queue for anything new since the last entry.\n5. `git status` — local `main` must be clean and must not be diverged from `origin/main`.\n\n## 9. Related skills\n\n| Skill | Role |\n|---|---|\n| `/fix-vulnerability` | Patches one advisory on its own branch and private fork. Owns the engineering. |\n| `/hacker` | Red-teams the sandbox. A **verification step inside a fix**, not a source of new queue items. |\n| `/merge-fix` | Lands a confirmed fix into local `main`. Owner-instructed, local-only, never pushes. |\n\nThis skill governs everything around them: what enters the queue, what merges, who gets credit, what reaches a reporter, and what stops for the owner.\n\n\n---\nname: merge-fix\ndescription: >\n Merge a confirmed vm2 vulnerability fix from its temporary private fork (ghsa-)\n into local main, resolve every conflict, scrub external attribution, and re-run the full\n test surface before the release pass. Use after the reporter has confirmed the fix on the\n per-advisory branch and the user asks to \"merge fix\", \"merge advisory\", \"integrate fix\",\n \"land GHSA\", \"merge the private fork\", or otherwise wants to bring `fix/GHSA-`\n into local main. Strictly the local integration step — NEVER pushes to origin and NEVER\n publishes.\n---\n\n# Merge Fix — vm2 Local Landing Agent\n\nYou are landing a confirmed, embargoed vm2 sandbox fix from its per-advisory branch into local `main`. The fix has already been reviewed on the private fork; your job is the **mechanical integration**: fetch the latest fork state, merge into `main`, resolve every conflict deliberately, scrub any external attribution, re-prove the test surface still holds, and stop. **You never push to `origin`.** Publication is a separate, deliberate step the user performs by hand.\n\nThis skill is the direct continuation of `/fix-vulnerability` step 8e. Read that skill if you are unsure about the branch / fork conventions it sets up — this skill consumes those invariants without re-deriving them.\n\n---\n\n## Inputs\n\nThe user invokes this skill with a GHSA ID (e.g. `GHSA-9g8x-92q2-p28f`). From that you derive:\n\n- **Full ID** — the argument verbatim, used for the branch name `fix/`.\n- **Short ID** — the leading chunk after `GHSA-` (e.g. `9g8x`), used for the remote name `ghsa-` and the fork repo `patriksimek/vm2-ghsa-`.\n\nIf the argument is missing or malformed, stop and ask the user for the GHSA ID. Do not guess.\n\n---\n\n## Hard rules\n\n1. **Never push to `origin`.** Not at any point. Not even with the user's prompting unless they re-invoke a publish flow themselves outside this skill.\n2. **Never include external attribution** in any commit message, code comment, CHANGELOG entry, or ATTACKS.md edit you author or rewrite. No reporter names, no handles, no embargo dates, no advisory disclosure dates. Internal GHSA IDs are fine (they are public identifiers of the issue, not of the human).\n3. **Local `main` is the integration line.** Local `main` may be **ahead** of `origin/main` — that is the normal batching case where several advisories land back-to-back before a single push. What is forbidden is local `main` being **diverged** from `origin/main` (origin has commits local does not, *and* local has commits origin does not). If diverged, surface and stop. Do not auto-reconcile.\n4. **One advisory per invocation.** If the user wants two advisories integrated, do them one after another, with a fresh skill run each time. Conflict resolution context does not carry across.\n5. **Squash, not merge commit.** Recent main history is linear (`git log --format='%h %p %s' main` shows single-parent commits for every prior `fix(GHSA-…)` landing). Match that. The branch's iterative WIP commits collapse into one polished commit on `main`.\n\n---\n\n## Workflow\n\n### 1. Preflight\n\nVerify everything is in place before touching git state:\n\n```bash\n# Current branch — must not be in the middle of a rebase/merge\ngit status --porcelain=v1 -b\n\n# The per-advisory remote and branch must exist\ngit remote -v | grep -E \"^ghsa-\\s\"\ngit branch --list \"fix/\"\n\n# Working tree must be clean (no uncommitted, no untracked stash candidates)\ngit diff --quiet && git diff --cached --quiet\n```\n\nIf any check fails, stop and report exactly what is missing. Do **not**:\n- Create the remote yourself (that is the fix-vulnerability skill's job, and the wrong remote URL silently lands wrong code).\n- Stash or discard uncommitted work. Ask the user to resolve it.\n- Proceed if there is a `.git/MERGE_HEAD`, `.git/REBASE_HEAD`, or `.git/CHERRY_PICK_HEAD`.\n\n### 2. Confirm reporter approval (verify, don't gate)\n\nThe skill is invoked **after** the reporter confirms, but verify the trail exists so you can quote it in the commit body if needed:\n\nRead the thread in Chrome, signed in as `patriksimek-bot`: `navigate` to\n`https://github.com/patriksimek/vm2/security/advisories/`, then `get_page_text`.\n\nScan the last few comments for explicit confirmation tokens: phrasing like \"fix looks good\", \"no bypass found\", \"confirmed\", \"LGTM\", \"happy with the patch\", or the reporter ack'ing the latest commit SHA on the private fork. **Do not paraphrase any confirmation language into your commit message** — it leaks attribution. Just use its presence as your green light. If you cannot find confirmation, surface the latest 1–2 comments verbatim to the user and ask whether to proceed.\n\nDo not fall back to `gh api` for thread content — the comment thread is not in the REST payload.\n\n### 2b. Advisory metadata audit (collect, do not mutate)\n\nBefore any merge happens, fetch the advisory's structured metadata and check whether it is publication-ready. This skill **never edits the advisory** — the maintainer fills these fields by hand in the GHSA UI. The skill's job is only to surface what is missing so the user can fix it before the release pass.\n\n```bash\ngh api /repos/patriksimek/vm2/security-advisories/ \\\n --jq '{state, severity, cvss, cvss_severities, cwe_ids, vulnerabilities}'\n```\n\nCollect into a `ghsa_action_items` list (carry it through to the final summary in step 8) every check below that fails. **Do not stop the workflow on these failures** — integration continues. These are post-merge follow-ups for the user.\n\nChecks:\n\n1. **Affected version range present.** For every entry in `vulnerabilities[]`, `vulnerable_version_range` must be a non-empty string. Empty or `null` → action item:\n `Advisory missing vulnerable_version_range for package — fill in the GHSA UI (e.g. \"<= 3.11.3\").`\n2. **Patched versions filled.** For every entry in `vulnerabilities[]`, `patched_versions` must be non-empty. Empty `patched_versions` is normal *before* a release, but at merge time the user is one step from cutting a release; flag it so they remember to set it. Action item:\n `Advisory missing patched_versions for package — set to the version this fix ships in (likely ).`\n3. **Affected package range covers the merge target.** If `vulnerable_version_range` is present, sanity-check that the current `main` `package.json` version (pre-bump) satisfies it. A range like `<= 3.10.0` on an advisory landing into `3.11.3` is almost certainly stale — the reporter probably tested against the latest version and the range was never updated. Action item:\n `Advisory vulnerable_version_range \"\" does not cover current main version — verify and widen if the bug reproduces on the latest release.`\n4. **CVSS vector set.** At least one of `cvss.vector_string` or `cvss_severities.cvss_v3.vector_string` must be a non-null CVSS v3.x vector. A bare `severity` string (\"high\", \"critical\") without a vector is incomplete — downstream scanners need the vector. Action item:\n `Advisory missing CVSS v3 vector — current severity label is \"\", but no vector is set. Fill in the GHSA UI (Severity → CVSS calculator).`\n5. **CVSS vector internally consistent with severity label.** If a vector is set, compute its base score range and confirm it matches `severity`:\n - 0.1–3.9 → low\n - 4.0–6.9 → medium\n - 7.0–8.9 → high\n - 9.0–10.0 → critical\n Mismatch (e.g. vector scores 9.8 but `severity` is \"high\") → action item:\n `Advisory CVSS vector \"\" scores () but severity label is \"\" — reconcile in the GHSA UI.`\n6. **CWE present.** `cwe_ids` should be non-empty. Empty → action item:\n `Advisory missing CWE — add the appropriate CWE in the GHSA UI (look up by attack class; e.g. CWE-1336 for sandbox escape via prototype pollution, CWE-913 for unsafe deserialization).`\n\n**Propose concrete values, do not just flag absence.** When an action item is about a missing CVSS vector or CWE, derive a specific suggestion from the merged fix and include it in the action item so the user can paste it directly into the GHSA UI:\n\n- **CVSS vector.** Build a CVSS v3.1 vector from what the merged commit actually shows. For vm2, the recurring shape is sandbox escape → arbitrary host code execution, which lands at `CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H` (9.8, critical). Adjust only the dimensions the specific fix changes — e.g. attack-complexity `AC:H` when the PoC needs a race, `UI:R` when sandbox invocation requires victim interaction (rare for vm2), `S:U` and reduced CIA when the bug is sandbox-internal DoS rather than escape (e.g. memory exhaustion landing closer to `AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H` → 7.5, high). State the vector and the score it computes to in the action item, and call out which dimension you departed from the default for, so the user can sanity-check the call rather than blindly paste.\n- **CWE.** Pick the closest match from the small set vm2 actually uses, based on the attack class the fix addresses:\n - Sandbox escape via proxy/prototype/realm boundary failure → `CWE-913` (Improper Control of Dynamically-Managed Code Resources) when sandbox code escapes to the host realm.\n - Bypass of a specific defensive check (e.g. `bufferAllocLimit`, timeout, frozen intrinsic) without a full escape → `CWE-693` (Protection Mechanism Failure).\n - Prototype pollution leading to escape → `CWE-1321` (Improperly Controlled Modification of Object Prototype Attributes).\n - Resource exhaustion / DoS inside or via the sandbox → `CWE-770` (Allocation of Resources Without Limits or Throttling).\n - Information disclosure of host-realm internals without code execution → `CWE-200` (Exposure of Sensitive Information to an Unauthorized Actor).\n Include the chosen CWE ID *and* a one-clause rationale tied to the merged fix in the action item.\n\nThese are starting points calibrated for the next paste, not verdicts. The user still makes the final judgment in the GHSA UI; the skill's job is to remove the \"stare at a blank CVSS calculator\" step.\n\nPrint nothing about this audit yet; keep `ghsa_action_items` in memory and emit it in the step-8 summary block.\n\n### 3. Sync the private fork as source of truth\n\nThe maintainer may have made small final tweaks on the private fork through the GitHub UI after the last local push. The **remote `ghsa-/main` is the source of truth**, not the local `fix/GHSA-` branch:\n\n```bash\ngit fetch ghsa-\n\n# Show local vs remote head — they should match, but the remote wins on disagreement\ngit rev-parse fix/ ghsa-/main\ngit log --oneline fix/..ghsa-/main\ngit log --oneline ghsa-/main..fix/\n```\n\nIf the local branch has commits the remote does not, the local copy carries work the reporter has not seen. Stop and surface them. The user must either push them and get re-confirmation, or drop them, before integration proceeds.\n\nIf the remote is ahead, fast-forward the local branch:\n\n```bash\ngit checkout fix/\ngit merge --ff-only ghsa-/main\n```\n\n### 4. Sync local main against origin\n\n```bash\ngit fetch origin\ngit checkout main\n\n# Are we behind, ahead, diverged, or in sync with origin/main?\ngit rev-list --left-right --count origin/main...main # prints \"\\t\"\ngit log --oneline main..origin/main # commits origin has, local doesn't\ngit log --oneline origin/main..main # commits local has, origin doesn't (the stack under this landing)\n```\n\nDecide based on the divergence shape:\n\n- **In sync** (`0\\t0`): nothing to do, continue to step 5.\n- **Behind only** (`N\\t0`, N > 0): fast-forward and continue.\n ```bash\n git merge --ff-only origin/main\n ```\n- **Ahead only** (`0\\tN`, N > 0): batch case — local has already-landed integration commits awaiting a push. Continue to step 5. Capture the local-only commit list for the step-8 `Stacked on:` line.\n- **Diverged** (`M\\tN`, both > 0): stop. Origin has work local does not, *and* local has work origin does not. This skill never reconciles a real divergence — the user must resolve the upstream pull before retrying.\n\n### 5. Squash-merge with deliberate conflict resolution\n\nFrom `main`:\n\n```bash\ngit merge --squash fix/\n```\n\n`--squash` stages the combined tree change without creating a commit, and surfaces every conflict immediately. There is no commit graph linkage to roll back through — only the index and worktree are affected. This makes conflict resolution mechanically simpler.\n\nIf the merge reports conflicts, **resolve every one deliberately**, file by file. Do not blanket-take one side. Per-file strategy:\n\n#### 5a. `CHANGELOG.md`\n\nConflicts here are almost always additive — both branches added a new line under the same release header.\n\n- Keep **both** entries.\n- Order them by GHSA ID ascending under the release header, or by the order the user prefers (ask once if unsure, then apply consistently).\n- If the branch you are landing also bumped to a new release header that's already on `main` from another advisory, collapse into the single release header on `main`.\n\n**Trim verbose entries before committing.** The fix-vulnerability skill tends to produce paragraph-long bullet points that mirror the full attack-catalog write-up. That is redundant — the catalog (`docs/attacks/*.md`) and the per-advisory tests are the source of truth. A CHANGELOG entry is a release-notes index, not a second copy of the analysis.\n\nTarget shape, in 2–4 sentences max:\n\n1. The vulnerability class in plain language (one sentence, no full PoC payload).\n2. The chokepoint of the fix in one short clause (file + structural mechanism, e.g. `Two-layer structural fix in lib/bridge.js (apply-trap blocklist + cache check)`).\n3. A pointer: `See ATTACKS.md Category N and test/ghsa//`.\n\nUse the existing 3.11.1 entry (`GHSA-8hg8-63c5-gwmx`) as the reference shape — that one is the right length. Entries from 3.11.2 and 3.11.3 are too long and should NOT be matched.\n\nIf the branch's entry is already short, leave it. If it is one giant paragraph quoting the commit body, rewrite it down to the target shape before the squash commit lands. The rewrite is part of conflict resolution — do it in the same edit pass, not as a follow-up commit.\n\n#### 5b. The attack catalog (`docs/ATTACKS.md` and `docs/attacks/`)\n\nThe fix-vulnerability skill assigns each new attack class the next unused category number across all family files. If two advisories both grew from the same base and both claimed the same number, you must renumber:\n\n- The category that lands first keeps its number.\n- The category landing now (this branch) takes the next free number on current `main` — i.e. `(max category number on main) + 1`.\n- Update **all cross-references** to the renumbered category: `Category N` mentions and `#attack-category-N-` anchors in every `docs/attacks/*.md` and in `docs/ATTACKS.md`, its row in the category index, and its Compound Attack Patterns / How The Bridge Defends rows. `test/docs-catalog.js` fails on a duplicate number, a gap, or an unresolved anchor, so run `npm test` before considering the renumbering done.\n\nIf both branches edited the same row in `Summary → How The Bridge Defends` or `Summary → Compound Attack Patterns`, merge the rows by hand to preserve both defenses.\n\n#### 5c. `package.json` (version bump conflict)\n\nIf both branches bumped `version`:\n\n- Pick the **higher** of the two as the floor.\n- If both bumped to the same `X.Y.Z`, increment patch one more so each landed fix gets a distinct version slot (`X.Y.Z` → `X.Y.(Z+1)`).\n- Update `package-lock.json`'s top-level `version` field (and the `\"\"` package entry) to match. Do not run `npm install` here — that would touch the lockfile graph and create churn unrelated to the security fix.\n\n#### 5d. `lib/*.js` (the boundary code)\n\nThese are semantic conflicts and you must reason about them as a security engineer, not as a text-merger:\n\n1. Open both sides with `git checkout --conflict=diff3 -- ` so you see the common ancestor block (`||||||| merged common ancestors`). The ancestor reveals the **intent** of each side.\n2. If both sides added new defensive checks at the same chokepoint, keep both — they are usually independent (e.g. one filters a symbol, another rebinds a return value). Order them by what runs first logically, not by file order.\n3. If the two sides modified the **same defensive check in incompatible ways**, that is a real design conflict. Do not pick — stop and tell the user. The fix-vulnerability skill's multi-angle exploration should have caught this; surfacing it here means an earlier round missed an interaction. The user must decide whether to re-spawn agents or hand-merge.\n4. If the conflict is purely formatter noise (trailing commas, brace spacing) on lines neither side changed semantically, take `main`'s formatting and keep the security delta. Never let formatter churn enter the final commit.\n5. Re-read every `// SECURITY:` comment in the touched region after resolution. If a comment now describes behavior that the merged code no longer has, fix the comment. A stale SECURITY comment is worse than no comment.\n\n#### 5e. `test/*.js` (main suites) and `test/ghsa//`\n\n- Conflicts in `test/vm.js` / `test/nodevm.js` follow the same logic as `lib/*.js` — both sides likely added related test cases; keep both.\n- `test/ghsa//` for **this** advisory is the branch's own directory and should not conflict. If it does, something is wrong with the branch hygiene — stop and surface.\n- Tests in other advisories' directories (`test/ghsa//`) should never appear in this branch's diff. If they do, the branch was not properly isolated; surface and let the user decide whether to revert those hunks.\n\n#### 5f. Scrub external attribution during conflict resolution\n\nWhile resolving, scan every conflict region (and every non-conflicting hunk you have just authored or rewritten) for:\n\n- Reporter names, GitHub handles, or affiliations.\n- Embargo dates, disclosure dates, \"as reported by …\" phrasing.\n- \"Thanks to …\" lines.\n- Email addresses other than the maintainer's commit identity.\n\nDelete them. Replace with neutral phrasing or simply drop the sentence. The GHSA ID itself stays — that's the issue identifier.\n\nAfter all conflicts are resolved:\n\n```bash\ngit status # confirm no remaining \"both modified\" entries\ngit diff --cached --stat # sanity-check the staged surface looks like one advisory\n```\n\n### 6. Build the integration commit\n\nThe commit subject **must** match the existing pattern visible in `git log --oneline main`:\n\n```\nfix(GHSA-): \n```\n\nThe body should:\n\n- State the root cause in 1–2 sentences.\n- State the fix's chokepoint and which `docs/ATTACKS.md` Defense Invariant it restores.\n- List the test surface added/changed (`test/ghsa//repro.js` plus any variant files).\n- Note the `docs/ATTACKS.md` category (new or updated) and the `package.json` version bump if any.\n- Be **fully free** of reporter names, handles, dates, and acknowledgements.\n\nDraft the message from the branch's own commits + the doc updates, not from the advisory thread, to keep attribution out automatically. Sources to mine for the body:\n\n```bash\ngit log fix/ --format='%s%n%n%b' main..ghsa-/main\ngit diff --cached docs/ATTACKS.md docs/attacks/ CHANGELOG.md\n```\n\nIf any phrase you considered including names a person, a handle, or a date — drop it.\n\nCommit:\n\n```bash\ngit commit -F - <<'EOF'\nfix(GHSA-): \n\n\nEOF\n```\n\nUse `-F -` (heredoc) rather than `-m` so multi-line bodies format cleanly.\n\n### 7. Re-prove the full test surface\n\nA clean merge with green local tests on one Node version proves almost nothing for vm2. Run the full sweep before declaring done.\n\n```bash\n# Full Node-version sweep, same floor as fix-vulnerability step 7\nfor v in 8 10 12 14 16 18 20 22 24 25 26; do\n echo \"=== node $v ===\"\n nvm use $v && npm test 2>&1 | tail -3\ndone\n```\n\nAny failure means the integration introduced a regression that the per-branch test pass did not see. Likely causes:\n- Another already-landed advisory's defense interacts with this one.\n- Conflict resolution in `lib/*.js` accidentally weakened a previously-restored invariant.\n- Renumbering in the attack catalog broke a link (`test/docs-catalog.js` fails) or an anchor that a test asserts on.\n\nRoll back with `git reset --hard HEAD~1`, re-do step 5 with the new information, and re-run. Do **not** patch the failing test to make it green unless you can articulate, in writing, why the prior behavior was the insecure one — and even then, surface that to the user before committing.\n\nThen re-run the advisory's own repro to confirm the fix still blocks the original PoC after rebase noise:\n\n```bash\nnode test/ghsa//repro.js # if it is standalone\n# or\nnpx mocha test/ghsa// # if it is mocha-style\n```\n\n### 8. Report and stop\n\nPrint a short, terse summary to the user. Match this shape:\n\n```\nGHSA- integrated into local main as .\n\nCommit: fix(GHSA-): \nStacked on: <\"origin/main\" | comma-separated list of local-only commits this landed on top of>\nConflicts: \nRenumbered: Category M in docs/attacks/.md>\nVersion: X.Y.(Z+1)>\nTest sweep: Node 8/10/12/14/16/18/20/22/24/25/26 all pass\n\nAdvisory action items (fix in GHSA UI before publishing):\n - \n - \n ...\n (or \"none — advisory metadata is publication-ready\" if the list is empty)\n\nNOT PUSHED. Publish via the maintainer's release flow when ready.\n```\n\nThe `Advisory action items` block is required even when empty — its absence would let a stale advisory ship silently. Render the empty case as the literal \"none — advisory metadata is publication-ready\" line so the user sees the check ran.\n\nThat last line (\"NOT PUSHED…\") is load-bearing. Make sure it is the final thing you say. Do **not** offer to push, do **not** offer to tag, do **not** offer to publish to npm. The user runs those steps themselves, deliberately, after a final visual review of `git log -p HEAD~1..HEAD`.\n\n---\n\n## Things this skill never does\n\n- Push to `origin` or to the private fork.\n- Delete the per-advisory branch or the private fork remote (those stay around until the maintainer's release flow has fully completed).\n- Edit the advisory on GitHub or post comments to the advisory thread.\n- Reword or \"clean up\" prior commits on `main`.\n- Run `npm install`, `npm publish`, or bump `package.json` beyond the minimum required for the version-conflict resolution in step 5c.\n- Trust the local `fix/GHSA-` branch over `ghsa-/main` — the private fork's main is canon.\n- Carry attribution from the advisory thread or the branch's iterative commits into the final commit.\n\n\n# vm2\n\nvm2 safely sandboxes untrusted JavaScript code running in Node.js. This is a security-critical project -- every change must be evaluated for sandbox escape potential.\n\n## Public API\n\nExported from `lib/main.js` via `index.js`:\n\n- **`VM`** -- isolated context for synchronous execution without `require`.\n- **`NodeVM`** -- sandbox emulating Node's module loader with fine-grained `require` controls.\n- **`VMScript`** -- compilation, caching, and compiler selection wrapper.\n- **`VMFileSystem`** -- controls sandbox filesystem access.\n- **`VMError`** -- raised when sandbox policy is violated.\n\n## Architecture\n\n### The Boundary (Security-Critical)\n\n| File | Role |\n|------|------|\n| `lib/bridge.js` | Core proxy layer. Paired proxies for every value crossing host/sandbox. WeakMap caches for identity. Proxy trap handlers (`BaseHandler`, `ProtectedHandler`, `ReadOnlyHandler`). |\n| `lib/setup-sandbox.js` | Sandbox bootstrap for `VM`. `handleException`, Promise wrapping, `Symbol.for` override, symbol filtering, `Error.prepareStackTrace` safe default, `WebAssembly.JSTag` deletion. |\n| `lib/setup-node-sandbox.js` | Sandbox bootstrap for `NodeVM`. `require`, module resolution, console redirection. |\n| `lib/transformer.js` | Acorn parser instrumenting `catch` blocks and `with` statements. **Limitation**: `ecmaVersion: 2022` -- post-ES2022 syntax (e.g., `using`) is invisible. |\n\n### Other Files\n\n| File | Role |\n|------|------|\n| `lib/vm.js` | `VM` class. Compiles via `vm.Script`, applies transformer, enforces timeout/async. |\n| `lib/nodevm.js` | `NodeVM` class. Module loader, external module access, console redirection. |\n| `lib/script.js` | `VMScript`. Options, compilers, caching, async detection. |\n| `lib/compiler.js` | Compiler resolution (JS passthrough, optional CoffeeScript/TypeScript). |\n| `lib/filesystem.js` | `VMFileSystem` implementation. |\n| `lib/resolver.js` | Module resolution for `NodeVM`. |\n| `lib/events.js` | Sandbox-safe copy of Node's `events`. |\n| `lib/sources.js` | **Generated** by `scripts/build-sources.js`. `bridge.js`, `setup-sandbox.js`, `setup-node-sandbox.js`, and `events.js` embedded as string literals so the runtime never reads package files from disk and bundlers (Bun compile, esbuild, pkg) work. Regenerate with `npm run build:sources` after editing any of those four files (`npm test` does it via `pretest`; `test/sources.js` fails if it is stale). Never edit by hand. |\n\n### CLI\n\n```sh\nnpx vm2 path/to/script.js # NodeVM with external modules, verbose logging\n```\n\n## Security\n\nThe attack catalog is [`docs/ATTACKS.md`](docs/ATTACKS.md) (category index, fundamentals, defense invariants, defense table, checklist) plus one file per mechanism family under [`docs/attacks/`](docs/attacks/). Every category has a permanent number; the index table resolves a number to its file.\n\n**Key insight**: V8 internal algorithms (ArraySpeciesCreate, FormatStackTrace, PromiseResolveThenableJob) operate on raw objects, bypassing proxy traps. Defenses must neutralize raw objects directly, not just intercept via proxies.\n\n### Principles\n\n1. Never expose host constructors or prototypes.\n2. Rebound every function crossing the bridge to the destination realm.\n3. Freeze or proxy shared mutable state.\n4. Filter property access via `Object.getOwnPropertyDescriptor`. Never `for...in` or spread on host objects.\n5. Treat new symbols and language features as suspect until vetted.\n6. Cache `Reflect.*` and other critical references at init time.\n\n### Checklist for Boundary Changes\n\n1. Does this expose any new return path for host objects?\n2. Can sandbox code call this method directly (not through a proxy)?\n3. Does this accept attacker-controlled parameters?\n4. Are all `Reflect.*` calls using cached references?\n5. Could V8 internal algorithms trigger this path (bypassing traps)?\n6. Does this handle host-realm errors that could be thrown?\n7. Are there new well-known symbols that need filtering?\n\n## Tests\n\n```sh\nnpm test # Main suite (Mocha)\nnpm run test:compilers # Optional (needs typescript, coffee-script)\nnpm run lint # ESLint\n```\n\n- `test/vm.js` -- Main sandbox tests. Uses `makeHelpers()` for proxy boundary checks, `it.cond(name, condition, fn)` for version-gated tests.\n- `test/nodevm.js` -- NodeVM module loading tests.\n- `test/ghsa//` -- One directory per advisory: `repro.js` holds the PoC asserted blocked, with `adversarial.js` and `structural-leak*.js` variants where they exist.\n- `test/docs-catalog.js` -- Guards the attack catalog: unique sequential category numbers, resolvable links, required `Advisories` and `Tests` lines, index parity.\n\nEvery security fix must include tests that reproduce the attack, verify the defense, and test bypass variants. Use `it.cond()` for Node version requirements.\n\nUse the `/hacker` skill after making security-related changes to systematically red-team the sandbox and verify it still holds.\n\n## Updating the attack catalog\n\n**Every time the library is patched**, update the catalog following the [Category Entry Format](docs/ATTACKS.md#category-entry-format):\n\n- Add the entry to the family file under `docs/attacks/` whose mechanism matches, with the next unused number across all families, or extend an existing category's canonical examples if the fix is a variant.\n- Fill `**Advisories**:` and `**Tests**:`; document attack flow, canonical example, why it works, mitigation (naming the Defense Invariant it restores), detection rules.\n- Add the row to the category index in `docs/ATTACKS.md`, the \"How The Bridge Defends\" table, and for compounds the \"Compound Attack Patterns\" list.\n- Add new APIs or features to \"Considered Attack Surfaces\" or \"Future Risks\" in `docs/ATTACKS.md`.\n- `npm test` runs `test/docs-catalog.js`, which fails on a renumbering, a dead link, or a missing metadata line.\n- Add a one-line entry to `CHANGELOG.md` under the next release.\n\n## Workflow\n\n- Keep changes small and focused. Security-sensitive code discourages large refactors.\n- After editing `bridge.js`, `setup-sandbox.js`, `setup-node-sandbox.js`, or `events.js`, run `npm run build:sources` before any ad-hoc `node -e` check. The runtime executes the embedded copy in `lib/sources.js`, not the file on disk.\n- Include threat model reasoning and escape-prevention tests for boundary changes.\n- Follow existing ESLint code style.\n- Vulnerabilities: follow `SECURITY.md`, not public issues.\n"}