diff --git a/.github/fork-ci-tests.txt b/.github/fork-ci-tests.txt index ca0e56a931e70..15b760440079c 100644 --- a/.github/fork-ci-tests.txt +++ b/.github/fork-ci-tests.txt @@ -98,6 +98,14 @@ fork-ci/actions/test-select/test-select.test.py ~26s unittest fork-ci/actions/test-select/trace-check.test.py unittest fork-ci/actions/weakened-tests/weakened_tests.test.py unittest fork-ci/laws/laws.test.py unittest +fork-kit/agent-guards/tests/actions-disable.test.py ~45s unittest +fork-kit/agent-guards/tests/agent-slots.test.py unittest +fork-kit/agent-guards/tests/bg-guard.test.py unittest +fork-kit/agent-guards/tests/capacity-pipe.test.py unittest +fork-kit/agent-guards/tests/config.test.py unittest +fork-kit/agent-guards/tests/install.test.py ~20s unittest +fork-kit/agent-guards/tests/memory-index.test.py unittest +fork-kit/agent-guards/tests/wiring.test.py unittest fork-kit/cleaner/tests/compress.test.py ~15s unittest fork-kit/cleaner/tests/daily.test.py ~19s unittest fork-kit/cleaner/tests/dedupe.test.py ~22s unittest @@ -108,7 +116,7 @@ fork-kit/cleaner/tests/report.test.py unittest fork-kit/cleaner/tests/scratch.test.py unittest fork-kit/cleaner/tests/worktrees.test.py ~43s unittest fork-kit/common/tests/free_contract.test.py ~6s unittest -fork-kit/common/tests/kit_install.test.py ~93s unittest +fork-kit/common/tests/kit_install.test.py ~125s unittest fork-kit/common/tests/machine_file.test.py unittest fork-kit/desk/tests/install.test.py ~103s unittest fork-kit/desk/tests/windows.test.py ~65s unittest 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..376a1e615647f --- /dev/null +++ b/fork-kit/agent-guards/README.md @@ -0,0 +1,202 @@ +# 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\|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`. +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" ] && [ -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. 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. 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). + +**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`, `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`): + +```sh +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 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 +`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. +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). 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, 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 | +| ------------------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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 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). + +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 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 +``` + +`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, 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 + +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..fdd5753739158 --- /dev/null +++ b/fork-kit/agent-guards/bin/actions-disable-guard @@ -0,0 +1,3514 @@ +#!/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, 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 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. + +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/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 +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, shlex, 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_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}) +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', '-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'} +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 ' + '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 ' + '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|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', + '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') + # 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') + 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, 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 + + +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})') +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 = [ + ('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, 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 (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): + 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 cue and 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('-')] + + +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', + '-a', '--ask-for-approval'} +# claude words that start no session (a session started with CLAUDE_CODE_SIMPLE from a file is what matters) +CLAUDE_TOOLS = {'mcp', 'config', 'update', 'doctor', 'install', 'auth', 'plugin', 'plugins', 'setup-token', + 'migrate-installer', 'logs', 'purge', 'import', 'auto-mode', '--version', '-v', '--help', '-h'} +NO_HOOKS_ENV = 'CLAUDE_CODE_SIMPLE' # bare mode: Claude Code runs no hooks, managed ones neither +# where the programs are installed: the native build's version folder, the npm packages +AGENT_PATH = re.compile(r'/claude/versions/|@anthropic-ai/claude-code(?:/|$)|@openai/codex(?:-[\w-]+)?(?:/|$)', re.I) +AGENT_PKGS = {'@anthropic-ai/claude-code': 'claude', '@openai/codex': 'codex', 'claude': 'claude', 'codex': 'codex'} +PKG_RUNNERS = {'npx': (), 'bunx': (), 'pnpx': (), 'pnpm': ('dlx',), 'yarn': ('dlx',), 'npm': ('exec', 'x'), + 'bun': ('x',)} +# the shell start files of the agents' user: a `claude` session the Bash tool starts may get its variables from them +START_FILES = ('.bashrc', '.bash_profile', '.bash_login', '.profile', '.zshrc', '.zshenv', '.zprofile', '.zlogin') +KNOWN_WORDS = DATA | QUICK_WORDS | WRAPPERS | NET_CLIENTS | {'git', 'gh', 'ssh', 'make', 'npm', 'pnpm', 'yarn'} +_AGENT_BINS = {} + + +def agent_path_kind(path): + m = AGENT_PATH.search(path or '') + return None if not m else ('codex' if 'codex' in m.group(0).lower() else 'claude') + + +def agent_copy(path, ctx): + """'claude'/'codex' when a file is a copy of the installed program (same size, same first 64 KB).""" + try: + size = os.path.getsize(path) + for kind in ('claude', 'codex'): + key = (kind, ctx['env'].get('PATH') or '') + if key not in _AGENT_BINS: + p = which(kind, ctx) + _AGENT_BINS[key] = os.path.realpath(p) if p else None + real = _AGENT_BINS[key] + if real and real != path and os.path.isfile(real) and os.path.getsize(real) == size: + with open(real, 'rb') as a, open(path, 'rb') as b: + if a.read(65536) == b.read(65536): + return kind + except OSError: + pass + return None + + +def agent_kind(tok, ctx, script=False): + """'claude' or 'codex' when a word runs one of them: by name, by a name the same command gave it (ln -s ..), + by the path of its program (.../claude/versions/2.1.3, @openai/codex), by a link to it or by a copy of the + installed one; 'maybe' for a name the same command gave a program it cannot read; else None. script: the + word is a script an interpreter runs (`node cli.js`).""" + if not tok or hidden(tok): + return None + base = os.path.basename(tok).lower() + if base in ('claude', 'codex'): + return base + given = ctx.get('agents', {}).get(base) + if given: + return given + kind = agent_path_kind(tok) + if kind or (not script and '/' not in tok and (base in KNOWN_WORDS or INTERPRETERS.match(base))): + return kind + p = resolve_path(tok, ctx['cwd']) if script or '/' in tok else which(tok, ctx) + if not p or not os.path.isfile(p): + return None + real = os.path.realpath(p) + return agent_path_kind(real) or {'claude': 'claude', 'codex': 'codex'}.get(os.path.basename(real).lower()) \ + or agent_copy(real, ctx) + + +def agent_names(toks, ctx): + """The names a command gives a link to or a copy of claude or codex (`ln -s ~/.local/share/claude/versions/2.1.3 + cc`: cc), as gh_names() does for gh. A source the guard cannot read gives 'maybe'.""" + h, _ = head(toks) + if h is None or os.path.basename(toks[h]) not in ('ln', 'cp', 'mv', 'install', 'link', 'rsync'): + return {} + rest = [a for a in toks[h + 1:] if not a.startswith('-') or hidden(a)] + if len(rest) < 2 or hidden(rest[-1]): + return {} + kinds = [agent_kind(a, ctx) or ('maybe' if hidden(a) else None) for a in rest[:-1]] + kind = next((k for k in kinds if k and k != 'maybe'), None) or next((k for k in kinds if k), None) + name = os.path.basename(rest[-1].rstrip('/')).lower() + return {name: kind} if kind and name not in ('', '.', '..') else {} + + +def package_agent(toks, h, ctx): + """(kind, the agent's own words) when the command word runs claude or codex through a package runner (npx, + bunx, pnpm dlx, npm exec ..) or an interpreter (`node .../@anthropic-ai/claude-code/cli.js`); else (None, []).""" + base, rest = os.path.basename(toks[h]).lower(), toks[h + 1:] + if INTERPRETERS.match(base): + i = next((i for i, a in enumerate(rest) if not a.startswith('-')), None) + kind = i is not None and agent_kind(rest[i], ctx, script=True) + return (kind, rest[i + 1:]) if kind else (None, []) + if base not in PKG_RUNNERS or (PKG_RUNNERS[base] and rest[:1] and rest[0] not in PKG_RUNNERS[base]) \ + or (PKG_RUNNERS[base] and not rest): + return None, [] + rest = rest[1:] if PKG_RUNNERS[base] else rest + pkgs, i = [], 0 + while i < len(rest): + a = rest[i] + if a in ('-p', '--package'): + pkgs.append(rest[i + 1] if i + 1 < len(rest) else '') + i += 2 + continue + if a.startswith('--package='): + pkgs.append(a.partition('=')[2]) + elif a in ('-c', '--call'): # npm exec -c 'text': shell text, read by the shell reading + return None, [] + elif a != '--' and not a.startswith('-'): + break + i += 1 + word = rest[i] if i < len(rest) else '' + names = [re.sub(r'(?<=.)@[^/]*$', '', p.lower()) for p in pkgs + [word] if p] + kind = next((AGENT_PKGS[n] for n in names if n in AGENT_PKGS), None) + return (kind, rest[i + 1:]) if kind else (None, []) + + +def start_files(ctx): + """Why a `claude` session may get CLAUDE_CODE_SIMPLE from a file the command or its shell reads (a sourced + file, BASH_ENV/ENV, --rcfile, the user's shell start files), as far as the guard can see; else None. Not + followed: files those files read in turn.""" + for f in ctx.get('sourced', ()): + if hidden(f): + return 'the command reads a file the guard cannot name (`. "$F"`) that may set ' + NO_HOOKS_ENV + text = read_named(f, ctx) + if text is None: + return f'the command reads {f}, which the guard cannot read, and it may set {NO_HOOKS_ENV}' + if NO_HOOKS_ENV.lower() in text.lower(): + return f'the command reads {f}, which names {NO_HOOKS_ENV}' + if re.search(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 + + +def segment_reason(toks, ctx, loose): + h, via = head(toks) + why = nested_agent(toks, h, ctx) + 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 base in PKG_RUNNERS or agent_kind(toks[j], ctx): + 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)) + 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) + 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 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': {}, + '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, 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: + pass + return why + + +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 + 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: + return None + return why + (f' (The owner marker is not accepted: {problem}.)' if problem else '') + + +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 = [] + + +TOOLS = ('Bash', 'Monitor') # the tools whose tool_input.command is shell text + + +def with_problem(out): + """The answer with a machine file problem added where the agent and the owner see it.""" + if not SETTINGS_PROBLEM: + return out + try: + from agent_guards import config + return config.notice('actions-disable-guard', SETTINGS_PROBLEM, {'hook_event_name': 'PreToolUse'}, out) + except BaseException: # noqa: BLE001 - no lib: say it plainly + return dict(out or {}, systemMessage=f'actions-disable-guard: {SETTINGS_PROBLEM}; built-in defaults used. ' + 'Tell the owner.') + + +def deny(why): + out = {'hookSpecificOutput': {'hookEventName': 'PreToolUse', 'permissionDecision': 'deny', + 'permissionDecisionReason': why}} + try: + out = with_problem(out) + except BaseException: # noqa: BLE001 - the refusal matters more than the notice + pass + print(json.dumps(out), flush=True) + ANSWERED.append(True) + + +def passed(): + """Let the command run; with a machine file problem, say so in the answer.""" + if SETTINGS_PROBLEM: + try: + print(json.dumps(with_problem(None)), flush=True) + ANSWERED.append(True) + except BaseException: # noqa: BLE001 + pass + return 0 + + +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: + from agent_guards import config + config.warn('actions-disable-guard', SETTINGS_PROBLEM) + except BaseException: # noqa: BLE001 + try: + sys.stderr.write(f'actions-disable-guard: {SETTINGS_PROBLEM}; built-in defaults used.\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') not in TOOLS: + alarm_off() + return passed() + cmd = (ev.get('tool_input') or {}).get('command') or '' + if QUICK and quick_pass(cmd): + alarm_off() + return passed() + 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), 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) + 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 passed() + if why: + deny(why) # first: logging may be slow + log(cmd, why, env) + return 0 + return passed() + + +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..453b96511a219 --- /dev/null +++ b/fork-kit/agent-guards/bin/agent-guards @@ -0,0 +1,184 @@ +#!/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). 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] [--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 + +_kit = os.path.dirname(os.path.dirname(os.path.realpath(__file__))) +sys.path.insert(0, os.path.join(_kit, 'lib')) + +PROG = 'agent-guards' +ROOT_UID = 0 # tests only + + +def root_ways(user): + """How `user` can become root without the owner (sudo without a password, the docker group): one text each. + The approval file and the managed settings are root's; such a user can write them.""" + out = [] + try: + pw = pwd.getpwnam(user) + docker = grp.getgrnam('docker') + if user in docker.gr_mem or pw.pw_gid == docker.gr_gid: + out.append(f'{user} is in the docker group (a container can write any root file)') + except KeyError: + pass + try: + if os.geteuid() == ROOT_UID: + r = subprocess.run(['sudo', '-n', '-l', '-U', user], capture_output=True, text=True, timeout=10) + if 'NOPASSWD' in r.stdout: + out.append(f'{user} may run sudo without a password (NOPASSWD)') + else: + r = subprocess.run(['sudo', '-n', 'true'], capture_output=True, text=True, timeout=10) + if r.returncode == 0: + out.append(f'{user} can run sudo now without typing a password') + except (OSError, subprocess.SubprocessError): + pass + return out + + +def self_check(bin_dir, drop_in, links_dir=None): + from agent_guards import approval, config, wiring + links_dir = links_dir or wiring.BIN + problems, notes = [], [] + settings, cfg_problems = config.load_all() + problems += [f'machine file: {p}' 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') + wired = False + 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: + wired = True + 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 in wiring.HOOKS: # what the settings entries run: the links, not this version folder + link = os.path.join(links_dir, hook) + if os.path.realpath(link) != os.path.realpath(os.path.join(bin_dir, hook)): + (problems if wired else notes).append( + f'{link} is not this kit\'s {hook} ({os.path.realpath(link) if os.path.lexists(link) else "missing"})') + data, why = approval.read() + 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 ' + 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': + 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: + 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) + 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) + if a.cmd == 'hooks': + print(json.dumps({'hooks': wiring.hooks(a.bin)}, indent=2)) + return 0 + if a.cmd == 'approve': + return approve(a) + try: + 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 + 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, 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, 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'Any other command, or a second run, is refused. End it early with `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 new file mode 100755 index 0000000000000..549ff2a6865ac --- /dev/null +++ b/fork-kit/agent-guards/bin/agent-slots @@ -0,0 +1,119 @@ +#!/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 + +NAME = 'agent-slots' + + +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 _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() + event = json.load(sys.stdin) + out = decide(event, c) + except Exception: # never break a call because of this hook + out = None + try: + out = _notice(problem, event, out) + except Exception: # noqa: BLE001 + pass + 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..cd969f24e605a --- /dev/null +++ b/fork-kit/agent-guards/bin/bg-guard @@ -0,0 +1,171 @@ +#!/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 +NAME = 'bg-guard' + + +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 _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() + event = json.load(sys.stdin) + out = decide(event, c, os.getppid()) + except Exception: # never break a stop because of this guard + out = None + try: + out = _notice(problem, event, out) + except Exception: # noqa: BLE001 + pass + 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..c9fc09c67bbbd --- /dev/null +++ b/fork-kit/agent-guards/bin/capacity-pipe-guard @@ -0,0 +1,376 @@ +#!/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 + event = None + try: + event = json.loads(sys.stdin.read()) + 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 new file mode 100755 index 0000000000000..3cb9132abed17 --- /dev/null +++ b/fork-kit/agent-guards/bin/memory-index-guard @@ -0,0 +1,206 @@ +#!/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() +NAME = 'memory-index-guard' +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 _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 + 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 + out = None + try: + out = _notice(SETTINGS_PROBLEM, data, out) + except Exception: # noqa: BLE001 + pass + 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/approval.py b/fork-kit/agent-guards/lib/agent_guards/approval.py new file mode 100644 index 0000000000000..bfe7d5482976b --- /dev/null +++ b/fork-kit/agent-guards/lib/agent_guards/approval.py @@ -0,0 +1,185 @@ +"""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. 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 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 + +_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 = 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 + + +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", "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) + 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) != 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 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)' + 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(): + """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, 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), '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: + 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 new file mode 100644 index 0000000000000..6a2762b03ecbe --- /dev/null +++ b/fork-kit/agent-guards/lib/agent_guards/check.py @@ -0,0 +1,182 @@ +"""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), 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). +""" +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})' + 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): + 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', '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), + ('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), + ('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'), + ('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) + home = os.path.join(tmp, 'home') + os.makedirs(home) + missing = set() + for hook, event, label, ev, want, how in cases(tmp, sid): + 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, tool) not in missing: + missing.add((hook, event, tool)) + bad += 1 + 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.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, env=env) + 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..1c031bf964836 --- /dev/null +++ b/fork-kit/agent-guards/lib/agent_guards/config.py @@ -0,0 +1,227 @@ +"""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). 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", + "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): + p = _row_problem(k, v) + if p: + return p + 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 _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: + return machine_file.read_section(KIT, MACHINE_PATH, OWNER_UID, optional=True), None + except machine_file.MachineFileError as 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, 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 = _own(section, hook) + problems += 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 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 (also in the hook's answer: notice); the hook goes on.""" + if problem: + try: + 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 new file mode 100644 index 0000000000000..f6fe70b5a3cb8 --- /dev/null +++ b/fork-kit/agent-guards/lib/agent_guards/wiring.py @@ -0,0 +1,116 @@ +"""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 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`). Monitor runs shell text like Bash, so every hook that reads a command reads it for +Monitor too. +""" +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 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', + '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|Monitor', [('actions-disable-guard', 10)]), + ('PreToolUse', 'Bash|Monitor', [('capacity-pipe-guard', 10)]), + ('PostToolUse', 'Write|Edit|MultiEdit|Bash|Monitor', [('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" ] && [ -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; }}; ' + 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'] = [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 + + +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 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) and matches(matcher, tool): + 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 + import re + cmds = commands_in(settings) + 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 new file mode 100755 index 0000000000000..897b17188ddf9 --- /dev/null +++ b/fork-kit/agent-guards/sbin/agent-guards-install @@ -0,0 +1,352 @@ +#!/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. + +Rolling back is `install --no-settings`: the hooks stay, new sessions no longer run them. A session that started +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__))) +_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__', 'approval', '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 + 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') + + 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() + 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): + 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)): + 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)') + 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 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}: 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) + 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 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).""" + 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: + 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(), [] + 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: + 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 + 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 = 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'), + '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 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): + 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 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: + 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): + 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'{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') + 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): + # 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..310a0ea92c66c --- /dev/null +++ b/fork-kit/agent-guards/tests/actions-disable.test.py @@ -0,0 +1,2792 @@ +#!/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'} +# 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' + + +_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', '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): + 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 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, 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, command, cwd or self.dir, 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) + 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.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.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 -R a/b {mark}')) + approval, mark = self.approve() + 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) + 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, '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): + 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('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) + 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 - < ~/.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 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")) + + # 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\'']) + + 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 + 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 + # a copy without the kit's lib says so (config.notice: a systemMessage and context, no decision): passed + out = (json.loads(r.stdout).get('hookSpecificOutput') or {}) if r.stdout else {} + return (out if 'permissionDecision' in out else None), 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..b9db86171773c --- /dev/null +++ b/fork-kit/agent-guards/tests/config.test.py @@ -0,0 +1,210 @@ +"""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), named in its answer (a +systemMessage the agent sees) and on stderr. Each hook reads only its own part, key by key. + + 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 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_an_unknown_sibling_key_keeps_each_hooks_facts(self): + """Lens A major: a key no hook knows (a later kit's section, a typo of a hook's name) once made every hook + drop the whole file. Each hook now gets its own facts, with no problem; self-check names the key.""" + with open(EXAMPLE) as f: + section = json.load(f)['agent-guards'] + section = dict(section, gardener={'any': 'thing'}, memoryIndx={}) + for hook in config.HOOKS: + with self.subTest(hook): + got, problem = self.load(hook, section) + self.assertIsNone(problem) + self.assertEqual(got, dict(config.defaults(hook), **section[hook])) + settings, problems = config.load_all() + self.assertEqual(settings, {h: dict(config.defaults(h), **section[h]) for h in config.HOOKS}) + self.assertEqual(sorted(p.split("'")[1] for p in problems), ['gardener', 'memoryIndx']) + + def test_another_hooks_broken_part_changes_nothing(self): + section = {'memoryIndex': {'maxChars': 4000}, 'bgGuard': {'maxBlocks': -1}, 'agentSlots': []} + got, problem = self.load('memoryIndex', section) + self.assertEqual((got['maxChars'], problem), (4000, None)) + got, problem = self.load('bgGuard', section) + self.assertEqual(got, config.defaults('bgGuard')) + self.assertIn('maxBlocks', problem) + + def test_a_bad_or_unknown_key_keeps_the_others(self): + got, problem = self.load('memoryIndex', {'memoryIndex': {'maxChars': 4000, 'maxLine': 0, 'maxchars': 1}}) + self.assertEqual(got, dict(config.defaults('memoryIndex'), maxChars=4000)) + self.assertIn('maxLine', problem) + self.assertIn("'maxchars'", problem) + + def test_a_bad_row_keeps_the_good_rows(self): + good = {'name': 'garden.py', 'flag': '--fix', 'why': 'x'} + got, problem = self.load('actionsDisable', {'actionsDisable': { + 'refuseScripts': [good, {'name': '../x.py', 'flag': '--fix'}, {'name': 'b.py', 'flag': '--off'}]}}) + self.assertEqual([r['name'] for r in got['refuseScripts']], ['garden.py', 'b.py']) + self.assertIn('refuseScripts', 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_to_the_agent_and_the_defaults_used(self): + """Lens A/B minor: the fallback was on stderr only, which Claude Code does not show for exit 0. The answer + now carries it as a systemMessage (and as additionalContext where the event takes one).""" + machine = fx.machine_file(self.tmp, text='{"version": 1, "agent-guards": ') + pre = {'hook_event_name': 'PreToolUse', 'session_id': 'config-test', 'tool_name': 'Read', + 'tool_input': {'file_path': '/nonexistent'}} + for hook in fx.wiring.HOOKS: + for ev in (QUIET_EVENT, pre): + with self.subTest(hook=hook, event=ev['hook_event_name']): + r = fx.run_hook(hook, ev, 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) + out = json.loads(r.stdout) + self.assertIn('built-in defaults used', out['systemMessage']) + self.assertNotIn('decision', out) + if ev is pre: + spec = out['hookSpecificOutput'] + self.assertEqual(spec['hookEventName'], 'PreToolUse') + self.assertIn('built-in defaults used', spec['additionalContext']) + self.assertNotIn('permissionDecision', spec) + + 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) + self.assertIn("cannot load the kit's config code", json.loads(r.stdout)['systemMessage']) + + 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..8d6b5e2b2fdde --- /dev/null +++ b/fork-kit/agent-guards/tests/install.test.py @@ -0,0 +1,414 @@ +"""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, time, 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 setUp(self): + super().setUp() + self.boot = int(time.time()) - 3600 # the fake host booted an hour ago + with open(os.path.join(self.m.PROC, 'stat'), 'w') as f: + f.write(f'cpu 1 2 3\nbtime {self.boot}\n') + self.homes = os.path.join(self.host, 'home') + os.makedirs(self.homes) + self.m.HOMES = [os.path.join(self.homes, 'agent')] + + 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. 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: + f.write(b'\0'.join(a.encode() for a in argv) + b'\0') + with open(os.path.join(d, 'stat'), 'w') as f: + if started == 'bad': + f.write('garbled') + else: + ticks = int(((started or self.boot) - self.boot) * os.sysconf('SC_CLK_TCK')) + 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): + 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) + + # lens A/B minor: uninstall removed hook files that running sessions or other settings files still named + def test_rollback_is_no_settings_and_keeps_the_hooks(self): + self.assertEqual(self.install('--settings')[0], 0) + self.session(4242) # a session that started with the hooks + code, out, err = self.install('--no-settings', sha=SHA2) + self.assertEqual(code, 0, err) + self.assertIsNone(self.drop_in()) + for hook in wiring.HOOKS: # the running session still finds every hook + self.assertTrue(self.is_file(f'/usr/local/bin/{hook}'), hook) + cfg = self.config() + self.assertEqual(cfg['settings'], False) + self.assertIsInstance(cfg['settingsOff'], int) + self.assertGreater(cfg['settingsOff'], time.time() - 60) + self.assertEqual(self.run_main('self-check')[0], 0) + before = self.snapshot() # run again: the time is kept, nothing changes + self.assertEqual(self.install('--no-settings', sha=SHA2)[0], 0) + self.assertEqual(self.snapshot(), before) + + def test_uninstall_refused_while_a_session_that_had_the_hooks_runs(self): + self.assertEqual(self.install('--settings')[0], 0) + for argv, started in ((('claude', '-p', 'x'), None), (('/usr/bin/node', '/x/@anthropic-ai/claude-code/cli.js'), + None), (('claude',), 'bad')): + with self.subTest(argv=argv, started=started): + d = self.session(4242, argv, started) + code, _, err = self.run_main('uninstall') + self.assertEqual(code, 1) + self.assertIn('started while the hooks were in managed settings', err) + self.assertIn('process 4242', err) + self.assertIsNone(self.drop_in()) # the drop-in went first: no new session gets them + self.assertEqual(self.config()['settings'], False) + for hook in wiring.HOOKS: + self.assertTrue(self.is_file(f'/usr/local/bin/{hook}'), hook) + shutil.rmtree(d) + self.session(4243, ('bash', '-c', 'claude')) # not Claude Code itself + self.session(4244, started=time.time() + 5) # started after the drop-in went: it never had them + code, _, err = self.run_main('uninstall') + self.assertEqual(code, 0, err) + self.assertFalse(os.path.lexists(self.path('/usr/local/bin/actions-disable-guard'))) + + def test_uninstall_refused_while_another_settings_file_names_a_hook(self): + entry = {'hooks': {'PreToolUse': [{'matcher': 'Bash', 'hooks': [ + {'type': 'command', 'command': '/usr/local/bin/actions-disable-guard'}]}]}} + user = os.path.join(self.m.HOMES[0], '.claude', 'settings.json') + for where in (self.path(f'{wiring.MANAGED_DIR}/managed-settings.json'), + self.path(f'{os.path.dirname(DROP_IN)}/zz-hand.json'), user, + os.path.join(self.m.HOMES[0], '.claude-other', 'settings.local.json')): + with self.subTest(where): + self.fresh() + self.assertEqual(self.install('--settings')[0], 0) + os.makedirs(os.path.dirname(where), exist_ok=True) + with open(where, 'w') as f: + json.dump(entry, f) + code, _, err = self.run_main('uninstall') + self.assertEqual(code, 1) + self.assertIn('names /usr/local/bin/actions-disable-guard', err) + self.assertIn('Remove those entries by hand', err) + os.unlink(where) + self.assertEqual(self.config(), {'version': 1, 'settings': True}) # nothing changed + self.assertIsNotNone(self.drop_in()) + self.assertEqual(self.run_main('self-check')[0], 0) + code, _, err = self.run_main('uninstall') + self.assertEqual(code, 0, err) + if os.geteuid() != 0: # a file it cannot read may name one + self.fresh() + self.assertEqual(self.install('--settings')[0], 0) + os.makedirs(os.path.dirname(user), exist_ok=True) + with open(user, 'w') as f: + f.write('{}') + os.chmod(user, 0) + self.addCleanup(os.chmod, user, 0o600) + code, _, err = self.run_main('uninstall') + self.assertEqual(code, 1) + self.assertIn('cannot be read', err) + + def test_uninstall_stopped_after_pending_then_a_session_is_still_refused(self): + """Stopped between "pending" and the drop-in's removal: the next run removes it, puts the time and still + counts a session that started while it was there.""" + self.assertEqual(self.install('--settings')[0], 0) + cfg = dict(self.config(), settings=False, settingsOff='pending') # the state such a stop leaves + with open(self.path(CONFIG), 'w') as f: + json.dump(cfg, f) + self.assertIsNotNone(self.drop_in()) + self.assert_named_hooks_there() + self.session(4242) + code, _, err = self.run_main('uninstall') + self.assertEqual(code, 1) + self.assertIsInstance(self.config()['settingsOff'], int) + self.assertIsNone(self.drop_in()) + self.assertEqual(self.install('--settings')[0], 0) # the owner keeps the kit after all: back as it was + self.assertEqual(self.config(), {'version': 1, 'settings': True}) + self.assertEqual(self.run_main('self-check')[0], 0) + + def test_a_managed_folder_others_can_write_is_refused(self): + os.makedirs(self.path(wiring.MANAGED_DIR)) + os.chmod(self.path(wiring.MANAGED_DIR), 0o777) + code, _, err = self.install('--settings') + self.assertEqual(code, 1) + 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) + + +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..ce946ba0f2415 --- /dev/null +++ b/fork-kit/agent-guards/tests/wiring.test.py @@ -0,0 +1,383 @@ +"""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|Monitor', [10]), + ('PreToolUse', 'Bash|Monitor', [10]), + ('PostToolUse', 'Write|Edit|MultiEdit|Bash|Monitor', [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': {}})) + # lens B nit: a command that only names a kit hook somewhere is not the kit's + other = {'type': 'command', 'command': 'echo /usr/local/bin/bg-guard; g=/usr/local/bin/bg-guard; x'} + self.assertFalse(wiring.ours({'hooks': {'Stop': [{'hooks': [other]}]}})) + self.assertFalse(wiring.ours({'hooks': {'Stop': [{'hooks': [ + {'type': 'command', 'command': 'g=/usr/local/bin/bg-guard-old; exec x'}]}]}})) + + def test_every_tool_that_runs_shell_text_is_matched(self): + """Lens B major: Monitor runs shell text like Bash; a guard wired for Bash only let it through.""" + for event, hook in (('PreToolUse', 'actions-disable-guard'), ('PreToolUse', 'capacity-pipe-guard'), + ('PostToolUse', 'memory-index-guard')): + for tool in ('Bash', 'Monitor'): + with self.subTest(hook=hook, tool=tool): + self.assertIsNotNone(wiring.find({'hooks': wiring.hooks()}, hook, event, tool)) + self.assertIsNone(wiring.find({'hooks': wiring.hooks()}, 'actions-disable-guard', 'PreToolUse', 'Read')) + + def test_matches_reads_the_matcher_as_claude_code_does(self): + for matcher, tool, want in ((None, 'Monitor', True), ('', 'Monitor', True), ('*', 'Monitor', True), + ('Bash', 'Monitor', False), ('Bash|Monitor', 'Monitor', True), + ('Bash|Monitor', 'Mon', False), ('Mon.*', 'Monitor', True), + ('(', 'Monitor', False), ('Bash', None, True)): + with self.subTest(matcher=matcher, tool=tool): + self.assertEqual(wiring.matches(matcher, tool), want) + + def test_the_closed_hook_blocks_on_a_timeout(self): + """Lens B minor: Claude Code lets the call run when a hook times out, unless the entry says + "onFailure": "block". The closed hook says it; the open ones do not.""" + for _event, entries in wiring.hooks().items(): + for e in entries: + for h in e['hooks']: + closed = 'actions-disable-guard' in h['command'] + self.assertEqual(h.get('onFailure'), 'block' if closed else None, h['command']) + + 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) + gone = 'is missing or empty' if hook in wiring.CLOSED else 'is missing' + self.assertIn(f'{hook}: {self.bin}/{hook} {gone}: {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, r.stderr) # lens A nit: empty refuses too + self.assertIn('is missing or empty' if name == 'empty' + else 'actions-disable-guard: the guard failed (exit', r.stderr) + if name != 'empty': + 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): + """Killed by a signal on its own (the machine ran out of memory, say), the closed entry still refuses. + Claude Code's own timeout is the entry's "onFailure" (test_the_closed_hook_blocks_on_a_timeout).""" + 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), 13, '\n'.join(lines)) + self.assertEqual(lines[-1], 'check: test settings: OK') + # lens A nit: the hooks ran with HOME in check's own temporary folder; nothing (log, cache, state) is + # written in the caller's HOME + self.assertEqual(os.listdir(self.home), []) + + 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_guard_wired_for_bash_only_is_missing_for_monitor(self): + s = json.loads(json.dumps(self.settings)) + for e in s['hooks']['PreToolUse']: + e['matcher'] = e['matcher'].replace('|Monitor', '') + code, lines = self.run_check(s) + self.assertEqual(code, 1) + self.assertIn('MISSING actions-disable-guard (PreToolUse, Monitor): not wired in test settings', lines) + + 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) + + + +def load_cli(): + import importlib.machinery, importlib.util + loader = importlib.machinery.SourceFileLoader('agent_guards_cli', os.path.join(fx.BIN, 'agent-guards')) + mod = importlib.util.module_from_spec(importlib.util.spec_from_loader(loader.name, loader)) + loader.exec_module(mod) + return mod + + +class Command(unittest.TestCase): + """bin/agent-guards as a module: root is this test's user (ROOT_UID), the approval file is in a temporary + folder (approval.PATH, approval.OWNER_UID).""" + + def setUp(self): + from agent_guards import approval + self.cli, self.approval = load_cli(), approval + self.tmp = tempfile.mkdtemp(prefix='agent-guards-cli-') + self.addCleanup(shutil.rmtree, self.tmp, True) + self.cli.ROOT_UID = os.geteuid() + for name, value in (('PATH', os.path.join(self.tmp, 'etc', 'approval.json')), ('OWNER_UID', os.geteuid())): + self.addCleanup(setattr, approval, name, getattr(approval, name)) + setattr(approval, name, value) + fx.use_machine(fx.NO_MACHINE) + + def main(self, *argv): + import contextlib + out, err = io.StringIO(), io.StringIO() + with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err): + code = self.cli.main(list(argv)) + return code, out.getvalue(), err.getvalue() + + def settings_file(self, mode=0o644, name='s.json'): + path = os.path.join(self.tmp, name) + with open(path, 'w') as f: + f.write('{"hooks": {}}') + os.chmod(path, mode) + return path + + def test_check_as_root_runs_only_a_settings_file_only_root_can_write(self): + """Lens B minor: as root, `check --settings F` runs F's commands; a file another user can write (or a link + to one) would run that user's commands as root.""" + good = self.settings_file() + self.assertEqual(self.cli.read_settings(good), '{"hooks": {}}') + for path in (self.settings_file(0o666, 'w.json'), self.settings_file(0o620, 'g.json')): + with self.subTest(path): + with self.assertRaises(OSError) as e: + self.cli.read_settings(path) + self.assertIn('not safe to run as root', str(e.exception)) + code, _out, err = self.main('check', '--settings', path) + self.assertEqual(code, 1) + self.assertIn('not safe to run as root', err) + link = os.path.join(self.tmp, 'link.json') + os.symlink(good, link) + with self.assertRaises(OSError): + self.cli.read_settings(link) + self.cli.ROOT_UID = os.geteuid() + 1 # not root: the user's own file, as it is + 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', '--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.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 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, '--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', '--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') + os.makedirs(links) + drop_in = os.path.join(self.tmp, 'agent-guards.json') + import contextlib + out = io.StringIO() + with contextlib.redirect_stdout(out): + code = self.cli.self_check(fx.BIN, drop_in, links) # not wired: a link elsewhere is a note + text = out.getvalue() + self.assertEqual(code, 0, text) + self.assertIn(f'note: {links}/bg-guard is not this kit\'s bg-guard (missing)', text) + self.assertIn('WARNING:', text) + 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, 'gh x', self.tmp) + out = io.StringIO() + with contextlib.redirect_stdout(out): + code = self.cli.self_check(fx.BIN, drop_in, links) + text = out.getvalue() + self.assertEqual(code, 1, text) + self.assertIn(f'PROBLEM: {links}/bg-guard is not this kit\'s bg-guard', text) + self.assertIn('an owner approval for actions-disable-guard is open', text) + for hook in wiring.HOOKS: + os.symlink(os.path.join(fx.BIN, hook), os.path.join(links, hook)) + out = io.StringIO() + with contextlib.redirect_stdout(out): + self.assertEqual(self.cli.self_check(fx.BIN, drop_in, links), 0, out.getvalue()) + + def test_self_check_names_an_unknown_key(self): + machine = fx.machine_file(self.tmp, {'gardener': {}}) + fx.use_machine(machine) + import contextlib + out = io.StringIO() + with contextlib.redirect_stdout(out): + code = self.cli.self_check(fx.BIN, os.path.join(self.tmp, 'none.json'), self.tmp) + self.assertEqual(code, 1) + self.assertIn("PROBLEM: machine file: agent-guards: unknown key 'gardener'", out.getvalue()) + + +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 7c8fb74b6d896..5faeea73ef478 100644 --- a/fork-kit/common/machine.example.json +++ b/fork-kit/common/machine.example.json @@ -52,6 +52,29 @@ "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'), }