From f64f2c79e94514141b1ef47b097bd0c9aa3dd960 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sat, 21 Nov 2026 23:47:52 +0000 Subject: [PATCH 1/9] fork-kit/agent-guards: the machine's agent guard hooks as a kit (#834 G4) Five Claude Code hooks that guard every agent on a shared machine, as one kit with one installer, facts from the machine file and the same messages and exit codes as before: - actions-disable-guard (PreToolUse Bash): no disabling of workflows, Actions or branch protection; fails closed (a missing or failing hook refuses, and says so) - capacity-pipe-guard (PreToolUse Bash|Monitor): no pipe out of a capacity check - memory-index-guard (Pre/PostToolUse): the auto-memory index stays inside its budget - bg-guard (Stop): no stop while a background Bash command still runs - agent-slots (UserPromptSubmit, Stop): slot and ready-queue context for orchestrators The others fail open with a visible line. `agent-guards check` runs each wired command with a case it must refuse and one it must pass; `--settings` writes a managed settings drop-in. Shared bootstrap and kit_install contract tests cover the new kit. Co-Authored-By: Claude Opus 5.5 --- .github/fork-ci-tests.txt | 10 +- fork-kit/README.md | 3 +- fork-kit/agent-guards/README.md | 129 + .../agent-guards/bin/actions-disable-guard | 3201 +++++++++++++++++ fork-kit/agent-guards/bin/agent-guards | 77 + fork-kit/agent-guards/bin/agent-slots | 97 + fork-kit/agent-guards/bin/bg-guard | 150 + fork-kit/agent-guards/bin/capacity-pipe-guard | 350 ++ fork-kit/agent-guards/bin/memory-index-guard | 189 + .../agent-guards/lib/agent_guards/__init__.py | 6 + .../agent-guards/lib/agent_guards/check.py | 169 + .../agent-guards/lib/agent_guards/config.py | 146 + .../agent-guards/lib/agent_guards/wiring.py | 94 + .../agent-guards/sbin/agent-guards-install | 127 + .../tests/actions-disable.test.py | 2505 +++++++++++++ .../agent-guards/tests/agent-slots.test.py | 111 + fork-kit/agent-guards/tests/bg-guard.test.py | 146 + .../agent-guards/tests/capacity-pipe.test.py | 436 +++ fork-kit/agent-guards/tests/config.test.py | 160 + fork-kit/agent-guards/tests/guards_fixture.py | 70 + fork-kit/agent-guards/tests/install.test.py | 172 + .../agent-guards/tests/memory-index.test.py | 196 + fork-kit/agent-guards/tests/wiring.test.py | 205 ++ fork-kit/common/README.md | 4 +- fork-kit/common/bootstrap.sh | 9 +- fork-kit/common/machine.example.json | 21 + fork-kit/common/tests/kit_install.test.py | 25 +- 27 files changed, 8799 insertions(+), 9 deletions(-) create mode 100644 fork-kit/agent-guards/README.md create mode 100755 fork-kit/agent-guards/bin/actions-disable-guard create mode 100755 fork-kit/agent-guards/bin/agent-guards create mode 100755 fork-kit/agent-guards/bin/agent-slots create mode 100755 fork-kit/agent-guards/bin/bg-guard create mode 100755 fork-kit/agent-guards/bin/capacity-pipe-guard create mode 100755 fork-kit/agent-guards/bin/memory-index-guard create mode 100644 fork-kit/agent-guards/lib/agent_guards/__init__.py create mode 100644 fork-kit/agent-guards/lib/agent_guards/check.py create mode 100644 fork-kit/agent-guards/lib/agent_guards/config.py create mode 100644 fork-kit/agent-guards/lib/agent_guards/wiring.py create mode 100755 fork-kit/agent-guards/sbin/agent-guards-install create mode 100644 fork-kit/agent-guards/tests/actions-disable.test.py create mode 100644 fork-kit/agent-guards/tests/agent-slots.test.py create mode 100644 fork-kit/agent-guards/tests/bg-guard.test.py create mode 100644 fork-kit/agent-guards/tests/capacity-pipe.test.py create mode 100644 fork-kit/agent-guards/tests/config.test.py create mode 100644 fork-kit/agent-guards/tests/guards_fixture.py create mode 100644 fork-kit/agent-guards/tests/install.test.py create mode 100644 fork-kit/agent-guards/tests/memory-index.test.py create mode 100644 fork-kit/agent-guards/tests/wiring.test.py diff --git a/.github/fork-ci-tests.txt b/.github/fork-ci-tests.txt index 907aa8fad9573..b321de178b51f 100644 --- a/.github/fork-ci-tests.txt +++ b/.github/fork-ci-tests.txt @@ -94,6 +94,14 @@ fork-ci/actions/test-select/test-select.test.py ~26s fork-ci/actions/test-select/trace-check.test.py fork-ci/actions/weakened-tests/weakened_tests.test.py fork-ci/laws/laws.test.py +fork-kit/agent-guards/tests/actions-disable.test.py ~45s +fork-kit/agent-guards/tests/agent-slots.test.py +fork-kit/agent-guards/tests/bg-guard.test.py +fork-kit/agent-guards/tests/capacity-pipe.test.py +fork-kit/agent-guards/tests/config.test.py +fork-kit/agent-guards/tests/install.test.py ~20s +fork-kit/agent-guards/tests/memory-index.test.py +fork-kit/agent-guards/tests/wiring.test.py fork-kit/cleaner/tests/compress.test.py ~15s fork-kit/cleaner/tests/daily.test.py ~19s fork-kit/cleaner/tests/dedupe.test.py ~22s @@ -104,7 +112,7 @@ fork-kit/cleaner/tests/report.test.py fork-kit/cleaner/tests/scratch.test.py fork-kit/cleaner/tests/worktrees.test.py ~43s fork-kit/common/tests/free_contract.test.py ~6s -fork-kit/common/tests/kit_install.test.py ~93s +fork-kit/common/tests/kit_install.test.py ~125s fork-kit/common/tests/machine_file.test.py fork-kit/desk/tests/install.test.py ~103s fork-kit/desk/tests/windows.test.py ~65s diff --git a/fork-kit/README.md b/fork-kit/README.md index 51553580fc7e2..f3d58d3dae1fe 100644 --- a/fork-kit/README.md +++ b/fork-kit/README.md @@ -15,6 +15,7 @@ Every kit follows the same pattern: | Kit | What | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [agent-guards](agent-guards/README.md) | Claude Code hooks that guard every agent on a machine: no disabling Actions, no piped capacity check, a memory index in budget, no stop with a background command, agent slots (Linux) | | [cleaner](cleaner/README.md) | `fork-cleaner`: free disk space by rules (`worktrees` with merged branches, `tmp`, `agent-scratch`, `docker`; `compress-cold` and `dedupe` delete no content) and never what could be needed; daily timer (Linux, systemd) | | [desk](desk/README.md) | A desktop's side of a fork fleet desk pool: runner users, walls, desk agent; one folder (Linux, WSL2) | | [gh-apps](gh-apps/README.md) | GitHub App tokens for agents through `gh-as`, without giving agents the keys (Linux) | @@ -27,7 +28,7 @@ Every kit follows the same pattern: [common](common/README.md) is code the kits share, copied into each kit's version folder: the loader of the one private machine file (`/etc/fork-kit/machine.json`) where the facts of one machine live, and the installer and -bootstrap of the cleaner, golive and schedule-kick kits. +bootstrap of the agent-guards, cleaner, golive and schedule-kick kits. [review](review/README.md) is the one kit with no installer: a skill, docs and tools an agent uses from a checkout of the fork, beside the merge gate whose parser it imports. diff --git a/fork-kit/agent-guards/README.md b/fork-kit/agent-guards/README.md new file mode 100644 index 0000000000000..1b6931eaa5269 --- /dev/null +++ b/fork-kit/agent-guards/README.md @@ -0,0 +1,129 @@ +# agent-guards: Claude Code hooks that guard every agent on a machine + +Five Claude Code hooks. Each one stops one mistake that agents made on a shared machine, at the moment they make it. +A line in the agents' instructions did not stop any of them. The hooks are general: a project gives only its facts +(file paths, a command name, a budget) in the machine file's `"agent-guards"` section. + +Linux, Python 3 standard library only. One file per hook in [bin/](bin/), the shared parts in +[lib/agent_guards/](lib/agent_guards/). + +## The hooks + +| Hook | Event (matcher) | Refuses | If the hook is missing or fails | +| ----------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| `actions-disable-guard` | PreToolUse (`Bash`), 10 s | Disabling a GitHub Actions workflow or Actions itself, or deleting or weakening branch protection or rulesets, on any repo (`gh workflow disable`, `gh api .../actions/workflows//disable`, ...). Also a listed script run with its listed flag (`refuseScripts`). | **Refuses** (exit 2): every Bash command is refused until it is back, with a line saying so | +| `capacity-pipe-guard` | PreToolUse (`Bash\|Monitor`), 10 s | A pipe out of a capacity check (`t3-capacity 2048 \| tail -1 && heavy-step`): the pipe hides the check's NOT OK exit | Passes (exit 1, "hook skipped, commands are NOT checked") | +| `memory-index-guard` | PreToolUse (`Write\|Edit\|MultiEdit`) and PostToolUse (`Write\|Edit\|MultiEdit\|Bash`), 5 s | An auto-memory index (`/memory/MEMORY.md`) over its budget: a write that would make it too big (Pre), or one that did, through any tool (Post, once per change) | Passes (exit 1, with a line) | +| `bg-guard` | Stop, 5 s | Ending a turn while a Bash command the agent started in the background still runs (the end of it may never wake the agent). At most `maxBlocks` times per session | Passes (exit 1, with a line) | +| `agent-slots` | UserPromptSubmit and Stop, 5 s | Only for the orchestrator sessions listed in `sessionsFile`: adds "agents alive, slots free, ready queue" as context; blocks a stop once while slots are free and the ready queue has items | Passes (exit 1, with a line) | + +How each hook answers is what Claude Code reads: PreToolUse refuses with exit 2 and the reason on stderr. PostToolUse +and Stop block with `{"decision": "block", "reason": ...}` on stdout. UserPromptSubmit adds `additionalContext`. +Exit 0 with nothing on stdout means pass. The messages and exit codes are the same as these hooks had before they +moved into this kit, so an agent sees no change. Each hook's file says what it reads and what it does not, and where +its tests are. + +**Why one fails closed and the others open.** `actions-disable-guard` guards against a step that cannot be undone +by an agent (Actions turned off on a repo). If it is gone or broken, refusing every Bash command is the safe answer, +and the message says so. The other four guard mistakes. Refusing every call because a helper is gone would stop all +work on the machine. The settings entry does both (`agent-guards hooks` prints it): + +```sh +# closed +g=/usr/local/bin/actions-disable-guard; [ -r "$g" ] || { echo "actions-disable-guard: $g is missing: every Bash command is refused until it is back" >&2; exit 2; }; /usr/bin/python3 -IB "$g" || { echo "actions-disable-guard: the guard failed (exit $?): the command is refused" >&2; exit 2; } +# open +g=/usr/local/bin/capacity-pipe-guard; [ -r "$g" ] || { echo "capacity-pipe-guard: $g is missing: hook skipped, commands are NOT checked" >&2; exit 1; }; exec /usr/bin/python3 -IB "$g" +``` + +A hook that runs past its timeout is ended by Claude Code, and the call goes on (no hook here sets `onFailure`). +`actions-disable-guard` answers by itself within 5 s of its start (it refuses when it runs out of time with a +guarded word unread), well inside its 10 s. + +## Settings (the machine file) + +Every key is optional. With no machine file, or no `"agent-guards"` section, each hook uses the defaults below. +These are the values the hooks had before. The file is `/etc/fork-kit/machine.json` +([common/machine_file.py](../common/machine_file.py): owned by root, not writable by others, so an agent cannot +change a guard's facts). A section that is broken (a wrong type, an unknown key, a bad path) is not used: the hook +uses its defaults and writes one line on stderr. `agent-guards self-check` names the problem. A broken section +drops the extra `refuseScripts` rules too, so fix one at once. + +| Key | Default | What it is | +| ------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| `actionsDisable.stateDir` | `~/.local/state/actions-disable-guard` | The refusal log (`log`) and a parse cache | +| `actionsDisable.refuseScripts` | `[]` | `{"name": "garden.py", "flag": "--fix", "why": "..."}`: also refuse running that script with that flag (a project's own tool that disables workflows) | +| `capacityPipe.commands` | `["t3-capacity"]` | The capacity checks: commands that answer OK (exit 0) or NOT OK (exit 1) | +| `memoryIndex.maxChars` | `6000` | Characters in the whole index at most | +| `memoryIndex.maxLine` | `160` | Characters in one line at most | +| `memoryIndex.stateDir` | `~/.cache/memory-index-guard` | One file per session: the index as last seen | +| `bgGuard.skipSessionsFiles` | `[]` | Files of session ids (one per line, `#` comments) that are never blocked, such as orchestrators that are woken another way | +| `bgGuard.maxBlocks` | `3` | Blocks per session at most, so a background job left on purpose never loops | +| `bgGuard.stateDir` | `~/.local/state/bg-guard` | One block count per session (raised under a lock) | +| `agentSlots.sessionsFile` | `""` (the hook does nothing) | The orchestrator session ids it acts for | +| `agentSlots.queue` | `""` | A markdown file; the ready list is the `- ` lines under `readyHeading` | +| `agentSlots.readyHeading` | `"## Ready"` | | +| `agentSlots.maxAlive` | `10` | Agent processes at most | +| `agentSlots.processName` | `"claude"` | The process name that is counted | +| `agentSlots.note` | `""` | Extra text for the context line (a build-agent limit, say) | + +Paths are absolute or start with `~/` (the home of the user the hook runs as). An example is in +[machine.example.json](../common/machine.example.json). + +**State and logs.** Each hook keeps going when its state folder or log cannot be written (a full disk, a folder +that is not writable): the answer never depends on it. `memory-index-guard` writes its state whole (a temporary +file, then a rename). `bg-guard` counts under a lock, so two Stop hooks at once count two blocks. +`actions-disable-guard` appends one line per refusal. `agent-slots` writes nothing. + +## Install + +As root, from a release commit of the fork (the shared [bootstrap](../common/bootstrap.sh) checks that it is on the +protected `ci-release` branch first): + +```sh +sh fork-kit-bootstrap.sh --kit agent-guards --repo OWNER/FORK --sha RELEASE_SHA [--settings | --no-settings] +``` + +The installer ([sbin/agent-guards-install](sbin/agent-guards-install), on the shared +[kit_install.py](../common/kit_install.py)) copies the release to `/usr/local/libexec/agent-guards/versions//`, +self-tests the copy, and links `/usr/local/bin/` and `/usr/local/bin/agent-guards` to it. It is safe to run +again and to stop at any step. + +`--settings` also writes the hooks' entries as a Claude Code **managed settings drop-in**, +`/etc/claude-code/managed-settings.d/agent-guards.json`. Every Claude Code session of every user on the machine +reads it, and only root can change it. It is written after the links, so every hook it names is there. Sessions +already running keep the hooks they started with. `--no-settings` removes it; the choice is kept, so a run with +neither keeps the last one (a first install: no drop-in). The installer refuses to overwrite a drop-in of that name +it did not write. Uninstall removes the drop-in first, then the hooks. + +Without `--settings`, put the entries in a settings file by hand: `agent-guards hooks` prints the `"hooks"` object. +A hook that is in both the drop-in and a user's settings runs twice. That is harmless for the refusing hooks, but +`bg-guard` then counts two blocks per stop, so remove the old entries soon after. + +## Check + +```sh +agent-guards self-check # the machine file section, the hook files, the drop-in +agent-guards check # run every hook wired in the drop-in: one case it must refuse, one it must pass +agent-guards check --settings ~/.claude/settings.json # the same for hooks wired in any settings file +agent-guards-install self-check # the installed files are the ones the installer wrote +``` + +`check` runs each wired command the way Claude Code does (`/bin/sh -c`, the event on stdin) and prints PASS or FAIL +for each case, and MISSING for a hook that is not wired. It changes nothing on the machine: the memory index and the +sessions are made up in a temporary folder, and their state files are removed afterwards. For `bg-guard` it starts a +`sleep` in the background under a stand-in parent named `claude`. + +## General vs project + +Everything in this kit is general. What a project or a machine adds is only its facts in the machine file: the +capacity command's name, the memory budget, the orchestrator's session file and queue, and a script of its own that +must not run with a given flag. Nothing in the hooks names a project, a person or a path of one machine. + +## Tests + +`tests/*.test.py`, run by the fork's CI (`.github/fork-ci-tests.txt`), with no root, no network and no installed +kit. They cover each hook's refuse and pass cases, and what happens when state is missing or old. That means: a +machine file that is missing, empty, garbled or not root-owned; a log or state folder that is missing or not +writable; two hooks at once; very long commands; and commands that only mention a guarded word (echo, a heredoc +into a file, a commit message). The settings entries are run as `/bin/sh -c` with the hook missing and with the +hook failing. diff --git a/fork-kit/agent-guards/bin/actions-disable-guard b/fork-kit/agent-guards/bin/actions-disable-guard new file mode 100755 index 0000000000000..038ecd9fa670b --- /dev/null +++ b/fork-kit/agent-guards/bin/actions-disable-guard @@ -0,0 +1,3201 @@ +#!/usr/bin/python3 -IB +"""Claude Code PreToolUse hook (Bash): refuse disabling GitHub Actions workflows, or Actions itself, on any repo. +Part of fork-kit/agent-guards (README.md there: install, settings entry, the machine file's "agent-guards" section). + +Owner rule ("guards that refuse, not trust"). Why: a GitHub security log showed workflows.disable_workflow events +with the user agent "GitHub CLI ... Agent/claude-code_...": agents disabled workflows with the owner's gh login. + +Best effort against mistakes, not a sandbox; the wall is a token that cannot do it. An agent runs as the +user who owns this hook, so one that sets out to get round a command-text hook can. Where the guard stops reading +(a limit, a file too big, out of time, its own crash) it refuses when the text it did not read names a guarded token. +A file too big to read whole, or one it cannot open, counts only where a shell or interpreter runs it (or a script +is copied); data handed to a tool passes as before. +How it reads a command (by parsing, not by pattern): + 1. Shell text, as a shell reads it: quotes, backslashes, $'..', comments, redirections, heredocs, && ; | chains, + $(..) `..` <(..) (their insides are commands too), plain NAME=value and `for NAME in ..` variables (every value + a name gets in the text is tried). Text it cannot know (other $VARs, $(..) output, "$@", {a,b}) stays in the + word as a hidden mark, it is never dropped. + 2. `gh` arguments, as gh reads them (cobra/pflag, gh 2.102): flags before the subcommand, `--flag=value`, + `--flag value`, joined short flags (`-iXPUT`, `-XPUT`, `-X=PUT`), and which `gh api` flags take a value, so a + value that looks like a flag (`-p -XGET`, `--jq --method=GET`) is a value. The last -X/--method wins. An + unknown flag, a flag without its value, or hidden text where a flag or the method may stand makes the call a + write to whatever guarded path is in sight. + 3. Guarded tokens. After decoding (backslashes, \\uXXXX, \\xXX, %XX, quotes, case, /./ and /x/../) it looks for: + .../actions/workflows//disable, `workflow disable`, .../actions/permissions, branches//protection, + rulesets/, and the GraphQL mutations deleteBranchProtectionRule, deleteRepositoryRuleset and + updateRepositoryRuleset. A command that names one of them passes only when the guard can PROVE it harmless: + - the command word only handles text (echo, cat, grep, rg, sed, jq ..: the DATA list below) + - gh, with a gh command this reader knows (rule 2 decides read or write) + - `curl -q ..` / `wget --no-config ..` as a plain read (the tool's read-only flags and nothing else) + - git commit/log/grep/diff/add ..: text git itself never runs + - shell text (bash -c '..', a .sh file, ssh host '..', a heredoc into sh): read again by these same rules + Every other use is refused: a command word the guard does not know (taskset, chrt, unshare, sg, screen, tmux, + at, expect, make, a project tool, a word from a variable), inline code or a script in any other language + (python -c, node -e, a .py file), an HTTP client without a flag table, gh under an alias or an extension. + 4. Known command words only widen what passes; an unknown word never hides what follows it. The words behind it + are read as a command of their own (`taskset 1 bash -c ..`), its quoted arguments as shell text + (`sg users -c '..'`), and gh is still gh under a name the command gives it (`ln -s /usr/bin/gh g; ./g ..`). + Files it is handed are looked at too: a shell script is read in full, a file that looks like code in another + language (.py/.js/.. name, a `#!` line, the executable bit) may not name a guarded token. An interpreter's + script is found behind its own words (`deno run x.ts`, `python3 -m x`, `node -r ./x.js`). A wrapper is a + wrapper only under its own name or in a system folder: `./sudo` and the `nice` of `bash nice` are files. + Files that carry arguments are read: `curl -K`, `wget -i`, `xargs -a`. + 5. Flow. Token text that goes on (a pipe into anything but a DATA word, a file, $(..), an exported variable, a + file that names a token and gets another name with cp/mv/ln) in a command that also runs a word the guard + cannot read is refused: `echo '' | at now`, `cp x.txt run.sh && bash run.sh`, + `curl -q -X PUT "$(cat url.txt)"`. + 6. It answers in time: the hook has a 10 s limit and a hook that is not done by then does not stop the + command, so 5 s after the hook process started the guard refuses the command itself. Before that: + - fast exit: a command of plain words that cannot name or run anything guarded (ls, git status, cat a > b, + grep ..: quick_pass() below) passes before any file is read and whatever the clock says; + - cache: what it learns from files (a code file names a token or not, a `#!` line, the gh aliases) is kept + 60 s in /cache-v1.json (default ~/.local/state/actions-disable-guard), per file name + inode + size + change times. + A file changed within the last 2 s is not cached; a missing, broken, old, foreign or odd cache is ignored + and written new (temp file, then rename). Shell scripts are still read every time (their reading depends + on the command around them). + +Refused: + - gh workflow disable ... (also through gh aliases: existing ones are expanded, new ones refused; + `gh workflow ` too) + - gh api / curl / wget / httpie to .../actions/workflows//disable + - any write (not GET/HEAD, fields or --input without -X, a method-override header) to .../actions/permissions[/...] + for a repo, org or enterprise; the one write that passes is the re-enable + `gh api -X PUT repos/O/R/actions/permissions -F enabled=true [-f allowed_actions=all]` + - curl and wget to a guarded path unless their own config is off: curl reads ~/.curlrc ($CURL_HOME, + $XDG_CONFIG_HOME) unless `-q`/`--disable` is the FIRST argument, wget reads ~/.wgetrc ($WGETRC, /etc/wgetrc) + unless `--no-config` is given, and a line there (`request = PUT`) turns a read into a write. The flag rule was + picked over "refuse when such a file exists" because it can be read from the command text alone: the guard + does not have to know every place the tool looks, or what the same command writes there first. + - a path with hidden parts that can spell one of those (`"$B/disable"`, `repos/$R/actions/$X`), when it is a write; + and, in the command itself, a `gh api` write whose path is hidden altogether (`gh api -X PUT "$URL"`) + - DELETE of branch protection (`.../branches//protection[/...]`, also for a branch name with slashes) or of a + ruleset, the GraphQL mutations that do the same, a write that switches one ruleset off (`enforcement=disabled`, + updateRepositoryRuleset with DISABLED, also written with \\u escapes) or carries a body the guard cannot + read. Other changes to protection with PUT/PATCH/POST pass (an owner decision) + - everything rule 3 cannot prove and rule 5 catches (see there) + - `gh` with a word that is no gh command when the gh config holds YAML outside the small subset this reader + follows (`!!str` tags, `? ` keys, anchors, flow maps ..), or sits in a folder the guard cannot read + (GH_CONFIG_DIR, XDG_CONFIG_HOME or HOME from a variable): the word may be an alias + - each script of the machine file's actionsDisable.refuseScripts run with its flag (a project tool that + disables workflows itself: {"name": "garden.py", "flag": "--fix", "why": "disables ..."}), where the file is real + - a command the guard cannot finish reading in time +Passes: reads (GET), gh workflow enable/list/view/run, PUT .../enable, searching and writing text about all this +(rg/grep, notes, commit messages, issue and PR bodies through gh), and every command that names no guarded token. +A file that is byte for byte this guard is not read as a script (running or testing the guard is no attack). + +Known over-refusals (harmless, but not provable from the text; the message says what to change): + - a read with curl/wget without `-q` / `--no-config`, or with httpie/xh/aria2c: use `gh api` + - code that only mentions a token (python -c "print('gh workflow disable')", a heredoc into python that edits + a text, a .py file): change or search such text with an edit or search tool; this guard's own test file run + directly: run it through a test runner that is handed its folder + - a token in the words of a tool the guard does not know (`sometool -m "text about actions/permissions"`, + awk '/actions\\/permissions/'), in the words handed to a shell function, or written to a file / piped on in + the same command that runs such a tool + - a code file that names a token (this guard, its tests) as an argument of a tool the guard does not know + (`pytest tests/test_x.py`, `ruff check x.py`, a project commit tool): name the folder, or use git add + - an exported variable or a `VAR=.. command` prefix that carries a token + - a GraphQL body piped into gh (`echo '{..}' | gh api graphql --input -`): use `--input - <<< '{..}'` or -f query= + - a gh word that is no gh command (an alias) while the gh config is half-written or uses YAML outside the subset + +Not covered (a text guard cannot): a value hidden in a variable, file or command output that the command gets at +run time (a download, base64, a file renamed by a tool other than cp/mv/ln), code that builds the words at run +time or loads them from another file (import, require), a file of commands that is no shell script and does not +look like code, written by an earlier command and handed to a tool the guard does not know (`at -f job.txt`, +`make -f x.mk`, a Makefile, package.json scripts), a gh copy made by an earlier command when there is no gh on +PATH to compare it with, a program that shadows a DATA or wrapper word on PATH, a remote shell's own config, +emptying branch protection with PUT/PATCH/POST, raw clients (openssl s_client). Also not covered (a review round; +each needs a command built to hide the action; closed by the token layer): + - known words that run code: sed `e`, rg --pre, find -exec, BASH_ENV, git diff.external / core.fsmonitor + - a command kept in a variable and run as the command word (`read -r c <<< '..'; $c`) + - a script changed by the same command before it runs it (mv, ln, >, >>, sed -i, then bash) + - a GraphQL query from a variable or command output (`-f query="$Q"`) +A guarded call only in a script 4 or more levels deep (a.sh -> b.sh -> c.sh -> d.sh) passes as an unknown program +unless other text in the command flows on. +gh has no request hook, so this hook is the command-text layer; the wall is a token that cannot do it. + +Escape hatch (owner only, by hand): start the Claude Code session with + CLAUDE_GUARD_OWNER_ALLOW_ACTIONS_DISABLE=$(date -u +%F) claude +and put #owner-approved:actions-disable in the command. The value must be today's UTC date (a stale export opens +nothing); a command prefix or `export` in the Bash tool never reaches this hook; the variable in any settings file +is refused (an agent could write those). Fails closed: an internal error refuses commands that look dangerous. + +Facts from the machine file (fork-kit/agent-guards/README.md): actionsDisable.stateDir (cache and log of +refusals, default ~/.local/state/actions-disable-guard) and actionsDisable.refuseScripts (default none). A missing +machine file or section gives those defaults; a broken one too, with one line on stderr: the guard never weakens. +Tests: fork-kit/agent-guards/tests/actions-disable.test.py +""" +import datetime as dt, fnmatch, glob, itertools, json, os, re, signal, sys, time +from stat import S_ISDIR, S_ISREG +from urllib.parse import unquote + + +def _settings(): + """(actionsDisable settings, problem or None). The kit's lib sits next to bin/; a copy without it keeps the + built-in defaults and says so (on stderr, in answer()).""" + try: + sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.realpath(__file__))), 'lib')) + from agent_guards import config + return config.load('actionsDisable') + except BaseException as e: # noqa: BLE001 - the guard works without its config + return ({'stateDir': '~/.local/state/actions-disable-guard', 'refuseScripts': []}, + f'cannot load the kit\'s config code ({type(e).__name__}: {e})') + + +SETTINGS, SETTINGS_PROBLEM = _settings() +REFUSE_SCRIPTS = tuple(SETTINGS['refuseScripts']) + +MARK_ENV, MARK_CMD = 'CLAUDE_GUARD_OWNER_ALLOW_ACTIONS_DISABLE', '#owner-approved:actions-disable' +# Marks inside a word (private-use characters; the same characters in a command read as hidden text too): +HID = '' # text the guard cannot know, as one piece of this word +WILD = '' # text the guard cannot know that may be no word at all, or several ("$@", unquoted $X, {a,b}) +DISABLE_RE = re.compile(r'actions/workflows/[^/\s]+/disable(?![\w.-])', re.I) +PERM_RE = re.compile(r'actions/permissions(?![\w-])', re.I) +PROTECT_RE = re.compile(r'branches/[^\s?#]+?/protection(?![\w-])|(? (how it looks spelled out, [(its path words, None = any one word, ... = one or more (a branch name +# may hold slashes); whether more may follow)]) +GUARDED = {'disable': (DISABLE_RE, [(['actions', 'workflows', None, 'disable'], False)]), + 'perm': (PERM_RE, [(['actions', 'permissions'], True)]), + 'protect': (PROTECT_RE, [(['branches', ..., 'protection'], True), (['rulesets', None], False)]), + 'ruleset': (RULESET_RE, [(['rulesets', None], False)])} # part of protect: one ruleset, by id +PLACEHOLDER = re.compile(r'\{(?:owner|repo|branch)\}') # gh api fills these in from the checkout +READS = ('GET', 'HEAD') +SHELLS = {'sh', 'bash', 'zsh', 'dash', 'ksh', 'fish', 'busybox'} +WRAPPERS = {'sudo', 'doas', 'env', 'command', 'exec', 'builtin', 'nohup', 'time', 'nice', 'ionice', 'timeout', + 'stdbuf', 'xargs', 'setsid', 'unbuffer', 'chronic', 'flock', 'eval', 'source', '.', 'do', 'then', + 'else', 'elif', 'if', 'while', 'until', '{', '}', '!', 'watch', 'script', 'runuser', 'systemd-run', + 'coproc'} | SHELLS +ARG_FLAGS = {'-u', '-g', '-n', '-k', '-s', '-I', '-P', '-L', '-d', '-E', '-C', '-p', '-o', '-e', '-i', '-l', + '--user', '--group', '--signal', '--kill-after', '--unit'} +TEXT_ARGS = {'trap', 'ssh', 'su', 'parallel'} # commands whose quoted arguments are shell text +SETTERS = {'export', 'local', 'declare', 'typeset', 'readonly'} +TAINTERS = {'read', 'mapfile', 'readarray', 'getopts', 'printf', 'let', 'unset', 'select'} # set names from data +INTERPRETERS = re.compile(r'^(python[\d.]*|pypy[\d.]*|node|nodejs|deno|bun|perl|ruby|php|pwsh|lua|tclsh|osascript)$') +NET_CLIENTS = {'curl', 'wget', 'http', 'https', 'xh', 'xhs', 'curlie', 'httpie', 'aria2c'} +# gh api (gh 2.102.0, `gh api --help`): the flags that take a value, and the switches +API_VALUE = {'cache', 'field', 'header', 'hostname', 'input', 'jq', 'method', 'preview', 'raw-field', 'template'} +API_SWITCH = {'allow-escape-sequences', 'include', 'paginate', 'silent', 'slurp', 'verbose', 'help'} +API_SHORT = {'F': 'field', 'H': 'header', 'q': 'jq', 'X': 'method', 'p': 'preview', 'f': 'raw-field', + 't': 'template'} +API_SHORT_SWITCH = {'i', 'h'} +GH_VERSION = '2.102' +# gh's own commands and help topics (`gh help`, gh 2.102.0). An alias cannot take one of these names. +GH_COMMANDS = {'auth', 'browse', 'codespace', 'discussion', 'gist', 'issue', 'org', 'pr', 'project', 'release', + 'repo', 'skill', 'cache', 'run', 'workflow', 'agent-task', 'alias', 'api', 'attestation', + 'completion', 'config', 'copilot', 'extension', 'gpg-key', 'label', 'licenses', 'preview', 'ruleset', + 'search', 'secret', 'ssh-key', 'status', 'variable', 'help', 'version', 'accessibility', 'actions', + 'environment', 'exit-codes', 'formatting', 'mintty', 'reference', 'telemetry', + 'cs', 'rs', 'at', 'agent', 'agents', 'agent-tasks'} # the short names gh has for its own commands +# In the command itself (not in script files or alias texts): refuse a `gh api` write whose path is hidden +# altogether. It stops careless calls only (a hidden value can always carry a whole command), so it is one switch. +HIDDEN_PATH_RULE = True +# curl and wget: what a plain read may carry, one table per tool because each reads flags its own way: +# (switches, flags with a value, method flags, short switches, short flags with a value, short method flag, +# whether --flag=value is read). Anything else next to a guarded path is refused; a tool without a table +# (httpie, xh, aria2c, a hidden command word) may carry no flags at all there. +NET_TOOLS = { + 'curl': ({'--silent', '--show-error', '--location', '--fail', '--fail-with-body', '--include', '--head', + '--verbose', '--compressed', '--get', '--globoff', '--no-buffer', '--no-progress-meter', '--http1.1', + '--http2', '--ipv4', '--ipv6', '--disable'}, + {'--header', '--output', '--user-agent', '--max-time', '--connect-timeout', '--retry', '--retry-delay', + '--retry-max-time', '--write-out', '--user', '--oauth2-bearer', '--url', '--dump-header'}, + {'--request'}, 'qsSLfiIvgGN46', 'HoAmwuD', 'X', False), + 'wget': ({'--quiet', '--no-verbose', '--server-response', '--verbose', '--no-config'}, + {'--output-document', '--header', '--tries', '--timeout', '--user-agent'}, + {'--method'}, 'qSv46', 'OtTU', '', True), +} +NO_FLAGS = (set(), set(), set(), '', '', '', False) +MAX_FILE, MAX_DEPTH, MAX_NEST, MAX_READINGS = 2_000_000, 2, 8, 64 +HARD_FILE = 64_000_000 # a bigger file that a shell or interpreter is about to run is refused unread +TOO_BIG, NO_OPEN = f'a file over {HARD_FILE // 1_000_000} MB', 'a file the guard cannot open' +# The hook is registered with a 10 s limit, and a hook that is not done by then does not stop the command. So the +# guard stops itself earlier and refuses: a command it could not read to the end is one it cannot let through. +BUDGET = 5.0 +START = time.monotonic() +QUICK = True # the fast exit (quick_pass); a switch for the tests that compare it with the full reading +CACHE_VERSION, CACHE_LIFE, CACHE_MAX, CACHE_BYTES = 1, 60.0, 512, 1_000_000 +CACHE_RACY = 2.0 +CRASH_RE = re.compile(r'\bgh\b|curl|wget|httpie|\bxh\b|api\.github|workflow|disable', re.I) # see main() +SELF = os.path.realpath(os.path.abspath(__file__)) if '__file__' in globals() else '' +RULE = ('Owner rule (2026-11-13, "guards that refuse, not trust"): no agent disables GitHub Actions workflows, or ' + 'Actions itself, on any repo; re-enabling (`gh workflow enable`, PUT .../enable) is fine. If disabling is ' + 'really needed, stop and ask the owner: name the repo, the workflow and why. Only the owner can approve ' + f'it: they start the session with {MARK_ENV}= in its environment and the command then carries ' + f'{MARK_CMD}. Agents must not set that variable (command prefix, export, settings file or anywhere else), ' + 'add the marker on their own, or route around this guard with scripts, aliases or other HTTP clients.') +UNREADABLE = ('If this call is harmless, write it so the guard can read it: the path and the flags spelled out in ' + 'the command, variables only for ids and only inside quotes.') + + +PREFIX = 'Refused by actions-disable-guard: ' + + +def reason(what, hint=''): + return f'{PREFIX}{what}. {hint + " " if hint else ""}{RULE}' + + +class Slow(BaseException): + """The guard is out of time for this command. Not an Exception, so no `except Exception` on the way swallows it.""" + + +def out_of_time(*_): + raise Slow() + + +SLOW = reason(f'the guard could not finish reading this command and the scripts it runs within {BUDGET:g} s of ' + 'its start, so it refuses (a hook that runs out of time would let the command through unread)', + 'Run it as smaller commands; tell the owner if this repeats.') + + +def process_age(): + """Seconds the hook process has used of its limit. The 10 s limit counts from the start of the process, so + Python's own start and the reading of the event count too. Loaded as a module (tests, gh-as) there is no hook + clock: 0.""" + return since_start() if __name__ == '__main__' else 0.0 + + +def since_start(): + """Seconds since this process started: from /proc where it is there and makes sense, else since this file was + loaded (the first thing the process does).""" + since = time.monotonic() - START + try: + with open('/proc/self/stat') as f: + ticks = int(f.read().rsplit(')', 1)[1].split()[19]) # field 22: start time, in clock ticks since boot + with open('/proc/uptime') as f: + age = float(f.read().split()[0]) - ticks / os.sysconf('SC_CLK_TCK') + if since <= age < 3600: + return age + except (OSError, ValueError, IndexError): + pass + return since + + +def hidden(tok): + return HID in tok or WILD in tok + + +# ---------- shell text -> commands of words + +ORD = re.compile(r'[^ \t\n\\\'"$`<>;&|()#]+') +DQ_ORD = re.compile(r'[^"\\$`]+') +NAME = re.compile(r'[A-Za-z_]\w*') +REDIR = re.compile(r'<<<|<<-|<<|<>|<&|>>|>&|>\||<|>') +ASSIGN = re.compile(r'^([A-Za-z_]\w*)(\+?)=(.*)$', re.S) +BRACE = re.compile(r'\{[^{}\s]*(?:,|\.\.)[^{}\s]*\}') +ANSI = re.compile(r'\\(x[0-9a-fA-F]{1,2}|u[0-9a-fA-F]{1,4}|U[0-9a-fA-F]{1,8}|[0-7]{1,3}|c.|.)', re.S) +ANSI_ONE = {'n': '\n', 't': '\t', 'r': '\r', 'a': '\a', 'b': '\b', 'e': '\x1b', 'E': '\x1b', 'f': '\f', 'v': '\v', + '\\': '\\', "'": "'", '"': '"', '?': '?'} +FUNC_RE = re.compile(r'(?:^|[;&|\n{(])\s*(?:function\s+([A-Za-z_][\w.:-]*)|([A-Za-z_][\w.:-]*)\s*\(\s*\))') + + +def ansi_c(s): + """The text of a $'..' string.""" + def one(m): + e = m.group(1) + if e[0] in 'xuU' and len(e) > 1: + return chr(min(int(e[1:], 16), 0x10ffff)) + if e[0] in '01234567': + return chr(int(e, 8) & 0xff) + if e[0] == 'c' and len(e) == 2: + return chr(ord(e[1]) & 0x1f) + return ANSI_ONE.get(e, '\\' + e) + return ANSI.sub(one, s) + + +class Lex: + """Shell text as a shell splits it. cmds: one dict per simple command with words (lists of pieces), redirs + [(operator, word)] and docs [heredoc body]. A piece is (kind, text, quoted): L literal text, V a $NAME, H text + no reader can know ($(..), $1, ${X:-y}), M the same but maybe several words ("$@"). subs: the texts inside + $(..), `..`, <(..), which are commands too. taint: names that get a value no reader can know. Never raises: + an unclosed quote or bracket runs to the end (a shell runs the lines before it all the same).""" + + def __init__(self, text, run=True): + self.t, self.n = text, len(text) + self.cmds, self.subs, self.taint, self.spans = [], [], set(), [] + self.cur, self.word, self.redir, self.pending, self.depth = self.new(), None, None, [], 0 + if run: + self.run() + + @staticmethod + def new(): + return {'words': [], 'redirs': [], 'docs': []} + + @classmethod + def expansions(cls, text): + """The commands inside the $(..) and `..` of text a shell expands without reading quotes (a heredoc body).""" + lx, i = cls(text, run=False), 0 + while i < lx.n: + c = text[i] + if c == '\\': + i += 2 + elif c == '$': + i = lx.dollar(i, True) + elif c == '`': + i = lx.backtick(i, True) + else: + i += 1 + return lx.subs + + def plain(self): + """The text without its heredoc bodies.""" + out, at = [], 0 + for a, b in self.spans: + out.append(self.t[at:a]) + at = b + return ''.join(out) + self.t[at:] + + def lit(self, s, quoted=False): + if self.word is None: + self.word = [] + if self.word and self.word[-1][0] == 'L' and self.word[-1][2] == quoted: + self.word[-1] = ('L', self.word[-1][1] + s, quoted) + else: + self.word.append(('L', s, quoted)) + + def piece(self, kind, text, quoted): + if self.word is None: + self.word = [] + self.word.append((kind, text, quoted)) + + def end_word(self): + w, self.word = self.word, None + if w is None: + return + op, self.redir = self.redir, None + if op is None: + self.cur['words'].append(w) + elif op in ('<<', '<<-'): # the word is the heredoc's end marker; quoted = its body is not expanded + mark = ''.join(p[1] if p[0] == 'L' else '$' + p[1] for p in w) + self.pending.append((mark, self.cur, any(p[0] == 'L' and p[2] for p in w))) + else: + self.cur['redirs'].append((op, w)) + + def end_cmd(self): + self.end_word() + self.redir = None + if self.cur['words'] or self.cur['redirs'] or any(c is self.cur for _, c, _ in self.pending): + self.cmds.append(self.cur) + self.cur = self.new() + + def run(self): + t, n, i = self.t, self.n, 0 + while i < n: + m = ORD.match(t, i) + if m: + self.lit(m.group()) + i = m.end() + continue + c, nxt = t[i], t[i + 1:i + 2] + if c in ' \t': + self.end_word() + i += 1 + elif c == '\n': + self.end_cmd() + i = self.docs(i + 1) if self.pending else i + 1 + elif c == '\\': + if nxt != '\n': # backslash + line break joins the lines + self.lit(nxt or '\\', True) + i += 2 + elif c == "'": + j = t.find("'", i + 1) + j = n if j < 0 else j + self.lit(t[i + 1:j], True) + i = j + 1 + elif c == '"': + i = self.dquote(i + 1) + elif c == '$': + i = self.dollar(i, False) + elif c == '`': + i = self.backtick(i, False) + elif c == '#': + if self.word is None: # a comment, to the end of the line + j = t.find('\n', i) + i = n if j < 0 else j + else: + self.lit(c) + i += 1 + elif c in '<>': + if nxt == '(': # <(..) >(..) + j = self.close(i + 1, '(', ')') + self.subs.append(t[i + 2:j]) + self.piece('H', '', False) + i = j + 1 + continue + if self.word is not None and all(p[0] == 'L' and not p[2] and p[1].isdigit() for p in self.word): + self.word = None # 2>file: the 2 is no argument + self.end_word() + self.redir = REDIR.match(t, i).group() # the next word is its target, no argument + i += len(self.redir) + elif c == '&': + if nxt == '>': + self.end_word() + self.redir = '&>' + i += 3 if t[i + 2:i + 3] == '>' else 2 + else: + self.end_cmd() + i += 2 if nxt == '&' else 1 + elif c == '|': + if nxt != '|': + self.cur['pipe'] = True # its output is the next command's input + self.end_cmd() + i += 2 if nxt in ('|', '&') else 1 + elif c == ';': + self.end_cmd() + i += 1 + while t[i:i + 1] in (';', '&') and t[i:i + 1]: + i += 1 + elif c == '(': + w = self.word + if w and len(w) == 1 and w[0][0] == 'L' and not w[0][2] and re.fullmatch(r'[A-Za-z_]\w*\+?=', w[0][1]): + self.taint.add(w[0][1].rstrip('+=')) # NAME=( .. ): an array, no single known text + j = self.close(i, '(', ')') + self.subs.append(t[i + 1:j]) + self.word = None + i = j + 1 + else: + self.end_cmd() + self.depth += 1 + i += 1 + else: # ')': the end of a ( .. ) group, or of a `case` pattern + if self.depth: + self.depth -= 1 + else: + self.cur['pat'] = True + self.end_cmd() + i += 1 + self.end_cmd() + + def dquote(self, i): + t, n = self.t, self.n + self.lit('', True) + while i < n: + c = t[i] + if c == '"': + return i + 1 + if c == '\\' and t[i + 1:i + 2] in ('$', '`', '"', '\\', '\n') and i + 1 < n: + if t[i + 1] != '\n': + self.lit(t[i + 1], True) + i += 2 + elif c == '$': + i = self.dollar(i, True) + elif c == '`': + i = self.backtick(i, True) + else: + m = DQ_ORD.match(t, i) + self.lit(m.group() if m else c, True) + i = m.end() if m else i + 1 + return n + + def dollar(self, i, q): + t = self.t + c = t[i + 1:i + 2] + if c == '(': # $(..) and $((..)) + j = self.close(i + 1, '(', ')') + self.subs.append(t[i + 2:j]) + self.piece('H', '', q) + return j + 1 + if c == '{': + j = self.close(i + 1, '{', '}') + body = t[i + 2:j] + if NAME.fullmatch(body): + self.piece('V', body, q) + elif re.fullmatch(r'[@*]|[A-Za-z_]\w*\[[@*]\]', body): + self.piece('H' if q and '*' in body else 'M', '', q) + else: # ${X:-y}, ${X/a/b}, ${#X}, ${!X}: unknown text; ${X:=y} also sets X + m = NAME.match(body) + if m and re.match(r':?=', body[m.end():]): + self.taint.add(m.group()) + self.subs += Lex(body).subs + self.piece('H', '', q) + return j + 1 + m = NAME.match(t, i + 1) + if m: + self.piece('V', m.group(), q) + return m.end() + if c in ('@', '*') and c: + self.piece('H' if q and c == '*' else 'M', '', q) + return i + 2 + if c and c in '0123456789?$!#-': + self.piece('H', '', q) + return i + 2 + if c == "'" and not q: # $'..' + j = i + 2 + while j < self.n and t[j] != "'": + j += 2 if t[j] == '\\' else 1 + self.lit(ansi_c(t[i + 2:j]), True) + return j + 1 + if c == '"' and not q: # $".." + return self.dquote(i + 2) + self.lit('$', q) + return i + 1 + + def backtick(self, i, q): + t, j = self.t, i + 1 + while j < self.n and t[j] != '`': + j += 2 if t[j] == '\\' else 1 + self.subs.append(re.sub(r'\\([`$\\])', r'\1', t[i + 1:j])) + self.piece('H', '', q) + return j + 1 + + def close(self, i, opener, closer): + """Index of the bracket that closes the one at i (quotes and backslashes respected); the end if none does.""" + t, n, depth = self.t, self.n, 0 + while i < n: + c = t[i] + if c == '\\': + i += 2 + continue + if c == "'": + j = t.find("'", i + 1) + i = n if j < 0 else j + 1 + continue + if c == '"': + i += 1 + while i < n and t[i] != '"': + i += 2 if t[i] == '\\' else 1 + i += 1 + continue + if c == opener: + depth += 1 + elif c == closer: + depth -= 1 + if depth == 0: + return i + i += 1 + return n + + def docs(self, i): + """Read the heredoc bodies that start at line start i; the index after the last one.""" + t, n = self.t, self.n + for mark, cmd, quoted in self.pending: + start, body = i, [] + while i < n: + j = t.find('\n', i) + j = n if j < 0 else j + line, i = t[i:j], j + 1 + if line.strip() == mark.strip(): + break + body.append(line) + text = '\n'.join(body) + self.spans.append((start, min(i, n))) + cmd['docs'].append(text) + if not quoted: # an unquoted marker: the shell runs $(..) and `..` in the body + self.subs += self.expansions(text) + self.pending = [] + return i + + +def parse(text): + """(every simple command of the text, also those inside $(..) `..` <(..); the text without heredoc bodies; + names that get a value no reader can know; the pieces left unread at the 400-piece limit, which decide_text + refuses or marks unknown: never a shorter command list without saying so).""" + cmds, taint, queue, plain, done = [], set(), [text], None, 0 + while queue and done < 400: + lx = Lex(queue.pop(0)) + done += 1 + plain = lx.plain() if plain is None else plain + for c in lx.cmds: + c['sub'] = done > 1 # inside $(..), `..`, <(..): its output goes into another command + cmds += lx.cmds + taint |= lx.taint + queue += lx.subs + return cmds, plain, taint, queue + + +def word_text(w): + """The text of a word made of literal pieces only, else None.""" + return ''.join(p[1] for p in w) if all(p[0] == 'L' for p in w) else None + + +def split_assign(w, any_quoting=False): + """(name, '+' for +=, the value's pieces) when the word is NAME=value, else None. A shell wants NAME= bare; + declare/export/local take it quoted too (`declare "X=y"`).""" + lead = '' + for k, (kind, text, quoted) in enumerate(w): + if kind != 'L' or (not any_quoting and (k or quoted)): + return None + name, eq, rest = text.partition('=') + if not eq: + lead += text + continue + m = re.fullmatch(r'([A-Za-z_]\w*)(\+?)', lead + name) + if not m: + return None + return m.group(1), m.group(2), ([('L', rest, quoted)] if rest else []) + list(w[k + 1:]) + return None + + +def runs_unseen_code(texts): + """Whether eval, source, `.` or trap is the command (or a wrapper before it), not one of its arguments: + `git add .` and `--jq .` set no variables.""" + lit = [HID if x is None else x for x in texts] + h, _ = head(lit) + return any(os.path.basename(x) in ('eval', 'source', '.', 'trap') for x in (lit if h is None else lit[:h + 1])) + + +def variables(cmds, taint): + """What the text says about its variables. vals: name -> every value it gets anywhere in the text, as (from a + `for`, pieces). Not by order: a name set twice has two values and both are tried, so a harmless first value + hides nothing. Any word that looks like NAME=value counts (also after `then`, `do`, `env`). Names set from + data (read, +=, arrays, unset) are left out, so they read as hidden. open: other code may set any name (eval, + source, trap, declare -n), so every name is also tried as hidden. standalone: names set for the commands that + follow (`X=y`, `export X=y`), not only for one command (`X=y cmd`).""" + vals, taint, open_world, standalone = {}, set(taint), False, set() + for c in cmds: + ws = c['words'] + texts = [word_text(w) for w in ws] + setter = any(x in SETTERS for x in texts) + found = [a for a in (split_assign(w, setter) for w in ws) if a] + for name, plus, value in found: + vals.setdefault(name, []).append((False, value)) + if plus: + taint.add(name) + if setter or len(found) == len(ws): + standalone.add(name) + for n, x in enumerate(texts): + if x == 'for' and n + 1 < len(ws): + name = texts[n + 1] + if name and NAME.fullmatch(name) and n + 2 < len(ws) and texts[n + 2] == 'in': + vals.setdefault(name, []).extend((True, w) for w in ws[n + 3:]) + elif name: + taint.add(name) + if x in TAINTERS and (x != 'printf' or '-v' in texts): + taint.update(y for y in texts[n + 1:] if y and NAME.fullmatch(y)) + if runs_unseen_code(texts) or \ + (setter and any(x and re.fullmatch(r'-[A-Za-z]*n[A-Za-z]*', x) for x in texts)): + open_world = True + return {'vals': {n: v for n, v in vals.items() if n not in taint}, 'open': open_world, + 'set': set(vals) | taint, 'standalone': standalone} + + +def var_texts(name, env, stack=()): + """Every text $name can be; HID for what cannot be known.""" + vals = env['vals'] + if name not in vals or name in stack or len(stack) > 4: + base = env.get('base', {}).get(name) # $HOME as the hook got it, when the text never sets it + if base and name not in env['set'] and not hidden(base): + return [base, HID] if env['open'] else [base] + return [HID] + out = [] + for from_for, value in vals[name]: + texts = [''] + if from_for and any(not q and (k != 'L' or re.search(r'[{}*?\[]', t)) for k, t, q in value): + texts = [HID] # for x in $LIST *.sh {a,b}: the shell makes the values, they are not in the text + value = () + for kind, text, _ in value: + opts = [text] if kind == 'L' else var_texts(text, env, stack + (name,)) if kind == 'V' else \ + [WILD if kind == 'M' else HID] + texts = [a + b for a in texts for b in opts] + if len(texts) > 32: + return [HID] + out += [x for x in texts if x not in out] + if env['open'] and HID not in out: + out.append(HID) + return out if len(out) <= 32 else [HID] + + +# Quoted text and $X values take no part in {a,b} expansion, quoted text also none in * ? [..] matching: their +# characters are swapped for private ones while a word is put together, and swapped back when it is done. +SHIELD_QUOTED = str.maketrans('{},.*?[', '') +SHIELD_VALUE = str.maketrans('{},.', '') +UNSHIELD = {v: k for k, v in SHIELD_QUOTED.items()} +GLOB = re.compile(r'[*?]|\[[^\]\s]+\]') +IFS = ' \t\n' + + +def finish(tok, wild): + """A word, once put together: an unquoted {a,b} or * ? [..] becomes hidden text (the shell fills it in from + the folder), and the word gets the WILD mark when it may come out as several words or as none.""" + while True: + tok, k = BRACE.subn(HID, tok) + if not k: + break + wild = True + if GLOB.search(tok): + wild = wild or GLOB.match(tok) is not None # a leading * can match a file named like a flag + tok = GLOB.sub(HID, tok) + tok = tok.translate(UNSHIELD) + return tok + WILD if wild and WILD not in tok else tok + + +def expand_word(w, bind): + """The tokens one word becomes. Quoted text stays one piece. An unquoted $X with a known value is split at + blanks (at $IFS when the text sets it). Unknown text is HID inside the word; when it is unquoted the shell may + split it anywhere, so the word also gets the WILD mark: it may be no word at all, or several.""" + out, cur, has, wild = [], '', False, False + ifs = bind.get('IFS', IFS) + for kind, text, quoted in w: + if kind == 'L': + cur += text.translate(SHIELD_QUOTED) if quoted else text + has = True + continue + val = WILD if kind == 'M' else HID if kind == 'H' else bind.get(text, HID) + if quoted or kind == 'M': + cur += val.translate(SHIELD_QUOTED) + has = True + continue + if hidden(val) or hidden(ifs): + cur += val.translate(SHIELD_VALUE) + has = wild = True + continue + for k, part in enumerate(re.split('[' + re.escape(ifs) + ']+', val) if ifs else [val]): + if k and has: + out.append(finish(cur, wild)) + if k: + cur, has, wild = '', False, False + if part: + cur += part.translate(SHIELD_VALUE) + has = True + if has: + out.append(finish(cur, wild)) + return out + + +def readings(cmd, env): + """The token lists a command can be: one per combination of the values its variables have in the text.""" + names = [] + for w in cmd['words']: + names += [p[1] for p in w if p[0] == 'V' and p[1] not in names] + if names and 'IFS' in env['set'] and 'IFS' not in names: + names.append('IFS') + opts, total = [], 1 + for name in names: + o = var_texts(name, env) + if name == 'IFS': # also the value it has before the text sets it + o = [IFS] + [x for x in o if x != IFS] + if total * len(o) > MAX_READINGS: + o = [HID] + total *= len(o) + opts.append(o) + out = [] + for combo in itertools.product(*opts): + bind, toks = dict(zip(names, combo)), [] + for w in cmd['words']: + toks += expand_word(w, bind) + out.append(toks) + return out + + +def segments(cmd): + """One token list per simple command. gh-as (an app-token wrapper of gh) relies on this: its text has + one word per gh argument, and each must stay one token here.""" + cmds, _, taint, _ = parse(cmd) + env = variables(cmds, taint) + return [r[0] for r in (readings(c, env) for c in cmds) if r[0]] + + +def quote(tok): + return "'" + tok.replace("'", "'\\''") + "'" + + +def is_assign(tok): + return re.match(r'^[A-Za-z_]\w*(\[[^\]]*\])?=', tok) is not None + + +def is_dur(tok): + return re.match(r'^\d+(\.\d+)?[smhd]?$', tok) is not None or tok == '{}' + + +def head(toks): + """(index of the command word after assignments and wrappers, which of shell/eval/xargs wrapped it).""" + i, via, prev_flag, script_next = 0, set(), False, False + while i < len(toks): + t = toks[i] + base = os.path.basename(t) + if prev_flag: + prev_flag = False + elif is_assign(t) or t in ('export', 'local', 'declare'): + pass + elif t == 'function': # function NAME { .. + i += 1 + # A wrapper only under its own name or in a system folder (`./sudo` is a file of the project), and not as + # the word a shell takes as its script (`bash nice` runs the file `nice` of the folder). + elif base in WRAPPERS and not script_next and ('/' not in t or os.path.dirname(t) in STD_BINS): + if base in SHELLS or base in ('source', '.'): + via.add('shell') + script_next = base != 'busybox' + if base in ('eval', 'xargs'): + via.add(base) + elif t.startswith('-'): + prev_flag = t in ARG_FLAGS + elif is_dur(t): + pass + elif base == 'uv' and i + 1 < len(toks) and toks[i + 1] == 'run': + i += 1 + via.add('shell') + else: + return i, via + i += 1 + return None, via + + +def positional(args, valflags): + out, i = [], 0 + while i < len(args): + a = args[i] + if a in valflags: + i += 2 + continue + if not a.startswith('-'): + out.append(a) + i += 1 + return out + + +# ---------- guarded paths + +def forms(tok): + """The spellings of a path a server may take as the same: percent-decoded, /./ and /x/../ resolved.""" + out, t = [tok], tok + for _ in range(3): + u = unquote(t) + if u == t: + break + out.append(u) + t = u + for s in list(out): + r = re.sub(r'(? last) + if si > last: + return False + if pat[pi] is ...: + return any(go(sj, pi + 1, seen) for sj in range(si + 1, last + 2)) + s = segs[si] + if not can(s, pat[pi]): + return False + if not hidden(s): + return go(si + 1, pi + 1, seen or pat[pi] is not None) + seen = seen or (pat[pi] is not None and len(s.replace(HID, '').replace(WILD, '')) >= 3) + return any(go(si + 1, pj, seen) for pj in range(pi + 1, len(pat) + 1)) + + return any(go(i, 0, False) for i in range(len(segs))) + + +def hits(tok, kind): + """2: the word spells the guarded path; 1: hidden text in it could complete it; 0: neither.""" + rx, pats = GUARDED[kind] + best = 0 + for f in forms(tok): + if rx.search(f): + return 2 + g = PLACEHOLDER.sub(HID, f) + if hidden(g): + path = re.split(r'[?#]', re.sub(r'^[a-z][a-z0-9+.-]*://[^/]*', '', g, flags=re.I), maxsplit=1)[0] + segs = [x.lower() for x in path.split('/') if x] + if any(seg_match(segs, pat, more) for pat, more in pats): + best = 1 + return best + + +def far_hits(tok, kind): + """hits() for the word as written and as the far end may read it (\\uXXXX, %XX and backslashes decoded).""" + best = hits(tok, kind) + if best < 2 and ('\\' in tok or '%' in tok): + best = max(best, hits(canon(tok), kind)) + return best + + +def visible_path(tok): + """Whether a path shows any text at all besides hidden parts and gh placeholders.""" + return re.search(r'[A-Za-z0-9]', PLACEHOLDER.sub('', tok).replace(HID, '').replace(WILD, '')) is not None + + +GRAPHQL_END = re.compile(r'(^|/)graphql/?$', re.I) + + +def may_be_graphql(tok): + """Whether a `gh api` path can be the GraphQL endpoint: it ends in `graphql` in some spelling, hidden text in + it can complete that word, or it shows no text at all. `repos/o/r/issues/comments/$id` cannot.""" + if not visible_path(tok): + return True + for f in forms(PLACEHOLDER.sub(HID, tok)): + path = re.split(r'[?#]', re.sub(r'^[a-z][a-z0-9+.-]*://[^/]*', '', f, flags=re.I), maxsplit=1)[0] + if GRAPHQL_END.search(path.rstrip(HID + WILD)): + return True + if hidden(path) and seg_match([x.lower() for x in path.split('/') if x], ['graphql'], False): + return True + return False + + +def certain_path(args): + """The path of a `gh api` call the guard cannot read fully, when the path itself is still certain: every word + before the first word that is no flag reads cleanly, and that word starts with plain text. gh api takes exactly + one path, so hidden text after it can add flags but cannot swap the path. None when it is not certain.""" + if len(args) > 200: + return None + for i, a in enumerate(args): + _, pos, bad = api_parse(args[:i] + ['x']) + if bad or len(pos) > 1: + return None + if pos == ['x']: # this word is no flag value + if a.startswith('-') and api_parse(args[:i] + ['--include'])[1] != ['--include']: + continue # a flag + return None if a[:1] in ('', HID, WILD) else a + return None + + +def override_header(value): + """Whether a header (key:value) may change the request method on the server.""" + name = value.partition(':')[0] + return hidden(name) or 'method' in name.lower() + + +# ---------- gh + +def looks_risky(text): + """Whether text that is no command line (a config, a request body) mentions what this guard refuses.""" + t = re.sub(r'["\'\\]', '', text or '') + return LOOSE_RE.search(t) is not None or GQL_RE.search(t) is not None + + +def yaml_text(s): + s = s.strip() + if len(s) > 1 and s[0] == s[-1] == "'": + return s[1:-1].replace("''", "'") + if len(s) > 1 and s[0] == s[-1] == '"': + return ansi_c(s[1:-1]) + return s + + +def gh_config(ctx): + """(the gh aliases [(the words of the name, the expansion)], whether a config may hold an alias this reader + missed) from the gh config of the hook's environment and of every config folder the command text points gh + at (GH_CONFIG_DIR=.. gh ..). A name can be several words (`pr wd` is `gh pr wd`).""" + env = ctx['env'] + dirs = [env.get('GH_CONFIG_DIR') or os.path.join(env.get('XDG_CONFIG_HOME') or os.path.join( + env.get('HOME', os.path.expanduser('~')), '.config'), 'gh')] + list(ctx.get('cfg', ())) + memo, key = ctx.setdefault('memo', {}), ('gh config', tuple(dirs)) + if key not in memo: + memo[key] = gh_config_cached(dirs, ctx) + return list(memo[key][0]), memo[key][1], memo[key][2] + + +YAML_KEY = r"""(?:[A-Za-z0-9_][\w .-]*?|'[^'\\]*'|"[^"\\]*")""" +YAML_ODD = re.compile(r'[!&*{\[|>?%@`"\']|- |:(?:\s|$)') # the start of a value this reader does not follow + + +def yaml_value_plain(v): + """Whether the value on a key's line is one of the few forms the reader below reads the way gh does: plain + text, one quoted text ('..' or ".." with \\\\ \\" \\n \\t only), or the start of a | or > block.""" + v = v.strip() + if not v or re.fullmatch(r'[|>][+-]?\d*', v): + return True + if v[0] in '"\'': + return re.fullmatch(r"'(?:[^']|'')*'" + '|' + r'"(?:[^"\\]|\\[\\"nt])*"', v) is not None + return not YAML_ODD.match(v) + + +def odd_yaml(text): + """Whether a gh config holds YAML outside the small subset the reader below follows: tags (`!!str`), `? ` keys, + anchors and `*` references, flow maps, escapes in keys, quoted values over several lines, tabs, `---`. The + guard does not try to read more YAML; it refuses a gh word that may be an alias from such a config.""" + top = inside = block = False + base = None + for line in text.splitlines(): + if not line.strip() or line.lstrip().startswith('#'): + continue + indent = len(line) - len(line.lstrip()) + if '\t' in line[:indent]: + return True + if not indent: + m = re.fullmatch(r'(%s)\s*:(?:\s+(.*))?\s*' % YAML_KEY, line) + if not m or not yaml_value_plain(m.group(2) or ''): + return True + value = (m.group(2) or '').strip() + top, inside, base, block = True, m.group(1).strip('"\'') == 'aliases', None, value[:1] in ('|', '>') + if inside and value: # aliases: {..}, aliases: *x + return True + elif not top: # the whole map is indented: the reader below looks for `aliases:` at the line start + return True + elif not inside or (block and base is not None and indent > base): + continue + elif base is None or indent <= base: + m = re.fullmatch(r'\s+(%s)\s*:(?:\s+(.*))?\s*' % YAML_KEY, line) + if not m or not yaml_value_plain(m.group(2) or '') or (base is not None and indent != base): + return True + base, block = indent, (m.group(2) or '').strip()[:1] in ('|', '>') + elif YAML_ODD.match(line.strip()): # a plain value that goes on in the next line + return True + return False + + +def gh_config_now(dirs): + out, risky, odd = [], False, False + for cfg in dict.fromkeys(dirs): + path = os.path.join(cfg, 'config.yml') + text = read_text(path) + if text is None: + risky = risky or os.path.exists(path) # too big, binary, no file: it cannot be read here, gh can + continue + found, inside, cur, base = [], False, None, 0 + for line in text.splitlines(): + m = re.match(r'^(["\']?)aliases\1\s*:\s*(.*)$', line) + if m: + inside, cur = True, None + for k, v in re.findall(r'["\']?([^,{}:"\']+)["\']?\s*:\s*([^,{}]*)', m.group(2)): # aliases: {a: b} + found.append([k.split(), yaml_text(v)]) + continue + if not inside or not line.strip() or line.lstrip().startswith('#'): + continue + if not line.startswith((' ', '\t')): + inside = False + continue + indent = len(line) - len(line.lstrip()) + m = re.match(r'^\s+(["\']?)([^:"\']+?)\1\s*:(?:\s+(.*)|\s*)$', line) + if m and (cur is None or indent <= base): + base, value = indent, (m.group(3) or '').strip() + cur = [m.group(2).split(), '' if re.fullmatch(r'[|>][+-]?\d*', value) else yaml_text(value)] + found.append(cur) + elif cur is not None: # a value on the next lines (| and > blocks) + cur[1] = (cur[1] + '\n' + line.strip()).strip() + out += [(w, e) for w, e in found if w] + risky = risky or (looks_risky(text) and not any(looks_risky(e) for _, e in found)) + odd = odd or odd_yaml(text) + return out, risky, odd + + +def alias_forms(exp): + """An alias text as written and with its line breaks as blanks (a YAML `>` block folds them; gh splits a + plain alias at any blank).""" + exp = exp.strip() + return list(dict.fromkeys([exp, ' '.join(exp.split())])) + + +def alias_text_reason(exp, ctx): + for x in alias_forms(exp): + # the bare text is read as a command too (a `!` the reader lost); its words are no command of this text, + # so it has its own flow and no gate on unknown words + r = decide_text(x[1:], ctx) if x.startswith('!') else \ + decide_text('gh ' + x, ctx) or decide_text(x, dict(ctx, flow={}, nogate=True)) + if r: + return r + return None + + +def sub_candidates(args, value_flags=('-R', '--repo'), switches=('--help', '--version', '-h')): + """Indexes of the words that may be the subcommand. cobra takes the first word that is no flag and no flag + value, and which flags take a value depends on the command, so after a flag this table does not know both + readings count; a hidden word may be a flag too.""" + out, value, maybe = [], False, False + for i, a in enumerate(args): + if value: + value = False + continue + if a.startswith('-') and len(a) > 1: + value = a in value_flags + maybe = not value and a not in switches and '=' not in a + continue + out.append(i) + if not maybe and not hidden(a): + break + maybe = False + return out + + +def gh_reason(args, ctx, sure=True): + """Why these gh arguments are refused, or None. sure: the command word is `gh` for certain (not a hidden + word or a shell function that may be gh).""" + top = sure and ctx['depth'] == 0 + cands = sub_candidates(args) + says = re.search(r'disable|actions/permissions', re.sub(r'["\'\\]', '', ctx.get('all') or ''), re.I) + # A config folder nobody can read here may hold any alias. An alias cannot take the name of a gh command, so + # `GH_CONFIG_DIR=$(mktemp -d) gh pr list` passes; a word that is no gh command may be an alias. + if top and ctx.get('cfg_hidden') and cands and (says or args[cands[0]] not in GH_COMMANDS): + return reason('`gh` with a config folder the guard cannot read (GH_CONFIG_DIR, XDG_CONFIG_HOME or HOME ' + 'set from a variable or command output) and a word that is no gh command, or in a command ' + 'that names `disable` or `actions/permissions`: the folder may hold an alias that disables ' + 'Actions', 'Write the folder out in the command.') + if top and cands and hidden(args[cands[0]]) and says: + return reason('`gh` with a subcommand the guard cannot read (an array, a variable, "$@"), in a command ' + 'that also names `disable` or `actions/permissions`', UNREADABLE) + for i in cands: + sub, after = args[i], args[i + 1:] + guess = hidden(sub) # `gh "$X" ..`: X may be workflow or api + for name in (('workflow', 'api', 'alias') if guess else (sub,)): + r = gh_sub_reason(name, args[:i] + after, after, ctx, guess, top) + if r: + return r + aliases, risky, odd = gh_config(ctx) + aliases += ctx.get('gh_set', []) + sub_ctx = dict(ctx, depth=ctx['depth'] + 1) + first = args[cands[0]] if cands else '' + if ctx['depth'] >= MAX_DEPTH: # too deep to expand an alias: what it stands for is read only for tokens + if not first or first in GH_COMMANDS: + return None + exps = [e for _, e in aliases] + if risky or odd or any(hidden(e) for e in exps): + return reason(f'`gh {redact(first)}` may be an alias, in a script that scripts run, too deep for the ' + 'guard to expand, and the gh config is one it cannot read in full') + return stopped('\n'.join(exps), f'`gh {redact(first)}` may be an alias that names disabling Actions, in a ' + 'script that scripts run, too deep for the guard to expand', ctx['flow']) + for words, exp in aliases: + if words is None: # an alias of any name + if not first or first in GH_COMMANDS: + continue + j = cands[0] + else: + at = 0 + for j, a in enumerate(args): + if spells(a, words[at]): + at += 1 + if at == len(words): + break + else: + continue + rest = ' '.join(quote(a) for a in args[j + 1:]) + if any(decide_text(x[1:] if x.startswith('!') else f'gh {x} {rest}', sub_ctx) for x in alias_forms(exp)): + return reason(f'the gh alias `{" ".join(words or ["?"])}` expands to a command that disables Actions') + if risky and sure and first and first not in GH_COMMANDS: # also when it is an alias this reader did find + return reason(f'`gh {redact(first)}` is no gh command, and the gh config holds text about disabling Actions ' + 'that the guard cannot read as an alias', 'Tell the owner: the gh config needs a look.') + if odd and sure and first and first not in GH_COMMANDS: + return reason(f'`gh {redact(first)}` is no gh command, and the gh config holds YAML the guard does not read ' + '(a tag like `!!str`, a `? ` key, an anchor, a flow map, an escape in a key ..), so the word ' + 'may be an alias the guard cannot see', 'Tell the owner: the gh config needs a look.') + return None + + +def gh_sub_reason(sub, rest, after, ctx, guess, top): + if sub == 'workflow': + for j in sub_candidates(after): + if after[j] == 'disable': + return reason('`gh workflow disable` disables a GitHub Actions workflow') + if hidden(after[j]) and spells(after[j], 'disable') and not guess: + return reason('`gh workflow` with a subcommand the guard cannot read (it may be `disable`)', + UNREADABLE) + return None + if sub == 'api': + return api_reason(rest, ctx, top) + if sub == 'alias': + verb = [a for a in after if not a.startswith('-')][:1] + tail = after[after.index(verb[0]) + 1:] if verb else [] + pos = [a for a in tail if a == '-' or not a.startswith('-')] # --clobber and -s/--shell are switches + # blind: the call is not known to be `gh alias ` (a hidden word stands where `alias` or the verb + # would be), or it only prints help. Then only alias text that can be read and disables is refused. + blind = guess or not verb or hidden(verb[0]) or bool({'--help', '-h'} & set(tail)) + if verb and (verb[0] == 'set' or hidden(verb[0]) and not guess): + exp = ' '.join(pos[1:]) + if exp in ('-', ''): # the alias text comes on stdin + known = ctx.get('stdin') + if exp == '-' and not blind and (known is None or hidden(known) or SHELL_VALUE.search(known)): + return reason('`gh alias set .. -` with alias text the guard cannot read (a pipe, a file that ' + 'is not there yet, a variable)', 'Write the alias text out in the command.') + if (known is not None and alias_text_reason(known, ctx)) or looks_risky(stdin_texts(ctx)[0]): + return reason('`gh alias set` from stdin with an alias that disables Actions') + return None + if hidden(exp) and blind: + return None + if hidden(exp): + return reason('a gh alias with text the guard cannot read (a variable or command output)', + 'Write the alias text out in the command.') + if any(a == '--shell' or re.fullmatch(r'-[a-z]*s[a-z]*', a) for a in tail) and not exp.startswith('!'): + exp = '!' + exp + if alias_text_reason(exp, ctx): + return reason('a gh alias that disables Actions') + if verb and (verb[0] == 'import' or hidden(verb[0]) and not guess): + src = pos[0] if pos else '-' + text = ctx.get('stdin') if src == '-' else read_named(src, ctx) + if text is None and not blind: + return reason('`gh alias import` of a file or pipe the guard cannot read', + 'Import a file that is there before the command runs.') + for _, exp in yaml_aliases(text or ''): + if alias_text_reason(exp, ctx): + return reason('`gh alias import` of an alias that disables Actions') + if looks_risky(text if text is not None else ctx.get('raw')): # also what the lines above cannot read + return reason('`gh alias import` of text about disabling Actions') + return None + + +def yaml_aliases(text): + """[(the words of the name, the expansion)] of the `name: expansion` lines of a gh alias import file.""" + out = [] + for line in text.splitlines(): + m = re.match(r'^\s*(["\']?)([^:#"\']+)\1\s*:\s*(.*)$', line) + if m and m.group(2).split(): + out.append((m.group(2).split(), yaml_text(m.group(3)))) + return out + + +def text_aliases(toks, stdin, ctx): + """The gh aliases a command of the text sets up itself (`gh alias set`, `gh alias import`): they are not in the + gh config yet when the guard reads the text, and a later command of the same text may use them. A name of + None stands for any name (an import the guard cannot read).""" + for i, t in enumerate(toks): + if os.path.basename(t) != 'gh': + continue + rest = [a for a in toks[i + 1:] if a == '-' or not a.startswith('-')] + if rest[:2] == ['alias', 'set'] and len(rest) > 3: + exp = ' '.join(rest[3:]) + exp = (HID if stdin is None or SHELL_VALUE.search(stdin) else stdin) if exp == '-' else exp + shell = any(a == '--shell' or re.fullmatch(r'-[a-z]*s[a-z]*', a) for a in toks[i + 1:]) + return [(rest[2].split() or None, '!' + exp if shell and not exp.startswith('!') else exp)] + if rest[:2] == ['alias', 'import']: + src = rest[2] if len(rest) > 2 else '-' + text = stdin if src == '-' else read_named(src, ctx) + return [(None, HID)] if text is None else yaml_aliases(text) + return [] + + +def stdin_texts(ctx): + """What a command reads on stdin: its heredoc or <<< text; when it comes from a pipe or a file, the command + text itself stands in (what is piped in is most often written there).""" + return [ctx['stdin']] if ctx.get('stdin') is not None else [ctx.get('raw') or ''] + + +def file_or_text(path, ctx): + """A file the command names, or the command text when the file is not there to read (it may be written by + the same command).""" + text = read_named(path, ctx) + return ctx.get('raw') or '' if text is None else text + + +def api_parse(args): + """`gh api` arguments as gh's flag reader (pflag) takes them: (flags [(long name, value)], positionals, what + went wrong or ''). `--` ends the flags; `--name=value` or `--name value`; short flags join (`-iXPUT`), a short + flag's value is the rest of the word (`-XPUT`, `-X=PUT`) or the next word; a flag that takes a value takes the + next word whatever it looks like (`-p -XGET`: the preview is "-XGET").""" + flags, pos, bad = [], [], '' + if any(WILD in a for a in args): + bad = 'an unquoted variable or command output, which may add flags: put it in double quotes' + i, n = 0, len(args) + while i < n: + a = args[i] + i += 1 + if a == '--': + pos += args[i:] + break + if not a.startswith('-') or a == '-': + pos.append(a) + continue + if a.startswith('--'): + name, eq, val = a[2:].partition('=') + if hidden(name): + bad = bad or 'a flag name the guard cannot read' + elif name in API_SWITCH: + pass + elif name not in API_VALUE: + bad = bad or f'the flag --{redact(name)}, which gh api {GH_VERSION} does not have' + elif eq: + flags.append((name, val)) + elif i < n: + flags.append((name, args[i])) + i += 1 + else: + bad = bad or f'--{name} without its value' + continue + s = a[1:] + while s: + c, s = s[0], s[1:] + if c in API_SHORT_SWITCH: + s = '' if s[:1] == '=' else s # -i=false + continue + if c not in API_SHORT: + bad = bad or ('a flag the guard cannot read' if c in (HID, WILD) else + f'the flag -{c}, which gh api {GH_VERSION} does not have') + break + if len(s) > 1 and s[0] == '=': + val = s[1:] + elif s: + val = s + elif i < n: + val = args[i] + i += 1 + else: + bad = bad or f'-{c} without its value' + break + flags.append((API_SHORT[c], val)) + s = '' + return flags, pos, bad + + +def api_reason(args, ctx, top=False): + flags, pos, bad = api_parse(args) + if not bad and len(pos) > 1 and any(a[:1] in (HID, WILD) for a in pos): + bad = 'a hidden word that may be a flag' # `gh api "$X" path`: X may be -XPUT + exact = not bad + method, fields, inputs = None, [], [] + override = any('x-http-method-override' in a.lower() for a in args) + for name, val in flags: + if name == 'method': + method = val + elif name in ('field', 'raw-field'): + fields.append(val) + elif name == 'input': + inputs.append(val) + elif name == 'header' and override_header(val): + override = True + eff = 'POST' if method is None and (fields or inputs) else 'GET' if method is None else \ + '?' if hidden(method) else method.upper() + if override and eff in READS: + eff = 'POST' + write = not exact or eff not in READS + cands = pos if exact else args # an unreadable call: any word may be the path + how = f'a {eff} with' if exact and eff != '?' else 'a call the guard cannot read fully ' \ + f'({bad or "the method is hidden"}), so it counts as a write, with' + best = {k: max([far_hits(a, k) for a in cands] or [0]) for k in GUARDED} + if best['disable'] == 2 or (best['disable'] and write): + return reason('a call to the GitHub `.../actions/workflows//disable` endpoint' if best['disable'] == 2 + else f'{how} `gh api` to a path that hidden text can turn into `.../actions/workflows//' + 'disable`', '' if best['disable'] == 2 else UNREADABLE) + if best['perm'] and write: + if exact and eff == 'PUT' and not inputs and not override and len(pos) == 1 and REPO_PERM_RE.match(pos[0]) \ + and not hidden(pos[0]) and reenables(fields): + return None # re-enabling Actions for a repo + return reason(f'{how} `gh api` to GitHub `.../actions/permissions` (turns Actions off or limits it)', + '' if exact and best['perm'] == 2 and eff != '?' else UNREADABLE) + if write: + srcs = [('', s) for s in inputs] + [(k + '=', v[1:]) for k, _, v in (f.partition('=') for f in fields) + if v.startswith('@')] # -F key=@file reads the value from a file + known = [(pre, ctx.get('stdin') if s == '-' else read_named(s, ctx)) for pre, s in srcs] + unread = any(b is None or hidden(b) for _, b in known) + # a file that is not there yet is often written by the same command, so its text is in the command + bodies = [ctx.get('raw') or '' if b is None else pre + b.strip() for pre, b in known] + seen = [canon(x) for x in list(args) + bodies] # as the far end reads them: \u0064isabled is disabled + if best['protect'] and (not exact or eff in ('DELETE', '?')): + return reason(f'{how} `gh api` to branch protection or a ruleset: a DELETE there removes the rules ' + 'that keep `main` behind CI and review (changing them with PUT/PATCH/POST is not ' + 'refused)', '' if exact and eff == 'DELETE' else UNREADABLE) + if best['ruleset'] and (any(re.fullmatch(r'enforcement=(disabled|.*[%s%s].*)' % (HID, WILD), f, re.S) + for f in fields) + or any(RULESET_OFF.search(x) for x in seen)): + return reason(f'{how} `gh api` that switches a ruleset off (enforcement=disabled)') + if best['ruleset'] and unread: + return reason(f'{how} `gh api` to a ruleset with a body the guard cannot read (a pipe, a file that is ' + 'not there yet, a file named by a variable): it may switch the ruleset off', + 'Write the body to a file in a command before this one and name the file in full.') + # GraphQL only when the path can be the GraphQL endpoint: a comment posted to `repos/o/r/issues/$n/comments` + # with its text from a file named by a variable is no GraphQL call + path = certain_path(args) + gql = any(may_be_graphql(a) for a in pos) if exact else path is None or may_be_graphql(path) + if gql and any(GQL_RE.search(x) for x in seen): + return reason('a GraphQL mutation that deletes branch protection or a ruleset') + if gql and any(GQL_UPDATE.search(x) for x in seen) and (unread or any('disabled' in x for x in seen)): + return reason('a GraphQL updateRepositoryRuleset that switches the ruleset off (enforcement: DISABLED), ' + 'or one with a body the guard cannot read') + if gql and unread: + return reason('a GraphQL call with a body the guard cannot read (a pipe, a file that is not there yet, ' + 'a file named by a variable): it may delete branch protection or a ruleset', + 'Write the query to a file in a command before this one and name the file in full.') + if top and HIDDEN_PATH_RULE and write and (eff not in READS or any(WILD in a for a in args)) \ + and not any(visible_path(a) for a in pos): + return reason(f'{how} `gh api` to a path that is hidden altogether (a variable or command output), so the ' + 'guard cannot tell it from the Actions settings', UNREADABLE) + return None + + +def reenables(fields): + """Whether gh api fields are exactly `enabled=true`, with at most `allowed_actions=all`.""" + seen = set() + for f in fields: + k, _, v = f.partition('=') + if hidden(f) or (k, v) not in (('enabled', 'true'), ('allowed_actions', 'all')): + return False + seen.add(k) + return 'enabled' in seen + + +# ---------- curl, wget, httpie + +def net_reason(word, args, ctx): + """curl, wget, httpie and the like next to a guarded path. Only a call that is plainly a read passes: the + tool's known read-only flags and nothing the guard cannot read. (Each tool reads flags its own way, so there + is one table per tool, and a tool without a table may carry no flags at all.)""" + best = {k: max([far_hits(a, k) for a in args] or [0]) for k in GUARDED} + if best['disable'] == 2: + return reason('a call to the GitHub `.../actions/workflows//disable` endpoint') + if not (best['disable'] or best['perm'] or best['protect']): + return None + paths = [a for a in args if any(far_hits(a, k) for k in GUARDED)] + if plain_read(NET_TOOLS.get(word), args, paths): + return None + if best['perm'] or best['disable']: + return reason('a request to GitHub `.../actions/permissions` (or to a path that hidden text can turn into ' + 'a guarded one) that is not plainly a read: it may turn Actions off or limit it', + 'A read passes with the tool\'s own config off and read-only flags only: `curl -q -sS -L ' + '-f -H .. -o ..` (-q first), `wget --no-config -q -O ..`.') + if any('DELETE' in a.upper() or hidden(a) for a in args if a not in paths): + return reason('a DELETE (or a request the guard cannot read) to branch protection or a ruleset: it removes ' + 'the rules that keep `main` behind CI and review') + if best['ruleset']: # a body that switches the ruleset off, written out or in a file (-d @file) + files = [m.group(1) for a in args for m in [re.search(r'@([^@=\s]+)$', a)] if m and a not in paths] + texts = [read_named(f, ctx) for f in files] + if any(t is None or RULESET_OFF.search(canon(t)) for t in texts) \ + or any(RULESET_OFF.search(canon(a)) for a in args): + return reason('a request that switches a ruleset off (enforcement=disabled), or one to a ruleset with a ' + 'body file the guard cannot read') + return None + + +def plain_read(tool, args, paths): + """Whether the arguments are a read for certain: the path, GET/HEAD, and flags from the tool's table.""" + switches, values, methods, short_switches, short_values, short_method, eq = tool or NO_FLAGS + i, n = 0, len(args) + + def value(joined=None): # a value that looks like a flag is refused: the tool may read it as one + nonlocal i + if joined is None: + i += 1 + joined = args[i - 1] if i <= n else None + return None if joined is None or (joined.startswith('-') and len(joined) > 1) else joined + + while i < n: + a = args[i] + i += 1 + if a in paths or (a.upper() in READS and not tool): # httpie: `http GET url` + continue + if not a.startswith('-') or a == '-' or hidden(a) and WILD in a: + return False + if a.startswith('--'): + name, has_eq, val = a.partition('=') + if name in switches and not has_eq: + continue + if (name not in values and name not in methods) or (has_eq and not eq): + return False + val = value(val if has_eq else None) + if val is None or hidden(val) and name in methods or (name in methods and val.upper() not in READS) \ + or (name == '--header' and override_header(val)): + return False + continue + s = a[1:] + while s: + c, s = s[0], s[1:] + if c in short_switches: + continue + if c not in short_values and c != short_method: + return False + val, s = value(s or None), '' + if val is None or (c == short_method and val.upper() not in READS) or (c == 'H' and override_header(val)): + return False + return True + + +# ---------- code and script files + +def read_text(path): + """A file's text; None for no file, a file over MAX_FILE, an error and a binary (NUL in the first 8 KB). Where a + shell or interpreter runs the file, file_token() and unread() tell those apart.""" + if not path or not os.path.isfile(path): + return None + try: + if os.path.getsize(path) > MAX_FILE: + return None + with open(path, 'rb') as f: + data = f.read() + except OSError: + return None + if b'\0' in data[:8192]: + return None + return data.decode('utf-8', 'replace') + + +def file_token(path): + """The guarded token a file names, also in a file over MAX_FILE (read in 1 MB pieces that overlap by 4 KB). None + when it names none, is not there or is a compiled binary (a NUL in the first 8 KB: today's pass); a file the + guard cannot read at all (an error, over HARD_FILE) counts as naming one.""" + text = read_text(path) + if text is not None: + return named(text) + try: + if not path or not os.path.isfile(path): + return None + with open(path, 'rb') as f: + if b'\0' in f.read(8192): + return None + if os.path.getsize(path) > HARD_FILE: + return TOO_BIG + f.seek(0) + tail = '' + while True: + piece = f.read(1 << 20) + if not piece: + return None + s = tail + piece.decode('utf-8', 'replace') + tok = named(s) or (LOOSE_RE.search(s) and 'disabling Actions') + if tok: + return tok + tail = s[-4096:] + except OSError: + return NO_OPEN + + +def unread(path, any_file=True): + """Why a file that a shell or interpreter is about to run, and that read_text() could not give in full, is + refused; None for no file, a compiled binary and a big file that names no token anywhere. any_file=False: only + a file that looks like a script (its name, a `#!` line, the executable bit); data passes as before.""" + if not path or read_text(path) is not None or not os.path.isfile(path) or not (any_file or script_like(path)): + return None + tok, name, mb = file_token(path), redact(os.path.basename(path)), MAX_FILE // 1_000_000 + if tok == NO_OPEN: + return reason(f'the file {name} is about to run, and the guard cannot open it to read it', 'Make it readable.') + return tok and reason(f'the file {name} is about to run, and the guard reads files whole only up to {mb} MB: ' + + (f'it is {tok}' if tok == TOO_BIG else f'read in pieces, it names {tok}'), + f'Split the file, or run the part you need from a file under {mb} MB.') + + +def script_like(path, unopened=True): + """A file that looks like a script (its name, the executable bit, a `#!` line) and is no compiled binary. + unopened: the answer for a file the guard cannot open (True where a shell or interpreter runs it).""" + try: + with open(path, 'rb') as f: + head = f.read(8192) + except OSError: + return unopened + return b'\0' not in head and (head[:2] == b'#!' or path.endswith(SHELL_EXT + CODE_EXT) or os.access(path, os.X_OK)) + + +def resolve_path(tok, cwd): + tok = os.path.expanduser(tok) + return os.path.normpath(tok if os.path.isabs(tok) else os.path.join(cwd, tok)) + + +def folders(ctx): + """The folders a command of the text may run in: the hook's, and every one the text moves to with `cd`.""" + return ctx.get('cwds') or [ctx['cwd']] + + +def read_named(tok, ctx): + """The text of a file the command names, looked for in every folder the command may run in; None when it is + hidden, not there or no text.""" + if hidden(tok): + return None + for d in folders(ctx): + text = read_text(resolve_path(tok, d)) + if text is not None: + return text + return None + + +def named_file(tok, ctx): + """file_token() of a file the command names, in every folder the command may run in.""" + return None if hidden(tok) else next((t for d in folders(ctx) for t in [file_token(resolve_path(tok, d))] if t), + None) + + +def resolve_cmd(tok, ctx, via_shell): + """The script file a command word runs: through a shell/source any file, else only an executable one.""" + if '/' in tok: + p = resolve_path(tok, ctx['cwd']) + return p if via_shell or (os.path.isfile(p) and os.access(p, os.X_OK)) else None + if via_shell: + p = resolve_path(tok, ctx['cwd']) + if os.path.isfile(p): + return p + for d in home_path_dirs(ctx['env'].get('PATH') or '', ctx['env'].get('HOME') or os.path.expanduser('~')): + p = os.path.join(d, tok) + if os.path.isfile(p) and os.access(p, os.X_OK): + return p + return None + + +_HOME_DIRS = {} + + +def home_path_dirs(path, home): + """PATH entries under $HOME (computed once: realpath on every entry for every segment was slow).""" + key = (path, home) + if key not in _HOME_DIRS: + h = os.path.realpath(home) + os.sep + _HOME_DIRS[key] = [d for d in path.split(':') if d and os.path.realpath(d).startswith(h)] + return _HOME_DIRS[key] + + +def file_reason(path, ctx, force_shell=False): + if not path or os.path.realpath(path) == SELF: + return None # the guard's own text is full of what it refuses + # One answer per file and setting: a script that calls its helpers fifty times is read once, not fifty times. + memo = ctx.setdefault('memo', {}) + key = (path, force_shell, ctx['depth'], tuple(folders(ctx)), tuple(ctx.get('cfg', ())), + bool(ctx.get('cfg_hidden')), repr(ctx.get('gh_set', ()))) + if key not in memo: + memo[key] = None # a script that runs itself: the run that is being read already answers for it + memo[key] = deep_reason(path, ctx) if ctx['depth'] >= MAX_DEPTH else file_reason_now(path, ctx, force_shell) + return memo[key] + + +def deep_reason(path, ctx): + """A script too deep to read as shell: it and the scripts it names are read for tokens only; anything further + counts as a program the guard does not know. A file it names that cannot be opened is no script here.""" + text = read_text(path) + near = {resolve_path(w, d) for w in re.findall(r'[\w.~/+-]+', text or '') for d in folders(ctx)} - {path} + hit = next((q for q in sorted(near) if os.path.isfile(q) and os.path.realpath(q) != SELF and + script_like(q, unopened=False) and file_token(q)), None) + what = 'a script that scripts run, too deep for the guard to read' + return unread(path) or (hit and reason(f'{what} ({redact(os.path.basename(path))}) names the script ' + f'{redact(os.path.basename(hit))}, which names a guarded token', + 'Run the inner script as a command of its own.')) or \ + stopped(text or '', what, ctx['flow'], 'Run the inner script as a command of its own.') + + +def file_reason_now(path, ctx, force_shell): + f = facts(path, ctx) + if not f['text']: # an interpreter's file counts only when it looks like a script (lockout care for data) + return unread(path, any_file=force_shell) + if f['own']: + return None + shellish = force_shell or path.endswith(('.sh', '.bash', '.zsh')) or f['bang'] in SHELLS + if not shellish: + f = facts(path, ctx, ('named',)) + if not f['text']: # changed under the guard since it was cached + return unread(path, any_file=force_shell) + tok = f['named'] + return tok and reason(f'{redact(os.path.basename(path))}: a script that names {tok}. The guard reads shell ' + 'scripts only, not code in other languages, so it cannot prove this one is harmless', + CODE_HINT + ' Run tests of this guard through a test runner that is handed their folder.') + text = body(path, ctx) + if text is None: + return unread(path, any_file=force_shell) + sub_ctx = dict(ctx, depth=ctx['depth'] + 1, raw=text, nest=0) + inner = decide_text(text, sub_ctx, scan_raw=False) + if inner: # say what in the script is refused, not only that something is + what = inner[len(PREFIX):] if inner.startswith(PREFIX) else inner + return PREFIX + f'the script {os.path.basename(path)} holds: {what}' + return None + + +_OWN = [] + + +def own_text(): + """The guard's own text: a copy that is the same byte for byte (the repo copy next to the installed one) is the + guard, not a script that disables Actions.""" + if not _OWN: + _OWN.append(read_text(SELF) if SELF else None) + return _OWN[0] + + +def shebang(text): + """The program a `#!` first line names (`#!/usr/bin/env -S python3 -I` is python3), '' without one.""" + first = text.split('\n', 1)[0] + if not first.startswith('#!'): + return '' + parts = first[2:].split() + if parts and os.path.basename(parts[0]) == 'env': + parts = [x for x in parts[1:] if not x.startswith('-') and '=' not in x] + return os.path.basename(parts[0]) if parts else '' + + +# ---------- the cache: what files say, kept 60 s between hook runs + +# One file per user: {"v": CACHE_VERSION, "guard": the stat of this guard file, "files": {path: entry}, "gh": {dirs: +# entry}}. A file entry: {"sig": [dev, inode, size, mtime_ns, ctime_ns], "t": unix time of the reading, "text": true, +# "own": byte-equal to this guard, "bang": the `#!` program or null without a `#!` line, "named": the guarded token +# it names or null (only once it was looked for)}. A gh entry: {"sig": [the sig or null (no file) per config.yml], +# "t", "aliases", "risky", "odd"}: gh_config_now() of those files. Every entry is checked on use; a cache that is +# not this user's own plain file, is too big, broken, from another guard file or version, counts as no cache. +# Same-user code can forge it, as it can edit this guard: best effort against mistakes, not a wall (see the top). +CACHE_FILE = 'cache-v1.json' + + +def state_dir(env): + """The guard's state folder (stateDir; "~/" is this HOME); None for "~/.." without an absolute HOME (no cache).""" + d = SETTINGS['stateDir'] + if not d.startswith('~/'): + return d + home = env.get('HOME') or '' + return os.path.join(home, d[2:]) if os.path.isabs(home) else None + + +def file_sig(path): + """[dev, inode, size, mtime_ns, ctime_ns] of a plain file (links followed); None for anything else. The change + time cannot be set back by a program (utime sets only mtime), so a file written again shows a new sig.""" + try: + st = os.stat(path) + except (OSError, ValueError): + return None + return [st.st_dev, st.st_ino, st.st_size, st.st_mtime_ns, st.st_ctime_ns] if S_ISREG(st.st_mode) else None + + +def racy(sig, now): + """A file changed within CACHE_RACY seconds (or in the future): a change in the same clock tick as the reading + would not show in its times, so it is not cached.""" + return sig is None or max(sig[3], sig[4]) / 1e9 > now - CACHE_RACY + + +def guard_sig(): + return file_sig(SELF) if SELF else None + + +# The guard file as this process found it when it started. If the file is replaced while the hook runs (an update), +# the code in memory is the old guard: it must not keep facts under the new file's stat, nor use the new one's cache. +GUARD_AT_START = guard_sig() + + +def guard_now(): + """The guard file's stat, or None when it is not the file this process started from.""" + me = guard_sig() + return me if me and me == GUARD_AT_START else None + + +def is_sig(v): + return isinstance(v, list) and len(v) == 5 and all(type(x) is int for x in v) + + +def fresh(t, now): + return type(t) in (int, float) and 0 <= now - t <= CACHE_LIFE + + +def file_entry_ok(e, now): + labels = {label for label, _ in TOKENS} + return isinstance(e, dict) and is_sig(e.get('sig')) and fresh(e.get('t'), now) and e.get('text') is True \ + and type(e.get('own')) is bool and (e.get('bang') is None or type(e.get('bang')) is str) \ + and ('named' not in e or e['named'] is None or (type(e['named']) is str and e['named'] in labels)) + + +def gh_entry_ok(e, now): + return isinstance(e, dict) and isinstance(e.get('sig'), list) and all(s is None or is_sig(s) for s in e['sig']) \ + and fresh(e.get('t'), now) and type(e.get('risky')) is bool and type(e.get('odd')) is bool \ + and isinstance(e.get('aliases'), list) and all( + isinstance(a, list) and len(a) == 2 and isinstance(a[0], list) and a[0] + and all(type(w) is str for w in a[0]) and type(a[1]) is str for a in e['aliases']) + + +def cache_load(env): + """The cache file as a dict, or None: no file, not a plain file of this user that only this user can write, over + CACHE_BYTES, not JSON, from another guard file or cache version. Never waits (O_NONBLOCK: a FIFO).""" + d, me = state_dir(env), guard_now() + if not d or not me: + return None + try: + fd = os.open(os.path.join(d, CACHE_FILE), os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK + | getattr(os, 'O_CLOEXEC', 0)) + except (OSError, ValueError): + return None + try: + st = os.fstat(fd) + if not S_ISREG(st.st_mode) or st.st_uid != os.geteuid() or st.st_mode & 0o022 or st.st_size > CACHE_BYTES: + return None + data = b'' + while len(data) <= CACHE_BYTES: + piece = os.read(fd, 1 << 16) + if not piece: + break + data += piece + if len(data) > CACHE_BYTES: + return None + c = json.loads(data.decode('utf-8')) + except Exception: # also RecursionError (deep nesting) and a half-written file + return None + finally: + os.close(fd) + if not isinstance(c, dict) or type(c.get('v')) is not int or c['v'] != CACHE_VERSION or c.get('guard') != me \ + or not isinstance(c.get('files'), dict) or not isinstance(c.get('gh'), dict): + return None + return c + + +def cache_disk(ctx): + """The cache of this run, read once and only when a file is first looked at; None without one.""" + h = ctx.get('cache') + if h is None: + return None + if 'disk' not in h: + h['disk'] = cache_load(ctx['env']) + return h['disk'] + + +def facts(path, ctx, need=()): + """What the guard knows of a file: {'text': whether read_text() gives it, and then 'own' (byte-equal to this + guard), 'bang' (the `#!` program, None without a `#!` line), 'named' (the guarded token it names, with 'named' in + need), '_body' (the text, with 'body' in need)}. From this run's memo, else the cache, else the file.""" + memo = ctx.setdefault('memo', {}) + key = ('facts', path) + f = memo.get(key) + if f is None: + f = cached_facts(path, ctx) or fresh_facts(path, ctx) + memo[key] = f + if f['text'] and '_body' not in f and ('body' in need or ('named' in need and 'named' not in f)): + f = memo[key] = fresh_facts(path, ctx) + if f['text'] and 'named' in need and 'named' not in f: + f['named'] = named(f['_body']) + return f + + +def body(path, ctx): + """The text of a file (read_text()), through facts().""" + f = facts(path, ctx, ('body',)) + return f['_body'] if f['text'] else None + + +def cached_facts(path, ctx): + disk = cache_disk(ctx) + e = disk['files'].get(path) if disk else None + if not file_entry_ok(e, time.time()) or e['sig'] != file_sig(path): + return None + return {k: e[k] for k in ('text', 'own', 'bang', 'named') if k in e} + + +_OWN_SIZE = [] + + +def own_size(): + if not _OWN_SIZE: + sig = guard_sig() + _OWN_SIZE.append(sig[2] if sig else None) + return _OWN_SIZE[0] + + +def fresh_facts(path, ctx): + before = file_sig(path) + text = read_text(path) + if text is None: + return {'text': False} + after, size = file_sig(path), own_size() + own = (after is None or size is None or after[2] == size) and text == own_text() + f = {'text': True, 'own': own, 'bang': shebang(text) if text.startswith('#!') else None, '_body': text} + now = time.time() + if ctx.get('cache') is not None and before is not None and before == after and not racy(after, now): + f.update(sig=after, t=now) + ctx['cache'].setdefault('files', {})[path] = f + return f + + +def gh_config_cached(dirs, ctx): + """gh_config_now(dirs), from the cache while every config.yml is the same file as when it was read.""" + paths = [os.path.abspath(os.path.join(cfg, 'config.yml')) for cfg in dict.fromkeys(dirs)] + def sigs(): + out = [] + for p in paths: + try: + st = os.stat(p) + except FileNotFoundError: + out.append(None) + continue + except (OSError, ValueError): + return False # unreadable folder, a loop: not cached + if not S_ISREG(st.st_mode): + return False + out.append([st.st_dev, st.st_ino, st.st_size, st.st_mtime_ns, st.st_ctime_ns]) + return out + key, now = repr(paths), time.time() + before = sigs() + disk = cache_disk(ctx) if before is not False else None + e = disk['gh'].get(key) if disk else None + if gh_entry_ok(e, now) and e['sig'] == before: + return [(list(w), x) for w, x in e['aliases']], e['risky'], e['odd'] + got = gh_config_now(dirs) + if before is not False and before == sigs() and not any(racy(s, now) for s in before if s is not None) \ + and ctx.get('cache') is not None: + ctx['cache'].setdefault('gh', {})[key] = {'sig': before, 't': now, 'aliases': [[list(w), x] for w, x in got[0]], + 'risky': bool(got[1]), 'odd': bool(got[2])} + return got + + +def cache_save(ctx): + """Add what this run learned to the cache file: under a lock, merged with the file as it is now, written to a + temp file and renamed over it (a reader sees the old or the new file, never half of one). decide() calls it last, + when the answer is known: any failure (a full disk, a folder that is no folder, out of time) keeps the old file + or none, and leaves that answer as it is.""" + h = ctx.get('cache') or {} + new_files = {p: {k: v for k, v in f.items() if not k.startswith('_')} for p, f in h.get('files', {}).items()} + new_gh = h.get('gh', {}) + # The hook's stop_at is 1 s before the budget ends (answer()); the write may use the first half of that second. + # A slow first run is the one whose reads most need keeping. The hook's alarm still cuts a write that runs over + # (Slow, caught below), so the answer is never late for it. + stop_at = ctx.get('stop_at') + save_by = None if stop_at is None else stop_at + 0.5 + if not (new_files or new_gh) or (save_by is not None and time.monotonic() > save_by): + return + lock = tmp = None + try: + d, me = state_dir(ctx['env']), guard_now() + if not d or not me: + return + os.makedirs(d, mode=0o700, exist_ok=True) + st = os.lstat(d) + if not S_ISDIR(st.st_mode) or st.st_uid != os.geteuid(): + return + if st.st_mode & 0o077: + os.chmod(d, 0o700) + import fcntl + lock = os.open(os.path.join(d, 'cache.lock'), os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW + | getattr(os, 'O_CLOEXEC', 0), 0o600) + give_up = time.monotonic() + 0.5 if save_by is None else min(time.monotonic() + 0.5, save_by) + while True: + try: + fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB) + break + except BlockingIOError: + if time.monotonic() > give_up: + return + time.sleep(0.01) + now = time.time() + cur = cache_load(ctx['env']) or {} + files = {p: e for p, e in (cur.get('files') or {}).items() if file_entry_ok(e, now)} + gh = {k: e for k, e in (cur.get('gh') or {}).items() if gh_entry_ok(e, now)} + files.update((p, e) for p, e in new_files.items() if file_entry_ok(e, now)) + gh.update((k, e) for k, e in new_gh.items() if gh_entry_ok(e, now)) + files = dict(sorted(files.items(), key=lambda kv: kv[1]['t'])[-CACHE_MAX:]) + gh = dict(sorted(gh.items(), key=lambda kv: kv[1]['t'])[-16:]) + data = json.dumps({'v': CACHE_VERSION, 'guard': me, 'files': files, 'gh': gh}, + separators=(',', ':')).encode('utf-8') + if len(data) > CACHE_BYTES: + return + tmp = os.path.join(d, f'.cache-{os.getpid()}-{os.urandom(4).hex()}.tmp') + fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | getattr(os, 'O_CLOEXEC', 0), 0o600) + try: + view = memoryview(data) + while view: + view = view[os.write(fd, view):] + finally: + os.close(fd) + os.replace(tmp, os.path.join(d, CACHE_FILE)) + tmp = None + for n in os.listdir(d): # temp files of hooks that were killed half-way + p = os.path.join(d, n) + if n.startswith('.cache-') and n.endswith('.tmp') and os.lstat(p).st_mtime < now - CACHE_LIFE: + os.unlink(p) + except BaseException: # also Slow: the answer is already known, the cache is only a help + pass + finally: + for f in ([lambda: os.unlink(tmp)] if tmp else []) + ([lambda: os.close(lock)] if lock is not None else []): + try: + f() + except OSError: + pass + + +# ---------- guarded tokens and the gate that fails closed + +# \uXXXX is four digits and no more (JSON, JS, Python, Go): in \u0070ermissions the `e` is the next letter +ESCAPES = re.compile(r'\\+(?:u([0-9a-fA-F]{4})|u\{([0-9a-fA-F]{1,6})\}|U([0-9a-fA-F]{8})|x([0-9a-fA-F]{2}))' + r'|\\+([0-3][0-7]{2})|%([0-9a-fA-F]{2})') +CUES = ('disable', 'permissions', 'protection', 'ruleset') +# What may not be changed, as it looks after canon(): wherever one of these shows up, the command passes only when +# the guard can prove it is harmless (a plain read, a known allowed form, or text that goes nowhere unread). +TOKENS = [ + ('the `.../actions/workflows//disable` endpoint', re.compile(r'actions/workflows/[^/\s]+/disable(?![\w-])')), + ('`workflow disable`', re.compile(r'workflow\b[\s\S]{0,60}?(? 2 and name.startswith('--') and any(f.startswith(name) for f in GIT_RUNS_LONG) + +SED_RUNS = re.compile(r'(?:^|[;{}!,$/\d\s])e(?:\s|$)|[^\w\s][a-zA-Z0-9]*e[a-zA-Z0-9]*\s*(?:[;}\n]|$)') # e, s///e +HOOK_PATH = re.compile(r'(^|/)(\.git|\.husky|\.githooks|hooks)/') +NO_FILE = re.compile(r'/dev/(null|stdout|stderr|tty|fd/\d+)|&?\d+|-') +SHELL_TEXT = re.compile(r'[\s;|&]') +SEPARATE = 'Run it as separate commands, or write it so the guard can read it (gh or curl as the command word).' +CODE_HINT = ('Make the call with `gh api` as a command of its own. To only change or search text that names it, use ' + 'an edit or search tool instead of code.') + + +# ---------- the fast exit + +# Words the fast exit lets through: DATA words that run no command, set no variable and read no shell text (not +# printf/read/export/alias/[ ..: they set names or take text that matters later), and git with a subcommand that +# runs none of its text. Each one is checked below for the forms of it that do run something. +QUICK_WORDS = frozenset('''echo cat head tail wc ls stat file du df basename dirname realpath readlink mkdir rmdir rm cp + mv ln touch chmod tee sort uniq cut tr paste column fold fmt nl tac rev comm join diff cmp grep egrep fgrep rg jq + date printenv id whoami hostname uname uptime nproc seq mktemp sha256sum sha1sum md5sum base64 xxd od tree ps + pgrep sleep true false test cd pushd popd pwd sed find'''.split()) +QUICK_GIT = GIT_SAFE +QUICK_FLOW = frozenset('if then else elif fi do done while until'.split()) # keywords in front of a command word +# Text that sends the command to the full reading wherever it stands, letters only (dis-able, Work_Flow ..): +QUICK_KEYS = ('disable', 'permission', 'protection', 'ruleset', 'workflow', 'graphql', 'mutation', 'github', 'curl', + 'wget', 'http', 'aria2') \ + + tuple(re.sub(r'[^a-z0-9]', '', os.path.splitext(r['name'])[0].lower()) for r in REFUSE_SCRIPTS) # garden.py: garden +QUICK_NAMES = frozenset({'gh', 'xh', 'xhs', 'curlie', 'httpie'}) # as a word anywhere (/usr/bin/gh, ln -s .. gh) +QUICK_SED = frozenset({'-n', '-E', '-r', '-e', '-i', '-s', '-u', '-z', '--quiet', '--silent', '--regexp-extended', + '--null-data', '--expression'}) +QUICK_CHARS = re.compile(r'[^\x20-\x7e\t\n]|[$`\\%!]|<<') +QUICK_MAX, QUICK_CDS = 4000, 8 +# sed scripts the fast exit takes: lines printed, deleted or counted, s/a/b/ with plain flags (no e, no w file) +_SED_ADDR = r'(?:\d+|\$|/[^/\n]*/)' +_SED_ONE = (rf'\s*(?:{_SED_ADDR}(?:\s*,\s*(?:{_SED_ADDR}|[+~]\d+))?\s*)?' + r'(?:[pdnNgGhHxlz=]|[qQ]\d*|s/[^/\n]*/[^/\n]*/[gpiI\d]*)\s*') +QUICK_SED_SCRIPT = re.compile(rf'{_SED_ONE}(?:;{_SED_ONE})*(?:;\s*)?') + + +def quick_words(cmd, globs=None): + """[[(word without its quotes, whether it had quotes)] per command] of a command in the small shell subset the + fast exit reads (plain words, '..' and ".." with no $ ` \\ inside, ; | & && || and line breaks, redirections); + None for anything else: an unclosed quote, # ( ) { } ! outside quotes. globs: each word with * ? [ outside + quotes (the shell may turn it into other names) is added to it, when given.""" + out, cmd_, word, quoted, started, glob, i = [], [], '', False, False, False, 0 + def end_word(): + nonlocal word, quoted, started, glob + if started: + cmd_.append((word, quoted)) + if glob and globs is not None: + globs.append(word) + word, quoted, started, glob = '', False, False, False + while i < len(cmd): + c = cmd[i] + if c in '\'"': + j = cmd.find(c, i + 1) + if j < 0: + return None + word, quoted, started, i = word + cmd[i + 1:j], True, True, j + 1 + continue + if c in '#(){}!' or (c == '|' and cmd[i - 1:i] == '>'): # >| writes a file, it is no pipe + return None + if c in ' \t': + end_word() + elif c in ';|\n' or (c == '&' and not (cmd[i - 1:i] in ('<', '>') or cmd[i + 1:i + 2] == '>')): + end_word() + out.append(cmd_) + cmd_ = [] + else: + word, started, glob = word + c, True, glob or c in '*?[' + i += 1 + end_word() + out.append(cmd_) + return out + + +def quick_sed_scripts(args): + """The scripts of a sed command the fast exit reads (-e X, --expression X, else the first word that is no + option); None for a form it does not read.""" + scripts, i, rest = [], 0, [] + while i < len(args): + a = args[i] + if a in ('-e', '--expression'): + if i + 1 >= len(args): + return None + scripts.append(args[i + 1]) + i += 2 + continue + if a.startswith('-') and a != '-': + if a not in QUICK_SED: + return None + else: + rest.append(a) + i += 1 + if not scripts: + scripts = rest[:1] + return scripts or None + + +def quick_pass(cmd): + """True for a command that cannot name or run anything this guard refuses, decided from its text alone, before + any file is read: every command in it is a QUICK_WORDS word (or safe git) in a form that runs nothing, and no + word of it can name a guarded token, gh, an HTTP client or a git hook, or one of its own command words (a file + the text writes and then runs). Anything else, however harmless, goes to the full reading. The tests compare + the two over every command they know and over random ones (what is fast passes there too).""" + if not isinstance(cmd, str) or len(cmd) > QUICK_MAX or QUICK_CHARS.search(cmd): + return False + low = cmd.lower() + letters = re.sub(r'[^a-z0-9]', '', low) + plain = re.sub(r'[\'"]', '', low) + if any(k in letters for k in QUICK_KEYS) or any(k in plain for k in ('hooks', '.git/', '.husky')) \ + or QUICK_NAMES & set(re.split(r'[^a-z0-9_.-]+', plain)): + return False + globs = [] + cmds = quick_words(cmd, globs) + if cmds is None: + return False + cds, heads, rest = 0, set(), set() + for words in cmds: + while words and not words[0][1] and words[0][0] in QUICK_FLOW: + words = words[1:] + if not words: + continue + (head, quoted), args = words[0], [w for w, _ in words[1:]] + if quoted or (head not in QUICK_WORDS and head != 'git'): + return False + heads.add(head) + rest.update(p for a in args for p in re.split(r'[^a-z0-9_.+-]+', a.lower())) + cds += head in ('cd', 'pushd', 'popd') + if cds > QUICK_CDS: + return False + if head == 'find' and any(a in ('-exec', '-execdir', '-ok', '-okdir') for a in args): + return False + if head in COPIERS and re.search(r'[*?\[]', cmd): + return False + if head == 'sed': + scripts = quick_sed_scripts(args) + if scripts is None or not all(QUICK_SED_SCRIPT.fullmatch(t) for t in scripts) \ + or any(SED_RUNS.search(a) for a in args): + return False + if head == 'rg' and any(a.startswith(('--pre', '--hostname-bin')) for a in args): + return False + if head == 'sort' and any(a.startswith('--co') for a in args): + return False + if head == 'git': + i = 0 + while i < len(args) and args[i] in ('-C', '--no-pager', '-P'): + i += 2 if args[i] == '-C' else 1 + if i >= len(args) or args[i] not in QUICK_GIT or any(git_runs(a) for a in args[i + 1:]): + return False + # echo .. > ~/.local/bin/ls; ls: a file the text may write under a name it runs, also as a glob (l?, [l]s) + return not heads & rest and not any(quick_glob_names(g, heads) for g in globs) + + +def quick_glob_names(word, heads): + """Whether a word with * ? [ outside quotes may name one of heads (each part between / = < > & : , is a glob). + A part with [ may name anything ([[:lower:]], [^x] ..: the guard does not read classes); * and ? are read the + way the shell does.""" + for part in re.split(r'[/=<>&:,]+', word.lower()): + if '[' in part: + return True + if re.search(r'[*?]', part) and any(fnmatch.fnmatchcase(h, part) for h in heads): # no [ here; never + return True # backtracks on *** + return False + + +def _unescape(m): + try: + return chr(int(m.group(5), 8) if m.group(5) else + int(m.group(1) or m.group(2) or m.group(3) or m.group(4) or m.group(6), 16)) + except (ValueError, OverflowError): + return m.group(0) + + +def canon(text, blank=True): + """Text as the program at the far end may read it: \\uXXXX, \\xXX, octal and %XX decoded (up to three rounds), + backslashes and all quotes dropped (blank: \\n \\t \\r read as a blank first), 'a' + 'b' joined, lower case, + /./ // and /x/../ in paths resolved. '' when no guarded word is left at all.""" + s = text + if '\\' in s or '%' in s: + for _ in range(3): + before = s + s = ESCAPES.sub(_unescape, s) + if s == before: + break + if blank: + s = re.sub(r'\\+[ntr]', ' ', s) + s = s.replace('\\', '') + s = re.sub(r'["\']\s*[+.]\s*["\']', '', s) + s = re.sub(r'["\'`]', '', s).lower() + if not any(c in s for c in CUES): + return '' + s = re.sub(r'(?= 2: + rest = rest[:2] + elif word not in ('ln', 'cp', 'mv', 'install', 'link', 'rsync'): + return set() + if len(rest) < 2 or hidden(rest[-1]) \ + or not any(hidden(a) or os.path.basename(a.rstrip('/')) == 'gh' for a in rest[:-1]): + return set() + name = os.path.basename(rest[-1].rstrip('/')) + return {name} if name not in ('', '.', '..') else set() + + +def runner_at(toks, start): + """Behind a command word the guard does not know: where a word it does know how to read starts (a shell, an + interpreter, git, curl, a wrapper ..), or None. An unknown word must not hide the command that follows it.""" + for i in range(start, len(toks)): + base = os.path.basename(toks[i]) + if base in RUNNERS or base in SHELLS or base in NET_CLIENTS or base in TEXT_ARGS or base in AWKS \ + or INTERPRETERS.match(base): + return i + return None + + +def exported(toks, flow): + return 'export' in toks or bool(flow.get('seta')) or \ + (('declare' in toks or 'typeset' in toks) and any(re.fullmatch(r'-[A-Za-z]*x[A-Za-z]*', t) for t in toks)) + + +def gh_gate(args, ctx, own): + """gh passed the checks above. What is left: a first word that is no gh command (an alias the reader may not + know, an extension: another program) and words gh hands on to another program.""" + cands = sub_candidates(args) + first = args[cands[0]] if cands else '' + if first and first not in GH_COMMANDS: + if own and not ctx.get('nogate'): + return unproven(own, f'and runs `gh {redact(first)}`, which is no gh command (an alias, an extension, ' + 'or a word the guard cannot read)', 'Use the gh command itself, spelled out.') + ctx['flow']['unknown'] = f'gh {redact(first)}' + if own and first in ('extension', 'codespace', 'cs'): + return unproven(own, f'and runs `gh {first}`, which starts other programs') + if own and first != 'api' and '--' in args and named(' '.join(args[args.index('--') + 1:])): + return unproven(own, 'behind `--`, where gh hands the words on to another program') + return None + + +def rc_files(word, toks, h, ctx): + """The config files curl or wget would read first, as far as the text and the hook's environment show them.""" + env = dict(ctx['env']) + for t in toks[:h]: + m = ASSIGN.match(t) + if m and not hidden(t): + env[m.group(1)] = m.group(3) + home = env.get('HOME') or '' + if word == 'curl': + dirs = [env.get('CURL_HOME'), env.get('XDG_CONFIG_HOME'), home, home and os.path.join(home, '.config')] + return [os.path.join(d, n) for d in dirs if d for n in ('.curlrc', 'curlrc')] + return [p for p in (env.get('WGETRC'), home and os.path.join(home, '.wgetrc'), '/etc/wgetrc') if p] + + +def net_gate(word, toks, h, ctx, own): + """curl, wget and the like passed net_reason. A guarded token passes only as a request path the guard can read, + with the tool's own config switched off (a ~/.curlrc can turn a read into `request = PUT`).""" + args = toks[h + 1:] + files = [m.group(1) for a in args for m in [re.search(r'@([^@=\s]+)$', a)] if m] + bodies = [ctx.get('stdin') or ''] + [read_named(f, ctx) or '' for f in files] + if any(GQL_RE.search(c) or GQL_UPDATE.search(c) for c in (canon(x) for x in list(args) + bodies)): + return reason('a GraphQL mutation that deletes branch protection or a ruleset, or changes a ruleset, sent ' + f'with `{word}`: the guard reads GraphQL only through `gh api graphql`') + no_rc = (word == 'curl' and bool(args) and not hidden(args[0]) and (args[0] == '--disable' + or re.match(r'-q', args[0]) is not None)) \ + or (word == 'wget' and '--no-config' in args) + hint = 'Put `-q` (or `--disable`) as the FIRST argument: curl then skips its config file.' if word == 'curl' \ + else 'Add `--no-config`: wget then skips its config files.' + for i, a in enumerate(args): # more arguments or addresses, from a file: curl -K/--config, wget -i/--input-file + after = args[i + 1] if i + 1 < len(args) else '' + short = re.match(r'-[A-Za-z0-9#:]*?%s(.*)$' % ('K' if word == 'curl' else 'i'), a, re.S) \ + if word in ('curl', 'wget') and not a.startswith('--') else None + if short: # also joined: -sK file, -Kfile + name = short.group(1) or after + elif word == 'curl' and a.startswith('--config') or word == 'wget' and a.startswith('--input-file'): + name = a.partition('=')[2] or after + else: + continue + tok = named_file(name, ctx) + if not tok and read_named(name, ctx) is None: + ctx['flow']['unknown'] = f'{word} with arguments from a file the guard cannot read' + elif tok: + return unproven(tok, f'in a file that `{word}` reads its arguments or addresses from ' + '(curl -K/--config, wget -i/--input-file)', 'Use `gh api` for it.') + if any(hidden(a) for a in args): # "$(cat url.txt)": what the same command sends on may land here + ctx['flow']['unknown'] = f'{word} with a word the guard cannot read' + if not no_rc: + for p in rc_files(word, toks, h, ctx) if word in NET_TOOLS else (): + tok = file_token(resolve_path(p, ctx['cwd'])) + if tok: + return unproven(tok, f'in {word}\'s own config file ({os.path.basename(p)}), which {word} reads ' + 'before its arguments', hint) + ctx['flow']['unknown'] = f'{word} (it reads its config file first)' + if not own: + return None + if word not in NET_TOOLS: + return unproven(own, f'and uses `{word}`, an HTTP client the guard has no flag table for', + 'Use `gh api`, or `curl -q` for a read.') + if not no_rc: + return unproven(own, 'with curl, which reads ~/.curlrc (or $CURL_HOME, $XDG_CONFIG_HOME) first: a line ' + 'there can turn a read into a write' if word == 'curl' else + 'with wget, which reads ~/.wgetrc (or $WGETRC, /etc/wgetrc) first: a line there can turn a ' + 'read into a write', hint) + if not any(hits(a, k) for a in args for k in GUARDED) or named(' '.join(toks[:h])): + return unproven(own, f'in an argument of `{word}` that is no request path the guard can read', + 'Use `gh api` for it.') + return None + + +def git_sub(args): + i = 0 + while i < len(args): + a = args[i] + if a in ('-C', '-c', '--git-dir', '--work-tree', '--namespace'): + i += 2 + elif a.startswith('-') or hidden(a) and WILD in a: + i += 1 + else: + return a, i + return '', len(args) + + +def git_gate(args, ctx, own, fed): + """git with a guarded token: only subcommands that take text and run none of it (a commit message, a grep + pattern), with nothing git would run as a command (a pager, an alias, a transport helper).""" + sub, i = git_sub(args) + if not sub or sub not in GIT_COMMANDS: # an alias, git- on PATH, a hidden word + ctx['flow']['unknown'] = f'git {redact(sub)}'.strip() + tok = own or fed + if tok and (sub not in GIT_SAFE or named(' '.join(args[:i])) or any(git_runs(a) for a in args[i + 1:])): + return unproven(tok, f'and runs `git {redact(sub)}` in a form that can run a command (an alias, a pager, ' + 'a transport, a config value)', 'Keep such text to commit messages and patterns.') + return None + + +def sed_scripts(args): + """The arguments sed reads as its script: after -e/--expression, else the first word that is no flag.""" + out = [a.partition('=')[2] or (args[i + 1] if i + 1 < len(args) else '') + for i, a in enumerate(args) if a == '-e' or a.startswith('--expression')] + return out or [a for a in args if not a.startswith('-')][:1] + + +def data_token(tok, ctx): + """The guarded token in a file that cat/cp/.. hand on: its text as read_text() gives it, so data over MAX_FILE or + that cannot be opened passes unread (lockout care). A file that looks like a script, or one piped into a shell + or interpreter that runs its stdin (`cat f | bash`), is read in pieces and counts when unread (file_token).""" + for d in [] if hidden(tok) else folders(ctx): + p = resolve_path(tok, d) + f = facts(p, ctx, ('named',)) + t = f['named'] if f['text'] else \ + (ctx.get('feeds_code') or script_like(p, unopened=False)) and file_token(p) + if t: + return t + return None + + +def stdin_runs(toks, how, loose): + """Whether a command runs what it reads on stdin as shell or code: a shell or interpreter with no script of + its own (`bash`, `sh -s x`, `python3 -`), not `python3 load.py` or `awk '{..}'`, whose stdin is data.""" + if not toks or doc_kind(toks, how, loose, '') == 'data': + return False + h, via = head(toks) + if 'shell' in via or h is None: # head() takes the shell's script as the command word + return h is None or '-s' in toks[:h] + return not any(a in ('-c', '-e', '-m', '--eval') or not a.startswith('-') for a in toks[h + 1:]) + + +def data_gate(word, args, ctx, own, fed, loose): + """A command word that only handles text. Its text may name a guarded token; where the text goes is noted (a + pipe, a file, $(..)), and decide() refuses when the same command also runs a word the guard cannot read.""" + flow = ctx['flow'] + if word == 'find': # -exec cmd ..: a command of its own + for i, a in enumerate(args): + if a in ('-exec', '-execdir', '-ok', '-okdir') and args[i + 1:]: + r = segment_reason(args[i + 1:], dict(ctx, stdin=None, cmd={}, leak=False, targets=()), loose) + if r: + return r + if word == 'set' and (any(re.fullmatch(r'-[A-Za-z]*a[A-Za-z]*', a) for a in args) or 'allexport' in args): + flow['seta'] = True + if word in ('typeset', 'readonly', 'local', 'declare', 'export'): + if own and exported([word] + args, flow): + flow['env'] = own + return None + if own and (word == 'sed' and any(SED_RUNS.search(a) for a in sed_scripts(args)) + or word == 'rg' and any(a.startswith(('--pre', '--hostname-bin')) for a in args) + or word == 'sort' and any(a.startswith('--compress-prog') for a in args)): + return unproven(own, f'in `{word}` arguments that can run a command (sed `e`, rg --pre, ' + 'sort --compress-program)') + tok, moved = own or fed, False + if not tok and (ctx.get('leak') and word in READERS or word in COPIERS): + # cat x | ..: the file's text goes on; cp x run.sh: it gets a name the next word may run + tok = next((t for t in (data_token(a, ctx) for a in args if not a.startswith('-')) if t), None) + moved = word in COPIERS + targets = list(ctx.get('targets', ())) + (args if word in WRITERS else []) + if tok and any(HOOK_PATH.search(t) for t in targets): + return unproven(tok, 'and writes it under .git/ or a hooks folder, where git runs it later') + if tok and ctx.get('proven'): # the text is a script the same command runs: it was read as shell text + return None + if tok and (ctx.get('leak') or moved or (own and word in WRITERS)): + flow['free'] = tok + return None + + +SHELL_EXT = ('.sh', '.bash', '.zsh') +CODE_EXT = ('.py', '.pyw', '.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx', '.rb', '.pl', '.pm', '.php', + '.lua', '.tcl', '.ps1', '.psm1', '.awk', '.go', '.groovy', '.kts', '.swift', '.exp', '.fish', '.nu') +LOADS = {'-r', '--require', '--import', '--loader', '-f', '--file', '-m', '--module'} # flags that name code to run + + +def arg_scripts_reason(word, args, ctx): + """Files handed to a command word the guard does not know (`taskset 1 ./x.sh`, `at -f x.sh`, `uv run x.py`, + `chrt 1 ./tool.py`): the word may run them. A shell script is read in full, as if it were the command word + itself. A file that looks like code in another language (its name, a `#!` line, the executable bit) may not + name a guarded token. Plain data files (.md, .json, .yml, .txt ..) are not looked at.""" + for a in args: + a = a.partition('=')[2] if a.startswith('--') and '=' in a else a + if a.startswith('-') or hidden(a) or not a: + continue + files = cmd_files(a, ctx, False) + [(p, d) for d in folders(ctx) for p in [resolve_path(a, d)]] + for p, d in dict.fromkeys(files): + f = facts(p, ctx) + if not f['text'] or is_self(p, ctx): + r = not f['text'] and unread(p, any_file=False) + if r: + return r + continue + if a.endswith(SHELL_EXT) or f['bang'] in SHELLS: + r = file_reason(p, dict(ctx, cwd=d), force_shell=True) + if r: + return r + elif (a.endswith(CODE_EXT) or f['bang'] is not None or os.access(p, os.X_OK)) and \ + facts(p, ctx, ('named',)).get('named'): + return unproven(facts(p, ctx)['named'], f'in `{redact(os.path.basename(a))}`, a code file that is handed to ' + f'`{word}`, which may run it (the guard cannot follow what that word ' + 'does with its arguments)', + 'If the file is only data here (a path to commit, lint or copy), name its folder ' + 'instead, or use a tool the guard knows (git add, cp).') + return None + + +def interp_files(kind, args, pos, ctx): + """[(file, folder)]: the code files an interpreter runs for these arguments. The script is the first of its + leading words that is a file (`python3 x.py a b`: x.py; `deno run x.ts`: x.ts; what follows the script is the + script's own business), plus what a flag loads (`node -r ./x.js`, `python3 -m x`, `php -f x.php`).""" + names = [] + if kind not in AWKS and not {'-m', '-c', '-e', '-', '--eval'} & set(args): + names.append([a for a in pos[:3] if not hidden(a)]) + for i, a in enumerate(args): + flag, eq, value = a.partition('=') + if flag in LOADS and not hidden(a): + value = value if eq else (args[i + 1] if i + 1 < len(args) else '') + if value and not hidden(value) and not value.startswith('-'): + if flag in ('-m', '--module'): + mod = value.replace('.', '/') + names += [[mod + '.py'], [mod + '/__main__.py']] + else: + names += [[value], [value + '.js'], [value + '.rb'], [value + '.pl']] + out = [] + for group in names: # of a group, the first name that is a file + for name in group: + found = [(p, d) for d in folders(ctx) for p in [resolve_path(name, d)] if os.path.isfile(p)] + if found: + out += found + break + return out + + +def launcher_gate(toks, h, ctx, own, fed, loose): + """A command word the guard does not know. With a guarded token in its words or its input it is refused: the + guard cannot tell what the word does with them. Without one, the words behind it are still read (a shell, an + interpreter, a script file), and decide() refuses when token text flows anywhere in the same command.""" + word = toks[h] + name = redact(os.path.basename(word)) if not hidden(word) else 'a command word from a variable' + if (own or fed) and not ctx.get('nogate'): + return unproven(own or fed, f'and runs `{name}`, a command word the guard does not know (a launcher, a ' + 'project tool, a renamed program ..)') + i = runner_at(toks, h + 1) + r = (i is not None and segment_reason(toks[i:], ctx, loose)) or arg_scripts_reason(name, toks[h + 1:], ctx) + if r: + return r + ctx['flow']['unknown'] = name + return None + + +def flow_reason(flow): + """The whole command read: token text that went somewhere, next to a word the guard could not read.""" + if flow.get('free') and flow.get('unknown'): + return unproven(flow['free'], f'in text that goes on (a pipe, a file, a variable), and that also runs ' + f'`{flow["unknown"]}`, which the guard cannot read') + if flow.get('env') and (flow.get('unknown') or flow.get('ran')): + return unproven(flow['env'], 'in an exported variable, which the programs run after it may take as a ' + 'command (PAGER, GIT_SSH_COMMAND ..)') + return None + + +# ---------- decision + +def cmd_files(tok, ctx, via_shell): + """[(file, folder)]: the script files a command word may run, one per folder the command may run in.""" + out = [] + for d in folders(ctx): + p = resolve_cmd(tok, dict(ctx, cwd=d), via_shell) + if p and os.path.isfile(p) and all(p != q for q, _ in out): + out.append((p, d)) + return out + + +def flag_values(toks, h): + """The words head() took as the value of a wrapper's flag (`sudo -u NAME`). Which flags take a value depends + on the wrapper, so such a word may be the command word itself (`env -i bash x.sh`, `bash -e x.sh`).""" + end = len(toks) if h is None else h + return [i for i in range(1, end) if toks[i - 1] in ARG_FLAGS and not toks[i].startswith('-')] + + +def segment_reason(toks, ctx, loose): + h, via = head(toks) + flow = ctx['flow'] + for j in flag_values(toks, h): # the other reading: the flag takes no value and the word starts the command + base = os.path.basename(toks[j]) + if base in SHELLS or base in NET_CLIENTS or base in TEXT_ARGS or base in AWKS or INTERPRETERS.match(base) \ + or is_gh(toks[j], ctx) or (not hidden(toks[j]) and cmd_files(toks[j], ctx, True)): + r = segment_reason(toks[:j - 1] + toks[j:], ctx, loose) + if r: + return r + extra = [WILD] if 'xargs' in via else [] # xargs adds words nobody can read here + for i, t in enumerate(toks if 'xargs' in via else ()): # xargs -a file: the words come from that file + name = t.partition('=')[2] if t.startswith('--arg-file=') else \ + (toks[i + 1] if t in ('-a', '--arg-file') and i + 1 < len(toks) else '') + tok = name and named_file(name, ctx) + if tok: + return unproven(tok, 'in the file that `xargs` takes the words of its command from (-a/--arg-file)') + for i, t in enumerate(toks): # gh anywhere in the command: behind find -exec, ssh, a wrapper not listed here + if is_gh(t, ctx): + r = gh_reason(toks[i + 1:] + extra, dict(ctx, cfg_hidden=ctx.get('cfg_hidden') or any( + hidden(a) and re.match(r'(GH_CONFIG_DIR|XDG_CONFIG_HOME|HOME)=', a) for a in toks[:i])), sure=i == h) + if r: + return r + word = os.path.basename(toks[h]) if h is not None else '' + # plain: the word is the program of that name for certain (no function, no alias, no file in another folder) + plain = h is not None and not hidden(toks[h]) and toks[h] not in ctx.get('funcs', ()) \ + and toks[h] not in ctx.get('aliases', {}) and ('/' not in toks[h] or os.path.dirname(toks[h]) in STD_BINS) + kind = word if plain else '' + gh_word = h is not None and is_gh(toks[h], ctx) + shellish = bool(via & {'shell', 'eval'}) + interp = INTERPRETERS.match(kind) is not None or kind in AWKS + # gh-as -- gh ..: gh with an app token (a wrapper that may run this guard on the gh words too) + rest = toks[h + 1:] if kind == 'gh-as' else [] + cut = rest.index('--') if '--' in rest else -1 + gh_as = rest[cut + 2:] if 0 <= cut <= 2 and rest[cut + 1:cut + 2] == ['gh'] else None + lost = h is not None and not (shellish or gh_word or interp or kind in DATA or kind in NET_CLIENTS + or kind in TEXT_ARGS or kind == 'git' or gh_as is not None) + texts = [] # words that are shell text themselves + if 'eval' in via and h is not None: + texts.append(' '.join(toks[h:])) + if (shellish and not interp) or loose or kind in TEXT_ARGS or lost: + texts += [t for t in toks if SHELL_TEXT.search(t)] # also behind a word the guard does not know (sg -c ..) + elif h is not None and re.search(r'\s', toks[h]): # env -S ".." and other wrappers that take one string + texts.append(toks[h]) + for t in toks[:h] if h is not None else toks: # --split-string=".." and the like + if t.startswith('-') and re.search(r'\s', t): + texts += [t.partition('=')[2], t[2:]] + how, proven = ctx.get('writes'), False + if how and h is not None: # echo/printf/tee .. > x.sh; sh x.sh: the words are the script + said = toks[h + 1:] + made = [' '.join(said), ' '.join(said[1:])] + [t for t in said if re.search(r'\s', t)] + made += [t.replace('\\n', '\n') for t in made if '\\n' in t] + if how == 'code' or (how == 'exec' and any(shebang(t.lstrip()) not in SHELLS | {''} for t in made)): + tok = named(' '.join(toks)) or named(ctx.get('stdin') or '') + if tok: + return reason(f'a script that the same command writes and runs names {tok}; the guard reads shell ' + 'scripts only, not code', 'Run the calls as gh commands the guard can read.') + else: + texts += made + proven = True + ctx = dict(ctx, writes='', proven=proven) + texts += [t.replace('\\n', '\n') for t in texts if '\\n' in t] # printf 'a\ngh ..' | sh + inner = dict(ctx, nogate=True) if lost and not loose else ctx # the gate below speaks for the whole command + for text in dict.fromkeys(texts): + r = text and decide_text(text, inner) + if r and lost and not loose and text in toks[h + 1:]: # -m/--what/-p text of a tool the guard does not know + what = r[len(PREFIX):] if r.startswith(PREFIX) else r + return PREFIX + (f'an argument of `{redact(word)}`, a tool the guard does not know, is text that reads as ' + 'shell, and read as shell it is refused. If it is only text (a message, a title, a ' + 'prompt), put it in a file and pass the file (--body-file, -F), or reword it; to run it, ' + f'run it as a command of its own. As shell: {what}') + if r: + return r + own, fed = named(' '.join(toks)), named(ctx.get('stdin') or '') + if h is None: + if own and exported(toks, flow): + flow['env'] = own + if 'shell' in via and ctx.get('stdin') is None: + flow['unknown'] = 'a shell that reads a pipe or a file the guard cannot read' + return None + if (ctx.get('cmd') or {}).get('pat') and not own: # a `case` pattern, not a command + return None + args = toks[h + 1:] + extra + if not gh_word and (hidden(toks[h]) or toks[h] in ctx.get('funcs', ())): # "$GH" .., g() { gh "$@"; }; g .. + r = gh_reason([WILD] + args, ctx, sure=False) or net_reason('', args, ctx) + if r: + return r + expansions = ctx.get('aliases', {}).get(toks[h], ()) + for exp in expansions: # alias g='gh workflow'; g ..: read as the text it stands for + r = decide_text(exp + ' ' + ' '.join(quote(a) for a in args), ctx) + if r: + return r + if kind in DATA and not shellish: + if 'xargs' in via and (own or kind in ('sed', 'find')): + flow['unknown'] = 'xargs' + return data_gate(kind, args, ctx, own, fed, loose) + flow['ran'] = True + if 'xargs' in via: + flow['unknown'] = 'xargs' + pre = named(' '.join(toks[:h])) + if pre and not ctx.get('nogate'): + return unproven(pre, 'in a variable or an option set in front of the command word, which the program may ' + 'take as a command (PAGER, GIT_SSH_COMMAND, a wrapper option ..)') + if gh_word: + if not plain: + flow['unknown'] = 'gh under another name or path' + return gh_gate(args, ctx, own) + if gh_as is not None: + return gh_reason(gh_as, ctx, sure=True) or gh_gate(gh_as, ctx, own) + pos = positional(args, {'-m', '-W', '-X', '--eval', '-e', '-c', '-r', '--require'}) + script = toks[h] if not interp else (pos[0] if pos else '') + for rs in REFUSE_SCRIPTS: # the machine file's refuseScripts: a project tool that disables workflows itself + if os.path.basename(script) == rs['name'] and rs['flag'] in args \ + and any(os.path.isfile(resolve_path(script, d)) for d in folders(ctx)): # a real run, not prose + return reason(f'`{rs["name"]} {rs["flag"]}` {rs.get("why") or "is refused by this machine's settings"}') + if interp: + files = interp_files(kind, args, pos, ctx) + if any(is_self(p, ctx) for p, _ in files): + return None + if own or fed: + return unproven(own or fed, f'in inline code, arguments or input of `{word}`: the guard reads shell ' + 'text and gh/curl calls, not code in other languages', CODE_HINT) + flow['unknown'] = word + for p, d in dict.fromkeys(files): + r = file_reason(p, dict(ctx, cwd=d)) + if r: + return r + return None + if shellish: + tok = named(' '.join(t for t in toks if not (SHELL_TEXT.search(t) and named(t)))) + if tok: # sh -c 'curl -X PUT "$1"' _ : the token is no shell text the guard has read + return unproven(tok, 'in the arguments of a shell, `eval` or a script, outside the shell text itself') + if 'eval' in via: + if any(hidden(t) for t in toks[h:]): + flow['unknown'] = 'eval' + return None + if any(re.fullmatch(r'-[A-Za-z]*c', t) for t in toks[:h]): # sh -c word: the word is the whole text + return None if SHELL_TEXT.search(toks[h]) else decide_text(toks[h], ctx) + files = [] if hidden(toks[h]) else cmd_files(toks[h], ctx, True) + for p, d in files: + r = file_reason(p, dict(ctx, cwd=d), force_shell=True) + if r: + return r + if not files and not SHELL_TEXT.search(toks[h]): + flow['unknown'] = 'a script that is not there to read (written later, or named by a variable)' + return None + if kind in TEXT_ARGS: # ssh, su, parallel, trap: their quoted arguments were read as shell text above + tok = named(' '.join(t for t in toks if not (SHELL_TEXT.search(t) and named(t)))) or fed + if tok: + return unproven(tok, f'in the words or the input of `{word}`, outside one quoted shell text') + if kind != 'trap': + flow['unknown'] = word + return None + if kind in NET_CLIENTS: + return net_reason(word, args, ctx) or net_gate(word, toks, h, ctx, own or fed) + if kind == 'git': + for a in args: # git -c alias.x='!cmd' x, git config alias.x '!cmd': the text after ! is a shell command + bang = a[1:] if a.startswith('!') else a.partition('=!')[2] + r = bang and decide_text(bang, ctx) + if r: + return r + return git_gate(args, ctx, own, fed) + # Every other command word: a script file the guard can read, a function, or a word it does not know. + if hidden(toks[h]): + return launcher_gate(toks, h, ctx, own, fed, loose) + if toks[h] in ctx.get('funcs', ()) or expansions: + if own or fed: # its body is in the text and was read; the words it gets may go anywhere + flow['free'] = own or fed + return None + files = cmd_files(toks[h], ctx, False) + if any(is_self(p, ctx) for p, _ in files): + return None + bare = '/' not in toks[h] and which(toks[h], ctx) + if any(gh_file(p, ctx) for p in [q for q, _ in files] + ([bare] if bare else [])): + return gh_reason(args, ctx, sure=True) or gh_gate(args, ctx, own) # gh, renamed or linked earlier + read = False + for p, d in files: + f = facts(p, ctx) + if not f['text']: + r = unread(p) + if r: + return r + continue + read = True + if (own or fed) and not ctx.get('nogate'): + return unproven(own or fed, f'and hands it to the script `{redact(word)}`, whose use of its ' + 'arguments and input the guard cannot follow') + r = file_reason(p, dict(ctx, cwd=d)) + if r: + return r + if not (p.endswith(('.sh', '.bash', '.zsh')) or f['bang'] in SHELLS): + flow['unknown'] = redact(word) # code in another language: only looked through for guarded tokens + if read: + return arg_scripts_reason(redact(word), toks[h + 1:], ctx) + return launcher_gate(toks, h, ctx, own, fed, loose) + + +def reads_stdin_as_shell(toks): + """bash, sh -s, eval ..: a shell that runs what a pipe or heredoc feeds it.""" + h, via = head(toks) + if 'eval' in toks: + return True + return 'shell' in via and (h is None or toks[h] in ('-', '/dev/stdin', '/dev/fd/0', '/proc/self/fd/0')) + + +def written(toks, cmd, env, ran): + """How a file this command writes (> file, tee file) is run by a command of the same text: 'shell' (through a + shell or `source`), 'exec' (as a command: its `#!` line picks the reader), 'code' (as an interpreter's script) + or '' (not run, as far as the text shows). Files are matched by name, not by folder.""" + h, _ = head(toks) + targets = [t for op, w in cmd['redirs'] if op.startswith(('>', '&>')) for r in readings({'words': [w]}, env) + for t in [''.join(r)]] + if h is not None and os.path.basename(toks[h]) == 'tee': + targets += [t for t in toks[h + 1:] if not t.startswith('-')] + names = {os.path.basename(t) for t in targets if os.path.basename(t)} + return next((k for k in ('shell', 'exec', 'code') if any(same_name(a, b) for a in names for b in ran[k])), '') + + +def same_name(a, b): + """Whether two file names can be the same file: equal (two hidden names count as equal: f=$(mktemp); cat > "$f" + ..; bash "$f"), or one has hidden parts and its visible text fits the other.""" + if a == b: + return True + if hidden(a) and hidden(b): + return True + for x, y in ((a, b), (b, a)): + if hidden(x) and x.replace(HID, '').replace(WILD, '') and spells(x, y): + return True + return False + + +def doc_kind(toks, how, loose, body): + """A heredoc (or <<< word, < file) is shell (fed to a shell), code (fed to an interpreter), script (written to + a file that a command in this text runs as shell) or data. how: written() of the command.""" + h, via = head(toks) + word = os.path.basename(toks[h]) if h is not None else '' + if 'shell' in via or 'eval' in via: + return 'shell' + if INTERPRETERS.match(word): + return 'code' + if how == 'exec': + how = 'shell' if shebang(body) in SHELLS | {''} else 'code' + if how: + return 'script' if how == 'shell' else 'code' + return 'shell' if loose else 'data' + + +def stdin_of(cmd, env, ctx): + """The text a command gets on stdin when the command text shows it (heredoc, <<< word, < file that is there to + read), else None (a pipe, the terminal, a file written later).""" + parts = list(cmd['docs']) + for op, w in cmd['redirs']: + if op not in ('<<<', '<'): + continue + words = redir_texts(op, w, env) + word = words[0] if len(words) == 1 else HID # a variable with several values: not known + text = word if op == '<<<' else read_named(word, ctx) + if text is None: + return None + parts.append(text) + return '\n'.join(parts) if parts or any(op == '<<<' for op, _ in cmd['redirs']) else None + + +def redir_texts(op, w, env): + """Every text the word of a redirection can be (`<<< word` is not split into words).""" + return list(dict.fromkeys((' ' if op == '<<<' else '').join(r) for r in readings({'words': [w]}, env))) + + +def fed_texts(cmd, env, ctx): + """The texts a command reads from `<<< word` and `< file`, in every reading; what cannot be read is left out.""" + out = [] + for op, w in cmd['redirs']: + if op in ('<<<', '<'): + for word in redir_texts(op, w, env): + text = word if op == '<<<' else read_named(word, ctx) + if text and text not in out: + out.append(text) + return out + + +def pure_sink(variants): + """Whether a command ends the text piped into it: in every reading its command word only handles text.""" + for toks in variants: + h, via = head(toks) if toks else (None, set()) + if h is None or via or hidden(toks[h]) or os.path.basename(toks[h]) not in DATA - NO_SINK \ + or ('/' in toks[h] and os.path.dirname(toks[h]) not in STD_BINS): + return False + return bool(variants) + + +def stopped(text, what, flow, hint=''): + """The guard stopped reading (a limit, a file it cannot read whole): refused when the text it did not read names + a guarded token, else the command counts as running a word the guard cannot read (flow_reason).""" + if LOOSE_RE.search(text) or named(text): + return reason(what, hint) + flow['unknown'] = what + return None + + +def decide_text(text, ctx, scan_raw=True): + nest, flow = ctx.get('nest', 0), ctx.setdefault('flow', {}) + if ctx.get('stop_at') is not None and time.monotonic() > ctx['stop_at']: + raise Slow() + if nest > MAX_NEST: + return stopped(text, 'shell text nested too deep to read', flow) + cmds, plain, taint, rest = parse(text) + if rest: # more than 400 $(..) `..` <(..): what was not read is no harmless text + r = stopped('\n'.join(rest) + '\n' + text, 'more than 400 $(..), `..` or <(..) in one text, more than the ' + 'guard reads', flow, 'Run it as smaller commands.') + if r: + return r + env = variables(cmds, taint) + env['base'] = {'HOME': ctx['env'].get('HOME') or ''} + runs = [(c, readings(c, env)) for c in cmds] + firsts = [r[0] for _, r in runs if r[0]] + loose = any(reads_stdin_as_shell(t) for t in firsts) + funcs, aliases, cfg = set(), {}, list(ctx.get('cfg', ())) + ran = {'shell': set(), 'exec': set(), 'code': set()} # the files the text runs, by how: see written() + for m in FUNC_RE.finditer(plain): + funcs.add(m.group(1) or m.group(2)) + for toks in (t for _, r in runs for t in r if t): + h, via = head(toks) + if h is None: + continue + word = os.path.basename(toks[h]) + if INTERPRETERS.match(word): + ran['code'].update(os.path.basename(a) for a in positional(toks[h + 1:], set())[:1]) + elif word: + ran['shell' if 'shell' in via else 'exec'].add(word) + for toks in firsts: + h, _ = head(toks) + if h is None: + continue + word = os.path.basename(toks[h]) + if word == 'alias': + for a in toks[h + 1:]: + name, eq, val = a.partition('=') + if eq: + aliases.setdefault(name, []).append(val) + cwds, lost = list(folders(ctx)), False # where the commands may run: `cd a && ./x` runs a/x + every = cwds[-1] # the folder after every `cd` so far worked + for toks in firsts: + h, _ = head(toks) + if h is not None and toks[h] in ('cd', 'pushd', 'popd'): + to = [a for a in toks[h + 1:] if not a.startswith('-')][:1] + if to and not hidden(to[0]): + every = resolve_path(to[0], every) + if to and not hidden(to[0]) and len(cwds) < 16: + cwds += [p for p in dict.fromkeys(resolve_path(to[0], d) for d in cwds) if p not in cwds] + else: + lost = True + cwds += [every] if to and not hidden(to[0]) and every not in cwds else [] # past 16: one per cd + r = to and not hidden(to[0]) and stopped(text, 'more than 16 folders to follow (cd)', flow, + 'Run it as smaller commands.') + if r: + return r + cfg_hidden, closed = ctx.get('cfg_hidden', False), dict(env, open=False) + for name, tail in (('GH_CONFIG_DIR', ''), ('XDG_CONFIG_HOME', 'gh'), ('HOME', '.config/gh')): + dirs = var_texts(name, closed) if name in env['set'] else [] + cfg += [resolve_path(os.path.join(d, tail), w) for d in dirs if d and not hidden(d) for w in cwds] + cfg_hidden = cfg_hidden or (name in env['standalone'] and any(hidden(d) for d in dirs)) or \ + (lost and any(d and not hidden(d) and not os.path.isabs(os.path.expanduser(d)) for d in dirs)) + c = dict(ctx, raw=plain if scan_raw else ctx.get('raw', text), scan_raw=scan_raw, nest=nest + 1, funcs=funcs, + aliases=aliases, cfg=cfg, cfg_hidden=cfg_hidden, cwds=cwds) + gh_set = list(ctx.get('gh_set', ())) + for cmd, variants in runs: + for toks in variants: + gh_set += [a for a in text_aliases(toks, stdin_of(cmd, env, c), c) if a not in gh_set] + c['gh_set'] = gh_set + c['ghs'] = set(ctx.get('ghs', ())).union(*(gh_names(toks) for _, variants in runs for toks in variants if toks)) + # Where each command's text goes on: into a file, into another command's words ($(..)), or down a pipe that + # does not end in a word that only handles text. + tgts = [[t for op, w in cmd['redirs'] if op.startswith('>') for t in redir_texts(op, w, env) + if not NO_FILE.fullmatch(t)] for cmd, _ in runs] + leaks = [False] * len(runs) + for k in range(len(runs) - 1, -1, -1): + piped = runs[k][0].get('pipe') and k + 1 < len(runs) + leaks[k] = bool(runs[k][0].get('sub') or tgts[k] or (piped and (leaks[k + 1] or not pure_sink(runs[k + 1][1])))) + hows = [written(variants[0], cmd, env, ran) for cmd, variants in runs] + for how, (cmd, variants) in zip(hows, runs): # .. | tee x.sh; sh x.sh: the script comes through a pipe + h, _ = head(variants[0]) + if how in ('shell', 'exec') and not cmd['docs'] and h is not None \ + and os.path.basename(variants[0][h]) not in ('echo', 'printf'): + loose = True + for k, (how, (cmd, variants)) in enumerate(zip(hows, runs)): + fed = list(cmd['docs']) + fed_texts(cmd, env, c) # heredocs, <<< words, < files + for op, w in cmd['redirs']: # bash < big.sh: a file the shell runs that the guard could not read whole + if op == '<' and stdin_runs(variants[0], how, loose): + r = next((r for word in redir_texts(op, w, env) if not hidden(word) for d in folders(c) + for r in [unread(resolve_path(word, d))] if r), None) + if r: + return r + for body in fed: + kind = doc_kind(variants[0], how, loose, body) + tok = kind == 'code' and named(body) + if tok: + return unproven(tok, 'in inline code (a heredoc into an interpreter, or a script in another ' + 'language that the same command writes and runs): the guard reads shell text ' + 'and gh/curl calls, not code', CODE_HINT) + if kind in ('shell', 'script'): + r = decide_text(body, c) + if r: + return r + feeds = bool(cmd.get('pipe')) and k + 1 < len(runs) and stdin_runs(runs[k + 1][1][0], hows[k + 1], loose) + cc = dict(c, stdin=stdin_of(cmd, env, c), writes=how, cmd=cmd, leak=leaks[k], targets=tgts[k], feeds_code=feeds) + for toks in variants: + r = toks and segment_reason(toks, cc, loose) + if r: + return r + return None + + +def settings_files(env, cwd): + home = env.get('HOME') or os.path.expanduser('~') + pats = [os.path.join(home, '.claude*', 'settings*.json'), os.path.join(cwd, '.claude', 'settings*.json'), + '/etc/claude-code/*.json'] + if env.get('CLAUDE_CONFIG_DIR'): + pats.append(os.path.join(env['CLAUDE_CONFIG_DIR'], 'settings*.json')) + out = set() + for p in pats: + out.update(glob.glob(p)) + return sorted(out) + + +def decide(cmd, cwd, env, budget=None): + """None to let the command run, else the deny reason. budget: seconds the reading may take (None: no limit).""" + if not cmd or (QUICK and quick_pass(cmd)): + return None + ctx = {'cwd': cwd or os.getcwd(), 'env': env, 'depth': 0, 'raw': cmd, 'all': cmd, 'memo': {}, 'flow': {}, + 'stop_at': None if budget is None else time.monotonic() + budget, 'cache': {}} + try: + why = decide_text(cmd, ctx) or flow_reason(ctx['flow']) + except Slow: + why = SLOW + ctx['cache'] = {} # a reading cut off half-way keeps nothing + if why: + why = owner_marker(why, cmd, cwd, env) + try: # last, with the answer known: an alarm or a failure in it changes nothing + cache_save(ctx) + except BaseException: + pass + return why + + +def owner_marker(why, cmd, cwd, env): + """The refusal, or None when the owner marker of today lets this one command through.""" + today = dt.datetime.now(dt.timezone.utc).strftime('%Y-%m-%d') + if env.get(MARK_ENV) == today and MARK_CMD in cmd: + for f in settings_files(env, cwd or os.getcwd()): + try: + with open(f, encoding='utf-8', errors='replace') as fh: + found = MARK_ENV in fh.read() + except OSError: + found = True # a settings file that cannot be read may hold it + if found: + return why + f' (The owner marker is refused: {MARK_ENV} is in the settings file {f}, or the ' \ + 'file cannot be read; only the owner sets it, by hand, when starting a session.)' + return None + return why + + +def redact(s): + s = re.sub(r'(gh[pousr]_|github_pat_)[A-Za-z0-9_]+', r'\1***', s) + s = re.sub(r'(?i)(bearer\s+|token[=:\s]+)\S+', r'\1***', s) + return s[:300] + + +def log(cmd, why, env): + """One line per refusal. Written after the answer, and only until 2 s past the budget: a slow disk must not + keep the hook past its limit (a hook that is cut off answers nothing).""" + try: + left = BUDGET + 2.0 - process_age() + if left <= 0: + return + if hasattr(signal, 'SIGALRM'): + signal.signal(signal.SIGALRM, out_of_time) + signal.setitimer(signal.ITIMER_REAL, left) + d = state_dir(env) or state_dir({'HOME': os.path.expanduser('~')}) + if not d: + return + os.makedirs(d, exist_ok=True) + with open(os.path.join(d, 'log'), 'a') as f: + f.write(time.strftime('%Y-%m-%dT%H:%M:%SZ ', time.gmtime()) + json.dumps( + {'cmd': redact(cmd), 'why': why[:160], 'cwd': os.getcwd()}) + '\n') + except BaseException: # also Slow: the answer is out already + pass + finally: + alarm_off() + + +ANSWERED = [] + + +def deny(why): + print(json.dumps({'hookSpecificOutput': {'hookEventName': 'PreToolUse', 'permissionDecision': 'deny', + 'permissionDecisionReason': why}}), flush=True) + ANSWERED.append(True) + + +def alarm_off(): + if hasattr(signal, 'SIGALRM'): + signal.setitimer(signal.ITIMER_REAL, 0) + + +def main(): + """The hook. Exit 1 or no answer lets the command run, so whatever happens on the way ends in an answer: a + late Slow or a crash in the handlers below (named, log, deny) still refuses.""" + del ANSWERED[:] + try: + return answer() + except BaseException as e: + alarm_off() + if ANSWERED: # a second answer would break the first one (two JSON objects are no answer) + return 0 + deny(reason(f'the guard itself failed ({type(e).__name__}) while it answered, so it refuses; tell the owner ' + 'if this repeats')) + return 0 + + +def answer(): + raw, env = '', dict(os.environ) + try: + # The limit counts from the start of the hook process (Python's start-up and a slow machine use it up too), + # so the guard answers BUDGET seconds after that start at the latest: 5 s before the hook's 10 s limit. + # A command the fast exit passes needs no time, so the clock is looked at only after that. + left = BUDGET - process_age() + if hasattr(signal, 'SIGALRM'): # also when one long step never comes back to the clock check + signal.signal(signal.SIGALRM, out_of_time) + signal.setitimer(signal.ITIMER_REAL, max(left, 0.5)) # reading stdin may hang + raw = sys.stdin.read() + if SETTINGS_PROBLEM: + try: + sys.stderr.write('actions-disable-guard: the machine file\'s "agent-guards" section cannot be used ' + f'({SETTINGS_PROBLEM}); built-in defaults used. Run `agent-guards self-check`.\n') + except Exception: # noqa: BLE001 + pass + if env.get('ACTIONS_DISABLE_GUARD_TEST_CRASH'): + raise RuntimeError('test crash') + ev = json.loads(raw) + if ev.get('tool_name') != 'Bash': + alarm_off() + return 0 + cmd = (ev.get('tool_input') or {}).get('command') or '' + if QUICK and quick_pass(cmd): + alarm_off() + return 0 + left = BUDGET - process_age() + if left <= 0: + raise Slow() + why = decide(cmd, ev.get('cwd') or os.getcwd(), env, max(left - 1.0, 0.0)) + alarm_off() + except Slow: + alarm_off() # first: the handlers below must not be cut off by the alarm (that answers nothing) + why, cmd = SLOW, raw + except Exception as e: + alarm_off() + # also when quotes split the words, or the word is put together from variables: gh or an HTTP client is enough + try: + tok = named(raw) + except Exception: + tok = True + if tok or LOOSE_RE.search(raw) or LOOSE_RE.search(re.sub(r'["\'\\]', '', raw)) or CRASH_RE.search(raw): + why = reason(f'the guard itself failed ({type(e).__name__}) on a command that uses gh or an HTTP client ' + 'or names disabling Actions, so it refuses; tell the owner if this repeats') + cmd = raw + else: + return 0 + if why: + deny(why) # first: logging may be slow + log(cmd, why, env) + return 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/fork-kit/agent-guards/bin/agent-guards b/fork-kit/agent-guards/bin/agent-guards new file mode 100755 index 0000000000000..babf783216390 --- /dev/null +++ b/fork-kit/agent-guards/bin/agent-guards @@ -0,0 +1,77 @@ +#!/usr/bin/python3 -IB +"""agent-guards: the command of the agent-guards kit (fork-kit/agent-guards/README.md). + + agent-guards self-check the machine file's "agent-guards" section, the hook files, the managed + settings drop-in (exit 1 on a problem) + agent-guards check [--settings F] run each hook wired in F (default: the managed settings drop-in) with one + case it must refuse and one it must pass (exit 1 on a problem) + agent-guards hooks [--bin DIR] print the "hooks" settings of every hook of the kit, for a settings file +""" +import argparse, json, os, sys + +_kit = os.path.dirname(os.path.dirname(os.path.realpath(__file__))) +sys.path.insert(0, os.path.join(_kit, 'lib')) + +PROG = 'agent-guards' + + +def self_check(bin_dir, drop_in): + from agent_guards import config, wiring + problems, notes = [], [] + settings, cfg_problems = config.load_all() + problems += [f'machine file: {p} (the hooks use their built-in defaults)' for p in cfg_problems] + for hook in wiring.HOOKS: + if not os.access(os.path.join(bin_dir, hook), os.R_OK): + problems.append(f'{os.path.join(bin_dir, hook)} is missing or cannot be read') + try: + with open(drop_in, encoding='utf-8') as f: + text = f.read() + if json.loads(text) != {'hooks': wiring.hooks()}: + problems.append(f'{drop_in} is not the kit\'s drop-in of this release: run the installer again ' + '(agent-guards-install install ... --settings)') + else: + notes.append(f'{drop_in}: every hook is wired in managed settings') + except FileNotFoundError: + notes.append(f'{drop_in} is not there: the hooks are not in managed settings (installer --settings, or ' + 'by hand from `agent-guards hooks`)') + except (OSError, ValueError) as e: + problems.append(f'{drop_in} cannot be read ({e})') + for hook, s in settings.items(): + notes.append(f'{hook}: {json.dumps(s, sort_keys=True)}') + for n in notes: + print(f'note: {n}') + for p in problems: + print(f'PROBLEM: {p}') + print(f'{PROG} self-check: ' + ('OK' if not problems else f'{len(problems)} problem(s)')) + return 0 if not problems else 1 + + +def main(argv): + if argv in (['-h'], ['--help']): + print(__doc__.strip()) + return 0 + from agent_guards import check, wiring + ap = argparse.ArgumentParser(prog=PROG) + sub = ap.add_subparsers(dest='cmd', required=True) + sub.add_parser('self-check') + c = sub.add_parser('check') + c.add_argument('--settings', default=wiring.DROP_IN) + h = sub.add_parser('hooks') + h.add_argument('--bin', default=wiring.BIN) + a = ap.parse_args(argv) + if a.cmd == 'self-check': + return self_check(os.path.dirname(os.path.realpath(__file__)), wiring.DROP_IN) + if a.cmd == 'hooks': + print(json.dumps({'hooks': wiring.hooks(a.bin)}, indent=2)) + return 0 + try: + with open(a.settings, encoding='utf-8') as f: + settings = json.load(f) + except (OSError, ValueError) as e: + print(f'{PROG}: cannot read {a.settings} ({e})', file=sys.stderr) + return 1 + return check.run(settings, a.settings) + + +if __name__ == '__main__': + sys.exit(main(sys.argv[1:])) diff --git a/fork-kit/agent-guards/bin/agent-slots b/fork-kit/agent-guards/bin/agent-slots new file mode 100755 index 0000000000000..b7fdd078ef6ff --- /dev/null +++ b/fork-kit/agent-guards/bin/agent-slots @@ -0,0 +1,97 @@ +#!/usr/bin/python3 -IB +"""Claude Code hook for orchestrator sessions: "agent slots free + ready queue not empty = don't stop yet". +Part of fork-kit/agent-guards (README.md there: install, settings entries, the machine file's "agent-guards" section). + +UserPromptSubmit: adds one line of context: live agent processes, free slots, the first items of the ready queue. +Stop: if slots are free and the ready queue has items, blocks the stop once (not again while stop_hook_active). +Acts only for the session ids in sessionsFile; every other session exits at once (one file read). Read only: it +writes nothing, so two at once need no lock. + +General (any project, any Claude config dir). Project facts come from the machine file (agentSlots): + sessionsFile one session id per line, # comments (default "": the hook does nothing) + queue a markdown file; its ready list is the "- " lines under readyHeading (default "## Ready") + maxAlive agent processes at most (default 10); processName the process counted (default "claude") + note extra text for the context line, e.g. a build-agent limit (default "") +Never fails a call because of its own error. A broken machine file section: the defaults (so it does nothing) and +one line on stderr. Tests: fork-kit/agent-guards/tests/agent-slots.test.py +""" +import json, os, subprocess, sys + + +def _settings(): + """(agentSlots settings, problem or None); a copy without the kit's lib keeps the defaults and says so.""" + try: + sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.realpath(__file__))), 'lib')) + from agent_guards import config + c, problem = config.load('agentSlots') + for k in ('sessionsFile', 'queue'): + c[k] = config.expand(c[k]) + return c, problem + except BaseException as e: # noqa: BLE001 + return ({'sessionsFile': '', 'queue': '', 'readyHeading': '## Ready', 'maxAlive': 10, 'processName': 'claude', + 'note': ''}, f'cannot load the kit\'s config code ({type(e).__name__}: {e})') + + +def lines(path): + try: + with open(path) as f: + return f.read().split('\n') + except OSError: + return [] + + +def ready_items(c): + out, on = [], False + for line in lines(c['queue']): + if line.startswith('## '): + on = line.strip().lower() == c['readyHeading'].strip().lower() + elif on and line.startswith('- '): + out.append(line[2:].strip()) + return out + + +def alive(c): + r = subprocess.run(['pgrep', '-c', '-x', c['processName']], capture_output=True, text=True) + return int((r.stdout or '0').strip() or 0) + + +def decide(data, c): + sessions = {l.strip() for l in lines(c['sessionsFile']) if l.strip() and not l.startswith('#')} + if not c['sessionsFile'] or data.get('session_id') not in sessions: + return None + event = data.get('hook_event_name', '') + n = alive(c) + mx = int(c['maxAlive']) + free = max(0, mx - n) + ready = ready_items(c) + head = '; '.join(ready[:3]) + msg = (f'Agent slots: {n}/{mx} {c["processName"]} processes alive, {free} free' + + (f' ({c["note"]})' if c['note'] else '') + '. ' + f'Ready queue ({c["queue"]}): {len(ready)} item(s){": " + head if head else ""}.') + if event == 'UserPromptSubmit': + return {'hookSpecificOutput': {'hookEventName': 'UserPromptSubmit', 'additionalContext': msg}} + if event == 'Stop' and not data.get('stop_hook_active') and free and ready: + return {'decision': 'block', 'reason': msg + ' Fill the free slots from the ready queue before ending the ' + 'turn (read the issue first). If an item cannot start now, move it out of the ready list with the reason.'} + return None + + +def main(): + if sys.argv[1:]: + sys.stderr.write('usage: agent-slots (hook: UserPromptSubmit or Stop JSON on stdin)\n') + return 1 + try: + c, problem = _settings() + if problem: + sys.stderr.write('agent-slots: the machine file\'s "agent-guards" section cannot be used ' + f'({problem}); built-in defaults used. Run `agent-guards self-check`.\n') + out = decide(json.load(sys.stdin), c) + except Exception: # never break a call because of this hook + return 0 + if out: + print(json.dumps(out)) + return 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/fork-kit/agent-guards/bin/bg-guard b/fork-kit/agent-guards/bin/bg-guard new file mode 100755 index 0000000000000..aec0837259714 --- /dev/null +++ b/fork-kit/agent-guards/bin/bg-guard @@ -0,0 +1,150 @@ +#!/usr/bin/python3 -IB +"""Claude Code Stop hook: don't let an agent end its turn while a Bash command it started in the background still runs. +Part of fork-kit/agent-guards (README.md there: install, settings entry, the machine file's "agent-guards" section). + +Why: in some hosts (child threads, headless runs) the end of a background command never wakes the agent, so it +stalls for hours (several agents did). This hook blocks such a stop once per try and tells the agent to wait in the +foreground. At most maxBlocks blocks per session, so a deliberate leftover (a test server) never loops. + +General (any project, any Claude config dir). Settings, all optional (machine file, bgGuard): + skipSessionsFiles files with one session id per line (# comments): sessions never blocked (e.g. orchestrators + that are woken another way); default none + maxBlocks blocks per session at most (default 3) + stateDir the per-session block counts (default ~/.local/state/bg-guard); a count is read and raised + under a lock, so two Stop hooks at once count two blocks +Never fails a stop because of its own error (exit 0 on anything unexpected). A broken machine file section: the +defaults, and one line on stderr. Tests: fork-kit/agent-guards/tests/bg-guard.test.py +""" +import fcntl, json, os, sys + +CLAUDE = 'claude' # Claude Code's process name +SNAPSHOT = 'shell-snapshots/snapshot-' # in the command line of each of its Bash tool commands + + +def _settings(): + """(bgGuard settings, problem or None); a copy without the kit's lib keeps the defaults and says so.""" + try: + sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.realpath(__file__))), 'lib')) + from agent_guards import config + c, problem = config.load('bgGuard') + c['stateDir'] = config.expand(c['stateDir']) + c['skipSessionsFiles'] = [config.expand(f) for f in c['skipSessionsFiles']] + return c, problem + except BaseException as e: # noqa: BLE001 - the guard works without its config + return ({'skipSessionsFiles': [], 'maxBlocks': 3, 'stateDir': os.path.expanduser('~/.local/state/bg-guard')}, + f'cannot load the kit\'s config code ({type(e).__name__}: {e})') + + +def cmdline(pid): + try: + return open(f'/proc/{pid}/cmdline', 'rb').read().replace(b'\0', b' ').decode(errors='replace').strip() + except OSError: + return '' + + +def ppid(pid): + try: + return int(open(f'/proc/{pid}/stat').read().rsplit(')', 1)[1].split()[1]) + except (OSError, IndexError, ValueError): + return 0 + + +def claude_pid(start): + pid = start + while pid > 1: + if os.path.basename(cmdline(pid).split(' ', 1)[0]) == CLAUDE: + return pid + pid = ppid(pid) + return 0 + + +def background_commands(root, mine): + """Bash tool commands still running under this claude process (children of it, not this hook's own chain).""" + out = [] + for d in os.listdir('/proc'): + if not d.isdigit() or int(d) in mine or ppid(int(d)) != root: + continue + c = cmdline(int(d)) + if SNAPSHOT in c: + i = c.rfind(" eval '") + out.append((c[i + 7:].split("' < /dev/null", 1)[0] if i >= 0 else c[-140:])[:140]) + return out + + +def skipped(c): + s = set() + for f in c['skipSessionsFiles']: + try: + with open(f) as fh: + s |= {l.strip() for l in fh if l.strip() and not l.startswith('#')} + except OSError: + pass + return s + + +def count_block(c, sid): + """Raise the session's block count when it is below maxBlocks: True when this stop may be blocked. Under a lock + (two Stop hooks at once count two). A state folder that cannot be written blocks no stop (as before).""" + os.makedirs(c['stateDir'], exist_ok=True) + f = os.path.join(c['stateDir'], ''.join(ch for ch in sid if ch.isalnum() or ch == '-')[:64] + '.count') + fd = os.open(f, os.O_RDWR | os.O_CREAT, 0o600) + try: + fcntl.flock(fd, fcntl.LOCK_EX) + try: + n = int(os.read(fd, 64).decode().strip() or 0) + except ValueError: + n = 0 + if n >= int(c['maxBlocks']): + return False + os.lseek(fd, 0, os.SEEK_SET) + os.ftruncate(fd, 0) + os.write(fd, str(n + 1).encode()) + return True + finally: + os.close(fd) + + +def decide(data, c, start_pid): + sid = data.get('session_id') or '' + if not sid or sid in skipped(c): + return None + root = claude_pid(start_pid) + if not root: + return None + mine, p = set(), os.getpid() + while p > 1: + mine.add(p) + p = ppid(p) + running = background_commands(root, mine) + if not running: + return None + if not count_block(c, sid): + return None + return {'decision': 'block', 'reason': + 'You are ending your turn while a command you started in the background is still running: ' + + ' | '.join(running[:3]) + + '. Its completion will NOT wake you, so you would stall. Wait for it in the foreground now ' + '(a loop that checks its output file every 60 s, with a long timeout), then continue your task. ' + 'If you really mean to leave it running (e.g. a test server) and something else will wake you, say so ' + 'and stop again.'} + + +def main(): + if sys.argv[1:]: + sys.stderr.write('usage: bg-guard (hook: Stop JSON on stdin)\n') + return 1 + try: + c, problem = _settings() + if problem: + sys.stderr.write('bg-guard: the machine file\'s "agent-guards" section cannot be used ' + f'({problem}); built-in defaults used. Run `agent-guards self-check`.\n') + out = decide(json.load(sys.stdin), c, os.getppid()) + except Exception: # never break a stop because of this guard + return 0 + if out: + print(json.dumps(out)) + return 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/fork-kit/agent-guards/bin/capacity-pipe-guard b/fork-kit/agent-guards/bin/capacity-pipe-guard new file mode 100755 index 0000000000000..1a9676be376a0 --- /dev/null +++ b/fork-kit/agent-guards/bin/capacity-pipe-guard @@ -0,0 +1,350 @@ +#!/usr/bin/python3 -IB +"""Claude Code PreToolUse hook (Bash, Monitor): refuse a command that pipes the output of a capacity check. +Part of fork-kit/agent-guards (README.md there: install, settings entry, the machine file's "agent-guards" section). + +The checks are the commands in the machine file's capacityPipe.commands (default ["t3-capacity"]): a tool that +answers OK (exit 0) or NOT OK (exit 1) before a heavy step. Why: agents ran `t3-capacity 2048 | tail -1 && `. A pipeline's exit status is its LAST command's, so NOT OK (exit 1) was lost and the heavy step ran on a full +machine. A line in the agents' briefs did not stop it. + +Rule: EVERY pipe (`|`, `|&`) out of such a command is refused, also one that decides nothing (`t3-capacity | cat`) +and one under `set -o pipefail`: nothing needs the pipe, and "is the status used" cannot be read from the text +reliably. Passes: `t3-capacity N && cmd`, `t3-capacity`, `t3-capacity; echo $?`, `if t3-capacity N; then ..`, +`t3-capacity N > file && cmd`, `out=$(t3-capacity N) && cmd`, `t3-capacity N || ..`, and a group that gates inside +and is piped as a whole (`{ t3-capacity N && cmd; } | tail`). + +How it reads a command (small on purpose; actions-disable-guard is the full shell reader, and what it guards is an +attack, this is a mistake): + - shell text as a shell reads it: quotes, backslashes, comments, redirections, `&& || ; & |` and newlines; + - the check must be the command word (any path; after NAME=value, `!`, if/while/until/then/do/else, and the + wrappers sudo, env, command, exec, nohup, nice, ionice, timeout, stdbuf, setsid, time, builtin with their flags); + - commands inside `$(..)`, backticks, `<(..)`, and a `( .. )` or `{ ..; }` group whose LAST command is the check; + - shell text handed on, read again by the same rules: `bash -c '..'` (sh, zsh, dash, ksh, su; also behind another + word: `heavy bash -c`, `timeout 60 bash -lc`), `eval ..`, `ssh host '..'`, `watch '..'`, and a heredoc into a shell. +Text that only mentions it passes: echo, grep, commit messages, a heredoc into cat/tee/a file (briefs), comments. + +Not covered (the check's own stderr line is the second layer when it has one: say "NOT OK .. never pipe it" on +stderr whenever it answers NOT OK into a pipe or a file): a command kept in a variable (`$C | tail`), a script file, +`sh t3-capacity`, a heredoc piped into a shell (`cat <` +would exit 2 and refuse every Bash call). A broken machine file section: the default command list, one line on +stderr. Tests: fork-kit/agent-guards/tests/capacity-pipe.test.py +""" +import json, os, re, sys + + +def _settings(): + """(capacityPipe settings, problem or None); a copy without the kit's lib keeps the defaults and says so.""" + try: + sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.realpath(__file__))), 'lib')) + from agent_guards import config + return config.load('capacityPipe') + except BaseException as e: # noqa: BLE001 - the guard works without its config + return {'commands': ['t3-capacity']}, f'cannot load the kit\'s config code ({type(e).__name__}: {e})' + + +SETTINGS, SETTINGS_PROBLEM = _settings() +CHECKS = tuple(SETTINGS['commands']) # the capacity checks whose output must not be piped +NAME = 'capacity-pipe-guard' +HID = '\x00' # text the guard cannot know ($X, ${..}, the output of $(..)), as part of a word +MAX_DEPTH = 40 +SHELLS = {'sh', 'bash', 'zsh', 'dash', 'ksh', 'su'} # ` .. -c TEXT`; a heredoc into one is commands +TEXT_ARGS = {'ssh', 'watch'} # each argument that names the tool is shell text +TOOLS = {'Bash', 'Monitor'} # the tools whose `command` is shell text +WRAPPERS = { # a command follows them; value: their one-letter flags whose value is the NEXT word (sudo -u someone) + 'sudo': 'ughpCDRTUrt', 'env': 'uCS', 'timeout': 'ks', 'nice': 'n', 'ionice': 'cnp', 'stdbuf': 'ioe', 'exec': 'a', + 'time': 'fo', 'command': '', 'builtin': '', 'nohup': '', 'setsid': ''} +KEYWORDS = {'!', '{', 'if', 'then', 'elif', 'else', 'while', 'until', 'do'} # a command follows them +OPENERS = {'{', 'if', 'while', 'until'} # ... and these open a group that CLOSERS end +HEADS = {'for', 'case', 'select'} # open a group too; the rest of their line is no command +CLOSERS = {'}', 'fi', 'done', 'esac'} +ASSIGN = re.compile(r'[A-Za-z_]\w*\+?=') +PLAIN = re.compile(r'-|\d+(\.\d+)?[smhd]?$') # a wrapper's flag, or its number / duration (timeout 5m, nice 10) +FLAGS = re.compile(r'-[A-Za-z]+$') # -u, -iu: the last letter decides whether a value follows +C_FLAG = re.compile(r'-[A-Za-z]*c[A-Za-z]*$') # -c, -lc, -ec +REDIR = re.compile(r'&>>|&>|<<<|<<-|<<|<>|<&|>>|>&|>\||<|>') +VAR = re.compile(r'\$(?:[A-Za-z_]\w*|[0-9@*#?$!-])') + + +def reason(tool): + return (f'Refused by {NAME}: this command pipes the output of {tool} (`{tool} N | ...`). A pipeline has the exit ' + f'status of its LAST command, so NOT OK (exit 1) is lost and the step after `&&` runs on a full machine. ' + f'Every pipe out of {tool} is refused, also a harmless one: nothing needs it. Gate with ' + f'`{tool} N && ` (or `if {tool} N; then ..`, `{tool} N; echo $?`). For less output: ' + f'`{tool} N > "$f" && ` or `out=$({tool} N) && `. Text that only mentions such a command ' + f'(echo, grep, a commit message, a heredoc into a file) is not refused.') + + +REASON = reason(CHECKS[0]) + + +class Piped(Exception): + """The command pipes a check's output (args[0]: the check).""" + + +def base(word): + return word.rsplit('/', 1)[-1] + + +def command_at(ws): + """Index of the command word of a simple command: behind NAME=value and wrappers. len(ws) when there is none.""" + i = 0 + while i < len(ws): + if ASSIGN.match(ws[i]): + i += 1 + continue + if base(ws[i]) not in WRAPPERS: + return i + asks, values = base(ws[i]) == 'command', WRAPPERS[base(ws[i])] + i += 1 + while i < len(ws) and (PLAIN.match(ws[i]) or ASSIGN.match(ws[i])): + if asks and ws[i] in ('-v', '-V'): + return len(ws) # `command -v x` only looks x up + i += 2 if FLAGS.match(ws[i]) and ws[i][-1] in values else 1 + return len(ws) + + +def handed_on(ws, depth): + """Read the shell text a simple command hands on. True when a shell is among its words (its heredoc is commands).""" + shell = False + for k, w in enumerate(ws): + if base(w) in SHELLS: + shell = True + elif shell and C_FLAG.match(w) and k + 1 < len(ws): + read(ws[k + 1], depth=depth + 1) + break + k = command_at(ws) + if k < len(ws): + word, args = base(ws[k]), ws[k + 1:] + if word == 'eval': + read(' '.join(args), depth=depth + 1) + elif word in TEXT_ARGS: + for a in args: + if any(t in a for t in CHECKS): + read(a, depth=depth + 1) + return shell + + +def dollar(s, i, out, depth): + """s[i] is `$` or a backtick: commands inside are read, the value is hidden. Returns the index behind it.""" + n = len(s) + if s[i] == '`': + j, buf = i + 1, [] + while j < n and s[j] != '`': + if s[j] == '\\' and s[j + 1:j + 2] in ('`', '\\', '$'): + j += 1 + buf.append(s[j]) + j += 1 + read(''.join(buf), depth=depth + 1) + out.append(HID) + return j + 1 + nxt = s[i + 1:i + 2] + if nxt == '(': + out.append(HID) + return read(s, i + 2, ')', depth + 1) + if nxt == '{': + j, open_ = i + 2, 1 + while j < n and open_: + open_ += (s[j] == '{') - (s[j] == '}') + j += 2 if s[j] == '\\' else 1 + out.append(HID) + return j + m = VAR.match(s, i) + out.append(HID if m else '$') + return m.end() if m else i + 1 + + +def word(s, i, depth): + """One word from s[i:], as the shell would hand it on (quotes gone): (text, index behind it).""" + n, out = len(s), [] + while i < n and s[i] not in ' \t\n;&|()<>': + c = s[i] + if c == '\\': + if s[i + 1:i + 2] != '\n': + out.append(s[i + 1:i + 2]) + i += 2 + elif c == "'": + j = s.find("'", i + 1) + j = n if j < 0 else j + out.append(s[i + 1:j]) + i = j + 1 + elif c == '$' and s[i + 1:i + 2] == "'": + j = i + 2 + while j < n and s[j] != "'": + j += 1 if s[j] == '\\' else 0 + out.append(s[j:j + 1]) + j += 1 + i = j + 1 + elif c == '"': + i += 1 + while i < n and s[i] != '"': + if s[i] == '\\' and i + 1 < n: + if s[i + 1] != '\n': + out.append(s[i + 1] if s[i + 1] in '"\\$`' else s[i:i + 2]) + i += 2 + elif s[i] in '$`': + i = dollar(s, i, out, depth) + else: + out.append(s[i]) + i += 1 + i += 1 + elif c in '$`': + i = dollar(s, i, out, depth) + else: + out.append(c) + i += 1 + return ''.join(out), i + + +def heredoc(s, i, delim, tabs): + """(body, index behind it) of the heredoc that starts at s[i:].""" + lines = [] + while i < len(s): + j = s.find('\n', i) + j = len(s) if j < 0 else j + line, i = s[i:j], j + 1 + if (line.lstrip('\t') if tabs else line) == delim: + break + lines.append(line) + return '\n'.join(lines), min(i, len(s)) + + +def read(s, i=0, closer='', depth=0): + """Read the commands in s[i:], to the `)` that ends this $(..) (closer) or to the end; raise Piped where + a check's output goes into a pipe. Returns the index it stopped at.""" + n = len(s) + if depth > MAX_DEPTH or (i == 0 and not any(t in s for t in CHECKS)): # i == 0: once per text, not once per $(..) in it + return n # nothing (more) to find; past MAX_DEPTH the rest is not read + ws, doc, groups, pending = [], {}, [], [] + tool = False # the command or group that just ended is a check (its last command is): its name + + def end(): + nonlocal ws, doc, tool + cmd, ws, mine, doc = ws, [], doc, {} + while cmd and (cmd[0] in KEYWORDS or cmd[0] == 'function'): + if cmd[0] in OPENERS: + groups.append(cmd[0]) + cmd = cmd[2:] if cmd[0] == 'function' else cmd[1:] # `function NAME { ..`: the rest is a command + if not cmd: + return + if cmd[0] in HEADS: + groups.append(cmd[0]) + tool = False + elif cmd[0] in CLOSERS: + if groups and groups[-1] != '(': + groups.pop() # tool stays: the group ends with what its last command was + else: + k = command_at(cmd) + tool = base(cmd[k]) if k < len(cmd) and base(cmd[k]) in CHECKS else False + mine['shell'] = handed_on(cmd, depth) + + while i < n: + c = s[i] + if c in ' \t': + i += 1 + elif c == '\\' and s[i + 1:i + 2] == '\n': + i += 2 + elif c == '#': + j = s.find('\n', i) + i = n if j < 0 else j + elif c == '\n': + end() + i += 1 + for delim, tabs, owner in pending: + body, i = heredoc(s, i, delim, tabs) + if owner.get('shell'): + read(body, depth=depth + 1) + pending = [] + elif c == ';': + end() + i += 1 + elif c == '(': + end() + groups.append('(') + tool = False + i += 1 + elif c == ')': + end() + i += 1 + if groups and groups[-1] == 'case': + tool = False # the `)` of a case pattern + elif groups and groups[-1] == '(': + groups.pop() # tool stays, as for `}` + elif closer: + return i + else: + tool = False + elif c == '|': + end() + if s.startswith('||', i): + i += 2 + elif tool: + raise Piped(tool) + else: + i += 2 if s.startswith('|&', i) else 1 + tool = False + elif c == '&' and not s.startswith('&>', i): + end() + tool = False + i += 2 if s.startswith('&&', i) else 1 + elif c in '<>&': + op = REDIR.match(s, i).group() + i += len(op) + if op in ('<', '>') and s[i:i + 1] == '(': + i = read(s, i + 1, ')', depth + 1) # <(..) and >(..) are commands + continue + while i < n and s[i] in ' \t': + i += 1 + target, i = word(s, i, depth) + if op in ('<<', '<<-'): + pending.append((target, op == '<<-', doc)) + else: + text, j = word(s, i, depth) + if not (text.isdigit() and s[j:j + 1] in ('<', '>')): # the 2 of 2>&1 is no word + ws.append(text) + i = max(j, i + 1) + end() + return n + + +def piped(command): + """The check whose output this Bash command pipes, or None.""" + try: + read(command) + except Piped as e: + return e.args[0] + return None + + +def main(argv=None): + """Exit 2 with the reason on stderr refuses; 0 lets the command run; 1 (this guard failed) lets it run, loudly.""" + argv = sys.argv[1:] if argv is None else argv + if argv: + sys.stderr.write(f'usage: {NAME} (hook: PreToolUse JSON on stdin; its settings entry: `agent-guards hooks`)\n') + return 1 + try: + if SETTINGS_PROBLEM: + sys.stderr.write(f'{NAME}: the machine file\'s "agent-guards" section cannot be used ({SETTINGS_PROBLEM}); ' + 'built-in defaults used. Run `agent-guards self-check`.\n') + event = json.loads(sys.stdin.read()) + if event.get('tool_name') not in TOOLS: + return 0 + command = (event.get('tool_input') or {}).get('command') + tool = piped(command) if isinstance(command, str) else None + if not tool: + return 0 + except BaseException as e: # fail open: this guards a mistake, not an attack + sys.stderr.write(f'{NAME}: failed ({type(e).__name__}: {e}); the command is NOT checked and runs. ' + 'Tell the owner if this repeats.\n') + return 1 + sys.stderr.write(reason(tool) + '\n') + return 2 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/fork-kit/agent-guards/bin/memory-index-guard b/fork-kit/agent-guards/bin/memory-index-guard new file mode 100755 index 0000000000000..68c1f05bdad00 --- /dev/null +++ b/fork-kit/agent-guards/bin/memory-index-guard @@ -0,0 +1,189 @@ +#!/usr/bin/python3 -IB +"""Claude Code hook: keep the auto-memory index (MEMORY.md) inside a size budget, at the moment it changes. +Part of fork-kit/agent-guards (README.md there: install, settings entries, the machine file's "agent-guards" section). + +General (any project, any Claude config dir): the session's index is /memory/MEMORY.md. +Budget (machine file, memoryIndex): maxChars (default 6000) characters in total, maxLine (default 160) per line. + +- PreToolUse (Write/Edit/MultiEdit on a memory index): works out the new text and refuses the call when it would be + over budget, unless it shrinks an index that was already over (so cutting down is always allowed). +- PostToolUse (any tool, mainly Bash): if the index changed since this session last looked and is over budget, it + blocks with the reason, so the agent cuts it in the same turn. Cheap: one stat per call, the file is read only + after a change. State: / (default ~/.cache/memory-index-guard), written whole + (temp file, then rename), so two hooks at once leave one of their two answers, never half of one. + +Never fails a tool call because of its own error (exit 0 on anything unexpected). A broken machine file section: +the default budget, and one line on stderr. Tests: fork-kit/agent-guards/tests/memory-index.test.py +""" +import json, os, sys, tempfile, time + + +def _settings(): + """(memoryIndex settings, problem or None); a copy without the kit's lib keeps the defaults and says so.""" + try: + sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.realpath(__file__))), 'lib')) + from agent_guards import config + c, problem = config.load('memoryIndex') + c['stateDir'] = config.expand(c['stateDir']) + return c, problem + except BaseException as e: # noqa: BLE001 - the guard works without its config + return ({'maxChars': 6000, 'maxLine': 160, 'stateDir': os.path.expanduser('~/.cache/memory-index-guard')}, + f'cannot load the kit\'s config code ({type(e).__name__}: {e})') + + +SETTINGS, SETTINGS_PROBLEM = _settings() +MAX_CHARS = SETTINGS['maxChars'] +MAX_LINE = SETTINGS['maxLine'] +STATE = SETTINGS['stateDir'] + + +def problems(text): + out = [] + if len(text) > MAX_CHARS: + out.append(f'{len(text)} chars, budget {MAX_CHARS}') + long = [i + 1 for i, l in enumerate(text.split('\n')) if len(l) > MAX_LINE] + if long: + out.append(f'line(s) {", ".join(map(str, long[:8]))} longer than {MAX_LINE} chars') + return out + + +def badness(text): + return max(0, len(text) - MAX_CHARS) + sum(max(0, len(l) - MAX_LINE) for l in text.split('\n')) + + +def message(path, probs): + return (f'Memory index {path} is over budget: {"; ".join(probs)}. It is sent on every call of every session. ' + f'Cut it now: one line per memory, "- [Title](file.md) - hook" under {MAX_LINE} chars; merge duplicates, ' + 'delete memories a tool now enforces or that are only history, and keep detail in the memory files.') + + +def index_of(data): + t = data.get('transcript_path') or '' + return os.path.join(os.path.dirname(t), 'memory', 'MEMORY.md') if t else '' + + +def is_index(path, idx): + if not path or os.path.basename(path) != 'MEMORY.md': + return False + rp = os.path.realpath(path) + if idx and rp == os.path.realpath(idx): + return True + parts = rp.split(os.sep) + return len(parts) >= 4 and parts[-2] == 'memory' and parts[-4] == 'projects' + + +def read(path): + try: + with open(path, encoding='utf-8', errors='replace') as f: + return f.read() + except OSError: + return None + + +def pre(data): + name = data.get('tool_name') + ti = data.get('tool_input') or {} + path = ti.get('file_path') or '' + if name not in ('Write', 'Edit', 'MultiEdit') or not is_index(path, index_of(data)): + return None + old = read(path) or '' + if name == 'Write': + new = ti.get('content') or '' + else: + new = old + for e in (ti.get('edits') or [ti]): + o, n = e.get('old_string') or '', e.get('new_string') or '' + if not o or o not in new: + return None # the tool itself will refuse it + new = new.replace(o, n) if e.get('replace_all') else new.replace(o, n, 1) + probs = problems(new) + if not probs or badness(new) < badness(old): + return None + return {'hookSpecificOutput': {'hookEventName': 'PreToolUse', 'permissionDecision': 'deny', + 'permissionDecisionReason': message(path, probs)}} + + +def session_start(data): + try: + with open(data.get('transcript_path') or '') as f: + for _ in range(20): + line = f.readline() + if not line: + break + if '"timestamp"' in line: + ts = json.loads(line).get('timestamp') or '' + return time.mktime(time.strptime(ts[:19], '%Y-%m-%dT%H:%M:%S')) - time.timezone + except (OSError, ValueError): + pass + return time.time() + + +def save(sf, text): + """Whole or not at all: two runs at once each rename their own temp file; a state folder that cannot be written + only means the next call looks again.""" + tmp = None + try: + os.makedirs(STATE, exist_ok=True) + fd, tmp = tempfile.mkstemp(prefix='.' + os.path.basename(sf) + '.', dir=STATE) + with os.fdopen(fd, 'w') as f: + f.write(text) + os.replace(tmp, sf) + tmp = None + except OSError: + pass + finally: + if tmp: + try: + os.unlink(tmp) + except OSError: + pass + + +def post(data): + idx = index_of(data) + try: + st = os.stat(idx) + except OSError: + return None + sig = f'{st.st_mtime_ns} {st.st_size}' + sid = ''.join(c for c in (data.get('session_id') or 'none') if c.isalnum() or c == '-')[:64] + sf = os.path.join(STATE, sid) + try: + with open(sf) as f: + last = f.read().strip() + except OSError: + last = None + if last == sig: + return None + save(sf, sig) + if last is None and st.st_mtime < session_start(data): + return None # first look in this session, and nobody changed it since the session started + probs = problems(read(idx) or '') + if not probs: + return None + return {'decision': 'block', 'reason': message(idx, probs)} + + +def main(): + if sys.argv[1:]: + sys.stderr.write('usage: memory-index-guard (hook: PreToolUse or PostToolUse JSON on stdin)\n') + return 1 + if SETTINGS_PROBLEM: + try: + sys.stderr.write('memory-index-guard: the machine file\'s "agent-guards" section cannot be used ' + f'({SETTINGS_PROBLEM}); built-in defaults used. Run `agent-guards self-check`.\n') + except Exception: # noqa: BLE001 + pass + try: + data = json.load(sys.stdin) + ev = data.get('hook_event_name') + out = pre(data) if ev == 'PreToolUse' else post(data) if ev == 'PostToolUse' else None + except Exception: # never break a tool call because of this guard + return 0 + if out: + print(json.dumps(out)) + return 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/fork-kit/agent-guards/lib/agent_guards/__init__.py b/fork-kit/agent-guards/lib/agent_guards/__init__.py new file mode 100644 index 0000000000000..aa312933e1799 --- /dev/null +++ b/fork-kit/agent-guards/lib/agent_guards/__init__.py @@ -0,0 +1,6 @@ +"""agent_guards: the Claude Code hooks of fork-kit/agent-guards (README.md there). + + config the facts of the hooks, from the machine file's "agent-guards" section, with safe defaults + wiring the hooks' settings entries (Claude Code managed settings drop-in, or any settings file) + check run the wired hooks with one case each hook must refuse and one it must pass +""" diff --git a/fork-kit/agent-guards/lib/agent_guards/check.py b/fork-kit/agent-guards/lib/agent_guards/check.py new file mode 100644 index 0000000000000..a3f50d691d6cb --- /dev/null +++ b/fork-kit/agent-guards/lib/agent_guards/check.py @@ -0,0 +1,169 @@ +"""agent_guards.check: prove the wired hooks work. Each hook's command, as a settings file has it, is run with one +event it must refuse (block) and one it must let through, the way Claude Code runs it (`/bin/sh -c COMMAND`, the +event on stdin). Nothing of the machine is changed: the memory index and the session ids are made up in a temporary +folder, and the few state files the hooks write for those made-up sessions are removed afterwards. + +A hook that is not wired is reported as MISSING (a problem); agent-slots with no sessionsFile only gets its pass +case (it does nothing for any session then). +""" +import json, os, shutil, signal, subprocess, tempfile + +from . import config, wiring + +SESSION = 'agent-guards-check-' + + +def _run(cmd, event, cwd, env=None, argv=None, timeout=30): + """Run one case in a process group of its own, ended whole afterwards: a hook that hangs, or a background + command of a case, leaves nothing running.""" + p = subprocess.Popen(argv or ['/bin/sh', '-c', cmd], stdin=subprocess.PIPE, stdout=subprocess.PIPE, + stderr=subprocess.PIPE, text=True, cwd=cwd, env=env, start_new_session=True) + try: + out, err = p.communicate(json.dumps(event), timeout=timeout) + return subprocess.CompletedProcess(p.args, p.returncode, out, err) + except subprocess.TimeoutExpired: + _end(p) + p.communicate() + return subprocess.CompletedProcess(p.args, 124, '', f'timed out after {timeout} s') + finally: + _end(p) + + +def _end(p): + try: + os.killpg(p.pid, signal.SIGKILL) + except OSError: + pass + + +def _answer(r): + """What a hook said: 'refused' (exit 2, a deny or a block), 'context', or 'passed' (exit 0, nothing); any other + exit is 'failed (exit N)'.""" + try: + out = json.loads(r.stdout) if r.stdout.strip() else {} + except ValueError: + out = {} + out = out if isinstance(out, dict) else {} + spec = out.get('hookSpecificOutput') if isinstance(out.get('hookSpecificOutput'), dict) else {} + if r.returncode == 2 or spec.get('permissionDecision') == 'deny' or out.get('decision') == 'block': + return 'refused' + if r.returncode != 0: + return f'failed (exit {r.returncode})' + return 'context' if spec.get('additionalContext') else 'passed' + + +def _remove(path): + try: + os.unlink(path) + except OSError: + pass + + +def cases(tmp, sid): + """[(hook, event name, label, event, want, how)]; how: None (plain sh), or for bg-guard 'claude' (under a fake + claude parent with a background Bash tool command) or 'idle' (the same parent with none).""" + cap = config.load('capacityPipe')[0]['commands'][0] + mem = config.load('memoryIndex')[0] + def project(name, index_text): + proj = os.path.join(tmp, 'projects', name) + os.makedirs(os.path.join(proj, 'memory'), exist_ok=True) + transcript = os.path.join(proj, 'session.jsonl') + with open(transcript, 'w') as f: + f.write('{"timestamp":"2000-01-01T00:00:00.000Z"}\n') + index = os.path.join(proj, 'memory', 'MEMORY.md') + with open(index, 'w') as f: + f.write(index_text) + return transcript, index + + transcript, index = project('pre', '- [a](a.md) - ok\n') # within budget + post_transcript, _ = project('post', '- ' + 'w' * (mem['maxChars'] + 10) + '\n') # over, changed since start + + def bash(command): + return {'hook_event_name': 'PreToolUse', 'tool_name': 'Bash', 'tool_input': {'command': command}, + 'session_id': sid, 'cwd': tmp} + + def write(content): + return {'hook_event_name': 'PreToolUse', 'tool_name': 'Write', 'session_id': sid, + 'transcript_path': transcript, 'tool_input': {'file_path': index, 'content': content}} + + post = {'hook_event_name': 'PostToolUse', 'tool_name': 'Bash', 'tool_input': {'command': 'true'}, + 'session_id': sid, 'transcript_path': post_transcript} + out = [ + ('actions-disable-guard', 'PreToolUse', 'gh workflow disable', bash('gh workflow disable 1 -R example/example'), + 'refused', None), + ('actions-disable-guard', 'PreToolUse', 'echo that only mentions it', + bash("echo 'gh workflow disable 1 is refused'"), 'passed', None), + ('capacity-pipe-guard', 'PreToolUse', f'{cap} piped', bash(f'{cap} 2048 | tail -1 && true'), 'refused', None), + ('capacity-pipe-guard', 'PreToolUse', f'{cap} gating', bash(f'{cap} 2048 && true'), 'passed', None), + ('memory-index-guard', 'PreToolUse', 'Write of an index over budget', + write('x' * (mem['maxChars'] + 1)), 'refused', None), + ('memory-index-guard', 'PreToolUse', 'Write of a small index', write('- [a](a.md) - ok\n'), 'passed', None), + ('memory-index-guard', 'PostToolUse', 'index over budget, changed', post, 'refused', None), + ('memory-index-guard', 'PostToolUse', 'same index again (seen)', post, 'passed', None), + ('bg-guard', 'Stop', 'stop with a background command running', {'hook_event_name': 'Stop', 'session_id': sid}, + 'refused', 'claude'), + ('bg-guard', 'Stop', 'stop with none', {'hook_event_name': 'Stop', 'session_id': sid}, 'passed', 'idle'), + ('agent-slots', 'Stop', 'a session it does not watch', {'hook_event_name': 'Stop', 'session_id': sid}, + 'passed', None), + ] + slots = config.load('agentSlots')[0] + watched = [] + try: + with open(config.expand(slots['sessionsFile'])) as f: + watched = [ln.strip() for ln in f if ln.strip() and not ln.startswith('#')] + except (OSError, ValueError): + pass + if slots['sessionsFile'] and watched: # read only: it adds a context line, it writes nothing + out.append(('agent-slots', 'UserPromptSubmit', 'a prompt of a watched session', + {'hook_event_name': 'UserPromptSubmit', 'session_id': watched[0], 'prompt': 'check'}, 'context', + None)) + return out + + +def _fake_claude(tmp): + """A copy of sh named claude: the parent process bg-guard looks for. It starts a command that looks like a + Bash tool command in the background, runs the hook, and ends the background command.""" + fake = os.path.join(tmp, 'claude') + shutil.copy('/bin/sh', fake) + os.chmod(fake, 0o700) + hook = 'printf "%s" "$AG_EVENT" | /bin/sh -c "$AG_HOOK"; r=$?; ' + busy = ("sh -c 'sleep 30; true' shell-snapshots/snapshot-agent-guards-check >/dev/null 2>&1 & B=$!; " + + hook + 'kill $B 2>/dev/null; exit $r') + return fake, {'claude': busy, 'idle': hook + 'exit $r'} + + +def run(settings, source, say=print): + """Run every case against the hooks in `settings` (a settings object read from `source`). 0: all as wanted.""" + tmp = tempfile.mkdtemp(prefix='agent-guards-check-') + sid = SESSION + str(os.getpid()) + bad = 0 + try: + fake, scripts = _fake_claude(tmp) + missing = set() + for hook, event, label, ev, want, how in cases(tmp, sid): + cmd = wiring.find(settings, hook, event) + if cmd is None: + if (hook, event) not in missing: + missing.add((hook, event)) + bad += 1 + say(f'MISSING {hook} ({event}): not wired in {source}') + continue + if how: + env = dict(os.environ, AG_EVENT=json.dumps(ev), AG_HOOK=cmd) + r = _run(cmd, ev, tmp, env=env, argv=[fake, '-c', scripts[how]]) + else: + r = _run(cmd, ev, tmp) + got = _answer(r) + ok = got == want + bad += not ok + note = '' if ok else f' (wanted {want}; stderr: {r.stderr.strip()[-200:]!r})' + say(f'{"PASS" if ok else "FAIL"} {hook} ({event}) {label}: {got}{note}') + finally: + shutil.rmtree(tmp, ignore_errors=True) + try: + _remove(os.path.join(config.expand(config.load('memoryIndex')[0]['stateDir']), sid)) + _remove(os.path.join(config.expand(config.load('bgGuard')[0]['stateDir']), sid + '.count')) + except Exception: # noqa: BLE001 - leftovers of a made-up session are harmless + pass + say(f'check: {source}: ' + ('OK' if not bad else f'{bad} problem(s)')) + return 0 if not bad else 1 diff --git a/fork-kit/agent-guards/lib/agent_guards/config.py b/fork-kit/agent-guards/lib/agent_guards/config.py new file mode 100644 index 0000000000000..f2049d89c2f19 --- /dev/null +++ b/fork-kit/agent-guards/lib/agent_guards/config.py @@ -0,0 +1,146 @@ +"""agent_guards.config: the facts of the agent guard hooks, from the machine file's "agent-guards" section. + +Every key is optional; a missing machine file or section gives the built-in defaults below (the values the hooks +had before they moved into this kit). A broken file or section never weakens a guard below those defaults: the hook +uses them and names the problem on stderr (`agent-guards self-check` names it too). + + "agent-guards": { + "actionsDisable": {"stateDir": "~/.local/state/actions-disable-guard", + "refuseScripts": [{"name": "garden.py", "flag": "--fix", "why": "it disables workflows"}]}, + "capacityPipe": {"commands": ["t3-capacity"]}, + "memoryIndex": {"maxChars": 6000, "maxLine": 160, "stateDir": "~/.cache/memory-index-guard"}, + "bgGuard": {"skipSessionsFiles": [], "maxBlocks": 3, "stateDir": "~/.local/state/bg-guard"}, + "agentSlots": {"sessionsFile": "", "queue": "", "readyHeading": "## Ready", "maxAlive": 10, + "processName": "claude", "note": ""} + } + +Paths are absolute or start with "~/" (each user's own home). Plain Python 3 standard library. +""" +import copy, os, re, sys + +_kit = os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))) +_common = os.path.join(_kit, 'common') +sys.path.insert(0, _common if os.path.isfile(os.path.join(_common, 'machine_file.py')) + else os.path.join(os.path.dirname(_kit), 'common')) +import machine_file # noqa: E402 + +KIT = 'agent-guards' +MACHINE_PATH = None # tests only (a runner script sets it); shipped hooks read the fixed path +OWNER_UID = 0 # tests only +REQ = machine_file.REQUIRED +COMMAND_RE = re.compile(r'^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$') + + +def _path(value): + if value and not (os.path.isabs(value) or value.startswith('~/')): + return 'must be an absolute path or start with "~/"' + if '\0' in value: + return 'must not hold a NUL character' + return None + + +def _paths(value): + for v in value: + if not isinstance(v, str) or not v or _path(v): + return f'every entry must be an absolute path or start with "~/" ({v!r} is not)' + return None + + +def _positive(value): + return None if value > 0 else 'must be above 0' + + +def _commands(value): + if not value: + return 'must name at least one command' + for v in value: + if not isinstance(v, str) or not COMMAND_RE.match(v): + return f'every entry must be a command name (letters, digits, . _ + -), not {v!r}' + return None + + +def _scripts(value): + for k, v in enumerate(value): + if not isinstance(v, dict) or set(v) - {'name', 'flag', 'why'} or not isinstance(v.get('name'), str) \ + or not isinstance(v.get('flag'), str) or not isinstance(v.get('why', ''), str): + return f'entry {k} must be {{"name": "", "flag": "", "why": ""}}' + if not re.match(r'^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$', v['name']) or not re.sub(r'[^a-z0-9]', '', os.path.splitext(v['name'])[0].lower()): + return f'entry {k}: "name" must be a plain file name, not {v["name"]!r}' + if not re.match(r'^-{1,2}[A-Za-z0-9][A-Za-z0-9-]*$', v['flag']): + return f'entry {k}: "flag" must be one option like --fix, not {v["flag"]!r}' + return None + + +SPEC = { + 'actionsDisable': { + 'stateDir': (str, '~/.local/state/actions-disable-guard', _path), + 'refuseScripts': (list, [], _scripts), + }, + 'capacityPipe': { + 'commands': (list, ['t3-capacity'], _commands), + }, + 'memoryIndex': { + 'maxChars': (int, 6000, _positive), + 'maxLine': (int, 160, _positive), + 'stateDir': (str, '~/.cache/memory-index-guard', _path), + }, + 'bgGuard': { + 'skipSessionsFiles': (list, [], _paths), + 'maxBlocks': (int, 3, _positive), + 'stateDir': (str, '~/.local/state/bg-guard', _path), + }, + 'agentSlots': { + 'sessionsFile': (str, '', _path), + 'queue': (str, '', _path), + 'readyHeading': (str, '## Ready', None), + 'maxAlive': (int, 10, _positive), + 'processName': (str, 'claude', lambda v: None if COMMAND_RE.match(v) else 'must be a process name'), + 'note': (str, '', None), + }, +} +HOOKS = tuple(SPEC) + + +def defaults(hook): + return {k: copy.deepcopy(d) for k, (_t, d, _c) in SPEC[hook].items()} + + +def load(hook): + """(settings of one hook with defaults filled in, problem text or None). Never raises.""" + try: + section = machine_file.read_section(KIT, MACHINE_PATH, OWNER_UID, optional=True) + if section is None: + return defaults(hook), None + machine_file.fields(section, {h: (dict, {}, None) for h in HOOKS}, KIT) + return machine_file.fields(section.get(hook, {}), SPEC[hook], f'{KIT}.{hook}'), None + except machine_file.MachineFileError as e: + return defaults(hook), str(e) + except Exception as e: # noqa: BLE001 - a guard keeps its defaults whatever the file holds + return defaults(hook), f'{type(e).__name__}: {e}' + + +def load_all(): + """{hook: settings}, [problems]: for the self-check.""" + out, problems = {}, [] + for hook in HOOKS: + out[hook], p = load(hook) + if p and p not in problems: + problems.append(p) + return out, problems + + +def expand(path, home=None): + """A configured path for this user: "~/x" under home (default: $HOME, as the hooks always did).""" + if path.startswith('~/'): + return os.path.join(home if home is not None else os.path.expanduser('~'), path[2:]) + return path + + +def warn(name, problem): + """One line on stderr about a config problem; the hook goes on with its defaults.""" + if problem: + try: + sys.stderr.write(f'{name}: the machine file\'s "{KIT}" section cannot be used ({problem}); built-in ' + 'defaults used. Run `agent-guards self-check`.\n') + except Exception: # noqa: BLE001 + pass diff --git a/fork-kit/agent-guards/lib/agent_guards/wiring.py b/fork-kit/agent-guards/lib/agent_guards/wiring.py new file mode 100644 index 0000000000000..1fdee1d6fb9cf --- /dev/null +++ b/fork-kit/agent-guards/lib/agent_guards/wiring.py @@ -0,0 +1,94 @@ +"""agent_guards.wiring: the settings entries of the kit's hooks. + +Each hook is one command in Claude Code's settings, at the installed path (/usr/local/bin/). The command +first checks that the hook file is there, so a missing hook fails the way its kind must, and says so on stderr: + + actions-disable-guard fails CLOSED: exit 2 (every Bash command is refused until the hook is back), also when + the hook process itself fails (`|| exit 2`). It answers itself within 5 s of its start. + capacity-pipe-guard, fail OPEN: exit 1, which Claude Code shows as a hook error and then runs the call. These + memory-index-guard, guard mistakes, not attacks; refusing every call because a helper is gone would stop all + bg-guard, agent-slots work on the machine. + +The same entries go in the managed settings drop-in the installer writes (--settings) or, by hand, in any settings +file (`agent-guards hooks`). Timeouts and matchers are the ones these hooks always had. +""" +import json + +BIN = '/usr/local/bin' +DROP_IN_NAME = 'agent-guards.json' +MANAGED_DIR = '/etc/claude-code' # Claude Code's managed settings folder on Linux +DROP_IN = f'{MANAGED_DIR}/managed-settings.d/{DROP_IN_NAME}' + +HOOKS = ('actions-disable-guard', 'capacity-pipe-guard', 'memory-index-guard', 'bg-guard', 'agent-slots') +CLOSED = {'actions-disable-guard'} # a missing or failed hook refuses +WHAT_IS_LOST = { + 'actions-disable-guard': 'every Bash command is refused until it is back', + 'capacity-pipe-guard': 'hook skipped, commands are NOT checked', + 'memory-index-guard': 'hook skipped, the memory index is NOT checked', + 'bg-guard': 'hook skipped, background commands are NOT checked', + 'agent-slots': 'hook skipped, agent slots are NOT counted', +} +# (event, matcher or None, [(hook, timeout)]): one settings entry each, in this order +ENTRIES = ( + ('PreToolUse', 'Write|Edit|MultiEdit', [('memory-index-guard', 5)]), + ('PreToolUse', 'Bash', [('actions-disable-guard', 10)]), + ('PreToolUse', 'Bash|Monitor', [('capacity-pipe-guard', 10)]), + ('PostToolUse', 'Write|Edit|MultiEdit|Bash', [('memory-index-guard', 5)]), + ('UserPromptSubmit', None, [('agent-slots', 5)]), + ('Stop', None, [('agent-slots', 5), ('bg-guard', 5)]), +) + + +def command(hook, bin_dir=BIN, python='/usr/bin/python3'): + """The shell command of one hook's settings entry.""" + path = f'{bin_dir}/{hook}' + if hook in CLOSED: + return (f'g={path}; [ -r "$g" ] || {{ echo "{hook}: $g is missing: {WHAT_IS_LOST[hook]}" >&2; exit 2; }}; ' + f'{python} -IB "$g" || {{ echo "{hook}: the guard failed (exit $?): the command is refused" >&2; ' + 'exit 2; }') + return (f'g={path}; [ -r "$g" ] || {{ echo "{hook}: $g is missing: {WHAT_IS_LOST[hook]}" >&2; exit 1; }}; ' + f'exec {python} -IB "$g"') + + +def hooks(bin_dir=BIN, python='/usr/bin/python3'): + """The "hooks" object of a settings file with every hook of the kit.""" + out = {} + for event, matcher, items in ENTRIES: + entry = {'matcher': matcher} if matcher else {} + entry['hooks'] = [{'type': 'command', 'command': command(h, bin_dir, python), 'timeout': t} for h, t in items] + out.setdefault(event, []).append(entry) + return out + + +def drop_in_text(bin_dir=BIN): + return json.dumps({'hooks': hooks(bin_dir)}, indent=2) + '\n' + + +def commands_in(settings): + """[(event, matcher, command)] of every command hook in a settings object.""" + out = [] + for event, entries in ((settings or {}).get('hooks') or {}).items(): + for e in entries if isinstance(entries, list) else []: + for h in (e.get('hooks') or []) if isinstance(e, dict) else []: + if isinstance(h, dict) and isinstance(h.get('command'), str): + out.append((event, e.get('matcher'), h['command'])) + return out + + +def find(settings, hook, event): + """The command of `hook` for `event` in a settings object (the first one naming it), or None. A name is found + as a whole word of a path (`/x/bg-guard`, `bg-guard;`), not inside another name.""" + import re + pat = re.compile(r'(^|[/\s="\'])' + re.escape(hook) + r'($|[\s;"\'])') + for ev, _matcher, cmd in commands_in(settings): + if ev == event and pat.search(cmd): + return cmd + return None + + +def ours(settings): + """True for a settings object this kit wrote: only "hooks", and every command one of the kit's hooks.""" + if not isinstance(settings, dict) or set(settings) != {'hooks'}: + return False + cmds = commands_in(settings) + return bool(cmds) and all(any(f'/{h}' in c for h in HOOKS) for _e, _m, c in cmds) diff --git a/fork-kit/agent-guards/sbin/agent-guards-install b/fork-kit/agent-guards/sbin/agent-guards-install new file mode 100755 index 0000000000000..44b80d784a984 --- /dev/null +++ b/fork-kit/agent-guards/sbin/agent-guards-install @@ -0,0 +1,127 @@ +#!/usr/bin/python3 -IB +"""agent-guards-install: install, uninstall or check the agent-guards kit, as root (fork-kit/agent-guards/README.md). + + agent-guards-install install --source KIT_FOLDER --sha RELEASE_SHA [--settings | --no-settings] + agent-guards-install uninstall + agent-guards-install self-check + +install copies bin/ (the five hooks and agent-guards), sbin/agent-guards-install, lib/agent_guards/, README.md and +fork-kit/common/{machine_file,kit_install}.py of one release into /usr/local/libexec/agent-guards/versions// +(with MANIFEST.sha256), checks the copy, switches the link `current` to it and links /usr/local/bin/ and +/usr/local/bin/agent-guards to it. With --settings it also writes the hooks' Claude Code managed settings drop-in +(/etc/claude-code/managed-settings.d/agent-guards.json), which every session of every user on the machine reads +and only root can change; --no-settings removes it. The choice is kept in /etc/agent-guards/config.json, so a run +without either option keeps it (the first install: no drop-in). The drop-in is written only after the links, so a +hook it names is always there. Safe to run again, and to stop at any step; one installer at a time. The steps every +kit shares are in fork-kit/common/kit_install.py. +""" +import json, os, sys +_kit = os.path.dirname(os.path.dirname(os.path.realpath(__file__))) +_common = os.path.join(_kit, 'common') +sys.path[:0] = [_common if os.path.isdir(_common) else os.path.join(os.path.dirname(_kit), 'common'), + os.path.join(_kit, 'lib')] +try: + import kit_install # noqa: E402 + from agent_guards import wiring # noqa: E402 +except ImportError as e: # a copy with a part missing: the bootstrap makes it whole again + sys.exit(f'agent-guards-install: cannot load its installer code ({e}): install again with the bootstrap, as root ' + '(fork-kit/agent-guards/README.md, Install)') + +HOOKS = wiring.HOOKS + + +class AgentGuardsInstaller(kit_install.Installer): + PROG = 'agent-guards-install' + PROGRAM = __file__ + KIT = 'agent-guards' + ETC = '/etc/agent-guards' + LIBEXEC = '/usr/local/libexec/agent-guards' + LINKS = dict({f'{wiring.BIN}/{h}': f'bin/{h}' for h in HOOKS + ('agent-guards',)}, + **{'/usr/local/sbin/agent-guards-install': 'sbin/agent-guards-install'}) + SOURCE_FILES = tuple(f'bin/{h}' for h in HOOKS + ('agent-guards',)) + ( + 'sbin/agent-guards-install', 'README.md', 'common/machine_file.py', 'common/kit_install.py') + EXECUTABLE = frozenset([f'bin/{h}' for h in HOOKS + ('agent-guards',)] + ['sbin/agent-guards-install']) + PACKAGE = 'agent_guards' + MODULES = ('__init__', 'check', 'config', 'wiring') + HELP = ('bin/agent-guards', 'agent-guards check') + HAS_CONFIG = True + KIT_STEPS = ('settings',) + + def add_install_options(self, parser): + parser.add_argument('--settings', dest='settings', action='store_true', default=None) + parser.add_argument('--no-settings', dest='settings', action='store_false') + + def drop_in_ours(self): + """The drop-in is a plain file this kit wrote (only the kit's hooks in it), or not there.""" + real = self.p(wiring.DROP_IN) + if not os.path.lexists(real): + return None + if os.path.islink(real) or not os.path.isfile(real): + return False + try: + with open(real, encoding='utf-8') as f: + return wiring.ours(json.load(f)) + except (OSError, ValueError): + return False + + def check_managed(self): + for path in (wiring.MANAGED_DIR, os.path.dirname(wiring.DROP_IN)): + real = self.p(path) + if os.path.lexists(real) and (os.path.islink(real) or not os.path.isdir(real) + or os.lstat(real).st_uid != self.ROOT_UID): + raise self.Refused(f'{path} exists and is not a root-owned folder: fix it by hand and run again') + if self.drop_in_ours() is False: + raise self.Refused(f'{wiring.DROP_IN} exists and was not written by this kit: remove it and run again, ' + 'or run with --no-settings to leave it alone') + + def plan(self, a): + settings = a.settings if a.settings is not None else bool(self.read_config().get('settings')) + if settings or self.drop_in_ours(): + self.check_managed() + return {'settings': settings} + + def config(self, a, plan): + return {'version': 1, 'settings': plan['settings']} + + def kit_step(self, step, a, plan, dest): + # after the links: every hook the drop-in names is the one of this release + if plan['settings']: + self.check_managed() + for path in (wiring.MANAGED_DIR, os.path.dirname(wiring.DROP_IN)): + self.ensure_dir(path) + if self.write_file(wiring.DROP_IN, wiring.drop_in_text()): + self.say(f'wrote {wiring.DROP_IN}: every new Claude Code session runs the hooks ' + '(sessions already running keep the hooks they started with)') + elif self.drop_in_ours(): + os.unlink(self.p(wiring.DROP_IN)) + self.say(f'removed {wiring.DROP_IN}') + + def kit_rows(self, plan): + if not plan['settings']: + return [] + return [(wiring.DROP_IN, 'file', kit_install.sha256_file(self.p(wiring.DROP_IN)))] + + def kit_uninstall(self): + if self.drop_in_ours(): + os.unlink(self.p(wiring.DROP_IN)) + self.say(f'removed {wiring.DROP_IN}') + + def _remove(self): + # the drop-in goes first: while it is there, the hooks it names must be too (a missing + # actions-disable-guard refuses every Bash command); the shared steps then remove the links + self.kit_uninstall() + return super()._remove() + + def installed_summary(self, plan): + return ', hooks in managed settings' if plan['settings'] else ', hooks not in managed settings' + + +INSTALLER = AgentGuardsInstaller() + + +def main(argv, stop_after=None): + return INSTALLER.main(argv, stop_after, doc=__doc__) + + +if __name__ == '__main__': + sys.exit(main(sys.argv[1:])) diff --git a/fork-kit/agent-guards/tests/actions-disable.test.py b/fork-kit/agent-guards/tests/actions-disable.test.py new file mode 100644 index 0000000000000..2b0eb60071d60 --- /dev/null +++ b/fork-kit/agent-guards/tests/actions-disable.test.py @@ -0,0 +1,2505 @@ +#!/usr/bin/env python3 +"""Tests of fork-kit/agent-guards/bin/actions-disable-guard (the Claude Code PreToolUse hook that refuses disabling +GitHub Actions). The guard is loaded as a module with a machine file of the test's own (guards_fixture.py), whose +actionsDisable.refuseScripts names one script (example_garden.py --fix); the runs as a hook read no machine file. + + node .github/scripts/fork-ci-tests.cjs fork-kit/agent-guards/ + +(a test runner handed the folder, not `python3 this-file` from an agent's shell: the guard reads the script files an +agent runs, and this one is full of the patterns it refuses.)""" +import datetime as dt, json, os, subprocess, sys, tempfile, unittest +from unittest import mock + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +import guards_fixture as fx # noqa: E402 + +HOOK = os.path.join(fx.BIN, 'actions-disable-guard') +GARDEN = {'name': 'example_garden.py', 'flag': '--fix', 'why': 'disables every workflow it does not know'} +MARK_ENV, MARK_CMD = 'CLAUDE_GUARD_OWNER_ALLOW_ACTIONS_DISABLE', '#owner-approved:actions-disable' + + +_MACHINE = tempfile.TemporaryDirectory(prefix='actions-disable-test-') + + +def load(): + """The guard as a module, with one refuseScripts row (example_garden.py --fix) from a machine file of its own.""" + path = fx.machine_file(_MACHINE.name, {'actionsDisable': {'refuseScripts': [GARDEN]}}) + return fx.load_hook('actions-disable-guard', path) + + +def today(): + return dt.datetime.now(dt.timezone.utc).strftime('%Y-%m-%d') + + +DENY = [ + # gh workflow disable, every spelling + 'gh workflow disable 415816119 -R example/repo', + 'gh workflow disable fork-tests.yml', + 'gh "workflow" \'disable\' 1', + 'gh work"flow" dis\'able\' 1', + 'g\\h workflow disable 1', + '/usr/bin/gh workflow disable 1', + 'GH_TOKEN=x GH_REPO=a/b gh workflow disable 1', + 'env GH_REPO=a/b gh workflow disable 1', + 'env -i PATH=/usr/bin gh workflow disable 1', + 'sudo -u someone gh workflow disable 1', + 'command gh workflow disable 1', + 'exec gh workflow disable 1', + 'nohup gh workflow disable 1 &', + 'timeout 30 gh workflow disable 1', # timing: guard input, not a wait + 'timeout -k 5 30s gh workflow disable 1', # timing: guard input, not a wait + 'xargs -n1 gh workflow disable < ids.txt', + 'printf "1\\n2\\n" | xargs -I{} gh workflow disable {} -R a/b', + 'gh workflow -R a/b disable 1', + 'gh workflow --repo=a/b disable 1', + 'gh workflow --repo a/b disable 1', + # shells, chains, substitutions + 'bash -c "gh workflow disable 1"', + "bash -lc 'gh workflow disable 1'", + 'sh -c "cd /tmp && gh workflow disable 1"', + 'zsh -c "true; gh workflow disable 1"', + 'cd /tmp && gh workflow disable 1', + 'true; gh workflow disable 1', + 'false || gh workflow disable 1', + 'gh workflow list | head -1 && gh workflow disable 1', + 'echo $(gh workflow disable 1)', + 'echo `gh workflow disable 1`', + '(gh workflow disable 1)', + 'for i in 1 2; do gh workflow disable $i; done', + 'if true; then gh workflow disable 1; fi', + 'echo "gh workflow disable 1" | sh', + 'echo gh workflow disable 1 | bash -s', + 'eval "gh workflow disable 1"', + 'W=disable; gh workflow $W 1', + 'W=disable && gh workflow ${W} 1', + 'bash < /tmp/x.sh < run.sh && chmod +x run.sh && ./run.sh\ngh api -X PUT repos/a/b/actions/workflows/1/disable\nEOF', + 'gh alias import - < notes.md <<'EOF'\nFound: gh workflow disable 415770881 --repo example/repo ran.\n" + "gh workflow disable 1\ngh api -X PUT repos/a/b/actions/permissions -F enabled=false\nEOF", + "cat >> research/plan.md < >(gh workflow disable 1)', + 'echo $((1+1)); gh workflow disable 1', + 'A=($(gh workflow disable 1))', + 'true && { false || gh workflow disable 1; }', + ], + 'brace, glob and IFS expansion': [ + 'gh workflow {disable,list} 1', + 'gh workflow dis{a,}ble 1', + 'gh workflow d* 1', + 'gh workflow ?isable 1', + 'gh workflow [d]isable 1', + 'gh {workflow,x} disable 1', + f'gh api -X PUT repos/a/b/actions/{{permissions,x}} {OFF}', + f'gh api -X PUT repos/a/b/actions/perm* {OFF}', + f'gh api {{-X,PUT}} {P}', + 'IFS=,; X=workflow,disable,1; gh $X', + 'IFS=/; X=workflow/disable; gh $X 1', + f'IFS=:; X=-X:PUT; gh api $X {P}', + 'X="workflow disable"; gh $X 1', + ], + 'variables: every value counts, not the first one': [ + 'W=list; W=disable; gh workflow $W 1', + 'W=list; for i in 1 2; do gh workflow $W 1; W=disable; done', + 'if true; then W=disable; fi; gh workflow $W 1', + 'W=list; true && W=disable; gh workflow $W 1', + 'declare W=disable; gh workflow $W 1', + 'declare "W=disable"; gh workflow $W 1', + 'export W=disable; gh workflow $W 1', + 'readonly W=disable; gh workflow $W 1', + 'W=list; declare -n W=X; X=disable; gh workflow $W 1', + 'W=list; read W <<< disable; gh workflow $W 1', + 'W=list; printf -v W disable; gh workflow $W 1', + 'W=dis; W+=able; gh workflow $W 1', + 'W=dis; W=${W}able; gh workflow $W 1', + 'W=able; W=dis$W; gh workflow "$W" 1', + 'W=list; eval "W=dis""able"; gh workflow $W 1', + 'for W in list disable; do gh workflow $W 1; done', + 'for W in $LIST; do gh workflow $W 1; done', + 'W=${X:-disable}; gh workflow $W 1', + 'A=dis; B=able; gh workflow $A$B 1', + 'A=dis; gh workflow ${A}able 1', + 'V=workflow; W=disable; gh $V $W 1', + 'gh workflow "$W" 1', + 'gh workflow $W', + f'E=permissions; gh api -X PUT repos/a/b/actions/$E {OFF}', + ], + 'the command word is hidden or wrapped': [ + '/usr/bin/gh workflow disable 1', + '~/bin/gh workflow disable 1', + '\\gh workflow disable 1', + "'gh' workflow disable 1", + 'g\\h workflow disable 1', + 'command gh workflow disable 1', + 'exec gh workflow disable 1', + 'nohup gh workflow disable 1 &', + 'timeout 5 gh workflow disable 1', # timing: guard input, not a wait + '(gh workflow disable 1)', + 'if gh workflow disable 1; then :; fi', + 'GH_REPO=a/b gh workflow disable 1', + 'GH_HOST=github.com GH_PROMPT_DISABLED=1 gh workflow disable 1', + 'gh workflow disable "CI and tests"', + 'GH=gh; $GH workflow disable 1', + 'G=/usr/bin/gh; "$G" workflow disable 1', + '"$GH" workflow disable 1', + '$(command -v gh) workflow disable 1', + '"${GH:-gh}" workflow disable 1', + f'"$GH" api -X PUT {P} {OFF}', + 'g() { gh "$@"; }; g workflow disable 1', + 'function g { gh workflow "$@"; }; g disable 1', + f'put() {{ gh api -X PUT "$@"; }}; put {P} {OFF}', + "alias g='gh workflow'; g disable 1", + 'A=(workflow disable 1); gh "${A[@]}"', + 'set -- workflow disable 1; gh "$@"', + "bash -c 'gh \"$0\" \"$1\" 1' workflow disable", + 'find . -name x -exec gh workflow disable 1 \\;', + 'echo disable 1 | xargs gh workflow', + 'echo 1 | xargs gh workflow disable', + 'xargs -a ids.txt gh workflow disable', + f'echo {P} | xargs gh api -X PUT {OFF}', + "ssh host 'gh workflow disable 1'", + 'ssh host gh workflow disable 1', + "trap 'gh workflow disable 1' EXIT", + 'env -S "gh workflow disable 1"', + 'env --split-string="gh workflow disable 1"', + 'nice -n 5 gh workflow disable 1', + 'stdbuf -oL gh workflow disable 1', + 'setsid -f gh workflow disable 1', + 'flock /tmp/l gh workflow disable 1', + 'time gh workflow disable 1', + 'script -q -c "gh workflow disable 1" /dev/null', + "su - someone -c 'gh workflow disable 1'", + "sudo sh -c 'gh workflow disable 1'", + "busybox sh -c 'gh workflow disable 1'", + "parallel 'gh workflow disable {}' ::: 1 2", + 'parallel gh workflow disable ::: 1 2', + 'eval gh workflow disable 1', + 'eval "$(echo gh workflow disable 1)"', + "git -c alias.x='!gh workflow disable 1' x", + "git config alias.x '!gh workflow disable 1'", + 'python3 -c "import os; os.system(\'gh workflow disable 1\')"', + "python3 - <<'EOF'\nimport subprocess\nsubprocess.run(['gh', 'workflow', 'disable', '1'])\nEOF", + f'python3 -c "import urllib.request as u; u.urlopen(u.Request(\'{U}\', method=\'PUT\', data=b\'{{}}\'))"', + 'node -e "require(\'child_process\').execSync(\'gh workflow disable 1\')"', + "bash <<'EOF'\ngh workflow disable 1\nEOF", + 'bash <<< "gh workflow disable 1"', + 'echo "gh workflow disable 1" | bash', + 'echo "gh workflow disable 1" | sh -s', + 'bash < sub/dis.sh', + 'sh -s < sub/dis.sh', + 'C="gh workflow disable 1"; bash <<< "$C"', + 'C="gh workflow disable 1"; bash -c "$C"', + 'C="gh workflow disable 1"; eval "$C"', + 'C="gh workflow disable 1"; $C', + ], + 'the gh config folder is swapped for one with an alias': [ + 'GH_CONFIG_DIR=evil gh wd 1', + 'GH_CONFIG_DIR=./evil gh wd 1', + 'env GH_CONFIG_DIR=evil gh wd 1', + 'export GH_CONFIG_DIR=evil; gh wd 1', + 'export GH_CONFIG_DIR; GH_CONFIG_DIR=evil; gh wd 1', + 'XDG_CONFIG_HOME=xdg gh wd 1', + 'HOME=h gh wd 1', + 'C=evil; GH_CONFIG_DIR=$C gh wd 1', + 'GH_CONFIG_DIR="$PWD/evil" gh wd 1', + 'GH_CONFIG_DIR=$(pwd)/evil gh wd 1', + 'env GH_CONFIG_DIR="$C" gh wd 1', + 'export GH_CONFIG_DIR="$C"; gh wd 1', + 'cd evil && GH_CONFIG_DIR=. gh wd 1', + 'cd "$X" && GH_CONFIG_DIR=. gh wd 1', + 'GH_CONFIG_DIR=evil gh off a/b', + 'GH_CONFIG_DIR=evil gh pr wd 1', + 'GH_CONFIG_DIR=block gh wd 1', + 'GH_CONFIG_DIR=block gh off', + 'GH_CONFIG_DIR=inline gh wd 1', + 'GH_CONFIG_DIR=odd gh wd 1', + ], + 'gh aliases': [ + "gh alias set wd --clobber 'workflow disable'", + "gh alias set --clobber wd 'workflow disable'", + "gh alias set 'pr wd' 'workflow disable'", + 'gh alias set wd workflow disable', + "gh alias set wd 'workflow \"$1\"'", + "gh alias set -s wd 'gh workflow disable $1'", + "gh alias set wd '!gh workflow disable $1'", + f"gh alias set off 'api -X PUT {P} {OFF}'", + f"gh alias set off 'api -X PUT repos/$1/actions/permissions {OFF}'", + 'gh alias set wd "$TEXT"', + 'gh alias set wd - < x.sh <<'EOF'\ngh workflow disable 1\nEOF\nbash x.sh", + "cat > x.sh <<'EOF'\n#!/bin/sh\ngh workflow disable 1\nEOF\nchmod +x x.sh; ./x.sh", + "cat > x <<'EOF'\n#!/usr/bin/env python3\ngh workflow disable 1\nEOF\nbash x", # bash ignores the #! line + "tee x.sh <<'EOF'\ngh workflow disable 1\nEOF\n. ./x.sh", + "cat > /tmp/x.sh <<'EOF'\ngh workflow disable 1\nEOF\ncd /tmp && source x.sh", + "f=$(mktemp); cat > \"$f\" <<'EOF'\ngh workflow disable 1\nEOF\nbash \"$f\"", + "cat > x.py <<'EOF'\nimport subprocess\nsubprocess.run(['gh', 'workflow', 'disable', '1'])\nEOF\npython3 x.py", + "cat > x.py <<'EOF'\n#!/usr/bin/env python3\nimport os\nos.system('gh workflow disable 1')\nEOF\n" + "chmod +x x.py && ./x.py", + "echo 'gh workflow disable 1' > x.sh; sh x.sh", + "echo 'gh workflow disable 1' > x.sh && chmod +x x.sh && ./x.sh", + 'echo gh workflow disable 1 > x.sh; bash x.sh', + "printf '%s\\n' 'gh workflow disable 1' > x.sh; bash x.sh", + "printf 'true\\ngh workflow disable 1\\n' > x.sh; bash x.sh", + "echo 'gh workflow disable 1' | tee x.sh; bash x.sh", + "echo 'gh workflow disable 1' | cat > x.sh; bash x.sh", + "printf 'true\\ngh workflow disable 1\\n' | sh", + "echo \"import os; os.system('gh workflow disable 1')\" > x.py; python3 x.py", + f"echo 'gh api -X PUT {P} {OFF}' >> x.sh; bash x.sh", + ], + # ---- lens round on #1543 (security NOT SAFE). The guard now fails closed by construction: a guarded token + # passes only where the guard can prove the use harmless. Every case below passed on 7c3268aef7. + 'lens blocker: a command word the guard does not know in front': [ + 'taskset 1 bash sub/dis.sh', + 'chrt -b 0 ./sub/dis.sh', + 'taskset 1 ./sub/dis.sh', + 'at -f sub/dis.sh now', + 'bash -e sub/dis.sh', + f"flock /tmp/l curl -q -sS -X PUT {U} -d '{{\"enabled\":false}}'", + 'sg users -c "gh workflow $W 1"', + f"sometool run \"curl -X PUT {U} -d '{{}}'\"", + f'faketime now gh api {P}', + "tmux new -d 'gh workflow disable 1'", + f"docker run --rm alpine sh -c 'curl -X PUT {U}'", + "cat > off.sh <<'EOF'\ngh workflow disable 1\nEOF\ntaskset 1 bash off.sh", + "cat > j.txt <<'EOF'\ngh workflow disable 1\nEOF\nat -f j.txt now", + ], + 'lens blocker: token text that goes on to a word the guard cannot read': [ + "echo 'gh workflow disable 1' | at now", + "printf 'gh workflow disable 1\\n' > job.txt; batch < job.txt", + "export RUN='gh workflow disable 1'; sometool", + "PAGER='gh workflow disable 1' git log", + "GIT_SSH_COMMAND='gh workflow disable 1' git fetch", + "echo 'gh workflow disable 1' > notes.md; make test", + "f() { sh -c \"$1\"; }; f 'gh workflow disable 1'", + ], + 'lens major: gh under another name or path': [ + 'cp /usr/bin/gh /tmp/x && /tmp/x workflow disable 1', + f'ln -s "$(command -v gh)" g; ./g api -X PUT {P} {OFF}', + 'install -m755 /usr/bin/gh ./tool && ./tool workflow disable 1', + ], + 'lens major: gh config in YAML the reader does not follow': [ + 'GH_CONFIG_DIR=tag gh wd 1', + 'GH_CONFIG_DIR=qkey gh wd 1', + 'GH_CONFIG_DIR=esc gh wd 1', + ], + 'lens major: escapes in a body or a path': [ + 'gh api -X PUT repos/a/b/rulesets/1 --input rs_esc.json', + "gh api -X PUT repos/a/b/rulesets/1 --input - <<< '{\"enforcement\": \"\\u0064isabl\\u0065d\"}'", + "curl -q -X PUT -d '{\"enforcement\":\"\\u0064isabled\"}' https://api.github.com/repos/a/b/rulesets/1", + f"gh api -X PUT 'repos/a/b/actions/\\u0070ermissions' {OFF}", + "curl -q -X PUT 'https://api.github.com/repos/a/b/actions/\\u0070ermissions' -d '{\"enabled\":false}'", + ], + 'own find: the GraphQL endpoint in another spelling, with a query the guard cannot read': [ + 'gh api https://api.github.com/graphql -F query=@$S/q.graphql', + 'gh api /graphql/ -F query=@$S/q.graphql', + "gh api 'graphql?x=1' -F query=@$S/q.graphql", + 'gh api repos/../graphql -F query=@$S/q.graphql', + 'gh api %67raphql -F query=@$S/q.graphql', + 'gh api "gra$X" -F query=@$S/q.graphql', + 'gh api "$H/graphql" -F query=@$S/q.graphql', + 'gh api {owner}/graphql -F query=@$S/q.graphql', + # the word that looks like the path may be a flag value: the hidden word in front may be `graphql -H` + 'gh api $A repos/a/b/issues/1/comments -F query=@not-there.graphql', + 'gh api "$A" repos/a/b/issues/1/comments -F query=@not-there.graphql', + 'gh api -F a=$1 repos/a/b/issues/1/comments -F query=@not-there.graphql', + 'gh api -X$M repos/a/b/issues/1/comments -F query=@not-there.graphql', + 'gh api -H -- -XPOST graphql -F query=@$f', + ], + 'lens major: GraphQL switches a ruleset off': [ + 'gh api graphql -F query=@upd.graphql', + f"gh api graphql -f query='{GQL_OFF}'", + 'curl -q -X POST https://api.github.com/graphql -d @upd.json', + ], + 'lens major: code in another language deletes protection or a ruleset': [ + 'python3 off.py', + 'python3 rs.py', + 'python3 -m off', + 'taskset 1 python3 off.py', + 'ipython off.py', + 'deno run off.ts', + 'node -r ./off.ts main.js', + 'tsx off.ts', + "ruby -e 'require \"net/http\"; Net::HTTP.new(\"api.github.com\", 443).delete(\"/repos/a/b/rulesets/12\")'", + "perl -e 'system(\"gh\",\"api\",\"-X\",\"DELETE\",\"repos/a/b/branches/main/protection\")'", + ], + 'lens major: curl and wget read their own config files': [ + f'curl -sS {U}', + f'CURL_HOME=cfg curl -sS {U}', + f'wget -qO- {U}', + f'WGETRC=wrc wget -qO- {U}', + ], + 'lens minor: a branch name with a slash': [ + 'gh api -X DELETE repos/a/b/branches/release/1.0/protection', + 'curl -q -X DELETE https://api.github.com/repos/a/b/branches/feat/x/y/protection', + 'gh api -X DELETE repos/a/b/branches/a/b/protection/required_status_checks', + ], +} + +# Harmless, but refused: the guard cannot prove it from the text. Each refusal says what to change (the hint). +OVER_REFUSED = [ + (f'curl -sS {U}', '-q'), + (f'wget -qO- {U}', '--no-config'), + (f'http GET {U}', 'gh api'), + ("python3 -c \"print('gh workflow disable')\"", 'gh api'), + ("python3 - <<'EOF'\nprint('the guard refuses gh workflow disable')\nEOF", 'edit or search tool'), + ("cat > x.py <<'EOF'\nimport re\nprint(re.sub(r'gh workflow (enable|disable)', 'gh workflow', " + "open('n.md').read()))\nEOF\npython3 x.py", 'edit or search tool'), + ("sometool -m 'text about actions/permissions'", 'does not know'), + ("awk '/actions\\/permissions/' notes.md", 'gh api'), + ("alias t=sometool; t 'x actions/permissions'", 'does not know'), + ("f() { echo \"$1\"; }; f 'about gh workflow disable'", 'workflow disable'), # a function may run its words + ("export NOTE='see actions/permissions'; gh pr list", 'exported variable'), + ("echo '{\"query\":\"query { viewer { login } }\"}' | gh api graphql --input -", 'cannot read'), + ('pytest tests/test_guard.py', 'name its folder'), + ("sometool commit -m 'fix the guard' tests/test_guard.py", 'name its folder'), +] + +# What still has to pass: reads, the re-enable, and ordinary writes that only look alike. +ALLOW_MORE = [ + f'gh api {P} --jq .enabled', + f'gh api {P} -q .enabled -i', + f'gh api -H "Accept: application/vnd.github+json" {P}', + f'gh api -iXGET {P}', + f'gh api -X=GET {P}', + f'gh api --method=GET {P} -f per_page=1', + f'gh api -X PUT -X GET {P}', + f'gh api -p -XPUT {P}', + f'M=GET; gh api -X $M {P}', + f'gh api "repos/$R/actions/permissions"', + f'gh api "repos/$R/actions/permissions" --jq .enabled', + 'gh api --paginate repos/a/b/actions/workflows --jq \'.workflows[] | select(.state != "active") | .path\'', + 'gh api -X PUT "repos/$R/actions/workflows/$W/enable"', + 'gh api "repos/$R/actions/workflows/$W"', + f'gh api -X PUT {P} -F enabled=true -F allowed_actions=all', + f'gh api --method PUT /{P}/ -f enabled=true', + 'gh api -X POST repos/a/b/issues/1/comments -f body="see actions/permissions and gh workflow disable"', + 'gh api -X POST repos/a/b/issues -f title=x -F body=@body.json', + 'gh api -X POST "repos/$REPO/issues/$N/comments" -f body="$B"', + # a comment with its text from a file named by a variable is no GraphQL call (real commands of the corpus) + 'gh api -X PATCH repos/a/b/issues/comments/$id -F body=@"$S/c$id.md" --jq \'.body\'', + 'gh api -X PATCH "repos/a/b/issues/comments/$id" -F body=@"$S/c.md"', + 'gh api repos/a/b/pulls/974/comments/$id/replies -F body=@$S/r39.md --jq .html_url', + "gh api repos/a/b/pulls/983/comments -F in_reply_to=$1 -F body=@$SP/$2.md -q '.html_url'", + 'gh api repos/a/b/issues/$n/comments --input $f', + 'gh api -X "$M" repos/a/b/issues/1/comments -F body=@$f', + 'gh api -H "Accept: $A" --hostname github.com repos/a/b/issues/1/comments -F body=@$f', + 'gh api repos/{owner}/{repo}/issues/$n/comments -F body=@$f', + 'gh api graphql -F query=@ok.graphql -F n=$n', + 'gh api -X PATCH repos/a/b -f has_issues=true', + 'gh api -X DELETE repos/a/b/git/refs/heads/work/x', + 'gh api -X DELETE "repos/a/b/git/refs/heads/$BR"', + 'gh api "$URL"', + 'gh api "$URL" --jq .state', + "gh api graphql -f query='query { viewer { login } }'", + "gh api graphql -f query='mutation($id:ID!){ markPullRequestReadyForReview(input:{pullRequestId:$id})" + "{ clientMutationId } }' -f id=\"$ID\"", + 'gh api graphql -F query=@ok.graphql -f owner=a', + 'gh api repos/a/b/branches/main/protection', + 'gh api -X PUT repos/a/b/branches/main/protection --input prot.json', + 'gh api -X PATCH repos/a/b/branches/main/protection/required_status_checks -f strict=true', + 'gh api repos/a/b/rulesets', + 'gh api repos/a/b/rulesets/12', + 'gh api -X POST repos/a/b/rulesets --input rs_on.json', + 'gh api -X PUT repos/a/b/rulesets/12 --input rs_on.json', + 'gh api -X PUT repos/a/b/rulesets/12 -f enforcement=active', + 'gh -R a/b workflow list', + 'gh workflow list --json name,state -q \'.[] | select(.state=="disabled_manually")\'', + 'gh workflow view "$W"', + 'gh workflow run ci.yml -f reason="disable the flaky test"', + 'gh workflow enable "$W" -R a/b', + 'W=enable; gh workflow $W 1', + 'for w in $(gh workflow list --json id -q ".[].id"); do gh workflow enable "$w"; done', + 'gh pr view 12 --json state -q .state', + 'gh pr list --search "disable in:title"', + 'gh pr comment 12 --body "do not disable the workflow"', + 'gh run view 1 --log | rg disable', + 'gh "$SUB" list', + 'gh alias list', + 'gh alias delete co', + "gh alias set bugs 'issue list --label=bug'", + "gh alias set co - <<< 'pr checkout'", + "gh alias set mine - <<< 'issue list --author=\"$1\" --label=\"$2\"'", + 'bash < sub/ok.sh', + 'bash "$HOME/sub/ok.sh"', + 'cat <<< "gh workflow disable 1"', + 'grep -c disable < al.txt', + 'gh alias import ok.yml', + 'gh alias import ok.yml && gh co 12', + 'GH_CONFIG_DIR=empty gh pr list', + 'GH_CONFIG_DIR=evil gh co 12', + 'GH_CONFIG_DIR="$(mktemp -d)" python3 -I tests.py', + # curl and wget next to a guarded path: only with their own config switched off (-q first, --no-config) + f'curl -q -sSL -o out.json -H "Authorization: Bearer $T" {U}', + f'curl -q -fsS --max-time 20 {U}', + f'curl -q -sI {U}', + f'curl -q -s -X GET {U}', + f'curl -q -sSLo out.json {U}', + f'curl --disable -fsS {U}', + f'curl -qsS {U}', + f'CURL_HOME=cfg curl -q -s {U}', + 'curl -q -fsS https://api.github.com/repos/a/b/branches/main/protection', + 'curl -q -X PUT -d @prot.json https://api.github.com/repos/a/b/branches/main/protection', + 'curl -X POST https://api.github.com/repos/a/b/issues -d \'{"title":"x"}\'', + 'curl -sS https://api.github.com/repos/a/b/pulls', + f'wget --no-config -qO- {U}', + f'wget --no-config -q --header="Accept: application/json" -O out.json {U}', + f'WGETRC=wrc wget --no-config -qO- {U}', + 'wget --no-config -qO- https://api.github.com/repos/a/b/rulesets/12', + # lens round on #1543: what the fail-closed rules must still let through + 'ln -s /usr/bin/gh g; ./g pr list', + 'GH_CONFIG_DIR=tag gh pr list', + 'gh api repos/a/b/branches/release/1.0/protection', + 'gh api graphql -F query=@upd_on.graphql', + "gh api graphql --input - <<< '{\"query\":\"query { viewer { login } }\"}'", + 'gh ruleset list', + 'gh ruleset view 12', + "echo 'gh workflow disable 1' | tee notes.md", + "echo 'gh workflow disable 1' | grep -c disable", + 'make test', + 'taskset 1 make -j4', + "rg -n 'deleteBranchProtectionRule|updateRepositoryRuleset' scripts/", + "git log --grep='workflow disable'", + "gh pr comment 12 --body 'the guard now refuses updateRepositoryRuleset with DISABLED'", + "git commit -m \"$(cat <<'EOF'\nguard: refuse gh workflow disable behind taskset\nEOF\n)\"", + f'gh api {P} | jq .enabled', + f"gh api {P} | python3 -c 'import json,sys; print(json.load(sys.stdin))'", + f'X=$(gh api {P} --jq .enabled); echo "$X"', + f'watch -n 5 gh api {P}', + f'time gh api {P}', + f'timeout 10 gh api {P}', # timing: guard input, not a wait + "gh api repos/a/b/rulesets --jq '.[].id' | while read id; do gh api \"repos/a/b/rulesets/$id\"; done", + "export NOTE='see actions/permissions'; echo \"$NOTE\"", + "NOTE='see actions/permissions'; gh pr comment 1 --body \"$NOTE\"", + 'python3 run_tests.py tests/test_guard.py', # the script is read; what it is handed is its own business + 'pytest tests/', + 'sometool lint docs/guard.md', + 'git add tests/test_guard.py off.py', + 'wc -l tests/test_guard.py off.py', + 'python3 -m unittest tests/test_guard.py', + # correctness lens m1: `.`, eval and source hide variables as the COMMAND word only, not as any word + 'for r in a-app b-app; do gh api repos/o/$r/actions/permissions --jq .; done', + 'git add . && for r in a b; do gh api repos/o/$r/actions/permissions; done', + "find . -name '*.md'; R=a/b; gh api repos/$R/actions/permissions", + f'M=GET; echo source vars.sh; gh api -X $M {P} {OFF}', + f'M=GET; echo eval; gh api -X $M {P}', + "echo 'the . and eval words'; for r in a b; do gh api repos/o/$r/actions/permissions --jq .; done", + 'git commit -m "guard: refuse gh workflow disable via alias"', + "git config alias.st 'status -sb'", + "git -c alias.l='!git log --oneline' l", + 'echo "gh api -X PUT repos/a/b/actions/permissions -F enabled=false" >> notes.md', + 'rg -n "X-HTTP-Method-Override|actions/permissions" scripts/', + "find . -name '*.yml' -exec grep -l disable {} +", + 'xargs -n1 gh pr view < prs.txt', + "ssh vm 'systemctl disable foo.timer'", + 'cd sub && bash ok.sh', + 'IFS=,; X=a,b; echo $X', + # a config folder from command output, as test briefs ask for: fine with a real gh command + 'GH_CONFIG_DIR=$(mktemp -d) gh pr list', + 'export GH_CONFIG_DIR=$(mktemp -d); gh auth status', + 'export GH_CONFIG_DIR="$TMP/gh"; gh api repos/a/b --jq .name', + # a command word nobody can read here, with words nobody can read here: no sign of gh or of disabling + '"$CMD" "$@"', + '"$TOOL" set "$KEY" "$VALUE"', + '"$BIN" import "$FILE"', + 'run() { "$@"; }; run make test', + 'gh alias set --help', + 'gh alias import --help', + # a Python script written and run by the same command is code, not shell text + "cat > x.py <<'EOF'\n#!/usr/bin/env python3\nwords = ['a; b', 'c | d && e']\nprint(len(words))\nEOF\n" + "chmod +x x.py && ./x.py", + "cat > notes.md <<'EOF'\nThe guard refuses `gh workflow disable 1`.\nEOF\ncat notes.md", + "echo 'gh workflow list' > x.sh; bash x.sh", + "cat > x.sh <<'EOF'\ngh workflow enable 1\nEOF\nbash x.sh", + 'gh api "repos/a/b/rulesets/$ID" --jq .enforcement', +] + + +class Case(unittest.TestCase): + """A scratch folder as cwd and HOME, and the guard loaded as a module. No token, no gh login, no network.""" + + @classmethod + def setUpClass(cls): + cls.g = load() + + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.dir = self.tmp.name + self.env = {'HOME': self.dir, 'GH_CONFIG_DIR': os.path.join(self.dir, 'gh')} + + def tearDown(self): + self.tmp.cleanup() + + def decide(self, cmd, env=None): + return self.g.decide(cmd, self.dir, self.env if env is None else env) + + def write(self, name, text, mode=0o755): + p = os.path.join(self.dir, name) + os.makedirs(os.path.dirname(p), exist_ok=True) + with open(p, 'w') as f: + f.write(text) + os.chmod(p, mode) + return p + + +EVIL_CONFIG = ('version: 1\naliases:\n co: pr checkout\n wd: workflow disable\n pr wd: workflow disable\n' + ' off: \'!gh api -X PUT "repos/$1/actions/permissions" -F enabled=false\'\n') +FILES = { + 'body.json': '{"enabled": false}\n', + 'flags.txt': '-X PUT\n', + 'ids.txt': '1\n2\n', + 'prs.txt': '12\n13\n', + 'urls.txt': U + '\n', + 'curl.cfg': 'request = PUT\n', + 'evil/config.yml': EVIL_CONFIG, # GH_CONFIG_DIR=evil + 'xdg/gh/config.yml': EVIL_CONFIG, # XDG_CONFIG_HOME=xdg + 'h/.config/gh/config.yml': EVIL_CONFIG, # HOME=h + 'empty/config.yml': 'version: 1\naliases:\n co: pr checkout\n', + # YAML block values: the line breaks hide the command from a line-by-line reader + 'block/config.yml': 'aliases:\n wd: >-\n workflow\n disable\n off: |\n' + f' !gh api -X PUT {P} \\\n -F enabled=false\n', + 'inline/config.yml': 'aliases: {co: pr checkout, wd: workflow disable}\n', + # YAML this guard's small reader does not follow (an anchor): it must not pass as "no such alias" + 'odd/config.yml': 'x: &off workflow disable\naliases:\n wd: *off\n', + 'al.txt': 'workflow disable\n', + 'al.yml': 'wd: workflow disable\n', + 'w.yml': 'w: workflow\n', + 'ok.yml': 'co: pr checkout\n', + 'rs_off.json': '{"name": "main", "enforcement": "disabled", "rules": []}\n', + 'rs_on.json': '{"name": "main", "enforcement": "active", "rules": []}\n', + 'off.txt': 'disabled\n', + 'prot.json': '{"required_status_checks": {"strict": true, "contexts": ["ci"]}, "enforce_admins": true,\n' + ' "required_pull_request_reviews": null, "restrictions": null}\n', + 'q.graphql': GQL + '\n', + 'gql.json': json.dumps({'query': GQL}) + '\n', + 'ok.graphql': 'query($owner: String!) { repositoryOwner(login: $owner) { login } }\n', + 'tests.py': 'print("ok")\n', + 'sub/dis.sh': '#!/bin/sh\ngh workflow disable 1\n', + 'sub/dis.py': "import subprocess\nsubprocess.run(['gh', 'workflow', 'disable', '1'])\n", + 'sub/ok.sh': '#!/bin/sh\ngh workflow list\n', + # lens round on #1543 + 'tag/config.yml': 'aliases:\n wd: !!str workflow disable\n', # gh reads all three as wd: workflow disable + 'qkey/config.yml': 'aliases:\n ? wd\n : workflow disable\n', + 'esc/config.yml': 'aliases:\n "w\\x64": workflow disable\n', + 'rs_esc.json': '{"enforcement": "\\u0064isabled"}\n', + 'upd.graphql': GQL_OFF + '\n', + 'upd.json': json.dumps({'query': GQL_OFF}) + '\n', + 'upd_on.graphql': GQL_OFF.replace('DISABLED', 'ACTIVE') + '\n', + 'off.py': "import requests\nrequests.delete('https://api.github.com/repos/a/b/branches/main/protection')\n", + 'rs.py': "import urllib.request as u\nu.urlopen(u.Request('https://api.github.com/repos/a/b/rulesets/12', " + "method='DELETE'))\n", + 'off.ts': "await fetch('https://api.github.com/repos/a/b/rulesets/12', {method: 'DELETE'})\n", + 'main.js': 'console.log(1)\n', + 'run_tests.py': 'import sys\nprint(sys.argv)\n', + 'tests/test_guard.py': "CASES = ['gh workflow disable 1', 'gh api -X PUT repos/a/b/actions/permissions']\n", + 'docs/guard.md': 'PUT repos/a/b/actions/permissions enabled=false is refused\n', + 'wrc': 'method = PUT\n', + 'cfg/.curlrc': 'request = PUT\n', + 'vars.sh': 'M=PUT\n', +} + + +class AttackTest(Case): + """#1436: the bypasses. Each ATTACKS case must be refused, each ALLOW_MORE case must pass.""" + + def setUp(self): + super().setUp() + self.env = {'HOME': self.dir} # gh's own config folder ($HOME/.config/gh) is not there: no aliases + for name, text in FILES.items(): + self.write(name, text, 0o755 if name.endswith('.sh') else 0o644) + + def test_attacks_are_refused(self): + for group, cmds in ATTACKS.items(): + for cmd in cmds: + with self.subTest(group=group, cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + + def test_the_rest_still_passes(self): + for cmd in ALLOW_MORE: + with self.subTest(cmd=cmd): + self.assertIsNone(self.decide(cmd), cmd) + + def test_known_over_refusals_say_what_to_change(self): + # harmless, but not provable from the text: refused, and the message names the way that passes + for cmd, hint in OVER_REFUSED: + with self.subTest(cmd=cmd): + self.assertIn(hint, self.decide(cmd) or '', cmd) + + def test_issue_1436_cases_name_what_was_read(self): + # the exact calls of the issue: the PUT is read as a PUT, and the reason says so + for cmd in (f'gh api -X PUT -p -XGET {P} {OFF}', f'gh api -iXPUT {P} {OFF}'): + self.assertIn('a PUT with', self.decide(cmd), cmd) + + def test_api_parse_reads_flags_as_gh_does(self): + parse = self.g.api_parse + for args, flags, pos in ( + (['-X', 'PUT', '-p', '-XGET', 'p'], [('method', 'PUT'), ('preview', '-XGET')], ['p']), + (['--jq', '--method=GET', 'p'], [('jq', '--method=GET')], ['p']), + (['-iXPUT', 'p'], [('method', 'PUT')], ['p']), + (['-iX', 'PUT', 'p'], [('method', 'PUT')], ['p']), + (['-X=PUT', 'p'], [('method', 'PUT')], ['p']), + (['-XPUT', 'p'], [('method', 'PUT')], ['p']), + (['--method=put', 'p'], [('method', 'put')], ['p']), + (['--method', 'PUT', 'p'], [('method', 'PUT')], ['p']), + (['p', '-iFa=b', '-fc=d'], [('field', 'a=b'), ('raw-field', 'c=d')], ['p']), + (['p', '--input=-', '--paginate', '--slurp'], [('input', '-')], ['p']), + (['-F', 'a=b', '--', '-X', 'p'], [('field', 'a=b')], ['-X', 'p']), + (['-H', 'A: b', '-q', '.x', '-t', '{{.x}}', 'p'], + [('header', 'A: b'), ('jq', '.x'), ('template', '{{.x}}')], ['p']), + (['p', '-'], [], ['p', '-'])): + with self.subTest(args=args): + self.assertEqual(parse(args), (flags, pos, '')) + for args in (['--nope', 'p'], ['-Z', 'p'], ['p', '-X'], ['p', '--method'], ['-iZXPUT', 'p'], ['--meth=PUT', 'p'], + ['--Method', 'PUT', 'p']): + with self.subTest(args=args): + self.assertTrue(parse(args)[2], args) # fails closed: the caller counts it as a write + + def test_words_are_read_as_bash_reads_them(self): + # the lexer against the real shell: harmless words only, each as bash hands them to a command + bash = '/bin/bash' if os.path.exists('/bin/bash') else '/usr/bin/bash' + if not os.path.exists(bash): + self.skipTest('no bash here') + cases = ( + "args a 'b c' \"d e\" f\\ g", + "args 'a'\"b\"c\\d \"\" ''", + "args $'a\\x41\\tb' $'\\101\\u0042' $'it\\'s'", + "args \"a\\\"b\" \"a\\$b\" \"a\\b\" 'a\\b'", + "args a\\\nb c \\\n d", + "args a#b # c d\n", + "args 'a\nb' \"c\nd\"", + "X=1; args \"$X\" ${X}2 '$X' \"${X}\" $X$X", + "X='a b'; args \"$X\" $X", + "X=a; Y=${X}b; args $Y \"$Y$X\"", + "args a;args b", + "args a&&args b", + "args < /dev/null b 2>&1 < /dev/null c", + "args --flag=value -x -- -y", + "args \"a 'b' c\" 'a \"b\" c'", + "args a~b a=b =c", + ) + for text in cases: + with self.subTest(text=text): + r = subprocess.run([bash, '--norc', '--noprofile', '-c', + 'args() { printf "%s\\0" "$@"; }\n' + text], + capture_output=True, text=True, cwd=self.dir, timeout=60, + env={'PATH': '/usr/bin:/bin', 'HOME': self.dir}) + want = r.stdout.split('\0')[:-1] + got = [t for seg in self.g.segments(text) if seg[:1] == ['args'] for t in seg[1:]] + self.assertEqual(got, want, r.stderr) + + def test_a_long_command_is_decided_in_time(self): + # the hook has a time limit; a long, nested, many-valued command must not run it out + import time + cmd = '; '.join(f'V{i}=a{i}; W{i}=${{V{i}}}{{x,y}}$(echo "$(echo {i})")' for i in range(60)) + cmd += '; ' + ' '.join(f'"$V{i}"$W{i}' for i in range(60)) + '; gh workflow $W1 $W2 1; gh api "$V1/$W2" -X GET' + cmd += '\n' + 'echo text of a long heredoc line\n' * 3000 + t = time.monotonic() + self.decide(cmd) + self.assertLess(time.monotonic() - t, 8) # timing: the hook's 10 s limit; a slower guard is the bug + + def test_out_of_time_fails_closed(self): + # A hook that is not done at its time limit does not stop the command. So the guard stops itself first + # and refuses: what it could not read to the end (a script the command runs, a word put together from + # variables) may be the disabling call. + for cmd in ('A=dis; B=able; gh workflow $A$B 1', 'bash sub/dis.sh', 'bash sub/ok.sh', 'ls -la $X'): + with self.subTest(cmd=cmd): + self.assertIn('could not finish', self.g.decide(cmd, self.dir, self.env, budget=-1) or '', cmd) + # #1752: a command the fast exit passes needs no time at all (it reads nothing), so it passes out of time too + self.assertIsNone(self.g.decide('ls -la', self.dir, self.env, budget=-1)) + self.assertIsNone(self.g.decide('gh pr list', self.dir, self.env, budget=60)) + self.assertIsNone(self.g.decide('gh pr list', self.dir, self.env)) + self.assertFalse(issubclass(self.g.Slow, Exception)) # an `except Exception` in the guard cannot swallow it + self.assertLessEqual(self.g.BUDGET, 5.0) # #1752: well under the 10 s limit the hook is registered with + + def test_a_script_is_read_once_however_often_it_is_run(self): + # a script that runs its helper two hundred times (and itself) must not take two hundred reads + import time + self.write('helper.sh', '#!/bin/sh\n' + 'gh pr view "$1" --json state\n' * 40) + self.write('big.sh', '#!/bin/sh\n' + './helper.sh 1\n' * 200 + './big.sh again\n') + t = time.monotonic() + self.assertIsNone(self.decide('./big.sh')) + self.assertLess(time.monotonic() - t, 4) # timing: one read per script; 200 reads would take far longer + self.write('helper.sh', '#!/bin/sh\ngh workflow disable "$1"\n') + why = self.decide('./big.sh') + self.assertIn('big.sh', why) + self.assertIn('helper.sh', why) # the reason names the script that holds the call + + def test_an_exact_copy_of_the_guard_is_the_guard(self): + # the repo copy next to the installed one: running it (for a manual check) is not "a script that disables" + with open(HOOK, encoding='utf-8') as f: + text = f.read() + self.write('copy/actions-disable-guard', text) + self.assertIsNone(self.decide('echo {} | python3 -I copy/actions-disable-guard')) + self.write('copy/other-guard', text + "\nsubprocess.run(['gh', 'workflow', 'disable', '1'])\n") + self.assertIsNotNone(self.decide('python3 -I copy/other-guard')) + + def test_alias_from_config_and_from_the_text_itself(self): + # an alias of the gh config next to one set in the same command: both are followed + self.write('.config/gh/config.yml', 'aliases:\n w: workflow\n', 0o644) + self.assertIsNotNone(self.decide('gh w disable 1')) + self.assertIsNone(self.decide('gh w list')) + self.assertIsNotNone(self.decide("gh alias set d 'w disable' && gh d 1")) + self.assertIsNotNone(self.decide("gh alias set d 'w disable'")) + + def test_body_files_are_read_when_the_call_is_checked(self): + # the same call passes or is refused by what the file holds now + self.write('rs.json', FILES['rs_on.json'], 0o644) + cmd = 'gh api -X PUT repos/a/b/rulesets/1 --input rs.json' + self.assertIsNone(self.decide(cmd)) + self.write('rs.json', FILES['rs_off.json'], 0o644) + self.assertIsNotNone(self.decide(cmd)) + # a file written by the same command is not there yet: its text is read from the command + for cmd in ("echo '{\"enforcement\": \"disabled\"}' > new.json && gh api -X PUT repos/a/b/rulesets/1 " + "--input new.json", + 'printf \'{\\"enforcement\\":\\"disabled\\"}\' > new.json; gh api -X PUT repos/a/b/rulesets/1 ' + '--input new.json', + 'gh api -X PUT repos/a/b/rulesets/1 --input "$(ls *.json | head -1)"', + 'python3 gen.py | gh api -X PUT repos/a/b/rulesets/1 --input -'): + with self.subTest(cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + + +class GuardTest(Case): + def test_deny(self): + for cmd in DENY: + with self.subTest(cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + + def test_allow(self): + for cmd in ALLOW: + with self.subTest(cmd=cmd): + self.assertIsNone(self.decide(cmd), cmd) + + def test_reason_names_rule_owner_and_marker(self): + why = self.decide('gh workflow disable 1') + for part in ('owner', 'refuse', MARK_ENV, 'must not'): + self.assertIn(part, why) + + # scripts the command runs + def test_shell_script_file(self): + self.write('dis.sh', '#!/bin/bash\nset -e\nfor i in 1 2; do\n gh workflow disable "$i" -R a/b\ndone\n') + for cmd in ('bash dis.sh', 'sh ./dis.sh', './dis.sh', 'source dis.sh', '. dis.sh', + f'{self.dir}/dis.sh', 'cd /tmp && bash ' + os.path.join(self.dir, 'dis.sh'), 'timeout 9 ./dis.sh'): # timing: guard input, not a wait + with self.subTest(cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + + def test_python_script_file(self): + self.write('a.py', "import subprocess\nsubprocess.run(['gh', 'workflow', 'disable', '1'])\n") + self.write('b.py', "import urllib.request as u\nu.urlopen(u.Request(" + "'https://api.github.com/repos/a/b/actions/workflows/1/disable', method='PUT'))\n") + self.write('c.py', "requests.put(f'{API}/repos/{repo}/actions/permissions', json={'enabled': False})\n") + for cmd in ('python3 a.py', 'python3 -u b.py --x', './c.py', 'uv run c.py', 'python3 -I a.py'): + with self.subTest(cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + + def test_script_on_path_in_home(self): + self.write('.local/bin/wfoff', '#!/bin/sh\ngh api -X PUT "repos/$1/actions/workflows/$2/disable"\n') + env = dict(self.env, PATH=os.path.join(self.dir, '.local/bin') + ':/usr/bin') + self.assertIsNotNone(self.decide('wfoff a/b 1', env)) + + def test_harmless_scripts_pass(self): + # messages that only mention the command (a sync script, example_garden.py read-only) are no call + self.write('ok.py', "print(f'disable: `gh workflow disable {wid} -R {repo}`')\n" + "subprocess.run(['gh', 'workflow', 'enable', wid])\n" + "gh('api', api_path('repos', repo, 'actions/permissions'))\n") + self.write('ok.sh', '#!/bin/sh\necho "run gh workflow enable"\ngh api repos/a/b/actions/permissions\n') + self.write('plain.py', "print('hello')\n") + for cmd in ('python3 plain.py', './plain.py', 'taskset 1 ./plain.py', 'bash ok.sh', './ok.sh', + 'python3 missing.py', 'bash'): + with self.subTest(cmd=cmd): + self.assertIsNone(self.decide(cmd), cmd) + # Code in another language that names a guarded token: the guard reads shell, not Python, so it cannot + # tell the mention from the call (lens round on #1543: requests.delete(...) of branch protection passed). + # Known over-refusal; the tests of such a tool run through run_tests.py, which is read and names none. + self.assertIn('cannot prove', self.decide('python3 ok.py')) + + def test_text_files_and_the_guard_itself_are_not_scripts(self): + self.write('docs/plan.md', 'Then PUT repos/a/b/actions/permissions enabled=false.\n', 0o644) + self.write('notes.txt', 'gh workflow disable 1\n', 0o644) + for cmd in ('docs/plan.md', './notes.txt', f'{self.dir}/docs/plan.md', + 'echo {} | python3 -I ' + HOOK, HOOK + ' < event.json'): + with self.subTest(cmd=cmd): + self.assertIsNone(self.decide(cmd), cmd) + self.assertIsNotNone(self.decide('bash notes.txt')) # run through a shell, any file is a script + + def test_a_listed_script_with_its_flag_is_refused_read_only_passes(self): + self.write('scripts/dev/example_garden.py', "print('read-only checks')\n") + self.assertIsNotNone(self.decide('python3 scripts/dev/example_garden.py --fix')) + self.assertIsNotNone(self.decide('python3 scripts/dev/example_garden.py --only minestom --fix --days 3')) + self.assertIsNone(self.decide('python3 scripts/dev/example_garden.py')) + self.assertIsNone(self.decide('python3 scripts/dev/example_garden.py --only minestom')) + self.assertIsNone(self.decide('echo "the gardener ran example_garden.py --fix" >> notes.md')) + self.assertIsNone(self.decide('gh issue comment 1 --body "held (see #719; run example_garden.py --fix later)"')) + + def test_stdin_script_argument_is_data(self): + self.write('body.md', 'PUT repos/a/b/actions/permissions enabled=false\n', 0o644) + self.assertIsNone(self.decide("python3 - body.md <<'EOF'\nimport sys\nprint(open(sys.argv[1]).read())\nEOF")) + + def test_existing_gh_alias_is_expanded(self): + self.write('gh/config.yml', 'version: 1\naliases:\n co: pr checkout\n wd: workflow disable\n' + ' off: \'!gh api -X PUT repos/$1/actions/permissions -F enabled=false\'\n', 0o644) + self.assertIsNotNone(self.decide('gh wd 1')) + self.assertIsNotNone(self.decide('gh off a/b')) + self.assertIsNone(self.decide('gh co 12')) + + def test_alias_import_file(self): + self.write('al.yml', 'wd: workflow disable\n', 0o644) + self.assertIsNotNone(self.decide('gh alias import al.yml')) + + # the owner's escape hatch + def hatch_env(self, value): + return dict(self.env, **{MARK_ENV: value}) + + def test_hatch_needs_env_of_today_and_marker(self): + cmd = f'gh workflow disable 1 -R a/b {MARK_CMD}' + self.assertIsNone(self.decide(cmd, self.hatch_env(today()))) + self.assertIsNotNone(self.decide('gh workflow disable 1 -R a/b', self.hatch_env(today()))) + self.assertIsNotNone(self.decide(cmd, self.hatch_env('2026-01-01'))) + self.assertIsNotNone(self.decide(cmd, self.hatch_env('1'))) + self.assertIsNotNone(self.decide(cmd)) + + def test_hatch_refused_when_set_in_a_settings_file(self): + self.write('.claude/settings.json', json.dumps({'env': {MARK_ENV: today()}}), 0o644) + cmd = f'gh workflow disable 1 {MARK_CMD}' + why = self.decide(cmd, self.hatch_env(today())) + self.assertIsNotNone(why) + self.assertIn('settings', why) + + # the hook as Claude Code runs it: JSON on stdin, JSON decision on stdout + def pipe(self, payload, env=None): + e = {'PATH': '/usr/bin:/bin', 'HOME': self.dir} + e.update(env or {}) + return subprocess.run([sys.executable, '-I', HOOK], input=payload, capture_output=True, text=True, + env=e, timeout=60) + + def event(self, cmd, tool='Bash'): + return json.dumps({'session_id': 't', 'hook_event_name': 'PreToolUse', 'tool_name': tool, 'cwd': self.dir, + 'tool_input': {'command': cmd, 'description': 'x'}}) + + def test_pipe_deny(self): + r = self.pipe(self.event('gh workflow disable 999999999 -R example/no-such-scratch-repo')) + self.assertEqual(r.returncode, 0, r.stderr) + out = json.loads(r.stdout)['hookSpecificOutput'] + self.assertEqual(out['hookEventName'], 'PreToolUse') + self.assertEqual(out['permissionDecision'], 'deny') + self.assertIn('owner', out['permissionDecisionReason']) + + def test_pipe_refusal_is_logged_and_a_failed_log_still_refuses(self): + home = os.path.join(self.dir, 'loghome') + os.makedirs(home) + log = os.path.join(home, '.local', 'state', 'actions-disable-guard', 'log') + for n in (1, 2): # no folder yet: it is made; a second refusal adds a line + r = self.pipe(self.event('gh workflow disable 1'), {'HOME': home}) + self.assertEqual(json.loads(r.stdout)['hookSpecificOutput']['permissionDecision'], 'deny') + with open(log) as f: + lines = f.read().splitlines() + self.assertEqual(len(lines), n) + self.assertIn('gh workflow disable 1', json.loads(lines[-1].split(' ', 1)[1])['cmd']) + self.pipe(self.event('ls'), {'HOME': home}) # what passes writes nothing + with open(log) as f: + self.assertEqual(len(f.read().splitlines()), 2) + blocked = os.path.join(self.dir, 'nolog') + os.makedirs(blocked) + with open(os.path.join(blocked, '.local'), 'w') as f: # the log folder cannot be made + f.write('a file, not a folder') + r = self.pipe(self.event('gh workflow disable 1'), {'HOME': blocked}) + self.assertEqual(json.loads(r.stdout)['hookSpecificOutput']['permissionDecision'], 'deny') + + def test_pipe_allow_is_silent(self): + for payload in (self.event('gh workflow enable 1'), self.event('ls'), + self.event('gh workflow disable 1', tool='Read')): + r = self.pipe(payload) + self.assertEqual((r.returncode, r.stdout), (0, ''), r.stderr) + + def test_pipe_bad_input_fails_closed_only_when_it_looks_dangerous(self): + r = self.pipe('{"tool_name": "Bash", "tool_input": {"command": ') # cut off + self.assertEqual((r.returncode, r.stdout), (0, '')) + r = self.pipe('not json but gh workflow disable 1') + self.assertEqual(json.loads(r.stdout)['hookSpecificOutput']['permissionDecision'], 'deny') + + def test_pipe_internal_error_fails_closed(self): + r = self.pipe(self.event('gh workflow disable 1'), {'ACTIONS_DISABLE_GUARD_TEST_CRASH': '1'}) + self.assertEqual(json.loads(r.stdout)['hookSpecificOutput']['permissionDecision'], 'deny') + r = self.pipe(self.event('ls -la'), {'ACTIONS_DISABLE_GUARD_TEST_CRASH': '1'}) + self.assertEqual((r.returncode, r.stdout), (0, '')) + # a call the plain word search would miss: gh with the word put together from variables + r = self.pipe(self.event('A=dis; gh "work""flow" ${A}able 1'), {'ACTIONS_DISABLE_GUARD_TEST_CRASH': '1'}) + self.assertEqual(json.loads(r.stdout)['hookSpecificOutput']['permissionDecision'], 'deny') + + def test_hook_out_of_time_refuses(self): + # the whole hook, with no time at all: it answers "deny" itself instead of running into the hook limit + import contextlib, io + from unittest import mock + for cmd, verdict in (('bash x.sh', 'deny'), ('ls', None)): # #1752: the fast exit needs no time + out = io.StringIO() + with mock.patch.object(self.g, 'BUDGET', -1), \ + mock.patch.object(sys, 'stdin', io.StringIO(self.event(cmd))), \ + mock.patch.dict(os.environ, {'HOME': self.dir}), contextlib.redirect_stdout(out): + self.assertEqual(self.g.main(), 0) + if verdict is None: + self.assertEqual(out.getvalue(), '', cmd) + continue + got = json.loads(out.getvalue())['hookSpecificOutput'] + self.assertEqual(got['permissionDecision'], 'deny') + self.assertIn('could not finish', got['permissionDecisionReason']) + + # correctness lens m2 on #1543: the time budget counts from the start of the hook process, not from decide() + def test_time_already_used_before_checking_counts(self): + import contextlib, io + from unittest import mock + out = io.StringIO() + with mock.patch.object(self.g, 'process_age', lambda: self.g.BUDGET + 1), \ + mock.patch.object(sys, 'stdin', io.StringIO(self.event('bash x.sh'))), \ + mock.patch.dict(os.environ, {'HOME': self.dir}), contextlib.redirect_stdout(out): + self.assertEqual(self.g.main(), 0) + got = json.loads(out.getvalue())['hookSpecificOutput'] + self.assertEqual(got['permissionDecision'], 'deny') + self.assertIn('could not finish', got['permissionDecisionReason']) + + def test_process_age_is_never_less_than_the_time_since_load(self): + import time + since = time.monotonic() - self.g.START + self.assertGreaterEqual(self.g.since_start(), since - 0.05) + self.assertEqual(self.g.process_age(), 0.0) # loaded as a module (tests, gh-as): no hook clock + self.assertLessEqual(self.g.BUDGET, 5.0) # #1752: at least 5 s under Claude Code's 10 s hook limit + + def test_a_slow_start_of_the_hook_eats_the_budget(self): + # The real hook as a process that is slow before it checks anything (a loaded machine, slow imports, a slow + # stdin): with a 1 s budget and 1.3 s gone before main() runs it must refuse, not start a fresh budget. + # #1752: a command the fast exit passes still passes (it is decided without any file or clock). + with open(HOOK, encoding='utf-8') as f: + text = f.read() + last = "\nif __name__ == '__main__':" + self.assertIn('\nBUDGET = 5.0\n', text) + self.assertIn(last, text) + body, _, tail = text.replace('\nBUDGET = 5.0\n', '\nBUDGET = 1.0\n', 1).rpartition(last) + self.write('slow-hook', body + '\ntime.sleep(1.3)' + last + tail) + for cmd in ('bash x.sh', 'ls -la'): + r = subprocess.run([sys.executable, '-I', os.path.join(self.dir, 'slow-hook')], input=self.event(cmd), + capture_output=True, text=True, env={'PATH': '/usr/bin:/bin', 'HOME': self.dir}, + timeout=60) + if cmd == 'ls -la': + self.assertEqual((r.returncode, r.stdout), (0, ''), r.stderr) + continue + got = json.loads(r.stdout)['hookSpecificOutput'] + self.assertEqual(got['permissionDecision'], 'deny') + self.assertIn('could not finish', got['permissionDecisionReason']) + + +class LensRound1Test(Case): + """Lens round on #1543: what the lists above do not hold (files with the executable bit, state, m1).""" + + def setUp(self): + super().setUp() + self.env = {'HOME': self.dir} + for name, text in FILES.items(): + self.write(name, text, 0o755 if name.endswith('.sh') else 0o644) + + def test_an_executable_script_in_another_language(self): + self.write('offx.py', '#!/usr/bin/env python3\n' + FILES['off.py']) + self.write('okx.py', "#!/usr/bin/env python3\nprint('hello')\n") + for cmd in ('./offx.py', 'taskset 1 ./offx.py', 'sometool run offx.py'): + with self.subTest(cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + for cmd in ('./okx.py', 'taskset 1 ./okx.py', 'sometool run okx.py', 'cp offx.py /tmp/x.py', + "git add offx.py && git commit -m 'fix the guard' offx.py", 'sometool commit -m fix .'): + with self.subTest(cmd=cmd): + self.assertIsNone(self.decide(cmd), cmd) + + def test_source_and_eval_as_the_command_word_still_hide_variables(self): + # correctness lens m1: the other half. These set M where the guard cannot see it: the call counts as a write + for cmd in (f'M=GET; . ./vars.sh; gh api -X $M {P} {OFF}', + f'M=GET; source vars.sh; gh api -X $M {P} {OFF}', + f'M=GET; eval "$Z"; gh api -X $M {P} {OFF}', + f'M=GET; command eval "$Z"; gh api -X $M {P} {OFF}', + f'M=GET; builtin source vars.sh; gh api -X $M {P} {OFF}', + f'M=GET; true && . vars.sh; gh api -X $M {P} {OFF}', + f"M=GET; trap 'M=PUT' EXIT; gh api -X $M {P} {OFF}", + f'M=GET; f() {{ . ./vars.sh; }}; f; gh api -X $M {P} {OFF}'): + with self.subTest(cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + + def test_curl_and_wget_config_rule(self): + # (c) of the round: the flag rule. It is read from the command text alone, so it holds whatever the rc + # files say, wherever the tool looks for them, and whatever the same command writes there first. + self.write('.curlrc', 'request = PUT\ndata = "{\\"enabled\\": false}"\n', 0o644) + self.write('.wgetrc', 'method = PUT\n', 0o644) + self.assertIn('-q', self.decide(f'curl -sS {U}')) + self.assertIn('--no-config', self.decide(f'wget -qO- {U}')) + for cmd in (f'curl -s -q {U}', # -q is only honoured as the first argument + f"printf '%s\\n' 'request = PUT' > ~/.curlrc; curl -sS {U}", + f'ionice -c3 wget --method=PUT --no-config {U}', + f'curl -q -X PUT {U} -d @body.json'): + with self.subTest(cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + for cmd in (f'curl -q -sS {U}', f'curl --disable -sS {U}', f'wget --no-config -qO- {U}', + f"printf '%s\\n' 'request = PUT' > ~/.curlrc; curl -q -sS {U}"): + with self.subTest(cmd=cmd): + self.assertIsNone(self.decide(cmd), cmd) + + def test_a_file_under_the_name_of_a_wrapper_or_a_shell(self): + # found while fixing the round (the old guard passes them too): `bash nice` runs the FILE nice of the + # folder, `./sudo` is a file of the project. Neither is the wrapper of that name. + for name in ('nice', 'sudo', 'sh', 'wrap/env'): + self.write(name, 'gh workflow disable 1\n') + self.write('fine/sudo', 'echo hi\n') + self.write('ok.sh', '#!/bin/sh\necho hi\n') + for cmd in ('bash nice', 'bash sh', 'sh -x nice', 'env bash nice', 'timeout 5 bash sh', 'source nice', # timing: guard input, not a wait + '. sudo', './sudo', './sudo ls', 'wrap/env ls', 'nice -n 5 ./sudo'): + with self.subTest(cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + for cmd in ('sudo ls', 'nice -n 5 ls', '/usr/bin/env ls', 'busybox sh -c "nice ls"', 'bash -c "nice ls"', + 'fine/sudo ls', 'bash ok.sh', 'env -i bash ok.sh'): + with self.subTest(cmd=cmd): + self.assertIsNone(self.decide(cmd), cmd) + + def test_a_file_that_names_a_token_goes_on_under_another_name(self): + # (a) of the round: a file the command reads or writes. cp/mv/ln give its text a new name, and the same + # command then runs a word the guard cannot read. + self.write('ok.sh', '#!/bin/sh\necho hi\n') + self.write('ok.py', "print('hello')\n", 0o644) + for cmd in ('cp sub/dis.sh run.sh && bash run.sh', 'cp off.py run.py && python3 run.py', + 'mv sub/dis.sh x; sometool x', 'ln -s sub/dis.sh x && ./x', 'cat sub/dis.sh > x; sometool x'): + with self.subTest(cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + for cmd in ('cp sub/dis.sh keep.txt', 'cp off.py backup/ && git status', 'mv off.py lib/off.py; ls lib', + 'cp ok.sh run.sh && bash run.sh', 'cp ok.py x.py && sometool x.py'): + with self.subTest(cmd=cmd): + self.assertIsNone(self.decide(cmd), cmd) + + def test_arguments_that_come_from_a_file(self): + # curl -K, wget -i, xargs -a: the request is in a file, the command text names no token at all + self.write('k.cfg', f'url = "{U}"\nrequest = PUT\ndata = "{{\\"enabled\\": false}}"\n', 0o644) + self.write('urls.txt', U + '\n', 0o644) + self.write('fine.cfg', 'url = "https://api.github.com/repos/a/b/pulls"\n', 0o644) + for cmd in ('curl -q -K k.cfg', 'curl -q -sK k.cfg', 'curl -q -Kk.cfg', 'curl -qK k.cfg', + 'curl -q --config k.cfg', 'curl -q --config=k.cfg', 'wget --no-config -i urls.txt --method=PUT', + 'wget --no-config --input-file=urls.txt --post-data=enabled=false', 'xargs -a k.cfg curl -q', + 'X=$(cat urls.txt); curl -q -X PUT "$X" -d x', 'curl -q -X PUT "$(cat urls.txt)" -d x'): + with self.subTest(cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + for cmd in ('curl -q -K fine.cfg', 'curl -q -sK fine.cfg', 'cat urls.txt', 'xargs -a fine.cfg echo', + 'curl -q -s "https://api.github.com/repos/$R/pulls"', + 'curl -q -s -H "Authorization: Bearer $(gh auth token)" ' + U): + with self.subTest(cmd=cmd): + self.assertIsNone(self.decide(cmd), cmd) + + def test_state_half_written_empty_and_missing(self): + # State question of the round: the guard keeps no state of its own; what it meets on disk may be old, + # half-written or missing. + self.write('half/config.yml', "version: 1\naliases:\n co: pr checkout\n wd: 'workflow dis", 0o644) + self.write('nul/config.yml', '', 0o644) + self.assertIsNotNone(self.decide('GH_CONFIG_DIR=half gh wd 1')) # the alias may be the cut-off one + self.assertIsNotNone(self.decide('GH_CONFIG_DIR=half gh co 1')) # known over-refusal: no gh command + self.assertIsNone(self.decide('GH_CONFIG_DIR=half gh pr list')) # a real gh command needs no alias table + for cfg in ('nul', 'nowhere'): # an empty file, no folder: no aliases, gh itself rejects the word + self.assertIsNone(self.decide(f'GH_CONFIG_DIR={cfg} gh pr list')) + self.assertIsNotNone(self.decide(f'GH_CONFIG_DIR={cfg} gh workflow disable 1')) + for env in ({}, {'HOME': ''}, {'HOME': os.path.join(self.dir, 'gone')}): # no HOME at all + with self.subTest(env=env): + self.assertIsNone(self.g.decide('gh pr list', self.dir, dict(env))) + self.assertIsNone(self.g.decide(f'curl -q -sS {U}', self.dir, dict(env))) + self.assertIsNotNone(self.g.decide('gh workflow disable 1', self.dir, dict(env))) + self.assertIsNotNone(self.g.decide('taskset 1 bash sub/dis.sh', self.dir, dict(env))) + # run again: the same answer every time, and nothing written by a command that passes + before = sorted(os.listdir(self.dir)) + self.assertEqual([self.decide(f'gh api {P}') for _ in range(3)], [None] * 3) + self.assertEqual(sorted(os.listdir(self.dir)), before) + + +class LensSecurityR1Test(Case): + """Lens security (guard bypass) on #1543: every command here must be refused; each fails on 7c3268a.""" + + def refused(self, *cmds): + for cmd in cmds: + with self.subTest(cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + + def test_unlisted_launcher_runs_shell_text_or_a_client(self): + self.refused("taskset -c 0 bash -c 'gh workflow disable 1'", + "chrt 0 sh -c 'gh workflow disable 1'", + "unshare -r bash -c 'gh workflow disable 1'", + "sg users -c 'gh workflow disable 1'", + "screen -dm bash -c 'gh workflow disable 1'", + "tmux new-session -d 'gh workflow disable 1'", + "at now <<< 'gh workflow disable 1'", + "expect -c 'spawn gh workflow disable 1'", + "taskset 1 curl -sS -X PUT https://api.github.com/repos/a/b/actions/permissions " + "-d '{\"enabled\":false}'", + "taskset 1 python3 -c \"import requests; " + "requests.put('https://api.github.com/repos/a/b/actions/permissions')\"") + + def test_gh_binary_under_another_name(self): + self.refused('ln -sf /usr/bin/gh ./g && ./g workflow disable 1', + 'cp /usr/bin/gh ./hub; ./hub api -X PUT repos/a/b/actions/permissions -F enabled=false') + + def test_gh_config_yaml_forms_gh_reads(self): + # gh 2.102 `gh alias list` shows both as wd: workflow disable + for text in ('aliases:\n wd: !!str workflow disable\n', 'aliases:\n ? wd\n : workflow disable\n'): + with self.subTest(text=text): + self.write('gh/config.yml', text, 0o644) + self.assertIsNotNone(self.decide('gh wd 1')) + + def test_json_escapes_and_graphql_ruleset_off(self): + self.write('rs.json', '{"enforcement": "\\u0064isabled"}\n', 0o644) + self.write('gq.json', '{"query": "mutation { deleteBranchProtectionRul\\u0065(input: ' + '{branchProtectionRuleId: \\"x\\"}) { clientMutationId } }"}\n', 0o644) + self.refused('gh api -X PUT repos/a/b/rulesets/1 --input rs.json', + "gh api -X PUT repos/a/b/rulesets/1 --input - <<'E'\n{\"enforcement\": \"\\u0064isabled\"}\nE", + 'gh api graphql --input gq.json', + "gh api graphql -f query='mutation { updateRepositoryRuleset(input: " + "{repositoryRulesetId: \"x\", enforcement: DISABLED}) { clientMutationId } }'") + + def test_code_that_deletes_protection_or_a_ruleset(self): + self.refused("python3 -c \"import requests; " + "requests.delete('https://api.github.com/repos/a/b/branches/main/protection')\"", + "node -e \"fetch('https://api.github.com/repos/a/b/rulesets/1', {method: 'DELETE'})\"") + + def test_curlrc_makes_a_plain_read_a_write(self): + self.write('.curlrc', 'request = PUT\ndata = "{\\"enabled\\": false}"\n', 0o644) + self.refused('curl -sS https://api.github.com/repos/a/b/actions/permissions') + + def test_branch_name_with_a_slash(self): + self.refused('gh api -X DELETE repos/a/b/branches/release/1.0/protection') + + + +class LensCorrR2Test(Case): + """Lens correctness re-check on #1543 (head b592fb8f): bash runs each command below; each is let through.""" + + def refused(self, *cmds): + for cmd in cmds: + with self.subTest(cmd=cmd[-70:]): + self.assertIsNotNone(self.decide(cmd), cmd[-70:]) + + def test_more_than_400_substitutions_hide_the_rest(self): + for n in (399, 1000): + self.refused('echo ' + '$(:) ' * n + '; $(gh workflow disable 1)', + 'echo ' + '$(:) ' * n + '; echo "$(gh api -X PUT repos/a/b/actions/permissions ' + '-F enabled=false)"', + 'echo ' + '$(' * (n + 1) + 'gh workflow disable 1' + ')' * (n + 1)) + + def test_script_over_max_file_runs_unread(self): + self.write('run.sh', '#!/bin/bash\n' + ('#' * 100 + '\n') * 21000 + 'gh workflow disable 1\n') + self.refused('bash run.sh', './run.sh', 'source run.sh', 'bash < run.sh', 'cat run.sh | bash') + + def test_alarm_is_off_before_the_slow_handlers(self): + import io, time + g = load() + g.process_age = lambda: 5.5 + g.decide = lambda *a: (_ for _ in ()).throw(RuntimeError('crash')) + g.log = lambda *a: time.sleep(1.5) + out, old_in, old_out = io.StringIO(), sys.stdin, sys.stdout + sys.stdin = io.StringIO(json.dumps({'tool_name': 'Bash', 'cwd': self.dir, + 'tool_input': {'command': 'gh workflow disable 1'}})) + sys.stdout = out + try: + g.main() + except BaseException as e: + self.fail(f'{type(e).__name__} left main(): the hook exits 1 and the command runs') + finally: + sys.stdin, sys.stdout = old_in, old_out + self.assertIn('"deny"', out.getvalue()) + + +class Round3Test(Case): + """Fix round 3 on #1543: where the guard stops reading (a limit, a file too big, time, its own crash) it never + passes a guarded command; data, binaries and token-free text keep passing (lockout care). Red on b592fb8.""" + T = 'gh workflow disable 1' + PAD = ('#' * 100 + '\n') * 21000 # 2.1 MB: over MAX_FILE + + def refused(self, *cmds, says=''): + for cmd in cmds: + with self.subTest(cmd=cmd[-70:]): + why = self.decide(cmd) + self.assertIsNotNone(why, cmd[-70:]) + self.assertIn(says, why, cmd[-70:]) + + def passes(self, *cmds): + for cmd in cmds: + with self.subTest(cmd=cmd[-70:]): + self.assertIsNone(self.decide(cmd), cmd[-70:]) + + def main_out(self, g, cmd): + import contextlib, io + from unittest import mock + out = io.StringIO() + ev = json.dumps({'tool_name': 'Bash', 'cwd': self.dir, 'tool_input': {'command': cmd}}) + with mock.patch.object(sys, 'stdin', io.StringIO(ev)), mock.patch.dict(os.environ, {'HOME': self.dir}), \ + contextlib.redirect_stdout(out): + try: + g.main() + except BaseException as e: + self.fail(f'{type(e).__name__} left main(): the hook exits 1 and the command runs') + return out.getvalue() + + def test_slow_in_the_handlers_still_denies(self): + def slow(*a): + raise g.Slow() + for where in ('named', 'log', 'deny'): + with self.subTest(where=where): + g, calls = load(), [] + if where == 'named': # decide crashes, then the crash handler runs out of time + g.decide = lambda *a: (_ for _ in ()).throw(RuntimeError('crash')) + g.named = slow + elif where == 'log': + g.log = slow + else: # the first answer runs out of time half-way; the second one is the answer + real = g.deny + g.deny = lambda why: calls.append(why) or (real(why) if len(calls) > 1 else slow()) + self.assertIn('"deny"', self.main_out(g, self.T)) + + def test_a_script_too_big_to_read_whole(self): + self.write('run.py', 'import os\n' + self.PAD + f'os.system("{self.T}")\n', 0o644) + self.write('run.sh', '#!/bin/sh\n' + self.PAD + self.T + '\n') + self.write('ok.sh', '#!/bin/sh\n' + self.PAD + 'echo hi\n') + head = '#!/bin/sh\n' # the token across the first 1 MB piece: the pieces overlap + self.write('edge.sh', head + '#' * ((1 << 20) - len(head) - 10) + '\n' + self.T + '\n' + self.PAD) + self.write('empty.sh', '') + self.refused('python3 run.py', 'uv run run.py', 'at -f run.sh now', 'bash edge.sh', 'nice ./run.sh', + says='read in pieces, it names') + self.passes('bash ok.sh', 'bash empty.sh', 'bash no-such.sh') + from unittest import mock + with mock.patch.object(self.g, 'HARD_FILE', 2_500_000): + self.write('huge.sh', '#!/bin/sh\n' + self.PAD * 2) + self.refused('bash huge.sh', 'source huge.sh', says='it is a file over') + if os.geteuid() != 0: + self.write('nr.sh', '#!/bin/sh\necho hi\n', 0o000) + self.refused('bash nr.sh', 'source nr.sh', says='cannot open it') + + def test_big_data_and_binaries_keep_passing(self): + self.write('big.log', self.PAD + self.T + '\n', 0o644) + with open(os.path.join(self.dir, 'bin'), 'wb') as f: # a compiled program: a NUL in the first 8 KB + f.write(b'\x7fELF\0\0' + b'x' * 9000 + self.T.encode() + b'\n' + self.PAD.encode()) + os.chmod(os.path.join(self.dir, 'bin'), 0o755) + self.passes('cat big.log | grep x', 'grep -c x big.log', 'mysql < big.log', 'tar czf a.tgz big.log', './bin') + # an interpreter whose script is not found here: its data file is not read as a script (corpus case) + self.passes('python3 -I nothere/rt.py --make-hint big.log') + + def test_files_that_carry_arguments_or_config(self): + self.write('k.cfg', self.PAD + f'url = "{U}"\nrequest = PUT\n', 0o644) + self.write('urls.txt', self.PAD + U + '\n', 0o644) + self.refused('curl -q -K k.cfg', 'wget --no-config -i urls.txt --method=PUT', 'xargs -a urls.txt curl -q -X PUT') + # gh_config_now: a config over 2 MB or one it cannot open may hold the alias + self.write('gh/config.yml', 'aliases:\n' + (' #' + 'x' * 90 + '\n') * 22000 + ' wd: workflow disable\n', + 0o644) + self.refused('gh wd 1') + self.passes('gh pr list') + if os.geteuid() != 0: + os.chmod(os.path.join(self.dir, 'gh/config.yml'), 0) + self.refused('gh co 1') + self.passes('gh pr list') + + def test_every_limit_fails_closed(self): + self.passes('echo ' + '$(:) ' * 1000, 'echo ' + '$(' * 9 + 'date' + ')' * 9) # read to the end: no token + for a, b in (('p', 'q'), ('q', 'r'), ('r', 's')): # a chain deeper than MAX_DEPTH, no token anywhere + self.write(f'{a}.sh', f'#!/bin/sh\nbash {b}.sh\n') + self.write('s.sh', '#!/bin/sh\necho hi\n') + self.passes('bash p.sh') # lockout care: deep and harmless passes + self.write('s.sh', '#!/bin/sh\necho hi # notes in n.py\n') # past the limit: only the scripts the deep + self.write('n.py', '#!/usr/bin/env python3\n# the cases are in t.py\n') # file names directly are read, no crawl + self.write('t.py', f'#!/usr/bin/env python3\nCASE = "{self.T}"\n') + self.passes('bash p.sh') + self.write('dis.sh', f'#!/bin/sh\n{self.T}\n') + deep = os.path.join(*[f'd{i}' for i in range(1, 19)]) + self.write(os.path.join(deep, 'deep.sh'), f'#!/bin/sh\n{self.T}\n') + for a, b in (('a', 'b'), ('b', 'c'), ('c', 'e')): # a.sh runs b.sh runs c.sh runs e.sh: deeper than MAX_DEPTH + self.write(f'{a}.sh', f'#!/bin/sh\nbash {b}.sh\n') + self.write('e.sh', f'#!/bin/sh\n{self.T}\n') + files = ' '.join(self.write(f'f{i}.txt', 'x\n', 0o644) and f'f{i}.txt' for i in range(1, 17)) + self.write('urls.txt', U + '\n', 0o644) + self.write('gh/config.yml', 'aliases:\n a1: a2\n a2: a3\n a3: a4\n a4: workflow disable\n', 0o644) + cds = ' && '.join(f'cd d{i}' for i in range(1, 19)) + self.refused(f'{cds} && ./deep.sh', f'{cds} && bash deep.sh', # cwds 16: the folder of every cd is kept + 'bash a.sh', # MAX_DEPTH: e.sh is read for tokens only + f'mytool {files} dis.sh', # args[:16] dropped: every argument + f'cat {files} urls.txt | xargs curl -q -X PUT -d x', # args[:8] dropped: every file + 'gh a1 1', # gh alias at MAX_DEPTH + 'gh api -X DELETE repos/a/b/rulesets/9' + '/x' * 25 + '/..' * 25, # forms() had 20 rounds + 'gh api -X DELETE repos/a/b/rulesets/9/.') + self.passes(f'{cds} && ls') + + def test_text_for_a_tool_the_guard_does_not_know_says_what_to_do(self): + for cmd in (f"projtool commit -m 'Guard: refuse {self.T}' -- x", f"claude -p 'explain {self.T}'"): + with self.subTest(cmd=cmd): + self.assertIn('put it in a file', self.decide(cmd) or '') + + def test_gh_as_is_read_as_gh(self): + self.passes(f"gh-as example-bot -- gh issue comment 1 --body 'fix {P}; {self.T} is refused'", + "gh-as --repo a/b -- gh pr comment 1 --body x") + self.refused(f'gh-as example-bot -- {self.T}', f'gh-as example-bot -- gh api -X PUT {P} {OFF}') + + +LINE = '2026-11-14 12:00:00 INFO [Server] player joined from /10.0.0.1 permissions ok 50% done\n' + + +class LensCorrR3Test(Case): + def passes(self, *cmds): + for cmd in cmds: + with self.subTest(cmd=cmd): + self.assertIsNone(self.decide(cmd), cmd) + + def test_big_log_into_an_ordinary_tool_passes(self): + # stands for /var/log/syslog on the dev VM (638 MB, readable through the adm group) + with mock.patch.object(self.g, 'HARD_FILE', 2_500_000): + self.write('big.log', LINE * 40000, 0o644) # 3.4 MB > patched HARD_FILE, names nothing + self.passes("tail -n 5000 big.log | grep -i oom | awk '{print $1}'", + "cat big.log | awk '/oom/'", + 'tail -n 200 big.log | python3 -c "import sys"', + 'cp big.log /tmp/s && python3 a.py /tmp/s', + 'mv big.log archive/ ; java -jar tool.jar', + 'python3 load.py < big.log') # load.py is the script; the log is its stdin data + + def test_mid_size_log_with_a_url_path_passes(self): + # 2-64 MB: the piece scan also takes LOOSE_RE hits, so an ordinary `/disable` URL in a web log counts + self.write('web.log', LINE * 36000 + 'GET /api/v1/feature/disable 200\n', 0o644) + self.write('web-small.log', LINE * 20000 + 'GET /api/v1/feature/disable 200\n', 0o644) + self.passes("cat web-small.log | awk '{print $7}' | sort | uniq -c", # under 2 MB: passes today + "cat web.log | awk '{print $7}' | sort | uniq -c") # 3 MB: refused at 118a3a1 + + @unittest.skipIf(os.geteuid() == 0, 'root opens a 0o000 file') + def test_unreadable_data_file_passes(self): + self.write('secret.db', 'x\n', 0o000) + self.passes('sudo cat secret.db | python3 -c "import sys"', + "sudo cat secret.db | awk '{print}'", + 'sudo cp secret.db copy.db && ./gradlew test') + + +class LensCorrR3TimeTest(Case): + def test_plain_copy_of_a_60_mb_log_passes_through_the_hook(self): + # data_gate scans every cp/mv/ln source with file_token(): ~0.12 s per MB, so a plain copy of a 60 MB text + # log runs into the 7 s budget and main() denies it ("could not finish reading ... within 7 s") + import json, subprocess + with open(os.path.join(self.dir, 'huge.log'), 'w') as f: + for _ in range(60): + f.write(LINE * 12000) + for cmd in ('cp huge.log old.log', 'mv huge.log logs/old.log'): + with self.subTest(cmd=cmd): + ev = json.dumps({'tool_name': 'Bash', 'cwd': self.dir, 'tool_input': {'command': cmd}}) + out = subprocess.run([sys.executable, '-I', '-B', HOOK], input=ev, capture_output=True, text=True, + env={'HOME': self.dir, 'GH_CONFIG_DIR': os.path.join(self.dir, 'gh'), + 'PATH': '/usr/bin:/bin'}, timeout=60).stdout + self.assertNotIn('"deny"', out, out[:300]) + + +class LensCorrR3DepthTest(Case): + def test_deep_helper_called_many_times_is_read_once(self): + # file_reason's MAX_DEPTH branch returns before the memo: a depth-2 helper called N times re-scans every file + # it names N times (100 calls x 30 files of 100 KB = 6.8 s through main(), next to the 7 s budget) + for i in range(5): + self.write(f'lib/m{i}.py', '#!/usr/bin/env python3\nx = 1\n') + self.write('helper.sh', '#!/bin/sh\n' + ''.join(f'python3 lib/m{i}.py\n' for i in range(5))) + self.write('mid.sh', '#!/bin/sh\n' + 'bash helper.sh\n' * 20) + self.write('top.sh', '#!/bin/sh\nbash mid.sh\n') + real, seen = self.g.file_token, [] + with mock.patch.object(self.g, 'file_token', lambda p: seen.append(p) or real(p)): + self.assertIsNone(self.decide('bash top.sh')) + self.assertLessEqual(seen.count(os.path.join(self.dir, 'lib/m0.py')), 1, 'helper.sh re-read for each call') + + @unittest.skipIf(os.geteuid() == 0, 'root opens /etc/sudoers') + def test_deep_script_naming_a_root_only_file_passes(self): + # script_like() is True on OSError and file_token() gives NO_OPEN: any root-only file a deep script names + if os.access('/etc/sudoers', os.R_OK) or not os.path.isfile('/etc/sudoers'): + self.skipTest('needs an unreadable /etc/sudoers') + self.write('a.sh', '#!/bin/sh\nbash b.sh\n') + self.write('b.sh', '#!/bin/sh\nbash c.sh\n') + self.write('c.sh', '#!/bin/sh\nsudo visudo -c -f /etc/sudoers\n') + self.assertIsNone(self.decide('bash a.sh')) + + +# ---------- #1752: the hook answers well inside its 10 s limit under load + +# Commands the fast exit lets through before any file is read (the most common Bash calls of agents). +QUICK_PASS = [ + 'ls', 'ls -la', 'pwd', 'git status', 'git status --short', 'git --no-pager log --oneline -5', + 'git -C sub diff --stat', 'git log -p -- a.txt', 'git diff origin/main...HEAD -- scripts', + "grep -rn 'foo bar' src", 'grep -c x a.txt b.txt', 'cat a.txt | head -5', 'cd sub && ls', 'sleep 1; echo done', + "find . -name '*.py' -newer x", "sed -n '1,20p' f.txt", 'wc -l a b > out.txt 2>&1', 'ls 2>/dev/null', + 'rg -n TODO scripts', 'if test -f x; then cat x; fi', 'while true; do sleep 1; done', "jq '.a | {b}' f.json", + "echo 'a;b|c&d' && pwd", 'echo "it\'s ok"', 'head -n 5 a.txt; tail -n 5 a.txt', 'mkdir -p out && cp a.txt out/', + 'ls -la | sort | uniq -c', 'ps aux | grep java', 'du -sh .', 'date -u', 'stat a.txt', 'diff a.txt b.txt', + 'rm -f out.txt', 'mv a.txt b.txt', 'touch x', 'git add a.txt && git commit -m "fix: words"', 'tree -L 2', + 'echo ok\nls', 'cat a.txt > b.txt', 'cp a.txt b.txt', +] +# Spellings that must never take the fast exit: quoting, escapes, variables, prefixes, subshells, functions, code +# that runs code, files under hook folders, and every word that may name a guarded call. +TRICKY = [ + '"g"h workflow disable 1', "g''h workflow disable 1", 'gh api -X PUT repos/a/b/actions/workflows/1/disable', + "gh api -X PUT 'repos/a/b/actions/workflows/1/dis''able'", 'echo work""flow dis\'\'able', + 'X=1 ls', 'GH_TOKEN=x ls', 'env ls', 'sudo ls', 'timeout 60 ls', 'nice ls', 'command ls', 'exec ls', 'builtin ls', + '(cd x && ./run.sh)', '(ls)', '{ ls; }', 'ls; bash x.sh', 'ls && ./x.sh', 'ls || sh x.sh', 'ls & ./x', 'ls | sh', + 'cat x | bash', 'cat x |& sh', 'ls $(./x)', 'ls `./x`', 'ls "$(./x)"', 'ls $X', 'ls ${X}', '\\ls', 'l\\s', + "l''s", '"ls"', 'ls\n./x.sh', 'ls\n\n bash x', 'ls # x\n./x.sh', "ls # it's\n./x.sh\n# '", 'ls #x', + 'ls() { ./x.sh; }; ls', 'function ls { ./x.sh; }; ls', 'alias ls=./x.sh; ls', 'ls {,./x}', 'b{a,}sh x.sh', + 'find . -exec ./x.sh {} +', 'find . -execdir sh -c x ;', 'find . -ok ./x ;', + 'cp /usr/bin/g? ./ls; ls wd', 'cp /usr/bin/gh ./x', 'ln -s /usr/bin/g* g', 'mv /usr/bin/[g]h x', + 'git wd', 'git -c alias.x=!./x.sh x', 'git -c core.pager=./x.sh log', 'git log --exec=x', 'git grep -O./x foo', + 'git --exec-path=. status', 'git config core.pager ./x', 'git rebase --exec ./x main', 'git difftool', + 'git --git-dir=x status', "sed '1e ./x.sh' f", "sed -n 's/a/b/e' f", 'sed -f script.sed f', 'sed --file=s f', + 'sed -nf s f', 'sort --compress-program=./x f', 'rg --pre ./x foo', 'rg --pre=./x foo', + 'echo é', 'echo  x', 'echo %64isable', "cat <&1 | ./x', 'cat <(./x)', 'ls >(./x)', + 'cat x > .git/hooks/pre-commit', 'cp n.txt .git/hooks/post-checkout', 'cp n.txt .husky/pre-commit', + 'cp n.txt .git/config', "cp n.txt '.g''it/config'", + 'curl -q https://api.github.com', 'wget x', 'http GET x', 'xh x', 'httpie x', 'ls; python3 x.py', + 'ls; node x.js', 'ls; perl x', 'ls; ./projtool state', 'projtool state', 't3-capacity 2048', 'make', 'ls\r; ./x', + 'ls\x0b./x', '! ./x', 'time ./x', 'if ./x.sh; then ls; fi', 'while ./x; do ls; done', 'for f in a; do ./x; done', + 'case x in x) ./x;; esac', 'printf -v GIT_PAGER ./x; git log', 'read -r X; git log', 'export PAGER=./x; git log', + 'declare -x PAGER=./x', 'cd ' + ' && cd '.join('abcdefghij') + ' && cat f > out', 'ls ' + 'a' * 5000, + 'echo examplegarden', 'python3 scripts/dev/example_garden.py --fix', 'echo protection', 'echo rulesets', + 'echo graphql mutation', 'echo permissions', 'echo github', 'ls >x.sh; bash x.sh', 'ls\x00; ./x', + "find . -exec ./x.sh ';'", "find . -ex\\ec ./x.sh ';'", "sort --c\\ompress-program=./x f", 'rg --hostname-bin=./x a', + "'do' ls", '"then" ls', 'cp n.txt hooks/pre-commit', 'cp n.txt .githooks/pre-commit', + 'echo bash run.sh > ~/.local/bin/ls; chmod +x ~/.local/bin/ls; ls', + 'cat ~/.local/bin/date; chmod +x ~/.local/bin/date; date', + 'tee ~/.local/bin/date .local/bin/ls; ls', + 'cp run.sh ~/.local/bin/ls && ls', 'git diff --output=bin/ls; ls', 'mv x bin/cat; cat a', + "sed '1eid' a.txt", "sed '1ebash run.sh' a.txt", "sed -n '/x/e id' a", "sed 's/a/b/w out' a", + "sed -e 1d -e '2e id' a", "sed 's|a|b|e' a", "sed '1!e id' a", "sed -n '$e id' a", + 'git grep --open=bash run.sh hello', 'git grep --open-files=bash run.sh x', 'git grep -nObash x', + 'git fetch --upl=./x', 'git log --ex=./x', "git commit -m '!bash run.sh'", 'sed -f p a.txt', + "sed -n -e p -e '1eid' p", # the file name p reads as a script too: only the -e scripts are scripts + 'tee ~/.local/bin/l? < p.txt; ls', 'tee ~/.local/bin/l? /dev/null; ls -la', + 'echo bash run.sh > ~/.local/bin/l?; ls', 'cat run.sh | tee ~/.local/bin/[l]s; ls', 'tee bin/*s |ls; chmod -R +x .; ls', 'echo x >|ls; ls', 'echo x >| ls; ls', + 'echo x 1>|ls; ls -la', 'echo x &>|ls; ls', +] +# Spellings the full reading refuses with the files of FastExitTest.test_refused_spellings_stay_refused +QUICK_REFUSED = [ + 'cp evil.sh hooks/pre-commit', 'cat evil.sh > .githooks/pre-commit', "find . -exec python3 evil.py ';'", + "find . -ex\\ec python3 evil.py ';'", "find . -e'x'ec python3 evil.py ';'", +] + + +class FastExitTest(Case): + """#1752 fix point 1: plain commands pass before any file is read or the clock matters, and nothing the full + reading refuses takes that way out.""" + + def setUp(self): + super().setUp() + self.env = {'HOME': self.dir} + for name, text in FILES.items(): + self.write(name, text, 0o755 if name.endswith('.sh') else 0o644) + + def test_plain_commands_pass_without_reading_anything(self): + def boom(*_a, **_k): + raise AssertionError('the fast exit read a file') + for cmd in QUICK_PASS: + with self.subTest(cmd=cmd): + self.assertTrue(self.g.quick_pass(cmd), cmd) + with mock.patch.object(self.g, 'read_text', boom), mock.patch.object(self.g, 'gh_config_now', boom), \ + mock.patch.object(self.g, 'decide_text', boom): + self.assertIsNone(self.decide(cmd), cmd) + + def test_refused_spellings_stay_refused(self): + self.write('evil.sh', 'gh workflow disable 1\n', 0o755) + self.write('evil.py', 'x = "actions/permissions"\n', 0o644) + for cmd in QUICK_REFUSED: + with self.subTest(cmd=cmd): + self.assertFalse(self.g.quick_pass(cmd), cmd) + self.assertIsNotNone(self.decide(cmd), cmd) + + def test_a_late_start_still_passes_plain_commands_at_once(self): + # the clock is looked at after the fast exit: a hook that starts late answers a plain command with a pass + import contextlib, io + self.write('evil.py', 'x = "actions/permissions"\n', 0o644) + for cmd, refused in (('ls -la', False), ('git status', False), ('python3 evil.py', True), + ('python3 ok.py', True)): + with self.subTest(cmd=cmd): + out = io.StringIO() + ev = json.dumps({'tool_name': 'Bash', 'cwd': self.dir, 'tool_input': {'command': cmd}}) + with mock.patch.object(self.g, 'process_age', lambda: self.g.BUDGET + 1.0), \ + mock.patch.object(sys, 'stdin', io.StringIO(ev)), \ + mock.patch.dict(os.environ, {'HOME': self.dir}), contextlib.redirect_stdout(out): + self.assertEqual(self.g.main(), 0) + if refused: + self.assertIn('could not finish', json.loads(out.getvalue())['hookSpecificOutput'][ + 'permissionDecisionReason']) + else: + self.assertEqual(out.getvalue(), '') + + def test_a_write_named_like_a_command_word_of_the_same_text_is_read(self): + # lens round 1: the text writes ~/.local/bin/ls, then runs ls (found there first on PATH) + self.write('run.sh', 'gh workflow dis' + 'able 1\n', 0o755) + self.write('p.txt', 'bash run.sh\n', 0o644) + os.makedirs(os.path.join(self.dir, '.local', 'bin')) + env = dict(self.env, PATH=os.path.join(self.dir, '.local', 'bin') + ':/usr/bin:/bin') + for cmd in ('echo bash run.sh > ~/.local/bin/ls; chmod +x ~/.local/bin/ls; ls', + 'cat ~/.local/bin/date; chmod +x ~/.local/bin/date; date', + 'tee ~/.local/bin/date ~/.local/bin/l?; ls', + 'cat run.sh | tee ~/.local/bin/[l]s; ls'): + with self.subTest(cmd=cmd): + self.assertFalse(self.g.quick_pass(cmd), cmd) + self.assertIsNotNone(self.g.decide(cmd, self.dir, env), cmd) + # Fable audit after round 2: >| (write even with noclobber) is a redirection, not a pipe. The hook's own + # HOME is the user's, as in the hook (~ in a script word is expanded with it) + for cmd in ('cd ~/.local/bin; echo bash ~/run.sh >|ls; chmod -R +x .; ls', + 'cd ~/.local/bin; echo bash ~/run.sh >| ls; ls -la'): + with self.subTest(cmd=cmd), mock.patch.dict(os.environ, {'HOME': self.dir}): + self.assertFalse(self.g.quick_pass(cmd), cmd) + self.assertIsNotNone(self.g.decide(cmd, self.dir, env), cmd) + # globs that cannot name a command word of the text, and real pipes, stay fast + for cmd in ('ls *.txt', 'cat a?.txt', "grep -n '[0-9]' a.txt", 'wc -l *.py', 'ls | wc -l', 'ls 2>&1 | head', + 'ls |& wc'): + with self.subTest(cmd=cmd): + self.assertTrue(self.g.quick_pass(cmd), cmd) + + def test_git_flags_that_run_a_command_are_seen_in_every_form(self): + # lens round 1: git takes a long flag cut short (--open=less) and -O inside a cluster of short flags + tok = "'actions/per" + "missions'" + for cmd in (f'git grep --open=less {tok}', f'git grep --open-files=less {tok}', f'git grep -nOless {tok}', + f'git grep -O less {tok}', f'git grep -1Oless {tok}', f'git grep -5nOless {tok}'): + with self.subTest(cmd=cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + for cmd in (f'git commit -m {tok}', f'git grep -n {tok}', f'git log --oneline --grep={tok}'): + with self.subTest(cmd=cmd): + self.assertIsNone(self.decide(cmd), cmd) + + def test_random_commands_that_are_fast_pass_the_full_reading(self): + # lens round 1: a fixed list cannot show "fast means the full reading passes"; random commands built from + # every fast word, file names of the attack tests, names of command words under PATH folders, separators + # and redirections + import random + rnd = random.Random(1752) + self.write('run.sh', 'gh workflow dis' + 'able 1\n', 0o755) + bin_ = os.path.join(self.dir, '.local', 'bin') + os.makedirs(bin_) + env = dict(self.env, PATH=bin_ + ':/usr/bin:/bin') + heads = sorted(self.g.QUICK_WORDS) + ['git ' + s for s in sorted(self.g.QUICK_GIT)] + words = list(FILES) + ['run.sh', '-la', '-n', '-r', '-i', "'a b'", '"x"', '~/.local/bin/ls', '.local/bin/date', + 'bin/cat', 'out.txt', '-o', 'x.sh', '--output=bin/ls', "'1,5p'", "'1eid'", "'s/a/b/'", + "'s/a/b/e'", '-e', '--open=ls', '-O', '.', 'sub', '-exec', 'bash', "';'", '+x', + '~/.local/bin/l?', '.local/bin/[d]ate', 'bin/c*', '*.txt', '-1O'] + ops = [' ; ', ' && ', ' || ', ' | ', '\n', ' & '] + redirs = ['', '', '', ' > {}', ' >> {}', ' 2>&1', ' < {}', ' &> {}', ' >{}'] + fast = [] + for _ in range(3000): + parts = [] + for _ in range(rnd.randint(1, 3)): + p = rnd.choice(heads) + ''.join(' ' + rnd.choice(words) for _ in range(rnd.randint(0, 3))) + parts.append(p + rnd.choice(redirs).format(rnd.choice(words))) + cmd = parts[0] + ''.join(rnd.choice(ops) + p for p in parts[1:]) + if self.g.quick_pass(cmd): + fast.append(cmd) + self.assertGreater(len(fast), 300) + with mock.patch.object(self.g, 'QUICK', False): + for cmd in fast: + with self.subTest(cmd=cmd): + self.assertIsNone(self.g.decide(cmd, self.dir, env), cmd) + + def test_a_long_sed_script_is_answered_at_once(self): + # lens round 2: two \\s* side by side made the sed check try every split of the blanks (5 s, then a refusal) + import time + for script, fast in (("'" + ' p;' * 16 + " y/ab/cd/'", False), ("'" + ' s/a/b/;' * 22 + " s/c/d/m'", False), + ("'" + ' p;' * 200 + "'", True), ("'" + ' 1,2 s/a/b/g ;' * 200 + "'", True)): + with self.subTest(script=script[:20]): + t = time.monotonic() + self.assertEqual(self.g.quick_pass('sed -n ' + script + ' a.txt'), fast) + self.assertLess(time.monotonic() - t, 2.0) # timing: in-process, 1.5 ms at most: 1000x margin + # Fable audit: a run of * in a glob word, matched against the command words + for cmd, fast in (('sha256sum a.txt ' + '*' * 40 + 'x', True), ('cat ' + '*?' * 30 + 'q; cat', True), + ('cat ' + '*' * 40 + 't; cat', False)): + with self.subTest(cmd=cmd[:20]): + t = time.monotonic() + self.assertEqual(self.g.quick_pass(cmd), fast) + self.assertLess(time.monotonic() - t, 2.0) # timing: in-process, 1.5 ms at most: 1000x margin + + def test_tricky_spellings_are_never_fast(self): + for cmd in TRICKY: + with self.subTest(cmd=cmd): + self.assertFalse(self.g.quick_pass(cmd), cmd) + for bad in (None, 5, b'ls', ['ls']): + self.assertFalse(self.g.quick_pass(bad)) + + def test_no_refused_case_is_fast(self): + refused = DENY + [c for cmds in ATTACKS.values() for c in cmds] + [c for c, _ in OVER_REFUSED] + for cmd in refused: + with self.subTest(cmd=cmd): + self.assertFalse(self.g.quick_pass(cmd), cmd) + + def test_what_is_fast_the_full_reading_passes_too(self): + # whatever the files hold: every fast command, over the files of the attack tests, read in full + corpus = QUICK_PASS + TRICKY + DENY + ALLOW + ALLOW_MORE + [c for cmds in ATTACKS.values() for c in cmds] + corpus += [f'{w} {f}' for w in sorted(self.g.QUICK_WORDS) for f in FILES] + corpus += [f'git {s} {f}' for s in sorted(self.g.GIT_SAFE) for f in FILES] + corpus += [c.format(f) for f in FILES for c in ('cat {} > run.sh', 'cp {} run.sh', 'cat {} | sort', + 'tee x.sh < {}', 'ln -s {} y', 'cd sub && cat {} > z')] + fast = [c for c in corpus if self.g.quick_pass(c)] + self.assertGreater(len(fast), 500) + with mock.patch.object(self.g, 'QUICK', False): + for cmd in fast: + with self.subTest(cmd=cmd): + self.assertIsNone(self.decide(cmd), cmd) + + def test_fast_words_are_words_the_full_reading_trusts(self): + self.assertLessEqual(self.g.QUICK_WORDS, self.g.DATA) + self.assertFalse(self.g.QUICK_WORDS & (self.g.SETTERS | self.g.TAINTERS | self.g.WRAPPERS | {'alias', 'hash'})) + self.assertLessEqual(self.g.QUICK_GIT, self.g.GIT_SAFE) + + +RACY = 0.05 + + +def settle(): + """Wait until the files written so far are old enough to cache.""" + import time + time.sleep(RACY + 0.03) + + +class CacheCase(Case): + """A scratch HOME with a code file that names a guarded token (evil.py) and one that does not (ok.py), both old + enough to cache.""" + + def setUp(self): + super().setUp() + self.env = {'HOME': self.dir} + self.ok = self.write('ok.py', 'x = "' + 'a' * 30 + '"\n', 0o644) + self.evil = self.write('evil.py', 'x = "actions/permissions/' + 'a' * 10 + '"\n', 0o644) + self.assertEqual(os.path.getsize(self.ok), os.path.getsize(self.evil)) + # A file is cached only when it was last changed CACHE_RACY seconds ago (a change in the same clock tick as + # the read would not show in the times). Tests use a short wait instead of the hook's 2 s. + p = mock.patch.object(self.g, 'CACHE_RACY', RACY) + p.start() + self.addCleanup(p.stop) + settle() + + def cache_path(self): + return os.path.join(self.dir, '.local', 'state', 'actions-disable-guard', 'cache-v1.json') + + def reads(self, cmd): + """(the verdict, the files the guard read for it).""" + real, seen = self.g.read_text, [] + with mock.patch.object(self.g, 'read_text', lambda p: seen.append(p) or real(p)): + return self.decide(cmd), seen + + def cache(self): + with open(self.cache_path()) as f: + return json.load(f) + + def put(self, data, mode=0o600): + with open(self.cache_path(), 'w') as f: + f.write(data if isinstance(data, str) else json.dumps(data)) + os.chmod(self.cache_path(), mode) + + +class CacheTest(CacheCase): + """#1752 fix point 2 and the state question: the hook runs again (a cache hit), a script changed after it was + cached, an old, empty, broken, future-dated or other-user cache, a write that stops half-way, two hooks at once.""" + + def test_second_run_reads_nothing_and_answers_the_same(self): + for path, verdict in ((self.ok, None), (self.evil, 'names `.../actions/permissions`')): + first, seen = self.reads(f'python3 {os.path.basename(path)}') + self.assertIn(path, seen) + again, seen = self.reads(f'python3 {os.path.basename(path)}') + self.assertNotIn(path, seen) + self.assertEqual(first, again) + if verdict is None: + self.assertIsNone(first) + else: + self.assertIn(verdict, first) + st = os.stat(self.cache_path()) + self.assertEqual(st.st_mode & 0o777, 0o600) + self.assertEqual(os.stat(os.path.dirname(self.cache_path())).st_mode & 0o777, 0o700) + + def test_a_script_changed_after_it_was_cached_is_read_again(self): + self.assertIsNone(self.decide('python3 ok.py')) + st = os.stat(self.ok) + with open(self.evil) as f: + evil = f.read() + with open(self.ok, 'w') as f: # same size, same mtime: only the change time tells + f.write(evil) + os.utime(self.ok, ns=(st.st_atime_ns, st.st_mtime_ns)) + self.assertIsNotNone(self.decide('python3 ok.py')) + self.write('ok2.py', 'x = "' + 'a' * 30 + '"\n', 0o644) + settle() + self.assertIsNone(self.decide('python3 ok2.py')) + os.replace(self.evil, os.path.join(self.dir, 'ok2.py')) # another file under the cached name + self.assertIsNotNone(self.decide('python3 ok2.py')) + + def test_a_file_written_just_now_is_not_cached(self): + self.write('ok.py', 'x = 1\n', 0o644) + os.utime(self.ok, (1, 1)) # an old mtime (cp -p, tar): the change time still says "just now" + cfg = self.write('.config/gh/config.yml', 'aliases:\n co: pr checkout\n', 0o644) + with mock.patch.object(self.g, 'CACHE_RACY', 2.0): + self.assertIsNone(self.decide('python3 ok.py')) + self.decide('gh co 1') + c = self.cache() if os.path.exists(self.cache_path()) else {} + self.assertNotIn(self.ok, c.get('files', {})) + self.assertFalse(any(cfg in k for k in c.get('gh', {})), c.get('gh')) + + def test_an_entry_lives_60_s(self): + self.assertIsNotNone(self.decide('python3 evil.py')) + import time as t + now = t.time() + for later, read in ((30, False), (61, True)): + with mock.patch.object(self.g.time, 'time', lambda: now + later): + _, seen = self.reads('python3 evil.py') + self.assertEqual(self.evil in seen, read, later) + + def forged(self): + """The cache after a real run, with evil.py's entry turned into "names nothing": if the guard trusted it, + evil.py would pass. Every bad cache below carries this entry, so a bad cache that is used lets evil.py by.""" + self.assertIsNotNone(self.decide('python3 evil.py')) + c = self.cache() + self.assertIn(self.evil, c['files']) + c['files'][self.evil]['named'] = None + return c + + def test_bad_cache_files_are_ignored(self): + import copy, time as t + good = self.forged() + def entry(**kw): + c = copy.deepcopy(good) + c['files'][self.evil].update(kw) + return c + half = json.dumps(good) + bad = { + 'empty': '', 'not json': 'not json {', 'half written': half[:len(half) // 2], 'a list': '[]', + 'an old hook version': dict(good, v=0), 'another guard': dict(good, guard=[0, 0, 0, 0, 0]), + 'no guard': {k: v for k, v in good.items() if k != 'guard'}, + 'from the future': entry(t=t.time() + 300), 'stale': entry(t=t.time() - 61), + 'a time that is no number': entry(t='now'), 'a bool time': entry(t=True), + 'a label the guard does not have': entry(named='nothing'), 'text not a bool': entry(text=1), + 'own not a bool': entry(own=1), 'a #! program that is no text': entry(bang=['bash']), + 'another file under the name': entry(sig=[1, 2, 3, 4, 5]), 'files not a map': dict(good, files=[]), + 'deep nesting': '[' * 100000 + ']' * 100000, + } + for name, data in bad.items(): + with self.subTest(name): + self.put(data) + why, seen = self.reads('python3 evil.py') + self.assertIsNotNone(why, name) + self.assertIn(self.evil, seen, name) + + def test_a_cache_file_that_is_not_the_users_own_plain_file_is_ignored(self): + good = json.dumps(self.forged()) + cases = {'group-writable': lambda: self.put(good, 0o664), 'world-writable': lambda: self.put(good, 0o646)} + def link(): + other = os.path.join(self.dir, 'other.json') + with open(other, 'w') as f: + f.write(good) + os.chmod(other, 0o600) + os.unlink(self.cache_path()) + os.symlink(other, self.cache_path()) + def fifo(): + os.unlink(self.cache_path()) + os.mkfifo(self.cache_path(), 0o600) # an open that waits for a writer would hang the hook + def folder(): + os.unlink(self.cache_path()) + os.mkdir(self.cache_path()) + def huge(): + self.put(good[:-1] + ', "pad": "' + 'x' * 1_100_000 + '"}') + cases.update({'a link': link, 'a fifo': fifo, 'a folder': folder, 'over 1 MB': huge}) + def clear(): + if os.path.isdir(self.cache_path()) and not os.path.islink(self.cache_path()): + os.rmdir(self.cache_path()) + elif os.path.lexists(self.cache_path()): + os.unlink(self.cache_path()) + for name, make in cases.items(): + with self.subTest(name): + clear() + self.put(good) + make() + why, seen = self.reads('python3 evil.py') + self.assertIsNotNone(why, name) + self.assertIn(self.evil, seen, name) + clear() + self.put(good) + with mock.patch.object(self.g.os, 'geteuid', lambda: os.getuid() + 1): # another user's cache and folder + why, seen = self.reads('python3 evil.py') + self.assertIsNotNone(why) + self.assertIn(self.evil, seen) + self.assertEqual(json.dumps(self.cache()), good) # and it does not write into another user's folder + + def test_missing_or_empty_state_folder_is_made_again(self): + state = os.path.dirname(os.path.dirname(self.cache_path())) + self.assertFalse(os.path.exists(state)) + self.assertIsNotNone(self.decide('python3 evil.py')) + self.assertIn(self.evil, self.cache()['files']) + import shutil + shutil.rmtree(os.path.dirname(self.cache_path())) + os.makedirs(os.path.dirname(self.cache_path())) + os.chmod(os.path.dirname(self.cache_path()), 0o777) + why, seen = self.reads('python3 evil.py') + self.assertIsNotNone(why) + self.assertIn(self.evil, seen) + self.assertIn(self.evil, self.cache()['files']) + self.assertEqual(os.stat(os.path.dirname(self.cache_path())).st_mode & 0o777, 0o700) + + def test_a_write_that_stops_half_way_leaves_no_bad_cache(self): + self.assertIsNone(self.decide('python3 ok.py')) + before = self.cache() + d = os.path.dirname(self.cache_path()) + for where in ('replace', 'write'): + with self.subTest(where): + target = {'replace': (self.g.os, 'replace'), 'write': (self.g.os, 'write')}[where] + def stop(*_a, **_k): + raise OSError(28, 'no space left on the disk') + with mock.patch.object(*target, stop): + self.assertIsNotNone(self.decide('python3 evil.py')) # the answer does not change + self.assertEqual(self.cache(), before) + self.assertEqual([n for n in os.listdir(d) if n.endswith('.tmp')], []) + # a temp file a killed writer left behind is no cache, and an old one is cleared by the next write + with open(os.path.join(d, '.cache-1-dead.tmp'), 'w') as f: + f.write('{"v": 1, "files": {') + os.utime(os.path.join(d, '.cache-1-dead.tmp'), (1, 1)) + with open(os.path.join(d, '.cache-2-live.tmp'), 'w') as f: + f.write('{"v": 1') + self.assertIsNotNone(self.decide('python3 evil.py')) + self.assertEqual(sorted(n for n in os.listdir(d) if n.endswith('.tmp')), ['.cache-2-live.tmp']) + + def test_a_file_that_changes_while_it_is_read_is_not_cached(self): + # read the harmless text, then the file becomes the evil one: the facts of the old text must not be kept + # under the new file's stat + import time + real, done = self.g.read_text, [] + def swap(p): + text = real(p) + if p == self.ok and not done: + done.append(p) + with open(self.evil) as f, open(self.ok, 'w') as g: + g.write(f.read()) + time.sleep(RACY * 3) # old enough to cache by the time the reading ends + return text + with mock.patch.object(self.g, 'read_text', swap): + self.assertIsNone(self.decide('python3 ok.py')) + settle() + self.assertIsNotNone(self.decide('python3 ok.py')) + + def test_no_cache_without_an_absolute_home(self): + here = os.getcwd() + os.chdir(self.dir) + self.addCleanup(os.chdir, here) + for home in ('rel', '', '.'): + with self.subTest(home=home): + self.assertIsNotNone(self.decide('python3 evil.py', {'HOME': home})) + self.assertFalse(os.path.exists(os.path.join(self.dir, 'rel'))) + self.assertFalse(os.path.exists(os.path.join(self.dir, '.local'))) + + def test_a_held_lock_skips_the_write(self): + import fcntl + d = os.path.dirname(self.cache_path()) + os.makedirs(d) + fd = os.open(os.path.join(d, 'cache.lock'), os.O_RDWR | os.O_CREAT, 0o600) + try: + fcntl.flock(fd, fcntl.LOCK_EX) + self.assertIsNotNone(self.decide('python3 evil.py')) # waits at most 0.5 s, then answers without + self.assertFalse(os.path.exists(self.cache_path())) + finally: + os.close(fd) + self.assertIsNotNone(self.decide('python3 evil.py')) + self.assertIn(self.evil, self.cache()['files']) + + def test_a_save_that_is_cut_off_never_changes_the_answer(self): + def slow(*_a, **_k): + raise self.g.Slow() + with mock.patch.object(self.g, 'cache_save', slow): + self.assertIsNone(self.decide('python3 ok.py')) + self.assertIsNotNone(self.decide('python3 evil.py')) + with mock.patch.object(self.g.os, 'replace', slow): + self.assertIsNone(self.decide('python3 ok.py')) + d = os.path.dirname(self.cache_path()) + self.assertEqual([n for n in os.listdir(d) if n.endswith('.tmp')], []) + self.assertFalse(os.path.exists(self.cache_path())) + + def test_a_reading_cut_off_keeps_nothing(self): + for i in range(3): + self.write(f'ok{i}.py', f'x = {i}\n', 0o644) + settle() + real, done = self.g.read_text, [] + def alarm(p): # the hook's alarm going off in the third read, after two files were read in full + done.append(p) + if len(done) == 3: + raise self.g.Slow() + return real(p) + with mock.patch.object(self.g, 'read_text', alarm): + why = self.g.decide('python3 ok.py; python3 ok0.py; python3 ok1.py; python3 ok2.py', self.dir, self.env) + self.assertIn('could not finish', why) + self.assertFalse(os.path.exists(self.cache_path())) + + def test_the_merge_reads_the_cache_under_the_lock(self): + import fcntl + self.assertIsNone(self.decide('python3 ok.py')) + d, real, held = os.path.dirname(self.cache_path()), self.g.cache_load, [] + def spy(env): + fd = os.open(os.path.join(d, 'cache.lock'), os.O_RDWR | os.O_CREAT, 0o600) + try: + fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB) + held.append(False) + except BlockingIOError: + held.append(True) + finally: + os.close(fd) + return real(env) + with mock.patch.object(self.g, 'cache_load', spy): + self.assertIsNotNone(self.decide('python3 evil.py')) + self.assertEqual(held, [False, True]) # the reading's look, then the merge under the lock + self.assertLessEqual({self.ok, self.evil}, set(self.cache()['files'])) # nothing lost + + def test_a_guard_file_replaced_while_the_hook_runs_neither_saves_nor_loads(self): + # lens round 1: the code in memory is the old guard; its facts must not be kept under the new file's stat, + # and the new guard's cache is not for it + self.assertIsNotNone(self.decide('python3 evil.py')) + with open(self.cache_path()) as f: + before = f.read() + with mock.patch.object(self.g, 'GUARD_AT_START', [0, 0, 0, 0, 0]): + verdict, seen = self.reads('python3 evil.py') + self.assertIsNotNone(verdict) + self.assertIn(self.evil, seen) + self.assertIsNone(self.decide('python3 ok.py')) + with open(self.cache_path()) as f: + self.assertEqual(f.read(), before) + + def test_a_failing_cache_never_changes_the_answer(self): + blocked = os.path.join(self.dir, '.local') + with open(blocked, 'w') as f: # the state folder cannot be made + f.write('a file') + self.assertIsNotNone(self.decide('python3 evil.py')) + self.assertIsNone(self.decide('python3 ok.py')) + os.unlink(blocked) + with mock.patch.object(self.g.json, 'dumps', side_effect=ValueError('x')): + self.assertIsNotNone(self.decide('python3 evil.py')) + + def test_the_gh_config_is_cached_and_read_again_when_it_changes(self): + cfg = self.write('.config/gh/config.yml', 'aliases:\n wd: workflow disable\n', 0o644) + settle() + self.assertIsNotNone(self.decide('gh wd 1')) + _, seen = self.reads('gh wd 1') + self.assertNotIn(cfg, seen) + self.write('.config/gh/config.yml', 'aliases:\n wd: workflow list \n', 0o644) # same size + self.assertIsNone(self.decide('gh wd 1')) + os.unlink(cfg) + self.assertIsNone(self.decide('gh pr list')) + self.write('.config/gh/config.yml', 'aliases:\n wd: workflow disable\n', 0o644) # was missing + self.assertIsNotNone(self.decide('gh wd 1')) + + def test_two_hooks_at_once_keep_one_whole_cache(self): + hook = slow_copy(self, racy=RACY) + names = [self.write(f'm{i}.py', f'x = {i}\n', 0o644) for i in range(6)] + settle() + ev = lambda c: json.dumps({'tool_name': 'Bash', 'cwd': self.dir, 'tool_input': {'command': c}}) + for _ in range(3): + runs = [(c, subprocess.Popen([sys.executable, '-I', hook], stdin=subprocess.PIPE, stdout=subprocess.PIPE, + stderr=subprocess.PIPE, text=True, cwd=self.dir, + env={'PATH': '/usr/bin:/bin', 'HOME': self.dir})) + for i in range(6) for c in (f'python3 m{i}.py', 'python3 evil.py')] + for c, p in runs: + out, err = p.communicate(ev(c), timeout=60) + self.assertEqual('"deny"' in out, c == 'python3 evil.py', (c, out, err)) + c = self.cache() + self.assertEqual(c['v'], 1) + self.assertIn(self.evil, c['files']) + self.assertTrue(set(names) & set(c['files'])) + self.assertEqual([n for n in os.listdir(os.path.dirname(self.cache_path())) if n.endswith('.tmp')], []) + + +def slow_copy(case, read=0.0, gh=0.0, racy=None): + """The real hook, with every whole-file read (read_text) and every gh config read taking `read` / `gh` seconds + more: a loaded machine, a slow disk. Each call adds a line ('read' or 'gh') to slow_calls(case) before it waits: + a test counts work, which load cannot change, instead of timing it (#1523).""" + with open(HOOK, encoding='utf-8') as f: + text = f.read() + calls = os.path.join(case.dir, 'slow-calls.log') + for head, delay, name in (('def read_text(path):\n', read, 'read'), ('def gh_config_now(dirs):\n', gh, 'gh')): + case.assertIn(head, text) + text = text.replace(head, f"{head} with open({calls!r}, 'a') as _f: _f.write({name!r} + '\\n')\n" + f' time.sleep({delay})\n', 1) + if racy is not None: + case.assertIn('\nCACHE_RACY = 2.0\n', text) + text = text.replace('\nCACHE_RACY = 2.0\n', f'\nCACHE_RACY = {racy}\n', 1) + return case.write('slow-hook', text, 0o755) + + +def slow_calls(case): + """The slow calls a slow_copy hook started so far, in order ('read', 'gh').""" + try: + with open(os.path.join(case.dir, 'slow-calls.log'), encoding='utf-8') as f: + return f.read().split() + except FileNotFoundError: + return [] + + +class SlowBackendTest(CacheCase): + """#1752 fix points 3 and 4: with a slow backend the hook still answers well inside its 10 s limit.""" + + def run_hook(self, hook, cmd): + import time + ev = json.dumps({'session_id': 't', 'hook_event_name': 'PreToolUse', 'tool_name': 'Bash', 'cwd': self.dir, + 'tool_input': {'command': cmd, 'description': 'x'}}) + t = time.monotonic() + r = subprocess.run([sys.executable, '-I', hook], input=ev, capture_output=True, text=True, timeout=60, + env={'PATH': '/usr/bin:/bin', 'HOME': self.dir}, cwd=self.dir) + took = time.monotonic() - t + out = json.loads(r.stdout)['hookSpecificOutput'] if r.stdout else None + return out, took + + def test_plain_commands_do_not_wait_for_a_slow_disk(self): + hook = slow_copy(self, read=5.0, gh=5.0) + self.write('a.txt', 'text\n', 0o644) + for cmd in ('ls -la', 'git status', 'cat a.txt > b.txt', 'cp a.txt c.txt', 'grep -rn x . | head'): + with self.subTest(cmd=cmd): + out, _ = self.run_hook(hook, cmd) + self.assertIsNone(out, cmd) + self.assertEqual(slow_calls(self), [], cmd) # no disk or gh read at all: nothing to wait for + + def test_a_slow_disk_ends_in_a_refusal_well_inside_the_limit(self): + hook = slow_copy(self, read=2.0) + for i in range(6): + self.write(f'm{i}.py', f'x = {i}\n', 0o644) + out, _ = self.run_hook(hook, '; '.join(f'python3 m{i}.py' for i in range(6))) # 12 s of reads + self.assertEqual(out['permissionDecision'], 'deny') + self.assertIn('could not finish', out['permissionDecisionReason']) + # The budget is 5 s from the start of the process (the limit is 10 s) and every read takes 2 s or more, so a + # hook that keeps its budget starts at most 3 of the 6 reads; a loaded machine only makes that fewer. + self.assertLessEqual(slow_calls(self).count('read'), 3, slow_calls(self)) + + def test_a_slow_log_never_holds_or_doubles_the_answer(self): + # the refusal is written out before the log line, and the log gets 2 s past the budget at most + import select, time + hook = slow_copy(self) + with open(hook, encoding='utf-8') as f: + text = f.read() + head = " d = state_dir(env) or state_dir({'HOME': os.path.expanduser('~')})\n" + self.assertEqual(text.count(head), 1) + self.write('slow-hook', text.replace(head, ' time.sleep(600)\n' + head), 0o755) # a log that never ends + ev = json.dumps({'tool_name': 'Bash', 'cwd': self.dir, 'tool_input': {'command': 'python3 evil.py'}}) + t = time.monotonic() + p = subprocess.Popen([sys.executable, '-I', hook], stdin=subprocess.PIPE, stdout=subprocess.PIPE, + stderr=subprocess.PIPE, text=True, cwd=self.dir, + env={'PATH': '/usr/bin:/bin', 'HOME': self.dir}) + try: + p.stdin.write(ev) + p.stdin.close() + ready, _, _ = select.select([p.stdout], [], [], 4) + self.assertTrue(ready, 'no answer before the log') + self.assertEqual(json.loads(p.stdout.readline())['hookSpecificOutput']['permissionDecision'], 'deny') + p.wait(timeout=60) # the hook's alarm ends the log 2 s past the budget; waiting for it would take 600 s + self.assertLess(time.monotonic() - t, 60) + self.assertEqual(p.stdout.read(), '') # one answer only + finally: + p.kill() + p.wait() + p.stdout.close() + p.stderr.close() + # a log that fails after the answer adds no second answer (two JSON objects are no answer at all) + import contextlib, io + out = io.StringIO() + with mock.patch.object(self.g, 'log', side_effect=self.g.Slow()), \ + mock.patch.object(self.g, 'process_age', lambda: 0.0), \ + mock.patch.object(sys, 'stdin', io.StringIO(ev)), \ + mock.patch.dict(os.environ, {'HOME': self.dir}), contextlib.redirect_stdout(out): + self.assertEqual(self.g.main(), 0) + self.assertEqual(json.loads(out.getvalue())['hookSpecificOutput']['permissionDecision'], 'deny') + # and a log that comes too late writes nothing + with mock.patch.object(self.g, 'process_age', lambda: self.g.BUDGET + 2.5): + self.g.log('x', 'y', {'HOME': self.dir}) + self.assertFalse(os.path.exists(os.path.join(self.dir, '.local', 'state', 'actions-disable-guard', 'log'))) + + def test_the_second_run_is_fast_with_the_same_answer(self): + # 3 s of slow reads in a 5 s budget: the run that pays for them must still leave them in the cache + slow_read = slow_copy(self, read=3.0, racy=RACY) + os.rename(slow_read, slow_read + '-read') + slow_read += '-read' + slow_gh = slow_copy(self, gh=3.0, racy=RACY) + self.write('.config/gh/config.yml', 'aliases:\n wd: workflow disable\n co: pr checkout\n', 0o644) + settle() + for cmd, verdict, hook in (('python3 ok.py', None, slow_read), ('python3 evil.py', 'deny', slow_read), + ('gh wd 1', 'deny', slow_gh), ('gh co 1', None, slow_gh)): + with self.subTest(cmd=cmd): + if os.path.exists(self.cache_path()): # each command starts with no cache + os.unlink(self.cache_path()) + first, took1 = self.run_hook(hook, cmd) + again, took2 = self.run_hook(hook, cmd) + self.assertEqual(first, again) + self.assertEqual(first and first['permissionDecision'], verdict) + self.assertGreater(took1, 3.0) + self.assertLess(took2, 0.9) + + +if __name__ == '__main__': + unittest.main() diff --git a/fork-kit/agent-guards/tests/agent-slots.test.py b/fork-kit/agent-guards/tests/agent-slots.test.py new file mode 100644 index 0000000000000..9c9c4c3fb15b8 --- /dev/null +++ b/fork-kit/agent-guards/tests/agent-slots.test.py @@ -0,0 +1,111 @@ +"""Tests of fork-kit/agent-guards/bin/agent-slots (UserPromptSubmit: a context line of agent slots and the ready +queue; Stop: block once while slots are free and the ready queue has items), for the sessions listed in sessionsFile +only. The process count comes from a stand-in `pgrep` on PATH. Read only: it writes nothing. + + python3 -I -B fork-kit/agent-guards/tests/agent-slots.test.py +""" +import json, os, shutil, sys, tempfile, unittest + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +import guards_fixture as fx # noqa: E402 + +HOOK = 'agent-slots' +QUEUE = '# Queue\n\n## Ready\n- first item\n- second item\n\n## Later\n- not ready\n' + + +class Slots(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.mkdtemp(prefix='agent-slots-test-') + self.addCleanup(shutil.rmtree, self.tmp, True) + self.bin = os.path.join(self.tmp, 'bin') + os.makedirs(self.bin) + self.pgrep(3) + self.sessions = os.path.join(self.tmp, 'sessions.txt') + with open(self.sessions, 'w') as f: + f.write('# orchestrators\norch-1\n') + self.queue = os.path.join(self.tmp, 'QUEUE.md') + with open(self.queue, 'w') as f: + f.write(QUEUE) + self.configure() + self.env = dict(os.environ, HOME=self.tmp, PATH=self.bin + os.pathsep + os.environ.get('PATH', '')) + + def pgrep(self, n, args_file=None): + path = os.path.join(self.bin, 'pgrep') + with open(path, 'w') as f: + f.write('#!/bin/sh\n' + (f'echo "$@" > {args_file}\n' if args_file else '') + f'echo {n}\n') + os.chmod(path, 0o755) + + def configure(self, **keys): + section = dict({'sessionsFile': self.sessions, 'queue': self.queue, 'note': 'at most 4 build agents'}, + **keys) + self.machine = fx.machine_file(self.tmp, {'agentSlots': section}) + + def run_hook(self, event, sid='orch-1', **extra): + return fx.run_hook(HOOK, dict({'hook_event_name': event, 'session_id': sid}, **extra), self.machine, + env=self.env) + + def assert_passed(self, r): + self.assertEqual((r.returncode, r.stdout), (0, ''), r.stderr) + + def test_a_prompt_gets_the_context_line(self): + args = os.path.join(self.tmp, 'pgrep-args') + self.pgrep(3, args) + r = self.run_hook('UserPromptSubmit', prompt='go') + self.assertEqual((r.returncode, fx.answer(r)), (0, 'context'), r.stderr) + line = json.loads(r.stdout)['hookSpecificOutput']['additionalContext'] + self.assertEqual(line, f'Agent slots: 3/10 claude processes alive, 7 free (at most 4 build agents). ' + f'Ready queue ({self.queue}): 2 item(s): first item; second item.') + with open(args) as f: + self.assertEqual(f.read().split(), ['-c', '-x', 'claude']) + + def test_a_stop_with_free_slots_and_ready_items_is_blocked_once(self): + r = self.run_hook('Stop') + self.assertEqual(fx.answer(r), 'refused', r.stderr) + self.assertIn('Fill the free slots from the ready queue', json.loads(r.stdout)['reason']) + self.assert_passed(self.run_hook('Stop', stop_hook_active=True)) + + def test_a_stop_passes_when_full_or_nothing_ready(self): + self.pgrep(10) + self.assert_passed(self.run_hook('Stop')) + self.pgrep(12) + r = self.run_hook('UserPromptSubmit') + self.assertIn('12/10 claude processes alive, 0 free', r.stdout) + self.pgrep(0) + for text in ('# Queue\n## Ready\n\n## Later\n- x\n', ''): + with self.subTest(text=text): + with open(self.queue, 'w') as f: + f.write(text) + self.assert_passed(self.run_hook('Stop')) + os.unlink(self.queue) + self.assert_passed(self.run_hook('Stop')) # a queue that is not there: nothing ready + + def test_only_listed_sessions(self): + self.assert_passed(self.run_hook('Stop', sid='other')) + self.assert_passed(self.run_hook('UserPromptSubmit', sid='# orchestrators')) + os.unlink(self.sessions) + self.assert_passed(self.run_hook('Stop')) + self.machine = fx.NO_MACHINE # the default: no sessions file, nothing + self.assert_passed(self.run_hook('UserPromptSubmit')) + + def test_settings_from_the_machine_file(self): + with open(self.queue, 'w') as f: + f.write('## Next up\n- only one\n## Ready\n- not this\n') + self.configure(readyHeading='## next UP', maxAlive=4, processName='codex', note='') + r = self.run_hook('UserPromptSubmit') + line = json.loads(r.stdout)['hookSpecificOutput']['additionalContext'] + self.assertTrue(line.startswith('Agent slots: 3/4 codex processes alive, 1 free. Ready queue'), line) + self.assertIn('1 item(s): only one.', line) + + def test_a_missing_pgrep_or_odd_input_never_breaks_a_call(self): + os.unlink(os.path.join(self.bin, 'pgrep')) + self.env['PATH'] = self.bin + self.assert_passed(self.run_hook('Stop')) + self.pgrep('not-a-number') + self.assert_passed(self.run_hook('Stop')) + for text in ('', 'not json', '[]'): + with self.subTest(text): + self.assert_passed(fx.run_hook(HOOK, text, self.machine, env=self.env)) + + +if __name__ == '__main__': + unittest.main() diff --git a/fork-kit/agent-guards/tests/bg-guard.test.py b/fork-kit/agent-guards/tests/bg-guard.test.py new file mode 100644 index 0000000000000..cfb8982d6b072 --- /dev/null +++ b/fork-kit/agent-guards/tests/bg-guard.test.py @@ -0,0 +1,146 @@ +"""Tests of fork-kit/agent-guards/bin/bg-guard (Stop hook: block a stop while a Bash command the agent started in +the background still runs, at most maxBlocks times per session). The hook runs under a stand-in parent named +`claude` (a copy of /bin/sh) that starts a command looking like a Claude Code Bash tool command in the background, +as agent_guards.check does. Each test has its own HOME and state folder. + + python3 -I -B fork-kit/agent-guards/tests/bg-guard.test.py +""" +import json, os, shutil, subprocess, sys, tempfile, threading, unittest + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +import guards_fixture as fx # noqa: E402 + +HOOK = 'bg-guard' +BUSY = "sh -c 'sleep 30; true' shell-snapshots/snapshot-bg-test >/dev/null 2>&1 & B=$!; " + + +class Base(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.mkdtemp(prefix='bg-guard-test-') + self.addCleanup(shutil.rmtree, self.tmp, True) + self.home = os.path.join(self.tmp, 'home') + os.makedirs(self.home) + self.claude = os.path.join(self.tmp, 'claude') + shutil.copy('/bin/sh', self.claude) + self.machine = fx.NO_MACHINE + self.state = os.path.join(self.home, '.local', 'state', 'bg-guard') + + def stop(self, sid='s1', busy=True, parent=True, event=None): + """One Stop hook run; (code, stdout, stderr).""" + ev = json.dumps(event if event is not None else {'hook_event_name': 'Stop', 'session_id': sid}) + argv = [sys.executable, '-I', '-B', '-c', fx.RUNNER, fx.LIB, self.machine, str(os.geteuid()), + os.path.join(fx.BIN, HOOK)] + env = dict(os.environ, HOME=self.home, BG_EVENT=ev, BG_PY=argv[0], BG_RUNNER=argv[4], BG_LIB=argv[5], + BG_MACHINE=argv[6], BG_UID=argv[7], BG_HOOK=argv[8]) + if not parent: + r = subprocess.run(argv, input=ev, capture_output=True, text=True, timeout=60, env=env) + return r + # a simple command in a pipeline: the shell forks and execs it, so the hook's parent is `claude` + script = (BUSY if busy else '') + 'printf "%s" "$BG_EVENT" | "$BG_PY" -I -B -c "$BG_RUNNER" "$BG_LIB" ' \ + '"$BG_MACHINE" "$BG_UID" "$BG_HOOK"; r=$?; ' \ + + ('kill $B 2>/dev/null; ' if busy else '') + 'exit $r' + p = subprocess.Popen([self.claude, '-c', script], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, + env=env, start_new_session=True) + try: + out, err = p.communicate(timeout=60) + finally: + try: + os.killpg(p.pid, 9) + except OSError: + pass + return subprocess.CompletedProcess(p.args, p.returncode, out, err) + + def assert_blocked(self, r): + self.assertEqual(r.returncode, 0, r.stderr) + out = json.loads(r.stdout) + self.assertEqual(out['decision'], 'block') + self.assertIn('still running', out['reason']) + self.assertIn("sleep 30; true", out['reason']) # it names the command + + def assert_passed(self, r): + self.assertEqual((r.returncode, r.stdout), (0, ''), r.stderr) + + +class Stop(Base): + def test_a_background_command_blocks_none_passes(self): + self.assert_blocked(self.stop()) + self.assert_passed(self.stop(busy=False)) + + def test_at_most_max_blocks_per_session(self): + for _ in range(3): + self.assert_blocked(self.stop()) + self.assert_passed(self.stop()) + self.assert_blocked(self.stop(sid='s2')) # each session counts its own + self.machine = fx.machine_file(self.tmp, {'bgGuard': {'maxBlocks': 5}}) + self.assert_blocked(self.stop()) # a higher limit from the machine file + self.machine = fx.machine_file(self.tmp, {'bgGuard': {'maxBlocks': 1}}) + self.assert_passed(self.stop(sid='s2')) + + def test_listed_sessions_are_never_blocked(self): + listed = os.path.join(self.tmp, 'sessions.txt') + with open(listed, 'w') as f: + f.write('# orchestrators\ns-orch\n\n') + self.machine = fx.machine_file(self.tmp, {'bgGuard': {'skipSessionsFiles': [ + listed, os.path.join(self.tmp, 'not-there.txt'), '~/also-not-there.txt']}}) + self.assert_passed(self.stop(sid='s-orch')) + self.assert_blocked(self.stop(sid='s1')) # a missing file skips no one + self.assert_blocked(self.stop(sid='# orchestrators')) + + def test_no_claude_parent_or_no_session_passes(self): + self.assert_passed(self.stop(parent=False)) + self.assert_passed(self.stop(sid='')) + self.assert_passed(self.stop(event={'hook_event_name': 'Stop'})) + + def test_a_state_folder_it_cannot_write_blocks_no_stop(self): + with open(os.path.join(self.tmp, 'a-file'), 'w') as f: + f.write('x') + self.machine = fx.machine_file(self.tmp, {'bgGuard': {'stateDir': os.path.join(self.tmp, 'a-file', 'x')}}) + self.assert_passed(self.stop()) + + def test_an_odd_session_id_stays_in_the_state_folder(self): + self.assert_blocked(self.stop(sid='../../escape')) + self.assertEqual(os.listdir(self.state), ['escape.count']) + + def test_odd_input_passes(self): + for text in ('', 'not json', '[]'): + with self.subTest(text): + r = fx.run_hook(HOOK, text, env=dict(os.environ, HOME=self.home)) + self.assert_passed(r) + + +class Count(Base): + """count_block itself: the lock, and a count file that is garbled.""" + + def setUp(self): + super().setUp() + self.g = fx.load_hook(HOOK) + self.c = {'skipSessionsFiles': [], 'maxBlocks': 3, 'stateDir': self.state} + + def test_two_at_once_count_two(self): + results, start = [], threading.Barrier(12) + + def one(): + start.wait() + results.append(self.g.count_block(self.c, 'same')) + threads = [threading.Thread(target=one) for _ in range(12)] + for t in threads: + t.start() + for t in threads: + t.join(30) + self.assertEqual(sorted(results), [False] * 9 + [True] * 3) + with open(os.path.join(self.state, 'same.count')) as f: + self.assertEqual(f.read(), '3') + + def test_a_garbled_count_starts_again(self): + os.makedirs(self.state) + for text in ('garbled', '', '\0\0'): + with self.subTest(text): + with open(os.path.join(self.state, 'g.count'), 'w') as f: + f.write(text) + self.assertTrue(self.g.count_block(self.c, 'g')) + with open(os.path.join(self.state, 'g.count')) as f: + self.assertEqual(f.read(), '1') + + +if __name__ == '__main__': + unittest.main() diff --git a/fork-kit/agent-guards/tests/capacity-pipe.test.py b/fork-kit/agent-guards/tests/capacity-pipe.test.py new file mode 100644 index 0000000000000..555ec68c1d29e --- /dev/null +++ b/fork-kit/agent-guards/tests/capacity-pipe.test.py @@ -0,0 +1,436 @@ +#!/usr/bin/env python3 +"""Tests of fork-kit/agent-guards/bin/capacity-pipe-guard (the Claude Code PreToolUse hook that refuses a piped +capacity check: `t3-capacity 2048 | tail -1 && ` ran the heavy step on NOT OK, four agents, 2026-11-18). +The guard is loaded with no machine file (the default check, t3-capacity) and, in Configured, with one that names a +second check. Its settings entry (missing hook, failed hook) is tested in wiring.test.py. + + python3 -I -B fork-kit/agent-guards/tests/capacity-pipe.test.py +""" +import io, json, os, shutil, subprocess, sys, tempfile, time, unittest +from unittest import mock + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +import guards_fixture as fx # noqa: E402 + +HOOK = os.path.join(fx.BIN, 'capacity-pipe-guard') +G = fx.load_hook('capacity-pipe-guard') + +REFUSED = [ + 't3-capacity 2048 | tail -1 && heavy ./gradlew build', # as reported + 't3-capacity 2048 | tail -1', + 't3-capacity | cat', # every pipe, also one that decides nothing + 't3-capacity 2048|tail -1', + 't3-capacity 2048 2>&1 | tail -1 && x', + 't3-capacity 2048 |& tail -1', + 't3-capacity 2048 > /tmp/cap.txt | tail -1', + 't3-capacity 2048 | tee /tmp/cap.txt', + 't3-capacity $N | tail -1', + 't3-capacity "$NEED" | tail -1', + 't3-capacity 2048 \\\n | tail -1', + 'set -o pipefail; t3-capacity 2048 | tail -1 && x', # right, but refused: the rule is "never pipe it" + # the command word, however it is written + '/usr/local/bin/t3-capacity 2048 | tail -1', + '~/.local/bin/t3-capacity 2048 | head -1', + '"$BIN"/t3-capacity 1 | tail -1', + '"t3-capacity" 2048 | tail -1', + "'t3-capacity' 2048 | tail -1", + 't3-capaci\\ty 2048 | tail -1 # t3-capacity', + 'X=1 t3-capacity 2048 | tail -1', + 'T3_CAPACITY_USER=x Y="a b" t3-capacity 2048 | tail -1', + 'sudo t3-capacity 2048 | tail -1', + 'sudo -u someone t3-capacity 2048 | tail -1', + 'env A=b t3-capacity 2048 | tail -1', + 'env -i PATH=/usr/bin t3-capacity 2048 | tail -1', + 'timeout 50 t3-capacity 768 | tail -1', # timing: guard input, not a wait + 'timeout -k 5 50s /usr/local/bin/t3-capacity 768 | tail -1', # timing: guard input, not a wait + 'command t3-capacity 1 | tail -1', + 'nice -n 5 t3-capacity 1 | tail', + 'time t3-capacity 1 | tail', + 'sudo env A=b nice t3-capacity 1 | tail', + 'sudo -n t3-capacity 2048 | tail -1 && x', # -n takes no value for sudo (it does for nice) + 'sudo -iu someone t3-capacity 1 | tail', + 'sudo -E -u someone -g staff t3-capacity 1 | tail', + 'nice -n 5 ionice -c 3 t3-capacity 1 | tail', + 'stdbuf -oL t3-capacity 1 | tail', + 'stdbuf -o L t3-capacity 1 | tail', + 'time -p t3-capacity 2048 | tail -1 && x', + 'exec -a cap t3-capacity 1 | tail', + # after && ; newline, in if / while / until / for / case, behind ! + 'cd /x && t3-capacity 2048 | tail -1 && heavy x', + 'true; t3-capacity 2048 | tail -1', + 'echo a\nt3-capacity 2048 | tail -1 && x', + 'echo "a" && t3-capacity 1 | tail -1 || echo no', + 'echo a > f; t3-capacity 1 | tail', + 'cat x # a comment\nt3-capacity 1 | tail', + 'if t3-capacity 2048 | grep -q OK; then x; fi', # "NOT OK" holds "OK" too + 'if true; then t3-capacity 2048 | tail -1; fi', + 'while ! t3-capacity 2048 | tail -1; do sleep 60; done', # timing: guard input, not a wait + 'until t3-capacity 2048 | grep -qx OK; do sleep 60; done', # timing: guard input, not a wait + '! t3-capacity 2048 | grep -q NOT', + 'for n in 1 2; do t3-capacity 2048 | tail -1; done', + 'case x in x) t3-capacity 1 | tail -1 ;; esac', + 'f() { t3-capacity 2048 | tail -1; }; f && x', + 'function f { t3-capacity 2048 | tail -1; }; f && x', + 'function f() { t3-capacity 2048 | tail -1; }; f && x', + 'function f {\n t3-capacity 2048 | tail -1\n}', + # $(..), backticks, <(..) + 'out=$(t3-capacity 2048 | tail -1) && x', + 'echo "$(t3-capacity 2048 | tail -1)"', + 'echo `t3-capacity 2048 | tail -1`', + 'x=$(echo $(t3-capacity 1 | tail -1))', + '[ "$(t3-capacity 2048 | tail -1)" = OK ] && x', + 'diff <(t3-capacity 1 | tail -1) x', + # a group whose last command it is + '(t3-capacity 2048) | tail -1', + '(cd /x && t3-capacity 2048) | tail -1', + '{ t3-capacity 2048; } | tail -1 && x', + '{ t3-capacity 2048\n} | tail -1', + '{ echo a; t3-capacity 2048; } 2>&1 | tail -1', + # shell text handed on, both forms of quoting + "bash -c 't3-capacity 2048 | tail -1 && x'", + 'bash -c "t3-capacity 2048 | tail -1 && x"', + "bash -lc 't3-capacity 2048 | tail -1'", + "sh -c 't3-capacity 2048 | tail -1'", + "/bin/bash -c 't3-capacity 2048 | tail -1'", + 'bash -o pipefail -c "t3-capacity 2048 | tail -1"', + 'bash -c "t3-capacity $N | tail -1"', + 'heavy bash -c "t3-capacity 2048 | tail -1 && ./gradlew"', + "timeout 600 bash -c 't3-capacity 2048 | tail -1 && x'", # timing: guard input, not a wait + 'bash -c "bash -c \\"t3-capacity 1 | tail -1\\""', + "bash -c 'bash -c \"t3-capacity 1 | tail -1\"'", + 'bash -c "echo $(t3-capacity 1 | tail -1)"', + "su - someone -c 't3-capacity 1 | tail -1'", + "eval 't3-capacity 2048 | tail -1'", + 'eval t3-capacity 2048 \\| tail -1', + "ssh host1 't3-capacity 2048 | tail -1'", + "watch -n 60 't3-capacity 2048 | tail -1'", + # a heredoc into a shell is commands + "bash <<'EOF'\nt3-capacity 2048 | tail -1 && x\nEOF", + 'bash < note <<'EOF'\ntext\nEOF\nt3-capacity 1 | tail -1", # behind a heredoc that is only text +] + +ALLOWED = [ + 't3-capacity', + 't3-capacity 2048', + 't3-capacity 2048 && heavy ./gradlew build', + 't3-capacity 2048 && heavy x | tail -20', # the pipe is behind the gate + 't3-capacity 2048 && python3 x.py 2>&1 | grep -E "^(FAIL|OK)" | head', + 't3-capacity; echo $?', + 't3-capacity 2048; echo "rc=$?"', + 't3-capacity 2048 || echo "not ok"', + 't3-capacity 2048 || { echo no; exit 1; }', + 't3-capacity 2048 > /tmp/cap.txt && x', + 't3-capacity 2048 >/dev/null 2>&1 && x', + 't3-capacity 2048 & wait', + 'if t3-capacity 2048; then x; fi', + 'if t3-capacity 2048; then x | tail; fi', + 'if ! t3-capacity 2048; then echo wait | cat; fi', + 'until t3-capacity 2048; do sleep 60; done', # timing: guard input, not a wait + 'X=$(t3-capacity 2048) && x', + 'out=$(t3-capacity 2048); rc=$?; echo "$out" | tail -1; [ $rc = 0 ] && x', + 'echo x | t3-capacity 2048 && y', # into it: the status is its own + "bash -c 't3-capacity 2048 && x'", + 'bash -c "t3-capacity 2048 && x | tail"', + "bash <<'EOF'\nt3-capacity 2048 && x\nEOF", + # a group that gates inside, piped as a whole + '{ t3-capacity 2048 && heavy x; } 2>&1 | tail -30', + '(t3-capacity 2048 && heavy x) | tail -30', + 'if t3-capacity 2048; then heavy x; fi | tail -30', + '{ t3-capacity 2048; echo "rc=$?"; } | tail -2', + # text that only mentions it + 'grep -n t3-capacity AGENTS.md | head', + 'rg "t3-capacity 2048 \\| tail" -l | head', + 'cat /usr/local/bin/t3-capacity | head -20', + 'command -v t3-capacity | head -1', + 'which t3-capacity | cat', + 'type -a t3-capacity | head', + 'man t3-capacity | head', + 'ls | grep t3-capacity', + 'echo t3-capacity | cat', + 'printf "%s\\n" t3-capacity 1 | tail -1', + 'echo "never t3-capacity 2048 | tail -1" | tee note', + "echo 't3-capacity 2048 | tail -1'", + 'git commit -m "t3-capacity 1 | tail is refused"', + "projtool commit -m 'no t3-capacity N | tail' -- x | tail -3", + 'gh pr comment 1 --body "t3-capacity 2048 | tail -1 && cmd hides NOT OK" | cat', + 'bash -c "echo \'t3-capacity 1 | tail\'"', + 'sudo install -m 755 scripts/dev/t3-capacity /usr/local/bin/t3-capacity | cat', + 'sudo -n cat /usr/local/bin/t3-capacity | head', + 'sudo -n diff /usr/local/bin/t3-capacity scripts/dev/t3-capacity | head', + 'sudo -n install -m 755 scripts/dev/t3-capacity /usr/local/bin/ 2>&1 | tail -3', + 'sudo -k ls t3-capacity | head', + 'timeout -s KILL 5 cat t3-capacity | head', # timing: guard input, not a wait + 'nice -n t3-capacity x | tail', # the value of -n, not the command + 'function f { t3-capacity 2048 && x; }; f | tail', + 'time -p grep t3-capacity x | head', + 'python3 -I scripts/dev/run_tests.py scripts/dev/tests/test_t3_capacity.py 2>&1 | tail -5', + '# t3-capacity 2048 | tail -1\nls', + 'ls # t3-capacity 2048 | tail -1', + # another program + 't3-capacity-old 1 | tail', + 'my-t3-capacity 1 | tail', + './t3-capacity.bak 1 | tail', + # a heredoc that is only text (briefs are written this way) + "cat > brief.md <<'EOF'\nnever `t3-capacity 2048 | tail -1 && cmd`\nEOF", + 'cat < x\nt3-capacity 1 | tail\nEOF', + "cat <<'EOF' | tee x\nt3-capacity 1 | tail\nEOF", + 'python3 x.py <`, never `t3-capacity 2048 | tail -1`\nEOF\nls | head", + "cat > a <<'EOF'\nt3-capacity 1 | tail\nEOF\nt3-capacity 2048 && x", +] + +# Read by nobody on purpose (the docstring's "Not covered"); pinned so a change that starts refusing them is seen. +NOT_COVERED = [ + 'C=t3-capacity; $C 2048 | tail -1', + 'sh scripts/dev/t3-capacity 1 | tail -1', + "cat <<'EOF' | bash\nt3-capacity 1 | tail -1\nEOF", + 'echo ${X:-$(t3-capacity 1 | tail -1)}', + 'echo 2048 | xargs t3-capacity | tail -1', + 'sudo --user someone t3-capacity 1 | tail -1', + "cat < /dev/null && echo RAN': False} + for cmd, hidden in cases.items(): + with self.subTest(cmd): + out = subprocess.run(['/bin/sh', '-c', cmd], env=env, capture_output=True, text=True, timeout=60).stdout + self.assertEqual('RAN' in out, hidden, out) + self.assertEqual(bool(G.piped(cmd)), hidden) + + def test_deep_or_long_text_is_read_in_time_and_never_crashes(self): + deep = '$(' * 3000 + 't3-capacity 1 | tail' + ')' * 3000 + self.assertFalse(G.piped(deep), 'past 40 levels it stops reading: allowed, said in the docstring') + self.assertTrue(G.piped('$(' * 30 + 't3-capacity 1 | tail' + ')' * 30)) + start = time.monotonic() + self.assertTrue(G.piped('echo ' + 'word "q $x" \'s\' ; ' * 20000 + 't3-capacity 1 | tail')) + self.assertFalse(G.piped('(' * 50000 + 't3-capacity 1' + ')' * 50000)) + self.assertFalse(G.piped('"' + 't3-capacity | ' * 50000)) + self.assertTrue(G.piped('echo ' + '$(x) `y` "$(z)" <(w) ' * 20000 + '; t3-capacity 1 | tail')) + self.assertLess(time.monotonic() - start, 60) # a quadratic read of these inputs takes far longer + + def test_broken_shell_text_is_read_without_a_crash(self): + for cmd in ('t3-capacity "', "t3-capacity '", 't3-capacity $(', 't3-capacity `', 't3-capacity ${', 't3-capacity \\', + 't3-capacity <<', 't3-capacity <', + "t3-capacity $'", '| t3-capacity', 't3-capacity |', 't3-capacity &>', ';;;((()))&&&|||t3-capacity', + 'case t3-capacity in', 't3-capacity\x00|x', 'bash -c', 'eval', 'ssh t3-capacity', 'sudo -u'): + with self.subTest(cmd): + G.piped(cmd) # any answer; no exception + G.piped(cmd + ' | tail') + + +class Hook(unittest.TestCase): + """The hook as Claude Code runs it: PreToolUse JSON on stdin, exit 2 + stderr refuses.""" + def hook(self, event, raw=None): + return subprocess.run([sys.executable, '-I', HOOK], input=json.dumps(event) if raw is None else raw, + capture_output=True, text=True, timeout=60) + + def bash(self, command): + return self.hook({'hook_event_name': 'PreToolUse', 'tool_name': 'Bash', 'tool_input': {'command': command}}) + + def test_refused_is_exit_2_with_the_reason_on_stderr(self): + r = self.bash('t3-capacity 2048 | tail -1 && heavy ./gradlew build') + self.assertEqual((r.returncode, r.stdout), (2, '')) + self.assertTrue(r.stderr.startswith('Refused by capacity-pipe-guard: '), r.stderr) + for said in ('`t3-capacity N && `', 'LAST command', 'Every pipe out of t3-capacity is refused', + 'nothing needs it'): + self.assertIn(said, r.stderr) + + def test_allowed_is_exit_0_and_silent(self): + for cmd in ('t3-capacity 2048 && heavy ./gradlew build', 'ls -la', 'grep t3-capacity x | head', ''): + with self.subTest(cmd): + r = self.bash(cmd) + self.assertEqual((r.returncode, r.stdout, r.stderr), (0, '', '')) + + def test_a_monitor_command_is_read_like_a_bash_command(self): + """Monitor runs shell text too, and a wait for capacity is what it is used for.""" + loop = 'until t3-capacity 2048 | tail -1; do sleep 60; done' # timing: guard input, not a wait + r = self.hook({'hook_event_name': 'PreToolUse', 'tool_name': 'Monitor', 'tool_input': {'command': loop, 'description': 'x'}}) + self.assertEqual(r.returncode, 2, r.stderr) + self.assertIn('Refused by capacity-pipe-guard', r.stderr) + for tool_input in ({'command': 'until t3-capacity 2048; do sleep 60; done'}, # timing: guard input, not a wait + {'ws': {'url': 'wss://x/t3-capacity | tail'}, 'description': 't3-capacity 1 | tail'}): + with self.subTest(tool_input): + r = self.hook({'tool_name': 'Monitor', 'tool_input': tool_input}) + self.assertEqual((r.returncode, r.stderr), (0, '')) + + def test_only_bash_and_monitor_commands_are_read(self): + for tool, key in (('Write', 'content'), ('Edit', 'new_string'), ('Read', 'command')): + with self.subTest(tool): + r = self.hook({'tool_name': tool, 'tool_input': {key: 't3-capacity 1 | tail -1', 'command': 't3-capacity 1 | tail'}}) + self.assertEqual((r.returncode, r.stderr), (0, '')) + + def test_its_own_failure_lets_the_command_run_and_says_so(self): + """Fail open: exit 1 is "the hook failed, run the command" for Claude Code; exit 2 would refuse.""" + for name, raw in (('no JSON', 'not json t3-capacity 1 | tail'), ('empty', ''), ('a list', '[1]'), + ('tool_input is text', '{"tool_name": "Bash", "tool_input": "t3-capacity 1 | tail"}')): + with self.subTest(name): + r = self.hook(None, raw=raw) + self.assertEqual((r.returncode, r.stdout), (1, '')) + self.assertTrue(r.stderr.startswith('capacity-pipe-guard: failed ('), r.stderr) + self.assertIn('NOT checked and runs', r.stderr) + + def test_odd_but_valid_events_pass(self): + for event in ({'tool_name': 'Bash'}, {'tool_name': 'Bash', 'tool_input': None}, {'tool_name': 'Bash', 'tool_input': {}}, + {'tool_name': 'Bash', 'tool_input': {'command': None}}, {'tool_name': 'Bash', 'tool_input': {'command': 7}}, {}): + with self.subTest(event): + r = self.hook(event) + self.assertEqual((r.returncode, r.stderr), (0, '')) + + def test_a_bug_in_the_reader_fails_open_too(self): + event = json.dumps({'tool_name': 'Bash', 'tool_input': {'command': 't3-capacity 1 | tail'}}) + for boom in (RuntimeError('bug'), RecursionError('deep'), KeyboardInterrupt(), SystemExit(2), MemoryError()): + with self.subTest(type(boom).__name__): + err = io.StringIO() + with mock.patch.object(G, 'read', side_effect=boom), mock.patch.object(sys, 'stdin', io.StringIO(event)), \ + mock.patch.object(sys, 'stderr', err): + self.assertEqual(G.main([]), 1) + self.assertIn('capacity-pipe-guard: failed (' + type(boom).__name__, err.getvalue()) + + def test_a_half_written_copy_never_refuses(self): + """State: the copy stopped half-way. Cut anywhere, it lets the command run (1 when Python cannot read it, 0 + when the cut leaves whole lines: main() is the last line), never 2.""" + tmp = tempfile.mkdtemp(prefix='capacity-pipe-') + self.addCleanup(shutil.rmtree, tmp, True) + with open(HOOK) as f: + whole = f.read() + path = os.path.join(tmp, 'capacity-pipe-guard') + event = json.dumps({'tool_name': 'Bash', 'tool_input': {'command': 't3-capacity 1 | tail -1'}}) + cuts = [len(whole) * k // 12 for k in range(12)] + [whole.index('Rule: EVERY pipe'), len(whole) - 2] + for cut in cuts: + with self.subTest(cut): + with open(path, 'w') as f: + f.write(whole[:cut]) + r = subprocess.run([sys.executable, '-I', path], input=event, capture_output=True, text=True, timeout=60) + self.assertIn(r.returncode, (0, 1), r.stderr) + self.assertEqual(r.returncode, 1, 'the last cut is inside `sys.exit(main())`') + + +class Usage(unittest.TestCase): + def test_an_argument_is_a_usage_error_not_a_refusal(self): + """--install is gone (the kit's settings entries are `agent-guards hooks`); any argument is exit 1, which + lets the command run, never 2.""" + for args in (['--install'], ['--help'], ['x']): + with self.subTest(args): + r = subprocess.run([sys.executable, '-I', HOOK, *args], input='', capture_output=True, text=True, + timeout=60) + self.assertEqual(r.returncode, 1) + self.assertIn('usage: capacity-pipe-guard', r.stderr) + + +class Configured(unittest.TestCase): + """capacityPipe.commands from the machine file: every check named there is guarded, the default one only when + it is named; a broken section keeps the default and says so.""" + + def setUp(self): + self.tmp = tempfile.mkdtemp(prefix='capacity-pipe-config-') + self.addCleanup(shutil.rmtree, self.tmp, True) + + def run_hook(self, cmd, section=None, text=None): + machine = fx.machine_file(self.tmp, section, text) + return fx.run_hook('capacity-pipe-guard', {'tool_name': 'Bash', 'tool_input': {'command': cmd}}, machine) + + def test_a_second_check_is_guarded_too(self): + section = {'capacityPipe': {'commands': ['t3-capacity', 'mem-free']}} + for cmd in ('mem-free 2048 | tail -1 && x', 't3-capacity 1 | tail', 'bash -c "mem-free 1 | tail"'): + with self.subTest(cmd): + r = self.run_hook(cmd, section) + self.assertEqual(r.returncode, 2, r.stderr) + self.assertIn('Refused by capacity-pipe-guard', r.stderr) + r = self.run_hook('mem-free 2048 | tail -1', section) + self.assertIn('`mem-free N && `', r.stderr) # the message names the check that was piped + for cmd in ('mem-free 2048 && x', 'echo "mem-free 1 | tail"', 'git commit -m "no mem-free | tail"'): + with self.subTest(cmd): + self.assertEqual(self.run_hook(cmd, section).returncode, 0) + + def test_a_list_without_the_default_drops_it(self): + section = {'capacityPipe': {'commands': ['mem-free']}} + self.assertEqual(self.run_hook('t3-capacity 1 | tail', section).returncode, 0) + self.assertEqual(self.run_hook('mem-free 1 | tail', section).returncode, 2) + + def test_a_broken_section_keeps_the_default_and_says_so(self): + for name, kw in (('empty list', {'section': {'capacityPipe': {'commands': []}}}), + ('a path, not a name', {'section': {'capacityPipe': {'commands': ['/bin/x | y']}}}), + ('unknown key', {'section': {'capacityPipe': {'command': ['x']}}}), + ('not JSON', {'text': '{"version": 1, "agent-guards": '}), + ('empty file', {'text': ''})): + with self.subTest(name): + r = self.run_hook('t3-capacity 2048 | tail -1', **kw) + self.assertEqual(r.returncode, 2, r.stderr) + self.assertIn('built-in defaults used', r.stderr) + r = self.run_hook('t3-capacity 2048 && x', **kw) + self.assertEqual(r.returncode, 0) + self.assertIn('built-in defaults used', r.stderr) + + def test_no_machine_file_or_no_section_is_the_default_quietly(self): + for kw in ({}, {'section': None}): + r = fx.run_hook('capacity-pipe-guard', {'tool_name': 'Bash', 'tool_input': {'command': 't3-capacity | x'}}) + self.assertEqual((r.returncode, r.stdout), (2, '')) + self.assertNotIn('defaults', r.stderr) + r = self.run_hook('ls', **kw) + self.assertEqual((r.returncode, r.stderr), (0, '')) + + def test_a_machine_file_others_can_write_is_not_used(self): + r = self.run_hook('mem-free 1 | tail', {'capacityPipe': {'commands': ['mem-free']}}) + self.assertEqual(r.returncode, 2) + os.chmod(os.path.join(self.tmp, 'machine.json'), 0o666) + r = fx.run_hook('capacity-pipe-guard', {'tool_name': 'Bash', 'tool_input': {'command': 'mem-free 1 | tail'}}, + os.path.join(self.tmp, 'machine.json')) + self.assertEqual(r.returncode, 0) # the default list: mem-free is not a check + self.assertIn('built-in defaults used', r.stderr) + + +if __name__ == '__main__': + unittest.main() diff --git a/fork-kit/agent-guards/tests/config.test.py b/fork-kit/agent-guards/tests/config.test.py new file mode 100644 index 0000000000000..83c753b58cddd --- /dev/null +++ b/fork-kit/agent-guards/tests/config.test.py @@ -0,0 +1,160 @@ +"""agent_guards.config: the machine file's "agent-guards" section, and what every hook does with a section that is +missing, empty, garbled or not safe: its built-in defaults (never a weaker guard), and one line on stderr. + + python3 -I -B fork-kit/agent-guards/tests/config.test.py +""" +import json, os, shutil, subprocess, sys, tempfile, unittest + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +import guards_fixture as fx # noqa: E402 +from guards_fixture import config # noqa: E402 + +EXAMPLE = os.path.join(os.path.dirname(fx.KIT), 'common', 'machine.example.json') +QUIET_EVENT = {'hook_event_name': 'Stop', 'session_id': 'config-test', 'tool_name': 'Read', 'tool_input': {}} + + +class Load(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.mkdtemp(prefix='agent-guards-config-') + self.addCleanup(shutil.rmtree, self.tmp, True) + self.addCleanup(fx.use_machine, fx.NO_MACHINE) + + def load(self, hook, section=None, text=None, mode=0o644): + fx.use_machine(fx.machine_file(self.tmp, section, text, mode)) + return config.load(hook) + + def test_no_file_or_no_section_is_the_defaults_with_no_problem(self): + fx.use_machine(fx.NO_MACHINE) + for hook in config.HOOKS: + self.assertEqual(config.load(hook), (config.defaults(hook), None)) + self.assertEqual(self.load(hook), (config.defaults(hook), None)) + self.assertEqual(config.defaults('memoryIndex'), {'maxChars': 6000, 'maxLine': 160, + 'stateDir': '~/.cache/memory-index-guard'}) + self.assertEqual(config.defaults('capacityPipe'), {'commands': ['t3-capacity']}) + self.assertEqual(config.defaults('agentSlots')['sessionsFile'], '') # does nothing until configured + + def test_a_section_fills_in_what_it_leaves_out(self): + got, problem = self.load('memoryIndex', {'memoryIndex': {'maxChars': 4000}}) + self.assertIsNone(problem) + self.assertEqual(got, {'maxChars': 4000, 'maxLine': 160, 'stateDir': '~/.cache/memory-index-guard'}) + got, problem = self.load('bgGuard', {'memoryIndex': {'maxChars': 4000}}) + self.assertEqual((got, problem), (config.defaults('bgGuard'), None)) + + def test_the_example_section_loads(self): + with open(EXAMPLE) as f: + section = json.load(f)['agent-guards'] + for hook in config.HOOKS: + got, problem = self.load(hook, section) + self.assertIsNone(problem, hook) + for key, value in section.get(hook, {}).items(): + self.assertEqual(got[key], value) + self.assertEqual(set(section), set(config.HOOKS)) # the example shows every hook's keys + for hook in config.HOOKS: + self.assertEqual(set(section[hook]), set(config.SPEC[hook]), hook) + + def test_a_broken_file_or_section_gives_the_defaults_and_names_the_problem(self): + cases = { + 'empty file': dict(text=''), + 'garbled JSON': dict(text='{"version": 1, "agent-guards": {'), + 'not an object': dict(text='[]'), + 'no version': dict(text='{"agent-guards": {}}'), + 'a newer version': dict(text='{"version": 99, "agent-guards": {}}'), + 'a duplicate key': dict(text='{"version": 1, "agent-guards": {}, "agent-guards": {}}'), + 'section not an object': dict(section=[]), + 'unknown hook': dict(section={'memoryIndx': {}}), + 'unknown key': dict(section={'memoryIndex': {'maxchars': 1}}), + 'wrong type': dict(section={'memoryIndex': {'maxChars': '6000'}}), + 'a bool for a number': dict(section={'memoryIndex': {'maxChars': True}}), + 'zero': dict(section={'memoryIndex': {'maxLine': 0}}), + 'a relative path': dict(section={'memoryIndex': {'stateDir': 'cache/x'}}), + 'others can write it': dict(section={}, mode=0o666), + } + for name, kw in cases.items(): + with self.subTest(name): + got, problem = self.load('memoryIndex', **kw) + self.assertEqual(got, config.defaults('memoryIndex')) + self.assertTrue(problem) + + def test_each_hook_checks_its_own_keys(self): + bad = { + 'actionsDisable': [{'refuseScripts': [{'name': '../x.py', 'flag': '--fix'}]}, + {'refuseScripts': [{'name': 'x.py', 'flag': 'fix'}]}, + {'refuseScripts': [{'name': '.py', 'flag': '--fix'}]}, + {'refuseScripts': [{'name': 'x.py', 'flag': '--fix', 'when': 'always'}]}, + {'refuseScripts': 'x.py'}], + 'capacityPipe': [{'commands': []}, {'commands': ['a b']}, {'commands': ['/bin/x']}, {'commands': 'x'}], + 'bgGuard': [{'skipSessionsFiles': ['rel']}, {'skipSessionsFiles': ['']}, {'maxBlocks': -1}], + 'agentSlots': [{'processName': 'a b'}, {'maxAlive': 0}, {'queue': 'QUEUE.md'}], + } + for hook, sections in bad.items(): + for s in sections: + with self.subTest(hook=hook, section=s): + got, problem = self.load(hook, {hook: s}) + self.assertEqual(got, config.defaults(hook)) + self.assertTrue(problem) + + def test_load_all_names_each_problem_once(self): + fx.use_machine(fx.machine_file(self.tmp, text='{')) + settings, problems = config.load_all() + self.assertEqual(settings, {h: config.defaults(h) for h in config.HOOKS}) + self.assertEqual(len(problems), 1) + + def test_expand(self): + self.assertEqual(config.expand('~/x/y', home='/h'), '/h/x/y') + self.assertEqual(config.expand('/abs', home='/h'), '/abs') + self.assertEqual(config.expand(''), '') + + +class Hooks(unittest.TestCase): + """Every hook, run as Claude Code runs it, with a broken machine file: it still answers (its defaults) and says + so on stderr; with a good file or none it says nothing.""" + + def setUp(self): + self.tmp = tempfile.mkdtemp(prefix='agent-guards-config-hooks-') + self.addCleanup(shutil.rmtree, self.tmp, True) + self.env = dict(os.environ, HOME=self.tmp) + + def test_a_broken_section_is_named_on_stderr_and_the_defaults_used(self): + machine = fx.machine_file(self.tmp, text='{"version": 1, "agent-guards": ') + for hook in fx.wiring.HOOKS: + with self.subTest(hook): + r = fx.run_hook(hook, QUIET_EVENT, machine, env=self.env) + self.assertEqual(r.returncode, 0, r.stderr) + self.assertIn(f'{hook}: the machine file\'s "agent-guards" section cannot be used', r.stderr) + self.assertIn('built-in defaults used', r.stderr) + + def test_a_good_file_or_none_is_quiet(self): + good = fx.machine_file(self.tmp, {'memoryIndex': {'maxChars': 5000}}) + for machine in (fx.NO_MACHINE, good): + for hook in fx.wiring.HOOKS: + with self.subTest(hook=hook, machine=machine): + r = fx.run_hook(hook, QUIET_EVENT, machine, env=self.env) + self.assertEqual((r.returncode, r.stdout, r.stderr), (0, '', '')) + + def test_a_copy_without_the_lib_keeps_the_defaults_and_says_so(self): + """State: a copy that stopped half-way (the hook file is there, its lib is not).""" + bare = os.path.join(self.tmp, 'bin') + os.makedirs(bare) + for hook in fx.wiring.HOOKS: + with self.subTest(hook): + shutil.copy(os.path.join(fx.BIN, hook), bare) + r = subprocess.run([sys.executable, '-I', '-B', os.path.join(bare, hook)], capture_output=True, + text=True, input=json.dumps(QUIET_EVENT), timeout=60, env=self.env) + self.assertEqual(r.returncode, 0, r.stderr) + self.assertIn("cannot load the kit's config code", r.stderr) + + def test_a_usage_error_never_refuses(self): + """An argument: exit 1 with a usage line (the call runs). actions-disable-guard ignores arguments, as it + always did, and answers the event.""" + for hook in fx.wiring.HOOKS: + with self.subTest(hook): + r = fx.run_hook(hook, QUIET_EVENT, args=('--install',), env=self.env) + if hook == 'actions-disable-guard': + self.assertEqual((r.returncode, r.stdout), (0, '')) + continue + self.assertEqual(r.returncode, 1) + self.assertIn(f'usage: {hook}', r.stderr) + + +if __name__ == '__main__': + unittest.main() diff --git a/fork-kit/agent-guards/tests/guards_fixture.py b/fork-kit/agent-guards/tests/guards_fixture.py new file mode 100644 index 0000000000000..614a843dbd2ed --- /dev/null +++ b/fork-kit/agent-guards/tests/guards_fixture.py @@ -0,0 +1,70 @@ +"""Shared by the agent-guards tests: a machine file of their own, and a hook run the way Claude Code runs it. + +A hook reads the machine file at the fixed path (/etc/fork-kit/machine.json); a test never does. It points the +kit's config at a file in a temporary folder (or at one that is not there: the built-in defaults), owned by the +user who runs the test, through config.MACHINE_PATH and config.OWNER_UID, the two names that are there for tests. +In a separate process the same is done by RUNNER, which then runs the hook file as __main__. No root, no network. +""" +import importlib.machinery, importlib.util, json, os, subprocess, sys + +sys.dont_write_bytecode = True # the CI runner has no -B: no __pycache__ beside the hooks + +KIT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +BIN, LIB = os.path.join(KIT, 'bin'), os.path.join(KIT, 'lib') +sys.path.insert(0, LIB) +from agent_guards import config, wiring # noqa: E402 + +NO_MACHINE = '/nonexistent-agent-guards-test/machine.json' # not there: every hook uses its defaults +RUNNER = '''import runpy, sys +lib, machine, uid, hook = sys.argv[1:5] +sys.path.insert(0, lib) +from agent_guards import config +config.MACHINE_PATH, config.OWNER_UID = machine, int(uid) +sys.argv = [hook] + sys.argv[5:] +runpy.run_path(hook, run_name='__main__') +''' + + +def machine_file(folder, section=None, text=None, mode=0o644): + """/machine.json with that "agent-guards" section (or that exact text); its path.""" + path = os.path.join(folder, 'machine.json') + if text is None: + data = {'version': 1} + if section is not None: + data['agent-guards'] = section + text = json.dumps(data) + with open(path, 'w', encoding='utf-8') as f: + f.write(text) + os.chmod(path, mode) + return path + + +def use_machine(path): + """This process's hooks (loaded as modules) read `path`, owned by the user who runs the test.""" + config.MACHINE_PATH, config.OWNER_UID = path, os.geteuid() + + +def load_hook(name, machine=NO_MACHINE): + """bin/ as a module, with its config read from `machine`.""" + use_machine(machine) + mod_name = name.replace('-', '_') + loader = importlib.machinery.SourceFileLoader(mod_name, os.path.join(BIN, name)) + spec = importlib.util.spec_from_loader(mod_name, loader) + mod = importlib.util.module_from_spec(spec) + loader.exec_module(mod) + return mod + + +def run_hook(name, event, machine=NO_MACHINE, env=None, cwd=None, timeout=60, args=(), hook=None): + """Run bin/ (or the file `hook`) in a new process with `event` (a dict, or text) on stdin.""" + text = event if isinstance(event, str) else json.dumps(event) + argv = [sys.executable, '-I', '-B', '-c', RUNNER, LIB, machine, str(os.geteuid()), hook or os.path.join(BIN, name), + *args] + return subprocess.run(argv, input=text, capture_output=True, text=True, timeout=timeout, cwd=cwd, + env=env if env is not None else dict(os.environ)) + + +def answer(r): + """What a finished hook said, as agent_guards.check reads it.""" + from agent_guards import check + return check._answer(r) diff --git a/fork-kit/agent-guards/tests/install.test.py b/fork-kit/agent-guards/tests/install.test.py new file mode 100644 index 0000000000000..38c6a14d4e6b5 --- /dev/null +++ b/fork-kit/agent-guards/tests/install.test.py @@ -0,0 +1,172 @@ +"""agent-guards-install's own part on a fake host in a temporary folder (every fixed path under PREFIX, the current user +as root): the Claude Code managed settings drop-in (--settings / --no-settings). What every kit's installer does +(copy, switch, links, record, self-check, stops half-way, uninstall) and the shared bootstrap are tested once for +every kit in fork-kit/common/tests/kit_install.test.py. The rule tested here: while the drop-in is there, every hook +it names is there too (a missing actions-disable-guard refuses every Bash command), whatever step a run stops at. +No root, no network. + + python3 -I -B fork-kit/agent-guards/tests/install.test.py +""" +import json, os, shutil, sys, unittest + +sys.dont_write_bytecode = True # the CI runner has no -B: a __pycache__ in an installed version folder is a change +KIT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +sys.path.insert(0, os.path.join(os.path.dirname(KIT), 'common', 'tests')) +sys.path.insert(0, os.path.join(KIT, 'lib')) +import install_fixture as fx # noqa: E402 +from agent_guards import wiring # noqa: E402 + +SHA1, SHA2 = fx.SHA1, fx.SHA2 +DROP_IN = wiring.DROP_IN +CONFIG = '/etc/agent-guards/config.json' +FOREIGN = {'permissions': {'deny': ['Bash(rm -rf /)']}} + + +class Install(fx.FakeHost): + KIT_DIR, INSTALLER = KIT, os.path.join(KIT, 'sbin', 'agent-guards-install') + + def config(self): + with open(self.path(CONFIG)) as f: + return json.load(f) + + def drop_in(self): + """The drop-in's settings object, or None when it is not there.""" + try: + with open(self.path(DROP_IN)) as f: + return json.load(f) + except FileNotFoundError: + return None + + def write_drop_in(self, data): + os.makedirs(os.path.dirname(self.path(DROP_IN)), exist_ok=True) + with open(self.path(DROP_IN), 'w') as f: + f.write(data if isinstance(data, str) else json.dumps(data)) + + def assert_named_hooks_there(self): + """The rule: a drop-in names only hooks that are installed (links that end in a file).""" + if not os.path.lexists(self.path(DROP_IN)): + return + for _event, _matcher, cmd in wiring.commands_in(self.drop_in()): + path = cmd.split(';', 1)[0].split('=', 1)[1] + self.assertTrue(self.is_file(path), f'{DROP_IN} names {path}, which is not there') + + def test_fresh_install_writes_no_drop_in(self): + code, out, err = self.install() + self.assertEqual(code, 0, err) + self.assertEqual(self.config(), {'version': 1, 'settings': False}) + self.assertIsNone(self.drop_in()) + self.assertIn('hooks not in managed settings', out) + for hook in wiring.HOOKS + ('agent-guards',): + self.assertTrue(self.is_file(f'/usr/local/bin/{hook}'), hook) + self.assertEqual(self.run_main('self-check')[0], 0) + + def test_settings_writes_the_drop_in_with_every_hook(self): + code, out, err = self.install('--settings') + self.assertEqual(code, 0, err) + with open(self.path(DROP_IN)) as f: + self.assertEqual(f.read(), wiring.drop_in_text()) + self.assertEqual(self.config(), {'version': 1, 'settings': True}) + self.assertIn('hooks in managed settings', out) + self.assert_named_hooks_there() + for hook in wiring.HOOKS: + for event in {e for e, _m, items in wiring.ENTRIES if hook in dict(items)}: + self.assertIsNotNone(wiring.find(self.drop_in(), hook, event), (hook, event)) + self.assertEqual(self.run_main('self-check')[0], 0) + + def test_the_choice_is_kept_and_no_settings_removes_it(self): + self.assertEqual(self.install('--settings')[0], 0) + code, _, err = self.install(sha=SHA2) # an update with neither option keeps it + self.assertEqual(code, 0, err) + self.assertIsNotNone(self.drop_in()) + code, out, err = self.install('--no-settings', sha=SHA2) + self.assertEqual(code, 0, err) + self.assertIsNone(self.drop_in()) + self.assertIn(f'removed {DROP_IN}', out) + self.assertEqual(self.install(sha=SHA1)[0], 0) + self.assertIsNone(self.drop_in()) + self.assertEqual(self.config()['settings'], False) + self.assertEqual(self.run_main('self-check')[0], 0) + + def test_runs_again_and_changes_nothing(self): + self.assertEqual(self.install('--settings')[0], 0) + before = self.snapshot() + code, _, err = self.install() + self.assertEqual(code, 0, err) + self.assertEqual(self.snapshot(), before) + + def test_a_drop_in_it_did_not_write_is_left_alone(self): + for name, text in (('other settings', FOREIGN), ('not JSON', '{"hooks": '), + ('hooks of another tool', {'hooks': {'Stop': [{'hooks': [ + {'type': 'command', 'command': '/usr/local/bin/other-hook'}]}]}})): + with self.subTest(name): + self.fresh() + self.write_drop_in(text) + with open(self.path(DROP_IN)) as f: + before = f.read() + code, _, err = self.install('--settings') + self.assertEqual(code, 1) + self.assertIn('was not written by this kit', err) + code, _, err = self.install('--no-settings') # leaves it alone, installs the hooks + self.assertEqual(code, 0, err) + code, _, err = self.run_main('uninstall') + self.assertEqual(code, 0, err) + with open(self.path(DROP_IN)) as f: + self.assertEqual(f.read(), before) + + def test_a_managed_folder_that_is_a_link_is_refused(self): + os.makedirs(self.path('/elsewhere')) + os.makedirs(self.path('/etc'), exist_ok=True) + os.symlink('/elsewhere', self.path(wiring.MANAGED_DIR)) + code, _, err = self.install('--settings') + self.assertEqual(code, 1) + self.assertIn('is not a root-owned folder', err) + self.assertEqual(os.listdir(self.path('/elsewhere')), []) + self.assertEqual(self.install('--no-settings')[0], 0) # the hooks alone do not touch it + + def test_every_stop_half_way_then_run_again(self): + for step in self.m.STEPS: + with self.subTest(step=step): + self.fresh() + code, _, _ = self.install('--settings', stop_after=step) + self.assertEqual(code, f'stopped after {step} (test)') + self.assert_named_hooks_there() + code, _, err = self.install('--settings') + self.assertEqual(code, 0, err) + self.assertIsNotNone(self.drop_in()) + self.assertEqual(self.run_main('self-check')[0], 0) + + def test_an_update_stopped_half_way_keeps_the_hooks_of_the_drop_in(self): + for step in self.m.STEPS: + with self.subTest(step=step): + self.fresh() + self.assertEqual(self.install('--settings')[0], 0) + code, _, _ = self.install(sha=SHA2, stop_after=step) + self.assertEqual(code, f'stopped after {step} (test)') + self.assertIsNotNone(self.drop_in()) + self.assert_named_hooks_there() + + def test_uninstall_removes_the_drop_in_before_the_hooks(self): + n = 0 + while True: + n += 1 + self.fresh() + self.assertEqual(self.install('--settings')[0], 0) + with self.stop_context(n): + code, _, err, stopped = self.uninstall_stopped_after(n, check=self.assert_named_hooks_there) + self.assert_named_hooks_there() + if not stopped: + self.assertEqual(code, 0, err) + break + code, _, err = self.run_main('uninstall') # run again: finishes + self.assertEqual(code, 0, err) + self.assertIsNone(self.drop_in()) + self.assertFalse(os.path.lexists(self.path('/usr/local/bin/actions-disable-guard'))) + self.assertGreater(n, 3) + + def fresh(self): + shutil.rmtree(self.root) + os.makedirs(self.root) + + +if __name__ == '__main__': + unittest.main() diff --git a/fork-kit/agent-guards/tests/memory-index.test.py b/fork-kit/agent-guards/tests/memory-index.test.py new file mode 100644 index 0000000000000..7a655119000ac --- /dev/null +++ b/fork-kit/agent-guards/tests/memory-index.test.py @@ -0,0 +1,196 @@ +"""Tests of fork-kit/agent-guards/bin/memory-index-guard (PreToolUse: refuse a write that puts the auto-memory index +over budget; PostToolUse: block once when the index changed and is over). Each test has its own HOME, project folder +and state folder; the budget comes from a machine file of the test's own or the defaults (6000 / 160). + + python3 -I -B fork-kit/agent-guards/tests/memory-index.test.py +""" +import json, os, shutil, subprocess, sys, tempfile, time, unittest +from concurrent.futures import ThreadPoolExecutor + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +import guards_fixture as fx # noqa: E402 + +HOOK = 'memory-index-guard' +SMALL = '- [A](a.md) - a memory\n' + + +class Base(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.mkdtemp(prefix='memory-index-test-') + self.addCleanup(shutil.rmtree, self.tmp, True) + self.home = os.path.join(self.tmp, 'home') + self.proj = os.path.join(self.home, '.claude', 'projects', '-srv-work') + os.makedirs(os.path.join(self.proj, 'memory')) + self.transcript = os.path.join(self.proj, 'session-1.jsonl') + self.started(time.time() - 3600) + self.index = os.path.join(self.proj, 'memory', 'MEMORY.md') + self.env = dict(os.environ, HOME=self.home) + self.machine = fx.NO_MACHINE + self.state = os.path.join(self.home, '.cache', 'memory-index-guard') + + def started(self, when): + with open(self.transcript, 'w') as f: + f.write(json.dumps({'type': 'user', 'timestamp': time.strftime('%Y-%m-%dT%H:%M:%S.000Z', + time.gmtime(when))}) + '\n') + + def set_index(self, text, age=0): + with open(self.index, 'w') as f: + f.write(text) + if age: + t = time.time() - age + os.utime(self.index, (t, t)) + + def run_hook(self, event, sid='session-1', **extra): + ev = dict({'session_id': sid, 'transcript_path': self.transcript}, **event, **extra) + return fx.run_hook(HOOK, ev, self.machine, env=self.env) + + def pre(self, tool, **tool_input): + tool_input.setdefault('file_path', self.index) + return self.run_hook({'hook_event_name': 'PreToolUse', 'tool_name': tool, 'tool_input': tool_input}) + + def post(self, tool='Bash', sid='session-1'): + return self.run_hook({'hook_event_name': 'PostToolUse', 'tool_name': tool, 'tool_input': {'command': 'x'}}, + sid=sid) + + def assert_refused(self, r, *words): + self.assertEqual(r.returncode, 0, r.stderr) + self.assertEqual(fx.answer(r), 'refused', r.stdout) + out = json.loads(r.stdout) + text = out.get('reason') or out['hookSpecificOutput']['permissionDecisionReason'] + self.assertIn(f'Memory index {self.index} is over budget', text) + for w in words: + self.assertIn(w, text) + + def assert_passed(self, r): + self.assertEqual((r.returncode, r.stdout), (0, ''), r.stderr) + + +class Pre(Base): + def test_a_write_over_budget_is_refused_one_inside_passes(self): + self.set_index(SMALL) + self.assert_refused(self.pre('Write', content='x' * 6001), '6001 chars, budget 6000') + self.assert_refused(self.pre('Write', content=SMALL + 'y' * 161 + '\n'), 'line(s) 2 longer than 160') + self.assert_passed(self.pre('Write', content=('x' * 99 + '\n') * 60)) # 6000 chars + self.assert_passed(self.pre('Write', content=SMALL + 'y' * 160 + '\n')) + + def test_edits_are_worked_out_on_the_file(self): + self.set_index(SMALL + 'B\n') + self.assert_refused(self.pre('Edit', old_string='B', new_string='z' * 200)) + self.assert_passed(self.pre('Edit', old_string='B', new_string='z' * 100)) + self.assert_passed(self.pre('Edit', old_string='not there', new_string='z' * 9000)) # the tool refuses it + self.assert_refused(self.pre('MultiEdit', edits=[{'old_string': 'B', 'new_string': 'C'}, + {'old_string': 'C', 'new_string': 'w' * 7000}])) + self.set_index('B B B\n') + self.assert_refused(self.pre('Edit', old_string='B', new_string='q' * 60, replace_all=True)) + self.assert_passed(self.pre('Edit', old_string='B', new_string='q' * 60)) + + def test_cutting_down_an_index_already_over_is_allowed(self): + self.set_index('x' * 9000) + self.assert_passed(self.pre('Write', content='x' * 8000)) + self.assert_passed(self.pre('Edit', old_string='x' * 100, new_string='')) + self.assert_refused(self.pre('Write', content='x' * 9001)) + + def test_only_a_memory_index_is_read(self): + other = os.path.join(self.tmp, 'notes', 'MEMORY.md') + for path in (other, os.path.join(self.proj, 'memory', 'other.md'), ''): + with self.subTest(path): + self.assert_passed(self.pre('Write', file_path=path, content='x' * 9000)) + # another project's index (any project's memory/MEMORY.md) counts + os.makedirs(os.path.join(self.home, '.claude', 'projects', 'p2', 'memory')) + r = self.pre('Write', file_path=os.path.join(self.home, '.claude', 'projects', 'p2', 'memory', 'MEMORY.md'), + content='x' * 9000) + self.assertEqual(fx.answer(r), 'refused') + self.assert_passed(self.pre('Read', content='x' * 9000)) + + def test_the_budget_comes_from_the_machine_file(self): + self.machine = fx.machine_file(self.tmp, {'memoryIndex': {'maxChars': 100, 'maxLine': 20}}) + self.set_index('') + self.assert_refused(self.pre('Write', content='x' * 101), 'budget 100') + self.assert_refused(self.pre('Write', content='y' * 21), 'longer than 20') + self.assert_passed(self.pre('Write', content='- a\n' * 20)) + + def test_a_very_long_write_still_answers_in_time(self): + self.set_index(SMALL) + start = time.monotonic() + self.assert_refused(self.pre('Write', content=('z' * 200 + '\n') * 30000)) + self.assertLess(time.monotonic() - start, 5) + + +class Post(Base): + def test_a_change_over_budget_blocks_once(self): + self.set_index('x' * 7000) # changed after the session started + self.assert_refused(self.post(), '7000 chars') + self.assert_passed(self.post()) # seen: not again + self.set_index('x' * 7001) + self.assert_refused(self.post(), '7001 chars') + self.assert_passed(self.post('Write')) + self.assert_refused(self.post(sid='session-2')) # another session looks for itself + + def test_an_index_over_before_the_session_started_is_left_alone(self): + self.set_index('x' * 7000, age=7200) # older than the session (1 h) + self.assert_passed(self.post()) + self.assert_passed(self.post()) + + def test_inside_budget_or_no_index_passes(self): + self.assert_passed(self.post()) # no index at all + self.set_index(SMALL) + self.assert_passed(self.post()) + + def test_a_transcript_missing_or_odd_counts_as_just_started(self): + for text in (None, '', 'not json\n', '{"timestamp": "yesterday"}\n'): + with self.subTest(text=text): + shutil.rmtree(self.state, ignore_errors=True) + if text is None: + if os.path.exists(self.transcript): + os.unlink(self.transcript) + else: + with open(self.transcript, 'w') as f: + f.write(text) + self.set_index('x' * 7000, age=60) + self.assert_passed(self.post()) # first look, older than "now" + + def test_state_it_cannot_write_or_read_never_breaks_a_call(self): + """A state folder that is a file: every call looks again (and blocks again); a garbled state file: changed.""" + self.machine = fx.machine_file(self.tmp, {'memoryIndex': {'stateDir': os.path.join(self.tmp, 'a-file')}}) + with open(os.path.join(self.tmp, 'a-file'), 'w') as f: + f.write('x') + self.set_index('x' * 7000) + self.assert_refused(self.post()) + self.assert_refused(self.post()) + self.machine = fx.NO_MACHINE + os.makedirs(self.state) + with open(os.path.join(self.state, 'session-1'), 'w') as f: + f.write('\0garbled') + self.assert_refused(self.post()) + self.assert_passed(self.post()) + + def test_an_odd_session_id_stays_in_the_state_folder(self): + self.set_index('x' * 7000) + self.assert_refused(self.post(sid='../../escape')) + self.assertEqual(os.listdir(self.state), ['escape']) + self.assertFalse(os.path.exists(os.path.join(self.home, 'escape'))) + + def test_two_at_once_leave_one_whole_state_file(self): + self.set_index('x' * 7000) + with ThreadPoolExecutor(8) as pool: + results = list(pool.map(lambda _: self.post(), range(16))) + self.assertTrue(all(r.returncode == 0 for r in results)) + self.assertGreaterEqual(sum(fx.answer(r) == 'refused' for r in results), 1) + self.assertEqual(os.listdir(self.state), ['session-1']) # no temporary file left + with open(os.path.join(self.state, 'session-1')) as f: + mtime, size = f.read().split() + self.assertEqual(int(size), 7000) + self.assert_passed(self.post()) + + +class Robust(Base): + def test_odd_input_never_breaks_a_call(self): + for text in ('', 'not json', '[]', '{"hook_event_name": "PreToolUse", "tool_input": "x"}', + '{"hook_event_name": "PostToolUse", "transcript_path": 5}'): + with self.subTest(text): + r = fx.run_hook(HOOK, text, env=self.env) + self.assert_passed(r) + + +if __name__ == '__main__': + unittest.main() diff --git a/fork-kit/agent-guards/tests/wiring.test.py b/fork-kit/agent-guards/tests/wiring.test.py new file mode 100644 index 0000000000000..532000aa21962 --- /dev/null +++ b/fork-kit/agent-guards/tests/wiring.test.py @@ -0,0 +1,205 @@ +"""agent_guards.wiring and agent_guards.check: the settings entries of the kit's hooks, run as Claude Code runs them +(`/bin/sh -c COMMAND`, the event on stdin). A missing or failing actions-disable-guard refuses (exit 2) and says so; +the other hooks then let the call run (exit 1) and say so. `agent-guards check` passes on the kit's own entries and +names a hook that is missing, broken or not wired. The hooks run from a folder of stand-ins that read no machine +file (their defaults), with HOME in a temporary folder, so nothing of the machine is read or changed. + + python3 -I -B fork-kit/agent-guards/tests/wiring.test.py +""" +import io, json, os, shutil, subprocess, sys, tempfile, unittest + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +import guards_fixture as fx # noqa: E402 +from guards_fixture import wiring # noqa: E402 +from agent_guards import check # noqa: E402 + +BASH = {'hook_event_name': 'PreToolUse', 'tool_name': 'Bash', 'tool_input': {'command': 'ls'}, 'session_id': 's'} +STAND_IN = '''import runpy, sys +sys.path.insert(0, {lib!r}) +from agent_guards import config +config.MACHINE_PATH, config.OWNER_UID = {machine!r}, {uid} +sys.argv = [{hook!r}] + sys.argv[1:] +runpy.run_path({hook!r}, run_name='__main__') +''' + + +class Entries(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.mkdtemp(prefix='agent-guards-wiring-') + self.addCleanup(shutil.rmtree, self.tmp, True) + self.bin = os.path.join(self.tmp, 'bin') + os.makedirs(self.bin) + for hook in wiring.HOOKS: # each one: the kit's hook with the built-in defaults + self.stand_in(hook) + self.home = os.path.join(self.tmp, 'home') + os.makedirs(self.home) + self.env = dict(os.environ, HOME=self.home) + self.settings = {'hooks': wiring.hooks(self.bin, sys.executable)} + + def stand_in(self, hook, text=None): + with open(os.path.join(self.bin, hook), 'w') as f: + f.write(text if text is not None else STAND_IN.format( + lib=fx.LIB, machine=fx.NO_MACHINE, uid=os.geteuid(), hook=os.path.join(fx.BIN, hook))) + + def sh(self, hook, event, command=None, timeout=60): + cmd = command or wiring.command(hook, self.bin, sys.executable) + return subprocess.run(['/bin/sh', '-c', cmd], input=json.dumps(event), capture_output=True, text=True, + timeout=timeout, env=self.env, cwd=self.tmp) + + def test_the_entries_are_the_ones_settings_had(self): + self.assertEqual(sorted((e, x.get('matcher'), [h['timeout'] for h in x['hooks']]) + for e, xs in wiring.hooks().items() for x in xs), + sorted([('PreToolUse', 'Write|Edit|MultiEdit', [5]), ('PreToolUse', 'Bash', [10]), + ('PreToolUse', 'Bash|Monitor', [10]), ('PostToolUse', 'Write|Edit|MultiEdit|Bash', [5]), + ('UserPromptSubmit', None, [5]), ('Stop', None, [5, 5])])) + for _e, _m, cmd in wiring.commands_in({'hooks': wiring.hooks()}): + self.assertIn('/usr/local/bin/', cmd) + self.assertIn('/usr/bin/python3 -IB "$g"', cmd) + self.assertTrue(wiring.ours(json.loads(wiring.drop_in_text()))) + self.assertFalse(wiring.ours({'hooks': wiring.hooks(), 'permissions': {}})) + self.assertFalse(wiring.ours({'hooks': {'Stop': [{'hooks': [{'type': 'command', 'command': '/x/other'}]}]}})) + self.assertFalse(wiring.ours({'hooks': {}})) + + def test_find_matches_whole_names_only(self): + s = {'hooks': {'Stop': [{'hooks': [{'type': 'command', 'command': '/x/my-bg-guard-2'}, + {'type': 'command', 'command': 'bg-guard 2>/dev/null || true'}]}]}} + self.assertEqual(wiring.find(s, 'bg-guard', 'Stop'), 'bg-guard 2>/dev/null || true') + self.assertIsNone(wiring.find(s, 'bg-guard', 'PreToolUse')) + self.assertIsNone(wiring.find({'hooks': {'Stop': 'x'}}, 'bg-guard', 'Stop')) + self.assertIsNone(wiring.find(None, 'bg-guard', 'Stop')) + + def test_a_present_hook_answers_through_its_entry(self): + r = self.sh('actions-disable-guard', dict(BASH, tool_input={'command': 'gh workflow disable 1 -R a/b'})) + self.assertEqual(fx.answer(r), 'refused', r.stderr) + r = self.sh('actions-disable-guard', BASH) + self.assertEqual((r.returncode, r.stdout, r.stderr), (0, '', '')) + r = self.sh('capacity-pipe-guard', dict(BASH, tool_input={'command': 't3-capacity 1 | tail'})) + self.assertEqual(r.returncode, 2) + self.assertIn('Refused by capacity-pipe-guard', r.stderr) + + def test_a_missing_hook_fails_its_way_and_says_so(self): + for hook in wiring.HOOKS: + with self.subTest(hook): + os.unlink(os.path.join(self.bin, hook)) + r = self.sh(hook, BASH) + self.assertEqual(r.returncode, 2 if hook in wiring.CLOSED else 1) + self.assertIn(f'{hook}: {self.bin}/{hook} is missing: {wiring.WHAT_IS_LOST[hook]}', r.stderr) + self.stand_in(hook) + + def test_a_hook_that_cannot_be_read_counts_as_missing(self): + if os.geteuid() == 0: + self.skipTest('root reads every file') + os.chmod(os.path.join(self.bin, 'actions-disable-guard'), 0) + r = self.sh('actions-disable-guard', BASH) + self.assertEqual(r.returncode, 2) + self.assertIn('is missing', r.stderr) + + def test_a_failing_hook_fails_its_way(self): + """A crash, a hook cut half-way, an exit of its own: the closed one refuses, the others let it run.""" + broken = {'crash': 'raise SystemExit(3)', 'cut half-way': 'import json\ndef main(:\n', 'empty': ''} + for name, text in broken.items(): + for hook in wiring.HOOKS: + with self.subTest(hook=hook, broken=name): + self.stand_in(hook, text) + r = self.sh(hook, BASH) + if hook in wiring.CLOSED: + self.assertEqual(r.returncode, 2 if name != 'empty' else 0) # an empty file says nothing + if name != 'empty': + self.assertIn('actions-disable-guard: the guard failed (exit', r.stderr) + self.assertIn('the command is refused', r.stderr) + else: + self.assertNotEqual(r.returncode, 2) + self.stand_in(hook) + + def test_a_hook_killed_by_a_timeout_refuses_only_the_closed_one(self): + """Claude Code ends a hook at its timeout and goes on (no onFailure). Killed by a signal on its own (the + machine ran out of memory, say), the closed entry still refuses.""" + for hook in ('actions-disable-guard', 'capacity-pipe-guard'): + with self.subTest(hook): + self.stand_in(hook, 'import os, signal\nos.kill(os.getpid(), signal.SIGKILL)\n') + r = self.sh(hook, BASH) + self.assertEqual(r.returncode == 2, hook in wiring.CLOSED, r.stderr) + self.stand_in(hook) + + +class Check(unittest.TestCase): + """agent-guards check, on the kit's entries (stand-ins with the defaults) and on broken wiring.""" + + def setUp(self): + Entries.setUp(self) + self.old_home = os.environ.get('HOME') + os.environ['HOME'] = self.home # check.run's clean-up of its made-up session, in this process + self.addCleanup(self.restore_home) + fx.use_machine(fx.NO_MACHINE) + + def restore_home(self): + if self.old_home is None: + os.environ.pop('HOME', None) + else: + os.environ['HOME'] = self.old_home + + stand_in = Entries.stand_in + + def run_check(self, settings): + lines = [] + code = check.run(settings, 'test settings', say=lines.append) + return code, lines + + def test_the_kit_entries_pass(self): + code, lines = self.run_check(self.settings) + self.assertEqual(code, 0, '\n'.join(lines)) + self.assertEqual(sum(ln.startswith('PASS') for ln in lines), 11, '\n'.join(lines)) + self.assertEqual(lines[-1], 'check: test settings: OK') + self.assertEqual(os.listdir(os.path.join(self.home, '.cache', 'memory-index-guard')), []) # cleaned up + self.assertEqual(os.listdir(os.path.join(self.home, '.local', 'state', 'bg-guard')), []) + + def test_a_hook_not_wired_is_missing(self): + s = json.loads(json.dumps(self.settings)) + s['hooks']['Stop'] = [{'hooks': [h for h in s['hooks']['Stop'][0]['hooks'] if 'bg-guard' not in h['command']]}] + code, lines = self.run_check(s) + self.assertEqual(code, 1) + self.assertEqual([ln for ln in lines if ln.startswith('MISSING')], + ['MISSING bg-guard (Stop): not wired in test settings']) + self.assertEqual(self.run_check({})[0], 1) + + def test_a_missing_or_broken_hook_fails_the_check(self): + os.unlink(os.path.join(self.bin, 'capacity-pipe-guard')) + code, lines = self.run_check(self.settings) + self.assertEqual(code, 1) + self.assertIn('FAIL capacity-pipe-guard (PreToolUse) t3-capacity piped: failed (exit 1)', + ' '.join(lines)) + self.stand_in('capacity-pipe-guard') + self.stand_in('memory-index-guard', 'import sys\nsys.exit(0)\n') # a hook that lets everything through + code, lines = self.run_check(self.settings) + self.assertEqual(code, 1) + self.assertTrue([ln for ln in lines if ln.startswith('FAIL memory-index-guard')]) + + def test_a_hook_that_hangs_is_a_failure_not_a_hang(self): + self.stand_in('bg-guard', 'import time\ntime.sleep(600)\n') + real = check._run + check._run = lambda *a, **k: real(*a, **dict(k, timeout=2)) + self.addCleanup(setattr, check, '_run', real) + code, lines = self.run_check(self.settings) + self.assertEqual(code, 1) + self.assertTrue([ln for ln in lines if ln.startswith('FAIL bg-guard')], '\n'.join(lines)) + + def test_the_command(self): + """agent-guards hooks / check --settings / --help, as a command.""" + cli = os.path.join(fx.BIN, 'agent-guards') + r = subprocess.run([sys.executable, '-I', '-B', cli, 'hooks', '--bin', '/opt/x'], capture_output=True, + text=True, timeout=60) + self.assertEqual(r.returncode, 0, r.stderr) + self.assertEqual(json.loads(r.stdout), {'hooks': wiring.hooks('/opt/x')}) + r = subprocess.run([sys.executable, '-I', '-B', cli, '--help'], capture_output=True, text=True, timeout=60) + self.assertIn('self-check', r.stdout) + path = os.path.join(self.tmp, 'settings.json') + with open(path, 'w') as f: + f.write('{not json') + r = subprocess.run([sys.executable, '-I', '-B', cli, 'check', '--settings', path], capture_output=True, + text=True, timeout=60) + self.assertEqual(r.returncode, 1) + self.assertIn('cannot read', r.stderr) + + +if __name__ == '__main__': + unittest.main() diff --git a/fork-kit/common/README.md b/fork-kit/common/README.md index 439db8eb279ba..0e00ac1008739 100644 --- a/fork-kit/common/README.md +++ b/fork-kit/common/README.md @@ -72,7 +72,7 @@ standard library. ## The installer -`kit_install.py` is the installer of the cleaner, golive and schedule-kick kits; each kit's `sbin/-install` is a small +`kit_install.py` is the installer of the agent-guards, cleaner, golive and schedule-kick kits; each kit's `sbin/-install` is a small subclass that names its paths, links, files and modules, and adds its own steps. `install --source FOLDER --sha SHA`, as root: @@ -108,7 +108,7 @@ root's `uninstall` can then wait there forever, with both locks held (as it can process whose memory is FUSE-backed). It fails safe: nothing is removed yet, and Ctrl-C ends it and frees the locks. Updates go through the bootstrap. -`bootstrap.sh --kit cleaner|golive|schedule-kick --repo OWNER/REPO --sha SHA [kit options]` checks the commit is on the protected +`bootstrap.sh --kit agent-guards|cleaner|golive|schedule-kick --repo OWNER/REPO --sha SHA [kit options]` checks the commit is on the protected release branch, downloads exactly that commit and runs the kit's installer; it passes on only the kit's own options. ## Tests diff --git a/fork-kit/common/bootstrap.sh b/fork-kit/common/bootstrap.sh index f55df5e463e76..f478326a250ec 100644 --- a/fork-kit/common/bootstrap.sh +++ b/fork-kit/common/bootstrap.sh @@ -5,6 +5,7 @@ # sh fork-kit-bootstrap.sh --kit KIT --repo FORK_OWNER/FORK --sha RELEASE_SHA [kit options] # # KIT and its options (each kit's sbin/*-install says what they do): +# agent-guards fork-kit/agent-guards/sbin/agent-guards-install [--settings | --no-settings] # cleaner fork-kit/cleaner/sbin/fork-cleaner-install [--timer | --no-timer] # golive fork-kit/golive/sbin/t3-golive-install (none) # schedule-kick fork-kit/schedule-kick/sbin/schedule-kick-install [--timer | --no-timer] @@ -29,14 +30,20 @@ while [ $# -gt 0 ]; do --sha) [ $# -ge 2 ] || die "--sha needs a value"; sha="$2"; shift 2 ;; --release-branch) [ $# -ge 2 ] || die "--release-branch needs a value"; branch="$2"; shift 2 ;; --timer|--no-timer) opt="$1"; shift ;; + --settings|--no-settings) opt="$1"; shift ;; *) die "unknown option $1 (see the top of this file)" ;; esac done case "$kit" in + agent-guards) installer='sbin/agent-guards-install' ;; cleaner) installer='sbin/fork-cleaner-install' ;; golive) installer='sbin/t3-golive-install'; [ -z "$opt" ] || die "$opt is not an option of --kit golive" ;; schedule-kick) installer='sbin/schedule-kick-install' ;; - *) die "--kit must be one of: cleaner golive schedule-kick" ;; + *) die "--kit must be one of: agent-guards cleaner golive schedule-kick" ;; +esac +case "$kit:$opt" in + agent-guards:--timer|agent-guards:--no-timer|cleaner:--*settings|schedule-kick:--*settings) + die "$opt is not an option of --kit $kit" ;; esac printf '%s\n' "$repo" | grep -Eqx '[A-Za-z0-9][A-Za-z0-9-]{0,38}/[A-Za-z0-9._-]{1,100}' || die "--repo must be OWNER/NAME" printf '%s\n' "$sha" | grep -Eqx '[0-9a-f]{40}' || die "--sha must be the full 40-character release commit" diff --git a/fork-kit/common/machine.example.json b/fork-kit/common/machine.example.json index f66b3162157ae..d64c53c5595a1 100644 --- a/fork-kit/common/machine.example.json +++ b/fork-kit/common/machine.example.json @@ -49,6 +49,27 @@ "policyFile": "/etc/fork-kit/model-policy.json", "t3ModelManifests": ["/srv/example/t3-home/userdata/model-manifest.json"] }, + "agent-guards": { + "actionsDisable": { + "stateDir": "~/.local/state/actions-disable-guard", + "refuseScripts": [{ "name": "example_garden.py", "flag": "--fix", "why": "disables workflows in the forks" }] + }, + "capacityPipe": { "commands": ["t3-capacity"] }, + "memoryIndex": { "maxChars": 6000, "maxLine": 160, "stateDir": "~/.cache/memory-index-guard" }, + "bgGuard": { + "skipSessionsFiles": ["~/.local/state/example-orch/slot-sessions.txt"], + "maxBlocks": 3, + "stateDir": "~/.local/state/bg-guard" + }, + "agentSlots": { + "sessionsFile": "~/.local/state/example-orch/slot-sessions.txt", + "queue": "/srv/example/QUEUE.md", + "readyHeading": "## Ready", + "maxAlive": 10, + "processName": "claude", + "note": "at most 4 build agents" + } + }, "cleaner": { "logFile": "~/.local/state/fork-cleaner/cleaner.log", "mustKeep": ["/srv/example/ledger"], diff --git a/fork-kit/common/tests/kit_install.test.py b/fork-kit/common/tests/kit_install.test.py index 11fd271f48326..c0d2edefe23a9 100644 --- a/fork-kit/common/tests/kit_install.test.py +++ b/fork-kit/common/tests/kit_install.test.py @@ -13,6 +13,7 @@ SHA1, SHA2 = fx.SHA1, fx.SHA2 KITS = { + 'agent-guards': os.path.join(fx.FORK_KIT, 'agent-guards', 'sbin', 'agent-guards-install'), 'cleaner': os.path.join(fx.FORK_KIT, 'cleaner', 'sbin', 'fork-cleaner-install'), 'golive': os.path.join(fx.FORK_KIT, 'golive', 'sbin', 't3-golive-install'), 'schedule-kick': os.path.join(fx.FORK_KIT, 'schedule-kick', 'sbin', 'schedule-kick-install'), @@ -599,6 +600,10 @@ def test_bad_options_and_not_root_are_refused(self): self.assertFalse(os.path.exists(self.path(self.m.ETC))) +class AgentGuards(Contract, fx.FakeHost): + KIT_DIR, INSTALLER = os.path.join(fx.FORK_KIT, 'agent-guards'), KITS['agent-guards'] + + class Cleaner(Contract, fx.FakeHost): KIT_DIR, INSTALLER = os.path.join(fx.FORK_KIT, 'cleaner'), KITS['cleaner'] @@ -622,7 +627,7 @@ def refused(self, *args): def test_the_kit_is_one_it_knows(self): self.assertEqual(self.refused('--repo', 'a/b', '--sha', SHA1), 'fork-kit-bootstrap: --kit must be one of: ' - 'cleaner golive schedule-kick') + 'agent-guards cleaner golive schedule-kick') self.assertIn('--kit must be one of', self.refused('--kit', '../heavy', '--repo', 'a/b', '--sha', SHA1)) self.assertEqual(self.refused('--repo', 'a/b', '--sha', SHA1, '--kit'), 'fork-kit-bootstrap: --kit needs a value') @@ -630,7 +635,7 @@ def test_the_kit_is_one_it_knows(self): def test_only_the_kit_options_are_passed_on(self): """Nothing reaches the installer unchecked: a second --source would install a folder the release check never saw.""" - for kit in ('cleaner', 'golive', 'schedule-kick'): + for kit in ('agent-guards', 'cleaner', 'golive', 'schedule-kick'): for extra in (['--source', '/elsewhere'], ['--x']): with self.subTest(kit=kit, extra=extra): err = self.refused('--kit', kit, '--repo', 'a/b', '--sha', SHA1, *extra) @@ -642,9 +647,15 @@ def test_only_the_kit_options_are_passed_on(self): for timer in ('--timer', '--no-timer'): # an option of one kit only self.assertEqual(self.refused(timer, '--kit', 'golive', '--repo', 'a/b', '--sha', SHA1), f'fork-kit-bootstrap: {timer} is not an option of --kit golive') + for kit, opt in (('agent-guards', '--timer'), ('agent-guards', '--no-timer'), ('cleaner', '--settings'), + ('schedule-kick', '--no-settings'), ('golive', '--settings')): + with self.subTest(kit=kit, opt=opt): + self.assertEqual(self.refused('--kit', kit, opt, '--repo', 'a/b', '--sha', SHA1), + f'fork-kit-bootstrap: {opt} is not an option of --kit {kit}') if os.geteuid() != 0: # as root it would go on to download for args in (['--kit', 'cleaner', '--timer'], ['--no-timer', '--kit', 'cleaner'], ['--kit', 'golive'], - ['--kit', 'schedule-kick', '--timer']): + ['--kit', 'schedule-kick', '--timer'], ['--kit', 'agent-guards', '--settings'], + ['--no-settings', '--kit', 'agent-guards']): with self.subTest(args=args): self.assertIn('run this as root', self.refused('--repo', 'a/b', '--sha', SHA1, *args)) @@ -754,8 +765,14 @@ def test_only_the_kit_options_are_passed_on(self): 'bootstrap', ' [ -z "$opt" ] || die "$opt is not an option of --kit golive" ;;', ' ;;', 'test_only_the_kit_options_are_passed_on'), 'bootstrap: an unknown kit is refused': ( - 'bootstrap', ' *) die "--kit must be one of: cleaner golive schedule-kick" ;;', ' *) installer=x ;;', + 'bootstrap', ' *) die "--kit must be one of: agent-guards cleaner golive schedule-kick" ;;', ' *) installer=x ;;', 'test_the_kit_is_one_it_knows'), + 'bootstrap: --settings is kept, nothing after it passed on': ( + 'bootstrap', ' --settings|--no-settings) opt="$1"; shift ;;', ' --settings|--no-settings) break ;;', + 'test_only_the_kit_options_are_passed_on'), + 'bootstrap: each kit gets only its own options': ( + 'bootstrap', ' die "$opt is not an option of --kit $kit" ;;', ' ;;', + 'test_only_the_kit_options_are_passed_on'), } From 268c2185ea7091c9b30765fc2fe97da35551103d Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 03:39:24 +0000 Subject: [PATCH 2/9] fork-kit/agent-guards: lens round 1 fixes for G4a - actions-disable-guard and capacity-pipe-guard match Bash|Monitor; the memory-index after-call check matches Monitor too; check reports a guard wired for Bash only as missing. - The owner's approval is a root-owned file with the hash of a one-time code (agent-guards approve); the session variable is no longer read, since nested sessions inherited it. - Refuse starting a nested session without this machine's hooks (claude --bare/--safe-mode, CLAUDE_CODE_SIMPLE, codex). - The closed hook sets onFailure block; an empty guard file refuses. - A ruleset set to evaluate is refused like disabled. - Each hook reads only its own part of the machine file section; bad keys and refuseScripts rows are dropped one by one and named to the agent; self-check does the strict check. - Uninstall refuses while a foreign settings file names a hook or an older session runs; rollback is --no-settings. - check --settings as root reads only a root-owned file; check runs hooks under a temporary HOME; self-check checks links, an open approval and passwordless ways to root. Co-Authored-By: Claude Opus 5.5 --- fork-kit/agent-guards/README.md | 105 ++++++---- .../agent-guards/bin/actions-disable-guard | 182 ++++++++++++------ fork-kit/agent-guards/bin/agent-guards | 110 ++++++++++- fork-kit/agent-guards/bin/agent-slots | 32 ++- fork-kit/agent-guards/bin/bg-guard | 31 ++- fork-kit/agent-guards/bin/capacity-pipe-guard | 40 +++- fork-kit/agent-guards/bin/memory-index-guard | 31 ++- .../agent-guards/lib/agent_guards/approval.py | 113 +++++++++++ .../agent-guards/lib/agent_guards/check.py | 31 ++- .../agent-guards/lib/agent_guards/config.py | 129 ++++++++++--- .../agent-guards/lib/agent_guards/wiring.py | 50 +++-- .../agent-guards/sbin/agent-guards-install | 151 +++++++++++++-- .../tests/actions-disable.test.py | 143 +++++++++++--- fork-kit/agent-guards/tests/config.test.py | 66 ++++++- fork-kit/agent-guards/tests/install.test.py | 126 +++++++++++- fork-kit/agent-guards/tests/wiring.test.py | 182 +++++++++++++++++- fork-kit/common/machine.example.json | 4 +- 17 files changed, 1299 insertions(+), 227 deletions(-) create mode 100644 fork-kit/agent-guards/lib/agent_guards/approval.py diff --git a/fork-kit/agent-guards/README.md b/fork-kit/agent-guards/README.md index 1b6931eaa5269..f88cc08393a7b 100644 --- a/fork-kit/agent-guards/README.md +++ b/fork-kit/agent-guards/README.md @@ -9,13 +9,13 @@ Linux, Python 3 standard library only. One file per hook in [bin/](bin/), the sh ## The hooks -| Hook | Event (matcher) | Refuses | If the hook is missing or fails | -| ----------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -| `actions-disable-guard` | PreToolUse (`Bash`), 10 s | Disabling a GitHub Actions workflow or Actions itself, or deleting or weakening branch protection or rulesets, on any repo (`gh workflow disable`, `gh api .../actions/workflows//disable`, ...). Also a listed script run with its listed flag (`refuseScripts`). | **Refuses** (exit 2): every Bash command is refused until it is back, with a line saying so | -| `capacity-pipe-guard` | PreToolUse (`Bash\|Monitor`), 10 s | A pipe out of a capacity check (`t3-capacity 2048 \| tail -1 && heavy-step`): the pipe hides the check's NOT OK exit | Passes (exit 1, "hook skipped, commands are NOT checked") | -| `memory-index-guard` | PreToolUse (`Write\|Edit\|MultiEdit`) and PostToolUse (`Write\|Edit\|MultiEdit\|Bash`), 5 s | An auto-memory index (`/memory/MEMORY.md`) over its budget: a write that would make it too big (Pre), or one that did, through any tool (Post, once per change) | Passes (exit 1, with a line) | -| `bg-guard` | Stop, 5 s | Ending a turn while a Bash command the agent started in the background still runs (the end of it may never wake the agent). At most `maxBlocks` times per session | Passes (exit 1, with a line) | -| `agent-slots` | UserPromptSubmit and Stop, 5 s | Only for the orchestrator sessions listed in `sessionsFile`: adds "agents alive, slots free, ready queue" as context; blocks a stop once while slots are free and the ready queue has items | Passes (exit 1, with a line) | +| Hook | Event (matcher) | Refuses | If the hook is missing or fails | +| ----------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | +| `actions-disable-guard` | PreToolUse (`Bash\|Monitor`), 10 s, `onFailure: block` | Disabling a GitHub Actions workflow or Actions itself, or deleting or weakening branch protection or rulesets (`enforcement` set to `disabled` or `evaluate`), on any repo (`gh workflow disable`, `gh api .../actions/workflows//disable`, ...). Also a listed script run with its listed flag (`refuseScripts`), and starting a nested agent session that runs without this machine's hooks (`claude --bare`, `--safe-mode`, `CLAUDE_CODE_SIMPLE`, `codex`). | **Refuses** (exit 2): every Bash and Monitor command is refused until it is back, with a line saying so | +| `capacity-pipe-guard` | PreToolUse (`Bash\|Monitor`), 10 s | A pipe out of a capacity check (`t3-capacity 2048 \| tail -1 && heavy-step`): the pipe hides the check's NOT OK exit | Passes (exit 1, "hook skipped, commands are NOT checked") | +| `memory-index-guard` | PreToolUse (`Write\|Edit\|MultiEdit`) and PostToolUse (`Write\|Edit\|MultiEdit\|Bash\|Monitor`), 5 s | An auto-memory index (`/memory/MEMORY.md`) over its budget: a write that would make it too big (Pre), or one that did, through any tool (Post, once per change) | Passes (exit 1, with a line) | +| `bg-guard` | Stop, 5 s | Ending a turn while a Bash command the agent started in the background still runs (the end of it may never wake the agent). At most `maxBlocks` times per session | Passes (exit 1, with a line) | +| `agent-slots` | UserPromptSubmit and Stop, 5 s | Only for the orchestrator sessions listed in `sessionsFile`: adds "agents alive, slots free, ready queue" as context; blocks a stop once while slots are free and the ready queue has items | Passes (exit 1, with a line) | How each hook answers is what Claude Code reads: PreToolUse refuses with exit 2 and the reason on stderr. PostToolUse and Stop block with `{"decision": "block", "reason": ...}` on stdout. UserPromptSubmit adds `additionalContext`. @@ -30,41 +30,66 @@ work on the machine. The settings entry does both (`agent-guards hooks` prints i ```sh # closed -g=/usr/local/bin/actions-disable-guard; [ -r "$g" ] || { echo "actions-disable-guard: $g is missing: every Bash command is refused until it is back" >&2; exit 2; }; /usr/bin/python3 -IB "$g" || { echo "actions-disable-guard: the guard failed (exit $?): the command is refused" >&2; exit 2; } +g=/usr/local/bin/actions-disable-guard; [ -r "$g" ] && [ -s "$g" ] || { echo "actions-disable-guard: $g is missing or empty: every Bash and Monitor command is refused until it is back" >&2; exit 2; }; /usr/bin/python3 -IB "$g" || { echo "actions-disable-guard: the guard failed (exit $?): the command is refused" >&2; exit 2; } # open g=/usr/local/bin/capacity-pipe-guard; [ -r "$g" ] || { echo "capacity-pipe-guard: $g is missing: hook skipped, commands are NOT checked" >&2; exit 1; }; exec /usr/bin/python3 -IB "$g" ``` -A hook that runs past its timeout is ended by Claude Code, and the call goes on (no hook here sets `onFailure`). -`actions-disable-guard` answers by itself within 5 s of its start (it refuses when it runs out of time with a -guarded word unread), well inside its 10 s. +A hook that runs past its timeout is ended by Claude Code. For the open hooks the call then goes on. The +`actions-disable-guard` entry sets `"onFailure": "block"`, so a timeout or a hook that cannot start refuses the call. +It also answers by itself within 5 s of its start (it refuses when it runs out of time with a guarded word unread), +well inside its 10 s. + +**Tools.** The Bash and Monitor tools both run shell text (`tool_input.command`), so the command hooks match both. +`agent-guards check` fails a hook that is wired for Bash only (MISSING ... Monitor). + +**Nested agent sessions.** Managed hooks run in every Claude Code session, a nested `claude -p` too, whatever its +own settings say (`disableAllHooks` in a user's or a `--settings` file does not turn managed hooks off). A bare +session (`claude --bare`, `--safe-mode`, `CLAUDE_CODE_SIMPLE`) and Codex (`codex`, `codex exec`) run none of them, +so `actions-disable-guard` refuses starting one (`codex login`, `logout`, `help` and `--version` pass). This is a +command check like the others: it does not see a session started by a program the guard does not read. + +**The owner's approval.** Only the owner can let one refused command through, as root: + +```sh +sudo agent-guards approve --hours 1 # prints a one-time code; keeps only its hash, in a root-owned file +sudo agent-guards approve --revoke # ends it now +``` + +The command then carries `#owner-approved:actions-disable:`. The file is +`/etc/fork-kit/agent-guards-approval.json` (read under the machine file's rules: root-owned, not writable by group or +others, no link), at most 24 hours. An earlier draft used a session environment variable; every nested session +inherited it, so it is not read any more. Anyone who can become root without a password (sudo `NOPASSWD`, the +`docker` group) can write the file: `agent-guards self-check` warns about both for the agents' user. ## Settings (the machine file) Every key is optional. With no machine file, or no `"agent-guards"` section, each hook uses the defaults below. These are the values the hooks had before. The file is `/etc/fork-kit/machine.json` ([common/machine_file.py](../common/machine_file.py): owned by root, not writable by others, so an agent cannot -change a guard's facts). A section that is broken (a wrong type, an unknown key, a bad path) is not used: the hook -uses its defaults and writes one line on stderr. `agent-guards self-check` names the problem. A broken section -drops the extra `refuseScripts` rules too, so fix one at once. - -| Key | Default | What it is | -| ------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `actionsDisable.stateDir` | `~/.local/state/actions-disable-guard` | The refusal log (`log`) and a parse cache | -| `actionsDisable.refuseScripts` | `[]` | `{"name": "garden.py", "flag": "--fix", "why": "..."}`: also refuse running that script with that flag (a project's own tool that disables workflows) | -| `capacityPipe.commands` | `["t3-capacity"]` | The capacity checks: commands that answer OK (exit 0) or NOT OK (exit 1) | -| `memoryIndex.maxChars` | `6000` | Characters in the whole index at most | -| `memoryIndex.maxLine` | `160` | Characters in one line at most | -| `memoryIndex.stateDir` | `~/.cache/memory-index-guard` | One file per session: the index as last seen | -| `bgGuard.skipSessionsFiles` | `[]` | Files of session ids (one per line, `#` comments) that are never blocked, such as orchestrators that are woken another way | -| `bgGuard.maxBlocks` | `3` | Blocks per session at most, so a background job left on purpose never loops | -| `bgGuard.stateDir` | `~/.local/state/bg-guard` | One block count per session (raised under a lock) | -| `agentSlots.sessionsFile` | `""` (the hook does nothing) | The orchestrator session ids it acts for | -| `agentSlots.queue` | `""` | A markdown file; the ready list is the `- ` lines under `readyHeading` | -| `agentSlots.readyHeading` | `"## Ready"` | | -| `agentSlots.maxAlive` | `10` | Agent processes at most | -| `agentSlots.processName` | `"claude"` | The process name that is counted | -| `agentSlots.note` | `""` | Extra text for the context line (a build-agent limit, say) | +change a guard's facts). Each hook reads only its own part (`actionsDisable`, `capacityPipe`, ...). A key in it that +is broken (a wrong type, a bad path) keeps its default; an unknown key is ignored; a bad `refuseScripts` row is +dropped and the good rows kept. The hook says so to the agent (a `systemMessage`, and context for PreToolUse) and +on stderr. A broken or unknown part of another hook changes nothing for it. `agent-guards self-check` checks the +whole section strictly and names every problem. + +| Key | Default | What it is | +| ------------------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `actionsDisable.stateDir` | `~/.local/state/actions-disable-guard` | The refusal log (`log`) and a parse cache | +| `actionsDisable.refuseScripts` | `[]` | `{"name": "garden.py", "flag": "--fix", "why": "..."}`: also refuse running that script with that flag (a project's own tool that disables workflows) | +| `capacityPipe.commands` | `["t3-capacity"]` | The capacity checks: commands that answer OK (exit 0) or NOT OK (exit 1) | +| `memoryIndex.maxChars` | `6000` | Characters in the whole index at most | +| `memoryIndex.maxLine` | `160` | Characters in one line at most | +| `memoryIndex.stateDir` | `~/.cache/memory-index-guard` | One file per session: the index as last seen | +| `bgGuard.skipSessionsFiles` | `[]` | Files of session ids (one per line, `#` comments) that are never blocked, such as orchestrators that are woken another way | +| `bgGuard.maxBlocks` | `3` | Blocks per session at most, so a background job left on purpose never loops | +| `bgGuard.stateDir` | `~/.local/state/bg-guard` | One block count per session (raised under a lock) | +| `agentSlots.sessionsFile` | `""` (the hook does nothing) | The orchestrator session ids it acts for | +| `agentSlots.queue` | `""` | A markdown file; the ready list is the `- ` lines under `readyHeading` | +| `agentSlots.readyHeading` | `"## Ready"` | | +| `agentSlots.maxAlive` | `10` | Agent processes at most | +| `agentSlots.processName` | `"claude"` | The process name that is counted | +| `agentSlots.note` | `""` | Extra text for the context line (a build-agent limit, say) | Paths are absolute or start with `~/` (the home of the user the hook runs as). An example is in [machine.example.json](../common/machine.example.json). @@ -93,7 +118,13 @@ again and to stop at any step. reads it, and only root can change it. It is written after the links, so every hook it names is there. Sessions already running keep the hooks they started with. `--no-settings` removes it; the choice is kept, so a run with neither keeps the last one (a first install: no drop-in). The installer refuses to overwrite a drop-in of that name -it did not write. Uninstall removes the drop-in first, then the hooks. +it did not write. + +Uninstall refuses while a settings file the kit did not write (a user's `~/.claude/settings.json`, say) still names +a hook: removing the file would make that entry fail. Otherwise it removes the drop-in first, then refuses while a +Claude Code session started before that still runs (it has the hooks loaded); run it again when those have ended. +To take the hooks out of new sessions at once and keep the files, run the installer with `--no-settings` (the +rollback). Without `--settings`, put the entries in a settings file by hand: `agent-guards hooks` prints the `"hooks"` object. A hook that is in both the drop-in and a user's settings runs twice. That is harmless for the refusing hooks, but @@ -102,7 +133,7 @@ A hook that is in both the drop-in and a user's settings runs twice. That is har ## Check ```sh -agent-guards self-check # the machine file section, the hook files, the drop-in +agent-guards self-check # the machine file section, the hook files and links, the drop-in, an open approval, ways to root agent-guards check # run every hook wired in the drop-in: one case it must refuse, one it must pass agent-guards check --settings ~/.claude/settings.json # the same for hooks wired in any settings file agent-guards-install self-check # the installed files are the ones the installer wrote @@ -110,8 +141,10 @@ agent-guards-install self-check # the installed files are the ones `check` runs each wired command the way Claude Code does (`/bin/sh -c`, the event on stdin) and prints PASS or FAIL for each case, and MISSING for a hook that is not wired. It changes nothing on the machine: the memory index and the -sessions are made up in a temporary folder, and their state files are removed afterwards. For `bg-guard` it starts a -`sleep` in the background under a stand-in parent named `claude`. +sessions are made up in a temporary folder, the hooks run with `HOME` there (their logs and caches go with it), and +the state files in configured folders are removed afterwards. For `bg-guard` it starts a `sleep` in the background +under a stand-in parent named `claude`. As root, `check --settings FILE` reads the file only when it is safe to run +what it names: root-owned, not writable by group or others, no link on the way. ## General vs project diff --git a/fork-kit/agent-guards/bin/actions-disable-guard b/fork-kit/agent-guards/bin/actions-disable-guard index 038ecd9fa670b..2979f9aeb4984 100755 --- a/fork-kit/agent-guards/bin/actions-disable-guard +++ b/fork-kit/agent-guards/bin/actions-disable-guard @@ -113,18 +113,28 @@ A guarded call only in a script 4 or more levels deep (a.sh -> b.sh -> c.sh -> d unless other text in the command flows on. gh has no request hook, so this hook is the command-text layer; the wall is a token that cannot do it. -Escape hatch (owner only, by hand): start the Claude Code session with - CLAUDE_GUARD_OWNER_ALLOW_ACTIONS_DISABLE=$(date -u +%F) claude -and put #owner-approved:actions-disable in the command. The value must be today's UTC date (a stale export opens -nothing); a command prefix or `export` in the Bash tool never reaches this hook; the variable in any settings file -is refused (an agent could write those). Fails closed: an internal error refuses commands that look dangerous. +Escape hatch (owner only, as root): `sudo agent-guards approve [--hours N]` prints a one-time code and keeps its +hash in a root-owned file (lib/agent_guards/approval.py); a command that carries + #owner-approved:actions-disable: +passes while that file holds the code and its time (1 hour by default) has not run out. An agent cannot write the +file, so it cannot approve itself, and nothing is inherited: a nested session gets the code only when it is in its +command. (The old CLAUDE_GUARD_OWNER_ALLOW_ACTIONS_DISABLE variable opens nothing any more: a variable reaches +every nested `claude -p` or `codex exec` of the session.) Fails closed: an internal error refuses commands that +look dangerous. + +Nested agents: a command that starts an agent session this machine's hooks do not reach is refused, since that +session could do what this guard refuses: `claude --bare` / `--safe-mode`, `claude` with CLAUDE_CODE_SIMPLE set in +the same command, and `codex` with anything but login/logout/help/completion/--version (codex runs no Claude Code +hooks). A nested `claude -p` passes: managed hooks run there too, also with `--settings '{"disableAllHooks": +true}'` (settings outside managed settings cannot turn managed hooks off). Not covered: other agent programs, and +an agent started by a program the guard does not read (a Python script, a container). Facts from the machine file (fork-kit/agent-guards/README.md): actionsDisable.stateDir (cache and log of refusals, default ~/.local/state/actions-disable-guard) and actionsDisable.refuseScripts (default none). A missing machine file or section gives those defaults; a broken one too, with one line on stderr: the guard never weakens. Tests: fork-kit/agent-guards/tests/actions-disable.test.py """ -import datetime as dt, fnmatch, glob, itertools, json, os, re, signal, sys, time +import fnmatch, itertools, json, os, re, signal, sys, time from stat import S_ISDIR, S_ISREG from urllib.parse import unquote @@ -144,7 +154,7 @@ def _settings(): SETTINGS, SETTINGS_PROBLEM = _settings() REFUSE_SCRIPTS = tuple(SETTINGS['refuseScripts']) -MARK_ENV, MARK_CMD = 'CLAUDE_GUARD_OWNER_ALLOW_ACTIONS_DISABLE', '#owner-approved:actions-disable' +MARK_CMD = '#owner-approved:actions-disable:' # + the owner's code (agent_guards.approval) # Marks inside a word (private-use characters; the same characters in a command read as hidden text too): HID = '' # text the guard cannot know, as one piece of this word WILD = '' # text the guard cannot know that may be no word at all, or several ("$@", unquoted $X, {a,b}) @@ -153,7 +163,9 @@ PERM_RE = re.compile(r'actions/permissions(?![\w-])', re.I) PROTECT_RE = re.compile(r'branches/[^\s?#]+?/protection(?![\w-])|(? in its environment and the command then carries ' - f'{MARK_CMD}. Agents must not set that variable (command prefix, export, settings file or anywhere else), ' - 'add the marker on their own, or route around this guard with scripts, aliases or other HTTP clients.') + 'it: they run `sudo agent-guards approve` and give you a code, and the command then carries ' + f'{MARK_CMD}. Agents must not make up a code, reuse one they were not given for this, start an agent ' + 'session without this machine\'s hooks, or route around this guard with scripts, aliases or other HTTP ' + 'clients.') UNREADABLE = ('If this call is harmless, write it so the guard can read it: the path and the flags spelled out in ' 'the command, variables only for ids and only inside quotes.') @@ -1387,10 +1400,10 @@ def api_reason(args, ctx, top=False): return reason(f'{how} `gh api` to branch protection or a ruleset: a DELETE there removes the rules ' 'that keep `main` behind CI and review (changing them with PUT/PATCH/POST is not ' 'refused)', '' if exact and eff == 'DELETE' else UNREADABLE) - if best['ruleset'] and (any(re.fullmatch(r'enforcement=(disabled|.*[%s%s].*)' % (HID, WILD), f, re.S) - for f in fields) - or any(RULESET_OFF.search(x) for x in seen)): - return reason(f'{how} `gh api` that switches a ruleset off (enforcement=disabled)') + if best['ruleset'] and (any(re.fullmatch(r'enforcement=(disabled|evaluate|.*[%s%s].*)' % (HID, WILD), f, + re.S | re.I) for f in fields) + or any(RULESET_OFF.search(canon(x, cue=False)) for x in list(args) + bodies)): + return reason(f'{how} `gh api` that switches a ruleset off (enforcement=disabled or evaluate)') if best['ruleset'] and unread: return reason(f'{how} `gh api` to a ruleset with a body the guard cannot read (a pipe, a file that is ' 'not there yet, a file named by a variable): it may switch the ruleset off', @@ -1401,8 +1414,9 @@ def api_reason(args, ctx, top=False): gql = any(may_be_graphql(a) for a in pos) if exact else path is None or may_be_graphql(path) if gql and any(GQL_RE.search(x) for x in seen): return reason('a GraphQL mutation that deletes branch protection or a ruleset') - if gql and any(GQL_UPDATE.search(x) for x in seen) and (unread or any('disabled' in x for x in seen)): - return reason('a GraphQL updateRepositoryRuleset that switches the ruleset off (enforcement: DISABLED), ' + if gql and any(GQL_UPDATE.search(x) for x in seen) and (unread or any(OFF_WORD.search(x) for x in seen)): + return reason('a GraphQL updateRepositoryRuleset that switches the ruleset off (enforcement: DISABLED ' + 'or EVALUATE), ' 'or one with a body the guard cannot read') if gql and unread: return reason('a GraphQL call with a body the guard cannot read (a pipe, a file that is not there yet, ' @@ -1451,9 +1465,10 @@ def net_reason(word, args, ctx): if best['ruleset']: # a body that switches the ruleset off, written out or in a file (-d @file) files = [m.group(1) for a in args for m in [re.search(r'@([^@=\s]+)$', a)] if m and a not in paths] texts = [read_named(f, ctx) for f in files] - if any(t is None or RULESET_OFF.search(canon(t)) for t in texts) \ - or any(RULESET_OFF.search(canon(a)) for a in args): - return reason('a request that switches a ruleset off (enforcement=disabled), or one to a ruleset with a ' + if any(t is None or RULESET_OFF.search(canon(t, cue=False)) for t in texts) \ + or any(RULESET_OFF.search(canon(a, cue=False)) for a in args): + return reason('a request that switches a ruleset off (enforcement=disabled or evaluate), or one to a ' + 'ruleset with a ' 'body file the guard cannot read') return None @@ -2213,10 +2228,11 @@ def _unescape(m): return m.group(0) -def canon(text, blank=True): +def canon(text, blank=True, cue=True): """Text as the program at the far end may read it: \\uXXXX, \\xXX, octal and %XX decoded (up to three rounds), backslashes and all quotes dropped (blank: \\n \\t \\r read as a blank first), 'a' + 'b' joined, lower case, - /./ // and /x/../ in paths resolved. '' when no guarded word is left at all.""" + /./ // and /x/../ in paths resolved. '' when no guarded word is left at all (cue=False: the text all the same, + for a ruleset body, where `"enforcement": "evaluate"` holds no guarded word).""" s = text if '\\' in s or '%' in s: for _ in range(3): @@ -2229,7 +2245,7 @@ def canon(text, blank=True): s = s.replace('\\', '') s = re.sub(r'["\']\s*[+.]\s*["\']', '', s) s = re.sub(r'["\'`]', '', s).lower() - if not any(c in s for c in CUES): + if cue and not any(c in s for c in CUES): return '' s = re.sub(r'(? 0 else 'an owner approval file is there, its time is over') + user = os.environ.get('SUDO_USER') or pwd.getpwuid(os.getuid()).pw_name + if user == 'root': + notes.append('run the self-check as the agents\' user, or through sudo, to see whether that user can become ' + 'root without the owner') + for way in root_ways(user) if user != 'root' else (): + notes.append(f'WARNING: {way}: an agent of that user can become root, and then write the managed settings, ' + 'the machine file and the approval file; the hooks do not hold against it') for hook, s in settings.items(): notes.append(f'{hook}: {json.dumps(s, sort_keys=True)}') for n in notes: @@ -58,20 +109,65 @@ def main(argv): c.add_argument('--settings', default=wiring.DROP_IN) h = sub.add_parser('hooks') h.add_argument('--bin', default=wiring.BIN) + p = sub.add_parser('approve') + p.add_argument('--hours', type=float, default=1.0) + p.add_argument('--revoke', action='store_true') a = ap.parse_args(argv) if a.cmd == 'self-check': return self_check(os.path.dirname(os.path.realpath(__file__)), wiring.DROP_IN) if a.cmd == 'hooks': print(json.dumps({'hooks': wiring.hooks(a.bin)}, indent=2)) return 0 + if a.cmd == 'approve': + return approve(a) try: - with open(a.settings, encoding='utf-8') as f: - settings = json.load(f) + settings = json.loads(read_settings(a.settings)) except (OSError, ValueError) as e: print(f'{PROG}: cannot read {a.settings} ({e})', file=sys.stderr) return 1 return check.run(settings, a.settings) +def read_settings(path): + """The text of a settings file whose commands `check` runs. As root only a file root owns, that only root can + write, in folders only root can write (else anyone who can write it runs commands as root).""" + if os.geteuid() != ROOT_UID: + with open(path, encoding='utf-8') as f: + return f.read() + from agent_guards import approval # noqa: F401 - puts fork-kit/common on the path + import machine_file + try: + return machine_file.read_protected_text(os.path.abspath(path), ROOT_UID) + except machine_file.MachineFileError as e: + raise OSError(f'not safe to run as root: {e}') from None + + +def approve(a): + from agent_guards import approval + if os.geteuid() != ROOT_UID: + print(f'{PROG} approve: run this as root (sudo {PROG} approve): only root can write the approval', + file=sys.stderr) + return 1 + if a.revoke: + print(f'{PROG}: approval removed' if approval.revoke() else f'{PROG}: there was no approval') + return 0 + if not 0 < a.hours <= approval.MAX_HOURS: + print(f'{PROG} approve: --hours must be above 0 and at most {approval.MAX_HOURS}', file=sys.stderr) + return 1 + code = approval.new_code() + try: + data = approval.write(code, a.hours) + except OSError as e: + print(f'{PROG} approve: cannot write {approval.PATH} ({e})', file=sys.stderr) + return 1 + import time + until = time.strftime('%Y-%m-%d %H:%M UTC', time.gmtime(data['until'])) + print(f'Approved until {until}. Give the agent this marker for the one command you approve:\n' + f' {approval.MARK}{code}\n' + f'Every command carrying it passes actions-disable-guard until then; end it early with ' + f'`sudo {PROG} approve --revoke`.') + return 0 + + if __name__ == '__main__': sys.exit(main(sys.argv[1:])) diff --git a/fork-kit/agent-guards/bin/agent-slots b/fork-kit/agent-guards/bin/agent-slots index b7fdd078ef6ff..549ff2a6865ac 100755 --- a/fork-kit/agent-guards/bin/agent-slots +++ b/fork-kit/agent-guards/bin/agent-slots @@ -17,6 +17,8 @@ one line on stderr. Tests: fork-kit/agent-guards/tests/agent-slots.test.py """ import json, os, subprocess, sys +NAME = 'agent-slots' + def _settings(): """(agentSlots settings, problem or None); a copy without the kit's lib keeps the defaults and says so.""" @@ -76,18 +78,38 @@ def decide(data, c): return None +def _notice(problem, event, out): + """`out` with a config problem added where the agent and the owner see it (and one line on stderr).""" + if not problem: + return out + try: + from agent_guards import config + config.warn(NAME, problem) + return config.notice(NAME, problem, event, out) + except BaseException: # noqa: BLE001 - no lib: say it plainly + text = f'{NAME}: {problem}; built-in defaults used. Tell the owner.' + try: + sys.stderr.write(text + '\n') + except Exception: # noqa: BLE001 + pass + return dict(out or {}, systemMessage=text) + + def main(): if sys.argv[1:]: sys.stderr.write('usage: agent-slots (hook: UserPromptSubmit or Stop JSON on stdin)\n') return 1 + event, problem = None, None try: c, problem = _settings() - if problem: - sys.stderr.write('agent-slots: the machine file\'s "agent-guards" section cannot be used ' - f'({problem}); built-in defaults used. Run `agent-guards self-check`.\n') - out = decide(json.load(sys.stdin), c) + event = json.load(sys.stdin) + out = decide(event, c) except Exception: # never break a call because of this hook - return 0 + out = None + try: + out = _notice(problem, event, out) + except Exception: # noqa: BLE001 + pass if out: print(json.dumps(out)) return 0 diff --git a/fork-kit/agent-guards/bin/bg-guard b/fork-kit/agent-guards/bin/bg-guard index aec0837259714..cd969f24e605a 100755 --- a/fork-kit/agent-guards/bin/bg-guard +++ b/fork-kit/agent-guards/bin/bg-guard @@ -19,6 +19,7 @@ import fcntl, json, os, sys CLAUDE = 'claude' # Claude Code's process name SNAPSHOT = 'shell-snapshots/snapshot-' # in the command line of each of its Bash tool commands +NAME = 'bg-guard' def _settings(): @@ -129,18 +130,38 @@ def decide(data, c, start_pid): 'and stop again.'} +def _notice(problem, event, out): + """`out` with a config problem added where the agent and the owner see it (and one line on stderr).""" + if not problem: + return out + try: + from agent_guards import config + config.warn(NAME, problem) + return config.notice(NAME, problem, event, out) + except BaseException: # noqa: BLE001 - no lib: say it plainly + text = f'{NAME}: {problem}; built-in defaults used. Tell the owner.' + try: + sys.stderr.write(text + '\n') + except Exception: # noqa: BLE001 + pass + return dict(out or {}, systemMessage=text) + + def main(): if sys.argv[1:]: sys.stderr.write('usage: bg-guard (hook: Stop JSON on stdin)\n') return 1 + event, problem = None, None try: c, problem = _settings() - if problem: - sys.stderr.write('bg-guard: the machine file\'s "agent-guards" section cannot be used ' - f'({problem}); built-in defaults used. Run `agent-guards self-check`.\n') - out = decide(json.load(sys.stdin), c, os.getppid()) + event = json.load(sys.stdin) + out = decide(event, c, os.getppid()) except Exception: # never break a stop because of this guard - return 0 + out = None + try: + out = _notice(problem, event, out) + except Exception: # noqa: BLE001 + pass if out: print(json.dumps(out)) return 0 diff --git a/fork-kit/agent-guards/bin/capacity-pipe-guard b/fork-kit/agent-guards/bin/capacity-pipe-guard index 1a9676be376a0..c9fc09c67bbbd 100755 --- a/fork-kit/agent-guards/bin/capacity-pipe-guard +++ b/fork-kit/agent-guards/bin/capacity-pipe-guard @@ -327,24 +327,50 @@ def main(argv=None): if argv: sys.stderr.write(f'usage: {NAME} (hook: PreToolUse JSON on stdin; its settings entry: `agent-guards hooks`)\n') return 1 + event = None try: - if SETTINGS_PROBLEM: - sys.stderr.write(f'{NAME}: the machine file\'s "agent-guards" section cannot be used ({SETTINGS_PROBLEM}); ' - 'built-in defaults used. Run `agent-guards self-check`.\n') event = json.loads(sys.stdin.read()) - if event.get('tool_name') not in TOOLS: - return 0 - command = (event.get('tool_input') or {}).get('command') - tool = piped(command) if isinstance(command, str) else None + tool = None + if event.get('tool_name') in TOOLS: + command = (event.get('tool_input') or {}).get('command') + tool = piped(command) if isinstance(command, str) else None if not tool: + _say_problem(event) return 0 except BaseException as e: # fail open: this guards a mistake, not an attack sys.stderr.write(f'{NAME}: failed ({type(e).__name__}: {e}); the command is NOT checked and runs. ' 'Tell the owner if this repeats.\n') return 1 sys.stderr.write(reason(tool) + '\n') + if SETTINGS_PROBLEM: # exit 2: stderr is what the agent reads + sys.stderr.write(_problem_text() + '\n') return 2 +def _problem_text(): + try: + from agent_guards import config + return config.problem_text(NAME, SETTINGS_PROBLEM) + except BaseException: # noqa: BLE001 - no lib + return f'{NAME}: {SETTINGS_PROBLEM}; built-in defaults used. Tell the owner.' + + +def _say_problem(event): + """A config problem, where the agent and the owner see it (the call runs: exit 0 with an answer).""" + if not SETTINGS_PROBLEM: + return + text = _problem_text() + try: + sys.stderr.write(text + '\n') + except Exception: # noqa: BLE001 + pass + try: + from agent_guards import config + out = config.notice(NAME, SETTINGS_PROBLEM, event, None) + except BaseException: # noqa: BLE001 + out = {'systemMessage': text} + print(json.dumps(out)) + + if __name__ == '__main__': sys.exit(main()) diff --git a/fork-kit/agent-guards/bin/memory-index-guard b/fork-kit/agent-guards/bin/memory-index-guard index 68c1f05bdad00..3cb9132abed17 100755 --- a/fork-kit/agent-guards/bin/memory-index-guard +++ b/fork-kit/agent-guards/bin/memory-index-guard @@ -32,6 +32,7 @@ def _settings(): SETTINGS, SETTINGS_PROBLEM = _settings() +NAME = 'memory-index-guard' MAX_CHARS = SETTINGS['maxChars'] MAX_LINE = SETTINGS['maxLine'] STATE = SETTINGS['stateDir'] @@ -164,22 +165,38 @@ def post(data): return {'decision': 'block', 'reason': message(idx, probs)} +def _notice(problem, event, out): + """`out` with a config problem added where the agent and the owner see it (and one line on stderr).""" + if not problem: + return out + try: + from agent_guards import config + config.warn(NAME, problem) + return config.notice(NAME, problem, event, out) + except BaseException: # noqa: BLE001 - no lib: say it plainly + text = f'{NAME}: {problem}; built-in defaults used. Tell the owner.' + try: + sys.stderr.write(text + '\n') + except Exception: # noqa: BLE001 + pass + return dict(out or {}, systemMessage=text) + + def main(): if sys.argv[1:]: sys.stderr.write('usage: memory-index-guard (hook: PreToolUse or PostToolUse JSON on stdin)\n') return 1 - if SETTINGS_PROBLEM: - try: - sys.stderr.write('memory-index-guard: the machine file\'s "agent-guards" section cannot be used ' - f'({SETTINGS_PROBLEM}); built-in defaults used. Run `agent-guards self-check`.\n') - except Exception: # noqa: BLE001 - pass + data = None try: data = json.load(sys.stdin) ev = data.get('hook_event_name') out = pre(data) if ev == 'PreToolUse' else post(data) if ev == 'PostToolUse' else None except Exception: # never break a tool call because of this guard - return 0 + out = None + try: + out = _notice(SETTINGS_PROBLEM, data, out) + except Exception: # noqa: BLE001 + pass if out: print(json.dumps(out)) return 0 diff --git a/fork-kit/agent-guards/lib/agent_guards/approval.py b/fork-kit/agent-guards/lib/agent_guards/approval.py new file mode 100644 index 0000000000000..e08ba74da451b --- /dev/null +++ b/fork-kit/agent-guards/lib/agent_guards/approval.py @@ -0,0 +1,113 @@ +"""agent_guards.approval: the owner's approval for one actions-disable-guard refusal, as a root-owned file. + +The owner (root) runs `sudo agent-guards approve [--hours N]`. That makes a random code, prints it once, and keeps +only its SHA-256 and an end time in PATH (root-owned, mode 0644, written whole and renamed into place). A command +that carries `#owner-approved:actions-disable:` passes the guard while the file holds that code's hash and +the end time has not come. `sudo agent-guards approve --revoke` removes the file. + +Why a file and not an environment variable: a variable set when a session starts is inherited by every process of +that session, a nested `claude -p` or `codex exec` too, so an approval meant for one command reached every agent +started under it. The code reaches an agent only when the owner hands it over, and an agent cannot write the file +(it is root's, in a root-owned folder), so it cannot approve itself. Who can become root without a password (sudo +NOPASSWD, the docker group) can write it: `agent-guards self-check` warns about that. + +The file is read under the machine file's rules (fork-kit/common/machine_file.py: every folder on the way and the +file root-owned, not writable by group or others, no link). Anything wrong with it (not there, bad owner, bad JSON, +an old version, the time over) is no approval: the guard refuses as it would without one. Plain Python 3. +""" +import base64, datetime as dt, hashlib, hmac, json, os, re, secrets, sys, tempfile + +_kit = os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))) +_common = os.path.join(_kit, 'common') +sys.path.insert(0, _common if os.path.isfile(os.path.join(_common, 'machine_file.py')) + else os.path.join(os.path.dirname(_kit), 'common')) +import machine_file # noqa: E402 + +PATH = '/etc/fork-kit/agent-guards-approval.json' +OWNER_UID = 0 # tests only +VERSION = 1 +MARK = '#owner-approved:actions-disable:' +CODE_RE = re.compile(r'#owner-approved:actions-disable:([a-z2-7]{20})(?![A-Za-z0-9])') +MAX_HOURS = 24 + + +def _hash(code): + return hashlib.sha256(code.encode('ascii')).hexdigest() + + +def _now(now): + return now if now is not None else dt.datetime.now(dt.timezone.utc).timestamp() + + +def read(path=None, owner_uid=None): + """The approval record {"version", "sha256", "until"}, or (None, why not).""" + path = path or PATH + try: + text = machine_file.read_protected_text(path, OWNER_UID if owner_uid is None else owner_uid) + data = json.loads(text) + except machine_file.MachineFileError as e: + return None, str(e) + except ValueError as e: + return None, f'{path}: not valid JSON ({e})' + if not isinstance(data, dict) or data.get('version') != VERSION or set(data) != {'version', 'sha256', 'until'} \ + or not isinstance(data['sha256'], str) or not re.fullmatch(r'[0-9a-f]{64}', data['sha256']) \ + or type(data['until']) not in (int, float): + return None, f'{path}: not an approval file of this kit (version {VERSION})' + return data, None + + +def approved(cmd, now=None): + """(True, None) when the command carries the code of a valid approval; else (False, why not or None when the + command carries no code at all).""" + codes = CODE_RE.findall(cmd or '') if isinstance(cmd, str) else [] + if not codes: + return False, None + data, why = read() + if data is None: + return False, why + if _now(now) >= data['until']: + return False, 'the approval is over (its time has passed)' + if any(hmac.compare_digest(_hash(c), data['sha256']) for c in codes): + return True, None + return False, 'the code in the command is not the one the owner approved' + + +def new_code(): + """About 100 random bits as 20 letters a-z and digits 2-7 (easy to read out and type).""" + return base64.b32encode(secrets.token_bytes(15)).decode('ascii').lower()[:20] + + +def write(code, hours, path=None, now=None): + """Write the approval for `code`, ending in `hours`, atomically (temp file in the same folder, then rename).""" + if not (0 < hours <= MAX_HOURS): + raise ValueError(f'--hours must be above 0 and at most {MAX_HOURS}') + path = path or PATH + folder = os.path.dirname(path) + if not os.path.isdir(folder): + os.makedirs(folder, 0o755, exist_ok=True) + data = {'version': VERSION, 'sha256': _hash(code), 'until': int(_now(now) + hours * 3600)} + fd, tmp = tempfile.mkstemp(prefix='.agent-guards-approval.', dir=folder) + try: + with os.fdopen(fd, 'w', encoding='utf-8') as f: + json.dump(data, f) + f.write('\n') + f.flush() + os.fsync(f.fileno()) + os.chmod(tmp, 0o644) + os.replace(tmp, path) + except BaseException: + try: + os.unlink(tmp) + except OSError: + pass + raise + return data + + +def revoke(path=None): + """Remove the approval file; True when there was one.""" + try: + os.unlink(path or PATH) + return True + except FileNotFoundError: + return False diff --git a/fork-kit/agent-guards/lib/agent_guards/check.py b/fork-kit/agent-guards/lib/agent_guards/check.py index a3f50d691d6cb..6a2762b03ecbe 100644 --- a/fork-kit/agent-guards/lib/agent_guards/check.py +++ b/fork-kit/agent-guards/lib/agent_guards/check.py @@ -1,7 +1,10 @@ """agent_guards.check: prove the wired hooks work. Each hook's command, as a settings file has it, is run with one event it must refuse (block) and one it must let through, the way Claude Code runs it (`/bin/sh -c COMMAND`, the -event on stdin). Nothing of the machine is changed: the memory index and the session ids are made up in a temporary -folder, and the few state files the hooks write for those made-up sessions are removed afterwards. +event on stdin), and the entry's matcher must take the case's tool (Bash, Monitor, Write). Nothing of the machine is +changed: the memory index and the session ids are made up in a temporary folder, the hooks run with HOME there (so +the "~/" state folders, the refusal log and the cache are written there and removed with it; agent-slots keeps the +real HOME, it writes nothing), and the state files a hook writes in a configured absolute folder for those made-up +sessions are removed afterwards. A hook that is not wired is reported as MISSING (a problem); agent-slots with no sessionsFile only gets its pass case (it does nothing for any session then). @@ -49,7 +52,9 @@ def _answer(r): return 'refused' if r.returncode != 0: return f'failed (exit {r.returncode})' - return 'context' if spec.get('additionalContext') else 'passed' + ctx = spec.get('additionalContext') + # a hook that only says its machine file section is broken (config.notice) passed: the self-check names that + return 'context' if ctx and ctx != out.get('systemMessage') else 'passed' def _remove(path): @@ -91,6 +96,8 @@ def write(content): out = [ ('actions-disable-guard', 'PreToolUse', 'gh workflow disable', bash('gh workflow disable 1 -R example/example'), 'refused', None), + ('actions-disable-guard', 'PreToolUse', 'the same in a Monitor', + dict(bash('gh workflow disable 1 -R example/example'), tool_name='Monitor'), 'refused', None), ('actions-disable-guard', 'PreToolUse', 'echo that only mentions it', bash("echo 'gh workflow disable 1 is refused'"), 'passed', None), ('capacity-pipe-guard', 'PreToolUse', f'{cap} piped', bash(f'{cap} 2048 | tail -1 && true'), 'refused', None), @@ -100,6 +107,8 @@ def write(content): ('memory-index-guard', 'PreToolUse', 'Write of a small index', write('- [a](a.md) - ok\n'), 'passed', None), ('memory-index-guard', 'PostToolUse', 'index over budget, changed', post, 'refused', None), ('memory-index-guard', 'PostToolUse', 'same index again (seen)', post, 'passed', None), + ('memory-index-guard', 'PostToolUse', 'same index after a Monitor (seen)', dict(post, tool_name='Monitor'), + 'passed', None), ('bg-guard', 'Stop', 'stop with a background command running', {'hook_event_name': 'Stop', 'session_id': sid}, 'refused', 'claude'), ('bg-guard', 'Stop', 'stop with none', {'hook_event_name': 'Stop', 'session_id': sid}, 'passed', 'idle'), @@ -139,20 +148,24 @@ def run(settings, source, say=print): bad = 0 try: fake, scripts = _fake_claude(tmp) + home = os.path.join(tmp, 'home') + os.makedirs(home) missing = set() for hook, event, label, ev, want, how in cases(tmp, sid): - cmd = wiring.find(settings, hook, event) + tool = ev.get('tool_name') if event.endswith('ToolUse') else None + cmd = wiring.find(settings, hook, event, tool) if cmd is None: - if (hook, event) not in missing: - missing.add((hook, event)) + if (hook, event, tool) not in missing: + missing.add((hook, event, tool)) bad += 1 - say(f'MISSING {hook} ({event}): not wired in {source}') + say(f'MISSING {hook} ({event}{", " + tool if tool else ""}): not wired in {source}') continue + env = dict(os.environ, HOME=home) if hook != 'agent-slots' else dict(os.environ) if how: - env = dict(os.environ, AG_EVENT=json.dumps(ev), AG_HOOK=cmd) + env.update(AG_EVENT=json.dumps(ev), AG_HOOK=cmd) r = _run(cmd, ev, tmp, env=env, argv=[fake, '-c', scripts[how]]) else: - r = _run(cmd, ev, tmp) + r = _run(cmd, ev, tmp, env=env) got = _answer(r) ok = got == want bad += not ok diff --git a/fork-kit/agent-guards/lib/agent_guards/config.py b/fork-kit/agent-guards/lib/agent_guards/config.py index f2049d89c2f19..1c031bf964836 100644 --- a/fork-kit/agent-guards/lib/agent_guards/config.py +++ b/fork-kit/agent-guards/lib/agent_guards/config.py @@ -1,8 +1,11 @@ """agent_guards.config: the facts of the agent guard hooks, from the machine file's "agent-guards" section. Every key is optional; a missing machine file or section gives the built-in defaults below (the values the hooks -had before they moved into this kit). A broken file or section never weakens a guard below those defaults: the hook -uses them and names the problem on stderr (`agent-guards self-check` names it too). +had before they moved into this kit). Each hook reads only its own part, key by key: a top-level key no hook knows +(a later kit's section) or another hook's broken part changes nothing for it; a bad key of its own keeps that key's +default, an unknown key of its own is ignored, a bad refuseScripts row is left out (each of these is named). A broken file never weakens a guard below the defaults: the hook uses them and names the problem in its +answer (systemMessage, and additionalContext where the event takes it) and on stderr. `agent-guards self-check` +names every problem, unknown keys too. "agent-guards": { "actionsDisable": {"stateDir": "~/.local/state/actions-disable-guard", @@ -61,13 +64,9 @@ def _commands(value): def _scripts(value): for k, v in enumerate(value): - if not isinstance(v, dict) or set(v) - {'name', 'flag', 'why'} or not isinstance(v.get('name'), str) \ - or not isinstance(v.get('flag'), str) or not isinstance(v.get('why', ''), str): - return f'entry {k} must be {{"name": "", "flag": "", "why": ""}}' - if not re.match(r'^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$', v['name']) or not re.sub(r'[^a-z0-9]', '', os.path.splitext(v['name'])[0].lower()): - return f'entry {k}: "name" must be a plain file name, not {v["name"]!r}' - if not re.match(r'^-{1,2}[A-Za-z0-9][A-Za-z0-9-]*$', v['flag']): - return f'entry {k}: "flag" must be one option like --fix, not {v["flag"]!r}' + p = _row_problem(k, v) + if p: + return p return None @@ -105,27 +104,85 @@ def defaults(hook): return {k: copy.deepcopy(d) for k, (_t, d, _c) in SPEC[hook].items()} -def load(hook): - """(settings of one hook with defaults filled in, problem text or None). Never raises.""" +def _row_problem(k, v): + """The problem of one refuseScripts row, or None.""" + if not isinstance(v, dict) or set(v) - {'name', 'flag', 'why'} or not isinstance(v.get('name'), str) \ + or not isinstance(v.get('flag'), str) or not isinstance(v.get('why', ''), str): + return f'entry {k} must be {{"name": "", "flag": "", "why": ""}}' + if not re.match(r'^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$', v['name']) \ + or not re.sub(r'[^a-z0-9]', '', os.path.splitext(v['name'])[0].lower()): + return f'entry {k}: "name" must be a plain file name, not {v["name"]!r}' + if not re.match(r'^-{1,2}[A-Za-z0-9][A-Za-z0-9-]*$', v['flag']): + return f'entry {k}: "flag" must be one option like --fix, not {v["flag"]!r}' + return None + + +def _own(section, hook): + """(settings, [problems]) of one hook from its own part of the section. Each key is checked on its own: a bad + key keeps its built-in default (and is named), the others keep their values; a bad refuseScripts row is dropped + (and named), the good rows stay. An unknown key of its own part (a typo, or a newer kit's key) is named and + ignored.""" + out, problems = defaults(hook), [] + where = f'{KIT}.{hook}' + part = section.get(hook, {}) + if not isinstance(part, dict): + return out, [f'{where}: must be a JSON object (built-in defaults used)'] + for key, value in part.items(): + if key not in SPEC[hook]: + problems.append(f'{where}: unknown key {key!r} (ignored; known: {", ".join(sorted(SPEC[hook]))})') + continue + if key == 'refuseScripts' and isinstance(value, list): + rows = [] + for k, row in enumerate(value): + p = _row_problem(k, row) + if p: + problems.append(f'{where}.refuseScripts: {p} (that entry is left out)') + else: + rows.append(row) + out[key] = rows + continue + try: + out[key] = machine_file.fields({key: value}, {key: SPEC[hook][key]}, where)[key] + except machine_file.MachineFileError as e: + problems.append(f'{e} (built-in default used)') + return out, problems + + +def _section(): + """(section or None, problem or None). Never raises.""" try: - section = machine_file.read_section(KIT, MACHINE_PATH, OWNER_UID, optional=True) - if section is None: - return defaults(hook), None - machine_file.fields(section, {h: (dict, {}, None) for h in HOOKS}, KIT) - return machine_file.fields(section.get(hook, {}), SPEC[hook], f'{KIT}.{hook}'), None + return machine_file.read_section(KIT, MACHINE_PATH, OWNER_UID, optional=True), None except machine_file.MachineFileError as e: - return defaults(hook), str(e) + return None, str(e) except Exception as e: # noqa: BLE001 - a guard keeps its defaults whatever the file holds + return None, f'{type(e).__name__}: {e}' + + +def load(hook): + """(settings of one hook with defaults filled in, problem text or None). Never raises. A hook reads only its + own part: another hook's part, or a key no hook knows (a later kit's), never changes what it gets.""" + section, problem = _section() + if section is None: + return defaults(hook), problem + try: + out, problems = _own(section, hook) + except Exception as e: # noqa: BLE001 return defaults(hook), f'{type(e).__name__}: {e}' + return out, '; '.join(problems) or None def load_all(): - """{hook: settings}, [problems]: for the self-check.""" + """{hook: settings}, [problems]: for the self-check, which is strict: it also names keys no hook knows.""" + section, problem = _section() + if section is None: + return {h: defaults(h) for h in HOOKS}, [problem] if problem else [] out, problems = {}, [] + for key in section: + if key not in SPEC: + problems.append(f'{KIT}: unknown key {key!r} (ignored by every hook; known: {", ".join(HOOKS)})') for hook in HOOKS: - out[hook], p = load(hook) - if p and p not in problems: - problems.append(p) + out[hook], p = _own(section, hook) + problems += p return out, problems @@ -136,11 +193,35 @@ def expand(path, home=None): return path +def problem_text(name, problem): + """The one line that says a hook runs on (some of) its built-in defaults.""" + return (f'{name}: the machine file\'s "{KIT}" section cannot be used as written ({problem}); built-in defaults ' + 'used for that part. Tell the owner; `agent-guards self-check` names every problem.') + + +def notice(name, problem, event, out=None): + """The hook's answer `out` (a dict or None) with the config problem added where the agent and the owner see + it: systemMessage (shown in the session), and for the events that take it, additionalContext (read by the + agent); a block reason gets it appended. None when there is nothing to say.""" + if not problem: + return out + text = problem_text(name, problem) + out = dict(out or {}) + out['systemMessage'] = (out['systemMessage'] + ' ' + text) if out.get('systemMessage') else text + if out.get('decision') == 'block' and isinstance(out.get('reason'), str): + out['reason'] += ' (' + text + ')' + ev = (event or {}).get('hook_event_name') if isinstance(event, dict) else None + if ev in ('PreToolUse', 'PostToolUse', 'UserPromptSubmit'): + hso = dict(out.get('hookSpecificOutput') or {}, hookEventName=ev) + hso['additionalContext'] = (hso['additionalContext'] + ' ' + text) if hso.get('additionalContext') else text + out['hookSpecificOutput'] = hso + return out + + def warn(name, problem): - """One line on stderr about a config problem; the hook goes on with its defaults.""" + """One line on stderr about a config problem (also in the hook's answer: notice); the hook goes on.""" if problem: try: - sys.stderr.write(f'{name}: the machine file\'s "{KIT}" section cannot be used ({problem}); built-in ' - 'defaults used. Run `agent-guards self-check`.\n') + sys.stderr.write(problem_text(name, problem) + '\n') except Exception: # noqa: BLE001 pass diff --git a/fork-kit/agent-guards/lib/agent_guards/wiring.py b/fork-kit/agent-guards/lib/agent_guards/wiring.py index 1fdee1d6fb9cf..f6fe70b5a3cb8 100644 --- a/fork-kit/agent-guards/lib/agent_guards/wiring.py +++ b/fork-kit/agent-guards/lib/agent_guards/wiring.py @@ -3,14 +3,18 @@ Each hook is one command in Claude Code's settings, at the installed path (/usr/local/bin/). The command first checks that the hook file is there, so a missing hook fails the way its kind must, and says so on stderr: - actions-disable-guard fails CLOSED: exit 2 (every Bash command is refused until the hook is back), also when - the hook process itself fails (`|| exit 2`). It answers itself within 5 s of its start. + actions-disable-guard fails CLOSED: exit 2 (every Bash and Monitor command is refused until the hook is back), + also when the hook process itself fails (`|| exit 2`) and when the file is empty (an + empty Python file would answer nothing, which lets the call run). It answers itself within 5 s of + its start; should Claude Code still cut it off at its timeout, the entry's + "onFailure": "block" refuses the call (without it a timed-out hook lets the call run). capacity-pipe-guard, fail OPEN: exit 1, which Claude Code shows as a hook error and then runs the call. These memory-index-guard, guard mistakes, not attacks; refusing every call because a helper is gone would stop all bg-guard, agent-slots work on the machine. The same entries go in the managed settings drop-in the installer writes (--settings) or, by hand, in any settings -file (`agent-guards hooks`). Timeouts and matchers are the ones these hooks always had. +file (`agent-guards hooks`). Monitor runs shell text like Bash, so every hook that reads a command reads it for +Monitor too. """ import json @@ -22,7 +26,7 @@ HOOKS = ('actions-disable-guard', 'capacity-pipe-guard', 'memory-index-guard', 'bg-guard', 'agent-slots') CLOSED = {'actions-disable-guard'} # a missing or failed hook refuses WHAT_IS_LOST = { - 'actions-disable-guard': 'every Bash command is refused until it is back', + 'actions-disable-guard': 'every Bash and Monitor command is refused until it is back', 'capacity-pipe-guard': 'hook skipped, commands are NOT checked', 'memory-index-guard': 'hook skipped, the memory index is NOT checked', 'bg-guard': 'hook skipped, background commands are NOT checked', @@ -31,9 +35,9 @@ # (event, matcher or None, [(hook, timeout)]): one settings entry each, in this order ENTRIES = ( ('PreToolUse', 'Write|Edit|MultiEdit', [('memory-index-guard', 5)]), - ('PreToolUse', 'Bash', [('actions-disable-guard', 10)]), + ('PreToolUse', 'Bash|Monitor', [('actions-disable-guard', 10)]), ('PreToolUse', 'Bash|Monitor', [('capacity-pipe-guard', 10)]), - ('PostToolUse', 'Write|Edit|MultiEdit|Bash', [('memory-index-guard', 5)]), + ('PostToolUse', 'Write|Edit|MultiEdit|Bash|Monitor', [('memory-index-guard', 5)]), ('UserPromptSubmit', None, [('agent-slots', 5)]), ('Stop', None, [('agent-slots', 5), ('bg-guard', 5)]), ) @@ -43,7 +47,7 @@ def command(hook, bin_dir=BIN, python='/usr/bin/python3'): """The shell command of one hook's settings entry.""" path = f'{bin_dir}/{hook}' if hook in CLOSED: - return (f'g={path}; [ -r "$g" ] || {{ echo "{hook}: $g is missing: {WHAT_IS_LOST[hook]}" >&2; exit 2; }}; ' + return (f'g={path}; [ -r "$g" ] && [ -s "$g" ] || {{ echo "{hook}: $g is missing or empty: {WHAT_IS_LOST[hook]}" >&2; exit 2; }}; ' f'{python} -IB "$g" || {{ echo "{hook}: the guard failed (exit $?): the command is refused" >&2; ' 'exit 2; }') return (f'g={path}; [ -r "$g" ] || {{ echo "{hook}: $g is missing: {WHAT_IS_LOST[hook]}" >&2; exit 1; }}; ' @@ -55,7 +59,8 @@ def hooks(bin_dir=BIN, python='/usr/bin/python3'): out = {} for event, matcher, items in ENTRIES: entry = {'matcher': matcher} if matcher else {} - entry['hooks'] = [{'type': 'command', 'command': command(h, bin_dir, python), 'timeout': t} for h, t in items] + entry['hooks'] = [dict({'type': 'command', 'command': command(h, bin_dir, python), 'timeout': t}, + **({'onFailure': 'block'} if h in CLOSED else {})) for h, t in items] out.setdefault(event, []).append(entry) return out @@ -75,13 +80,28 @@ def commands_in(settings): return out -def find(settings, hook, event): - """The command of `hook` for `event` in a settings object (the first one naming it), or None. A name is found - as a whole word of a path (`/x/bg-guard`, `bg-guard;`), not inside another name.""" +def matches(matcher, tool): + """Whether a settings entry's matcher takes this tool, as Claude Code reads it: none, "" or "*" take every tool; + letters, digits, _ and | only are an exact list; anything else is a regular expression.""" + import re + if tool is None or matcher in (None, '', '*'): + return True + if re.fullmatch(r'[A-Za-z0-9_|]+', matcher): + return tool in matcher.split('|') + try: + return re.search(matcher, tool) is not None + except re.error: + return False + + +def find(settings, hook, event, tool=None): + """The command of `hook` for `event` in a settings object (the first one naming it, in an entry whose matcher + takes `tool` when one is given), or None. A name is found as a whole word of a path (`/x/bg-guard`, + `bg-guard;`), not inside another name.""" import re pat = re.compile(r'(^|[/\s="\'])' + re.escape(hook) + r'($|[\s;"\'])') - for ev, _matcher, cmd in commands_in(settings): - if ev == event and pat.search(cmd): + for ev, matcher, cmd in commands_in(settings): + if ev == event and pat.search(cmd) and matches(matcher, tool): return cmd return None @@ -90,5 +110,7 @@ def ours(settings): """True for a settings object this kit wrote: only "hooks", and every command one of the kit's hooks.""" if not isinstance(settings, dict) or set(settings) != {'hooks'}: return False + import re cmds = commands_in(settings) - return bool(cmds) and all(any(f'/{h}' in c for h in HOOKS) for _e, _m, c in cmds) + kit = re.compile(r'^g=' + re.escape(BIN) + r'/(' + '|'.join(re.escape(h) for h in HOOKS) + r'); ') + return bool(cmds) and all(kit.match(c) for _e, _m, c in cmds) diff --git a/fork-kit/agent-guards/sbin/agent-guards-install b/fork-kit/agent-guards/sbin/agent-guards-install index 44b80d784a984..635efc631d138 100755 --- a/fork-kit/agent-guards/sbin/agent-guards-install +++ b/fork-kit/agent-guards/sbin/agent-guards-install @@ -14,8 +14,15 @@ and only root can change; --no-settings removes it. The choice is kept in /etc/a without either option keeps it (the first install: no drop-in). The drop-in is written only after the links, so a hook it names is always there. Safe to run again, and to stop at any step; one installer at a time. The steps every kit shares are in fork-kit/common/kit_install.py. + +Rolling back is `install --no-settings`: the hooks stay, new sessions no longer run them. A session that started +while the drop-in was there keeps running the hooks it started with, so uninstall (which removes the hook files) +refuses while such a session runs (a `claude` process older than the drop-in's removal, kept as "settingsOff" in +config.json), and while a settings file the kit did not write names a kit hook (managed-settings.json, another +managed-settings.d file, a user's ~/.claude*/settings*.json): a hook that is gone refuses every Bash command +there. Uninstall with the drop-in still there removes it first, then checks. """ -import json, os, sys +import contextlib, glob, json, os, pwd, sys, time _kit = os.path.dirname(os.path.dirname(os.path.realpath(__file__))) _common = os.path.join(_kit, 'common') sys.path[:0] = [_common if os.path.isdir(_common) else os.path.join(os.path.dirname(_kit), 'common'), @@ -42,7 +49,7 @@ class AgentGuardsInstaller(kit_install.Installer): 'sbin/agent-guards-install', 'README.md', 'common/machine_file.py', 'common/kit_install.py') EXECUTABLE = frozenset([f'bin/{h}' for h in HOOKS + ('agent-guards',)] + ['sbin/agent-guards-install']) PACKAGE = 'agent_guards' - MODULES = ('__init__', 'check', 'config', 'wiring') + MODULES = ('__init__', 'approval', 'check', 'config', 'wiring') HELP = ('bin/agent-guards', 'agent-guards check') HAS_CONFIG = True KIT_STEPS = ('settings',) @@ -68,8 +75,10 @@ class AgentGuardsInstaller(kit_install.Installer): for path in (wiring.MANAGED_DIR, os.path.dirname(wiring.DROP_IN)): real = self.p(path) if os.path.lexists(real) and (os.path.islink(real) or not os.path.isdir(real) - or os.lstat(real).st_uid != self.ROOT_UID): - raise self.Refused(f'{path} exists and is not a root-owned folder: fix it by hand and run again') + or os.lstat(real).st_uid != self.ROOT_UID + or os.lstat(real).st_mode & 0o022): + raise self.Refused(f'{path} exists and is not a root-owned folder that only root can write: fix it ' + 'by hand and run again') if self.drop_in_ours() is False: raise self.Refused(f'{wiring.DROP_IN} exists and was not written by this kit: remove it and run again, ' 'or run with --no-settings to leave it alone') @@ -78,33 +87,151 @@ class AgentGuardsInstaller(kit_install.Installer): settings = a.settings if a.settings is not None else bool(self.read_config().get('settings')) if settings or self.drop_in_ours(): self.check_managed() - return {'settings': settings} + off = self.read_config().get('settingsOff') + if not settings and self.drop_in_ours(): + off = 'pending' # written before the drop-in goes; the time once it is gone (kit_step) + return {'settings': settings, 'settingsOff': None if settings else off} def config(self, a, plan): - return {'version': 1, 'settings': plan['settings']} + out = {'version': 1, 'settings': plan['settings']} + if plan.get('settingsOff') is not None: + out['settingsOff'] = plan['settingsOff'] + return out def kit_step(self, step, a, plan, dest): # after the links: every hook the drop-in names is the one of this release if plan['settings']: self.check_managed() for path in (wiring.MANAGED_DIR, os.path.dirname(wiring.DROP_IN)): - self.ensure_dir(path) + if not os.path.lexists(self.p(path)): # Claude Code's folders: made when missing, else left as + self.ensure_dir(path) # they are (check_managed: root-owned folders) if self.write_file(wiring.DROP_IN, wiring.drop_in_text()): self.say(f'wrote {wiring.DROP_IN}: every new Claude Code session runs the hooks ' '(sessions already running keep the hooks they started with)') - elif self.drop_in_ours(): - os.unlink(self.p(wiring.DROP_IN)) - self.say(f'removed {wiring.DROP_IN}') + else: + self.settings_off(plan) def kit_rows(self, plan): if not plan['settings']: return [] return [(wiring.DROP_IN, 'file', kit_install.sha256_file(self.p(wiring.DROP_IN)))] - def kit_uninstall(self): + def settings_off(self, plan=None): + """Remove the kit's drop-in, keeping in config.json when that was: "pending" before, the time after (a stop + in between leaves "pending", and the next run puts the time of that run: later, so it counts more sessions + as older, never fewer). "settings" becomes false with it, so a later install without an option keeps the + drop-in off (an uninstall that refuses has already removed it).""" + cfg = self.read_config() if self.drop_in_ours(): + if cfg.get('settingsOff') != 'pending': + self.write_file(self.CONFIG, json.dumps(dict(cfg, settings=False, settingsOff='pending'), indent=2, + sort_keys=True) + '\n') os.unlink(self.p(wiring.DROP_IN)) - self.say(f'removed {wiring.DROP_IN}') + self.say(f'removed {wiring.DROP_IN}: new sessions do not run the hooks; sessions already running keep ' + 'them until they end') + cfg = self.read_config() + if cfg.get('settingsOff') == 'pending' and not os.path.lexists(self.p(wiring.DROP_IN)): + cfg['settingsOff'] = int(time.time()) + 1 # +1: a session started in this very second counts as older + self.write_file(self.CONFIG, json.dumps(cfg, indent=2, sort_keys=True) + '\n') + if plan is not None: + plan['settingsOff'] = cfg['settingsOff'] + + def kit_uninstall(self): + self.settings_off() + + HOMES = None # tests only: the home folders searched for user settings (default: every passwd entry) + CLAUDE = 'claude' # Claude Code's process name + + def foreign_settings(self): + """Settings files the kit did not write that name a kit hook (or cannot be read), as (path, why).""" + homes = self.HOMES if self.HOMES is not None else sorted({e.pw_dir for e in pwd.getpwall() if e.pw_dir}) + files = [self.p(f'{wiring.MANAGED_DIR}/managed-settings.json')] + files += sorted(glob.glob(self.p(f'{os.path.dirname(wiring.DROP_IN)}/*'))) + for home in homes: + files += sorted(glob.glob(os.path.join(self.p(home) if self.HOMES is None else home, '.claude*', + 'settings*.json'))) + names = [f'{wiring.BIN}/{h}' for h in HOOKS] + found = [] + for f in dict.fromkeys(files): + if os.path.realpath(f) == os.path.realpath(self.p(wiring.DROP_IN)) and self.drop_in_ours(): + continue + try: + with open(f, encoding='utf-8', errors='replace') as fh: + text = fh.read() + except FileNotFoundError: + continue + except OSError as e: + found.append((f, f'cannot be read ({e.strerror}), so it may name one')) + continue + hit = [n for n in names if n in text] + if hit: + found.append((f, f'names {hit[0]}')) + return found + + def boot_time(self): + with open(f'{self.PROC}/stat', encoding='ascii', errors='replace') as f: + for line in f: + if line.startswith('btime '): + return int(line.split()[1]) + raise ValueError('no btime') + + def older_sessions(self, since): + """`claude` processes that started before `since` (epoch seconds), one line each; a process whose start + cannot be read counts as older.""" + try: + boot, tick = self.boot_time(), os.sysconf('SC_CLK_TCK') + except (OSError, ValueError) as e: + raise self.Refused(f'{self.PROC}/stat cannot be read ({e}): uninstall cannot see which Claude Code ' + 'sessions are older than the removal of the drop-in') from None + mine, pid = set(), os.getpid() + while pid > 1 and pid not in mine: # this uninstall and what started it (a session running sudo) + mine.add(pid) + try: + with open(f'{self.PROC}/{pid}/stat', 'rb') as f: + pid = int(f.read().rpartition(b')')[2].split()[1]) + except (OSError, ValueError, IndexError): + break + out = [] + for name in sorted((n for n in os.listdir(self.PROC) if n.isdigit()), key=int): + if int(name) in mine: + continue + try: + with open(f'{self.PROC}/{name}/cmdline', 'rb') as f: + args = [a.decode('utf-8', 'replace') for a in f.read().split(b'\0') if a] + except OSError: + continue + if not any(os.path.basename(a) == self.CLAUDE for a in args[:2]) \ + and not any('@anthropic-ai/claude-code' in a for a in args[:2]): + continue + try: + with open(f'{self.PROC}/{name}/stat', 'rb') as f: + start = boot + int(f.read().rpartition(b')')[2].split()[19]) / tick + except (OSError, ValueError, IndexError): + start = None + if start is None or start < since: + out.append(f'process {name}: {" ".join(args)[:200]}') + return out + + @contextlib.contextmanager + def uninstall_guard(self): + foreign = self.foreign_settings() + if foreign: + raise self.Refused('uninstall refused: a settings file this kit did not write names a kit hook, and ' + 'with the hook gone it would refuse every Bash command there:\n ' + + '\n '.join(f'{f[len(self.PREFIX):] if f.startswith(self.PREFIX) else f}: {why}' + for f, why in foreign) + + '\nRemove those entries by hand and run uninstall again') + self.settings_off() + off = self.read_config().get('settingsOff') + if isinstance(off, (int, float)) and not isinstance(off, bool): + older = self.older_sessions(off) + if older: + raise self.Refused('uninstall refused: these Claude Code sessions started while the hooks were in ' + 'managed settings and still run them; with the hooks gone they would refuse every ' + 'Bash command:\n ' + '\n '.join(older) + '\nThe drop-in is removed, so new ' + 'sessions do not run the hooks. Let these end (or stop them) and run uninstall ' + 'again') + yield def _remove(self): # the drop-in goes first: while it is there, the hooks it names must be too (a missing diff --git a/fork-kit/agent-guards/tests/actions-disable.test.py b/fork-kit/agent-guards/tests/actions-disable.test.py index 2b0eb60071d60..c2ad294d760f2 100644 --- a/fork-kit/agent-guards/tests/actions-disable.test.py +++ b/fork-kit/agent-guards/tests/actions-disable.test.py @@ -15,6 +15,8 @@ HOOK = os.path.join(fx.BIN, 'actions-disable-guard') GARDEN = {'name': 'example_garden.py', 'flag': '--fix', 'why': 'disables every workflow it does not know'} +# the old escape hatch (a session variable and a bare marker): it opens nothing any more (lens B major: a nested +# session inherited the variable) MARK_ENV, MARK_CMD = 'CLAUDE_GUARD_OWNER_ALLOW_ACTIONS_DISABLE', '#owner-approved:actions-disable' @@ -1149,8 +1151,10 @@ def test_allow(self): def test_reason_names_rule_owner_and_marker(self): why = self.decide('gh workflow disable 1') - for part in ('owner', 'refuse', MARK_ENV, 'must not'): + for part in ('owner', 'refuse', 'sudo agent-guards approve', MARK_CMD + ':', 'must not', + 'without this machine\'s hooks'): self.assertIn(part, why) + self.assertNotIn(MARK_ENV, why) # scripts the command runs def test_shell_script_file(self): @@ -1223,24 +1227,108 @@ def test_alias_import_file(self): self.write('al.yml', 'wd: workflow disable\n', 0o644) self.assertIsNotNone(self.decide('gh alias import al.yml')) - # the owner's escape hatch - def hatch_env(self, value): - return dict(self.env, **{MARK_ENV: value}) - - def test_hatch_needs_env_of_today_and_marker(self): - cmd = f'gh workflow disable 1 -R a/b {MARK_CMD}' - self.assertIsNone(self.decide(cmd, self.hatch_env(today()))) - self.assertIsNotNone(self.decide('gh workflow disable 1 -R a/b', self.hatch_env(today()))) - self.assertIsNotNone(self.decide(cmd, self.hatch_env('2026-01-01'))) - self.assertIsNotNone(self.decide(cmd, self.hatch_env('1'))) - self.assertIsNotNone(self.decide(cmd)) - - def test_hatch_refused_when_set_in_a_settings_file(self): + # the owner's approval (lens B major): a root-owned file `sudo agent-guards approve` writes, and the code it + # prints in the command. A session variable reached every nested agent; the old one now opens nothing. + def approve(self, hours=1, now=None): + """An approval file in this test's folder, owned by the test user (approval.PATH, approval.OWNER_UID); + (the approval module, the marker with its code).""" + from agent_guards import approval + for name, value in (('PATH', os.path.join(self.dir, 'etc', 'approval.json')), ('OWNER_UID', os.geteuid())): + self.addCleanup(setattr, approval, name, getattr(approval, name)) + setattr(approval, name, value) + code = approval.new_code() + approval.write(code, hours, now=now) + return approval, approval.MARK + code + + def test_the_old_variable_and_marker_open_nothing(self): + env = dict(self.env, **{MARK_ENV: today()}) + for cmd in (f'gh workflow disable 1 -R a/b {MARK_CMD}', f'gh workflow disable 1 {MARK_CMD}:', + f'gh workflow disable 1 {MARK_CMD}:abc'): + with self.subTest(cmd): + self.assertIsNotNone(self.decide(cmd, env)) self.write('.claude/settings.json', json.dumps({'env': {MARK_ENV: today()}}), 0o644) - cmd = f'gh workflow disable 1 {MARK_CMD}' - why = self.decide(cmd, self.hatch_env(today())) - self.assertIsNotNone(why) - self.assertIn('settings', why) + self.assertIsNotNone(self.decide(f'gh workflow disable 1 {MARK_CMD}', env)) + + def test_an_approval_needs_the_owners_file_and_its_code(self): + approval, mark = self.approve() + cmd = 'gh workflow disable 1 -R a/b' + self.assertIsNone(self.decide(f'{cmd} {mark}')) + self.assertIsNone(self.decide(f'{cmd} {mark} (the owner asked for it in issue 9)')) + self.assertIsNotNone(self.decide(cmd)) # no code: refused + why = self.decide(f'{cmd} {approval.MARK}{approval.new_code()}') # a made-up code + self.assertIn('not the one the owner approved', why) + self.assertIsNotNone(self.decide(f'{cmd} {mark}x')) # not the code: longer + self.assertIsNotNone(self.decide(f'{cmd} {mark[:-1]}')) # not the code: shorter + with open(approval.PATH) as f: + self.assertNotIn(mark.rpartition(':')[2], f.read()) # only its hash is kept + self.assertTrue(approval.revoke()) + self.assertIn('not there', self.decide(f'{cmd} {mark}')) + + def test_an_approval_that_is_over_or_not_safe_opens_nothing(self): + import time + approval, mark = self.approve(hours=1, now=time.time() - 7200) + self.assertIn('the approval is over', self.decide(f'gh workflow disable 1 {mark}')) + approval, mark = self.approve() + cmd = f'gh workflow disable 1 {mark}' + os.chmod(approval.PATH, 0o666) # an agent could write it + self.assertIn('writable by group or others', self.decide(cmd)) + os.chmod(approval.PATH, 0o644) + os.rename(approval.PATH, approval.PATH + '.real') + os.symlink(approval.PATH + '.real', approval.PATH) + self.assertIn('symbolic link', self.decide(cmd)) + os.unlink(approval.PATH) + for text in ('', '{', '[]', '{"version": 1}', '{"version": 2, "sha256": "' + 'a' * 64 + '", "until": 9e9}', + '{"version": 1, "sha256": "x", "until": 9e9}', '{"version": 1, "sha256": "' + 'a' * 64 + + '", "until": "9e9"}'): + with self.subTest(text): + with open(approval.PATH, 'w') as f: + f.write(text) + self.assertIsNotNone(self.decide(cmd)) + with self.assertRaises(ValueError): + approval.write(approval.new_code(), approval.MAX_HOURS + 1) + + # nested agent sessions (lens B minor): one without this machine's hooks would run anything + def test_a_nested_session_without_the_hooks_is_refused(self): + refused = ['claude --bare -p "x"', 'claude -p --bare x', 'claude --safe-mode -p x', 'claude --bare=1 -p x', + 'CLAUDE_CODE_SIMPLE=1 claude -p x', 'env CLAUDE_CODE_SIMPLE=1 claude -p x', + 'export CLAUDE_CODE_SIMPLE=1; claude -p x', + 'claude -p --settings \'{"env": {"CLAUDE_CODE_SIMPLE": "1"}}\' x', + '/usr/local/bin/claude --bare -p x', 'bash -c "claude --bare -p x"', + 'codex exec "x"', 'codex "x"', 'codex', 'codex --full-auto exec x', 'cd /tmp && codex exec x', + 'timeout 60 codex exec x', 'bash -c "codex exec x"'] + for cmd in refused: + with self.subTest(cmd): + why = self.decide(cmd) + self.assertIsNotNone(why, cmd) + self.assertIn('without this machine\'s hooks' if 'claude' in cmd else 'runs no Claude Code hooks', + why) + # managed hooks run in a nested `claude -p` whatever its own settings say: disableAllHooks in a session's + # or user's settings does not turn managed hooks off + passed = ['claude -p "x"', 'claude -p --settings \'{"disableAllHooks": true}\' x', 'claude --version', + 'claude mcp list', 'codex login', 'codex --version', 'codex --help', 'codex help exec', + 'echo "codex exec x"', 'git commit -m "no claude --bare here"', 'grep -rn CLAUDE_CODE_SIMPLE .'] + for cmd in passed: + with self.subTest(cmd): + self.assertIsNone(self.decide(cmd), cmd) + + def test_the_owner_can_approve_a_nested_session_too(self): + _approval, mark = self.approve() + self.assertIsNone(self.decide(f'codex exec x {mark}')) + + # rulesets: "evaluate" only reports, so it switches the rules off as "disabled" does (lens B minor) + def test_a_ruleset_set_to_evaluate_is_refused(self): + self.write('rs_eval.json', '{"name": "main", "enforcement": "evaluate", "rules": []}\n', 0o644) + for cmd in ('gh api -X PUT repos/a/b/rulesets/1 -f enforcement=evaluate', + 'gh api -X PUT repos/a/b/rulesets/1 -f enforcement=EVALUATE', + 'gh api -X PUT repos/a/b/rulesets/1 --input rs_eval.json', + 'gh api -X PUT repos/a/b/rulesets/1 --input - < Date: Sun, 22 Nov 2026 04:01:51 +0000 Subject: [PATCH 3/9] fork-kit/agent-guards: GraphQL ruleset update with EVALUATE in a variable is refused (lens B r2 minor 1) The off word of updateRepositoryRuleset was looked for in canon() text, which blanks text with no cue word, so `-F e=EVALUATE` (or a JSON variables block) was '' before OFF_WORD saw it. It is now read without the cue words, as the REST ruleset body already was. Co-Authored-By: Claude Opus 5.5 --- .../agent-guards/bin/actions-disable-guard | 5 ++++- .../tests/actions-disable.test.py | 20 +++++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/fork-kit/agent-guards/bin/actions-disable-guard b/fork-kit/agent-guards/bin/actions-disable-guard index 2979f9aeb4984..6f148994c789f 100755 --- a/fork-kit/agent-guards/bin/actions-disable-guard +++ b/fork-kit/agent-guards/bin/actions-disable-guard @@ -1414,7 +1414,10 @@ def api_reason(args, ctx, top=False): gql = any(may_be_graphql(a) for a in pos) if exact else path is None or may_be_graphql(path) if gql and any(GQL_RE.search(x) for x in seen): return reason('a GraphQL mutation that deletes branch protection or a ruleset') - if gql and any(GQL_UPDATE.search(x) for x in seen) and (unread or any(OFF_WORD.search(x) for x in seen)): + # the off word may stand alone in a variable (-F e=EVALUATE, `"variables": {"e": "EVALUATE"}`): read without + # the cue words, as for a ruleset body (canon() blanks text that names no guarded word) + if gql and any(GQL_UPDATE.search(x) for x in seen) and (unread or any( + OFF_WORD.search(canon(x, cue=False)) for x in list(args) + bodies)): return reason('a GraphQL updateRepositoryRuleset that switches the ruleset off (enforcement: DISABLED ' 'or EVALUATE), ' 'or one with a body the guard cannot read') diff --git a/fork-kit/agent-guards/tests/actions-disable.test.py b/fork-kit/agent-guards/tests/actions-disable.test.py index c2ad294d760f2..fc17006d426a8 100644 --- a/fork-kit/agent-guards/tests/actions-disable.test.py +++ b/fork-kit/agent-guards/tests/actions-disable.test.py @@ -1948,6 +1948,26 @@ def test_deep_script_naming_a_root_only_file_passes(self): ] +class LensSecurityR2Test(Case): + """PR 847, lens B round 2 (security boundary): each test names the finding it closes.""" + + def test_r2_minor1_graphql_update_with_evaluate_in_a_variable_is_refused(self): + mut = ('mutation($e: RuleEnforcement!) { updateRepositoryRuleset(input: {repositoryRulesetId: \\"x\\", ' + 'enforcement: $e}) { clientMutationId } }') + mut_i = 'mutation($i: UpdateRepositoryRulesetInput!) { updateRepositoryRuleset(input: $i) { clientMutationId } }' + self.write('vars.json', json.dumps({'query': mut, 'variables': {'e': 'EVALUATE'}}) + '\n', 0o644) + for cmd in (f"gh api graphql -f query='{mut}' -F e=EVALUATE", + f"gh api graphql -f query='{mut}' -f e=evaluate", + f"gh api graphql -f query='{mut}' --raw-field e=EVALUATE", + f"gh api graphql -f query='{mut}' --field=e=EVALUATE", + f"gh api graphql -f query='{mut_i}' -F i[repositoryRulesetId]=x -F i[enforcement]=EVALUATE", + 'gh api graphql --input vars.json'): + with self.subTest(cmd): + self.assertIsNotNone(self.decide(cmd), cmd) + # the same call that keeps the ruleset on passes + self.assertIsNone(self.decide(f"gh api graphql -f query='{mut}' -F e=ACTIVE")) + + class FastExitTest(Case): """#1752 fix point 1: plain commands pass before any file is read or the clock matters, and nothing the full reading refuses takes that way out.""" From 239c710bb3800f9b1daff3eb277e7ec6be2081a5 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 04:07:12 +0000 Subject: [PATCH 4/9] fork-kit/agent-guards: an owner approval passes one command, in one folder, once (lens B r2 major 2) `sudo agent-guards approve --command '' [--cwd DIR]` now stores the hash of the normalised command and the folder next to the code's hash (approval file version 2). The guard passes only that command, ending in the marker, run in that folder, and records the use in its state folder (O_EXCL link; the same tool_use_id passes again), so the approval is used up. A code seen in a transcript, the app database or ps opens no other command. A version 1 file counts as no approval. Co-Authored-By: Claude Opus 5.5 --- fork-kit/agent-guards/README.md | 15 ++- .../agent-guards/bin/actions-disable-guard | 37 +++--- fork-kit/agent-guards/bin/agent-guards | 27 ++-- .../agent-guards/lib/agent_guards/approval.py | 124 ++++++++++++++---- .../tests/actions-disable.test.py | 89 +++++++++++-- fork-kit/agent-guards/tests/wiring.test.py | 28 +++- 6 files changed, 252 insertions(+), 68 deletions(-) diff --git a/fork-kit/agent-guards/README.md b/fork-kit/agent-guards/README.md index f88cc08393a7b..790e2c88d5cc8 100644 --- a/fork-kit/agent-guards/README.md +++ b/fork-kit/agent-guards/README.md @@ -49,14 +49,23 @@ session (`claude --bare`, `--safe-mode`, `CLAUDE_CODE_SIMPLE`) and Codex (`codex so `actions-disable-guard` refuses starting one (`codex login`, `logout`, `help` and `--version` pass). This is a command check like the others: it does not see a session started by a program the guard does not read. -**The owner's approval.** Only the owner can let one refused command through, as root: +**The owner's approval.** Only the owner can let one refused command through, as root, in the folder the command +will run in (or with `--cwd DIR`): ```sh -sudo agent-guards approve --hours 1 # prints a one-time code; keeps only its hash, in a root-owned file +sudo agent-guards approve --hours 1 --command 'gh workflow disable ci.yml -R owner/repo' +# prints a code; keeps only hashes of the code and the command, the folder and the end time, in a root-owned file sudo agent-guards approve --revoke # ends it now ``` -The command then carries `#owner-approved:actions-disable:`. The file is +The approval is for that one command (compared after taking the marker off its end; runs of blanks count as one), +run in that folder, once, before the end time. The agent runs it with `#owner-approved:actions-disable:` at its +end. The first run records the use in the guard's state folder (`actionsDisable.stateDir`); a second run, or any +other command carrying the code, is refused. So a code an agent sees in a transcript, the app's database or `ps` +opens nothing else. A new `approve` replaces the approval before it; an approval file of an earlier draft (version +1, not bound to a command) is no approval. The use record lives in the agents' user's folder (the hook runs as that +user): an agent that sets out to can remove it, and then can only repeat the approved command in that folder until +the end time. The file is `/etc/fork-kit/agent-guards-approval.json` (read under the machine file's rules: root-owned, not writable by group or others, no link), at most 24 hours. An earlier draft used a session environment variable; every nested session inherited it, so it is not read any more. Anyone who can become root without a password (sudo `NOPASSWD`, the diff --git a/fork-kit/agent-guards/bin/actions-disable-guard b/fork-kit/agent-guards/bin/actions-disable-guard index 6f148994c789f..e1426ec93231e 100755 --- a/fork-kit/agent-guards/bin/actions-disable-guard +++ b/fork-kit/agent-guards/bin/actions-disable-guard @@ -113,12 +113,14 @@ A guarded call only in a script 4 or more levels deep (a.sh -> b.sh -> c.sh -> d unless other text in the command flows on. gh has no request hook, so this hook is the command-text layer; the wall is a token that cannot do it. -Escape hatch (owner only, as root): `sudo agent-guards approve [--hours N]` prints a one-time code and keeps its -hash in a root-owned file (lib/agent_guards/approval.py); a command that carries +Escape hatch (owner only, as root): `sudo agent-guards approve [--hours N] --command ''` approves ONE command +run in one folder, once: it prints a code and keeps in a root-owned file (lib/agent_guards/approval.py) only the +code's hash, the normalised command's hash, the folder and the end time (1 hour by default). That command, ending in #owner-approved:actions-disable: -passes while that file holds the code and its time (1 hour by default) has not run out. An agent cannot write the -file, so it cannot approve itself, and nothing is inherited: a nested session gets the code only when it is in its -command. (The old CLAUDE_GUARD_OWNER_ALLOW_ACTIONS_DISABLE variable opens nothing any more: a variable reaches +passes once, in that folder, before the end time; the use is recorded in the state folder and a second run, or any +other command with the code, is refused. A code seen in a transcript, the app's database or `ps` opens nothing else. +An agent cannot write the file, so it cannot approve itself, and nothing is inherited: a nested session gets the +code only when it is in its command. (The old CLAUDE_GUARD_OWNER_ALLOW_ACTIONS_DISABLE variable opens nothing any more: a variable reaches every nested `claude -p` or `codex exec` of the session.) Fails closed: an internal error refuses commands that look dangerous. @@ -238,8 +240,9 @@ SELF = os.path.realpath(os.path.abspath(__file__)) if '__file__' in globals() el RULE = ('Owner rule (2026-11-13, "guards that refuse, not trust"): no agent disables GitHub Actions workflows, or ' 'Actions itself, on any repo; re-enabling (`gh workflow enable`, PUT .../enable) is fine. If disabling is ' 'really needed, stop and ask the owner: name the repo, the workflow and why. Only the owner can approve ' - 'it: they run `sudo agent-guards approve` and give you a code, and the command then carries ' - f'{MARK_CMD}. Agents must not make up a code, reuse one they were not given for this, start an agent ' + 'it: they run `sudo agent-guards approve --command \'\'` and give you a code; that ' + f'one command, ending in {MARK_CMD}, then passes once, in the folder they approved it for. Agents ' + 'must not make up a code, reuse one they were not given for this, start an agent ' 'session without this machine\'s hooks, or route around this guard with scripts, aliases or other HTTP ' 'clients.') UNREADABLE = ('If this call is harmless, write it so the guard can read it: the path and the flags spelled out in ' @@ -3082,8 +3085,9 @@ def decide_text(text, ctx, scan_raw=True): return None -def decide(cmd, cwd, env, budget=None): - """None to let the command run, else the deny reason. budget: seconds the reading may take (None: no limit).""" +def decide(cmd, cwd, env, budget=None, use_id=None): + """None to let the command run, else the deny reason. budget: seconds the reading may take (None: no limit). + use_id: the tool call's id (an owner approval is used up by one call; the same call's second hook run passes).""" if not cmd or (QUICK and quick_pass(cmd)): return None ctx = {'cwd': cwd or os.getcwd(), 'env': env, 'depth': 0, 'raw': cmd, 'all': cmd, 'memo': {}, 'flow': {}, @@ -3094,7 +3098,7 @@ def decide(cmd, cwd, env, budget=None): why = SLOW ctx['cache'] = {} # a reading cut off half-way keeps nothing if why: - why = owner_marker(why, cmd, cwd, env) + why = owner_marker(why, cmd, ctx['cwd'], env, use_id) try: # last, with the answer known: an alarm or a failure in it changes nothing cache_save(ctx) except BaseException: @@ -3102,14 +3106,17 @@ def decide(cmd, cwd, env, budget=None): return why -def owner_marker(why, cmd, cwd, env): - """The refusal, or None when the command carries the code of the owner's approval (agent_guards.approval). - A code that is wrong, too old, or one with no approval file adds why to the refusal.""" +def owner_marker(why, cmd, cwd, env, use_id=None): + """The refusal, or None when the command is the one command the owner approved (agent_guards.approval): it ends + with the approval's code, runs in its folder, and the approval was not used before (this use is recorded in the + state folder, so it is used up). A code that is wrong, used, for another command or folder, or too old, or one + with no approval file, adds why to the refusal.""" if MARK_CMD not in cmd: return why try: from agent_guards import approval - ok, problem = approval.approved(cmd) + used = state_dir(env) or state_dir({'HOME': os.path.expanduser('~')}) # where its one use is recorded + ok, problem = approval.approved(cmd, cwd, use_id=use_id, used_dir=used) except BaseException as e: # noqa: BLE001 - no approval code: no approval ok, problem = False, f'the approval code cannot be loaded ({type(e).__name__})' if ok: @@ -3239,7 +3246,7 @@ def answer(): left = BUDGET - process_age() if left <= 0: raise Slow() - why = decide(cmd, ev.get('cwd') or os.getcwd(), env, max(left - 1.0, 0.0)) + why = decide(cmd, ev.get('cwd') or os.getcwd(), env, max(left - 1.0, 0.0), ev.get('tool_use_id')) alarm_off() except Slow: alarm_off() # first: the handlers below must not be cut off by the alarm (that answers nothing) diff --git a/fork-kit/agent-guards/bin/agent-guards b/fork-kit/agent-guards/bin/agent-guards index c37cded26cf77..453b96511a219 100755 --- a/fork-kit/agent-guards/bin/agent-guards +++ b/fork-kit/agent-guards/bin/agent-guards @@ -7,8 +7,10 @@ case it must refuse and one it must pass (exit 1 on a problem). As root, F must be root's and only root may write it (its commands are run) agent-guards hooks [--bin DIR] print the "hooks" settings of every hook of the kit, for a settings file - agent-guards approve [--hours N] as root: approve actions-disable-guard refusals for N hours (default 1, at - most 24); prints the code the command must carry + agent-guards approve [--hours N] [--cwd DIR] --command 'CMD' + as root: approve ONE command that actions-disable-guard refuses, run in + DIR (default: this folder), once, within N hours (default 1, at most 24); + prints the code the command must end with agent-guards approve --revoke as root: end the approval now """ import argparse, grp, json, os, pwd, subprocess, sys @@ -78,7 +80,8 @@ def self_check(bin_dir, drop_in, links_dir=None): if data is not None: import time left = data['until'] - time.time() - notes.append(f'an owner approval for actions-disable-guard is open for {int(left // 60)} more minutes' + notes.append(f'an owner approval for actions-disable-guard is open for {int(left // 60)} more minutes ' + f'(one command, run once in {data["cwd"]})' if left > 0 else 'an owner approval file is there, its time is over') user = os.environ.get('SUDO_USER') or pwd.getpwuid(os.getuid()).pw_name if user == 'root': @@ -112,6 +115,8 @@ def main(argv): p = sub.add_parser('approve') p.add_argument('--hours', type=float, default=1.0) p.add_argument('--revoke', action='store_true') + p.add_argument('--command', help='the one command approved (exactly; blanks may differ)') + p.add_argument('--cwd', help='the folder it runs in (default: this one)') a = ap.parse_args(argv) if a.cmd == 'self-check': return self_check(os.path.dirname(os.path.realpath(__file__)), wiring.DROP_IN) @@ -154,18 +159,24 @@ def approve(a): if not 0 < a.hours <= approval.MAX_HOURS: print(f'{PROG} approve: --hours must be above 0 and at most {approval.MAX_HOURS}', file=sys.stderr) return 1 + if not a.command or not approval.normalise(a.command): + print(f'{PROG} approve: name the one command you approve: --command \'\' (the approval ' + 'passes that command only, once)', file=sys.stderr) + return 1 + cwd = os.path.realpath(a.cwd or os.getcwd()) code = approval.new_code() try: - data = approval.write(code, a.hours) - except OSError as e: + data = approval.write(code, a.hours, a.command, cwd) + except (OSError, ValueError) as e: print(f'{PROG} approve: cannot write {approval.PATH} ({e})', file=sys.stderr) return 1 import time until = time.strftime('%Y-%m-%d %H:%M UTC', time.gmtime(data['until'])) - print(f'Approved until {until}. Give the agent this marker for the one command you approve:\n' + print(f'Approved, once, until {until}: this command, run in {cwd}:\n' + f' {approval.normalise(a.command)}\n' + f'Give the agent this marker; the command passes actions-disable-guard with it at its end:\n' f' {approval.MARK}{code}\n' - f'Every command carrying it passes actions-disable-guard until then; end it early with ' - f'`sudo {PROG} approve --revoke`.') + f'Any other command, or a second run, is refused. End it early with `sudo {PROG} approve --revoke`.') return 0 diff --git a/fork-kit/agent-guards/lib/agent_guards/approval.py b/fork-kit/agent-guards/lib/agent_guards/approval.py index e08ba74da451b..bfe7d5482976b 100644 --- a/fork-kit/agent-guards/lib/agent_guards/approval.py +++ b/fork-kit/agent-guards/lib/agent_guards/approval.py @@ -1,19 +1,29 @@ -"""agent_guards.approval: the owner's approval for one actions-disable-guard refusal, as a root-owned file. - -The owner (root) runs `sudo agent-guards approve [--hours N]`. That makes a random code, prints it once, and keeps -only its SHA-256 and an end time in PATH (root-owned, mode 0644, written whole and renamed into place). A command -that carries `#owner-approved:actions-disable:` passes the guard while the file holds that code's hash and -the end time has not come. `sudo agent-guards approve --revoke` removes the file. +"""agent_guards.approval: the owner's approval of ONE refused actions-disable-guard command, as a root-owned file. + +The owner (root) runs `sudo agent-guards approve [--hours N] [--cwd DIR] --command ''`. That +makes a random code, prints it once, and keeps in PATH (root-owned, mode 0644, written whole and renamed into +place) only the code's SHA-256, the SHA-256 of the normalised command, the folder it runs in and an end time. The +command passes the guard when it is that command (marker taken off its end, runs of blanks as one), it ends with +`#owner-approved:actions-disable:`, it runs in that folder, the end time has not come, and the approval was +not used before: the first pass records its use (a file named by the code's hash in the guard's state folder, +made with O_EXCL; a second hook run for the same tool call, with the same tool_use_id, passes too). The approval +is then used up. `sudo agent-guards approve --revoke` removes the file. + +Why bound to the command: the code travels in the command text, so it lands in the session's transcript, the app's +database and `ps`, which every agent of the same user can read. Bound to one command in one folder, a code seen +there opens nothing else: no other workflow, repo or act. The use record is in the agents' user's own folder (the +hook runs as that user and cannot write a root file), so an agent that sets out to can remove it; that lets it +repeat only the act the owner approved, in that folder, until the end time. Why a file and not an environment variable: a variable set when a session starts is inherited by every process of -that session, a nested `claude -p` or `codex exec` too, so an approval meant for one command reached every agent -started under it. The code reaches an agent only when the owner hands it over, and an agent cannot write the file -(it is root's, in a root-owned folder), so it cannot approve itself. Who can become root without a password (sudo -NOPASSWD, the docker group) can write it: `agent-guards self-check` warns about that. +that session, a nested `claude -p` or `codex exec` too. An agent cannot write the file (it is root's, in a +root-owned folder), so it cannot approve itself. Who can become root without a password (sudo NOPASSWD, the docker +group) can write it: `agent-guards self-check` warns about that. The file is read under the machine file's rules (fork-kit/common/machine_file.py: every folder on the way and the file root-owned, not writable by group or others, no link). Anything wrong with it (not there, bad owner, bad JSON, -an old version, the time over) is no approval: the guard refuses as it would without one. Plain Python 3. +an older version such as the version 1 file of an earlier draft, the time over) is no approval: the guard refuses +as it would without one. Plain Python 3. """ import base64, datetime as dt, hashlib, hmac, json, os, re, secrets, sys, tempfile @@ -25,9 +35,11 @@ PATH = '/etc/fork-kit/agent-guards-approval.json' OWNER_UID = 0 # tests only -VERSION = 1 +VERSION = 2 # 1: an earlier draft, not bound to a command (counts as no approval) MARK = '#owner-approved:actions-disable:' CODE_RE = re.compile(r'#owner-approved:actions-disable:([a-z2-7]{20})(?![A-Za-z0-9])') +END_RE = re.compile(r'(?:^|(?<=\s))#owner-approved:actions-disable:([a-z2-7]{20})\s*\Z') # the marker ends the command +KEYS = {'version', 'sha256', 'command', 'cwd', 'until'} MAX_HOURS = 24 @@ -40,7 +52,7 @@ def _now(now): def read(path=None, owner_uid=None): - """The approval record {"version", "sha256", "until"}, or (None, why not).""" + """The approval record {"version", "sha256", "command", "cwd", "until"}, or (None, why not).""" path = path or PATH try: text = machine_file.read_protected_text(path, OWNER_UID if owner_uid is None else owner_uid) @@ -49,27 +61,81 @@ def read(path=None, owner_uid=None): return None, str(e) except ValueError as e: return None, f'{path}: not valid JSON ({e})' - if not isinstance(data, dict) or data.get('version') != VERSION or set(data) != {'version', 'sha256', 'until'} \ - or not isinstance(data['sha256'], str) or not re.fullmatch(r'[0-9a-f]{64}', data['sha256']) \ + if not isinstance(data, dict) or data.get('version') != VERSION or set(data) != KEYS \ + or not all(isinstance(data[k], str) and re.fullmatch(r'[0-9a-f]{64}', data[k]) for k in ('sha256', 'command')) \ + or not isinstance(data['cwd'], str) or not os.path.isabs(data['cwd']) \ or type(data['until']) not in (int, float): return None, f'{path}: not an approval file of this kit (version {VERSION})' return data, None -def approved(cmd, now=None): - """(True, None) when the command carries the code of a valid approval; else (False, why not or None when the - command carries no code at all).""" - codes = CODE_RE.findall(cmd or '') if isinstance(cmd, str) else [] - if not codes: +def normalise(cmd): + """The command the owner approves or an agent runs, as it is compared: a marker at its end taken off, runs of + blanks (spaces, tabs, line breaks) as one space, no blanks at either end.""" + m = END_RE.search(cmd) + return ' '.join((cmd[:m.start()] if m else cmd).split()) + + +def command_hash(cmd): + return hashlib.sha256(normalise(cmd).encode('utf-8')).hexdigest() + + +def approved(cmd, cwd=None, now=None, use_id=None, used_dir=None): + """(True, None) when the command is the one a valid approval names, ends with its code, runs in its folder, and + the approval was not used before (its use is then recorded in used_dir: the approval is used up); else (False, + why not, or None when the command carries no code at all). use_id: the tool call's id (a second hook run for + the same call passes too); used_dir: the folder of use records (None: the use cannot be recorded, so no pass).""" + if not isinstance(cmd, str) or not CODE_RE.search(cmd): return False, None data, why = read() if data is None: return False, why if _now(now) >= data['until']: return False, 'the approval is over (its time has passed)' - if any(hmac.compare_digest(_hash(c), data['sha256']) for c in codes): - return True, None - return False, 'the code in the command is not the one the owner approved' + m = END_RE.search(cmd) + if not m: + return False, 'the marker must end the command (the code is for one exact command, with nothing after it)' + if not hmac.compare_digest(_hash(m.group(1)), data['sha256']): + return False, 'the code in the command is not the one the owner approved' + if not hmac.compare_digest(command_hash(cmd), data['command']): + return False, ('the approval is for another command: it passes only the exact command the owner approved ' + '(`sudo agent-guards approve --command ...`)') + if os.path.realpath(cwd or '') != os.path.realpath(data['cwd']): + return False, f'the approval is for a command run in {data["cwd"]}, not in {cwd}' + return use(data['sha256'], use_id, used_dir) + + +def use(code_sha, use_id, used_dir): + """Record the one use of an approval: a file named by the code's hash, made whole (a temp file, then a link, + which fails when the name is taken). (True, None) for the first use, or for the same tool call again.""" + if not used_dir: + return False, 'the guard has no state folder to record the use of the approval in (stateDir)' + me = (use_id if isinstance(use_id, str) and use_id else 'none-' + secrets.token_hex(8))[:200] + path = os.path.join(used_dir, f'approval-used-{code_sha[:32]}') + tmp = None + try: + os.makedirs(used_dir, 0o700, exist_ok=True) + fd, tmp = tempfile.mkstemp(prefix='.approval-used.', dir=used_dir) + with os.fdopen(fd, 'w', encoding='utf-8') as f: + f.write(me) + f.flush() + os.fsync(f.fileno()) + try: + os.link(tmp, path) + return True, None + except FileExistsError: + with open(path, encoding='utf-8', errors='replace') as f: + if f.read() == me: + return True, None + return False, 'the approval was used already (it is for one run of one command): ask the owner again' + except OSError as e: + return False, f'the use of the approval cannot be recorded in {used_dir} ({e.strerror or e})' + finally: + if tmp: + try: + os.unlink(tmp) + except OSError: + pass def new_code(): @@ -77,15 +143,21 @@ def new_code(): return base64.b32encode(secrets.token_bytes(15)).decode('ascii').lower()[:20] -def write(code, hours, path=None, now=None): - """Write the approval for `code`, ending in `hours`, atomically (temp file in the same folder, then rename).""" +def write(code, hours, command, cwd, path=None, now=None): + """Write the approval of `command` run in `cwd` for `code`, ending in `hours`, atomically (temp file in the + same folder, then rename). The approval before it, used or not, is gone with it.""" if not (0 < hours <= MAX_HOURS): raise ValueError(f'--hours must be above 0 and at most {MAX_HOURS}') + if not isinstance(command, str) or not normalise(command): + raise ValueError('the command to approve is empty') + if not isinstance(cwd, str) or not os.path.isabs(cwd): + raise ValueError('the folder the command runs in must be an absolute path') path = path or PATH folder = os.path.dirname(path) if not os.path.isdir(folder): os.makedirs(folder, 0o755, exist_ok=True) - data = {'version': VERSION, 'sha256': _hash(code), 'until': int(_now(now) + hours * 3600)} + data = {'version': VERSION, 'sha256': _hash(code), 'command': command_hash(command), + 'cwd': os.path.realpath(cwd), 'until': int(_now(now) + hours * 3600)} fd, tmp = tempfile.mkstemp(prefix='.agent-guards-approval.', dir=folder) try: with os.fdopen(fd, 'w', encoding='utf-8') as f: diff --git a/fork-kit/agent-guards/tests/actions-disable.test.py b/fork-kit/agent-guards/tests/actions-disable.test.py index fc17006d426a8..16c2d1b5eab61 100644 --- a/fork-kit/agent-guards/tests/actions-disable.test.py +++ b/fork-kit/agent-guards/tests/actions-disable.test.py @@ -1229,15 +1229,15 @@ def test_alias_import_file(self): # the owner's approval (lens B major): a root-owned file `sudo agent-guards approve` writes, and the code it # prints in the command. A session variable reached every nested agent; the old one now opens nothing. - def approve(self, hours=1, now=None): - """An approval file in this test's folder, owned by the test user (approval.PATH, approval.OWNER_UID); - (the approval module, the marker with its code).""" + def approve(self, command='gh workflow disable 1 -R a/b', hours=1, now=None, cwd=None): + """An approval of `command` run in this test's folder, in a file there owned by the test user + (approval.PATH, approval.OWNER_UID); (the approval module, the marker with its code).""" from agent_guards import approval for name, value in (('PATH', os.path.join(self.dir, 'etc', 'approval.json')), ('OWNER_UID', os.geteuid())): self.addCleanup(setattr, approval, name, getattr(approval, name)) setattr(approval, name, value) code = approval.new_code() - approval.write(code, hours, now=now) + approval.write(code, hours, command, cwd or self.dir, now=now) return approval, approval.MARK + code def test_the_old_variable_and_marker_open_nothing(self): @@ -1252,8 +1252,6 @@ def test_the_old_variable_and_marker_open_nothing(self): def test_an_approval_needs_the_owners_file_and_its_code(self): approval, mark = self.approve() cmd = 'gh workflow disable 1 -R a/b' - self.assertIsNone(self.decide(f'{cmd} {mark}')) - self.assertIsNone(self.decide(f'{cmd} {mark} (the owner asked for it in issue 9)')) self.assertIsNotNone(self.decide(cmd)) # no code: refused why = self.decide(f'{cmd} {approval.MARK}{approval.new_code()}') # a made-up code self.assertIn('not the one the owner approved', why) @@ -1261,15 +1259,84 @@ def test_an_approval_needs_the_owners_file_and_its_code(self): self.assertIsNotNone(self.decide(f'{cmd} {mark[:-1]}')) # not the code: shorter with open(approval.PATH) as f: self.assertNotIn(mark.rpartition(':')[2], f.read()) # only its hash is kept + self.assertIsNone(self.decide(f'{cmd} {mark}\n')) # blanks may differ + approval, mark = self.approve() self.assertTrue(approval.revoke()) self.assertIn('not there', self.decide(f'{cmd} {mark}')) + # lens B r2 major 2: the code travels in the command (transcript, app database, ps), so it must open only the + # one command the owner approved, in its folder, once + def test_r2_major2_an_approval_passes_only_the_approved_command(self): + approval, mark = self.approve('gh workflow disable 1 -R a/b') + for other in ('gh workflow disable 2 -R a/b', 'gh workflow disable 1 -R a/other', + 'gh api -X PUT repos/a/b/actions/permissions -F enabled=false', + 'gh workflow disable 1 -R a/b; gh workflow disable 2 -R a/b', + 'gh workflow disable 1 -R a/b && codex exec x'): + with self.subTest(other): + why = self.decide(f'{other} {mark}') + self.assertIsNotNone(why, other) + self.assertIn('approval is for another command', why) + why = self.decide(f'gh workflow disable 1 -R a/b {mark} (the owner asked for it)') # text after the code + self.assertIn('the marker must end the command', why) + self.assertIsNone(self.decide(f'gh workflow disable 1 -R a/b {mark}')) # the approved command itself + + def test_r2_major2_an_approval_is_used_up_by_one_run(self): + approval, mark = self.approve() + cmd = f'gh workflow disable 1 -R a/b {mark}' + self.assertIsNone(self.decide(cmd)) + why = self.decide(cmd) # the same command again + self.assertIsNotNone(why) + self.assertIn('used already', why) + # the same tool call's hook run twice (a hook wired twice) passes both times; another call does not + approval, mark = self.approve() + cmd = f'gh workflow disable 1 -R a/b {mark}' + state = os.path.join(self.dir, 'state') + self.assertEqual(approval.approved(cmd, self.dir, use_id='toolu_1', used_dir=state), (True, None)) + self.assertEqual(approval.approved(cmd, self.dir, use_id='toolu_1', used_dir=state), (True, None)) + self.assertFalse(approval.approved(cmd, self.dir, use_id='toolu_2', used_dir=state)[0]) + self.assertFalse(approval.approved(cmd, self.dir, use_id='toolu_1', used_dir=None)[0]) # nowhere to record + + def test_r2_major2_approving_again_ends_the_approval_before_it(self): + approval, first = self.approve() + approval, second = self.approve() + cmd = 'gh workflow disable 1 -R a/b' + self.assertIn('not the one the owner approved', self.decide(f'{cmd} {first}')) + self.assertIsNone(self.decide(f'{cmd} {second}')) + + def test_r2_major2_an_approval_is_for_one_folder(self): + os.makedirs(os.path.join(self.dir, 'other')) + approval, mark = self.approve(cwd=os.path.join(self.dir, 'other')) + cmd = f'gh workflow disable 1 -R a/b {mark}' + self.assertIn('for a command run in', self.decide(cmd)) # the test runs in self.dir + self.assertIsNone(self.g.decide(cmd, os.path.join(self.dir, 'other'), self.env)) + + def test_r2_major2_an_approval_file_in_the_old_format_is_no_approval(self): + import json as j, time + approval, mark = self.approve() + code = mark.rpartition(':')[2] + with open(approval.PATH, 'w') as f: # the version 1 file of the first draft: code hash and time only + j.dump({'version': 1, 'sha256': approval._hash(code), 'until': int(time.time() + 3600)}, f) + why = self.decide(f'gh workflow disable 1 -R a/b {mark}') + self.assertIsNotNone(why) + self.assertIn('not an approval file of this kit', why) + + def test_r2_major2_an_approval_killed_half_way_leaves_no_use_record_and_no_half_file(self): + approval, mark = self.approve() + state = os.path.join(self.dir, 'state') + os.makedirs(state) + with open(os.path.join(state, '.approval-used.left'), 'w') as f: # a temp file of a killed run + f.write('toolu_9') + cmd = f'gh workflow disable 1 -R a/b {mark}' + self.assertEqual(approval.approved(cmd, self.dir, use_id='toolu_1', used_dir=state), (True, None)) + etc = os.path.dirname(approval.PATH) + self.assertEqual([n for n in os.listdir(etc) if n.startswith('.')], []) # written whole, renamed + def test_an_approval_that_is_over_or_not_safe_opens_nothing(self): import time approval, mark = self.approve(hours=1, now=time.time() - 7200) - self.assertIn('the approval is over', self.decide(f'gh workflow disable 1 {mark}')) + self.assertIn('the approval is over', self.decide(f'gh workflow disable 1 -R a/b {mark}')) approval, mark = self.approve() - cmd = f'gh workflow disable 1 {mark}' + cmd = f'gh workflow disable 1 -R a/b {mark}' os.chmod(approval.PATH, 0o666) # an agent could write it self.assertIn('writable by group or others', self.decide(cmd)) os.chmod(approval.PATH, 0o644) @@ -1285,7 +1352,9 @@ def test_an_approval_that_is_over_or_not_safe_opens_nothing(self): f.write(text) self.assertIsNotNone(self.decide(cmd)) with self.assertRaises(ValueError): - approval.write(approval.new_code(), approval.MAX_HOURS + 1) + approval.write(approval.new_code(), approval.MAX_HOURS + 1, 'x', self.dir) + with self.assertRaises(ValueError): + approval.write(approval.new_code(), 1, ' ', self.dir) # no command # nested agent sessions (lens B minor): one without this machine's hooks would run anything def test_a_nested_session_without_the_hooks_is_refused(self): @@ -1312,7 +1381,7 @@ def test_a_nested_session_without_the_hooks_is_refused(self): self.assertIsNone(self.decide(cmd), cmd) def test_the_owner_can_approve_a_nested_session_too(self): - _approval, mark = self.approve() + _approval, mark = self.approve('codex exec x') self.assertIsNone(self.decide(f'codex exec x {mark}')) # rulesets: "evaluate" only reports, so it switches the rules off as "disabled" does (lens B minor) diff --git a/fork-kit/agent-guards/tests/wiring.test.py b/fork-kit/agent-guards/tests/wiring.test.py index 4baac946cd0a3..ce946ba0f2415 100644 --- a/fork-kit/agent-guards/tests/wiring.test.py +++ b/fork-kit/agent-guards/tests/wiring.test.py @@ -303,25 +303,41 @@ def test_check_as_root_runs_only_a_settings_file_only_root_can_write(self): self.assertEqual(self.cli.read_settings(os.path.join(self.tmp, 'w.json')), '{"hooks": {}}') def test_approve_prints_a_code_that_the_approval_takes(self): - code, out, err = self.main('approve', '--hours', '2') + code, out, err = self.main('approve', '--hours', '2', '--cwd', self.tmp, '--command', 'gh x 1') self.assertEqual(code, 0, err) mark = [w for w in out.split() if w.startswith(self.approval.MARK)] self.assertEqual(len(mark), 1, out) - self.assertEqual(self.approval.approved(f'gh x {mark[0]}'), (True, None)) + self.assertIn('once', out) + self.assertIn('gh x 1', out) # the command, as it is compared + self.assertFalse(self.approval.approved(f'gh y {mark[0]}', self.tmp, used_dir=self.tmp)[0]) self.assertEqual(oct(os.stat(self.approval.PATH).st_mode & 0o777), '0o644') code, out, _ = self.main('approve', '--revoke') self.assertEqual((code, os.path.exists(self.approval.PATH)), (0, False)) - self.assertFalse(self.approval.approved(f'gh x {mark[0]}')[0]) + self.assertFalse(self.approval.approved(f'gh x 1 {mark[0]}', self.tmp, used_dir=self.tmp)[0]) self.assertEqual(self.main('approve', '--revoke')[0], 0) # again: nothing there, still fine for hours in ('0', '25', '-1'): - self.assertEqual(self.main('approve', '--hours', hours)[0], 1) + self.assertEqual(self.main('approve', '--hours', hours, '--command', 'gh x')[0], 1) self.assertFalse(os.path.exists(self.approval.PATH)) self.cli.ROOT_UID = os.geteuid() + 1 - code, _out, err = self.main('approve') + code, _out, err = self.main('approve', '--command', 'gh x') self.assertEqual(code, 1) self.assertIn('run this as root', err) self.assertFalse(os.path.exists(self.approval.PATH)) + # lens B r2 major 2: an approval names the one command it is for + def test_r2_major2_approve_needs_the_command_and_the_code_passes_it_once(self): + for args in ((), ('--command', ''), ('--command', ' ')): + code, _out, err = self.main('approve', *args) + self.assertEqual(code, 1, args) + self.assertIn('name the one command you approve', err) + self.assertFalse(os.path.exists(self.approval.PATH)) + code, out, err = self.main('approve', '--cwd', self.tmp, '--command', 'gh x 1') + self.assertEqual(code, 0, err) + mark = [w for w in out.split() if w.startswith(self.approval.MARK)][0] + used = os.path.join(self.tmp, 'state') + self.assertEqual(self.approval.approved(f'gh x 1 {mark}', self.tmp, used_dir=used), (True, None)) + self.assertFalse(self.approval.approved(f'gh x 1 {mark}', self.tmp, used_dir=used)[0]) # used up + def test_self_check_names_links_root_ways_and_the_approval(self): self.cli.root_ways = lambda user: [f'{user} is in the docker group (a container can write any root file)'] links = os.path.join(self.tmp, 'links') @@ -338,7 +354,7 @@ def test_self_check_names_links_root_ways_and_the_approval(self): self.assertIn('docker group', text) with open(drop_in, 'w') as f: # wired: the same is a problem f.write(wiring.drop_in_text()) - self.approval.write(self.approval.new_code(), 1) + self.approval.write(self.approval.new_code(), 1, 'gh x', self.tmp) out = io.StringIO() with contextlib.redirect_stdout(out): code = self.cli.self_check(fx.BIN, drop_in, links) From d249b386b90bbd6a088a4a2259271ba623a986fe Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 04:20:33 +0000 Subject: [PATCH 5/9] fork-kit/agent-guards: refuse hookless agent sessions by path, package and wrapper, and say what the guards are not (lens B r2 major 1) A list of strings cannot be complete, so this does both things the review asked for: (a) Wider detection where it is cheap and reliable. claude and codex now count by name, by their real program path (.../claude/versions/, the @anthropic-ai/claude-code and @openai/codex packages), as a link to or a copy of the installed program, through npx, bunx, pnpm dlx, npm exec, bun x and `node `, behind `$(which claude)`, and inside python -c, node -e, perl -e, at, systemd-run and the other wrappers already read for gh. CLAUDE_CODE_SIMPLE counts in the command, through env -S, in a sourced file, in BASH_ENV/--rcfile and in the user's shell start files. (b) The threat model, written plainly in the README ("What the guards are and are not") and the guard's docstring: the guards stop mistakes and casual misuse; they are not a boundary against a hostile agent; the boundary is the GitHub permissions of the agent's token (a fine-grained token without Actions and Administration write is the recommended setup). Codex arguments are now read option by option (an option's value is not taken for the subcommand), because the new path and package forms need it; the separate codex nits follow in their own commit. Tests: LensSecurityR2Test.test_r2_major1_* (each fails on 6d5047d4). Co-Authored-By: Claude Opus 5.5 --- fork-kit/agent-guards/README.md | 42 ++- .../agent-guards/bin/actions-disable-guard | 273 ++++++++++++++++-- .../tests/actions-disable.test.py | 87 ++++++ 3 files changed, 375 insertions(+), 27 deletions(-) diff --git a/fork-kit/agent-guards/README.md b/fork-kit/agent-guards/README.md index 790e2c88d5cc8..1eeeff3da5259 100644 --- a/fork-kit/agent-guards/README.md +++ b/fork-kit/agent-guards/README.md @@ -9,13 +9,13 @@ Linux, Python 3 standard library only. One file per hook in [bin/](bin/), the sh ## The hooks -| Hook | Event (matcher) | Refuses | If the hook is missing or fails | -| ----------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -| `actions-disable-guard` | PreToolUse (`Bash\|Monitor`), 10 s, `onFailure: block` | Disabling a GitHub Actions workflow or Actions itself, or deleting or weakening branch protection or rulesets (`enforcement` set to `disabled` or `evaluate`), on any repo (`gh workflow disable`, `gh api .../actions/workflows//disable`, ...). Also a listed script run with its listed flag (`refuseScripts`), and starting a nested agent session that runs without this machine's hooks (`claude --bare`, `--safe-mode`, `CLAUDE_CODE_SIMPLE`, `codex`). | **Refuses** (exit 2): every Bash and Monitor command is refused until it is back, with a line saying so | -| `capacity-pipe-guard` | PreToolUse (`Bash\|Monitor`), 10 s | A pipe out of a capacity check (`t3-capacity 2048 \| tail -1 && heavy-step`): the pipe hides the check's NOT OK exit | Passes (exit 1, "hook skipped, commands are NOT checked") | -| `memory-index-guard` | PreToolUse (`Write\|Edit\|MultiEdit`) and PostToolUse (`Write\|Edit\|MultiEdit\|Bash\|Monitor`), 5 s | An auto-memory index (`/memory/MEMORY.md`) over its budget: a write that would make it too big (Pre), or one that did, through any tool (Post, once per change) | Passes (exit 1, with a line) | -| `bg-guard` | Stop, 5 s | Ending a turn while a Bash command the agent started in the background still runs (the end of it may never wake the agent). At most `maxBlocks` times per session | Passes (exit 1, with a line) | -| `agent-slots` | UserPromptSubmit and Stop, 5 s | Only for the orchestrator sessions listed in `sessionsFile`: adds "agents alive, slots free, ready queue" as context; blocks a stop once while slots are free and the ready queue has items | Passes (exit 1, with a line) | +| Hook | Event (matcher) | Refuses | If the hook is missing or fails | +| ----------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `actions-disable-guard` | PreToolUse (`Bash\|Monitor`), 10 s, `onFailure: block` | Disabling a GitHub Actions workflow or Actions itself, or deleting or weakening branch protection or rulesets (`enforcement` set to `disabled` or `evaluate`), on any repo (`gh workflow disable`, `gh api .../actions/workflows//disable`, ...). Also a listed script run with its listed flag (`refuseScripts`), and starting a nested agent session that runs without this machine's hooks (`claude --bare`, `--safe-mode`, `CLAUDE_CODE_SIMPLE`, `codex`, by name, path or package). | **Refuses** (exit 2): every Bash and Monitor command is refused until it is back, with a line saying so | +| `capacity-pipe-guard` | PreToolUse (`Bash\|Monitor`), 10 s | A pipe out of a capacity check (`t3-capacity 2048 \| tail -1 && heavy-step`): the pipe hides the check's NOT OK exit | Passes (exit 1, "hook skipped, commands are NOT checked") | +| `memory-index-guard` | PreToolUse (`Write\|Edit\|MultiEdit`) and PostToolUse (`Write\|Edit\|MultiEdit\|Bash\|Monitor`), 5 s | An auto-memory index (`/memory/MEMORY.md`) over its budget: a write that would make it too big (Pre), or one that did, through any tool (Post, once per change) | Passes (exit 1, with a line) | +| `bg-guard` | Stop, 5 s | Ending a turn while a Bash command the agent started in the background still runs (the end of it may never wake the agent). At most `maxBlocks` times per session | Passes (exit 1, with a line) | +| `agent-slots` | UserPromptSubmit and Stop, 5 s | Only for the orchestrator sessions listed in `sessionsFile`: adds "agents alive, slots free, ready queue" as context; blocks a stop once while slots are free and the ready queue has items | Passes (exit 1, with a line) | How each hook answers is what Claude Code reads: PreToolUse refuses with exit 2 and the reason on stderr. PostToolUse and Stop block with `{"decision": "block", "reason": ...}` on stdout. UserPromptSubmit adds `additionalContext`. @@ -45,9 +45,16 @@ well inside its 10 s. **Nested agent sessions.** Managed hooks run in every Claude Code session, a nested `claude -p` too, whatever its own settings say (`disableAllHooks` in a user's or a `--settings` file does not turn managed hooks off). A bare -session (`claude --bare`, `--safe-mode`, `CLAUDE_CODE_SIMPLE`) and Codex (`codex`, `codex exec`) run none of them, -so `actions-disable-guard` refuses starting one (`codex login`, `logout`, `help` and `--version` pass). This is a -command check like the others: it does not see a session started by a program the guard does not read. +session (`claude --bare`, `CLAUDE_CODE_SIMPLE`) and Codex (`codex`, `codex exec`, `codex review` ...) run none of +them, so `actions-disable-guard` refuses starting one (`codex login`, `logout`, `help`, `completion` and +`--version` pass). `claude --safe-mode` is refused too: it runs managed hooks, but not hooks a user wired by hand in +user settings (the `agent-guards hooks` route, below). The guard knows claude and codex by name, by their program +path (`.../claude/versions/`, the `@anthropic-ai/claude-code` and `@openai/codex` packages), as a link to or a +copy of the installed program, through `npx`, `bunx`, `pnpm dlx`, `npm exec`, `bun x` and `node `, behind +`$(which claude)`, and inside `python -c`, `node -e`, `at`, `systemd-run` and the other wrappers it reads for `gh`. +It sees `CLAUDE_CODE_SIMPLE` in the command, through `env -S`, in a file the command sources, in `BASH_ENV` or +`--rcfile`, and in the agents' user's shell start files (`~/.bashrc` ...; files those read in turn are not +followed). This is a list of forms, so it is not complete: see the next section. **The owner's approval.** Only the owner can let one refused command through, as root, in the folder the command will run in (or with `--cwd DIR`): @@ -71,6 +78,21 @@ others, no link), at most 24 hours. An earlier draft used a session environment inherited it, so it is not read any more. Anyone who can become root without a password (sudo `NOPASSWD`, the `docker` group) can write the file: `agent-guards self-check` warns about both for the agents' user. +## What the guards are and are not + +The guards stop **mistakes and casual misuse** by an agent: a command typed from habit, a step copied from an old +note, an agent that takes a short cut it was told not to take. Each refusal says why, and the agent goes another +way. They are **not a security boundary against a hostile agent**. They read shell text before it runs, and text +can always be built so that no reader sees what it does until it runs: words made at run time, a program the guard +does not know (another agent program, a script, an MCP tool that starts a session), a file read by a file the +command sources. A guard that claimed to stop those would be claiming more than the code does. + +The real boundary is **the GitHub permissions of the token the agent holds**. The recommended setup: give agents a +fine-grained token for the repos they work on, without the Actions (write) and Administration (write) permissions, +so turning off a workflow, Actions, or a ruleset fails at GitHub whatever command asks for it; keep the token that +can do that with the owner. The guards then catch the mistake earlier, with a reason, and the token holds when they +miss one. + ## Settings (the machine file) Every key is optional. With no machine file, or no `"agent-guards"` section, each hook uses the defaults below. diff --git a/fork-kit/agent-guards/bin/actions-disable-guard b/fork-kit/agent-guards/bin/actions-disable-guard index e1426ec93231e..bc9e2201c128a 100755 --- a/fork-kit/agent-guards/bin/actions-disable-guard +++ b/fork-kit/agent-guards/bin/actions-disable-guard @@ -125,18 +125,25 @@ every nested `claude -p` or `codex exec` of the session.) Fails closed: an inter look dangerous. Nested agents: a command that starts an agent session this machine's hooks do not reach is refused, since that -session could do what this guard refuses: `claude --bare` / `--safe-mode`, `claude` with CLAUDE_CODE_SIMPLE set in -the same command, and `codex` with anything but login/logout/help/completion/--version (codex runs no Claude Code -hooks). A nested `claude -p` passes: managed hooks run there too, also with `--settings '{"disableAllHooks": -true}'` (settings outside managed settings cannot turn managed hooks off). Not covered: other agent programs, and -an agent started by a program the guard does not read (a Python script, a container). +session could do what this guard refuses: `claude --bare` / `--safe-mode` (safe mode runs managed hooks, but not +hooks a user wired by hand in user settings), `claude` with CLAUDE_CODE_SIMPLE set, and `codex` with anything but +login/logout/help/completion/--version (codex runs no Claude Code hooks). claude and codex count by name, by +their program path (.../claude/versions/, @anthropic-ai/claude-code, @openai/codex), as a link to or a copy of +the installed program, as a name the same command gives one (ln -s), through npx/bunx/pnpm dlx/npm exec/bun x and +`node `, behind `$(which claude)`, and as text in python -c, node -e, at, systemd-run .. (the same token +reading as for gh). CLAUDE_CODE_SIMPLE counts in the command, through env -S, from a file the command sources, from +BASH_ENV/--rcfile, and from the agents' user's shell start files (~/.bashrc ..; files those read are not followed). +A nested `claude -p` passes: managed hooks run there too, also with `--settings '{"disableAllHooks": true}'`. +This is a list, and a list of strings cannot be complete: it stops mistakes and casual misuse, not an agent set on +getting round it (other agent programs, an MCP tool that starts one, words built at run time). The wall against +that is the GitHub permissions of the token the agent holds (README, "What the guards are and are not"). Facts from the machine file (fork-kit/agent-guards/README.md): actionsDisable.stateDir (cache and log of refusals, default ~/.local/state/actions-disable-guard) and actionsDisable.refuseScripts (default none). A missing machine file or section gives those defaults; a broken one too, with one line on stderr: the guard never weakens. Tests: fork-kit/agent-guards/tests/actions-disable.test.py """ -import fnmatch, itertools, json, os, re, signal, sys, time +import fnmatch, itertools, json, os, re, shlex, signal, sys, time from stat import S_ISDIR, S_ISREG from urllib.parse import unquote @@ -185,7 +192,7 @@ WRAPPERS = {'sudo', 'doas', 'env', 'command', 'exec', 'builtin', 'nohup', 'time' 'stdbuf', 'xargs', 'setsid', 'unbuffer', 'chronic', 'flock', 'eval', 'source', '.', 'do', 'then', 'else', 'elif', 'if', 'while', 'until', '{', '}', '!', 'watch', 'script', 'runuser', 'systemd-run', 'coproc'} | SHELLS -ARG_FLAGS = {'-u', '-g', '-n', '-k', '-s', '-I', '-P', '-L', '-d', '-E', '-C', '-p', '-o', '-e', '-i', '-l', +ARG_FLAGS = {'-u', '-g', '-n', '-k', '-s', '-I', '-P', '-L', '-d', '-E', '-C', '-p', '-o', '-e', '-i', '-l', '-a', '--user', '--group', '--signal', '--kill-after', '--unit'} TEXT_ARGS = {'trap', 'ssh', 'su', 'parallel'} # commands whose quoted arguments are shell text SETTERS = {'export', 'local', 'declare', 'typeset', 'readonly'} @@ -2012,7 +2019,8 @@ def cache_save(ctx): # \uXXXX is four digits and no more (JSON, JS, Python, Go): in \u0070ermissions the `e` is the next letter ESCAPES = re.compile(r'\\+(?:u([0-9a-fA-F]{4})|u\{([0-9a-fA-F]{1,6})\}|U([0-9a-fA-F]{8})|x([0-9a-fA-F]{2}))' r'|\\+([0-3][0-7]{2})|%([0-9a-fA-F]{2})') -CUES = ('disable', 'permissions', 'protection', 'ruleset') +AGENT_LABEL = 'an agent session without this machine\'s hooks (`claude --bare`, CLAUDE_CODE_SIMPLE, `codex exec`)' +CUES = ('disable', 'permissions', 'protection', 'ruleset', 'bare', 'safe-mode', 'claude_code_simple', 'codex') # What may not be changed, as it looks after canon(): wherever one of these shows up, the command passes only when # the guard can prove it is harmless (a plain read, a known allowed form, or text that goes nowhere unread). TOKENS = [ @@ -2023,6 +2031,15 @@ TOKENS = [ ('a ruleset', re.compile(r'(? 2): + v = a.partition('=')[2] if a.startswith('--') else a[2:] + return ' '.join([v] + [shlex.quote(x) for x in toks[j + 1:]]) + if not a.startswith('-') and not is_assign(a): + break + return None + + +def claude_starts(args): + """Whether claude with these words starts a session (not `claude --version`, `claude mcp list` ..).""" + return not any(a in CLAUDE_TOOLS for a in args[:1]) and not any(a in ('--version', '-v', '--help', '-h') + for a in args) + + +def codex_sub(args): + """codex's subcommand: the first word that is no option and no option's value (`codex -m o3 exec x`: exec), + or a safe option (--version); None for the interactive session.""" + i = 0 + while i < len(args): + a = args[i] + if a in CODEX_SAFE and a.startswith('-'): + return a + if a == '--': + return args[i + 1] if i + 1 < len(args) else None + if a in CODEX_VALUE: + i += 2 + continue + if not a.startswith('-'): + return a + i += 1 return None @@ -2675,11 +2902,17 @@ def segment_reason(toks, ctx, loose): if why: return reason(why, 'Run the work in this session (or a nested `claude -p` without --bare), or ask the ' 'owner.') + split = env_split(toks) + if split: # env -S 'A=1 cmd x': read the text env runs as a command + r = decide_text(split, ctx) + if r: + return r flow = ctx['flow'] for j in flag_values(toks, h): # the other reading: the flag takes no value and the word starts the command base = os.path.basename(toks[j]) if base in SHELLS or base in NET_CLIENTS or base in TEXT_ARGS or base in AWKS or INTERPRETERS.match(base) \ - or is_gh(toks[j], ctx) or (not hidden(toks[j]) and cmd_files(toks[j], ctx, True)): + or is_gh(toks[j], ctx) or (not hidden(toks[j]) and cmd_files(toks[j], ctx, True)) \ + or base in PKG_RUNNERS or agent_kind(toks[j], ctx): r = segment_reason(toks[:j - 1] + toks[j:], ctx, loose) if r: return r @@ -3043,6 +3276,12 @@ def decide_text(text, ctx, scan_raw=True): gh_set += [a for a in text_aliases(toks, stdin_of(cmd, env, c), c) if a not in gh_set] c['gh_set'] = gh_set c['ghs'] = set(ctx.get('ghs', ())).union(*(gh_names(toks) for _, variants in runs for toks in variants if toks)) + c['agents'] = dict(ctx.get('agents', {})) + for _, variants in runs: + for toks in (t for t in variants if t): + c['agents'].update(agent_names(toks, c)) + c['sourced'] = list(ctx.get('sourced', ())) + [f for _, variants in runs for toks in variants[:1] if toks + for f in sourced_files(toks)] # Where each command's text goes on: into a file, into another command's words ($(..)), or down a pipe that # does not end in a word that only handles text. tgts = [[t for op, w in cmd['redirs'] if op.startswith('>') for t in redir_texts(op, w, env) diff --git a/fork-kit/agent-guards/tests/actions-disable.test.py b/fork-kit/agent-guards/tests/actions-disable.test.py index 16c2d1b5eab61..eebe90067f6c4 100644 --- a/fork-kit/agent-guards/tests/actions-disable.test.py +++ b/fork-kit/agent-guards/tests/actions-disable.test.py @@ -2036,6 +2036,93 @@ def test_r2_minor1_graphql_update_with_evaluate_in_a_variable_is_refused(self): # the same call that keeps the ruleset on passes self.assertIsNone(self.decide(f"gh api graphql -f query='{mut}' -F e=ACTIVE")) + # lens B r2 major 1: a nested session without this machine's hooks, started in a form the first list missed + def agents(self): + """A stand-in install in the test folder: bin/claude, bin/codex on PATH, a native version folder.""" + for rel, text in (('bin/claude', '#!/bin/sh\n# stand-in claude ' + 'c' * 200 + '\n'), + ('bin/codex', '#!/bin/sh\n# stand-in codex ' + 'x' * 300 + '\n'), + ('share/claude/versions/2.1.9', '#!/bin/sh\n# stand-in native build\n')): + self.write(rel, text, 0o755) + self.env = dict(self.env, PATH=os.path.join(self.dir, 'bin')) + return os.path.join(self.dir, 'share/claude/versions/2.1.9') + + def assert_refused(self, cmds, part=None): + for cmd in cmds: + with self.subTest(cmd): + why = self.decide(cmd) + self.assertIsNotNone(why, cmd) + if part: + self.assertIn(part, why) + + def assert_passed(self, cmds): + for cmd in cmds: + with self.subTest(cmd): + self.assertIsNone(self.decide(cmd), cmd) + + def test_r2_major1_the_real_program_path_a_link_or_a_copy_of_claude_or_codex_is_refused(self): + ver = self.agents() + os.symlink(ver, os.path.join(self.dir, 'cc')) + os.symlink(os.path.join(self.dir, 'bin/claude'), os.path.join(self.dir, 'c2')) + import shutil + shutil.copy(os.path.join(self.dir, 'bin/claude'), os.path.join(self.dir, 'mine')) + shutil.copy(os.path.join(self.dir, 'bin/codex'), os.path.join(self.dir, 'cx')) + self.assert_refused([f'{ver} --bare -p x', '~/share/claude/versions/2.1.9 --bare -p x', + './cc --bare -p x', './c2 --safe-mode -p x', './mine --bare -p x', + f'ln -s {ver} ./new && ./new --bare -p x', 'ln -s "$(which claude)" n2 && ./n2 --bare', + '$(which claude) --bare -p x', '"$(command -v claude)" --bare -p x', + '`which claude` --bare -p x', './cx exec x', './cx', '"$(which codex)" exec x']) + self.assert_passed(['./cc -p x', './mine --version', './cx login', 'git clone --bare https://example.com/x', + 'git init --bare x.git', f'ls -la {ver}']) + + def test_r2_major1_npx_bunx_pnpm_dlx_and_node_of_the_packages_are_refused(self): + self.write('node_modules/@anthropic-ai/claude-code/cli.js', '// stand-in\n', 0o644) + self.assert_refused([ + 'npx @anthropic-ai/claude-code --bare -p x', 'npx -y @anthropic-ai/claude-code@latest --bare -p x', + 'bunx @anthropic-ai/claude-code --bare -p x', 'pnpm dlx @anthropic-ai/claude-code --safe-mode -p x', + 'pnpx @anthropic-ai/claude-code --bare', 'yarn dlx @anthropic-ai/claude-code --bare', + 'npm exec -- @anthropic-ai/claude-code --bare -p x', 'npm x @anthropic-ai/claude-code --bare', + 'bun x @anthropic-ai/claude-code --bare', 'node node_modules/@anthropic-ai/claude-code/cli.js --bare -p x', + 'node /usr/lib/node_modules/@anthropic-ai/claude-code/cli.js --bare -p x', + 'npx @openai/codex exec x', 'npx -y @openai/codex exec x', 'npx -y @openai/codex', 'npx @openai/codex@0.9', + 'pnpm dlx @openai/codex e x', 'npm exec --package=@openai/codex -- codex exec x', + 'npm exec -p @openai/codex codex', 'bunx @openai/codex review']) + self.assert_passed(['npx @anthropic-ai/claude-code -p x', 'npx prettier --check .', + 'npm install -g @openai/codex', 'npm install -g @anthropic-ai/claude-code', + 'npx -y @openai/codex login', 'npm exec -- eslint .', 'pnpm dlx create-vite x']) + + def test_r2_major1_the_wrappers_refused_for_gh_are_refused_for_a_hookless_session(self): + self.assert_refused([ + 'python3 -c \'import os; os.system("claude --bare -p x")\'', + 'node -e \'require("child_process").execSync("claude --bare -p x")\'', + 'perl -e \'system("claude --bare -p x")\'', 'python3 -c \'import os; os.system("codex exec x")\'', + 'ruby -e \'system("codex -m o3 exec x")\'', 'at now <<< \'claude --bare -p x\'', + 'echo "claude --bare -p x" | at now', 'systemd-run --user claude --bare -p x', + 'systemd-run --user codex exec x', 'exec -a foo claude --bare -p x', 'exec -a foo codex exec x', + 'CLAUDE_CODE_SIMPLE=1 python3 -c \'import os; os.system("claude -p x")\'', + 'python3 -c \'import os; os.environ["CLAUDE_CODE_SIMPLE"] = "1"; os.system("claude -p x")\'']) + self.assert_passed(['python3 -c \'print("claude")\'', 'echo "codex exec x"', + 'git commit -m "no claude --bare here"', 'grep -rn CLAUDE_CODE_SIMPLE .', + 'gh pr comment 1 --body "claude --bare is refused"', 'codex help exec']) + + def test_r2_major1_claude_code_simple_from_a_file_or_env_split_string_is_refused(self): + self.write('e.env', 'CLAUDE_CODE_SIMPLE=1\n', 0o644) + self.write('ok.env', 'A=1\n', 0o644) + self.write('venv/bin/activate', 'export VIRTUAL_ENV=x\n', 0o644) + self.assert_refused([ + '. ./e.env; claude -p x', 'source ./e.env && claude -p x', 'set -a; . ./e.env; set +a; claude -p x', + '. "$F"; claude -p x', '. ./missing.env; claude -p x', 'env $(cat e.env) claude -p x', + 'env $(cat ok.env) claude -p x', 'env -S \'CLAUDE_CODE_SIMPLE=1 claude -p x\'', + 'env -S"CLAUDE_CODE_SIMPLE=1 claude -p x"', 'env --split-string=\'CLAUDE_CODE_SIMPLE=1 claude -p x\'', + 'BASH_ENV=./e.env bash -c \'claude -p x\'', 'bash --rcfile ./e.env -ic \'claude -p x\'']) + self.assert_passed(['. ./ok.env; claude -p x', '. ./venv/bin/activate && python3 -V', + 'env -S \'A=1 claude -p x\'', 'source ./e.env && claude --version', + 'bash -lc \'claude -p x\'', 'bash -ic \'ls\'']) + # the agents' user's own shell start files: a session the Bash tool or `bash -l` starts may read them + self.write('.bashrc', 'export CLAUDE_CODE_SIMPLE=1\n', 0o644) + self.assert_refused(['claude -p x', 'bash -lc \'claude -p x\'', 'bash -ic \'claude -p x\''], + '.bashrc names CLAUDE_CODE_SIMPLE') + self.assert_passed(['claude --version', 'claude mcp list', 'bash -lc \'ls\'']) + class FastExitTest(Case): """#1752 fix point 1: plain commands pass before any file is read or the clock matters, and nothing the full From 325132b9210d9d780cc0e62aa24b57f4f92933c2 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 04:20:58 +0000 Subject: [PATCH 6/9] fork-kit/agent-guards: codex arguments are read option by option; codex mcp passes (lens A r2 nit) `codex -m o3 exec x` is now refused as `codex exec` (the option's value is no longer taken for the subcommand), `codex mcp list` (MCP setup, no session) passes, and `npx -y @openai/codex exec x` is refused (the package form came with the major-1 commit). `codex mcp-server` stays refused. Test: LensSecurityR2Test.test_r2_nit_codex_arguments_name_the_right_subcommand_mcp_passes_npx_refused. Co-Authored-By: Claude Opus 5.5 --- fork-kit/agent-guards/README.md | 19 ++++++++++--------- .../agent-guards/bin/actions-disable-guard | 4 ++-- .../tests/actions-disable.test.py | 12 ++++++++++++ 3 files changed, 24 insertions(+), 11 deletions(-) diff --git a/fork-kit/agent-guards/README.md b/fork-kit/agent-guards/README.md index 1eeeff3da5259..42cd0d1f3a405 100644 --- a/fork-kit/agent-guards/README.md +++ b/fork-kit/agent-guards/README.md @@ -46,15 +46,16 @@ well inside its 10 s. **Nested agent sessions.** Managed hooks run in every Claude Code session, a nested `claude -p` too, whatever its own settings say (`disableAllHooks` in a user's or a `--settings` file does not turn managed hooks off). A bare session (`claude --bare`, `CLAUDE_CODE_SIMPLE`) and Codex (`codex`, `codex exec`, `codex review` ...) run none of -them, so `actions-disable-guard` refuses starting one (`codex login`, `logout`, `help`, `completion` and -`--version` pass). `claude --safe-mode` is refused too: it runs managed hooks, but not hooks a user wired by hand in -user settings (the `agent-guards hooks` route, below). The guard knows claude and codex by name, by their program -path (`.../claude/versions/`, the `@anthropic-ai/claude-code` and `@openai/codex` packages), as a link to or a -copy of the installed program, through `npx`, `bunx`, `pnpm dlx`, `npm exec`, `bun x` and `node `, behind -`$(which claude)`, and inside `python -c`, `node -e`, `at`, `systemd-run` and the other wrappers it reads for `gh`. -It sees `CLAUDE_CODE_SIMPLE` in the command, through `env -S`, in a file the command sources, in `BASH_ENV` or -`--rcfile`, and in the agents' user's shell start files (`~/.bashrc` ...; files those read in turn are not -followed). This is a list of forms, so it is not complete: see the next section. +them, so `actions-disable-guard` refuses starting one (`codex login`, `logout`, `help`, `completion`, `mcp` (setup, +not a session; `mcp-server` is refused) and `--version` pass). `claude --safe-mode` is refused too: it runs managed +hooks, but not hooks a user wired by hand in user settings (the `agent-guards hooks` route, below). The guard knows +claude and codex by name, by their program path (`.../claude/versions/`, the `@anthropic-ai/claude-code` and +`@openai/codex` packages), as a link to or a copy of the installed program, through `npx`, `bunx`, `pnpm dlx`, `npm +exec`, `bun x` and `node `, behind `$(which claude)`, and inside `python -c`, `node -e`, `at`, +`systemd-run` and the other wrappers it reads for `gh`. It sees `CLAUDE_CODE_SIMPLE` in the command, through `env +-S`, in a file the command sources, in `BASH_ENV` or `--rcfile`, and in the agents' user's shell start files +(`~/.bashrc` ...; files those read in turn are not followed). This is a list of forms, so it is not complete: see +the next section. **The owner's approval.** Only the owner can let one refused command through, as root, in the folder the command will run in (or with `--cwd DIR`): diff --git a/fork-kit/agent-guards/bin/actions-disable-guard b/fork-kit/agent-guards/bin/actions-disable-guard index bc9e2201c128a..fdd5753739158 100755 --- a/fork-kit/agent-guards/bin/actions-disable-guard +++ b/fork-kit/agent-guards/bin/actions-disable-guard @@ -127,7 +127,7 @@ look dangerous. Nested agents: a command that starts an agent session this machine's hooks do not reach is refused, since that session could do what this guard refuses: `claude --bare` / `--safe-mode` (safe mode runs managed hooks, but not hooks a user wired by hand in user settings), `claude` with CLAUDE_CODE_SIMPLE set, and `codex` with anything but -login/logout/help/completion/--version (codex runs no Claude Code hooks). claude and codex count by name, by +login/logout/help/completion/mcp/--version (codex runs no Claude Code hooks). claude and codex count by name, by their program path (.../claude/versions/, @anthropic-ai/claude-code, @openai/codex), as a link to or a copy of the installed program, as a name the same command gives one (ln -s), through npx/bunx/pnpm dlx/npm exec/bun x and `node `, behind `$(which claude)`, and as text in python -c, node -e, at, systemd-run .. (the same token @@ -2663,7 +2663,7 @@ def flag_values(toks, h): return [i for i in range(1, end) if toks[i - 1] in ARG_FLAGS and not toks[i].startswith('-')] -CODEX_SAFE = {'login', 'logout', 'help', 'completion', '--version', '-V', '--help', '-h'} +CODEX_SAFE = {'login', 'logout', 'help', 'completion', 'mcp', '--version', '-V', '--help', '-h'} # codex's options that take a value (codex --help): `codex -m o3 exec x` runs `exec`, not `o3` CODEX_VALUE = {'-c', '--config', '--enable', '--disable', '--remote', '--remote-auth-token-env', '-i', '--image', '-m', '--model', '--local-provider', '-p', '--profile', '-s', '--sandbox', '-C', '--cd', '--add-dir', diff --git a/fork-kit/agent-guards/tests/actions-disable.test.py b/fork-kit/agent-guards/tests/actions-disable.test.py index eebe90067f6c4..310a0ea92c66c 100644 --- a/fork-kit/agent-guards/tests/actions-disable.test.py +++ b/fork-kit/agent-guards/tests/actions-disable.test.py @@ -2123,6 +2123,18 @@ def test_r2_major1_claude_code_simple_from_a_file_or_env_split_string_is_refused '.bashrc names CLAUDE_CODE_SIMPLE') self.assert_passed(['claude --version', 'claude mcp list', 'bash -lc \'ls\'']) + def test_r2_nit_codex_arguments_name_the_right_subcommand_mcp_passes_npx_refused(self): + # an option's value is not the subcommand: the message names `codex exec`, not `codex o3` + for cmd in ('codex -m o3 exec x', 'codex --model o3 -C /tmp exec x', 'codex -c a=b -s read-only exec x'): + with self.subTest(cmd): + why = self.decide(cmd) + self.assertIsNotNone(why, cmd) + self.assertIn('`codex exec`', why) + # `codex mcp ...` sets up MCP servers; it starts no agent session + self.assert_passed(['codex mcp list', 'codex mcp add x -- y', 'codex -p work mcp list']) + # `codex mcp-server` runs codex as a server for another agent: still refused + self.assert_refused(['codex mcp-server', 'npx -y @openai/codex exec x', 'npx -y @openai/codex mcp-server']) + class FastExitTest(Case): """#1752 fix point 1: plain commands pass before any file is read or the clock matters, and nothing the full From 2dffcfc98015599cd1977cf14bd7ceefb72cf85b Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 04:25:23 +0000 Subject: [PATCH 7/9] fork-kit/agent-guards: uninstall finds sessions by program path, refuses inside a hooked session, remembers hand-wired entries (lens B r2 minor 2, lens A r2 minors 1 and 2) - Sessions are found by the real path of their program (/proc//exe: the native build in .../claude/versions/ under any name, the @anthropic-ai/claude-code script node runs through any link, an installed `claude`), not by the process name alone. - The uninstall's own ancestors are no longer skipped: run from inside a Claude Code session that has the hooks, it refuses and says to run it from a terminal. - A refusal for a hand-wired entry is remembered (/etc/agent-guards/hand-wired-seen.json, removed with /etc/agent-guards); the next run then counts every session older than itself, as does a run where the drop-in was never on. A broken record counts as seen now. - The project .claude/settings*.json of each running session's working folder (and the folders above it) is searched too. Tests: Install.test_r2_minorB2_*, test_r2_minorA1_*, test_r2_minorA2_* and test_r2_state_* (each fails on 6d5047d4). Co-Authored-By: Claude Opus 5.5 --- fork-kit/agent-guards/README.md | 11 +- .../agent-guards/sbin/agent-guards-install | 210 +++++++++++++----- fork-kit/agent-guards/tests/install.test.py | 124 ++++++++++- 3 files changed, 280 insertions(+), 65 deletions(-) diff --git a/fork-kit/agent-guards/README.md b/fork-kit/agent-guards/README.md index 42cd0d1f3a405..fe69833afe42b 100644 --- a/fork-kit/agent-guards/README.md +++ b/fork-kit/agent-guards/README.md @@ -152,9 +152,14 @@ already running keep the hooks they started with. `--no-settings` removes it; th neither keeps the last one (a first install: no drop-in). The installer refuses to overwrite a drop-in of that name it did not write. -Uninstall refuses while a settings file the kit did not write (a user's `~/.claude/settings.json`, say) still names -a hook: removing the file would make that entry fail. Otherwise it removes the drop-in first, then refuses while a -Claude Code session started before that still runs (it has the hooks loaded); run it again when those have ended. +Uninstall refuses while a settings file the kit did not write (a user's `~/.claude/settings.json`, or the project +`.claude/settings*.json` of a folder a running session works in) still names a hook: removing the file would make +that entry fail. Otherwise it removes the drop-in first, then refuses while a Claude Code session started before +that still runs (it has the hooks loaded); run it again when those have ended. It finds sessions by the real path of +their program (`/proc//exe`, the script node runs), so a renamed link to Claude Code counts too. When it once +saw a hand-wired entry, or the drop-in was never on, every session older than the uninstall counts, since such a +session may have read an entry that is gone now. Run uninstall from a terminal: from inside a session that has the +hooks it refuses, because that session would lose them. To take the hooks out of new sessions at once and keep the files, run the installer with `--no-settings` (the rollback). diff --git a/fork-kit/agent-guards/sbin/agent-guards-install b/fork-kit/agent-guards/sbin/agent-guards-install index 635efc631d138..3142df404263c 100755 --- a/fork-kit/agent-guards/sbin/agent-guards-install +++ b/fork-kit/agent-guards/sbin/agent-guards-install @@ -16,11 +16,14 @@ hook it names is always there. Safe to run again, and to stop at any step; one i kit shares are in fork-kit/common/kit_install.py. Rolling back is `install --no-settings`: the hooks stay, new sessions no longer run them. A session that started -while the drop-in was there keeps running the hooks it started with, so uninstall (which removes the hook files) -refuses while such a session runs (a `claude` process older than the drop-in's removal, kept as "settingsOff" in -config.json), and while a settings file the kit did not write names a kit hook (managed-settings.json, another -managed-settings.d file, a user's ~/.claude*/settings*.json): a hook that is gone refuses every Bash command -there. Uninstall with the drop-in still there removes it first, then checks. +while the hooks were wired keeps running the hooks it started with, so uninstall (which removes the hook files) +refuses while a settings file the kit did not write names a kit hook (managed-settings.json, another +managed-settings.d file, a user's ~/.claude*/settings*.json, a running session's project .claude/settings*.json), +and while such a session runs: a Claude Code process (found by the real path of its program, not its name) older +than the drop-in's removal ("settingsOff" in config.json), or older than this uninstall when a hand-wired entry was +seen before (hand-wired-seen.json) or the drop-in was never on. It refuses with its own message when it runs inside +such a session: run it from a terminal. A hook that is gone refuses every Bash command there. Uninstall with the +drop-in still there removes it first, then checks. """ import contextlib, glob, json, os, pwd, sys, time _kit = os.path.dirname(os.path.dirname(os.path.realpath(__file__))) @@ -140,16 +143,108 @@ class AgentGuardsInstaller(kit_install.Installer): self.settings_off() HOMES = None # tests only: the home folders searched for user settings (default: every passwd entry) - CLAUDE = 'claude' # Claude Code's process name + HAND_WIRED = ETC + '/hand-wired-seen.json' # when a settings file the kit did not write last named a hook + CLAUDE_PATHS = ('/claude/versions/', '/@anthropic-ai/claude-code') # in a Claude Code program's real path - def foreign_settings(self): - """Settings files the kit did not write that name a kit hook (or cannot be read), as (path, why).""" - homes = self.HOMES if self.HOMES is not None else sorted({e.pw_dir for e in pwd.getpwall() if e.pw_dir}) + def homes(self): + return self.HOMES if self.HOMES is not None else sorted({e.pw_dir for e in pwd.getpwall() if e.pw_dir}) + + def home_path(self, home, *rel): + return os.path.join(self.p(home) if self.HOMES is None else home, *rel) + + def installed_claude(self): + """The real paths of the Claude Code programs installed where a session finds them: each user's + ~/.local/bin/claude, /usr/local/bin/claude, /usr/bin/claude.""" + out = set() + for path in [self.home_path(h, '.local', 'bin', 'claude') for h in self.homes()] + \ + [self.p('/usr/local/bin/claude'), self.p('/usr/bin/claude')]: + if os.path.exists(path): + out.add(os.path.realpath(path)) + return out + + def proc_link(self, pid, name): + """The target of /proc// (exe, cwd) as the kernel gives it, or None.""" + try: + return os.readlink(f'{self.PROC}/{pid}/{name}').removesuffix(' (deleted)') + except OSError: + return None + + def is_claude(self, pid, args, installed): + """Whether the process runs Claude Code, by the real path of its program (/proc//exe: the native build + in .../claude/versions/, under any name or link), of the script node runs (argv[1] in the + @anthropic-ai/claude-code package, through any link), or of an installed `claude`. The name alone (argv[0] + `claude`) counts too.""" + cwd = self.proc_link(pid, 'cwd') or '/' + paths = [self.proc_link(pid, 'exe') or ''] + for a in args[:2]: + paths.append(a) + if '/' in a: + paths.append(os.path.realpath(os.path.join(cwd, a))) + return any(p and (os.path.basename(p) == 'claude' or any(c in p for c in self.CLAUDE_PATHS) + or p in installed) for p in paths) + + def sessions(self): + """The running Claude Code sessions: dicts with pid, args, start (epoch seconds, None when unreadable), cwd + (None when unreadable) and own (an ancestor of this uninstall: it runs inside that session).""" + try: + boot, tick = self.boot_time(), os.sysconf('SC_CLK_TCK') + except (OSError, ValueError) as e: + raise self.Refused(f'{self.PROC}/stat cannot be read ({e}): uninstall cannot see which Claude Code ' + 'sessions run') from None + ancestors, pid = set(), os.getpid() + while pid > 1 and pid not in ancestors: # this uninstall and what started it (sudo, a shell, a session) + ancestors.add(pid) + try: + with open(f'{self.PROC}/{pid}/stat', 'rb') as f: + pid = int(f.read().rpartition(b')')[2].split()[1]) + except (OSError, ValueError, IndexError): + break + installed, out = self.installed_claude(), [] + for name in sorted((n for n in os.listdir(self.PROC) if n.isdigit()), key=int): + if int(name) == os.getpid(): + continue + try: + with open(f'{self.PROC}/{name}/cmdline', 'rb') as f: + args = [a.decode('utf-8', 'replace') for a in f.read().split(b'\0') if a] + except OSError: + continue + if not self.is_claude(name, args, installed): + continue + try: + with open(f'{self.PROC}/{name}/stat', 'rb') as f: + start = boot + int(f.read().rpartition(b')')[2].split()[19]) / tick + except (OSError, ValueError, IndexError): + start = None + out.append({'pid': int(name), 'args': args, 'start': start, 'cwd': self.proc_link(name, 'cwd'), + 'own': int(name) in ancestors}) + return out + + def older_sessions(self, since, sessions=None): + """The sessions that started before `since` (epoch seconds), or whose start cannot be read.""" + return [s for s in (self.sessions() if sessions is None else sessions) + if s['start'] is None or s['start'] < since] + + def project_settings(self, sessions): + """The project settings files a running session may have read: .claude/settings*.json in its working folder + and each folder above it (where /proc shows the folder).""" + files = [] + for s in sessions: + d = s['cwd'] + while d and os.path.isabs(d): + files += sorted(glob.glob(os.path.join(d, '.claude', 'settings*.json'))) + if d == os.path.dirname(d): + break + d = os.path.dirname(d) + return files + + def foreign_settings(self, sessions=()): + """Settings files the kit did not write that name a kit hook (or cannot be read), as (path, why): managed + settings, each user's ~/.claude*/settings*.json, and the project settings of running sessions.""" files = [self.p(f'{wiring.MANAGED_DIR}/managed-settings.json')] files += sorted(glob.glob(self.p(f'{os.path.dirname(wiring.DROP_IN)}/*'))) - for home in homes: - files += sorted(glob.glob(os.path.join(self.p(home) if self.HOMES is None else home, '.claude*', - 'settings*.json'))) + for home in self.homes(): + files += sorted(glob.glob(self.home_path(home, '.claude*', 'settings*.json'))) + files += self.project_settings(sessions) names = [f'{wiring.BIN}/{h}' for h in HOOKS] found = [] for f in dict.fromkeys(files): @@ -175,62 +270,59 @@ class AgentGuardsInstaller(kit_install.Installer): return int(line.split()[1]) raise ValueError('no btime') - def older_sessions(self, since): - """`claude` processes that started before `since` (epoch seconds), one line each; a process whose start - cannot be read counts as older.""" + def hand_wired_seen(self): + """The time a settings file the kit did not write was last seen naming a hook (an earlier uninstall refused + for it), or None. Kept in , which uninstall removes last.""" try: - boot, tick = self.boot_time(), os.sysconf('SC_CLK_TCK') - except (OSError, ValueError) as e: - raise self.Refused(f'{self.PROC}/stat cannot be read ({e}): uninstall cannot see which Claude Code ' - 'sessions are older than the removal of the drop-in') from None - mine, pid = set(), os.getpid() - while pid > 1 and pid not in mine: # this uninstall and what started it (a session running sudo) - mine.add(pid) - try: - with open(f'{self.PROC}/{pid}/stat', 'rb') as f: - pid = int(f.read().rpartition(b')')[2].split()[1]) - except (OSError, ValueError, IndexError): - break - out = [] - for name in sorted((n for n in os.listdir(self.PROC) if n.isdigit()), key=int): - if int(name) in mine: - continue - try: - with open(f'{self.PROC}/{name}/cmdline', 'rb') as f: - args = [a.decode('utf-8', 'replace') for a in f.read().split(b'\0') if a] - except OSError: - continue - if not any(os.path.basename(a) == self.CLAUDE for a in args[:2]) \ - and not any('@anthropic-ai/claude-code' in a for a in args[:2]): - continue - try: - with open(f'{self.PROC}/{name}/stat', 'rb') as f: - start = boot + int(f.read().rpartition(b')')[2].split()[19]) / tick - except (OSError, ValueError, IndexError): - start = None - if start is None or start < since: - out.append(f'process {name}: {" ".join(args)[:200]}') - return out + with open(self.p(self.HAND_WIRED), encoding='utf-8') as f: + t = json.load(f).get('seen') + return t if isinstance(t, (int, float)) and not isinstance(t, bool) else time.time() + except FileNotFoundError: + return None + except (OSError, ValueError, AttributeError): + return time.time() # a broken record: count it as seen now (more sessions older, never fewer) + + def show(self, f): + return f[len(self.PREFIX):] if self.PREFIX and f.startswith(self.PREFIX) else f @contextlib.contextmanager def uninstall_guard(self): - foreign = self.foreign_settings() + sessions = self.sessions() + foreign = self.foreign_settings(sessions) if foreign: + if os.path.isdir(self.p(self.ETC)): # the second run still checks the sessions that read those entries + self.write_file(self.HAND_WIRED, json.dumps({'seen': int(time.time()) + 1}) + '\n') raise self.Refused('uninstall refused: a settings file this kit did not write names a kit hook, and ' 'with the hook gone it would refuse every Bash command there:\n ' - + '\n '.join(f'{f[len(self.PREFIX):] if f.startswith(self.PREFIX) else f}: {why}' - for f, why in foreign) - + '\nRemove those entries by hand and run uninstall again') + + '\n '.join(f'{self.show(f)}: {why}' for f, why in foreign) + + '\nRemove those entries by hand and run uninstall again (it then also waits for the ' + 'sessions that started with them)') self.settings_off() off = self.read_config().get('settingsOff') - if isinstance(off, (int, float)) and not isinstance(off, bool): - older = self.older_sessions(off) - if older: - raise self.Refused('uninstall refused: these Claude Code sessions started while the hooks were in ' - 'managed settings and still run them; with the hooks gone they would refuse every ' - 'Bash command:\n ' + '\n '.join(older) + '\nThe drop-in is removed, so new ' - 'sessions do not run the hooks. Let these end (or stop them) and run uninstall ' - 'again') + seen = self.hand_wired_seen() + if seen is not None: + since = int(time.time()) + 1 + why = ('a settings file the kit did not write named the hooks (seen by an earlier uninstall), so every ' + 'session older than this uninstall may run them') + elif isinstance(off, (int, float)) and not isinstance(off, bool): + since = off + why = 'these sessions started while the hooks were in managed settings and still run them' + else: + since = int(time.time()) + 1 + why = ('the kit\'s drop-in was never on, so the hooks can only be wired by hand, in a file uninstall may ' + 'not see; every session older than this uninstall may run them') + older = self.older_sessions(since, sessions) + own = [s for s in older if s['own']] + if own: + raise self.Refused(f'uninstall refused: it runs inside Claude Code session process {own[0]["pid"]}, which ' + 'has the hooks; with them gone that session would refuse every Bash command. Run ' + 'uninstall from a terminal, not from a Claude Code session that has the hooks') + if older: + raise self.Refused(f'uninstall refused: {why}; with the hooks gone they would refuse every Bash ' + 'command:\n ' + '\n '.join(f'process {s["pid"]}: {" ".join(s["args"])[:200]}' + for s in older) + + '\nNew sessions do not run the kit\'s drop-in. Let these end (or stop them) and run ' + 'uninstall again') yield def _remove(self): diff --git a/fork-kit/agent-guards/tests/install.test.py b/fork-kit/agent-guards/tests/install.test.py index 7f4d0dbeeb064..8d6b5e2b2fdde 100644 --- a/fork-kit/agent-guards/tests/install.test.py +++ b/fork-kit/agent-guards/tests/install.test.py @@ -34,9 +34,9 @@ def setUp(self): os.makedirs(self.homes) self.m.HOMES = [os.path.join(self.homes, 'agent')] - def session(self, pid, argv=('claude', '-p'), started=None): + def session(self, pid, argv=('claude', '-p'), started=None, exe=None, cwd=None, ppid=1): """A fake process in PROC: argv, started at `started` (epoch seconds; default: at boot). started='bad': a - stat that cannot be read.""" + stat that cannot be read. exe, cwd: the targets of its /proc links; ppid: its parent.""" d = os.path.join(self.m.PROC, str(pid)) os.makedirs(d, exist_ok=True) with open(os.path.join(d, 'cmdline'), 'wb') as f: @@ -46,7 +46,10 @@ def session(self, pid, argv=('claude', '-p'), started=None): f.write('garbled') else: ticks = int(((started or self.boot) - self.boot) * os.sysconf('SC_CLK_TCK')) - f.write(f'{pid} (node) S 1 ' + ' '.join(['0'] * 17) + f' {ticks} 0 0\n') + f.write(f'{pid} (node) S {ppid} ' + ' '.join(['0'] * 17) + f' {ticks} 0 0\n') + for name, target in (('exe', exe), ('cwd', cwd)): + if target: + os.symlink(target, os.path.join(d, name)) return d def config(self): @@ -287,6 +290,121 @@ def test_a_managed_folder_others_can_write_is_refused(self): self.assertIn('only root can write', err) self.assertEqual(os.listdir(self.path(wiring.MANAGED_DIR)), []) + # PR 847 round 2: uninstall's running-session check (lens B minor 2, lens A minors 1 and 2) + HAND = '/etc/agent-guards/hand-wired-seen.json' + ENTRY = {'hooks': {'PreToolUse': [{'matcher': 'Bash', 'hooks': [ + {'type': 'command', 'command': '/usr/local/bin/actions-disable-guard'}]}]}} + + def make(self, rel, text='', mode=0o644): + path = os.path.join(self.host, rel) + os.makedirs(os.path.dirname(path), exist_ok=True) + with open(path, 'w') as f: + f.write(text) + os.chmod(path, mode) + return path + + def assert_uninstall_refused(self, *parts): + code, _, err = self.run_main('uninstall') + self.assertEqual(code, 1, err) + for part in parts: + self.assertIn(part, err) + self.assertTrue(self.is_file('/usr/local/bin/actions-disable-guard')) + return err + + def test_r2_minorB2_a_session_is_found_by_its_program_path_not_its_name(self): + native = self.make('home/agent/.local/share/claude/versions/2.1.9', '#!/bin/sh\n', 0o755) + os.makedirs(os.path.join(self.m.HOMES[0], '.local', 'bin')) + os.symlink(native, os.path.join(self.m.HOMES[0], '.local', 'bin', 'claude')) + cli = self.make('opt/node_modules/@anthropic-ai/claude-code/cli.js') + work = os.path.join(self.host, 'work') + os.makedirs(work) + os.symlink(cli, os.path.join(work, 'cc.js')) + other = self.make('opt/elsewhere/agent-bin', '#!/bin/sh\n', 0o755) + os.unlink(os.path.join(self.m.HOMES[0], '.local', 'bin', 'claude')) + os.symlink(other, os.path.join(self.m.HOMES[0], '.local', 'bin', 'claude')) # an install in its own folder + for argv, exe, cwd in ((('cc', '-p', 'x'), native, None), # a renamed link to the build + (('foo', '-p'), native + ' (deleted)', None), # exec -a, updated since + (('/usr/bin/node', './cc.js', '-p'), '/usr/bin/node', work), # node, a link to cli.js + (('agent-bin', '-p'), other, None)): # the installed `claude` + with self.subTest(argv=argv): + self.fresh() + self.assertEqual(self.install('--settings')[0], 0) + d = self.session(4242, argv, exe=exe, cwd=cwd) + self.assert_uninstall_refused('process 4242', 'started while the hooks were in managed settings') + shutil.rmtree(d) + self.session(4243, ('bash', '-c', 'claude'), exe='/usr/bin/bash') # not Claude Code itself + self.assertEqual(self.run_main('uninstall')[0], 0) + + def test_r2_minorA1_uninstall_run_inside_a_session_that_has_the_hooks_is_refused(self): + self.assertEqual(self.install('--settings')[0], 0) + self.session(os.getpid(), ('python3', 'agent-guards-install'), started=time.time(), ppid=5001) + self.session(5001, ('sudo', 'agent-guards-install'), started=time.time(), ppid=5000) + self.session(5000, ('claude',), ppid=1) # the session whose Bash tool ran sudo + self.assert_uninstall_refused('inside Claude Code session process 5000', + 'Run uninstall from a terminal') + shutil.rmtree(os.path.join(self.m.PROC, '5000')) # a session that started after the drop-in went + self.session(5000, ('claude',), started=time.time() + 5, ppid=1) + self.assertEqual(self.run_main('uninstall')[0], 0) + + def test_r2_minorA2_after_hand_wired_entries_go_the_next_uninstall_still_waits_for_older_sessions(self): + user = os.path.join(self.m.HOMES[0], '.claude', 'settings.json') + for name in ('no drop-in ever', 'drop-in removed earlier'): + with self.subTest(name): + self.fresh() + self.assertEqual(self.install('--settings' if name != 'no drop-in ever' else '--no-settings')[0], 0) + if name == 'drop-in removed earlier': + self.assertEqual(self.install('--no-settings')[0], 0) + cfg = dict(self.config(), settingsOff=self.boot + 10) # removed long ago + with open(self.path(CONFIG), 'w') as f: + json.dump(cfg, f) + os.makedirs(os.path.dirname(user), exist_ok=True) + with open(user, 'w') as f: + json.dump(self.ENTRY, f) + d = self.session(4242, started=self.boot + 100) # started with the hand-wired entry + self.assert_uninstall_refused('names /usr/local/bin/actions-disable-guard') + os.unlink(user) # the owner removes it, runs again + self.assert_uninstall_refused('process 4242', 'named the hooks') + self.assert_uninstall_refused('process 4242') # and again: still + shutil.rmtree(d) + self.assertEqual(self.run_main('uninstall')[0], 0) + self.assertFalse(os.path.lexists(self.path('/etc/agent-guards'))) + + def test_r2_minorA2_without_the_drop_in_ever_on_every_older_session_counts(self): + self.assertEqual(self.install()[0], 0) + d = self.session(4242) + self.assert_uninstall_refused('process 4242', 'drop-in was never on') + shutil.rmtree(d) + self.session(4243, started=time.time() + 5) + self.assertEqual(self.run_main('uninstall')[0], 0) + + def test_r2_minorA2_project_settings_of_a_running_session_are_searched(self): + proj = os.path.join(self.host, 'proj') + self.make('proj/.claude/settings.local.json', json.dumps(self.ENTRY)) + os.makedirs(os.path.join(proj, 'sub')) + self.assertEqual(self.install('--settings')[0], 0) + d = self.session(4242, started=time.time() + 5, cwd=os.path.join(proj, 'sub')) # newer: has no drop-in + err = self.assert_uninstall_refused('names /usr/local/bin/actions-disable-guard') + self.assertIn(os.path.join(proj, '.claude', 'settings.local.json'), err) + shutil.rmtree(d) + self.assertEqual(self.run_main('uninstall')[0], 0) # a project no session runs in is not read + + def test_r2_state_an_uninstall_stopped_after_the_hand_wired_record_or_a_broken_record_still_counts(self): + for text in (json.dumps({'seen': self.boot + 200}), 'garbled', '[]', json.dumps({'seen': 'x'})): + with self.subTest(text): + self.fresh() + self.assertEqual(self.install('--settings')[0], 0) + self.assertEqual(self.install('--no-settings')[0], 0) + with open(self.path(CONFIG)) as f: + cfg = json.load(f) + with open(self.path(CONFIG), 'w') as f: + json.dump(dict(cfg, settingsOff=self.boot + 10), f) + with open(self.path(self.HAND), 'w') as f: # what a run stopped after it leaves + f.write(text) + d = self.session(4242, started=self.boot + 100) + self.assert_uninstall_refused('process 4242') + shutil.rmtree(d) + self.assertEqual(self.run_main('uninstall')[0], 0) + def fresh(self): shutil.rmtree(self.root) os.makedirs(self.root) From aec5b9fcbd576d9d29e07a7d08e37b156c774de0 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 04:25:59 +0000 Subject: [PATCH 8/9] fork-kit/agent-guards: README names the first Claude Code that honours onFailure, and how often a machine-file note shows (r2 nits) - onFailure: "block" is honoured from Claude Code 2.1.295 on; older versions ignore it and let a failed or timed-out hook's call run (lens B r2 nit 1). - A broken part of the machine file is named on every call the hook handles, once per hook with a problem, so a Bash call can carry it up to three times: kept loud on purpose, now said in the README (lens A r2 nit). - The --safe-mode refusal is kept, with its reason in the README since the major-1 commit: safe mode runs managed hooks but not hooks wired by hand in user settings (lens B r2 nit 2). Co-Authored-By: Claude Opus 5.5 --- fork-kit/agent-guards/README.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/fork-kit/agent-guards/README.md b/fork-kit/agent-guards/README.md index fe69833afe42b..376a1e615647f 100644 --- a/fork-kit/agent-guards/README.md +++ b/fork-kit/agent-guards/README.md @@ -36,9 +36,10 @@ g=/usr/local/bin/capacity-pipe-guard; [ -r "$g" ] || { echo "capacity-pipe-guard ``` A hook that runs past its timeout is ended by Claude Code. For the open hooks the call then goes on. The -`actions-disable-guard` entry sets `"onFailure": "block"`, so a timeout or a hook that cannot start refuses the call. -It also answers by itself within 5 s of its start (it refuses when it runs out of time with a guarded word unread), -well inside its 10 s. +`actions-disable-guard` entry sets `"onFailure": "block"`, so a timeout or a hook that cannot start refuses the +call. Claude Code honours `onFailure` from version 2.1.295 on; an older one ignores it, and there a hook that fails +or times out lets the call run, so run 2.1.295 or later. The guard also answers by itself within 5 s of its start (it +refuses when it runs out of time with a guarded word unread), well inside its 10 s. **Tools.** The Bash and Monitor tools both run shell text (`tool_input.command`), so the command hooks match both. `agent-guards check` fails a hook that is wired for Bash only (MISSING ... Monitor). @@ -101,9 +102,11 @@ These are the values the hooks had before. The file is `/etc/fork-kit/machine.js ([common/machine_file.py](../common/machine_file.py): owned by root, not writable by others, so an agent cannot change a guard's facts). Each hook reads only its own part (`actionsDisable`, `capacityPipe`, ...). A key in it that is broken (a wrong type, a bad path) keeps its default; an unknown key is ignored; a bad `refuseScripts` row is -dropped and the good rows kept. The hook says so to the agent (a `systemMessage`, and context for PreToolUse) and -on stderr. A broken or unknown part of another hook changes nothing for it. `agent-guards self-check` checks the -whole section strictly and names every problem. +dropped and the good rows kept. The hook says so to the agent (a `systemMessage`, and context for PreToolUse) and on +stderr, on every call it handles, until the file is fixed: loud on purpose. A Bash call can carry the note more than +once, once from each hook that has a problem in its part (`actionsDisable` and `capacityPipe` before it, +`memoryIndex` after it). A broken or unknown part of another hook changes nothing for it. `agent-guards self-check` +checks the whole section strictly and names every problem. | Key | Default | What it is | | ------------------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | From a90b854badd5a6f0fc6563ae2220ab0bbcb310f6 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 04:37:47 +0000 Subject: [PATCH 9/9] fork-kit/agent-guards: uninstall reads the boot time only when a Claude Code session runs (follow-up to the session-check commit) The session check now runs on every uninstall, so it must not refuse for a /proc/stat it does not need: the boot time is read only once a Claude Code process is found, and an unreadable process list still refuses with "cannot be read". Found by the shared fork-kit/common/tests/kit_install.test.py run (its fake /proc has no stat file). Co-Authored-By: Claude Opus 5.5 --- .../agent-guards/sbin/agent-guards-install | 22 ++++++++++++------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/fork-kit/agent-guards/sbin/agent-guards-install b/fork-kit/agent-guards/sbin/agent-guards-install index 3142df404263c..897b17188ddf9 100755 --- a/fork-kit/agent-guards/sbin/agent-guards-install +++ b/fork-kit/agent-guards/sbin/agent-guards-install @@ -186,12 +186,7 @@ class AgentGuardsInstaller(kit_install.Installer): def sessions(self): """The running Claude Code sessions: dicts with pid, args, start (epoch seconds, None when unreadable), cwd (None when unreadable) and own (an ancestor of this uninstall: it runs inside that session).""" - try: - boot, tick = self.boot_time(), os.sysconf('SC_CLK_TCK') - except (OSError, ValueError) as e: - raise self.Refused(f'{self.PROC}/stat cannot be read ({e}): uninstall cannot see which Claude Code ' - 'sessions run') from None - ancestors, pid = set(), os.getpid() + ancestors, pid, clock = set(), os.getpid(), [] while pid > 1 and pid not in ancestors: # this uninstall and what started it (sudo, a shell, a session) ancestors.add(pid) try: @@ -200,7 +195,12 @@ class AgentGuardsInstaller(kit_install.Installer): except (OSError, ValueError, IndexError): break installed, out = self.installed_claude(), [] - for name in sorted((n for n in os.listdir(self.PROC) if n.isdigit()), key=int): + try: + pids = sorted((n for n in os.listdir(self.PROC) if n.isdigit()), key=int) + except OSError as e: + raise self.Refused(f'{self.PROC} cannot be read ({e.strerror}): uninstall cannot see which Claude Code ' + 'sessions run') from None + for name in pids: if int(name) == os.getpid(): continue try: @@ -210,9 +210,15 @@ class AgentGuardsInstaller(kit_install.Installer): continue if not self.is_claude(name, args, installed): continue + if not clock: # read only when a session runs + try: + clock[:] = [self.boot_time(), os.sysconf('SC_CLK_TCK')] + except (OSError, ValueError) as e: + raise self.Refused(f'{self.PROC}/stat cannot be read ({e}): uninstall cannot see which Claude ' + 'Code sessions are older than the hooks\' removal') from None try: with open(f'{self.PROC}/{name}/stat', 'rb') as f: - start = boot + int(f.read().rpartition(b')')[2].split()[19]) / tick + start = clock[0] + int(f.read().rpartition(b')')[2].split()[19]) / clock[1] except (OSError, ValueError, IndexError): start = None out.append({'pid': int(name), 'args': args, 'start': start, 'cwd': self.proc_link(name, 'cwd'),