feat(setup-steward): verify check 8d — propose permission allow-list audit on adopt + upgrade#415
Merged
Conversation
…audit on adopt + upgrade Adds a verify check that audits the adopter's per-machine permission allow-list and surfaces: - **Forbidden entries** (✗) — broad wildcards that grant arbitrary code execution, e.g. `Bash(uv run *)`, `Bash(python3 *)`, `Bash(npm run *)`, `Bash(bash *)`, `Bash(gh api *)`, `Bash(docker run *)`. Per-entry proposal to remove. - **Recommended entries** (⚠) — narrow read-only patterns the framework's `security` family invokes constantly: Gmail MCP `get_thread` / `search_threads` / `list_drafts` / `list_labels`, PonyMail MCP `search_list` / `auth_status` / `get_thread` / `get_email` / `list_restrictions`, `Bash(vulnogram-api-record-fetch *)`. Plus `Bash(lychee *)` for every adopter that ships docs. Both surfaces are *proposals only* — the allow-list is the operator's capability surface for the agent in this checkout, and even an objectively-safer edit (drop a known-dangerous wildcard) is a capability change the operator must own. The framework's job is to surface the gap; the operator's job is to close it. Because verify is chained from both `/setup-steward adopt` (Step 12 sanity check) and `/setup-steward upgrade` (Step 9 sanity check), every adopt + upgrade pass now surfaces this audit automatically. The recommended-entry list is family-scoped — an adopter who skipped the `security` family will not see the Gmail/PonyMail entries surfaced as gaps. The interactive apply path (`/setup-steward verify --apply-permission-audit`) does an atomic JSON read → mutate → write so concurrent `setup-isolated-setup-install` writes do not silently clobber the diff, and requires per-write sandbox-bypass authorisation when the target settings file lives at a `denyWithinAllow` path. Motivation: the user's own `airflow-s` allow-list had accumulated `Bash(uv run *)` and `Bash(python3 *)` over time, both of which are arbitrary-code-execution holes. A periodic audit catches this drift on every adopt + upgrade rather than relying on the operator to remember to run `/fewer-permission-prompts`.
Merged
4 tasks
potiuk
added a commit
that referenced
this pull request
May 31, 2026
… of permissions.allow[] (#417) Real implementation behind the `--apply-permission-audit` flag of `/setup-steward verify` check 8d (introduced in #415). The skill previously described the audit + atomic-edit semantics abstractly; this PR adds the actual CLI the skill calls. Three subcommands: - `audit <path> [--families ...]` — read a settings file, classify `permissions.allow[]` against the forbidden + family-scoped recommended lists, print structured JSON. Exit 1 on any forbidden hit so a shell caller can pipeline. The JSON-pointer path (`.permissions.allow[<index>]`) returned for each forbidden entry lets the verify report point operators at the exact location. - `apply <path> [--add ...]... [--remove ...]... [--create-if-missing]` — atomic add/remove. POSIX `fcntl.flock` advisory exclusive lock on the target file, re-parse under the lock, mutate, write to a sibling temp file, `os.replace` into place. Concurrent `setup-isolated-setup-install` writes (which touch `sandbox.filesystem.*` on the same file) serialise without either losing work. Unrelated top-level keys (`extraKnownMarketplaces`, `hooks`, `permissions.deny`) preserved verbatim. - `list-known` — dump the canonical forbidden + recommended-by-family lists for diff-friendly inspection. The forbidden list covers the broad arbitrary-exec wildcards observed in real adopter trees: `Bash(uv run *)`, `Bash(python3 *)`, `Bash(npm run *)`, `Bash(bash *)`, `Bash(gh api *)`, `Bash(docker run *)`, `Bash(sudo *)`, plus the interpreter / shell / package-runner extensions documented in verify check 8d. The recommended list is family-scoped — every entry is read-only and verified against Claude Code's auto-allowed harness exclusions (`READONLY_COMMANDS`, `GIT_READ_ONLY_COMMANDS`, ...) so the tool does not propose entries that never prompt anyway. Wired into: - `.pre-commit-config.yaml` — ruff + mypy + pytest gates on `tools/permission-audit/**` (matches the github-body-field convention). - `docs/labels-and-capabilities.md` — new tool row, `capability:setup`. - `.claude/skills/setup-steward/verify.md` — check 8d's "Implementation" paragraph now references the CLI with concrete `uv run --project` invocations. Stdlib-only runtime — fast `uv run` resolution + no surprises on a fresh install. 22 tests covering classification, family-scoping, duplicate JSON-pointer numbering, atomic add/remove, no-op-rewrite skip, malformed-JSON detection.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new
verifycheck (8d) that audits the adopter's per-machinepermission allow-list (
<repo>/.claude/settings.jsonand<repo>/.claude/settings.local.json) and surfaces two kinds of finding:execution. Per-entry proposal to remove. Examples already seen in
real adopter trees:
Bash(uv run *),Bash(python3 *),Bash(npm run *),Bash(bash *),Bash(gh api *),Bash(docker run *),Bash(sudo *).securityfamily invokes constantly. Family-scoped so the proposalmatches the adopter's opted-in skill set.
Because
verifyis chained from both/setup-steward adopt(Step 12sanity check) and
/setup-steward upgrade(Step 9 sanity check), everyadopt + upgrade pass now surfaces this audit automatically — no
separate skill invocation needed.
Why
The user's own
airflow-sallow-list had silently accumulatedBash(uv run *)andBash(python3 *)over time. Both arearbitrary-code-execution holes; both stayed for months because no
periodic check flagged them. The verify chain is the right place for a
periodic capability-surface review — it already runs on every adopt +
upgrade, and proposing-rather-than-applying matches the framework's
golden rule that operator changes to capability surface stay under
operator control.
What
### 8d. Permission allow-list hygiene:Reads both
.claude/settings.jsonand.claude/settings.local.json.For each entry in
permissions.allow[]:runners, task-runner wildcards, broad
gh api/docker run/sudowildcards). ✗ per hit. List is explicitly not exhaustive— the same-category rule extends to anything that can spawn an
arbitrary process.
securityfamily → 9 Gmail/PonyMail read-only MCPs +Bash(vulnogram-api-record-fetch *)Bash(lychee *)Reports the per-entry JSON-pointer path
(
.permissions.allow[<index>]) so the operator can locate findingsinstantly.
Read-only — proposes, never auto-writes. Interactive apply via
/setup-steward verify --apply-permission-audit(atomic JSONread → mutate → write so concurrent
setup-isolated-setup-installwrites do not silently clobber; per-write sandbox-bypass
authorisation when the target file is at a
denyWithinAllowpath).The recommended list is deliberately narrow — every entry is
verified against Claude Code's auto-allowed harness exclusions
(
READONLY_COMMANDS,GIT_READ_ONLY_COMMANDS,GH_READ_ONLY_COMMANDS,etc.) so the framework does not redundantly propose entries that never
prompt anyway.
Test plan
/setup-steward verifyon a checkout whose.claude/settings.local.jsonhasBash(uv run *)→ ✗ on 8d with JSON-pointer path, removal proposal printed.claude/settings.local.jsonis missingmcp__claude_ai_Gmail__get_threadand the adopter opted into thesecurityfamily → ⚠ on 8d, paste-ready string printed.claude/settings.local.jsonis missingmcp__claude_ai_Gmail__get_threadbut the adopter did not opt intosecurity→ no ⚠ (family-scoped).claude/settings*.jsonat all → ⚠ (soft signal), suggests/setup-isolated-setup-install/setup-steward adoptand/setup-steward upgradeboth chain through verify and surface the 8d findings in their final report🤖 Generated with Claude Code