# Show HN: AgentShield Zero-dep secret redactor and shell firewall for Claude

> Source: <https://github.com/RitualDev-Lab/AgentShield>
> Published: 2026-11-18 04:39:11+00:00

**Key takeaway:** AgentShield wraps agent shell commands via `agentshield exec` and streams stdout through a redactor that catches secrets split across 1-byte chunks and multiline PEM blocks, blocking `.env` reads and `printenv` dumps at under 20 µs P99 redaction.

**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`](https://github.com/RitualDev-Lab/AgentShield/blob/main/assets/demo.tape) with [Charm VHS](https://github.com/charmbracelet/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 inline`node` /`python` env 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` ), Linux`bwrap` /Landlock, and Windows AppContainer isolation via`agentshield doctor` .
- **Unified 3-layer stack** : Boot AgentShield +[DBShield](https://github.com/RitualDev-Lab/DBShield) +[SkillPrism](https://github.com/RitualDev-Lab/SkillPrism) from a single declarative[`ritual.policy.yaml`](https://github.com/RitualDev-Lab/AgentShield/blob/main/examples/ritual.policy.yaml) via`agentshield 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`](https://github.com/RitualDev-Lab/AgentShield/blob/main/THREAT_MODEL.md) for exact scope and honest OS isolation limits.

[Quick Start](#-instant-30-second-setup) · [Full Guide](https://github.com/RitualDev-Lab/AgentShield/blob/main/GUIDE.md) · [Threat Model](https://github.com/RitualDev-Lab/AgentShield/blob/main/THREAT_MODEL.md) · [Examples (Claude Code, LangGraph, E2B/Daytona)](https://github.com/RitualDev-Lab/AgentShield/blob/main/examples) · [GitHub Action](#-3-cicd-security-gate--github-action)

```
# 1. Diagnose your OS sandbox (Seatbelt / bwrap / Landlock / AppContainer)
npx @ritualdev-lab/agentshield doctor

# 2. Install a git pre-commit secret leak gate
npx @ritualdev-lab/agentshield hook install

# 3. Generate Claude Code PreToolUse or Cursor hooks
npx @ritualdev-lab/agentshield init-claude
npx @ritualdev-lab/agentshield init-cursor

# 4. Wrap any agent shell command safely
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"
# 🚨 [AgentShield Sandbox Block] Blocked attempt to read raw .env or private credential file.
# Protected credentials from entering agent LLM context window!
```

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:

```
# Refuse execution if the host cannot enforce true OS kernel isolation
npx @ritualdev-lab/agentshield exec "npm test" --require-isolation
# 🛑 [AgentShield Isolation Refusal] Execution refused: requireIsolation is enabled, but OS-level kernel isolation is unavailable on host (win32). Refusing to silently downgrade to process-level firewall.
```

In the TypeScript SDK:

``` js
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:

```
# Install once in your repo (native git hook)
npx @ritualdev-lab/agentshield hook git-install

# Or manually audit staged files
npx @ritualdev-lab/agentshield hook check
```

Or using the standard [pre-commit](https://pre-commit.com/) 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`](https://github.com/RitualDev-Lab/AgentShield/blob/main/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:

``` python
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"])
# "Query database with [AGENT_SHIELD:AI:7b3a4f1c]"

# Attach to LangChain to protect prompt inputs automatically:
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:

``` js
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/](https://agentshield.ritualdev.in/)
- **Bug Bounty Program** : Read our[SECURITY.md](https://github.com/RitualDev-Lab/AgentShield/blob/main/SECURITY.md) for rewards ($50 – $500).
- **Open Governance Charter** : Read our[GOVERNANCE.md](https://github.com/RitualDev-Lab/AgentShield/blob/main/GOVERNANCE.md) for project stewardship.
- **Grant Applications** : Review our[GRANTS.md](https://github.com/RitualDev-Lab/AgentShield/blob/main/GRANTS.md) dossier for NLnet, OpenSSF & Mozilla.
- **Contributing** : Check out[CONTRIBUTING.md](https://github.com/RitualDev-Lab/AgentShield/blob/main/CONTRIBUTING.md) to add new secret patterns.

AgentShield is initiated and maintained by the team at [RitualDev Lab](https://github.com/RitualDev-Lab) and protected by the global AI security research community.

|    [<sub>**Divyanshu Jethi**</sub>](https://github.com/divyanshujethi) <sub>🚀 Founder & Lead</sub><sub>🔑 **Direct Access Admin**</sub> |    [<sub>** Sakshi Sharma**</sub>](https://github.com/Sakshisharma1616) <sub>🎨 Core Maintainer & Product</sub><sub>🔑 **Direct Access Admin**</sub> |    [<sub>** RitualDev**</sub>](https://github.com/Ritual-Dev-Git) <sub>⚙️ Core Maintainer & Infra</sub><sub>🔑 **Direct Access Admin**</sub> |    [<sub>** Divyanshu-hub-dotcom**</sub>](https://github.com/Divyanshu-hub-dotcom) <sub>🛠️ Core Member</sub> |    [<sub>** Ayush**</sub>](https://github.com/ayushxx01) <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**](https://checkout.dodopayments.com/buy/pdt_0NpjONGugY5QkrFDUaPva)  •  [**🎁 Interactive Donation Form (USD & INR UPI)**](https://ritualdev.in/donate)  •  **❤️ 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>](https://github.com/ciperx) <sub>📜 OWASP ATLAS & AEO (PR #8)</sub> |    [<sub>** Voyagerroc-Lab**</sub>](https://github.com/Voyagerroc-Lab) <sub>🔒 Security & Rules Contributor</sub> | 

  Huge thanks to all our open-source [Contributors](https://github.com/RitualDev-Lab/AgentShield/graphs/contributors)!

<sub>Maintained with 💜 by</sub>
