# AgentShield
> Enterprise-Grade Zero-Leak Secret Defense & Sandboxing for Autonomous AI Coding Agents

AgentShield is an open-source, local-first runtime security layer designed to prevent autonomous AI coding agents (Claude Code, Cursor, Windsurf, Codex, Antigravity) from reading `.env` files, leaking private cloud credentials into LLM inference contexts, or committing secrets into Git repositories.

Website: https://agentshield.ritualdev.in/
Repository: https://github.com/RitualDev-Lab/AgentShield
Ecosystem Directory: https://devshelf.ritualdev.in/

License: Apache-2.0

## Quick Start CLI
```bash
# Audit a configuration file for leaked secrets
npx @ritualdev_lab/agentshield scan .env

# Install pre-commit hook in local repository
npx @ritualdev_lab/agentshield hook git-install

# Sandbox an agent bash command with real-time output redaction
npx @ritualdev_lab/agentshield exec "cat .env"

# Audit git pull request diff in CI
npx @ritualdev_lab/agentshield ci --base origin/main
```

## Core Security Capabilities
- **Autonomous Agent Shell Sandbox**: Intercepts high-risk commands (`cat .env`, `grep . .env`, `type .env`, `python -c "open('.env')"`, `env | sort`, `export`, `printenv`, `curl ... $API_KEY`) and prevents secrets from entering agent terminal context.
- **Active Shannon Entropy Discovery**: Scans candidate tokens for informational entropy H >= 4.5 bits/char to uncover unknown high-entropy passwords, tokens, and random credentials alongside structured regex patterns.
- **SHA-256 Collision Defense**: Deterministic surrogate tokens map 1:1 using 16-hex digest hashes (`[AGENT_SHIELD:ID:hexHash]`) to guarantee zero collision during rehydration.
- **Micro-Sandboxing & MCP Protocol Interception**: Micro-sandboxing profiles for macOS (Seatbelt sandbox-exec), Linux (bwrap/seccomp), and Windows integrity levels, combined with inline JSON-RPC sanitization for Model Context Protocol (MCP) server calls.
- **Cryptographic Write-Ahead Audit Ledger**: SHA-256 HMAC chained event logs with sequential verification preventing retrospective log tampering.
- **Cross-Turn Taint Graph & Canary Decoys**: Directional taint propagation tracking multi-turn prompt leakages, coupled with honeypot synthetic decoy tripwires that alert on unauthorized tool access.
- **Local-First Air-Gapped Architecture**: Zero telemetry, zero external network dependencies, ensuring strict compliance with SOC2 CC6.1, PCI-DSS Req-3.4, HIPAA §164.312, and ISO27001 A.8.28.

## Threat Model Alignment: OWASP LLM02 & MITRE ATLAS

AgentShield controls are indexed against the two frameworks most often cited in AI-agent security review: the OWASP Top 10 for LLM Applications and the MITRE ATLAS knowledge base.

### OWASP Top 10 for LLM Applications

- **LLM02:2025 — Sensitive Information Disclosure.** AgentShield is the disclosure boundary between the repository and the model context window. Credential values are replaced with deterministic `[AGENT_SHIELD:ID:hexHash]` surrogates before a tool result, command output, or MCP response reaches the agent, so `.env` contents, cloud access keys, database URLs, and bearer tokens are never rendered into inference context, agent transcripts, or third-party telemetry.
- **LLM01:2025 — Prompt Injection.** Instructions that attempt to make the agent read credentials are neutralized at the shell boundary rather than at the prompt layer, so a successful prompt injection still cannot produce a plaintext secret in the transcript.
- **LLM05:2025 — Improper Output Handling.** Subprocess output is redacted in flight (`agentshield exec`, `agentshield stream`) before it is echoed back to the agent, including output produced by interpreters such as `python -c`.
- **LLM06:2025 — Excessive Agency.** High-risk read paths (`cat .env`, `grep . .env`, `printenv`, `env | sort`, input redirection from a secret file) are intercepted and reported instead of executed.

### MITRE ATLAS

- **AML.T0025 — Exfiltration via Cyber Means.** The subshell exfiltration pattern — `sh -c "..."`, `bash -c '...'`, ANSI-C quoting such as `$'cat\t.env'`, input redirection (`< .env`), and interpreter one-liners such as `python -c "open('.env')"` — is normalized and unpacked to its AST before evaluation, so wrapper tricks do not defeat the gate.
- **AML.T0057 — LLM Data Leakage.** Secret material reachable from the agent (files, process environment, MCP tool responses) is substituted with surrogates, so prompts that induce disclosure return tokens that cannot be replayed outside the local machine.
- **AML.T0086 — Exfiltration via AI Agent Tool Invocation.** MCP JSON-RPC requests and responses are sanitized bidirectionally, covering tool invocation as an exfiltration channel.
- **AML.T0051 — LLM Prompt Injection.** Tracked through the cross-turn taint graph, which flags multi-turn attempts to launder a secret across successive tool calls.

Machine-readable severity and control attribution is available per finding from `agentshield scan --json`.