Stop Claude Code, Cursor, Windsurf, and autonomous coding agents from leaking .env secrets, SSH keys, or running destructive shell commands.
Zero runtime dependencies. 100% local & air-gapped by default. <20 Β΅s P99 redaction across 10,000-call benchmarks (149k+ ops/sec).
npx @ritualdev-lab/agentshield demo
bash
$ npx @ritualdev-lab/agentshield exec "cat .env && printenv"
[AgentShield] BLOCKED: Direct credential file read & environment dump (.env / printenv)
$ node print-config.js | npx @ritualdev-lab/agentshield stream
{"db":"[AGENT_SHIELD:DATABASE_URL:9f3a12]","token":"[AGENT_SHIELD:GITHUB_TOKEN:4c8e19]"}
Want to record a fresh 15-second terminal GIF? Run vhs assets/demo.tape with Charm VHS.
Autonomous coding agents have direct access to your shell, filesystem, and git repo. Even well-behaved agents routinely run cat .env, printenv, node -e 'console.log(process.env)', or commit live test keys into PRsβleaking raw credentials into third-party model APIs and git history.
AgentShield intercepts commands and stdout/stderr before credentials leave your machine:
- Obfuscation-resistant command firewall : Catches
cat .e""nv,cat .e?v,/proc/self/environ,base64/xxd,tar/cp, and inlinenode/pythonenv dumps. - Boundary-safe streaming redactor : Catches secrets split across arbitrary 1-byte TCP/stdio chunks and multiline PEM blocks (0 runtime dependencies, linear-time regex + Shannon entropy).
- OS sandbox preflight & profiles : Generates and verifies macOS Seatbelt (
sandbox-exec), Linuxbwrap/Landlock, and Windows AppContainer isolation viaagentshield doctor. - Unified 3-layer stack : Boot AgentShield +DBShield +SkillPrism from a single declarative
ritual.policy.yamlviaagentshield up.
Think you can bypass our .env / /proc/self/environ blocker or split a secret across stream chunks without triggering redaction?
npx @ritualdev-lab/agentshield bounty-verify "your-payload-here"
If you find a bypass, open an issue with your reproβevery confirmed bypass gets a regression test and credit in the repo. Check THREAT_MODEL.md for exact scope and honest OS isolation limits.
Quick Start Β· Full Guide Β· Threat Model Β· Examples (Claude Code, LangGraph, E2B/Daytona) Β· GitHub Action
npx @ritualdev-lab/agentshield doctor
npx @ritualdev-lab/agentshield hook install
npx @ritualdev-lab/agentshield init-claude
npx @ritualdev-lab/agentshield init-cursor
npx @ritualdev-lab/agentshield exec "cat .env"
Intercept and sandbox agent terminal execution. If an agent tries to read .env, dump shell variables ( printenv), or send keys to outbound endpoints, AgentShield blocks it on the fly:
npx @ritualdev-lab/agentshield exec "cat .env"
Important
Defense-in-Depth vs OS Security Boundary: Userland command inspection (AST parsing and regex heuristics) is defense-in-depth designed to prevent accidental exfiltration and common script bypasses. It is not an OS kernel security boundary. Arbitrary compiled binaries or direct kernel syscalls require true OS-level containerization.
| Platform | Primary Isolation Mechanism | Security Boundary Level | Guarantees & Limitations |
|---|---|---|---|
| macOS | macos_sandbox_exec |
Kernel-Enforced | System call mediation via Apple Seatbelt; restricts file read/write and networking outside workspace. |
| Linux | linux_landlock /bwrap |
Defense-in-Depth*(unless containerized)* | Generates Landlock LSM & bubblewrap profiles. Without a container runtime, Node child processes inherit caller privileges. |
| Windows | windows_appcontainer |
Defense-in-Depth | Generates AppContainer / Low-Integrity profile templates. Win32 child processes run with normal caller token integrity. |
| Fallback | process_level_firewall |
Defense-in-Depth | AST pattern firewall and real-time streaming redaction. |
By default, requesting kernel sandboxing on non-macOS hosts logs an isolation warning and runs under the defense-in-depth AST firewall. To fail-closed and refuse execution whenever OS-level kernel isolation cannot be guaranteed:
npx @ritualdev-lab/agentshield exec "npm test" --require-isolation
In the TypeScript SDK:
const result = await interceptor.execute(command, {
enableKernelSandbox: true,
requireIsolation: true, // Fails closed instead of silently downgrading
});
Catch leaked credentials before they enter git history. Audits staged diffs automatically:
npx @ritualdev-lab/agentshield hook git-install
npx @ritualdev-lab/agentshield hook check
Or using the standard pre-commit framework (.pre-commit-config.yaml):
repos:
- repo: https://github.com/RitualDev-Lab/AgentShield
rev: v0.1.1
hooks:
- id: agentshield
- id: agentshield-audit
Block pull requests that introduce exposed credentials into your codebase:
name: AgentShield Security Gate
on: [pull_request, push]
jobs:
secret-audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: RitualDev-Lab/AgentShield@v1
with:
fail_on_leak: "true"
Or run via CLI in any CI container:
npx @ritualdev-lab/agentshield ci --base origin/main --report security-report.md
Assess files and workspace streams against technical secret-handling controls in standard frameworks (SOC 2, PCI-DSS, HIPAA, ISO 27001):
npx @ritualdev-lab/agentshield compliance .env
π [SECRET-CONTROL ASSESSMENT] Status: NO_FINDINGS_IN_ASSESSED_CONTROLS (Assessed Controls Score: 100%)
βΉοΈ Scope: Technical secret detection, real-time streaming token redaction, and CLI command firewall.
β οΈ Disclaimer: Notice: This report reflects only the results of automated secret detection across assessed technical controls ('NO_FINDINGS_IN_ASSESSED_CONTROLS'). It does NOT establish overall organizational SOC 2, HIPAA, PCI-DSS, or ISO 27001 compliance. Overall compliance requires an accredited third-party audit firm, administrative governance, physical safeguards, and operational policies.
Assessed Controls:
β
[SOC2] CC6.1: Logical Access Controls & Credential Integrity
β
[SOC2] CC6.6: Boundary Protection & Unauthorized Egress Controls
β
[PCI_DSS] Req-3.4: Protection of Authentication & Payment Gateway Secrets
β
[PCI_DSS] Req-8.3: Strong Authentication Credential Management
β
[HIPAA] Β§164.312(a)(1): Technical Safeguards - Access Control & Authentication
β
[ISO27001] A.8.28: Secure Coding & Secret Management
β
[ISO27001] A.8.24: Use of Cryptography & Key Protection
Broader Controls (Not Assessed by Secret Scanning):
βΈοΈ [SOC2] CC1.1: Integrity & Ethical Values (Governance) (NOT ASSESSED)
βΈοΈ [SOC2] CC5.2: Risk Assessment & Vendor Management (NOT ASSESSED)
βΈοΈ [PCI_DSS] Req-9.1: Physical Access Restrictions (NOT ASSESSED)
βΈοΈ [HIPAA] Β§164.308(a)(1): Administrative Safeguards (NOT ASSESSED)
βΈοΈ [ISO27001] A.5.1: Policies for Information Security (NOT ASSESSED)
Instead of cleartext .env keys, AgentShield provides deterministic, collision-resistant surrogate tokens ([AGENT_SHIELD:ID:hexHash]). Agents can safely manipulate configurations and inspect outputs without ever seeing the plaintext secret in prompt history, rehydrating values locally when required.
AgentShield provides 1-command generators for leading AI coding agent environments:
Automatically intercept agent terminal executions before commands touch your environment:
npx @ritualdev-lab/agentshield init-claude
Generates .claude/settings.json configured with:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|Terminal",
"command": "npx @ritualdev-lab/agentshield exec --claude-hook"
}
]
}
}
Note: Claude Code delivers tool call payloads via stdin JSON. AgentShield inspects the payload in real-time and cleanly returns exit code 2 to halt unauthorized commands before execution.
npx @ritualdev-lab/agentshield init-cursor
Generates .cursor/rules.json with sensitive path boundaries (.env*, *.pem, id_rsa*) and pre-execution command sandboxing.
Plug SKILL.md into workspace agent instructions to enforce zero-leak guarantees natively.
Traditional scanners (gitleaks, trufflehog) were designed for post-facto static git repository scanning (scanning files and commit histories at rest).
AgentShield is designed specifically for Autonomous Agent Runtime Protection β intercepting shell commands, scrubbing streaming stdio chunk-by-chunk in sub-milliseconds, and sanitizing LLM prompt inputs before transmission.
| Feature / Metric | AgentShield | GitLeaks | TruffleHog |
|---|---|---|---|
| Primary Domain | Agent Runtime & Stdio Interception | Git History Scanner | Git & Filesystem Scanner |
| Average Scan Latency | < 0.04 ms / scan | ~ 2 - 5 ms | ~ 10 - 50 ms |
| Throughput | 28,000+ operations/sec | ~ 5,000 ops/sec | ~ 1,200 ops/sec |
| Streaming Stdio Interception | β
Native (createRedactingStream) |
β (Disk / Git diff only) | β (Disk / Git diff only) |
| Agent AST Command Sandbox | β
Native (exec / run) |
β None | β None |
| Deterministic Vault Rehydration | β
Native ([AGENT_SHIELD:...]) |
β None | β None |
| MCP Protocol Filter (JSON-RPC) | β
Native (mcp-proxy) |
β None | β None |
| Zero Runtime Dependencies | β 0 deps (Pure Node.js) | Go binary | Go binary / Python |
| Git Pre-Commit & CI Gates | β Built-in | β Built-in | β Built-in |
AgentShield combines high-performance regular expressions with Shannon Entropy to catch both structured keys and arbitrary high-entropy passwords:
- π€ AI Providers : OpenAI (
sk-proj-*), Anthropic Claude (sk-ant-*), Google Gemini (AIzaSy*), Hugging Face (hf_*) - βοΈ Cloud Infrastructure : AWS Access Key ID (
AKIA*), AWS Secret Access Keys - π³ Payments & SaaS : Stripe Live (
sk_live_*), Slack Incoming Webhooks - π Version Control : GitHub Personal Access Tokens (
ghp_*,github_pat_*) - π Cryptography : PEM / OpenSSH private key blocks, JSON Web Tokens (JWT)
- π Mathematical Entropy : High-entropy password detection with false-positive filtering
AgentShield provides first-class, idiomatic SDKs across multiple languages:
| Language / Platform | Package / Location | Supported Runtimes & Frameworks | Integration Pattern |
|---|---|---|---|
| Node.js / TypeScript | @ritualdev-lab/agentshield |
Node 20+, Cursor, Claude Code, MCP | In-process native TypeScript |
| Python | agentshield (sdks/python ) |
Python 3.9+, LangChain, LangGraph, CrewAI, AutoGen | In-process standalone + Sidecar |
| Go | sdks/go |
Go 1.21+, net/http middleware, Gin, Chi |
JSON-RPC 2.0 Stdio Sidecar |
| Rust | sdks/rust |
Rust 2021 edition | JSON-RPC 2.0 Stdio Sidecar |
| Any Language / Shell | agentshield sidecar |
Ruby, Elixir, PHP, C++, Bash | Stdio Line-Delimited JSON-RPC 2.0 |
Works in pure-Python without requiring Node.js, with built-in LangChain/LangGraph callbacks:
from agentshield import AgentShieldEngine, AgentShieldCallbackHandler
from langchain_openai import ChatOpenAI
shield = AgentShieldEngine()
redacted = shield.scan_and_redact("Query database with sk-proj-placeholder-token")
print(redacted["sanitizedText"])
llm = ChatOpenAI(callbacks=[AgentShieldCallbackHandler()])
import "github.com/RitualDev-Lab/agentshield/sdks/go"
client, _ := agentshield.NewClient(ctx)
defer client.Close()
res, _ := client.ScanAndRedact(ctx, "Stripe secret sk_live_placeholder_token")
fmt.Println(res.SanitizedText)
js
use agentshield::AgentShieldClient;
let client = AgentShieldClient::new()?;
let res = client.scan_and_redact("My token is ghp_placeholder_token")?;
println!("Sanitized: {}", res.sanitized_text);
Any language can interact with AgentShield via line-delimited JSON-RPC 2.0:
npx @ritualdev-lab/agentshield sidecar
{"jsonrpc": "2.0", "id": 1, "method": "shield.scanAndRedact", "params": {"text": "My API key is sk-proj-placeholder"}}
Response:
{"jsonrpc":"2.0","id":1,"result":{"hasSecrets":true,"sanitizedText":"My API key is [AGENT_SHIELD:AI:...]","findings":[...]}}
Integrate AgentShield directly into your AI workflows, proxy servers, or custom agent frameworks:
import { AgentShieldEngine, AgentCommandSandbox, AgentStdioInterceptor } from "@ritualdev-lab/agentshield";
const shield = new AgentShieldEngine();
// Scan and redact unmasked credentials from LLM prompt inputs
const rawPrompt = `Run tests with OPENAI_API_KEY=${mySecretToken}`;
const result = shield.scanAndRedact(rawPrompt);
console.log(result.hasSecrets); // true
console.log(result.sanitizedText);
// "Run tests with OPENAI_API_KEY=[AGENT_SHIELD:OPENAI_API_KEY:c2stcH]"
// Deterministically rehydrate when receiving LLM response back locally
const original = shield.rehydrate(result.sanitizedText);
- Live Documentation :https://agentshield.ritualdev.in/
- Bug Bounty Program : Read ourSECURITY.md for rewards ($50 β $500).
- Open Governance Charter : Read ourGOVERNANCE.md for project stewardship.
- Grant Applications : Review ourGRANTS.md dossier for NLnet, OpenSSF & Mozilla.
- Contributing : Check outCONTRIBUTING.md to add new secret patterns.
AgentShield is initiated and maintained by the team at RitualDev Lab and protected by the global AI security research community.
| <sub>Divyanshu Jethi</sub> <sub>π Founder & Lead</sub><sub>π Direct Access Admin</sub> | <sub>** Sakshi Sharma**</sub> <sub>π¨ Core Maintainer & Product</sub><sub>π Direct Access Admin</sub> | <sub>** RitualDev**</sub> <sub>βοΈ Core Maintainer & Infra</sub><sub>π Direct Access Admin</sub> | <sub>** Divyanshu-hub-dotcom**</sub> <sub>π οΈ Core Member</sub> | <sub>** Ayush**</sub> <sub>π‘οΈ Core Maintainer & Triage</sub> |
AgentShield is 100% open-source and Apache-2.0 licensed. Your sponsorship directly funds multi-platform OS sandbox testing rigs (Linux Landlock, macOS Seatbelt, Windows AppContainer), automated security regression suites, and cloud runner hours.
β‘ 1-Click Dodo Payments Checkout Β β’Β π Interactive Donation Form (USD & INR UPI) Β β’Β β€οΈ GitHub Sponsors
<sub>π Zero physical shipping required. Powered by Dodo Payments (Merchant of Record) with instant tax invoice and global payment methods (Cards, UPI, Apple Pay).</sub>
| <sub>ciperx</sub> <sub>π OWASP ATLAS & AEO (PR #8)</sub> | <sub>** Voyagerroc-Lab**</sub> <sub>π Security & Rules Contributor</sub> |
Huge thanks to all our open-source Contributors!
<sub>Maintained with π by</sub>