Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .claude/settings.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,11 @@
"excludedCommands": [
"uv run --project ~/.claude/magpie/vetted-ops vetted-op-read *",
"uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *",
"uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *",
"uv run --project ~/.claude/magpie/vetted-ops vetted-op *",
"uvx --from ~/.claude/magpie/vetted-ops vetted-op-read *",
"uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *",
"uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *",
"uvx --from ~/.claude/magpie/vetted-ops vetted-op *"
],
"filesystem": {
Expand Down Expand Up @@ -135,6 +137,8 @@
"Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *)",
"Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *)",
"Bash(uvx --from ~/.claude/magpie/security-tools/cve-tool cve-tool *)",
"Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *)",
"Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *)",
"Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op *)",
"Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op *)",
"Bash(gh api -X*)",
Expand Down
19 changes: 15 additions & 4 deletions docs/setup/secure-agent-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -525,6 +525,10 @@ The full block below is the two merged, annotated.
// bodies read only from the workspace, so the exclusion exposes less than
// the bare `gh *` above. Both keep their `ask` below, never `allow`: the
// prompt is the gate on every write (sandbox-lint enforces the pairing).
// `vetted-op-git` is excluded because what it does cannot happen inside:
// an SSH push gets no TCP through the sandbox's proxy, and a linked
// worktree's administrative directory is read-only there. It keeps its
// `ask` too (see "Git operations the sandbox blocks" below).
// The adversarial-review tool runs the reviewer CLIs, which need network
// and their own credentials. Like the vetted-ops entries, it names the
// fixed link its plugin's SessionStart hook maintains, never a `*` where
Expand All @@ -542,6 +546,8 @@ The full block below is the two merged, annotated.
"uvx --from ~/.claude/magpie/vetted-ops vetted-op-read *",
"uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *",
"uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *",
"uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *",
"uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *",
"uv run --project ~/.claude/magpie/vetted-ops vetted-op *",
"uvx --from ~/.claude/magpie/vetted-ops vetted-op *",
"uvx --from ~/.claude/magpie/adversarial-review adversarial-review *",
Expand Down Expand Up @@ -776,6 +782,8 @@ The full block below is the two merged, annotated.
"Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *)", // the tracker rollup / body-field procedures: excluded from the sandbox above, so never `allow`
"Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *)",
"Bash(uvx --from ~/.claude/magpie/security-tools/cve-tool cve-tool *)", // cve-tool: excluded from the sandbox above, and it changes CVE records, so every call asks
"Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *)", // push / worktree moves outside the sandbox: never `allow`
"Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *)",
// gh WRITE subcommands, listed one by one. Claude Code evaluates deny,
// then ask, then allow, and "a matching ask rule prompts even when a
// more specific allow rule also matches the same call" — so a catch-all
Expand Down Expand Up @@ -964,7 +972,10 @@ If even the read-widening matters for your threat model, keep the
policy in a path the sandbox does not grant write to and point
`vetted-op-read --config` at it.

`vetted-op-tracker` and `vetted-op` are the write-capable entry points excluded from the sandbox.
`vetted-op-tracker`, `vetted-op-git` and `vetted-op` are the write-capable entry points excluded from the sandbox.
`vetted-op-git` runs four git operations a sandboxed agent cannot (see
[vetted-ops → Git operations the sandbox blocks](../../tools/vetted-ops/README.md#git-operations-the-sandbox-blocks)),
each bounded by the approved policy's `[git]` table.
`vetted-op-tracker` refuses every operation except the tracker rollup / body-field procedures before it reads the policy,
and their runner refuses any `gh` call outside `repos/<tracker>/`.
`vetted-op` runs the whole write catalogue, but each operation is a fixed `gh` argv with no shell,
Expand Down Expand Up @@ -1032,7 +1043,7 @@ Codex is the exception that proves the rule: its execpolicy cannot match `~`, so

They are what makes an unprompted read safe to allow: the `allow` rests on the catalogue's shape, so the agent that calls the dispatcher must not be able to edit it.
A missing rule is a must-fix.
5. `sandbox.excludedCommands` keeps the `vetted-op-read`, `vetted-op-tracker` and `vetted-op` exclusions in both `~` launcher forms, as in [the framework's own settings](#the-frameworks-own-claudesettingsjson).
5. `sandbox.excludedCommands` keeps the `vetted-op-read`, `vetted-op-tracker`, `vetted-op-git` and `vetted-op` exclusions in both `~` launcher forms, as in [the framework's own settings](#the-frameworks-own-claudesettingsjson).
Without them, an allowed call runs inside the sandbox, where its `gh` cannot verify TLS: a silent failure again.
6. The agent-guard plugin is installed, so the `vetted-ops-spelling` guard turns an expanded spelling into a refusal instead of a sandboxed call that fails silently.

Expand All @@ -1042,7 +1053,7 @@ Codex is the exception that proves the rule: its execpolicy cannot match `~`, so
"excludedCommands": [
"uvx --from ~/.claude/magpie/vetted-ops vetted-op-read *",
"uv run --project ~/.claude/magpie/vetted-ops vetted-op-read *"
// ...plus the two vetted-op-tracker and two vetted-op entries
// ...plus the two vetted-op-tracker, two vetted-op-git and two vetted-op entries
]
},
"permissions": {
Expand Down Expand Up @@ -4033,7 +4044,7 @@ never delete it:
is ✗ and worth stopping for: it grants every operation in
the catalogue, because the operation's caller name is chosen
by whoever runs the command.
- `vetted-op-tracker` and `vetted-op` are each in `ask` and in
- `vetted-op-tracker`, `vetted-op-git` and `vetted-op` are each in `ask` and in
`sandbox.excludedCommands` (both forms), never in `allow`;
an exclusion without its `ask` is ✗ (the prompt is the only
gate on an unsandboxed write).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2063,6 +2063,7 @@ def guard_empty_rebase(seg: Segment, cwd: str | None) -> str | None:
"vetted-op": "vetted-ops",
"vetted-op-read": "vetted-ops",
"vetted-op-tracker": "vetted-ops",
"vetted-op-git": "vetted-ops",
"adversarial-review": "adversarial-review",
}
VETTED_STABLE_BASE = "~/.claude/magpie/"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,4 @@
for installs that do not carry the framework source (see `isolated.py`).
"""

FRAMEWORK_FINGERPRINT = "sha256:5ef56166ec29b5d7"
FRAMEWORK_FINGERPRINT = "sha256:2b2d856e6cb8f098"
111 changes: 110 additions & 1 deletion plugins/magpie-vetted-ops/tools/vetted-ops/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
- [The pr-management-stats reads](#the-pr-management-stats-reads)
- [Tracker procedures: rollup and body-field writes](#tracker-procedures-rollup-and-body-field-writes)
- [Tracker backends](#tracker-backends)
- [Git operations the sandbox blocks](#git-operations-the-sandbox-blocks)
- [Wiring it into settings](#wiring-it-into-settings)
- [Codex native rules](#codex-native-rules)
- [Tests](#tests)
Expand Down Expand Up @@ -151,6 +152,7 @@ scripts over one catalogue:
|---|---|---|
| `vetted-op-read` | never — refused before policy is consulted | `allow` |
| `vetted-op-tracker` | only the [tracker procedures](#tracker-procedures-rollup-and-body-field-writes) — everything else refused before policy is consulted | `ask`, and excluded from the sandbox |
| `vetted-op-git` | only the [git operations](#git-operations-the-sandbox-blocks) — no `gh` operation exists there | `ask`, and excluded from the sandbox |
| `vetted-op` | yes, subject to policy | `ask` (or unlisted) |

That split is what lets the read path lose its prompts without the write path
Expand Down Expand Up @@ -766,6 +768,109 @@ On a non-GitHub tracker the `number` parameter of a tracker operation takes the
backend's own IDs (`SEC-0012`, `FOOSEC-12`, `2024-007-xss`): letters, digits,
`-` and `_` only, so an ID can never name a path.

## Git operations the sandbox blocks

Three git steps fail in a sandboxed session however the agent phrases them, and
used to end in a command the user pasted into their own terminal:

- **Pushing over SSH.** The sandbox routes network through an HTTP proxy, so an
SSH transport gets no TCP at all, and a hardware key's touch prompt never
reaches the user.
- **Moving a linked worktree** to a rebased or pushed commit. Harnesses keep
`.git/worktrees/<name>/` read-only for worktrees the session did not create,
so `git reset`, `git fetch` and `git rebase` in such a worktree stop half-way.
- **Adding or removing a linked worktree**, for the same reason.

`vetted-op-git` runs exactly those four steps outside the sandbox, as closed
shapes, behind the harness's confirmation like `vetted-op`:

| Operation | Parameters | What it does |
|---|---|---|
| `git-push-branch` | `checkout branch target remote_branch expected` | Pushes local `branch`'s commit to `remote_branch` of the policy's `fork` or `upstream` repository, with `--force-with-lease=refs/heads/<remote_branch>:<expected>` and `--no-verify`. `expected` is the remote branch's current full SHA, or `new`. Run the pre-push checks in the sandbox first. |
| `git-worktree-sync` | `worktree commit` | Moves a clean linked worktree's branch to `commit` with `git reset --keep`, and prints the commit it was on. |
| `git-worktree-add` | `checkout path branch start` | Creates a linked worktree at `path`, directly inside a `worktree_roots` directory, on a new `branch` at `start`. |
| `git-worktree-remove` | `worktree` | Removes a linked worktree that has no changes (never `--force`). |

```bash
uvx --from ~/.claude/magpie/vetted-ops vetted-op-git --caller <skill> git-push-branch \
~/code/project fix-thing fork fix-thing 0123…(40 hex)
```

The policy's `[git]` table bounds them:

```toml
[git]
# Main checkouts the operations may act on; their linked worktrees count too.
checkouts = ["~/code/project"]
# Pushed over git@<host>:<repo>.git (transport = "https" for https://<host>/<repo>.git).
fork = "alice/project"
# Branches a push may create or move on [repos] upstream. Empty or absent: never.
upstream_push = ["ci-*", "stack/*"]
# Added to the built-in list (main, master, trunk, develop, gh-pages, release*, v*-test, v*-stable, *-stable, asf-site).
protected = ["prod"]
# Directories new worktrees may be created in, directly.
worktree_roots = ["~/code/project/files"]
```

What makes running git unsandboxed acceptable here:

- **Closed destinations.** A push goes to a URL built from the policy's
repository names, never to a remote the repository configures. Protected
branches are refused whatever the policy says, and upstream takes only
branches matching `upstream_push`.
- **Nothing lost silently.** Every push carries a lease on the full SHA the
caller expects (`new` for a branch that must not exist yet), so a branch
someone else moved is never overwritten, and moving a branch to a commit with
nothing over a remote's default branch (an emptied rebase, which would close
the pull request it heads) is refused, as agent-guard's `empty-rebase` guard
refuses the plain `git push`. A worktree moves only when it has
no local changes, and the previous commit is printed and stays in the reflog.
- **No repository configuration steers git.** Keys such as `core.sshCommand`,
`url.*.insteadOf`, `filter.*`, `core.fsmonitor`, `core.hooksPath` or
`include.path` can be planted in a repository's own config; the operation
refuses to run while the local or worktree config holds any key outside a
short list of inert ones (remotes, branch tracking, `user.name`, …). Global
and system configuration are the user's own and stay in effect, so an SSH
wrapper or touch overlay configured there keeps working. The check covers
every working tree the operation runs git in, and runs again right before
the command that acts.
- **Pinned on every call**, so a key added between that check and the command
cannot take effect: no file-system monitor, no automatic gc or maintenance,
only `https` and `ssh` transports, `core.sshCommand` set to the user's global
value (or `ssh`), and hooks off wherever they are not wanted. Attributes are
read from the empty tree, so no `.gitattributes` can switch on a filter
(the cost: a worktree is checked out without LFS smudging or line-ending
conversion). A push sends the one ref, never tags (`--no-follow-tags`), and
`GIT_ALLOW_PROTOCOL` limits transports whatever the configuration says.
- **Directories are held, not named.** Each validated directory is opened
without following a symlink at any component, and git runs inside it by
descriptor, so a directory swapped for a symlink after the checks cannot
send git elsewhere. A new worktree is created through its root's descriptor
and added as `.`, so git names its administrative directory `-` (`-1`, …).
A URL rewrite (`url.*.insteadOf`) cannot be pinned away: that it cannot
appear while the confirmed command runs rests on the harness keeping
`.git/config` write-protected, as Claude Code's sandbox does.
- **No environment steers git.** Every `GIT_*` variable is dropped, `HOME`
comes from the password database and `XDG_CONFIG_HOME` is dropped, so the
global configuration git reads is the account's own.
- **Hooks never run.** No operation runs a hook: the worktree operations set
`core.hooksPath=/dev/null`, and a push also passes `--no-verify`. A
`pre-push` hook is code the agent can write (`.git/hooks/pre-push`, or a
hook manager reading its configuration from the working tree), and the
confirmation shows the push, not what the hook would execute, so running it
here would run agent-written code outside the sandbox. The push-time checks
still run: the caller runs them inside the sandbox first (for prek,
`prek run --hook-stage pre-push --from-ref <base> --to-ref <branch>`), fixes
what they report, and only then pushes.
- **Unapproved policy, dry run.** `--dry-run` against a policy that is not an
approved copy checks the parameters and runs no git command; only an
approved policy prints the command it would run.

Everything else git does in a sandboxed session stays there. Rewriting history
for a branch checked out in a worktree you did not create is done in a scratch
clone (`git clone --shared <checkout> <scratch>`), fetched back into the main
checkout, pushed with `git-push-branch` and applied with `git-worktree-sync`.

## Wiring it into settings

Replace the wildcard `ask` rules with one `allow` entry, and keep an `ask` on
Expand All @@ -786,7 +891,9 @@ anything still invoked directly:
"Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op *)",
"Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op *)",
"Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *)",
"Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *)"
"Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *)",
"Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *)",
"Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *)"
],
"deny": [
// `Edit(path)` is the path rule for every file-writing tool — Write and
Expand Down Expand Up @@ -820,6 +927,8 @@ fails the same way:
"uvx --from ~/.claude/magpie/vetted-ops vetted-op-read *",
"uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *",
"uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *",
"uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *",
"uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *",
"uv run --project ~/.claude/magpie/vetted-ops vetted-op *",
"uvx --from ~/.claude/magpie/vetted-ops vetted-op *"
]
Expand Down
1 change: 1 addition & 0 deletions plugins/magpie-vetted-ops/tools/vetted-ops/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ dependencies = []
vetted-op = "vetted_ops:main"
vetted-op-read = "vetted_ops:main_read"
vetted-op-tracker = "vetted_ops:main_tracker"
vetted-op-git = "vetted_ops.git_ops:main"
vetted-ops-codex-rules = "vetted_ops.codex:main"

[tool.hatch.build.targets.wheel]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ def render_rules(tool_root: Path) -> str:
"# Generated by vetted-ops-codex-rules; review before installing.",
]
for launcher in (("uv", "run", "--project"), ("uvx", "--from")):
for entry in ("vetted-op-read", "vetted-op", "vetted-op-tracker"):
for entry in ("vetted-op-read", "vetted-op", "vetted-op-tracker", "vetted-op-git"):
pattern = [*launcher, base, entry]
decision = "allow" if entry == "vetted-op-read" else "prompt"
lines.append(f"prefix_rule(pattern = {json.dumps(pattern)}, decision = {json.dumps(decision)})")
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,8 @@ class Config:
#: The non-GitHub security tracker, when ``[tracker] platform`` selects one.
#: ``None`` means GitHub: tracker operations run their ``gh`` builders.
tracker_backend: TrackerBackend | None = None
#: The raw ``[git]`` table, validated by `git_ops.git_policy` for `vetted-op-git`.
git: object = None

def as_mapping(self) -> dict[str, object]:
"""The mapping handed to an operation's ``build`` callable."""
Expand Down Expand Up @@ -421,6 +423,7 @@ def load(path: Path | None = None, *, cwd: Path | None = None, approved_only: bo
endpoints=endpoints,
callers=callers,
tracker_backend=_tracker_backend(raw.get("tracker")),
git=raw.get("git"),
)


Expand All @@ -435,6 +438,7 @@ def describe(config: Config) -> str:
"endpoints": dict(sorted(config.endpoints.items())),
"callers": {k: sorted(v) for k, v in sorted(config.callers.items())},
"tracker_backend": (dict(vars(config.tracker_backend)) if config.tracker_backend else "github"),
"git": config.git,
},
indent=2,
sort_keys=True,
Expand Down
Loading
Loading