From 66816329fbd49d04154cf9d887f42a2b471124a5 Mon Sep 17 00:00:00 2001 From: Kaitian Xie Date: Sun, 15 Nov 2026 12:24:38 +0800 Subject: [PATCH 1/9] Add regression tests for inline Python str.replace and Path target confinement --- hooks/guard.test.mjs | 93 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/hooks/guard.test.mjs b/hooks/guard.test.mjs index b236449..cf8d60e 100644 --- a/hooks/guard.test.mjs +++ b/hooks/guard.test.mjs @@ -2928,4 +2928,97 @@ if (process.env.MOCK_CLI_MODE === "hang") { setTimeout(() => {}, 10000); } else sb.cleanup(); } }); + + test("allows multi-argument Python str.replace in inline scripts while blocking 1-arg Path.replace and escaping rename or replace targets", () => { + const sb = makeSandbox(); + try { + writeSwarmMembers(sb.appDataDir, "coord-py-replace", { + coordinator: { conversation_id: "coord-py-replace", role: "coordinator" }, + "ro-py": { conversation_id: "ro-py-id", role: "worker" }, + "impl-py": { conversation_id: "impl-py-id", role: "worker" }, + "adv-py": { conversation_id: "adv-py-id", role: "worker" }, + "sicko-py": { conversation_id: "sicko-py-id", role: "worker" }, + }); + + const runPyCmd = (convId, CommandLine) => + runGuard( + { + hookEventName: "PreToolUse", + conversationId: convId, + rootConversationId: "coord-py-replace", + cwd: sb.worktree, + toolCall: { id: "py-rep", name: "run_command", args: { CommandLine } }, + }, + { PSTACK_APPDATA_DIR: sb.appDataDir, TMPDIR: sb.customTmpDir }, + ); + + const roAllowed = [ + `python3 -c "print('hello'.replace('e', 'a'))"`, + `python3 -c "s = 'foobar'; print(s.replace('foo', 'bar'))"`, + `python3 -c "s = 'aaa'; print(s.replace('a', 'b', 1))"`, + `python3 -c "s = 'aaa'; print(s.replace('a', 'b', count=1))"`, + `python3 -c "s = 'aaa'; print(s.replace('a', 'b',))"`, + `python3 -c "from pathlib import Path; print(Path('README.md').read_text().replace('foo', 'bar'))"`, + `python3 -c "import os; print(os.environ.get('PATH', '').replace('/usr', '/opt'))"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').replace('/tmp/dst')"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').rename('/tmp/dst')"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').replace(target='/tmp/dst')"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').rename(target='/tmp/dst')"`, + ]; + for (const cmd of roAllowed) { + assert.equal(runPyCmd("ro-py-id", cmd).decision, "allow", `expected ro allow for ${cmd}`); + } + + const roDenied = [ + `python3 -c "p.replace('/Users/repo/out')"`, + `python3 -c "p.replace('/Users/repo/out',)"`, + `python3 -c "p.replace(target='/Users/repo/out')"`, + `python3 -c "p.replace(target='/Users/repo/out',)"`, + `python3 -c "p.replace(*['/Users/repo/out'])"`, + `python3 -c "p.replace('/Users/repo/out', *[])"`, + `python3 -c "p.replace(**{'target': '/Users/repo/out'})"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').replace('/Users/repo/dst')"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').rename('/Users/repo/dst')"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').replace(target='/Users/repo/dst')"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').rename(target='/Users/repo/dst')"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').replace('${join(sb.worktree, "dst")}')"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').rename('${join(sb.worktree, "dst")}')"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').replace('/tmp')"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').rename('/tmp')"`, + `python3 -c "import os; os.replace('/tmp/src', '/Users/repo/dst')"`, + `python3 -c "import os; os.rename('/tmp/src', '/Users/repo/dst')"`, + `python3 -c "import os; os.replace('/tmp/src', '/tmp')"`, + `python3 -c "from pathlib import Path; print('a'.replace('a', str(Path('README.md').write_text('x'))))"`, + ]; + for (const cmd of roDenied) { + assert.equal(runPyCmd("ro-py-id", cmd).decision, "deny", `expected ro deny for ${cmd}`); + } + + for (const convId of ["impl-py-id", "adv-py-id"]) { + assert.equal( + runPyCmd(convId, `python3 -c "s = 'cfg'; print(s.replace('/etc/old', '/etc/new'))"`).decision, + "allow", + ); + for (const badAuthorCmd of [ + `python3 -c "from pathlib import Path; Path('/tmp/src').replace('${join(sb.outsideDir, "dst")}')"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').rename('${join(sb.outsideDir, "dst")}')"`, + `python3 -c "p.replace('${join(sb.outsideDir, "dst")}')"`, + `python3 -c "from pathlib import Path; Path('/tmp/src').replace('${sb.worktree}')"`, + ]) { + assert.equal(runPyCmd(convId, badAuthorCmd).decision, "deny", `expected ${convId} deny for ${badAuthorCmd}`); + } + } + + assert.equal( + runPyCmd("sicko-py-id", `python3 -c "print('hello'.replace('e', 'a'))"`).decision, + "allow", + ); + assert.equal( + runPyCmd("sicko-py-id", `python3 -c "p.replace('/tmp/out')"`).decision, + "deny", + ); + } finally { + sb.cleanup(); + } + }); }); From 6457965730f8d26174c73e682ebd86f99620308b Mon Sep 17 00:00:00 2001 From: Kaitian Xie Date: Sun, 15 Nov 2026 12:29:29 +0800 Subject: [PATCH 2/9] Allow multi-argument Python str.replace and tighten rename and replace target checks --- hooks/guard.mjs | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/hooks/guard.mjs b/hooks/guard.mjs index a55c092..e482906 100755 --- a/hooks/guard.mjs +++ b/hooks/guard.mjs @@ -3118,7 +3118,11 @@ function checkInlineNodeFs(code, allowPath, options = {}) { function splitPythonCallArgs(callArgs) { const positionals = []; const kwargs = {}; - for (const arg of callArgs) { + const trimmed = + callArgs.length > 0 && callArgs[callArgs.length - 1] === "" + ? callArgs.slice(0, -1) + : callArgs; + for (const arg of trimmed) { const kwMatch = arg.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=(?!=)\s*([\s\S]*)$/); if (kwMatch) { kwargs[kwMatch[1]] = kwMatch[2].trim(); @@ -3258,6 +3262,18 @@ function checkInlinePythonFs(code, allowPath, options = {}) { continue; } } + if (method === "replace") { + const effectiveArgs = + methodArgs.length > 0 && methodArgs[methodArgs.length - 1] === "" + ? methodArgs.slice(0, -1) + : methodArgs; + if ( + effectiveArgs.length >= 2 && + effectiveArgs.every((a) => a.length > 0 && !a.startsWith("*")) + ) { + continue; + } + } const prefix = code.slice(0, match.index); const recv = resolvePythonPathReceiverArg(prefix); const isMkdir = method === "mkdir"; @@ -3325,10 +3341,11 @@ function checkInlinePythonFs(code, allowPath, options = {}) { if ( !targetExpr || !checkPyPathArg(targetExpr, { - allowRootEqual: true, + allowRootEqual: false, allowDevNull: false, allowArtifactDir: false, allowArtifactRoot: false, + disallowArtifactRoot: true, forbidReadOnlyArtifact: !srcOkForRoArtifact, }) ) { @@ -3363,8 +3380,8 @@ function checkInlinePythonFs(code, allowPath, options = {}) { while ((match = osShutilRe.exec(code)) !== null) { const qualifier = match[1] || ""; const fnName = match[2]; - const beforeChar = match.index > 0 ? code[match.index - 1] : ""; - if (!qualifier && (beforeChar === "." || !hasFsImport)) { + const isMemberCall = !qualifier && /\.\s*$/.test(code.slice(0, match.index)); + if (!qualifier && (isMemberCall || !hasFsImport)) { continue; } const openParenIdx = match.index + match[0].length - 1; @@ -3425,12 +3442,12 @@ function checkInlinePythonFs(code, allowPath, options = {}) { customBaseDir: symlinkBaseDir, }) || !checkPyPathArg(dstExpr, { - allowRootEqual: true, + allowRootEqual: fnName === "move", allowDevNull: false, allowArtifactDir: allowMoveDir, allowArtifactRoot: allowMoveDir, forbidReadOnlyArtifact: isLink || !srcOkForRoArtifact, - disallowArtifactRoot: isLink, + disallowArtifactRoot: isLink || fnName !== "move", }) ) { return `Inline Python ${fnName}() outside allowed roots is blocked for ${roleLabel}.`; From d91f6b6292205a5738c0b8b45d488f9ff2591fdd Mon Sep 17 00:00:00 2001 From: Kaitian Xie Date: Sun, 15 Nov 2026 12:32:42 +0800 Subject: [PATCH 3/9] Align plugin manifest, role capsules, and skills with agy 1.5.9 swarm --- .antigravity-plugin/plugin.json | 10 ---------- roles/coordinator.md | 28 ++++++++++++++++++++------- roles/poteto-agent.md | 6 +++++- roles/research.md | 7 ++++++- skills/control-cli/SKILL.md | 6 +++++- skills/control-ui/SKILL.md | 6 +++++- skills/crucible/SKILL.md | 4 ++-- skills/interrogate/SKILL.md | 6 +++--- skills/ketchup/SKILL.md | 6 +++--- skills/make-bot-ui/SKILL.md | 6 +++++- skills/pstack/SKILL.md | 9 +++++---- skills/pstack/topologies/hillclimb.md | 2 +- skills/reflect/SKILL.md | 4 ++-- skills/statechart/SKILL.md | 7 ++++++- skills/technical-writing/SKILL.md | 7 ++++++- skills/understand/SKILL.md | 6 +++--- skills/verify-gen/SKILL.md | 7 ++++++- 17 files changed, 84 insertions(+), 43 deletions(-) diff --git a/.antigravity-plugin/plugin.json b/.antigravity-plugin/plugin.json index 25543ea..59c8b8b 100644 --- a/.antigravity-plugin/plugin.json +++ b/.antigravity-plugin/plugin.json @@ -8,16 +8,6 @@ }, "homepage": "https://github.com/pstack-ports/agy-pstack-next", "repository": "https://github.com/pstack-ports/agy-pstack-next", - "license": "MIT", - "keywords": [ - "pstack", - "swarm", - "workflow", - "hooks", - "verification", - "crucible", - "interrogate" - ], "logo": "assets/logo.png", "suggestedPrompts": [ "/agy-pstack-next:setup-pstack configure per-role swarm models, global guard hooks, and autonomy gates", diff --git a/roles/coordinator.md b/roles/coordinator.md index 14bf1df..d755434 100644 --- a/roles/coordinator.md +++ b/roles/coordinator.md @@ -53,6 +53,13 @@ matching role capsule and enforces its runtime tool boundaries. ## Native swarm mechanics +- **Name the swarm and use batch spawning when appropriate.** Set a concise + swarm title via `swarm` with `action` set to `"title"` when starting a swarm. + When spawning parallel slices or homogeneous copies that share one prefix, + brief, and model, `swarm` `add` accepts `tasks` (a sharded slice array) and + `n` (a homogeneous worker count), generating `-1` through `-` + numbered suffixes that `hooks/guard.mjs` classifies under the base prefix + automatically. - **Eliminate shared mutable state.** Never assign two concurrent authors to edit the same file or branch. Partition work across module seams, isolated `share` worktrees, or sequential phases before spawning. @@ -89,8 +96,14 @@ matching role capsule and enforces its runtime tool boundaries. - **Honor model rules implicitly.** Named rule files such as `~/.gemini/config/rules/pstack-models.md` require YAML frontmatter with `trigger` set to `always_on` so `agy` loads them into `` on every - turn. When active in context, apply those per-prefix model tiers without - reading the file from disk. + turn. When active in context, apply one live model ID per `swarm` `add` call + from those per-prefix model tiers without reading the file from disk. On + comma-separated model lists such as `cand-*` or `adv-*`, pick the first live + entry for a single-worker `cand-*` spawn and cycle live entries in order + across parallel `cand-*` or `adv-*` spawns. Worker-spawned helpers apply the + matching prefix model from `` when present and not `inherit`, or + omit `model` to inherit their parent model. Omit `model` whenever a prefix is + unset or `inherit`. - **Populate the Swarm UI Overview (`swarm_pane`).** When `swarm_pane` is in ``, load `swarm_pane` before briefing workers, skip `narrator` unless requested by name, and write `plan.json` under @@ -100,11 +113,12 @@ matching role capsule and enforces its runtime tool boundaries. and `ro-verify`) to save full-window timeline screenshots under their own `/brain//` folder outside `.system_generated` and flag each step on its own board line per `swarm_pane`. -- **Surface `open_board` on mid-flight replies.** When `native_swarm` is not - loaded in your active `` catalog and you reply to the user while the - swarm is running (on the turn that spawns a continuing swarm or on any - mid-flight status reply), end your reply with the verbatim `open_board` line - from your latest `swarm` `add` or `status` result on its own line. Call +- **Surface `open_board` on mid-flight replies.** Even when starting a swarm + directly without loading the built-in `swarm` skill from your `` + catalog, whenever you reply to the user while the swarm is running (on the + turn that spawns a continuing swarm or on any mid-flight status reply), end + your reply with the verbatim `open_board` line from your latest `swarm` `add` + or `status` result on its own line whenever `open_board` is non-empty. Call `swarm` with `action` set to `"status"` if no `open_board` value is in view, omit the line when `open_board` is empty, and never write a board command or link yourself. diff --git a/roles/poteto-agent.md b/roles/poteto-agent.md index 795893b..35555bb 100644 --- a/roles/poteto-agent.md +++ b/roles/poteto-agent.md @@ -26,7 +26,11 @@ runtime evidence on the swarm message board. (passing warm `fork` when carrying context forward, landing any `share` helper commits before calling `kill` on your own helpers, and using `model` for quota hot-swap) whenever your slice splits into parallel pieces or needs an - independent `ro-*` or `verifier` check. + independent `ro-*` or `verifier` check. When spawning helpers, apply the + matching prefix model from `pstack-models.md` in `` when present + and not `inherit` (picking the first live entry on comma-separated lists for a + single helper or cycling live entries in order across parallel helpers), or + omit `model` to inherit your parent model. - **Keep pushes gated.** Never run `git push` on your own initiative. `adv-*` workers are permanently blocked from pushing, and authoring workers are blocked unless the coordinator explicitly authorizes pushing with diff --git a/roles/research.md b/roles/research.md index 3f60069..c776eee 100644 --- a/roles/research.md +++ b/roles/research.md @@ -30,7 +30,12 @@ directly, and post cited evidence on the swarm message board. trackers, docs, team chat, observability, error tracking, and analytics warehouses, and use native swarm tools (`swarm` including `add` for read-only helpers and `model` for quota hot-swap, `post_message`, `read_board`, - `swarm_wait`, `schedule`, and `manage_task`). Alongside canonical temp roots, + `swarm_wait`, `schedule`, and `manage_task`). When spawning read-only helpers + via `swarm` `add`, apply the matching prefix model from `pstack-models.md` in + `` when present and not `inherit` (picking the first live entry on + comma-separated lists for a single helper or cycling live entries in order + across parallel helpers), or omit `model` to inherit your parent model. + Alongside canonical temp roots, the guard permits writing or copying screenshot image files (`.png`, `.jpg`, `.jpeg`, `.webp`) and screenshot subdirectories inside your own conversation artifact directory (`/brain//`) outside diff --git a/skills/control-cli/SKILL.md b/skills/control-cli/SKILL.md index 332d86f..9d8deeb 100644 --- a/skills/control-cli/SKILL.md +++ b/skills/control-cli/SKILL.md @@ -1,6 +1,10 @@ --- name: control-cli -description: "Build or adapt an isolated local PTY or tmux harness to drive, inspect, and profile an interactive CLI or TUI. Use for deterministic CLI bug repros, keyboard and prompt flows, startup or memory profiling, and parallel swarm verification." +description: >- + Build or adapt an isolated local PTY or tmux harness to drive, inspect, and + profile an interactive CLI or TUI. Use for /agy-pstack-next:control-cli, + /control-cli, deterministic CLI bug repros, keyboard and prompt flows, startup + or memory profiling, and parallel swarm verification. --- # Control CLI diff --git a/skills/control-ui/SKILL.md b/skills/control-ui/SKILL.md index 183c4a1..65d248f 100644 --- a/skills/control-ui/SKILL.md +++ b/skills/control-ui/SKILL.md @@ -1,6 +1,10 @@ --- name: control-ui -description: "Build or adapt an isolated local browser or CDP harness to drive and inspect a web, IDE, or Electron UI. Use for UI verification, screenshots, ARIA snapshots, perf profiles, visual parity diffs, or reproducing UI bugs across parallel swarm workers." +description: >- + Build or adapt an isolated local browser or CDP harness to drive and inspect a + web, IDE, or Electron UI. Use for /agy-pstack-next:control-ui, /control-ui, UI + verification, screenshots, ARIA snapshots, perf profiles, visual parity diffs, + or reproducing UI bugs across parallel swarm workers. --- # Control UI diff --git a/skills/crucible/SKILL.md b/skills/crucible/SKILL.md index d57449d..7c7f0dd 100644 --- a/skills/crucible/SKILL.md +++ b/skills/crucible/SKILL.md @@ -5,8 +5,8 @@ description: >- design axes in isolated share worktrees, evaluate via peer #seq critique and a cross-family ro-judge against design red flags, and synthesize via warm fork and donor cherry-pick. Supports sketch and full fidelity modes. Use for - /crucible, "design this", "architect this", "race prototypes", or comparing - structural options before locking in a shape. + /agy-pstack-next:crucible, /crucible, "design this", "architect this", "race + prototypes", or comparing structural options before locking in a shape. --- # Crucible diff --git a/skills/interrogate/SKILL.md b/skills/interrogate/SKILL.md index 6d4912b..26bde3b 100644 --- a/skills/interrogate/SKILL.md +++ b/skills/interrogate/SKILL.md @@ -5,9 +5,9 @@ description: >- isolated adv-* exploit authors (workspace: "share") alongside read-only ro-blast caller, schema, and rollout mappers (workspace: "inherit"), uses live #seq board deduplication and cross-boundary exploit chaining, and gates every - surviving finding through ro-verify. Use for /interrogate, "adversarial - review", "break this", "stress test this diff", "blast radius", or "what could - this break". + surviving finding through ro-verify. Use for /agy-pstack-next:interrogate, + /interrogate, "adversarial review", "break this", "stress test this diff", + "blast radius", or "what could this break". --- # Interrogate diff --git a/skills/ketchup/SKILL.md b/skills/ketchup/SKILL.md index 8a36833..0448a92 100644 --- a/skills/ketchup/SKILL.md +++ b/skills/ketchup/SKILL.md @@ -5,7 +5,7 @@ description: >- plain-language restatements (--plain), subtitled slide walkthrough videos (--video), and cross-session transcript and swarm recall (--recall). Parallel read-only ro-* gatherers inspect board.jsonl #seq deltas, members.json, - optional narrator swarm_view/view.json, prior swarm boards, git log, and gh pr + optional narrator view.json, prior swarm boards, git log, and gh pr state. Use for /agy-pstack-next:ketchup, /ketchup, "catch me up", "ketchup --plain", "explain that in plain words", "ketchup --video", "recall my work on X", or "where did I leave off". @@ -32,9 +32,9 @@ Keep the repository completely read-only in every mode. Rendering the MP4 into ` Never trust stale prose in chat when live state can be checked. For small single-turn catch-ups, inspect directly. Whenever a swarm ran, multiple PRs or branches moved, or `--recall` spans prior sessions, spawn parallel read-only `ro-*` gatherers (`workspace: "inherit"`, enforced read-only by `hooks/guard.mjs`) using the `ro-*` model from `~/.gemini/config/rules/pstack-models.md` (or `inherit`): -- **`ro-swarm` (live swarm and board delta).** Inspects `/brain//.system_generated/swarm/` (`members.json` roster states and worktree paths, `swarm.json`, and `board.jsonl` `#seq` deltas since the human's last message) alongside `swarm{action: "status"}`. When `members.json` records a `narrator` member (`members.narrator.conversation_id`), also reads `/brain//swarm_view/view.json` if present. Because `swarm_narrator` is optional and absent in `agy` CLI sessions, `ketchup` falls back cleanly to `board.jsonl` and `members.json` whenever no `narrator` or `view.json` exists. Verifies claimed worker completions against real commits and test runs. +- **`ro-swarm` (live swarm and board delta).** Inspects `/brain//.system_generated/swarm/` (`members.json` roster states and worktree paths, `swarm.json`, and `board.jsonl` `#seq` deltas since the human's last message) alongside `swarm{action: "status"}`. For narrator Overview state, checks `/brain//.system_generated/swarm/view.json` first, and otherwise selects the highest-numbered live `narrator` or `narrator-N` replacement (`narrator` ranks `1`, `narrator-N` ranks `N`) ahead of any killed narrator entry in `members.json` before reading `/brain//swarm_view/view.json` if present. Because `swarm_narrator` is optional and absent in `agy` CLI sessions, `ketchup` falls back cleanly to `board.jsonl` and `members.json` whenever no `narrator` or `view.json` exists. Verifies claimed worker completions against real commits and test runs. - **`ro-repo` (live git, PR, and CI state).** Runs `git status --short`, `git branch`, `git log`, and `gh pr list` / `gh pr view` / `gh pr checks` to confirm branch cleanliness, review threads, merge readiness, and exact numbers behind any metric before reporting it. -- **`ro-history` (cross-session transcripts, prior swarms, and shared record for `--recall`).** Orders `/brain/*` directories strictly within the active workspace by real modification time (`ls -t`, default 7-day window unless another window is named). Filters matching topics first, reads `/brain//.system_generated/logs/transcript.jsonl` (`transcript_full.jsonl` only on `truncated_fields` lines), prior `/brain//.system_generated/swarm/` (`members.json` and `board.jsonl`), and `/brain//swarm_view/view.json` when prior `members.json` includes a `narrator` entry, skipping unrelated workspaces or eval noise. When `--recall` names a feature, module, or bug, also queries issue trackers, docs, chat, and error telemetry per [`../understand/references/source-playbook.md`](../understand/references/source-playbook.md) to surface reverts and recurring user reports. +- **`ro-history` (cross-session transcripts, prior swarms, and shared record for `--recall`).** Orders `/brain/*` directories strictly within the active workspace by real modification time (`ls -t`, default 7-day window unless another window is named). Filters matching topics first, reads `/brain//.system_generated/logs/transcript.jsonl` (`transcript_full.jsonl` only on `truncated_fields` lines), prior `/brain//.system_generated/swarm/` (`members.json` and `board.jsonl`), and narrator Overview `view.json` by checking `/brain//.system_generated/swarm/view.json` first and otherwise selecting the highest-numbered live `narrator` or `narrator-N` replacement ahead of any killed narrator entry in `members.json` before reading `/brain//swarm_view/view.json`, skipping unrelated workspaces or eval noise. When `--recall` names a feature, module, or bug, also queries issue trackers, docs, chat, and error telemetry per [`../understand/references/source-playbook.md`](../understand/references/source-playbook.md) to surface reverts and recurring user reports. Retire all `ro-*` gatherers via `swarm{action: "kill"}` once their `#seq` reports arrive. diff --git a/skills/make-bot-ui/SKILL.md b/skills/make-bot-ui/SKILL.md index e288485..513eabe 100644 --- a/skills/make-bot-ui/SKILL.md +++ b/skills/make-bot-ui/SKILL.md @@ -1,6 +1,10 @@ --- name: make-bot-ui -description: "Build a custom web page or dashboard whose buttons wake an Antigravity agent over agy agentapi or an external webhook, with server-side secret isolation and optional Tailscale exposure." +description: >- + Build a custom web page or dashboard whose buttons wake an Antigravity agent + over agy agentapi or an external webhook, with server-side secret isolation + and optional Tailscale exposure. Use for /agy-pstack-next:make-bot-ui, + /make-bot-ui, or building an agent-waking control page. --- # How to Make a Bot UI diff --git a/skills/pstack/SKILL.md b/skills/pstack/SKILL.md index 73974dd..3fd1fc2 100644 --- a/skills/pstack/SKILL.md +++ b/skills/pstack/SKILL.md @@ -3,8 +3,8 @@ name: pstack description: >- Swarm-native engineering kernel for autonomous features, bug fixes, refactors, performance hillclimbs, multi-phase programs, PR shipping, and skill evals. - Use for /pstack or any non-trivial engineering workflow coordinated across a - native agent swarm. + Use for /agy-pstack-next:pstack, /pstack, or any non-trivial engineering + workflow coordinated across a native agent swarm. metadata: icon: crown color: yellow @@ -38,16 +38,17 @@ Root `hooks.json` and global `~/.gemini/config/hooks.json` (`pstack-swarm-guard` **Worker skill and capsule paths in briefs.** Native `Swarm Worker` subagents do not mount installed plugin skills in ``, and worker hooks run only when `pstack-swarm-guard` is registered in global `~/.gemini/config/hooks.json`. Derive `` from this skill's directory path in ``. Pass explicit resolved `SKILL.md` and reference paths in worker briefs (such as `/skills/statechart/SKILL.md`, `/skills/control-ui/SKILL.md`, and `/skills/control-cli/SKILL.md`) for `read_file` rather than telling workers to invoke plugin skills by name. When global `~/.gemini/config/hooks.json` is not active, also pass the resolved `/roles/.md` path (`poteto-agent.md`, `research.md`, or `comment-sicko.md`) in each worker brief to read first. -**Model selection.** `~/.gemini/config/rules/pstack-models.md` (configured via `/setup-pstack`) requires `trigger: always_on` YAML frontmatter so `agy` injects it into `` on every turn. When active in context, pass its configured per-prefix `model` in `swarm{action: "add"}` and do not call `read_file` on that rule file manually. When unset or `inherit`, omit `model` so workers inherit your session model. +**Model selection.** `~/.gemini/config/rules/pstack-models.md` (configured via `/setup-pstack`) requires `trigger: always_on` YAML frontmatter so `agy` injects it into `` on every turn. When active in context, pass one configured per-prefix `model` ID per `swarm{action: "add"}` call without calling `read_file` on that rule file manually. For comma-separated model lists (such as `cand-*` or `adv-*`), single-worker `cand-*` spawns pick the first live entry and parallel `cand-*` (or `adv-*`) spawns cycle live entries in order across individual `add` calls. Worker-spawned helpers apply the matching prefix model from `` when present and non-`inherit` (picking the first live entry or cycling in order across parallel helpers), or omit `model` to inherit their parent worker's model. When a prefix is unset or `inherit`, omit `model` so the new member inherits its caller's model. ## 3. Native swarm mechanics +- **Swarm title and batch spawning (`title`, `tasks`, `n`).** Call `swarm{action: "title", title: ""}` when starting a swarm so the Swarm UI names the run clearly. For parallel slices or worker pools sharing one prefix, brief, and model, `swarm{action: "add"}` accepts `tasks` (a sharded slice array spawning `-1` through `-`) or `n` (a homogeneous worker count spawning `-1` through `-`). `hooks/guard.mjs` strips trailing `-` suffixes and classifies every numbered worker under its base prefix automatically (`@` and `swarm{action: "kill", name: ""}` address the group while `@-1` targets one member). - **Warm context handoffs (`fork`).** Pass `fork: ""` in `swarm{action: "add"}` (for example, `swarm{action: "add", name: "impl-fix", workspace: "share", fork: "ro-probe-1", brief: "..."}`) whenever an author or synthesizer builds directly on an investigator's or winning candidate's warm context. When global `hooks.json` is active, `hooks/guard.mjs` upgrades the forked worker's role capsule automatically on its first turn. When global `hooks.json` is not active, pass `/roles/.md` explicitly in the brief. - **Topic channels when supported.** Stay on the main board for `<= 8` workers. For `> 8` concurrent workers or multi-area DAGs, check whether the live `swarm` tool declaration includes `"channel"` in `action`. When `"channel"` is present, partition traffic with `swarm{action: "channel"}` (`#area`) and assign one `lead-` (`workspace: "share"`) per channel so leaf chatter never wakes unrelated slices. When `"channel"` is absent, coordinate on the main board under `lead-` coordinators (`workspace: "share"`) with strict `@mention` discipline so leaf updates mention only `@lead-`. - **`#seq` citations and paged board reads.** Cite board messages by sequence number (`#12`) and pull specific posts via `read_board{seqs: [12]}` or incremental deltas via `read_board{since: }`. Never copy-paste raw worker logs across briefs. Because `read_board` defaults to `limit: 20`, cold-start session pickup and catch-up after busy bursts must page `read_board{since: , limit: 100}` starting from `` (`0` on cold start) until `` reaches `head`. - **Doorbell `@mention` hygiene.** `@name` wakes a sleeping agent and spends a turn. Never use `@name` as a passive CC. On peer handoffs (`impl-1` to `@ro-verify`), mention only the next actor and require workers to open final completion posts with `@ [done]` so the Swarm UI marks parked workers done. Post non-urgent progress unaddressed. Reserve `@all` for swarm-wide holds or interface contract changes. Sleep for free with `swarm_wait{since: }` instead of polling `read_board` in a loop. - **Swarm UI Overview (`swarm_pane`).** When `swarm_pane` is present in ``, load `swarm_pane` before briefing workers, skip `narrator` unless the user asks for `narrator` by name, and write `/brain//.system_generated/swarm/plan.json` (`goal`, `tasks`, and 1 to 6 outcome `threads`) after adding workers. Rewrite `plan.json` whenever workers, task assignments, or goals change. On UI, layout, or visual tasks, instruct UI-facing workers (`impl-*`, `cand-*`, `ro-verify`) in their briefs to save full-window timeline screenshots under their own `/brain//` directory (outside `.system_generated/`) and flag each step on its own board line as `Screenshot: | `. Skip screenshot instructions on backend, infra, data, or docs work. -- **Show `open_board` on mid-flight status replies.** When `native_swarm` is not loaded in `` and you reply to the user while the swarm is active (on the turn that launches a continuing swarm or whenever the user asks what the swarm is doing), end your reply with the verbatim `open_board` string from your latest `swarm` `add` or `status` result on its own line. Call `swarm{action: "status"}` if none is in view, omit the line when `open_board` is empty, and never fabricate a board command or link yourself. +- **Show `open_board` on mid-flight status replies.** Even when you start a swarm directly without loading the built-in `swarm` skill from ``, whenever you reply to the user while the swarm is active (on the turn that launches a continuing swarm or whenever the user asks what the swarm is doing), end your reply with the verbatim `open_board` string from your latest `swarm` `add` or `status` result on its own line whenever `open_board` is non-empty. Call `swarm{action: "status"}` if none is in view, omit the line when `open_board` is empty, and never fabricate a board command or link yourself. - **Quota and capacity hot-swap (`swarm{action: "model"}`).** On `[quota]` warnings or model capacity errors, inspect valid models via `swarm{action: "models"}` and switch the `waiting` worker (or yourself) in place with `swarm{action: "model", name, model}` while preserving full conversation history. Never `kill` and re-`add` merely to switch models. - **Land commits BEFORE `swarm{action: "kill"}`.** `swarm{action: "kill", name}` is permanent and **deletes that worker's `share` or `branch` worktree**. Keep finished `impl-*` and `cand-*` workers parked in `waiting` (zero token cost) until you run `git fetch && git merge --no-edit FETCH_HEAD` (or `git cherry-pick `) and verify `git status --short` locally. Only after commits are safely landed in your branch, call `swarm{action: "kill"}` on every task worker (`impl-*`, `cand-*`, `lead-*`, `ro-*`, `adv-*`, `sicko-*`) while leaving built-in `monitor` and `narrator` (`*-N`) alive unless the user asks. - **Board closure (`[done] `).** Once verification passes on the integrated tree and all task workers are killed, post `[done] ` with no `@` symbol in the text so `monitor` goes quiet before you deliver your final user reply. diff --git a/skills/pstack/topologies/hillclimb.md b/skills/pstack/topologies/hillclimb.md index f063d04..c544032 100644 --- a/skills/pstack/topologies/hillclimb.md +++ b/skills/pstack/topologies/hillclimb.md @@ -38,7 +38,7 @@ Order candidate hypotheses by the seven performance levers, cheapest and safest ### Parallel candidate execution (`cand-*`, `workspace: "share"`) -- Spawn `2` to `4` parallel `cand-*` workers (`cand-1`, `cand-2`, `cand-3`, `workspace: "share"`) when orthogonal mechanisms target the bottleneck. +- Spawn `2` to `4` parallel `cand-*` workers (`cand-1`, `cand-2`, `cand-3`, `workspace: "share"`) when orthogonal mechanisms target the bottleneck, or a single `cand-1` worker for one targeted fix. When `pstack-models.md` in `` configures a comma-separated model list for `cand-*`, pick the first live entry for a single-worker `cand-*` spawn and cycle live entries in order across parallel `cand-*` spawns (or omit `model` when unset or `inherit`). - Give each `cand-*` **one falsifiable mechanism** ("pre-index node IDs in a `Map` to eliminate O(N) scan in `resolveEdges`"), the frozen benchmark command, the behavioral test command, and strict instructions never to edit the benchmark harness or bundle unrelated tweaks. - Each `cand-*` commits its minimal change cleanly in its `share` worktree, runs a sanity check, and posts its commit SHA, `pwd` worktree path, and observed numbers to the board (`#seq`). diff --git a/skills/reflect/SKILL.md b/skills/reflect/SKILL.md index e7cc119..d9f1930 100644 --- a/skills/reflect/SKILL.md +++ b/skills/reflect/SKILL.md @@ -7,8 +7,8 @@ description: >- ro-judgment, ro-tooling, and ro-divergent reviewers, then dispatches impl-sharpen (workspace: "share") to encode approved fixes structurally in architecture, types, linters, hooks/guard.mjs, tests, role capsules, or - skills. Use for /reflect, "reflect on this session", "stop repeating this - mistake", "correct", or "sharpen this prompt". + skills. Use for /agy-pstack-next:reflect, /reflect, "reflect on this session", + "stop repeating this mistake", "correct", or "sharpen this prompt". --- # Reflect diff --git a/skills/statechart/SKILL.md b/skills/statechart/SKILL.md index 41a5e45..3b005c6 100644 --- a/skills/statechart/SKILL.md +++ b/skills/statechart/SKILL.md @@ -1,6 +1,11 @@ --- name: statechart -description: "Check a TLA+ model of a stateful flow, protocol, or service with TLC and render it as a Mermaid statechart in user terms. Marks every state that breaks an invariant and gives the shortest path to each bug. Pairs with /pstack, /crucible, /interrogate, and /verify-gen --formal." +description: >- + Check a TLA+ model of a stateful flow, protocol, or service with TLC and + render it as a Mermaid statechart in user terms. Marks every state that breaks + an invariant and gives the shortest path to each bug. Use for + /agy-pstack-next:statechart, /statechart, or formal state modeling paired with + /pstack, /crucible, /interrogate, and /verify-gen --formal. --- # Statechart diff --git a/skills/technical-writing/SKILL.md b/skills/technical-writing/SKILL.md index dd545bc..3a9bcd3 100644 --- a/skills/technical-writing/SKILL.md +++ b/skills/technical-writing/SKILL.md @@ -1,6 +1,11 @@ --- name: technical-writing -description: "Layered technical-writing standard combining Diataxis modes, Google developer style, STE single-thought instruction rules, Global English syntax, zero-slop prose hygiene, and ro-* technical accuracy checks. Use for docs, guides, RFCs, READMEs, PR bodies, and commit messages." +description: >- + Layered technical-writing standard combining Diataxis modes, Google developer + style, STE single-thought instruction rules, Global English syntax, zero-slop + prose hygiene, and ro-* technical accuracy checks. Use for + /agy-pstack-next:technical-writing, /technical-writing, docs, guides, RFCs, + READMEs, PR bodies, and commit messages. --- # Technical Writing diff --git a/skills/understand/SKILL.md b/skills/understand/SKILL.md index 2d5e6c6..3d86fd5 100644 --- a/skills/understand/SKILL.md +++ b/skills/understand/SKILL.md @@ -4,9 +4,9 @@ description: >- Unifies runtime mechanism walkthroughs (how), historical provenance and multi-source code archaeology (why), and interactive Socratic explanations (teach) over a parallel read-only ro-* clue-sharing swarm mesh, with warm fork - handoff into implementation. Use for /understand, "how does X work", "where - should this live", "why is X shaped this way", "where did this number come - from", or "teach me X". + handoff into implementation. Use for /agy-pstack-next:understand, /understand, + "how does X work", "where should this live", "why is X shaped this way", + "where did this number come from", or "teach me X". --- # Understand diff --git a/skills/verify-gen/SKILL.md b/skills/verify-gen/SKILL.md index 801e6fa..3d798b7 100644 --- a/skills/verify-gen/SKILL.md +++ b/skills/verify-gen/SKILL.md @@ -1,6 +1,11 @@ --- name: verify-gen -description: "Create or maintain project-local behavioral E2E verification skills and formal property or state-machine verification skills. Supports default behavioral generation, --formal invariant checking (TLA+, PBT, SMT, statecharts), and --maintain diff-driven drift upkeep." +description: >- + Create or maintain project-local behavioral E2E verification skills and formal + property or state-machine verification skills. Supports default behavioral + generation, --formal invariant checking (TLA+, PBT, SMT, statecharts), and + --maintain diff-driven drift upkeep. Use for /agy-pstack-next:verify-gen, + /verify-gen, generating E2E verification skills, or maintaining formal checks. --- # Generate and Maintain Verification Skills From 3eda93fd64383846972caa7293c5b3ee626bdf9f Mon Sep 17 00:00:00 2001 From: Kaitian Xie Date: Sun, 15 Nov 2026 13:11:23 +0800 Subject: [PATCH 4/9] Add regression tests for unbound Path classes and aliased Python FS receivers --- hooks/guard.test.mjs | 105 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) diff --git a/hooks/guard.test.mjs b/hooks/guard.test.mjs index cf8d60e..92c0144 100644 --- a/hooks/guard.test.mjs +++ b/hooks/guard.test.mjs @@ -3021,4 +3021,109 @@ if (process.env.MOCK_CLI_MODE === "hang") { setTimeout(() => {}, 10000); } else sb.cleanup(); } }); + + test("blocks unbound Python Path classes, parenthesized or aliased os and Path receivers, and type or __class__ escapes across all worker roles", () => { + const sb = makeSandbox(); + try { + writeSwarmMembers(sb.appDataDir, "coord-py-unbound", { + coordinator: { conversation_id: "coord-py-unbound", role: "coordinator" }, + "ro-u": { conversation_id: "ro-u-id", role: "worker" }, + "impl-u": { conversation_id: "impl-u-id", role: "worker" }, + "adv-u": { conversation_id: "adv-u-id", role: "worker" }, + "sicko-u": { conversation_id: "sicko-u-id", role: "worker" }, + }); + + const runRolePy = (convId, CommandLine) => + runGuard( + { + hookEventName: "PreToolUse", + conversationId: convId, + rootConversationId: "coord-py-unbound", + cwd: sb.worktree, + toolCall: { id: "py-unb", name: "run_command", args: { CommandLine } }, + }, + { PSTACK_APPDATA_DIR: sb.appDataDir, TMPDIR: sb.customTmpDir }, + ); + + const outsideDst = join(sb.outsideDir, "dst"); + const outsideFile = join(sb.outsideDir, "f"); + + const deniedForAllRoles = [ + `python3 -c "from pathlib import Path; Path.replace(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import Path; Path.replace(Path('/tmp/src'), '/Users/repo/dst')"`, + `python3 -c "import pathlib; pathlib.Path.replace(pathlib.Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import PosixPath; PosixPath.replace(PosixPath('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import PurePath; PurePath.replace(PurePath('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import WindowsPath; WindowsPath.replace(WindowsPath('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import PurePosixPath; PurePosixPath.replace(PurePosixPath('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import PureWindowsPath; PureWindowsPath.replace(PureWindowsPath('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import Path; Path.rename(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import Path; Path.write_text(Path('${outsideFile}'), 'x')"`, + `python3 -c "from pathlib import Path; (Path).replace(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "import pathlib; ((pathlib).Path).replace(pathlib.Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "import os; (os).replace('/tmp/src', '${outsideDst}')"`, + `python3 -c "import os; (os).rename('/tmp/src', '${outsideDst}')"`, + `python3 -c "import os; (os).replace('${outsideDst}', '/tmp/dst')"`, + `python3 -c "import os; (os).rename('${outsideDst}', '/tmp/dst')"`, + `python3 -c "import os; m = os; m.replace('/tmp/src', '${outsideDst}')"`, + `python3 -c "import os; m = os; m.rename('/tmp/src', '${outsideDst}')"`, + `python3 -c "import os; m = os; m.replace('${outsideDst}', '/tmp/dst')"`, + `python3 -c "import shutil; m = shutil; m.move('/tmp/src', '${outsideDst}')"`, + `python3 -c "from pathlib import Path; P = Path; P.replace(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import Path; P = Path; P.write_text(Path('${outsideFile}'), 'x')"`, + `python3 -c "from pathlib import Path as P; P.replace(P('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import Path; p = Path('/tmp/src'); p.__class__.replace(p, '${outsideDst}')"`, + `python3 -c "from pathlib import Path; p = Path('/tmp/src'); type(p).replace(p, '${outsideDst}')"`, + `python3 -c "from pathlib import Path; p = Path('/tmp/src'); C = p.__class__; C.replace(p, '${outsideDst}')"`, + `python3 -c "from pathlib import Path; p = Path('/tmp/src'); T = type(p); T.replace(p, '${outsideDst}')"`, + `python3 -c "import sys, os; sys.modules.get('os').replace('/tmp/src', '${outsideDst}')"`, + ]; + + for (const convId of ["ro-u-id", "impl-u-id", "adv-u-id", "sicko-u-id"]) { + for (const cmd of deniedForAllRoles) { + assert.equal(runRolePy(convId, cmd).decision, "deny", `expected ${convId} deny for ${cmd}`); + } + } + + for (const convId of ["ro-u-id", "impl-u-id", "adv-u-id"]) { + assert.equal( + runRolePy(convId, `python3 -c "import os; (os).replace('/tmp/src', '/tmp/dst')"`).decision, + "allow", + ); + assert.equal( + runRolePy(convId, `python3 -c "import os; m = os; m.rename('/tmp/src', '/tmp/dst')"`).decision, + "allow", + ); + } + assert.equal( + runRolePy("sicko-u-id", `python3 -c "import os; (os).replace('/tmp/src', '/tmp/dst')"`).decision, + "deny", + ); + + const legitStrReplaceCmds = [ + `python3 -c "print('hello'.replace('e', 'a'))"`, + `python3 -c "print(('hello').replace('e', 'a'))"`, + `python3 -c "name = 'world'; print(f'hi {name}'.replace('hi', 'hello'))"`, + `python3 -c "from pathlib import Path; print(Path('README.md').read_text().replace('a', 'b'))"`, + `python3 -c "s = ' foo '; print(s.strip().replace('foo', 'bar'))"`, + `python3 -c "s = 'FOO'; print(s.lower().replace('foo', 'bar'))"`, + `python3 -c "s = 'foo'; print(s.upper().replace('FOO', 'BAR'))"`, + `python3 -c "raw = b'foo'; print(raw.decode('utf-8').replace('foo', 'bar'))"`, + `python3 -c "print('hello {}'.format('world').replace('world', 'swarm'))"`, + `python3 -c "items = ['a', 'b']; print(','.join(items).replace(',', ';'))"`, + `python3 -c "import os; print(os.environ.get('PATH', '').replace('/usr', '/opt'))"`, + `python3 -c "d = {'k': 'val'}; print(d.get('k', '').replace('val', 'ok'))"`, + `python3 -c "print(str(123).replace('2', '9'))"`, + `python3 -c "s = 'foobar'; print(s.replace('foo', 'bar').replace('bar', 'baz'))"`, + ]; + + for (const convId of ["ro-u-id", "impl-u-id", "adv-u-id", "sicko-u-id"]) { + for (const cmd of legitStrReplaceCmds) { + assert.equal(runRolePy(convId, cmd).decision, "allow", `expected ${convId} allow for ${cmd}`); + } + } + } finally { + sb.cleanup(); + } + }); }); From 96f7ae50ca951b7c6915a611a46367eafdf577ce Mon Sep 17 00:00:00 2001 From: Kaitian Xie Date: Sun, 15 Nov 2026 13:18:15 +0800 Subject: [PATCH 5/9] Block unbound Python Path classes and validate aliased FS module receivers --- hooks/guard.mjs | 666 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 622 insertions(+), 44 deletions(-) diff --git a/hooks/guard.mjs b/hooks/guard.mjs index e482906..82f24f2 100755 --- a/hooks/guard.mjs +++ b/hooks/guard.mjs @@ -2679,7 +2679,545 @@ const NODE_MUTATION_NAME_RE = /\b(?:writeFileSync|writeFile|appendFileSync|appendFile|unlinkSync|unlink|rmSync|rm|rmdirSync|rmdir|renameSync|rename|copyFileSync|copyFile|cpSync|cp|mkdirSync|mkdir|mkdtempSync|mkdtemp|chmodSync|chmod|chownSync|chown|truncateSync|truncate|symlinkSync|symlink|linkSync|link|createWriteStream|openSync)\b/; const PYTHON_MUTATION_NAME_RE = - /\b(?:remove|unlink|rmdir|removedirs|mkdir|makedirs|chmod|chown|truncate|rename|renames|replace|rmtree|move|copy|copy2|copyfile|copytree|symlink|link|write_text|write_bytes|touch|lchmod|symlink_to|hardlink_to|link_to)\b/; + /\b(?:remove|unlink|rmdir|removedirs|mkdir|makedirs|chmod|lchmod|chown|truncate|rename|renames|replace|rmtree|move|copy|copy2|copyfile|copytree|symlink|link|write_text|write_bytes|touch|symlink_to|hardlink_to|link_to)\b/; + +const PYTHON_PATH_CLASS_NAMES = new Set([ + "Path", + "PurePath", + "PosixPath", + "WindowsPath", + "PurePosixPath", + "PureWindowsPath", +]); + +const PYTHON_FS_MODULE_NAMES = new Set(["os", "posix", "shutil"]); + +const PYTHON_OS_SHUTIL_FN_NAMES = new Set([ + "remove", + "unlink", + "rmdir", + "removedirs", + "mkdir", + "makedirs", + "chmod", + "lchmod", + "chown", + "truncate", + "rename", + "renames", + "replace", + "rmtree", + "move", + "copy", + "copy2", + "copyfile", + "copytree", + "symlink", + "link", +]); + +const PYTHON_STRING_RETURNING_METHODS = new Set([ + "read_text", + "read", + "readline", + "strip", + "lstrip", + "rstrip", + "lower", + "upper", + "casefold", + "title", + "capitalize", + "swapcase", + "decode", + "format", + "format_map", + "join", + "removeprefix", + "removesuffix", + "expandtabs", + "zfill", + "center", + "ljust", + "rjust", + "translate", +]); + +const PYTHON_STATEMENT_KEYWORDS = new Set([ + "and", + "as", + "assert", + "await", + "case", + "del", + "elif", + "else", + "for", + "from", + "if", + "import", + "in", + "is", + "lambda", + "not", + "or", + "raise", + "return", + "while", + "with", + "yield", +]); + +function findMatchingCloseForward(str, openIdx) { + let depth = 0; + let quote = null; + let i = openIdx; + while (i < str.length) { + const ch = str[i]; + if (quote) { + if (ch === "\\") { + i += 2; + continue; + } + if (quote.length === 3) { + if (str.slice(i, i + 3) === quote) { + quote = null; + i += 3; + continue; + } + } else if (ch === quote) { + quote = null; + } + i += 1; + continue; + } + if (str.slice(i, i + 3) === "'''" || str.slice(i, i + 3) === '"""') { + quote = str.slice(i, i + 3); + i += 3; + continue; + } + if (ch === "'" || ch === '"' || ch === "`") { + quote = ch; + i += 1; + continue; + } + if (ch === "(" || ch === "[" || ch === "{") { + depth += 1; + } else if (ch === ")" || ch === "]" || ch === "}") { + depth -= 1; + if (depth === 0) return i; + } + i += 1; + } + return -1; +} + +function stripBalancedOuterParens(expr) { + let cur = String(expr || "").trim(); + while (cur.startsWith("(") && cur.endsWith(")")) { + if (findMatchingCloseForward(cur, 0) !== cur.length - 1) break; + cur = cur.slice(1, -1).trim(); + } + return cur; +} + +function scanPythonTokensBefore(code, limitIdx) { + const tokens = []; + const openStack = []; + let i = 0; + const end = Math.min(limitIdx, code.length); + while (i < end) { + const ch = code[i]; + if (/\s/.test(ch)) { + i += 1; + continue; + } + if (ch === "#") { + while (i < end && code[i] !== "\n") i += 1; + continue; + } + const strPrefix = code.slice(i, Math.min(end, i + 5)).match(/^([rRbBuUfF]{0,2})('''|"""|'|"|`)/); + if (strPrefix) { + const start = i; + const q = strPrefix[2]; + i += strPrefix[0].length; + while (i < end) { + if (code[i] === "\\") { + i += 2; + continue; + } + if (q.length === 3) { + if (code.slice(i, i + 3) === q) { + i += 3; + break; + } + } else if (code[i] === q) { + i += 1; + break; + } + i += 1; + } + tokens.push({ kind: "string", start, end: Math.min(i, end) }); + continue; + } + if (/[A-Za-z_]/.test(ch)) { + const start = i; + while (i < end && /[A-Za-z0-9_]/.test(code[i])) i += 1; + tokens.push({ kind: "ident", start, end: i, text: code.slice(start, i) }); + continue; + } + if (ch === "(" || ch === "[" || ch === "{") { + const idx = tokens.length; + tokens.push({ kind: "open", start: i, end: i + 1, ch }); + openStack.push(idx); + i += 1; + continue; + } + if (ch === ")" || ch === "]" || ch === "}") { + const openTokenIdx = openStack.length > 0 ? openStack.pop() : -1; + tokens.push({ kind: "close", start: i, end: i + 1, ch, openTokenIdx }); + i += 1; + continue; + } + if (ch === ".") { + tokens.push({ kind: "dot", start: i, end: i + 1 }); + i += 1; + continue; + } + tokens.push({ kind: "other", start: i, end: i + 1, ch }); + i += 1; + } + return tokens; +} + +function extractPythonReceiverBeforeDot(code, dotIdx) { + const tokens = scanPythonTokensBefore(code, dotIdx); + if (tokens.length === 0) return ""; + let cur = tokens.length - 1; + const endCharIdx = tokens[cur].end; + let startCharIdx = null; + while (cur >= 0) { + const tok = tokens[cur]; + if (tok.kind === "string") { + startCharIdx = tok.start; + break; + } + if (tok.kind === "close") { + if (tok.openTokenIdx < 0) return null; + startCharIdx = tokens[tok.openTokenIdx].start; + cur = tok.openTokenIdx - 1; + if ( + cur >= 0 && + (tokens[cur].kind === "ident" || tokens[cur].kind === "close" || tokens[cur].kind === "string") + ) { + continue; + } + if (cur >= 0 && tokens[cur].kind === "dot") { + startCharIdx = tokens[cur].start; + cur -= 1; + continue; + } + break; + } + if (tok.kind === "ident") { + if (cur === 0 || tokens[cur - 1].kind !== "dot") { + if (PYTHON_STATEMENT_KEYWORDS.has(tok.text)) break; + startCharIdx = tok.start; + break; + } + startCharIdx = tokens[cur - 1].start; + cur -= 2; + if (cur < 0) return null; + continue; + } + break; + } + if (startCharIdx === null) return ""; + return code.slice(startCharIdx, endCharIdx); +} + +function isSinglePyStringLiteralExpr(expr) { + const trimmed = stripBalancedOuterParens(expr); + if (!trimmed) return false; + const tokens = scanPythonTokensBefore(trimmed, trimmed.length); + return tokens.length === 1 && tokens[0].kind === "string"; +} + +function isPythonPathlibModuleExpr(rawExpr, symbols) { + const expr = stripBalancedOuterParens(rawExpr); + if (!expr) return false; + if (symbols.pathlibModuleIdents.has(expr)) return true; + if ( + /^(?:__import__|builtins\s*\.\s*__import__|importlib\s*\.\s*import_module|import_module)\s*\(\s*['"]pathlib['"]\s*\)$/.test( + expr, + ) + ) { + return true; + } + return /^sys\s*\.\s*modules\s*(?:\[\s*['"]pathlib['"]\s*\]|\.\s*get\s*\(\s*['"]pathlib['"])/.test(expr); +} + +function isPythonFsModuleExpr(rawExpr, symbols) { + const expr = stripBalancedOuterParens(rawExpr); + if (!expr) return false; + if (symbols.fsModuleIdents.has(expr)) return true; + if ( + /^(?:__import__|builtins\s*\.\s*__import__|importlib\s*\.\s*import_module|import_module)\s*\(\s*['"](?:os|posix|shutil)['"]\s*\)$/.test( + expr, + ) + ) { + return true; + } + return /^sys\s*\.\s*modules\s*(?:\[\s*['"](?:os|posix|shutil)['"]\s*\]|\.\s*get\s*\(\s*['"](?:os|posix|shutil)['"])/.test( + expr, + ); +} + +function isPythonPathClassExpr(rawExpr, symbols) { + const expr = stripBalancedOuterParens(rawExpr); + if (!expr) return false; + if (symbols.pathClassIdents.has(expr)) return true; + const tokens = scanPythonTokensBefore(expr, expr.length); + if (tokens.length === 0) return false; + const last = tokens[tokens.length - 1]; + if (last.kind === "ident" && tokens.length >= 3 && tokens[tokens.length - 2].kind === "dot") { + const attr = last.text; + const base = expr.slice(0, tokens[tokens.length - 2].start); + if (attr === "__class__") return true; + if (PYTHON_PATH_CLASS_NAMES.has(attr) && isPythonPathlibModuleExpr(base, symbols)) { + return true; + } + } + if (last.kind === "close" && last.ch === ")" && last.openTokenIdx > 0) { + const callee = stripBalancedOuterParens(expr.slice(0, tokens[last.openTokenIdx].start)); + if (callee === "type" || callee === "builtins.type") return true; + if (callee === "getattr") { + const args = parseCallArguments(expr, tokens[last.openTokenIdx].start); + if (args && args.length >= 2) { + const attrLit = parseStaticPyString(args[1]); + if (attrLit.ok && PYTHON_PATH_CLASS_NAMES.has(attrLit.value)) return true; + } + } + } + return false; +} + +function isPythonPathCtorCallExpr(rawExpr, symbols) { + const expr = stripBalancedOuterParens(rawExpr); + if (!expr) return null; + const tokens = scanPythonTokensBefore(expr, expr.length); + if (tokens.length < 2) return null; + const last = tokens[tokens.length - 1]; + if (last.kind !== "close" || last.ch !== ")" || last.openTokenIdx <= 0) return null; + const callee = stripBalancedOuterParens(expr.slice(0, tokens[last.openTokenIdx].start)); + let isPathCallee = symbols.pathClassIdents.has(callee) || PYTHON_PATH_CLASS_NAMES.has(callee); + if (!isPathCallee) { + const calleeTokens = scanPythonTokensBefore(callee, callee.length); + if ( + calleeTokens.length >= 3 && + calleeTokens[calleeTokens.length - 1].kind === "ident" && + calleeTokens[calleeTokens.length - 2].kind === "dot" + ) { + const attr = calleeTokens[calleeTokens.length - 1].text; + const base = callee.slice(0, calleeTokens[calleeTokens.length - 2].start); + if (PYTHON_PATH_CLASS_NAMES.has(attr) && isPythonPathlibModuleExpr(base, symbols)) { + isPathCallee = true; + } + } + } + if (!isPathCallee) return null; + return parseCallArguments(expr, tokens[last.openTokenIdx].start); +} + +function collectPythonSymbolBindings(code) { + const pathClassIdents = new Set(PYTHON_PATH_CLASS_NAMES); + const fsModuleIdents = new Set(PYTHON_FS_MODULE_NAMES); + const pathlibModuleIdents = new Set(["pathlib"]); + const taintedIdents = new Set([ + ...pathClassIdents, + ...fsModuleIdents, + ...pathlibModuleIdents, + "sys", + "builtins", + "importlib", + "posixpath", + "ntpath", + "genericpath", + "io", + "type", + ]); + + const plainImportRe = /(?:^|[\n;])\s*import\s+([^\n;#]+)/g; + let im; + while ((im = plainImportRe.exec(code)) !== null) { + for (const part of im[1].split(",")) { + const m = part.trim().match(/^([A-Za-z_][A-Za-z0-9_.]*)(?:\s+as\s+([A-Za-z_][A-Za-z0-9_]*))?$/); + if (!m) continue; + const mod = m[1]; + const bound = m[2] || mod.split(".")[0]; + taintedIdents.add(bound); + if (PYTHON_FS_MODULE_NAMES.has(mod)) fsModuleIdents.add(bound); + if (mod === "pathlib") pathlibModuleIdents.add(bound); + } + } + + const fromImportRe = /\bfrom\s+([A-Za-z_][A-Za-z0-9_.]*)\s+import\s+([^\n;#]+)/g; + while ((im = fromImportRe.exec(code)) !== null) { + const mod = im[1]; + const clause = stripBalancedOuterParens(im[2]); + for (const part of clause.split(",")) { + const m = part.trim().match(/^([A-Za-z_][A-Za-z0-9_]*)(?:\s+as\s+([A-Za-z_][A-Za-z0-9_]*))?$/); + if (!m) continue; + const orig = m[1]; + const bound = m[2] || orig; + taintedIdents.add(bound); + if (mod === "pathlib" && PYTHON_PATH_CLASS_NAMES.has(orig)) pathClassIdents.add(bound); + if (PYTHON_FS_MODULE_NAMES.has(orig)) fsModuleIdents.add(bound); + if (orig === "pathlib") pathlibModuleIdents.add(bound); + } + } + + const pairs = []; + const assignStmtRe = /(?:^|[\n;])\s*([A-Za-z_][A-Za-z0-9_]*(?:\s*,\s*[A-Za-z_][A-Za-z0-9_]*|\s*=\s*[A-Za-z_][A-Za-z0-9_]*)*)\s*=(?!=)\s*([^\n;#]+)/g; + let am; + while ((am = assignStmtRe.exec(code)) !== null) { + const lhsRaw = am[1].trim(); + const rhsRaw = am[2].trim(); + if (lhsRaw.includes(",")) { + const lhsNames = lhsRaw.split(",").map((s) => s.trim()); + const rhsTuple = parseCallArguments(`(${stripBalancedOuterParens(rhsRaw)})`, 0); + if (rhsTuple && rhsTuple.length === lhsNames.length) { + for (let idx = 0; idx < lhsNames.length; idx += 1) { + pairs.push([lhsNames[idx], rhsTuple[idx]]); + } + } else { + for (const name of lhsNames) pairs.push([name, rhsRaw]); + } + } else { + for (const name of lhsRaw.split("=").map((s) => s.trim())) { + if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) pairs.push([name, rhsRaw]); + } + } + } + + const walrusRe = /\b([A-Za-z_][A-Za-z0-9_]*)\s*:=\s*([^,)\]\n;#]+)/g; + while ((am = walrusRe.exec(code)) !== null) { + pairs.push([am[1], am[2].trim()]); + } + + const forLoopRe = /\bfor\s+([A-Za-z_][A-Za-z0-9_]*)\s+in\s+([^\n:#]+):/g; + const forPairs = []; + while ((am = forLoopRe.exec(code)) !== null) { + forPairs.push([am[1], am[2].trim()]); + } + + const symbols = { pathClassIdents, fsModuleIdents, pathlibModuleIdents, taintedIdents }; + for (let pass = 0; pass < 4; pass += 1) { + const beforeSize = + pathClassIdents.size + fsModuleIdents.size + pathlibModuleIdents.size + taintedIdents.size; + for (const [lhs, rhs] of pairs) { + if (isPythonFsModuleExpr(rhs, symbols)) { + fsModuleIdents.add(lhs); + taintedIdents.add(lhs); + } else if (isPythonPathlibModuleExpr(rhs, symbols)) { + pathlibModuleIdents.add(lhs); + taintedIdents.add(lhs); + } else if (isPythonPathClassExpr(rhs, symbols)) { + pathClassIdents.add(lhs); + taintedIdents.add(lhs); + } else { + const stripped = stripBalancedOuterParens(rhs); + if ( + taintedIdents.has(stripped) || + isPythonPathCtorCallExpr(stripped, symbols) !== null || + /\b(?:__import__|import_module|globals|locals|vars|getattr|type)\s*\(|\b(?:__class__|__base__|__bases__|__mro__|__subclasses__|__dict__)\b|sys\s*\.\s*modules/.test( + stripped, + ) + ) { + taintedIdents.add(lhs); + } + } + } + for (const [loopVar, iterExpr] of forPairs) { + const iterTokens = scanPythonTokensBefore(iterExpr, iterExpr.length); + for (const tok of iterTokens) { + if (tok.kind !== "ident") continue; + if (pathClassIdents.has(tok.text) || tok.text === "type" || tok.text === "__class__") { + pathClassIdents.add(loopVar); + taintedIdents.add(loopVar); + } else if (fsModuleIdents.has(tok.text)) { + fsModuleIdents.add(loopVar); + taintedIdents.add(loopVar); + } else if (pathlibModuleIdents.has(tok.text)) { + pathlibModuleIdents.add(loopVar); + taintedIdents.add(loopVar); + } + } + } + const afterSize = + pathClassIdents.size + fsModuleIdents.size + pathlibModuleIdents.size + taintedIdents.size; + if (afterSize === beforeSize) break; + } + + return symbols; +} + +function isValidStrReplaceArgs(methodArgs) { + const effective = + methodArgs.length > 0 && methodArgs[methodArgs.length - 1] === "" + ? methodArgs.slice(0, -1) + : methodArgs; + if (effective.length !== 2 && effective.length !== 3) return false; + if (effective.some((a) => a.length === 0 || a.startsWith("*"))) return false; + const { positionals, kwargs } = splitPythonCallArgs(effective); + const kwKeys = Object.keys(kwargs); + if (kwKeys.length === 0) { + return positionals.length === 2 || positionals.length === 3; + } + return positionals.length === 2 && kwKeys.length === 1 && kwKeys[0] === "count"; +} + +function isSafeStrReplaceReceiver(rawExpr, symbols, depth = 0) { + if (depth > 6 || rawExpr === null) return false; + const expr = stripBalancedOuterParens(rawExpr); + if (!expr) return false; + if (isPythonPathClassExpr(expr, symbols) || isPythonFsModuleExpr(expr, symbols)) return false; + if (isSinglePyStringLiteralExpr(expr)) return true; + if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(expr)) { + return !symbols.taintedIdents.has(expr); + } + const tokens = scanPythonTokensBefore(expr, expr.length); + if (tokens.length < 2) return false; + const last = tokens[tokens.length - 1]; + if (last.kind !== "close" || last.ch !== ")" || last.openTokenIdx <= 0) return false; + const callArgs = parseCallArguments(expr, tokens[last.openTokenIdx].start); + if (!callArgs) return false; + if (last.openTokenIdx === 1 && tokens[0].kind === "ident") { + const fn = tokens[0].text; + return ["str", "repr", "chr", "format", "ascii"].includes(fn) && !symbols.taintedIdents.has(fn); + } + if ( + last.openTokenIdx >= 3 && + tokens[last.openTokenIdx - 1].kind === "ident" && + tokens[last.openTokenIdx - 2].kind === "dot" + ) { + const methodName = tokens[last.openTokenIdx - 1].text; + const subRecv = stripBalancedOuterParens(expr.slice(0, tokens[last.openTokenIdx - 2].start)); + if (!subRecv) return false; + if (methodName === "replace") { + return isValidStrReplaceArgs(callArgs) && isSafeStrReplaceReceiver(subRecv, symbols, depth + 1); + } + if (methodName === "get") { + if (subRecv === "os.environ" || subRecv === "posix.environ") return true; + return /^[A-Za-z_][A-Za-z0-9_]*$/.test(subRecv) && !symbols.taintedIdents.has(subRecv); + } + if (methodName === "dumps" && subRecv === "json") return true; + if (PYTHON_STRING_RETURNING_METHODS.has(methodName)) { + return !isPythonPathClassExpr(subRecv, symbols) && !isPythonFsModuleExpr(subRecv, symbols); + } + } + return false; +} function isVarBoundToVerifiedTmpRoot(varName, code) { if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(varName)) return false; @@ -2742,9 +3280,20 @@ function isSafeTmpTemplateOrJoin(expr, code, allowPath) { return false; } -function unwrapPythonPathCtor(expr) { - const trimmed = String(expr || "").trim(); - const m = trimmed.match(/^(?:pathlib\s*\.\s*)?Path\s*\(([\s\S]*)\)$/); +function unwrapPythonPathCtor(expr, symbols = null) { + const trimmed = stripBalancedOuterParens(expr); + if (!trimmed) return ""; + if (symbols) { + const ctorArgs = isPythonPathCtorCallExpr(trimmed, symbols); + if (ctorArgs) { + if (ctorArgs.length === 0) return trimmed; + if (ctorArgs.length === 1) return ctorArgs[0].trim(); + return `os.path.join(${ctorArgs.join(", ")})`; + } + } + const m = trimmed.match( + /^(?:pathlib\s*\.\s*)?(?:Path|PurePath|PosixPath|WindowsPath|PurePosixPath|PureWindowsPath)\s*\(([\s\S]*)\)$/, + ); if (!m) return trimmed; const args = parseCallArguments(`(${m[1]})`, 0); if (!args || args.length === 0) return trimmed; @@ -3176,8 +3725,10 @@ function checkInlinePythonFs(code, allowPath, options = {}) { return `Aliased filesystem mutation API in inline Python script is blocked for ${roleLabel}.`; } + const pySymbols = collectPythonSymbolBindings(code); + const checkPyPathArg = (argExpr, opts) => { - const rawExpr = unwrapPythonPathCtor(argExpr || ""); + const rawExpr = unwrapPythonPathCtor(argExpr || "", pySymbols); const lit = parseStaticPyString(rawExpr); if (lit.ok) { return allowPath(lit.value, opts); @@ -3199,29 +3750,26 @@ function checkInlinePythonFs(code, allowPath, options = {}) { return allowDynamicPaths; }; - const resolvePythonPathReceiverArg = (prefixStr) => { - const ctorMatch = prefixStr.match(/(?:pathlib\s*\.\s*)?Path\s*\(\s*([^()]*)\s*\)\s*$/); - if (ctorMatch) { - const ctorArgs = parseCallArguments(`(${ctorMatch[1]})`, 0); - if (!ctorArgs || ctorArgs.length !== 1) return { valid: false, found: true, expr: null }; + const resolvePythonPathReceiverArg = (rawRecv) => { + if (rawRecv === null) return { valid: false, found: true, expr: null }; + const recvExpr = stripBalancedOuterParens(rawRecv); + const ctorArgs = isPythonPathCtorCallExpr(recvExpr, pySymbols); + if (ctorArgs !== null) { + if (ctorArgs.length !== 1) return { valid: false, found: true, expr: null }; return { valid: true, found: true, expr: ctorArgs[0] }; } - const varMatch = prefixStr.match(/(?:^|[^\w.])([A-Za-z_][A-Za-z0-9_]*)\s*$/); - if (varMatch) { - const varEsc = varMatch[1].replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); - const assignRe = new RegExp( - `(?:^|[\\n;])\\s*${varEsc}\\s*=\\s*(?:pathlib\\s*\\.\\s*)?Path\\s*\\(\\s*([^()]*)\\s*\\)`, - "g", - ); - let lastBody = null; + if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(recvExpr)) { + const varEsc = recvExpr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + const assignRe = new RegExp(`(?:^|[\\n;])\\s*${varEsc}\\s*=\\s*([^\\n;#]+)`, "g"); + let lastRhs = null; let am; while ((am = assignRe.exec(code)) !== null) { - lastBody = am[1]; + lastRhs = am[1].trim(); } - if (lastBody !== null) { - const boundArgs = parseCallArguments(`(${lastBody})`, 0); - if (boundArgs && boundArgs.length === 1) { - return { valid: true, found: true, expr: boundArgs[0] }; + if (lastRhs !== null) { + const boundCtorArgs = isPythonPathCtorCallExpr(lastRhs, pySymbols); + if (boundCtorArgs !== null && boundCtorArgs.length === 1) { + return { valid: true, found: true, expr: boundCtorArgs[0] }; } } } @@ -3253,6 +3801,16 @@ function checkInlinePythonFs(code, allowPath, options = {}) { if (!methodArgs) { return `Unparseable .${method}() call in inline Python script is blocked for ${roleLabel}.`; } + const rawRecv = extractPythonReceiverBeforeDot(code, match.index); + if (rawRecv === null) { + return `Unparseable .${method}() receiver in inline Python script is blocked for ${roleLabel}.`; + } + if (isPythonPathClassExpr(rawRecv, pySymbols)) { + return `Unbound Python Path.${method}() call in inline Python script is blocked for ${roleLabel}.`; + } + if (PYTHON_OS_SHUTIL_FN_NAMES.has(method) && isPythonFsModuleExpr(rawRecv, pySymbols)) { + continue; + } if (method === "open") { const { positionals, kwargs } = splitPythonCallArgs(methodArgs); const modeExpr = positionals[0] ?? kwargs.mode ?? null; @@ -3262,20 +3820,14 @@ function checkInlinePythonFs(code, allowPath, options = {}) { continue; } } - if (method === "replace") { - const effectiveArgs = - methodArgs.length > 0 && methodArgs[methodArgs.length - 1] === "" - ? methodArgs.slice(0, -1) - : methodArgs; - if ( - effectiveArgs.length >= 2 && - effectiveArgs.every((a) => a.length > 0 && !a.startsWith("*")) - ) { - continue; - } + if ( + method === "replace" && + isValidStrReplaceArgs(methodArgs) && + isSafeStrReplaceReceiver(rawRecv, pySymbols) + ) { + continue; } - const prefix = code.slice(0, match.index); - const recv = resolvePythonPathReceiverArg(prefix); + const recv = resolvePythonPathReceiverArg(rawRecv); const isMkdir = method === "mkdir"; const isLinkMethod = method === "symlink_to" || method === "hardlink_to" || method === "link_to"; @@ -3333,11 +3885,29 @@ function checkInlinePythonFs(code, allowPath, options = {}) { } } else if (method === "rename" || method === "replace") { const { positionals: mPos, kwargs: mKw } = splitPythonCallArgs(methodArgs); - const targetExpr = mPos[0] ?? mKw.target ?? ""; - const recvVal = recv.found ? resolveStaticArgValue(recv.expr, code, true) : null; + const isTwoArgCall = mPos.length >= 2 || (mPos.length === 1 && Object.hasOwn(mKw, "target")); + const srcArgExpr = isTwoArgCall ? mPos[0] : null; + const targetExpr = isTwoArgCall ? (mPos[1] ?? mKw.target ?? "") : (mPos[0] ?? mKw.target ?? ""); + const recvVal = srcArgExpr + ? resolveStaticArgValue(srcArgExpr, code, true) + : recv.found + ? resolveStaticArgValue(recv.expr, code, true) + : null; const srcOkForRoArtifact = allowReadOnlyArtifactCopySource ? Boolean(recvVal && allowReadOnlyArtifactCopySource(recvVal)) : Boolean(recvVal && /\.(?:png|jpe?g|webp)$/i.test(recvVal)); + if ( + srcArgExpr !== null && + !checkPyPathArg(srcArgExpr, { + allowRootEqual: false, + allowDevNull: false, + allowArtifactDir: false, + allowArtifactRoot: false, + disallowArtifactRoot: true, + }) + ) { + return `Inline Python Path.${method}() outside allowed roots is blocked for ${roleLabel}.`; + } if ( !targetExpr || !checkPyPathArg(targetExpr, { @@ -3376,13 +3946,21 @@ function checkInlinePythonFs(code, allowPath, options = {}) { const hasFsImport = /\b(?:os|posix|shutil)\b/.test(code); const osShutilRe = - /(?:(os|posix|shutil)\s*\.\s*|\b)(remove|unlink|rmdir|removedirs|mkdir|makedirs|chmod|chown|truncate|rename|renames|replace|rmtree|move|copy|copy2|copyfile|copytree|symlink|link)\s*\(/g; + /(?:(os|posix|shutil)\s*\.\s*|\b)(remove|unlink|rmdir|removedirs|mkdir|makedirs|chmod|lchmod|chown|truncate|rename|renames|replace|rmtree|move|copy|copy2|copyfile|copytree|symlink|link)\s*\(/g; while ((match = osShutilRe.exec(code)) !== null) { - const qualifier = match[1] || ""; + let qualifier = match[1] || ""; const fnName = match[2]; - const isMemberCall = !qualifier && /\.\s*$/.test(code.slice(0, match.index)); - if (!qualifier && (isMemberCall || !hasFsImport)) { - continue; + if (!qualifier) { + const dotMatch = code.slice(0, match.index).match(/\.\s*$/); + if (dotMatch) { + const memberRecv = extractPythonReceiverBeforeDot(code, match.index - dotMatch[0].length); + if (!isPythonFsModuleExpr(memberRecv, pySymbols)) { + continue; + } + qualifier = "fs_alias"; + } else if (!hasFsImport) { + continue; + } } const openParenIdx = match.index + match[0].length - 1; const callArgs = parseCallArguments(code, openParenIdx); @@ -3456,7 +4034,7 @@ function checkInlinePythonFs(code, allowPath, options = {}) { } const singleExpr = positionals[0] ?? kwargs.path ?? kwargs.name ?? ""; const isMkdir = fnName === "mkdir" || fnName === "makedirs"; - const forbidRo = ["rmdir", "removedirs", "rmtree", "chmod", "chown"].includes(fnName); + const forbidRo = ["rmdir", "removedirs", "rmtree", "chmod", "lchmod", "chown"].includes(fnName); if ( !singleExpr || !checkPyPathArg(singleExpr, { From 7d57647783e392ea34ac9cce7c10b26963aba841 Mon Sep 17 00:00:00 2001 From: Kaitian Xie Date: Sun, 15 Nov 2026 14:06:28 +0800 Subject: [PATCH 6/9] Add regression tests for Python Path subclasses, syntax continuations, reflection, and aliased FS imports --- hooks/guard.test.mjs | 139 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) diff --git a/hooks/guard.test.mjs b/hooks/guard.test.mjs index 92c0144..470b1a1 100644 --- a/hooks/guard.test.mjs +++ b/hooks/guard.test.mjs @@ -3126,4 +3126,143 @@ if (process.env.MOCK_CLI_MODE === "hang") { setTimeout(() => {}, 10000); } else sb.cleanup(); } }); + + test("blocks Python Path subclasses, comment and continuation dot obfuscation, reflection dispatch, and aliased os or shutil escapes across worker roles", () => { + const sb = makeSandbox(); + try { + writeSwarmMembers(sb.appDataDir, "coord-py-struct", { + coordinator: { conversation_id: "coord-py-struct", role: "coordinator" }, + "ro-s": { conversation_id: "ro-s-id", role: "worker" }, + "impl-s": { conversation_id: "impl-s-id", role: "worker" }, + "adv-s": { conversation_id: "adv-s-id", role: "worker" }, + "sicko-s": { conversation_id: "sicko-s-id", role: "worker" }, + }); + + const runRolePy = (convId, CommandLine) => + runGuard( + { + hookEventName: "PreToolUse", + conversationId: convId, + rootConversationId: "coord-py-struct", + cwd: sb.worktree, + toolCall: { id: "py-str", name: "run_command", args: { CommandLine } }, + }, + { PSTACK_APPDATA_DIR: sb.appDataDir, TMPDIR: sb.customTmpDir }, + ); + + const outsideDst = join(sb.outsideDir, "dst"); + const outsideFile = join(sb.outsideDir, "f"); + const worktreeDst = join(sb.worktree, "dst"); + + const deniedForAllRoles = [ + `python3 -c "from pathlib import Path\nclass S(Path):\n pass\nS.replace(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import PosixPath\nclass S(PosixPath):\n pass\nS.replace(PosixPath('/tmp/src'), '${outsideDst}')"`, + `python3 -c "import pathlib\nclass S(pathlib.Path):\n pass\nS.replace(pathlib.Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import PosixPath\nclass S1(PosixPath):\n pass\nclass S2(S1):\n pass\nS2.replace(PosixPath('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import PosixPath\nclass S1(PosixPath):\n pass\nclass S2(S1):\n pass\nS2('/tmp/src').replace('${outsideDst}')"`, + `python3 -c "from pathlib import Path\nclass S1(Path):\n pass\nclass S2(S1):\n pass\nS2('${outsideFile}').write_text('x')"`, + `python3 -c "from pathlib import Path\n(Path.#c\nreplace)(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import Path\n(Path('${outsideFile}').#c\nwrite_text)('x')"`, + `python3 -c "import os\n(os.#c\nreplace)('/tmp/src', '${outsideDst}')"`, + `python3 -c 'from pathlib import Path\nPath.\\\nreplace(Path("/tmp/src"), "${outsideDst}")'`, + `python3 -c 'from pathlib import Path\nPath("${outsideFile}").\\\nwrite_text("x")'`, + `python3 -c 'import os\nos.\\\nreplace("/tmp/src", "${outsideDst}")'`, + `python3 -c "from pathlib import Path; (Path.replace)(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "import os; (os.replace)('/tmp/src', '${outsideDst}')"`, + `python3 -c "import os; ((os.replace))('/tmp/src', '${outsideDst}')"`, + `python3 -c "import os\n((os.#c\nreplace))('/tmp/src', '${outsideDst}')"`, + `python3 -c "from pathlib import Path; (Path('${outsideFile}').write_text)('x')"`, + `python3 -c 'from pathlib import Path\nPath.replace\\\n(Path("/tmp/src"), "${outsideDst}")'`, + `python3 -c "import os\n(os.replace #c\n)('/tmp/src', '${outsideDst}')"`, + `python3 -c "import os; getattr(os, 'replace')('/tmp/src', '${outsideDst}')"`, + `python3 -c "from pathlib import Path; getattr(Path, 'replace')(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "import os; setattr(os, 'x', 1)"`, + `python3 -c "import os; delattr(os, 'x')"`, + `python3 -c "import os; vars(os)['replace']('/tmp/src', '${outsideDst}')"`, + `python3 -c "from pathlib import Path; globals()['Path'].replace(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import Path; locals()['Path'].replace(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "import os; os.__dict__['replace']('/tmp/src', '${outsideDst}')"`, + `python3 -c "from pathlib import Path; Path.__dict__['replace'](Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "import os; os.__getattribute__('replace')('/tmp/src', '${outsideDst}')"`, + `python3 -c "from pathlib import Path; p = Path('/tmp/src'); p.__getattr__('replace')('${outsideDst}')"`, + `python3 -c "from pathlib import Path; Path.__subclasses__()[0].replace(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import Path; Path.__mro__[0].replace(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import PosixPath; PosixPath.__bases__[0].replace(PosixPath('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import PosixPath; PosixPath.__base__.replace(PosixPath('/tmp/src'), '${outsideDst}')"`, + `python3 -c "import operator; from pathlib import Path; operator.methodcaller('replace', '${outsideDst}')(Path('/tmp/src'))"`, + `python3 -c "import operator, os; operator.attrgetter('replace')(os)('/tmp/src', '${outsideDst}')"`, + `python3 -c "from operator import methodcaller; from pathlib import Path; methodcaller('replace', '${outsideDst}')(Path('/tmp/src'))"`, + `python3 -c "from operator import attrgetter; import os; attrgetter('replace')(os)('/tmp/src', '${outsideDst}')"`, + `python3 -c "from os import replace as r; r('/tmp/src', '${outsideDst}')"`, + `python3 -c "from os import replace as r; r('${outsideDst}', '/tmp/dst')"`, + `python3 -c "from os import rename as r; r('/tmp/src', '${outsideDst}')"`, + `python3 -c "from posix import replace as r; r('/tmp/src', '${outsideDst}')"`, + `python3 -c "from shutil import move as mv; mv('/tmp/src', '${outsideDst}')"`, + `python3 -c "from shutil import copy as cp; cp('/tmp/src', '${outsideDst}')"`, + `python3 -c "from os import (\n replace as r,\n)\nr('/tmp/src', '${outsideDst}')"`, + `python3 -c "import os; r = os.replace; r('/tmp/src', '/tmp/dst')"`, + `python3 -c "import os; r = os.replace; r('/tmp/src', '${outsideDst}')"`, + `python3 -c "from pathlib import Path; p = Path('/tmp/a'); f = p.write_text; f('x')"`, + `python3 -c "from pathlib import Path; p = Path('${outsideFile}'); f = p.write_text; f('x')"`, + `python3 -c "from pathlib import Path; p = Path('/tmp/src'); f = p.replace; f('${outsideDst}')"`, + ]; + + for (const convId of ["ro-s-id", "impl-s-id", "adv-s-id", "sicko-s-id"]) { + for (const cmd of deniedForAllRoles) { + assert.equal(runRolePy(convId, cmd).decision, "deny", `expected ${convId} deny for ${cmd}`); + } + } + + for (const convId of ["ro-s-id", "impl-s-id", "adv-s-id"]) { + assert.equal( + runRolePy(convId, `python3 -c "from os import replace as r; r('/tmp/src', '/tmp/dst')"`).decision, + "allow", + ); + assert.equal( + runRolePy(convId, `python3 -c "from posix import rename as rn; rn('/tmp/src', '/tmp/dst')"`).decision, + "allow", + ); + assert.equal( + runRolePy(convId, `python3 -c "from shutil import move as mv; mv('/tmp/src', '/tmp/dst')"`).decision, + "allow", + ); + assert.equal( + runRolePy(convId, `python3 -c "from shutil import copy as cp; cp('/tmp/src', '/tmp/dst')"`).decision, + "allow", + ); + } + + assert.equal( + runRolePy("ro-s-id", `python3 -c "from os import replace as r; r('/tmp/src', '${worktreeDst}')"`).decision, + "deny", + ); + for (const convId of ["impl-s-id", "adv-s-id"]) { + assert.equal( + runRolePy(convId, `python3 -c "from os import replace as r; r('/tmp/src', '${worktreeDst}')"`).decision, + "allow", + ); + } + for (const cmd of [ + `python3 -c "from os import replace as r; r('/tmp/src', '/tmp/dst')"`, + `python3 -c "from shutil import copy as cp; cp('/tmp/src', '/tmp/dst')"`, + ]) { + assert.equal(runRolePy("sicko-s-id", cmd).decision, "deny"); + } + + const legitReadOnlySnippets = [ + `python3 -c "# inspect string\ns = 'hello # world'\n# second comment\nprint(s.replace('hello', 'hi'))"`, + `python3 -c 's = "alpha beta"\nprint(s.\\\nreplace("alpha", "gamma"))'`, + `python3 -c "s = 'getattr __dict__ vars globals locals methodcaller attrgetter'\nprint(s.replace('getattr', 'safe'))"`, + `python3 -c "s = '(os.replace) and f = os.replace'\n# harmless comment mentioning getattr and __dict__\nprint((s.replace)('os.replace', 'noop'))"`, + ]; + + for (const convId of ["ro-s-id", "impl-s-id", "adv-s-id", "sicko-s-id"]) { + for (const cmd of legitReadOnlySnippets) { + assert.equal(runRolePy(convId, cmd).decision, "allow", `expected ${convId} allow for ${cmd}`); + } + } + } finally { + sb.cleanup(); + } + }); }); From edb89597fd0ed032d161d71c5381876dcecec96c Mon Sep 17 00:00:00 2001 From: Kaitian Xie Date: Sun, 15 Nov 2026 14:41:02 +0800 Subject: [PATCH 7/9] Normalize inline Python syntax, block reflection dispatch, and validate aliased FS imports and Path subclasses --- hooks/guard.mjs | 1085 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 915 insertions(+), 170 deletions(-) diff --git a/hooks/guard.mjs b/hooks/guard.mjs index 82f24f2..0821a33 100755 --- a/hooks/guard.mjs +++ b/hooks/guard.mjs @@ -2768,6 +2768,17 @@ const PYTHON_STATEMENT_KEYWORDS = new Set([ "yield", ]); +const PYTHON_REFLECTION_IDENT_RE = + /\b(?:getattr|setattr|delattr|vars|globals|locals|methodcaller|attrgetter|__dict__|__getattribute__|__getattr__|__setattr__|__delattr__|__subclasses__|__mro__|__bases__|__base__|__builtins__)\b/; + +const PYTHON_EVAL_EXEC_RE = /(?:^|[^\w.])(?:builtins\s*\.\s*)?(?:eval|exec)\b/; + +const PYTHON_UNBOUND_MUTATION_ATTR_RE = + /\.\s*(write_text|write_bytes|unlink|rmdir|mkdir|touch|chmod|lchmod|rename|replace|symlink_to|hardlink_to|link_to|remove|removedirs|makedirs|chown|truncate|renames|rmtree|move|copy|copy2|copyfile|copytree|symlink|link)\b(?!\s*\()/; + +const PYTHON_UNBOUND_OPEN_RE = + /(?:(?:^|[^\w.])=\s*(?:builtins\s*\.\s*|_?io\s*\.\s*|codecs\s*\.\s*)?open\b(?!\s*\()|\b(?:builtins|_?io|codecs)\s*\.\s*open\b(?!\s*\())/; + function findMatchingCloseForward(str, openIdx) { let depth = 0; let quote = null; @@ -2821,6 +2832,127 @@ function stripBalancedOuterParens(expr) { return cur; } +function unwrapPythonExprParensAndWalrus(rawExpr) { + let cur = stripBalancedOuterParens(rawExpr); + while (cur) { + const m = cur.match(/^[A-Za-z_][A-Za-z0-9_]*\s*:=\s*([\s\S]+)$/); + if (!m) break; + cur = stripBalancedOuterParens(m[1]); + } + return cur; +} + +function findFStringExprSpan(str, openBraceIdx) { + let parenDepth = 0; + let braceDepth = 1; + let inFormatSpec = false; + let exprEndIdx = -1; + let j = openBraceIdx + 1; + while (j < str.length) { + const ch = str[j]; + if (!inFormatSpec) { + if (/[A-Za-z_]/.test(ch)) { + const wStart = j; + while (j < str.length && /[A-Za-z0-9_]/.test(str[j])) j += 1; + const word = str.slice(wStart, j); + if (!/^[rRbBuUfFtT]{1,2}$/.test(word) || (str[j] !== "'" && str[j] !== '"')) { + continue; + } + } + if (str[j] === "'" || str[j] === '"') { + const q = + str.slice(j, j + 3) === "'''" || str.slice(j, j + 3) === '"""' + ? str.slice(j, j + 3) + : str[j]; + j += q.length; + while (j < str.length) { + if (str[j] === "\\") { + j += 2; + continue; + } + if (q.length === 3) { + if (str.slice(j, j + 3) === q) { + j += 3; + break; + } + } else if (str[j] === q) { + j += 1; + break; + } + j += 1; + } + continue; + } + if (ch === "#") { + while (j < str.length && str[j] !== "\n" && str[j] !== "\r") j += 1; + continue; + } + if (ch === "(" || ch === "[") { + parenDepth += 1; + j += 1; + continue; + } + if (ch === ")" || ch === "]") { + parenDepth = Math.max(0, parenDepth - 1); + j += 1; + continue; + } + if (ch === "{") { + braceDepth += 1; + j += 1; + continue; + } + if (ch === "}") { + braceDepth -= 1; + if (braceDepth === 0) { + return { + exprStart: openBraceIdx + 1, + exprEnd: exprEndIdx < 0 ? j : exprEndIdx, + closeBrace: j, + }; + } + j += 1; + continue; + } + if (parenDepth === 0 && braceDepth === 1) { + if (ch === ":") { + exprEndIdx = j; + inFormatSpec = true; + j += 1; + continue; + } + if (ch === "!" && /^[rsa]\s*[:}]/.test(str.slice(j + 1, j + 6))) { + exprEndIdx = j; + inFormatSpec = true; + j += 1; + continue; + } + } + j += 1; + continue; + } + if (ch === "{") { + braceDepth += 1; + j += 1; + continue; + } + if (ch === "}") { + braceDepth -= 1; + if (braceDepth === 0) { + return { + exprStart: openBraceIdx + 1, + exprEnd: exprEndIdx < 0 ? j : exprEndIdx, + closeBrace: j, + }; + } + j += 1; + continue; + } + j += 1; + } + return null; +} + function scanPythonTokensBefore(code, limitIdx) { const tokens = []; const openStack = []; @@ -2836,7 +2968,7 @@ function scanPythonTokensBefore(code, limitIdx) { while (i < end && code[i] !== "\n") i += 1; continue; } - const strPrefix = code.slice(i, Math.min(end, i + 5)).match(/^([rRbBuUfF]{0,2})('''|"""|'|"|`)/); + const strPrefix = code.slice(i, Math.min(end, i + 5)).match(/^([rRbBuUfFtT]{0,2})('''|"""|'|"|`)/); if (strPrefix) { const start = i; const q = strPrefix[2]; @@ -2890,6 +3022,400 @@ function scanPythonTokensBefore(code, limitIdx) { return tokens; } +function stripPythonCommentsAndContinuations(rawCode) { + let out = ""; + let bracketDepth = 0; + let i = 0; + while (i < rawCode.length) { + const ch = rawCode[i]; + let prefix = ""; + let strStart = -1; + let quoteIdx = -1; + if (/[A-Za-z_]/.test(ch)) { + const wStart = i; + while (i < rawCode.length && /[A-Za-z0-9_]/.test(rawCode[i])) i += 1; + const word = rawCode.slice(wStart, i); + if (/^[rRbBuUfFtT]{1,2}$/.test(word) && (rawCode[i] === "'" || rawCode[i] === '"')) { + prefix = word; + strStart = wStart; + quoteIdx = i; + } else { + out += word; + continue; + } + } else if (ch === "'" || ch === '"') { + strStart = i; + quoteIdx = i; + } + + if (quoteIdx >= 0) { + const q = + rawCode.slice(quoteIdx, quoteIdx + 3) === "'''" || + rawCode.slice(quoteIdx, quoteIdx + 3) === '"""' + ? rawCode.slice(quoteIdx, quoteIdx + 3) + : rawCode[quoteIdx]; + const isFormat = /[fFtT]/.test(prefix); + i = quoteIdx + q.length; + if (!isFormat) { + while (i < rawCode.length) { + if (rawCode[i] === "\\") { + i += 2; + continue; + } + if (q.length === 3) { + if (rawCode.slice(i, i + 3) === q) { + i += 3; + break; + } + } else if (rawCode[i] === q) { + i += 1; + break; + } + i += 1; + } + out += rawCode.slice(strStart, Math.min(i, rawCode.length)); + continue; + } + + out += prefix + q; + while (i < rawCode.length) { + if (rawCode[i] === "\\") { + out += rawCode.slice(i, Math.min(i + 2, rawCode.length)); + i += 2; + continue; + } + if (q.length === 3) { + if (rawCode.slice(i, i + 3) === q) { + out += q; + i += 3; + break; + } + } else if (rawCode[i] === q) { + out += q; + i += 1; + break; + } + if (rawCode[i] === "{") { + if (rawCode[i + 1] === "{") { + out += "{{"; + i += 2; + continue; + } + const span = findFStringExprSpan(rawCode, i); + if (span) { + const normExpr = normalizeInlinePythonCode(rawCode.slice(span.exprStart, span.exprEnd)); + const specRaw = rawCode.slice(span.exprEnd, span.closeBrace); + let normSpec = ""; + let sj = 0; + while (sj < specRaw.length) { + if (specRaw[sj] === "{" && specRaw[sj + 1] !== "{") { + const subSpan = findFStringExprSpan(specRaw, sj); + if (subSpan) { + normSpec += `{${normalizeInlinePythonCode(specRaw.slice(subSpan.exprStart, subSpan.exprEnd))}${specRaw.slice(subSpan.exprEnd, subSpan.closeBrace + 1)}`; + sj = subSpan.closeBrace + 1; + continue; + } + } + normSpec += specRaw[sj]; + sj += 1; + } + out += `{${normExpr}${normSpec}}`; + i = span.closeBrace + 1; + continue; + } + } + if (rawCode[i] === "}" && rawCode[i + 1] === "}") { + out += "}}"; + i += 2; + continue; + } + out += rawCode[i]; + i += 1; + } + continue; + } + + if (ch === "\\") { + if (rawCode[i + 1] === "\r" && rawCode[i + 2] === "\n") { + out += " "; + i += 3; + continue; + } + if (rawCode[i + 1] === "\n" || rawCode[i + 1] === "\r") { + out += " "; + i += 2; + continue; + } + } + if (ch === "#") { + out += " "; + while (i < rawCode.length && rawCode[i] !== "\n" && rawCode[i] !== "\r") i += 1; + continue; + } + if (ch === "(" || ch === "[" || ch === "{") { + bracketDepth += 1; + out += ch; + i += 1; + continue; + } + if (ch === ")" || ch === "]" || ch === "}") { + bracketDepth = Math.max(0, bracketDepth - 1); + out += ch; + i += 1; + continue; + } + if (ch === "\r" || ch === "\n") { + if (ch === "\r" && rawCode[i + 1] === "\n") i += 2; + else i += 1; + out += bracketDepth > 0 ? " " : "\n"; + continue; + } + out += ch; + i += 1; + } + return out; +} + +function unwrapParenthesizedPythonRefs(code) { + const chars = code.split(""); + const maxPasses = Math.max(1, Math.floor(chars.length / 2) + 1); + for (let pass = 0; pass < maxPasses; pass += 1) { + const cur = chars.join(""); + const tokens = scanPythonTokensBefore(cur, cur.length); + let changed = false; + for (let closeIdx = 0; closeIdx < tokens.length; closeIdx += 1) { + const closeTok = tokens[closeIdx]; + if (closeTok.kind !== "close" || closeTok.ch !== ")" || closeTok.openTokenIdx < 0) continue; + const openIdx = closeTok.openTokenIdx; + const openTok = tokens[openIdx]; + if (openTok.ch !== "(" || openIdx + 1 >= closeIdx) continue; + const prev = openIdx > 0 ? tokens[openIdx - 1] : null; + const isGroupingOpen = + prev === null || + prev.kind === "open" || + prev.kind === "other" || + (prev.kind === "ident" && PYTHON_STATEMENT_KEYWORDS.has(prev.text) && prev.text !== "import"); + if (!isGroupingOpen) continue; + + const topTokens = []; + let validPrimary = true; + let k = openIdx + 1; + while (k < closeIdx) { + const t = tokens[k]; + if (t.kind === "open") { + let matchClose = -1; + for (let m = k + 1; m < closeIdx; m += 1) { + if (tokens[m].kind === "close" && tokens[m].openTokenIdx === k) { + matchClose = m; + break; + } + } + if (matchClose < 0) { + validPrimary = false; + break; + } + topTokens.push({ kind: "group" }); + k = matchClose + 1; + continue; + } + if ( + t.kind === "ident" && + !PYTHON_STATEMENT_KEYWORDS.has(t.text) && + t.text !== "class" && + t.text !== "def" + ) { + topTokens.push(t); + k += 1; + continue; + } + if (t.kind === "string") { + if (topTokens.length > 0 && topTokens[topTokens.length - 1].kind === "string") { + validPrimary = false; + break; + } + topTokens.push(t); + k += 1; + continue; + } + if (t.kind === "dot") { + topTokens.push(t); + k += 1; + continue; + } + validPrimary = false; + break; + } + if ( + !validPrimary || + topTokens.length === 0 || + topTokens[0].kind === "dot" || + topTokens[topTokens.length - 1].kind === "dot" + ) { + continue; + } + + const endsWithAttr = + topTokens.length >= 3 && + topTokens[topTokens.length - 1].kind === "ident" && + topTokens[topTokens.length - 2].kind === "dot"; + const nextTok = closeIdx + 1 < tokens.length ? tokens[closeIdx + 1] : null; + const followedByChain = + nextTok !== null && + (nextTok.kind === "dot" || + (nextTok.kind === "open" && (nextTok.ch === "(" || nextTok.ch === "[")) || + (nextTok.kind === "close" && nextTok.ch === ")")); + if (endsWithAttr || followedByChain) { + chars[openTok.start] = " "; + chars[closeTok.start] = " "; + changed = true; + break; + } + } + if (!changed) return cur; + } + return chars.join(""); +} + +function normalizeInlinePythonCode(rawCode) { + const stripped = stripPythonCommentsAndContinuations(String(rawCode || "")); + return unwrapParenthesizedPythonRefs(stripped); +} + +function maskSlicePreservingNewlines(slice) { + let out = ""; + for (let idx = 0; idx < slice.length; idx += 1) { + out += slice[idx] === "\n" ? "\n" : " "; + } + return out; +} + +function maskPythonNonCodeStrings(code) { + let out = ""; + let i = 0; + while (i < code.length) { + const ch = code[i]; + let prefix = ""; + let quoteIdx = -1; + if (/[A-Za-z_]/.test(ch)) { + const wStart = i; + while (i < code.length && /[A-Za-z0-9_]/.test(code[i])) i += 1; + const word = code.slice(wStart, i); + if (/^[rRbBuUfFtT]{1,2}$/.test(word) && (code[i] === "'" || code[i] === '"')) { + prefix = word; + quoteIdx = i; + } else { + out += word; + continue; + } + } else if (ch === "'" || ch === '"') { + quoteIdx = i; + } + + if (quoteIdx >= 0) { + const q = + code.slice(quoteIdx, quoteIdx + 3) === "'''" || code.slice(quoteIdx, quoteIdx + 3) === '"""' + ? code.slice(quoteIdx, quoteIdx + 3) + : code[quoteIdx]; + const isFormat = /[fFtT]/.test(prefix); + out += prefix + q; + i = quoteIdx + q.length; + if (!isFormat) { + const innerStart = i; + let closed = false; + while (i < code.length) { + if (code[i] === "\\") { + if (i + 1 < code.length) { + i += 2; + } else { + i += 1; + } + continue; + } + if (q.length === 3) { + if (code.slice(i, i + 3) === q) { + out += maskSlicePreservingNewlines(code.slice(innerStart, i)) + q; + i += 3; + closed = true; + break; + } + } else if (code[i] === q) { + out += maskSlicePreservingNewlines(code.slice(innerStart, i)) + q; + i += 1; + closed = true; + break; + } + i += 1; + } + if (!closed) { + out += maskSlicePreservingNewlines(code.slice(innerStart)); + } + continue; + } + + while (i < code.length) { + if (code[i] === "\\") { + const escSlice = code.slice(i, Math.min(i + 2, code.length)); + out += maskSlicePreservingNewlines(escSlice); + i += escSlice.length; + continue; + } + if (q.length === 3) { + if (code.slice(i, i + 3) === q) { + out += q; + i += 3; + break; + } + } else if (code[i] === q) { + out += q; + i += 1; + break; + } + if (code[i] === "{") { + if (code[i + 1] === "{") { + out += " "; + i += 2; + continue; + } + const span = findFStringExprSpan(code, i); + if (span) { + const maskedExpr = maskPythonNonCodeStrings(code.slice(span.exprStart, span.exprEnd)); + const specRaw = code.slice(span.exprEnd, span.closeBrace); + let maskedSpec = ""; + let sj = 0; + while (sj < specRaw.length) { + if (specRaw[sj] === "{" && specRaw[sj + 1] !== "{") { + const subSpan = findFStringExprSpan(specRaw, sj); + if (subSpan) { + maskedSpec += `{${maskPythonNonCodeStrings(specRaw.slice(subSpan.exprStart, subSpan.exprEnd))}${maskSlicePreservingNewlines(specRaw.slice(subSpan.exprEnd, subSpan.closeBrace))}}`; + sj = subSpan.closeBrace + 1; + continue; + } + } + maskedSpec += specRaw[sj] === "\n" ? "\n" : " "; + sj += 1; + } + out += `{${maskedExpr}${maskedSpec}}`; + i = span.closeBrace + 1; + continue; + } + } + if (code[i] === "}" && code[i + 1] === "}") { + out += " "; + i += 2; + continue; + } + out += code[i] === "\n" ? "\n" : " "; + i += 1; + } + continue; + } + + out += ch; + i += 1; + } + return out; +} + function extractPythonReceiverBeforeDot(code, dotIdx) { const tokens = scanPythonTokensBefore(code, dotIdx); if (tokens.length === 0) return ""; @@ -2944,21 +3470,35 @@ function isSinglePyStringLiteralExpr(expr) { } function isPythonPathlibModuleExpr(rawExpr, symbols) { - const expr = stripBalancedOuterParens(rawExpr); + const expr = unwrapPythonExprParensAndWalrus(rawExpr); if (!expr) return false; if (symbols.pathlibModuleIdents.has(expr)) return true; + const tokens = scanPythonTokensBefore(expr, expr.length); if ( - /^(?:__import__|builtins\s*\.\s*__import__|importlib\s*\.\s*import_module|import_module)\s*\(\s*['"]pathlib['"]\s*\)$/.test( + tokens.length >= 3 && + tokens[tokens.length - 1].kind === "ident" && + tokens[tokens.length - 2].kind === "dot" + ) { + const subAttr = tokens[tokens.length - 1].text; + const base = expr.slice(0, tokens[tokens.length - 2].start); + if ((subAttr === "_local" || subAttr === "_abc") && isPythonPathlibModuleExpr(base, symbols)) { + return true; + } + } + if ( + /^(?:__import__|builtins\s*\.\s*__import__|importlib\s*\.\s*import_module|import_module)\s*\(\s*['"]pathlib(?:\.[A-Za-z0-9_]+)?['"]\s*\)$/.test( expr, ) ) { return true; } - return /^sys\s*\.\s*modules\s*(?:\[\s*['"]pathlib['"]\s*\]|\.\s*get\s*\(\s*['"]pathlib['"])/.test(expr); + return /^sys\s*\.\s*modules\s*(?:\[\s*['"]pathlib(?:\.[A-Za-z0-9_]+)?['"]\s*\]|\.\s*get\s*\(\s*['"]pathlib(?:\.[A-Za-z0-9_]+)?['"])/.test( + expr, + ); } function isPythonFsModuleExpr(rawExpr, symbols) { - const expr = stripBalancedOuterParens(rawExpr); + const expr = unwrapPythonExprParensAndWalrus(rawExpr); if (!expr) return false; if (symbols.fsModuleIdents.has(expr)) return true; if ( @@ -2974,7 +3514,7 @@ function isPythonFsModuleExpr(rawExpr, symbols) { } function isPythonPathClassExpr(rawExpr, symbols) { - const expr = stripBalancedOuterParens(rawExpr); + const expr = unwrapPythonExprParensAndWalrus(rawExpr); if (!expr) return false; if (symbols.pathClassIdents.has(expr)) return true; const tokens = scanPythonTokensBefore(expr, expr.length); @@ -2989,27 +3529,20 @@ function isPythonPathClassExpr(rawExpr, symbols) { } } if (last.kind === "close" && last.ch === ")" && last.openTokenIdx > 0) { - const callee = stripBalancedOuterParens(expr.slice(0, tokens[last.openTokenIdx].start)); + const callee = unwrapPythonExprParensAndWalrus(expr.slice(0, tokens[last.openTokenIdx].start)); if (callee === "type" || callee === "builtins.type") return true; - if (callee === "getattr") { - const args = parseCallArguments(expr, tokens[last.openTokenIdx].start); - if (args && args.length >= 2) { - const attrLit = parseStaticPyString(args[1]); - if (attrLit.ok && PYTHON_PATH_CLASS_NAMES.has(attrLit.value)) return true; - } - } } return false; } function isPythonPathCtorCallExpr(rawExpr, symbols) { - const expr = stripBalancedOuterParens(rawExpr); + const expr = unwrapPythonExprParensAndWalrus(rawExpr); if (!expr) return null; const tokens = scanPythonTokensBefore(expr, expr.length); if (tokens.length < 2) return null; const last = tokens[tokens.length - 1]; if (last.kind !== "close" || last.ch !== ")" || last.openTokenIdx <= 0) return null; - const callee = stripBalancedOuterParens(expr.slice(0, tokens[last.openTokenIdx].start)); + const callee = unwrapPythonExprParensAndWalrus(expr.slice(0, tokens[last.openTokenIdx].start)); let isPathCallee = symbols.pathClassIdents.has(callee) || PYTHON_PATH_CLASS_NAMES.has(callee); if (!isPathCallee) { const calleeTokens = scanPythonTokensBefore(callee, callee.length); @@ -3029,10 +3562,14 @@ function isPythonPathCtorCallExpr(rawExpr, symbols) { return parseCallArguments(expr, tokens[last.openTokenIdx].start); } -function collectPythonSymbolBindings(code) { +function collectPythonSymbolBindings(code, preMasked = null) { + const masked = preMasked ?? maskPythonNonCodeStrings(code); const pathClassIdents = new Set(PYTHON_PATH_CLASS_NAMES); const fsModuleIdents = new Set(PYTHON_FS_MODULE_NAMES); - const pathlibModuleIdents = new Set(["pathlib"]); + const pathlibModuleIdents = new Set(["pathlib", "pathlib._local", "pathlib._abc"]); + const fsFuncAliases = new Map(); + const openAliases = new Set(); + const fsOpenAliases = new Set(); const taintedIdents = new Set([ ...pathClassIdents, ...fsModuleIdents, @@ -3044,12 +3581,15 @@ function collectPythonSymbolBindings(code) { "ntpath", "genericpath", "io", + "_io", + "codecs", + "operator", "type", ]); const plainImportRe = /(?:^|[\n;])\s*import\s+([^\n;#]+)/g; let im; - while ((im = plainImportRe.exec(code)) !== null) { + while ((im = plainImportRe.exec(masked)) !== null) { for (const part of im[1].split(",")) { const m = part.trim().match(/^([A-Za-z_][A-Za-z0-9_.]*)(?:\s+as\s+([A-Za-z_][A-Za-z0-9_]*))?$/); if (!m) continue; @@ -3057,12 +3597,15 @@ function collectPythonSymbolBindings(code) { const bound = m[2] || mod.split(".")[0]; taintedIdents.add(bound); if (PYTHON_FS_MODULE_NAMES.has(mod)) fsModuleIdents.add(bound); - if (mod === "pathlib") pathlibModuleIdents.add(bound); + if (mod === "pathlib" || mod.startsWith("pathlib.")) { + pathlibModuleIdents.add(bound); + if (!m[2]) pathlibModuleIdents.add(mod); + } } } const fromImportRe = /\bfrom\s+([A-Za-z_][A-Za-z0-9_.]*)\s+import\s+([^\n;#]+)/g; - while ((im = fromImportRe.exec(code)) !== null) { + while ((im = fromImportRe.exec(masked)) !== null) { const mod = im[1]; const clause = stripBalancedOuterParens(im[2]); for (const part of clause.split(",")) { @@ -3071,18 +3614,51 @@ function collectPythonSymbolBindings(code) { const orig = m[1]; const bound = m[2] || orig; taintedIdents.add(bound); - if (mod === "pathlib" && PYTHON_PATH_CLASS_NAMES.has(orig)) pathClassIdents.add(bound); + if ( + (mod === "pathlib" || mod.startsWith("pathlib.") || pathlibModuleIdents.has(mod)) && + PYTHON_PATH_CLASS_NAMES.has(orig) + ) { + pathClassIdents.add(bound); + } + if (mod === "pathlib" && (orig === "_local" || orig === "_abc")) { + pathlibModuleIdents.add(bound); + } + if (PYTHON_FS_MODULE_NAMES.has(mod) && PYTHON_OS_SHUTIL_FN_NAMES.has(orig)) { + fsFuncAliases.set(bound, { fnName: orig, mod }); + } + if (PYTHON_FS_MODULE_NAMES.has(mod) && orig === "open") { + fsOpenAliases.add(bound); + } + if (["io", "_io", "builtins", "codecs"].includes(mod) && orig === "open") { + openAliases.add(bound); + } if (PYTHON_FS_MODULE_NAMES.has(orig)) fsModuleIdents.add(bound); if (orig === "pathlib") pathlibModuleIdents.add(bound); } } + const classDefs = []; + const classDefRe = /\bclass\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(/g; + let cm; + while ((cm = classDefRe.exec(masked)) !== null) { + const clsName = cm[1]; + const openParenIdx = cm.index + cm[0].length - 1; + const baseArgs = parseCallArguments(code, openParenIdx); + if (baseArgs === null) { + pathClassIdents.add(clsName); + taintedIdents.add(clsName); + } else { + classDefs.push([clsName, baseArgs]); + } + } + const pairs = []; const assignStmtRe = /(?:^|[\n;])\s*([A-Za-z_][A-Za-z0-9_]*(?:\s*,\s*[A-Za-z_][A-Za-z0-9_]*|\s*=\s*[A-Za-z_][A-Za-z0-9_]*)*)\s*=(?!=)\s*([^\n;#]+)/g; let am; - while ((am = assignStmtRe.exec(code)) !== null) { + while ((am = assignStmtRe.exec(masked)) !== null) { const lhsRaw = am[1].trim(); - const rhsRaw = am[2].trim(); + const rhsStart = am.index + am[0].length - am[2].length; + const rhsRaw = code.slice(rhsStart, rhsStart + am[2].length).trim(); if (lhsRaw.includes(",")) { const lhsNames = lhsRaw.split(",").map((s) => s.trim()); const rhsTuple = parseCallArguments(`(${stripBalancedOuterParens(rhsRaw)})`, 0); @@ -3101,20 +3677,37 @@ function collectPythonSymbolBindings(code) { } const walrusRe = /\b([A-Za-z_][A-Za-z0-9_]*)\s*:=\s*([^,)\]\n;#]+)/g; - while ((am = walrusRe.exec(code)) !== null) { - pairs.push([am[1], am[2].trim()]); + while ((am = walrusRe.exec(masked)) !== null) { + const rhsStart = am.index + am[0].length - am[2].length; + pairs.push([am[1], code.slice(rhsStart, rhsStart + am[2].length).trim()]); } const forLoopRe = /\bfor\s+([A-Za-z_][A-Za-z0-9_]*)\s+in\s+([^\n:#]+):/g; const forPairs = []; - while ((am = forLoopRe.exec(code)) !== null) { - forPairs.push([am[1], am[2].trim()]); - } - - const symbols = { pathClassIdents, fsModuleIdents, pathlibModuleIdents, taintedIdents }; - for (let pass = 0; pass < 4; pass += 1) { + while ((am = forLoopRe.exec(masked)) !== null) { + const iterStart = am.index + am[0].length - 1 - am[2].length; + forPairs.push([am[1], code.slice(iterStart, iterStart + am[2].length).trim()]); + } + + const symbols = { + pathClassIdents, + fsModuleIdents, + pathlibModuleIdents, + fsFuncAliases, + openAliases, + fsOpenAliases, + taintedIdents, + }; + const maxPasses = pairs.length + classDefs.length + forPairs.length + 8; + for (let pass = 0; pass < maxPasses; pass += 1) { const beforeSize = - pathClassIdents.size + fsModuleIdents.size + pathlibModuleIdents.size + taintedIdents.size; + pathClassIdents.size + + fsModuleIdents.size + + pathlibModuleIdents.size + + fsFuncAliases.size + + openAliases.size + + fsOpenAliases.size + + taintedIdents.size; for (const [lhs, rhs] of pairs) { if (isPythonFsModuleExpr(rhs, symbols)) { fsModuleIdents.add(lhs); @@ -3126,18 +3719,54 @@ function collectPythonSymbolBindings(code) { pathClassIdents.add(lhs); taintedIdents.add(lhs); } else { - const stripped = stripBalancedOuterParens(rhs); - if ( + const stripped = unwrapPythonExprParensAndWalrus(rhs); + const maskedStripped = maskPythonNonCodeStrings(stripped); + if (fsFuncAliases.has(stripped)) { + fsFuncAliases.set(lhs, fsFuncAliases.get(stripped)); + taintedIdents.add(lhs); + } else if (openAliases.has(stripped)) { + openAliases.add(lhs); + taintedIdents.add(lhs); + } else if (fsOpenAliases.has(stripped)) { + fsOpenAliases.add(lhs); + taintedIdents.add(lhs); + } else if ( taintedIdents.has(stripped) || isPythonPathCtorCallExpr(stripped, symbols) !== null || /\b(?:__import__|import_module|globals|locals|vars|getattr|type)\s*\(|\b(?:__class__|__base__|__bases__|__mro__|__subclasses__|__dict__)\b|sys\s*\.\s*modules/.test( - stripped, + maskedStripped, ) ) { taintedIdents.add(lhs); } } } + for (const [clsName, baseArgs] of classDefs) { + for (const rawBase of baseArgs) { + const baseExpr = unwrapPythonExprParensAndWalrus(rawBase); + if (!baseExpr) continue; + if ( + isPythonPathClassExpr(baseExpr, symbols) || + isPythonPathlibModuleExpr(baseExpr, symbols) + ) { + pathClassIdents.add(clsName); + taintedIdents.add(clsName); + break; + } + const baseTokens = scanPythonTokensBefore(baseExpr, baseExpr.length); + if ( + baseTokens.some( + (tok) => + tok.kind === "ident" && + (pathClassIdents.has(tok.text) || pathlibModuleIdents.has(tok.text)), + ) + ) { + pathClassIdents.add(clsName); + taintedIdents.add(clsName); + break; + } + } + } for (const [loopVar, iterExpr] of forPairs) { const iterTokens = scanPythonTokensBefore(iterExpr, iterExpr.length); for (const tok of iterTokens) { @@ -3155,7 +3784,13 @@ function collectPythonSymbolBindings(code) { } } const afterSize = - pathClassIdents.size + fsModuleIdents.size + pathlibModuleIdents.size + taintedIdents.size; + pathClassIdents.size + + fsModuleIdents.size + + pathlibModuleIdents.size + + fsFuncAliases.size + + openAliases.size + + fsOpenAliases.size + + taintedIdents.size; if (afterSize === beforeSize) break; } @@ -3683,37 +4318,18 @@ function splitPythonCallArgs(callArgs) { } function hasDisallowedPythonAlias(code) { - if ( - /\.\s*(write_text|write_bytes|unlink|rmdir|mkdir|touch|chmod|lchmod|rename|replace|symlink_to|hardlink_to|link_to|remove|removedirs|makedirs|chown|truncate|renames|rmtree|move|copy|copy2|copyfile|copytree|symlink|link)\b(?!\s*\()/.test( - code, - ) || - /(?:^|[^\w.])=\s*(?:builtins\s*\.\s*|io\s*\.\s*)?open\b(?!\s*\()/.test(code) - ) { - return true; - } - const importRe = /\bimport\s+(?:os|posix|shutil)\s+as\s+([A-Za-z_][A-Za-z0-9_]*)/g; + const fromImportRe = /\bfrom\s+pathlib(?:\.[A-Za-z0-9_]+)?\s+import\s+([^\n;]+)/g; let im; - while ((im = importRe.exec(code)) !== null) { - const alias = im[1].replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); - if (new RegExp(`\\b${alias}\\s*\\.\\s*${PYTHON_MUTATION_NAME_RE.source}`).test(code)) { - return true; - } - } - const fromImportRe = /\bfrom\s+(os|posix|shutil|pathlib)\s+import\s+([^\n;]+)/g; while ((im = fromImportRe.exec(code)) !== null) { - const mod = im[1]; - const clause = im[2]; - if (!/\bas\b/.test(clause)) continue; - if (mod === "pathlib") { - if (PYTHON_MUTATION_NAME_RE.test(clause)) return true; - continue; + const clause = im[1]; + if (/\bas\b/.test(clause) && PYTHON_MUTATION_NAME_RE.test(clause)) { + return true; } - if (PYTHON_MUTATION_NAME_RE.test(clause)) return true; } return false; } -function checkInlinePythonFs(code, allowPath, options = {}) { +function checkInlinePythonFs(rawCode, allowPath, options = {}) { const { allowDynamicPaths = false, roleLabel = "read-only ro-* workers", @@ -3721,11 +4337,22 @@ function checkInlinePythonFs(code, allowPath, options = {}) { registerReadOnlyMkdir = null, } = options; - if (!allowDynamicPaths && hasDisallowedPythonAlias(code)) { + const code = normalizeInlinePythonCode(rawCode); + const maskedCode = maskPythonNonCodeStrings(code); + + if (PYTHON_REFLECTION_IDENT_RE.test(maskedCode) || PYTHON_EVAL_EXEC_RE.test(maskedCode)) { + return `Dynamic Python reflection or attribute dispatch in inline Python script is blocked for ${roleLabel}.`; + } + + if (PYTHON_UNBOUND_MUTATION_ATTR_RE.test(maskedCode) || PYTHON_UNBOUND_OPEN_RE.test(maskedCode)) { + return `Aliased filesystem mutation API in inline Python script is blocked for ${roleLabel}.`; + } + + if (!allowDynamicPaths && hasDisallowedPythonAlias(maskedCode)) { return `Aliased filesystem mutation API in inline Python script is blocked for ${roleLabel}.`; } - const pySymbols = collectPythonSymbolBindings(code); + const pySymbols = collectPythonSymbolBindings(code, maskedCode); const checkPyPathArg = (argExpr, opts) => { const rawExpr = unwrapPythonPathCtor(argExpr || "", pySymbols); @@ -3752,7 +4379,7 @@ function checkInlinePythonFs(code, allowPath, options = {}) { const resolvePythonPathReceiverArg = (rawRecv) => { if (rawRecv === null) return { valid: false, found: true, expr: null }; - const recvExpr = stripBalancedOuterParens(rawRecv); + const recvExpr = unwrapPythonExprParensAndWalrus(rawRecv); const ctorArgs = isPythonPathCtorCallExpr(recvExpr, pySymbols); if (ctorArgs !== null) { if (ctorArgs.length !== 1) return { valid: false, found: true, expr: null }; @@ -3776,25 +4403,146 @@ function checkInlinePythonFs(code, allowPath, options = {}) { return { valid: true, found: false, expr: null }; }; + const validateOsShutilCall = (fnName, qualifier, callArgs) => { + const { positionals, kwargs } = splitPythonCallArgs(callArgs); + if (["copy", "copy2", "copyfile", "copytree"].includes(fnName)) { + if (!qualifier && !/\bshutil\b/.test(maskedCode)) return null; + const srcExpr = positionals[0] ?? kwargs.src ?? ""; + const dstExpr = positionals[1] ?? kwargs.dst ?? ""; + const isCopyTree = fnName === "copytree"; + const srcVal = !isCopyTree ? resolveStaticArgValue(srcExpr, code, true) : null; + const srcOkForRoArtifact = + !isCopyTree && + (allowReadOnlyArtifactCopySource + ? Boolean(srcVal && allowReadOnlyArtifactCopySource(srcVal)) + : Boolean(srcVal && /\.(?:png|jpe?g|webp)$/i.test(srcVal))); + const allowImgDir = srcOkForRoArtifact && (fnName === "copy" || fnName === "copy2"); + if ( + !dstExpr || + !checkPyPathArg(dstExpr, { + allowRootEqual: true, + allowDevNull: true, + allowArtifactDir: allowImgDir, + allowArtifactRoot: allowImgDir, + forbidReadOnlyArtifact: isCopyTree || !srcOkForRoArtifact, + }) + ) { + return `Inline Python ${fnName}() destination outside allowed roots is blocked for ${roleLabel}.`; + } + return null; + } + if (["rename", "renames", "replace", "move", "symlink", "link"].includes(fnName)) { + const srcExpr = positionals[0] ?? kwargs.src ?? ""; + const dstExpr = positionals[1] ?? kwargs.dst ?? ""; + const isSymlink = fnName === "symlink"; + const isLink = isSymlink || fnName === "link"; + const srcVal = !isLink ? resolveStaticArgValue(srcExpr, code, true) : null; + const dstVal = isSymlink ? resolveStaticArgValue(dstExpr, code, true) : null; + const symlinkBaseDir = + isSymlink && dstVal && isAbsolute(dstVal) ? dirname(dstVal) : null; + const srcOkForRoArtifact = + !isLink && + (allowReadOnlyArtifactCopySource + ? Boolean(srcVal && allowReadOnlyArtifactCopySource(srcVal)) + : Boolean(srcVal && /\.(?:png|jpe?g|webp)$/i.test(srcVal))); + const allowMoveDir = srcOkForRoArtifact && fnName === "move"; + if ( + !srcExpr || + !dstExpr || + !checkPyPathArg(srcExpr, { + allowRootEqual: false, + allowDevNull: false, + forbidReadOnlyArtifact: isLink, + disallowArtifactRoot: isLink, + customBaseDir: symlinkBaseDir, + }) || + !checkPyPathArg(dstExpr, { + allowRootEqual: fnName === "move", + allowDevNull: false, + allowArtifactDir: allowMoveDir, + allowArtifactRoot: allowMoveDir, + forbidReadOnlyArtifact: isLink || !srcOkForRoArtifact, + disallowArtifactRoot: isLink || fnName !== "move", + }) + ) { + return `Inline Python ${fnName}() outside allowed roots is blocked for ${roleLabel}.`; + } + return null; + } + const singleExpr = positionals[0] ?? kwargs.path ?? kwargs.name ?? ""; + const isMkdir = fnName === "mkdir" || fnName === "makedirs"; + const forbidRo = ["rmdir", "removedirs", "rmtree", "chmod", "lchmod", "chown"].includes(fnName); + if ( + !singleExpr || + !checkPyPathArg(singleExpr, { + allowRootEqual: isMkdir, + allowDevNull: false, + allowArtifactDir: isMkdir, + requireArtifactDir: isMkdir, + allowArtifactRoot: isMkdir, + forbidReadOnlyArtifact: forbidRo, + }) + ) { + return `Inline Python ${fnName}() outside allowed roots is blocked for ${roleLabel}.`; + } + if (isMkdir && registerReadOnlyMkdir) { + const mkdirVal = + resolveStaticArgValue(singleExpr, code, true) ?? + resolveStaticJoinOrTemplate(unwrapPythonPathCtor(singleExpr, pySymbols), code, true); + if (mkdirVal) registerReadOnlyMkdir(mkdirVal); + } + return null; + }; + + const validatePyOpenArgs = (openArgs) => { + const { positionals, kwargs } = splitPythonCallArgs(openArgs); + const modeExpr = positionals[1] ?? kwargs.mode ?? null; + if (modeExpr === null) return null; + const modeLit = parseStaticPyString(modeExpr); + if (modeLit.ok && /^[rbtU]+$/.test(modeLit.value) && modeLit.value.includes("r")) { + return null; + } + const pathExpr = positionals[0] ?? kwargs.file ?? ""; + if (!checkPyPathArg(pathExpr, { allowRootEqual: false, allowDevNull: true })) { + return `Inline Python open() for write outside allowed roots is blocked for ${roleLabel}.`; + } + return null; + }; + if (registerReadOnlyMkdir) { const preMkdirRe = /(?:(?:os|posix)\s*\.\s*|\b)(?:mkdir|makedirs)\s*\(/g; let pm; - while ((pm = preMkdirRe.exec(code)) !== null) { + while ((pm = preMkdirRe.exec(maskedCode)) !== null) { const mArgs = parseCallArguments(code, pm.index + pm[0].length - 1); if (!mArgs) continue; const { positionals: pPos, kwargs: pKw } = splitPythonCallArgs(mArgs); const dExpr = pPos[0] ?? pKw.path ?? pKw.name ?? ""; const dVal = resolveStaticArgValue(dExpr, code, true) ?? - resolveStaticJoinOrTemplate(unwrapPythonPathCtor(dExpr), code, true); + resolveStaticJoinOrTemplate(unwrapPythonPathCtor(dExpr, pySymbols), code, true); if (dVal) registerReadOnlyMkdir(dVal); } + for (const [alias, entry] of pySymbols.fsFuncAliases.entries()) { + if (entry.fnName !== "mkdir" && entry.fnName !== "makedirs") continue; + const aliasEsc = alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + const aliasCallRe = new RegExp(`(?:^|[^\\w.])${aliasEsc}\\s*\\(`, "g"); + while ((pm = aliasCallRe.exec(maskedCode)) !== null) { + const mArgs = parseCallArguments(code, pm.index + pm[0].length - 1); + if (!mArgs) continue; + const { positionals: pPos, kwargs: pKw } = splitPythonCallArgs(mArgs); + const dExpr = pPos[0] ?? pKw.path ?? pKw.name ?? ""; + const dVal = + resolveStaticArgValue(dExpr, code, true) ?? + resolveStaticJoinOrTemplate(unwrapPythonPathCtor(dExpr, pySymbols), code, true); + if (dVal) registerReadOnlyMkdir(dVal); + } + } } const pathMethodRe = /\.\s*(write_text|write_bytes|unlink|rmdir|mkdir|touch|chmod|lchmod|rename|replace|symlink_to|hardlink_to|link_to|open)\s*\(/g; let match; - while ((match = pathMethodRe.exec(code)) !== null) { + while ((match = pathMethodRe.exec(maskedCode)) !== null) { const method = match[1]; const openParenIdx = match.index + match[0].length - 1; const methodArgs = parseCallArguments(code, openParenIdx); @@ -3812,6 +4560,25 @@ function checkInlinePythonFs(code, allowPath, options = {}) { continue; } if (method === "open") { + const recvTrimmed = unwrapPythonExprParensAndWalrus(rawRecv); + if ( + recvTrimmed === "io" || + recvTrimmed === "_io" || + recvTrimmed === "builtins" || + recvTrimmed === "codecs" + ) { + const openDeny = validatePyOpenArgs(methodArgs); + if (openDeny) return openDeny; + continue; + } + if (isPythonFsModuleExpr(rawRecv, pySymbols)) { + const { positionals, kwargs } = splitPythonCallArgs(methodArgs); + const pathExpr = positionals[0] ?? kwargs.path ?? ""; + if (!pathExpr || !checkPyPathArg(pathExpr, { allowRootEqual: false, allowDevNull: true })) { + return `Inline Python os.open() outside allowed roots is blocked for ${roleLabel}.`; + } + continue; + } const { positionals, kwargs } = splitPythonCallArgs(methodArgs); const modeExpr = positionals[0] ?? kwargs.mode ?? null; if (modeExpr === null) continue; @@ -3856,7 +4623,7 @@ function checkInlinePythonFs(code, allowPath, options = {}) { if (isMkdir && registerReadOnlyMkdir) { const mkdirVal = resolveStaticArgValue(recv.expr, code, true) ?? - resolveStaticJoinOrTemplate(unwrapPythonPathCtor(recv.expr), code, true); + resolveStaticJoinOrTemplate(unwrapPythonPathCtor(recv.expr, pySymbols), code, true); if (mkdirVal) registerReadOnlyMkdir(mkdirVal); } } else if (!allowDynamicPaths) { @@ -3924,34 +4691,25 @@ function checkInlinePythonFs(code, allowPath, options = {}) { } } - const openRe = /(?:^|[^\w.])(?:io\s*\.\s*|builtins\s*\.\s*)?open\s*\(/g; - while ((match = openRe.exec(code)) !== null) { + const openRe = /(?:^|[^\w.])(?:_?io\s*\.\s*|builtins\s*\.\s*|codecs\s*\.\s*)?open\s*\(/g; + while ((match = openRe.exec(maskedCode)) !== null) { const openParenIdx = match.index + match[0].length - 1; const openArgs = parseCallArguments(code, openParenIdx); if (!openArgs) { return `Unparseable open() call in inline Python script is blocked for ${roleLabel}.`; } - const { positionals, kwargs } = splitPythonCallArgs(openArgs); - const modeExpr = positionals[1] ?? kwargs.mode ?? null; - if (modeExpr === null) continue; - const modeLit = parseStaticPyString(modeExpr); - if (modeLit.ok && /^[rbtU]+$/.test(modeLit.value) && modeLit.value.includes("r")) { - continue; - } - const pathExpr = positionals[0] ?? kwargs.file ?? ""; - if (!checkPyPathArg(pathExpr, { allowRootEqual: false, allowDevNull: true })) { - return `Inline Python open() for write outside allowed roots is blocked for ${roleLabel}.`; - } + const openDeny = validatePyOpenArgs(openArgs); + if (openDeny) return openDeny; } - const hasFsImport = /\b(?:os|posix|shutil)\b/.test(code); + const hasFsImport = /\b(?:os|posix|shutil)\b/.test(maskedCode); const osShutilRe = /(?:(os|posix|shutil)\s*\.\s*|\b)(remove|unlink|rmdir|removedirs|mkdir|makedirs|chmod|lchmod|chown|truncate|rename|renames|replace|rmtree|move|copy|copy2|copyfile|copytree|symlink|link)\s*\(/g; - while ((match = osShutilRe.exec(code)) !== null) { + while ((match = osShutilRe.exec(maskedCode)) !== null) { let qualifier = match[1] || ""; const fnName = match[2]; if (!qualifier) { - const dotMatch = code.slice(0, match.index).match(/\.\s*$/); + const dotMatch = maskedCode.slice(0, match.index).match(/\.\s*$/); if (dotMatch) { const memberRecv = extractPythonReceiverBeforeDot(code, match.index - dotMatch[0].length); if (!isPythonFsModuleExpr(memberRecv, pySymbols)) { @@ -3967,97 +4725,84 @@ function checkInlinePythonFs(code, allowPath, options = {}) { if (!callArgs) { return `Unparseable ${fnName}() call in inline Python script is blocked for ${roleLabel}.`; } - const { positionals, kwargs } = splitPythonCallArgs(callArgs); - if (["copy", "copy2", "copyfile", "copytree"].includes(fnName)) { - if (!qualifier && !/\bshutil\b/.test(code)) continue; - const srcExpr = positionals[0] ?? kwargs.src ?? ""; - const dstExpr = positionals[1] ?? kwargs.dst ?? ""; - const isCopyTree = fnName === "copytree"; - const srcVal = !isCopyTree ? resolveStaticArgValue(srcExpr, code, true) : null; - const srcOkForRoArtifact = - !isCopyTree && - (allowReadOnlyArtifactCopySource - ? Boolean(srcVal && allowReadOnlyArtifactCopySource(srcVal)) - : Boolean(srcVal && /\.(?:png|jpe?g|webp)$/i.test(srcVal))); - const allowImgDir = srcOkForRoArtifact && (fnName === "copy" || fnName === "copy2"); - if ( - !dstExpr || - !checkPyPathArg(dstExpr, { - allowRootEqual: true, - allowDevNull: true, - allowArtifactDir: allowImgDir, - allowArtifactRoot: allowImgDir, - forbidReadOnlyArtifact: isCopyTree || !srcOkForRoArtifact, - }) - ) { - return `Inline Python ${fnName}() destination outside allowed roots is blocked for ${roleLabel}.`; - } - continue; - } - if (["rename", "renames", "replace", "move", "symlink", "link"].includes(fnName)) { - const srcExpr = positionals[0] ?? kwargs.src ?? ""; - const dstExpr = positionals[1] ?? kwargs.dst ?? ""; - const isSymlink = fnName === "symlink"; - const isLink = isSymlink || fnName === "link"; - const srcVal = !isLink ? resolveStaticArgValue(srcExpr, code, true) : null; - const dstVal = isSymlink ? resolveStaticArgValue(dstExpr, code, true) : null; - const symlinkBaseDir = - isSymlink && dstVal && isAbsolute(dstVal) ? dirname(dstVal) : null; - const srcOkForRoArtifact = - !isLink && - (allowReadOnlyArtifactCopySource - ? Boolean(srcVal && allowReadOnlyArtifactCopySource(srcVal)) - : Boolean(srcVal && /\.(?:png|jpe?g|webp)$/i.test(srcVal))); - const allowMoveDir = srcOkForRoArtifact && fnName === "move"; - if ( - !srcExpr || - !dstExpr || - !checkPyPathArg(srcExpr, { - allowRootEqual: false, - allowDevNull: false, - forbidReadOnlyArtifact: isLink, - disallowArtifactRoot: isLink, - customBaseDir: symlinkBaseDir, - }) || - !checkPyPathArg(dstExpr, { - allowRootEqual: fnName === "move", - allowDevNull: false, - allowArtifactDir: allowMoveDir, - allowArtifactRoot: allowMoveDir, - forbidReadOnlyArtifact: isLink || !srcOkForRoArtifact, - disallowArtifactRoot: isLink || fnName !== "move", - }) - ) { - return `Inline Python ${fnName}() outside allowed roots is blocked for ${roleLabel}.`; + const callDeny = validateOsShutilCall(fnName, qualifier, callArgs); + if (callDeny) return callDeny; + } + + if ( + pySymbols.fsFuncAliases.size > 0 || + pySymbols.openAliases.size > 0 || + pySymbols.fsOpenAliases.size > 0 + ) { + const bodyMasked = maskedCode + .replace(/\bfrom\s+[A-Za-z_][A-Za-z0-9_.]*\s+import\s+[^\n;]+/g, (s) => " ".repeat(s.length)) + .replace(/(?:^|[\n;])\s*import\s+[^\n;]+/g, (s) => + s.replace(/[^\n]/g, " "), + ); + + const checkAliasUsages = (alias, validateCallFn, fnLabel) => { + const aliasEsc = alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + const refRe = new RegExp(`(?:^|[^\\w.])(${aliasEsc})\\b`, "g"); + let rm; + while ((rm = refRe.exec(bodyMasked)) !== null) { + const aliasEnd = rm.index + rm[0].length; + const aliasStart = aliasEnd - rm[1].length; + const beforeTrimmed = bodyMasked.slice(0, aliasStart).trimEnd(); + if (beforeTrimmed.endsWith(".")) continue; + const afterAlias = bodyMasked.slice(aliasEnd); + const callMatch = afterAlias.match(/^\s*\(/); + if (callMatch) { + const openParenIdx = aliasEnd + callMatch[0].length - 1; + const callArgs = parseCallArguments(code, openParenIdx); + if (!callArgs) { + return `Unparseable ${fnLabel}() call in inline Python script is blocked for ${roleLabel}.`; + } + const deny = validateCallFn(callArgs); + if (deny) return deny; + continue; + } + const isSimpleAssignRhs = + /(?:^|[\n;])\s*[A-Za-z_][A-Za-z0-9_]*\s*=$/.test(beforeTrimmed) && + /^\s*(?:$|[\n;])/.test(afterAlias); + const isSimpleAssignLhs = + /(?:^|[\n;])$/.test(beforeTrimmed) && /^\s*=(?!=)/.test(afterAlias); + if (isSimpleAssignRhs || isSimpleAssignLhs) continue; + return `Aliased filesystem mutation API in inline Python script is blocked for ${roleLabel}.`; } - continue; - } - const singleExpr = positionals[0] ?? kwargs.path ?? kwargs.name ?? ""; - const isMkdir = fnName === "mkdir" || fnName === "makedirs"; - const forbidRo = ["rmdir", "removedirs", "rmtree", "chmod", "lchmod", "chown"].includes(fnName); - if ( - !singleExpr || - !checkPyPathArg(singleExpr, { - allowRootEqual: isMkdir, - allowDevNull: false, - allowArtifactDir: isMkdir, - requireArtifactDir: isMkdir, - allowArtifactRoot: isMkdir, - forbidReadOnlyArtifact: forbidRo, - }) - ) { - return `Inline Python ${fnName}() outside allowed roots is blocked for ${roleLabel}.`; - } - if (isMkdir && registerReadOnlyMkdir) { - const mkdirVal = - resolveStaticArgValue(singleExpr, code, true) ?? - resolveStaticJoinOrTemplate(unwrapPythonPathCtor(singleExpr), code, true); - if (mkdirVal) registerReadOnlyMkdir(mkdirVal); + return null; + }; + + for (const [alias, entry] of pySymbols.fsFuncAliases.entries()) { + const deny = checkAliasUsages( + alias, + (callArgs) => validateOsShutilCall(entry.fnName, entry.mod, callArgs), + entry.fnName, + ); + if (deny) return deny; + } + for (const alias of pySymbols.openAliases) { + const deny = checkAliasUsages(alias, validatePyOpenArgs, "open"); + if (deny) return deny; + } + for (const alias of pySymbols.fsOpenAliases) { + const deny = checkAliasUsages( + alias, + (callArgs) => { + const { positionals, kwargs } = splitPythonCallArgs(callArgs); + const pathExpr = positionals[0] ?? kwargs.path ?? ""; + if (!pathExpr || !checkPyPathArg(pathExpr, { allowRootEqual: false, allowDevNull: true })) { + return `Inline Python os.open() outside allowed roots is blocked for ${roleLabel}.`; + } + return null; + }, + "open", + ); + if (deny) return deny; } } const screenshotRe = /\.\s*screenshot\s*\(/g; - while ((match = screenshotRe.exec(code)) !== null) { + while ((match = screenshotRe.exec(maskedCode)) !== null) { const openParenIdx = match.index + match[0].length - 1; const callArgs = parseCallArguments(code, openParenIdx); if (!callArgs) { From 4e24d736fee6546f6f312675ec13464a60a92173 Mon Sep 17 00:00:00 2001 From: Kaitian Xie Date: Sun, 15 Nov 2026 14:58:23 +0800 Subject: [PATCH 8/9] Add regression tests for f-string and t-string interpolations and wrapped Path or FS receivers --- hooks/guard.test.mjs | 93 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/hooks/guard.test.mjs b/hooks/guard.test.mjs index 470b1a1..ebcc172 100644 --- a/hooks/guard.test.mjs +++ b/hooks/guard.test.mjs @@ -3265,4 +3265,97 @@ if (process.env.MOCK_CLI_MODE === "hang") { setTimeout(() => {}, 10000); } else sb.cleanup(); } }); + + test("blocks f-string and t-string interpolation escapes and container, conditional, boolean, or lambda wrapped Path and FS receivers across worker roles", () => { + const sb = makeSandbox(); + try { + writeSwarmMembers(sb.appDataDir, "coord-py-fstr", { + coordinator: { conversation_id: "coord-py-fstr", role: "coordinator" }, + "ro-f": { conversation_id: "ro-f-id", role: "worker" }, + "impl-f": { conversation_id: "impl-f-id", role: "worker" }, + "adv-f": { conversation_id: "adv-f-id", role: "worker" }, + "sicko-f": { conversation_id: "sicko-f-id", role: "worker" }, + }); + + const runRolePy = (convId, CommandLine) => + runGuard( + { + hookEventName: "PreToolUse", + conversationId: convId, + rootConversationId: "coord-py-fstr", + cwd: sb.worktree, + toolCall: { id: "py-fstr", name: "run_command", args: { CommandLine } }, + }, + { PSTACK_APPDATA_DIR: sb.appDataDir, TMPDIR: sb.customTmpDir }, + ); + + const outsideDst = join(sb.outsideDir, "dst"); + const outsideFile = join(sb.outsideDir, "f"); + const worktreeFile = join(sb.worktree, "ok.txt"); + + const deniedForAllRoles = [ + `python3 -c 'from pathlib import Path; f"{Path.replace(Path("/tmp/src"), "${outsideDst}")}"'`, + `python3 -c 'from pathlib import Path; t"{Path.replace(Path("/tmp/src"), "${outsideDst}")}"'`, + `python3 -c 'from pathlib import Path; f"{(Path.#c\nreplace)(Path("/tmp/src"), "${outsideDst}")}"'`, + `python3 -c 'from pathlib import Path; f"""{(Path.#c\nreplace)(Path("/tmp/src"), "${outsideDst}")}"""'`, + `python3 -c 'from pathlib import Path; f"""{Path("${outsideFile}").write_text("x")}"""'`, + `python3 -c 'from pathlib import Path; f"{Path("${outsideFile}").write_text("x")}"'`, + `python3 -c 'from pathlib import Path; f"outer {f"{Path.replace(Path("/tmp/src"), "${outsideDst}")}"} end"'`, + `python3 -c 'from pathlib import Path; f"outer {f"{Path("${outsideFile}").write_text("x")}"} end"'`, + `python3 -c 'import os; f"{[os][0].replace("/tmp/src", "${outsideDst}")}"'`, + `python3 -c 'import os; f"{[os][0].remove("${outsideFile}")}"'`, + `python3 -c "from pathlib import Path; [Path][0].write_text(Path('${outsideFile}'), 'x')"`, + `python3 -c "from pathlib import Path; [Path][0].replace(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "import os; [os][0].replace('/tmp/src', '${outsideDst}')"`, + `python3 -c "import os; [os][0].remove('${outsideFile}')"`, + `python3 -c "import shutil; [shutil][0].rmtree('${sb.outsideDir}')"`, + `python3 -c "from pathlib import Path; (Path if 1 else Path).write_text(Path('${outsideFile}'), 'x')"`, + `python3 -c "from pathlib import Path; (Path if 1 else Path).replace(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "from pathlib import Path; (None or Path).write_text(Path('${outsideFile}'), 'x')"`, + `python3 -c "import os; (None or os).replace('/tmp/src', '${outsideDst}')"`, + `python3 -c "import os; (None or os).remove('${outsideFile}')"`, + `python3 -c "from pathlib import Path; (lambda: Path)().write_text(Path('${outsideFile}'), 'x')"`, + `python3 -c "from pathlib import Path; (lambda: Path)().replace(Path('/tmp/src'), '${outsideDst}')"`, + `python3 -c "import os; (lambda: os)().replace('/tmp/src', '${outsideDst}')"`, + `python3 -c "import os; (lambda: os)().remove('${outsideFile}')"`, + `python3 -c "from pathlib import Path\ndef g():\n return Path\ng().write_text(Path('${outsideFile}'), 'x')"`, + `python3 -c "from pathlib import Path\ndef g():\n return Path\np = Path('${outsideFile}')\ng().write_text(p, 'x')"`, + ]; + + for (const convId of ["ro-f-id", "impl-f-id", "adv-f-id", "sicko-f-id"]) { + for (const cmd of deniedForAllRoles) { + assert.equal(runRolePy(convId, cmd).decision, "deny", `expected ${convId} deny for ${cmd}`); + } + } + + const legitFStringSnippets = [ + `python3 -c "name = 'world'; print(f'hi {name}'.replace('hi', 'hello'))"`, + `python3 -c "s = 'alpha'; print(f'{s.replace(\"a\", \"b\")}')"`, + `python3 -c 's = "alpha"; print(f"outer {f"{s.replace("a", "b")}"} end")'`, + `python3 -c "items = ['a', 'b']; print(','.join(items).replace(',', ';'))"`, + ]; + + for (const convId of ["ro-f-id", "impl-f-id", "adv-f-id", "sicko-f-id"]) { + for (const cmd of legitFStringSnippets) { + assert.equal(runRolePy(convId, cmd).decision, "allow", `expected ${convId} allow for ${cmd}`); + } + } + + for (const convId of ["impl-f-id", "adv-f-id"]) { + assert.equal( + runRolePy( + convId, + `python3 -c "import os; from pathlib import Path; Path(os.path.join('${sb.worktree}', 'ok.txt')).write_text('ok')"`, + ).decision, + "allow", + ); + assert.equal( + runRolePy(convId, `python3 -c "from pathlib import Path; p = Path('${worktreeFile}'); p.write_text('ok')"`).decision, + "allow", + ); + } + } finally { + sb.cleanup(); + } + }); }); From e30b191f6756d77ee2d6c3fb4a9d3919eabfe223 Mon Sep 17 00:00:00 2001 From: Kaitian Xie Date: Sun, 15 Nov 2026 15:08:15 +0800 Subject: [PATCH 9/9] Tokenize f-string and t-string interpolations and block wrapped Path and FS receivers --- hooks/guard.mjs | 323 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 295 insertions(+), 28 deletions(-) diff --git a/hooks/guard.mjs b/hooks/guard.mjs index 0821a33..0d71af4 100755 --- a/hooks/guard.mjs +++ b/hooks/guard.mjs @@ -2851,6 +2851,7 @@ function findFStringExprSpan(str, openBraceIdx) { while (j < str.length) { const ch = str[j]; if (!inFormatSpec) { + let nestedPrefix = ""; if (/[A-Za-z_]/.test(ch)) { const wStart = j; while (j < str.length && /[A-Za-z0-9_]/.test(str[j])) j += 1; @@ -2858,12 +2859,14 @@ function findFStringExprSpan(str, openBraceIdx) { if (!/^[rRbBuUfFtT]{1,2}$/.test(word) || (str[j] !== "'" && str[j] !== '"')) { continue; } + nestedPrefix = word; } if (str[j] === "'" || str[j] === '"') { const q = str.slice(j, j + 3) === "'''" || str.slice(j, j + 3) === '"""' ? str.slice(j, j + 3) : str[j]; + const nestedIsFormat = /[fFtT]/.test(nestedPrefix); j += q.length; while (j < str.length) { if (str[j] === "\\") { @@ -2879,6 +2882,17 @@ function findFStringExprSpan(str, openBraceIdx) { j += 1; break; } + if (nestedIsFormat && str[j] === "{") { + if (str[j + 1] === "{") { + j += 2; + continue; + } + const innerSpan = findFStringExprSpan(str, j); + if (innerSpan) { + j = innerSpan.closeBrace + 1; + continue; + } + } j += 1; } continue; @@ -2953,10 +2967,8 @@ function findFStringExprSpan(str, openBraceIdx) { return null; } -function scanPythonTokensBefore(code, limitIdx) { - const tokens = []; - const openStack = []; - let i = 0; +function scanPythonTokensRange(code, startIdx, limitIdx, tokens, openStack) { + let i = startIdx; const end = Math.min(limitIdx, code.length); while (i < end) { const ch = code[i]; @@ -2968,36 +2980,146 @@ function scanPythonTokensBefore(code, limitIdx) { while (i < end && code[i] !== "\n") i += 1; continue; } - const strPrefix = code.slice(i, Math.min(end, i + 5)).match(/^([rRbBuUfFtT]{0,2})('''|"""|'|"|`)/); - if (strPrefix) { - const start = i; - const q = strPrefix[2]; - i += strPrefix[0].length; - while (i < end) { - if (code[i] === "\\") { - i += 2; + let prefix = ""; + let strStart = -1; + let quoteIdx = -1; + if (/[A-Za-z_]/.test(ch)) { + const wStart = i; + while (i < end && /[A-Za-z0-9_]/.test(code[i])) i += 1; + const word = code.slice(wStart, i); + if ( + i < end && + /^[rRbBuUfFtT]{1,2}$/.test(word) && + (code[i] === "'" || code[i] === '"' || code[i] === "`") + ) { + prefix = word; + strStart = wStart; + quoteIdx = i; + } else { + tokens.push({ kind: "ident", start: wStart, end: i, text: word }); + continue; + } + } else if (ch === "'" || ch === '"' || ch === "`") { + strStart = i; + quoteIdx = i; + } + + if (quoteIdx >= 0) { + const q = + quoteIdx + 3 <= code.length && + (code.slice(quoteIdx, quoteIdx + 3) === "'''" || + code.slice(quoteIdx, quoteIdx + 3) === '"""') + ? code.slice(quoteIdx, quoteIdx + 3) + : code[quoteIdx]; + const isFormat = /[fFtT]/.test(prefix); + if (!isFormat) { + i = quoteIdx + q.length; + let closed = false; + while (i < end) { + if (code[i] === "\\") { + i += 2; + continue; + } + if (q.length === 3) { + if (i + 3 <= end && code.slice(i, i + 3) === q) { + i += 3; + closed = true; + break; + } + } else if (code[i] === q) { + i += 1; + closed = true; + break; + } + i += 1; + } + tokens.push({ kind: "string", start: strStart, end: Math.min(i, end), closed, isFormat: false }); + continue; + } + + let j = quoteIdx + q.length; + let fullStrEnd = -1; + const interpSpans = []; + while (j < code.length) { + if (code[j] === "\\") { + j += 2; continue; } if (q.length === 3) { - if (code.slice(i, i + 3) === q) { - i += 3; + if (code.slice(j, j + 3) === q) { + fullStrEnd = j + 3; break; } - } else if (code[i] === q) { - i += 1; + } else if (code[j] === q) { + fullStrEnd = j + 1; break; } - i += 1; + if (code[j] === "{") { + if (code[j + 1] === "{") { + j += 2; + continue; + } + const span = findFStringExprSpan(code, j); + if (span) { + interpSpans.push({ openBrace: j, exprStart: span.exprStart, exprEnd: span.exprEnd, closeBrace: span.closeBrace }); + let sj = span.exprEnd; + while (sj < span.closeBrace) { + if (code[sj] === "{" && code[sj + 1] !== "{") { + const subSpan = findFStringExprSpan(code, sj); + if (subSpan) { + interpSpans.push({ + openBrace: sj, + exprStart: subSpan.exprStart, + exprEnd: subSpan.exprEnd, + closeBrace: subSpan.closeBrace, + }); + sj = subSpan.closeBrace + 1; + continue; + } + } + sj += 1; + } + j = span.closeBrace + 1; + continue; + } + interpSpans.push({ openBrace: j, exprStart: j + 1, exprEnd: code.length, closeBrace: code.length }); + break; + } + if (code[j] === "}" && code[j + 1] === "}") { + j += 2; + continue; + } + j += 1; } - tokens.push({ kind: "string", start, end: Math.min(i, end) }); - continue; - } - if (/[A-Za-z_]/.test(ch)) { - const start = i; - while (i < end && /[A-Za-z0-9_]/.test(code[i])) i += 1; - tokens.push({ kind: "ident", start, end: i, text: code.slice(start, i) }); + + if (fullStrEnd >= 0 && fullStrEnd <= end) { + tokens.push({ kind: "string", start: strStart, end: fullStrEnd, closed: true, isFormat: true }); + i = fullStrEnd; + continue; + } + + let activeSpan = null; + for (const sp of interpSpans) { + if (sp.openBrace < end && end <= sp.closeBrace) { + if (!activeSpan || sp.openBrace > activeSpan.openBrace) { + activeSpan = sp; + } + } + } + if (activeSpan && end <= activeSpan.exprEnd) { + const openIdx = tokens.length; + tokens.push({ kind: "open", start: activeSpan.openBrace, end: activeSpan.openBrace + 1, ch: "{" }); + openStack.push(openIdx); + scanPythonTokensRange(code, activeSpan.exprStart, end, tokens, openStack); + i = end; + continue; + } + + tokens.push({ kind: "string", start: strStart, end, closed: false, isFormat: true }); + i = end; continue; } + if (ch === "(" || ch === "[" || ch === "{") { const idx = tokens.length; tokens.push({ kind: "open", start: i, end: i + 1, ch }); @@ -3019,6 +3141,12 @@ function scanPythonTokensBefore(code, limitIdx) { tokens.push({ kind: "other", start: i, end: i + 1, ch }); i += 1; } +} + +function scanPythonTokensBefore(code, limitIdx) { + const tokens = []; + const openStack = []; + scanPythonTokensRange(code, 0, limitIdx, tokens, openStack); return tokens; } @@ -3398,6 +3526,9 @@ function maskPythonNonCodeStrings(code) { i = span.closeBrace + 1; continue; } + out += code.slice(i); + i = code.length; + break; } if (code[i] === "}" && code[i + 1] === "}") { out += " "; @@ -3466,7 +3597,7 @@ function isSinglePyStringLiteralExpr(expr) { const trimmed = stripBalancedOuterParens(expr); if (!trimmed) return false; const tokens = scanPythonTokensBefore(trimmed, trimmed.length); - return tokens.length === 1 && tokens[0].kind === "string"; + return tokens.length === 1 && tokens[0].kind === "string" && tokens[0].closed === true; } function isPythonPathlibModuleExpr(rawExpr, symbols) { @@ -3513,6 +3644,46 @@ function isPythonFsModuleExpr(rawExpr, symbols) { ); } +function receiverReferencesFsModule(rawExpr, symbols) { + const expr = unwrapPythonExprParensAndWalrus(rawExpr); + if (!expr) return false; + if (isPythonFsModuleExpr(expr, symbols)) return true; + if ( + /\b(?:__import__|import_module)\s*\(\s*['"](?:os|posix|shutil)['"]\s*\)|sys\s*\.\s*modules\s*(?:\[\s*['"](?:os|posix|shutil)['"]\s*\]|\.\s*get\s*\(\s*['"](?:os|posix|shutil)['"])/.test( + expr, + ) + ) { + return true; + } + const tokens = scanPythonTokensBefore(expr, expr.length); + for (let idx = 0; idx < tokens.length; idx += 1) { + const tok = tokens[idx]; + if (tok.kind !== "ident") continue; + if (symbols.fsModuleReturningFuncs && symbols.fsModuleReturningFuncs.has(tok.text)) return true; + if (symbols.fsModuleIdents.has(tok.text)) { + const t1 = idx + 1 < tokens.length ? tokens[idx + 1] : null; + const t2 = idx + 2 < tokens.length ? tokens[idx + 2] : null; + if ( + t1 && + t1.kind === "dot" && + t2 && + t2.kind === "ident" && + (t2.text === "path" || + t2.text === "environ" || + t2.text === "sep" || + t2.text === "linesep" || + t2.text === "devnull" || + t2.text === "getpid" || + t2.text === "getcwd") + ) { + continue; + } + return true; + } + } + return false; +} + function isPythonPathClassExpr(rawExpr, symbols) { const expr = unwrapPythonExprParensAndWalrus(rawExpr); if (!expr) return false; @@ -3531,6 +3702,27 @@ function isPythonPathClassExpr(rawExpr, symbols) { if (last.kind === "close" && last.ch === ")" && last.openTokenIdx > 0) { const callee = unwrapPythonExprParensAndWalrus(expr.slice(0, tokens[last.openTokenIdx].start)); if (callee === "type" || callee === "builtins.type") return true; + if (symbols.pathClassReturningFuncs && symbols.pathClassReturningFuncs.has(callee)) return true; + } + return false; +} + +function receiverReferencesUnboundPathClass(rawExpr, symbols) { + const expr = unwrapPythonExprParensAndWalrus(rawExpr); + if (!expr) return false; + if (isPythonPathClassExpr(expr, symbols)) return true; + const tokens = scanPythonTokensBefore(expr, expr.length); + for (let idx = 0; idx < tokens.length; idx += 1) { + const tok = tokens[idx]; + if (tok.kind !== "ident") continue; + if (symbols.pathClassReturningFuncs && symbols.pathClassReturningFuncs.has(tok.text)) return true; + if (tok.text === "__class__" || tok.text === "type") return true; + if (symbols.pathClassIdents.has(tok.text)) { + const nextTok = idx + 1 < tokens.length ? tokens[idx + 1] : null; + if (!nextTok || nextTok.kind !== "open" || nextTok.ch !== "(") { + return true; + } + } } return false; } @@ -3565,6 +3757,9 @@ function isPythonPathCtorCallExpr(rawExpr, symbols) { function collectPythonSymbolBindings(code, preMasked = null) { const masked = preMasked ?? maskPythonNonCodeStrings(code); const pathClassIdents = new Set(PYTHON_PATH_CLASS_NAMES); + const pathInstanceIdents = new Set(); + const pathClassReturningFuncs = new Set(); + const fsModuleReturningFuncs = new Set(); const fsModuleIdents = new Set(PYTHON_FS_MODULE_NAMES); const pathlibModuleIdents = new Set(["pathlib", "pathlib._local", "pathlib._abc"]); const fsFuncAliases = new Map(); @@ -3652,6 +3847,28 @@ function collectPythonSymbolBindings(code, preMasked = null) { } } + const defHeaders = []; + const defRe = /\bdef\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(/g; + let dm; + while ((dm = defRe.exec(masked)) !== null) { + defHeaders.push({ name: dm[1], index: dm.index }); + } + const defReturns = []; + if (defHeaders.length > 0) { + const retRe = /\breturn\s+([^\n;#]+)/g; + let rm; + while ((rm = retRe.exec(masked)) !== null) { + let owner = null; + for (const dh of defHeaders) { + if (dh.index < rm.index) owner = dh.name; + } + if (owner) { + const retStart = rm.index + rm[0].length - rm[1].length; + defReturns.push([owner, code.slice(retStart, retStart + rm[1].length).trim()]); + } + } + } + const pairs = []; const assignStmtRe = /(?:^|[\n;])\s*([A-Za-z_][A-Za-z0-9_]*(?:\s*,\s*[A-Za-z_][A-Za-z0-9_]*|\s*=\s*[A-Za-z_][A-Za-z0-9_]*)*)\s*=(?!=)\s*([^\n;#]+)/g; let am; @@ -3691,6 +3908,9 @@ function collectPythonSymbolBindings(code, preMasked = null) { const symbols = { pathClassIdents, + pathInstanceIdents, + pathClassReturningFuncs, + fsModuleReturningFuncs, fsModuleIdents, pathlibModuleIdents, fsFuncAliases, @@ -3698,10 +3918,13 @@ function collectPythonSymbolBindings(code, preMasked = null) { fsOpenAliases, taintedIdents, }; - const maxPasses = pairs.length + classDefs.length + forPairs.length + 8; + const maxPasses = pairs.length + classDefs.length + forPairs.length + defReturns.length + 8; for (let pass = 0; pass < maxPasses; pass += 1) { const beforeSize = pathClassIdents.size + + pathInstanceIdents.size + + pathClassReturningFuncs.size + + fsModuleReturningFuncs.size + fsModuleIdents.size + pathlibModuleIdents.size + fsFuncAliases.size + @@ -3730,9 +3953,13 @@ function collectPythonSymbolBindings(code, preMasked = null) { } else if (fsOpenAliases.has(stripped)) { fsOpenAliases.add(lhs); taintedIdents.add(lhs); + } else if (isPythonPathCtorCallExpr(stripped, symbols) !== null || pathInstanceIdents.has(stripped)) { + pathInstanceIdents.add(lhs); + taintedIdents.add(lhs); } else if ( taintedIdents.has(stripped) || - isPythonPathCtorCallExpr(stripped, symbols) !== null || + receiverReferencesUnboundPathClass(stripped, symbols) || + receiverReferencesFsModule(stripped, symbols) || /\b(?:__import__|import_module|globals|locals|vars|getattr|type)\s*\(|\b(?:__class__|__base__|__bases__|__mro__|__subclasses__|__dict__)\b|sys\s*\.\s*modules/.test( maskedStripped, ) @@ -3741,6 +3968,16 @@ function collectPythonSymbolBindings(code, preMasked = null) { } } } + for (const [fnName, retExpr] of defReturns) { + if (receiverReferencesUnboundPathClass(retExpr, symbols)) { + pathClassReturningFuncs.add(fnName); + taintedIdents.add(fnName); + } + if (receiverReferencesFsModule(retExpr, symbols)) { + fsModuleReturningFuncs.add(fnName); + taintedIdents.add(fnName); + } + } for (const [clsName, baseArgs] of classDefs) { for (const rawBase of baseArgs) { const baseExpr = unwrapPythonExprParensAndWalrus(rawBase); @@ -3785,6 +4022,9 @@ function collectPythonSymbolBindings(code, preMasked = null) { } const afterSize = pathClassIdents.size + + pathInstanceIdents.size + + pathClassReturningFuncs.size + + fsModuleReturningFuncs.size + fsModuleIdents.size + pathlibModuleIdents.size + fsFuncAliases.size + @@ -4553,12 +4793,15 @@ function checkInlinePythonFs(rawCode, allowPath, options = {}) { if (rawRecv === null) { return `Unparseable .${method}() receiver in inline Python script is blocked for ${roleLabel}.`; } - if (isPythonPathClassExpr(rawRecv, pySymbols)) { + if (receiverReferencesUnboundPathClass(rawRecv, pySymbols)) { return `Unbound Python Path.${method}() call in inline Python script is blocked for ${roleLabel}.`; } if (PYTHON_OS_SHUTIL_FN_NAMES.has(method) && isPythonFsModuleExpr(rawRecv, pySymbols)) { continue; } + if (receiverReferencesFsModule(rawRecv, pySymbols)) { + return `Wrapped filesystem module .${method}() call in inline Python script is blocked for ${roleLabel}.`; + } if (method === "open") { const recvTrimmed = unwrapPythonExprParensAndWalrus(rawRecv); if ( @@ -4594,6 +4837,24 @@ function checkInlinePythonFs(rawCode, allowPath, options = {}) { ) { continue; } + if ( + ["write_text", "write_bytes", "unlink", "rmdir", "mkdir", "touch", "chmod", "lchmod"].includes( + method, + ) + ) { + const { positionals: uPos, kwargs: uKw } = splitPythonCallArgs(methodArgs); + const selfCandidate = uPos[0] ?? uKw.self ?? null; + if (selfCandidate !== null) { + const trimmedSelf = unwrapPythonExprParensAndWalrus(selfCandidate); + if ( + isPythonPathCtorCallExpr(trimmedSelf, pySymbols) !== null || + pySymbols.pathInstanceIdents.has(trimmedSelf) || + resolvePythonPathReceiverArg(trimmedSelf).found + ) { + return `Unbound Python Path.${method}() call in inline Python script is blocked for ${roleLabel}.`; + } + } + } const recv = resolvePythonPathReceiverArg(rawRecv); const isMkdir = method === "mkdir"; const isLinkMethod = @@ -4632,6 +4893,9 @@ function checkInlinePythonFs(rawCode, allowPath, options = {}) { if (isLinkMethod) { const { positionals: mPos, kwargs: mKw } = splitPythonCallArgs(methodArgs); + if (mPos.length >= 2 || Object.hasOwn(mKw, "self")) { + return `Unbound Python Path.${method}() call in inline Python script is blocked for ${roleLabel}.`; + } const targetExpr = mPos[0] ?? mKw.target ?? ""; const recvVal = recv.found ? resolveStaticArgValue(recv.expr, code, true) : null; const symlinkBaseDir = @@ -4713,6 +4977,9 @@ function checkInlinePythonFs(rawCode, allowPath, options = {}) { if (dotMatch) { const memberRecv = extractPythonReceiverBeforeDot(code, match.index - dotMatch[0].length); if (!isPythonFsModuleExpr(memberRecv, pySymbols)) { + if (receiverReferencesFsModule(memberRecv, pySymbols)) { + return `Wrapped filesystem module .${fnName}() call in inline Python script is blocked for ${roleLabel}.`; + } continue; } qualifier = "fs_alias";