{"_id":"ecc-agentshield","_rev":"3-6f8294d8bd415b970503593127533748","name":"ecc-agentshield","dist-tags":{"latest":"1.4.0"},"versions":{"1.0.0":{"name":"ecc-agentshield","version":"1.0.0","keywords":["claude-code","security","ai-agent","mcp","hackathon","opus","anthropic","scanner","audit"],"author":{"name":"Affaan Mustafa"},"license":"MIT","_id":"ecc-agentshield@1.0.0","maintainers":[{"name":"cogsec","email":"me@affaanmustafa.com"}],"homepage":"https://github.com/affaan-m/agentshield#readme","bugs":{"url":"https://github.com/affaan-m/agentshield/issues"},"bin":{"agentshield":"dist/index.js"},"dist":{"shasum":"46440a9db41d47ffe15169384f108fc5fc10498c","tarball":"https://registry.npmjs.org/ecc-agentshield/-/ecc-agentshield-1.0.0.tgz","fileCount":9,"integrity":"sha512-fQmzS3Nv8k8Y7o6HMmuJ7sdirEEgjvYjAAUgssyyQx62wXutGhZ5VOYmuH3eaR8JK48Cesk+lZjzbH0KBEztsg==","signatures":[{"sig":"MEUCICNwQcCueXLg+aSqVdOyj3OIe3iQWcnuhEfEGSljbp+FAiEAku//wrzt50cM4RIylZn4AO5La320EWPSBLA9s5UkJaM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":106251},"type":"module","engines":{"node":">=18"},"gitHead":"e3a0a5d95704dfcf5c6581657849432063036519","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/","scan":"tsx src/index.ts scan","test":"vitest","build":"tsup src/index.ts src/action.ts --format esm --dts --clean","scan:demo":"tsx src/index.ts scan --path examples/vulnerable","typecheck":"tsc --noEmit","test:coverage":"vitest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"cogsec","email":"me@affaanmustafa.com"},"repository":{"url":"git+https://github.com/affaan-m/agentshield.git","type":"git"},"_npmVersion":"10.8.2","description":"Security auditor for AI agent configurations. Scans Claude Code setups for vulnerabilities, misconfigs, and injection risks.","directories":{},"_nodeVersion":"20.19.5","dependencies":{"zod":"^3.24.2","glob":"^11.0.1","yaml":"^2.7.0","chalk":"^5.4.1","commander":"^13.1.0","@anthropic-ai/sdk":"^0.39.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","tsup":"^8.3.6","eslint":"^9.19.0","vitest":"^3.0.5","typescript":"^5.7.3","@types/node":"^22.13.0","@vitest/coverage-v8":"^3.2.4"},"_npmOperationalInternal":{"tmp":"tmp/ecc-agentshield_1.0.0_1770805645230_0.9931987564493585","host":"s3://npm-registry-packages-npm-production"}},"1.3.0":{"name":"ecc-agentshield","version":"1.3.0","keywords":["claude-code","security","ai-agent","mcp","hackathon","opus","anthropic","scanner","audit"],"author":{"name":"Affaan Mustafa"},"license":"MIT","_id":"ecc-agentshield@1.3.0","maintainers":[{"name":"cogsec","email":"me@affaanmustafa.com"}],"homepage":"https://github.com/affaan-m/agentshield#readme","bugs":{"url":"https://github.com/affaan-m/agentshield/issues"},"bin":{"agentshield":"dist/index.js"},"dist":{"shasum":"cfd73f699061341ad16daf9875449ec2f658d4ab","tarball":"https://registry.npmjs.org/ecc-agentshield/-/ecc-agentshield-1.3.0.tgz","fileCount":23,"integrity":"sha512-akQYuYiRkHP9TYoQn8QLQ3E2v3ceWxrLDt3jU1NzEO/VU03GD0LUzUjlp64zHkg3uxDRNZ/Axea10tMYNkFK9Q==","signatures":[{"sig":"MEUCIQCxcetOHA39rSUi7eF7GRcMNubp+NspgqHheVLJi2akowIgT7W9inQONEVLmqGi8apG/mIReG5MTAcvKkQw7+106p4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":510913},"type":"module","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./miniclaw":{"types":"./dist/miniclaw/index.d.ts","import":"./dist/miniclaw/index.js"}},"gitHead":"c42333506eec4336853fc933b05a293814626b9c","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/","scan":"tsx src/index.ts scan","test":"vitest","build":"tsup src/index.ts src/action.ts src/miniclaw/index.ts --format esm --dts --clean","scan:demo":"tsx src/index.ts scan --path examples/vulnerable","typecheck":"tsc --noEmit","test:coverage":"vitest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"cogsec","email":"me@affaanmustafa.com"},"repository":{"url":"git+https://github.com/affaan-m/agentshield.git","type":"git"},"_npmVersion":"10.8.2","description":"Security auditor for AI agent configurations. Scans Claude Code setups for vulnerabilities, misconfigs, and injection risks.","directories":{},"_nodeVersion":"20.19.5","dependencies":{"zod":"^3.24.2","glob":"^11.0.1","yaml":"^2.7.0","chalk":"^5.4.1","commander":"^13.1.0","@anthropic-ai/sdk":"^0.39.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","tsup":"^8.3.6","eslint":"^9.19.0","vitest":"^3.0.5","typescript":"^5.7.3","@types/node":"^22.13.0","@vitest/coverage-v8":"^3.2.4"},"_npmOperationalInternal":{"tmp":"tmp/ecc-agentshield_1.3.0_1771270970393_0.15687039074146192","host":"s3://npm-registry-packages-npm-production"}},"1.4.0":{"name":"ecc-agentshield","version":"1.4.0","description":"Security auditor for AI agent configurations. Scans Claude Code setups for vulnerabilities, misconfigs, and injection risks.","type":"module","bin":{"agentshield":"dist/index.js"},"exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./miniclaw":{"import":"./dist/miniclaw/index.js","types":"./dist/miniclaw/index.d.ts"}},"scripts":{"build":"tsup src/index.ts src/action.ts src/miniclaw/index.ts --format esm --dts --clean --no-splitting","prepublishOnly":"npm run build","dev":"tsx src/index.ts","test":"npm run test:batch:core && npm run test:batch:analysis && npm run test:batch:miniclaw-a && npm run test:batch:miniclaw-b && npm run test:batch:misc","test:batch:core":"vitest run tests/rules/*.test.ts tests/scanner/*.test.ts tests/reporter/*.test.ts","test:batch:analysis":"vitest run tests/integration.test.ts tests/injection.test.ts tests/action.test.ts","test:batch:miniclaw-a":"vitest run tests/miniclaw/index.test.ts tests/miniclaw/server.test.ts","test:batch:miniclaw-b":"vitest run tests/miniclaw/cli.test.ts tests/miniclaw/sandbox.test.ts","test:batch:misc":"vitest run tests/corpus.test.ts tests/logger.test.ts tests/init/init.test.ts tests/taint/taint.test.ts tests/opus/*.test.ts tests/fixer/*.test.ts tests/types.test.ts tests/skills/*.test.ts tests/miniclaw/router.test.ts tests/miniclaw/tools.test.ts tests/miniclaw/types.test.ts tests/sandbox/sandbox.test.ts tests/threat-intel/*.test.ts tests/watch/*.test.ts tests/runtime/*.test.ts tests/baseline/*.test.ts tests/supply-chain/*.test.ts tests/policy/*.test.ts","test:coverage":"vitest --coverage","lint":"eslint src/","typecheck":"tsc --noEmit","scan":"tsx src/index.ts scan","scan:demo":"tsx src/index.ts scan --path examples/vulnerable"},"keywords":["claude-code","security","ai-agent","mcp","hackathon","opus","anthropic","scanner","audit"],"author":{"name":"Affaan Mustafa"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/affaan-m/agentshield.git"},"homepage":"https://github.com/affaan-m/agentshield#readme","bugs":{"url":"https://github.com/affaan-m/agentshield/issues"},"dependencies":{"@anthropic-ai/sdk":"^0.39.0","chalk":"^5.4.1","commander":"^13.1.0","glob":"^11.0.1","yaml":"^2.7.0","zod":"^3.24.2"},"devDependencies":{"@types/node":"^22.13.0","@vitest/coverage-v8":"^3.2.4","eslint":"^9.19.0","tsup":"^8.3.6","tsx":"^4.19.2","typescript":"^5.7.3","vitest":"^3.0.5"},"overrides":{"ajv":"^6.14.0","flatted":"^3.4.0"},"engines":{"node":">=18"},"_id":"ecc-agentshield@1.4.0","gitHead":"bff08f0bcd5b8501b46a9bd9b493c4910379a3e2","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-R98OO1Ujyk2lezDLb+iQmMhF6FwTJCHajy3G4FCB6x7wkSTqR9f8+eAelC5KDzYDsGSbc0sOZvjXOOPRBtMpDg==","shasum":"2337dfa586c35664d3150183718c27ef0bed1e52","tarball":"https://registry.npmjs.org/ecc-agentshield/-/ecc-agentshield-1.4.0.tgz","fileCount":11,"unpackedSize":1058729,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG70EjaGxL/hgbBhbrBKN2ufGVdCPqcnr9YqVcJjAbUeAiEA/vxGpdyN+NTLz9oQSWJgUz6Lr3y3CQ+rEFqNk73ppZc="}]},"_npmUser":{"name":"cogsec","email":"me@affaanmustafa.com"},"directories":{},"maintainers":[{"name":"cogsec","email":"me@affaanmustafa.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ecc-agentshield_1.4.0_1774070985659_0.22918729475664423"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-11T10:27:25.230Z","modified":"2026-03-21T05:29:45.974Z","1.0.0":"2026-02-11T10:27:25.375Z","1.3.0":"2026-02-16T19:42:50.564Z","1.4.0":"2026-03-21T05:29:45.858Z"},"bugs":{"url":"https://github.com/affaan-m/agentshield/issues"},"author":{"name":"Affaan Mustafa"},"license":"MIT","homepage":"https://github.com/affaan-m/agentshield#readme","keywords":["claude-code","security","ai-agent","mcp","hackathon","opus","anthropic","scanner","audit"],"repository":{"type":"git","url":"git+https://github.com/affaan-m/agentshield.git"},"description":"Security auditor for AI agent configurations. Scans Claude Code setups for vulnerabilities, misconfigs, and injection risks.","maintainers":[{"name":"cogsec","email":"me@affaanmustafa.com"}],"readme":"<div align=\"center\">\n\n# AgentShield\n\n**Security auditor for AI agent configurations**\n\nScans Claude Code setups for hardcoded secrets, permission misconfigs,<br/>\nhook injection, MCP server risks, and agent prompt injection vectors.\n\n[![npm version](https://img.shields.io/npm/v/ecc-agentshield)](https://www.npmjs.com/package/ecc-agentshield)\n[![npm downloads](https://img.shields.io/npm/dm/ecc-agentshield)](https://www.npmjs.com/package/ecc-agentshield)\n[![tests](https://img.shields.io/badge/tests-passing-brightgreen)]()\n[![coverage](https://img.shields.io/badge/coverage-v8-blue)]()\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n[Quick Start](#quick-start) · [What It Catches](#what-it-catches) · [Opus Pipeline](#opus-46-deep-analysis---opus) · [GitHub Action](#github-action) · [MiniClaw](#miniclaw) · [Distribution](#distribution) · [Changelog](./CHANGELOG.md)\n\n</div>\n\n---\n\n## Why\n\nThe AI agent ecosystem is growing faster than its security tooling. In January 2026 alone:\n\n- **12%** of a major agent skill marketplace was malicious (341 of 2,857 community skills)\n- A **CVSS 8.8** CVE exposed 17,500+ internet-facing instances to one-click RCE\n- The Moltbook breach compromised **1.5M API tokens** across 770,000 agents\n\nDevelopers install community skills, connect MCP servers, and configure hooks without any automated way to audit the security of their setup. AgentShield scans your `.claude/` directory and flags vulnerabilities before they become exploits.\n\nBuilt at the [Claude Code Hackathon](https://cerebralvalley.ai/e/claude-code-hackathon) (Cerebral Valley x Anthropic, Feb 2026). Part of the [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) ecosystem (42K+ stars).\n\n## Quick Start\n\n```bash\n# Scan your Claude Code config (no install required)\nnpx ecc-agentshield scan\n\n# Or install globally\nnpm install -g ecc-agentshield\nagentshield scan\n```\n\nThat's it. AgentShield auto-discovers your `~/.claude/` directory, scans all config files, and prints a graded security report.\n\n```\n  AgentShield Security Report\n\n  Grade: F (0/100)\n\n  Score Breakdown\n  Secrets        ░░░░░░░░░░░░░░░░░░░░ 0\n  Permissions    ░░░░░░░░░░░░░░░░░░░░ 0\n  Hooks          ░░░░░░░░░░░░░░░░░░░░ 0\n  MCP Servers    ░░░░░░░░░░░░░░░░░░░░ 0\n  Agents         ░░░░░░░░░░░░░░░░░░░░ 0\n\n  ● CRITICAL  Hardcoded Anthropic API key\n    CLAUDE.md:13\n    Evidence: sk-ant-a...cdef\n    Fix: Replace with environment variable reference [auto-fixable]\n\n  ● CRITICAL  Overly permissive allow rule: Bash(*)\n    settings.json\n    Evidence: Bash(*)\n    Fix: Restrict to specific commands: Bash(git *), Bash(npm *), Bash(node *)\n\n  Summary\n  Files scanned: 6\n  Findings: 73 total — 19 critical, 29 high, 15 medium, 4 low, 6 info\n  Auto-fixable: 8 (use --fix)\n```\n\n### More commands\n\n```bash\n# Scan a specific directory\nagentshield scan --path /path/to/.claude\n\n# Auto-fix safe issues (replaces hardcoded secrets with env var references)\nagentshield scan --fix\n\n# JSON output for CI pipelines\nagentshield scan --format json\n\n# Generate an HTML security report\nagentshield scan --format html > report.html\n\n# Three-agent Opus 4.6 adversarial analysis (requires ANTHROPIC_API_KEY)\nagentshield scan --opus --stream\n\n# Generate a secure baseline config\nagentshield init\n```\n\n## What It Catches\n\n**102 rules** across 5 categories, graded A–F with a 0–100 numeric score.\n\n### Secrets Detection (10 rules, 14 patterns)\n\n| What | Examples |\n|------|----------|\n| API keys | Anthropic (`sk-ant-`), OpenAI (`sk-proj-`), AWS (`AKIA`), Google (`AIza`), Stripe (`sk_test_`/`sk_live_`) |\n| Tokens | GitHub PATs (`ghp_`/`github_pat_`), Slack (`xox[bprs]-`), JWTs (`eyJ...`), Bearer tokens |\n| Credentials | Hardcoded passwords, database connection strings (postgres/mongo/mysql/redis), private key material |\n| Env leaks | Secrets passed through environment variables in configs, `echo $SECRET` in hooks |\n\n### Permission Audit (10 rules)\n\n| What | Examples |\n|------|----------|\n| Wildcard access | `Bash(*)`, `Write(*)`, `Edit(*)` — unrestricted tool permissions |\n| Missing deny lists | No deny rules for `rm -rf`, `sudo`, `chmod 777` |\n| Dangerous flags | `--dangerously-skip-permissions` usage |\n| Mutable tool exposure | All mutable tools (Write, Edit, Bash) allowed without scoping |\n| Destructive git | `git push --force`, `git reset --hard` in allowed commands |\n| Unrestricted network | `curl *`, `wget`, `ssh *`, `scp *` in allow list without scope |\n\n### Hook Analysis (34 rules)\n\n| What | Examples |\n|------|----------|\n| Command injection | `${file}` interpolation in shell commands — attacker-controlled filenames become code |\n| Data exfiltration | `curl -X POST` with variable interpolation sending data to external URLs |\n| Silent errors | `2>/dev/null`, `\\|\\| true` — failing security hooks that silently pass |\n| Missing hooks | No PreToolUse hooks, no Stop hooks for session-end validation |\n| Network exposure | Unthrottled network requests in hooks, sensitive file access without filtering |\n| Session startup | SessionStart hooks that download and execute remote scripts |\n| Package installs | Global `npm install -g`, `pip install`, `gem install`, `cargo install` in hooks |\n| Container escape | Docker `--privileged`, `--pid=host`, `--network=host`, root volume mounts |\n| Credential access | macOS Keychain, GNOME Keyring, /etc/shadow reads |\n| Reverse shells | `/dev/tcp`, `mkfifo + nc`, Python/Perl socket shells |\n| Clipboard access | `pbcopy`, `xclip`, `xsel`, `wl-copy` — exfiltration via clipboard |\n| Log tampering | `journalctl --vacuum`, `rm /var/log`, `history -c` — anti-forensics |\n\n### MCP Server Security (23 rules)\n\n| What | Examples |\n|------|----------|\n| High-risk servers | Shell/command MCPs, filesystem with root access, database MCPs, browser automation |\n| Supply chain | `npx -y` auto-install without confirmation — typosquatting vector |\n| Hardcoded secrets | API tokens in MCP environment config instead of env var references |\n| Remote transport | MCP servers connecting to remote URLs (SSE/streamable HTTP) |\n| Shell metacharacters | `&&`, `\\|`, `;` in MCP server command arguments |\n| Missing metadata | No version pin, no description, excessive server count |\n| Sensitive file args | `.env`, `.pem`, `credentials.json` passed as server arguments |\n| Network exposure | Binding to `0.0.0.0` instead of localhost |\n| Auto-approve | `autoApprove` settings that skip user confirmation for tool calls |\n| Missing timeouts | High-risk servers without timeout — resource exhaustion risk |\n\n### Agent Config Review (25 rules)\n\n| What | Examples |\n|------|----------|\n| Unrestricted tools | Agents with Bash access, no `allowedTools` restriction |\n| Prompt injection surface | Agents processing external/user-provided content without defenses |\n| Auto-run instructions | `CLAUDE.md` containing \"Always run\", \"without asking\", \"automatically install\" |\n| Hidden instructions | Unicode zero-width characters, HTML comments, base64-encoded directives |\n| URL execution | `CLAUDE.md` instructing agents to fetch and execute remote URLs |\n| Time bombs | Delayed execution instructions triggered by time or absence conditions |\n| Data harvesting | Bulk collection of passwords, credentials, or database dumps |\n| Prompt reflection | `ignore previous instructions`, `you are now`, DAN jailbreak, fake system prompts |\n| Output manipulation | `always report ok`, `remove warnings from output`, suppress security findings |\n\n## Features\n\n### Auto-Fix Engine (`--fix`)\n\nAutomatically applies safe fixes:\n- Replaces hardcoded secrets with `${ENV_VAR}` references\n- Tightens wildcard permissions (`Bash(*)` → scoped `Bash(git *)`, `Bash(npm *)`)\n\nOnly fixes marked `auto: true` are applied. Permission changes require human review.\n\n### Secure Init (`agentshield init`)\n\nGenerates a hardened `.claude/` directory with scoped permissions, safety hooks, and security best practices. Existing files are never overwritten.\n\n### Opus 4.6 Deep Analysis (`--opus`)\n\nThree-agent adversarial pipeline powered by Claude Opus 4.6:\n\n1. **Red Team (Attacker)** — finds exploitable attack vectors and multi-step chains\n2. **Blue Team (Defender)** — evaluates existing protections and recommends hardening\n3. **Auditor** — synthesizes both perspectives into a prioritized risk assessment\n\nThe Attacker finds that `curl` hooks with `${file}` interpolation + `Bash(*)` = command injection pivot. The Defender notes no PreToolUse hooks exist to stop it. The Auditor chains them into a prioritized action list.\n\n```bash\nagentshield scan --opus              # Red + Blue run in parallel\nagentshield scan --opus --stream     # Sequential with real-time output\nagentshield scan --opus --stream -v  # Verbose — see full agent reasoning\n```\n\n```\n  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n  ┃  Phase 1a: ATTACKER (Red Team)                       ┃\n  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛\n\n  ✓ Attacker analysis complete (4521 tokens)\n\n  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n  ┃  Phase 1b: DEFENDER (Blue Team)                      ┃\n  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛\n\n  ✓ Defender analysis complete (3892 tokens)\n\n  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n  ┃  Phase 2: AUDITOR                                    ┃\n  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛\n\n  Risk Level: CRITICAL\n  Opus Score: █████░░░░░░░░░░░░░░░ 15/100\n```\n\nRequires `ANTHROPIC_API_KEY` environment variable.\n\n### Output Formats\n\n| Format | Flag | Use Case |\n|--------|------|----------|\n| Terminal | `--format terminal` (default) | Interactive use |\n| JSON | `--format json` | CI pipelines, programmatic access |\n| Markdown | `--format markdown` | Documentation, PRs |\n| HTML | `--format html` | Self-contained shareable report (dark theme, all CSS inlined) |\n\n## GitHub Action\n\n```yaml\n- name: AgentShield Security Scan\n  uses: affaan-m/agentshield@v1\n  with:\n    path: \".\"\n    min-severity: \"medium\"\n    fail-on-findings: \"true\"\n```\n\n**Inputs:**\n\n| Input | Default | Description |\n|-------|---------|-------------|\n| `path` | `.` | Path to scan |\n| `min-severity` | `medium` | Minimum severity: critical, high, medium, low, info |\n| `fail-on-findings` | `true` | Fail the action if findings meet severity threshold |\n| `format` | `terminal` | Output format |\n\n**Outputs:** `score` (0–100), `grade` (A–F), `total-findings`, `critical-count`\n\nThe action writes a markdown job summary and emits GitHub annotations inline on affected files.\n\n## CLI Reference\n\n```\nagentshield scan [options]         Scan configuration directory\n  -p, --path <path>                Path to scan (default: ~/.claude or cwd)\n  -f, --format <format>            Output: terminal, json, markdown, html\n  --fix                            Auto-apply safe fixes\n  --opus                           Enable Opus 4.6 multi-agent analysis\n  --stream                         Stream Opus analysis in real-time\n  --min-severity <severity>        Filter: critical, high, medium, low, info\n  -v, --verbose                    Show detailed output\n\nagentshield init                   Generate secure baseline config\n\nagentshield miniclaw start [opts]  Launch MiniClaw secure agent server\n  -p, --port <port>                Port (default: 3847)\n  -H, --hostname <host>            Hostname (default: localhost)\n  --network <policy>               Network: none, localhost, allowlist\n  --rate-limit <n>                 Max req/min per IP (default: 10)\n  --sandbox-root <path>            Root path for sandboxes\n  --max-duration <ms>              Max session duration (default: 300000)\n```\n\n## Security Rules Summary\n\n| Category | Rules | Patterns | Severity Range |\n|----------|-------|----------|----------------|\n| Secrets | 10 | 14 | Critical -- Medium |\n| Permissions | 10 | -- | Critical -- Medium |\n| Hooks | 34 | -- | Critical -- Low |\n| MCP Servers | 23 | -- | Critical -- Info |\n| Agents | 25 | -- | Critical -- Info |\n| **Total** | **102** | **14** | |\n\n## Architecture\n\n```\nsrc/\n├── index.ts              CLI entry point (commander)\n├── action.ts             GitHub Action entry point\n├── types.ts              Type system + Zod schemas\n├── scanner/\n│   ├── discovery.ts      Config file discovery\n│   └── index.ts          Scan orchestrator\n├── rules/\n│   ├── index.ts          Rule registry\n│   ├── secrets.ts        Secret detection (10 rules, 14 patterns)\n│   ├── permissions.ts    Permission audit (10 rules)\n│   ├── mcp.ts            MCP server security (23 rules)\n│   ├── hooks.ts          Hook analysis (34 rules)\n│   └── agents.ts         Agent config review (25 rules)\n├── reporter/\n│   ├── score.ts          Scoring engine (A-F grades)\n│   ├── terminal.ts       Color terminal output\n│   ├── json.ts           JSON + Markdown output\n│   └── html.ts           Self-contained HTML report\n├── fixer/\n│   ├── transforms.ts     Fix transforms (secret, permission, generic)\n│   └── index.ts          Fix engine orchestrator\n├── init/\n│   └── index.ts          Secure config generator\n├── opus/\n│   ├── prompts.ts        Attacker/Defender/Auditor system prompts\n│   ├── pipeline.ts       Three-agent Opus 4.6 pipeline\n│   └── render.ts         Opus analysis rendering\n└── miniclaw/\n    ├── types.ts          Core type system (immutable, readonly)\n    ├── sandbox.ts        Sandbox lifecycle + path validation\n    ├── router.ts         Prompt sanitization + output filtering\n    ├── tools.ts          Whitelist-based tool authorization\n    ├── server.ts         HTTP server with rate limiting + CORS\n    ├── dashboard.tsx     React dashboard component\n    └── index.ts          Entry point and re-exports\n```\n\n## MiniClaw\n\nMiniClaw is a minimal, sandboxed AI agent runtime bundled with AgentShield. Where typical agent platforms expose many attack surfaces (Telegram, Discord, email, community plugins), MiniClaw presents a **single HTTP endpoint** backed by an **isolated sandbox**.\n\n```bash\n# Start with secure defaults (localhost:3847, no network, safe tools only)\nnpx ecc-agentshield miniclaw start\n\n# Custom configuration\nnpx ecc-agentshield miniclaw start --port 4000 --network localhost --rate-limit 20\n```\n\nOr use as a library:\n\n```typescript\nimport { startMiniClaw } from 'ecc-agentshield/miniclaw';\n\nconst { server, stop } = startMiniClaw();\n// Listening on http://localhost:3847\n```\n\n### Security Model\n\nFour independently enforced layers:\n\n```\nRequest → [Rate Limit] → [CORS] → [Size Cap] → [Sanitize Prompt]\n                                                       ↓\n                                                 [Tool Whitelist]\n                                                       ↓\n                                                   [Sandbox FS]\n                                                       ↓\n                                                 [Filter Output] → Response\n```\n\n- **Server** — Rate limiting (10 req/min/IP), CORS, 10KB request cap, localhost-only binding\n- **Prompt Router** — Strips 12+ injection pattern categories (system prompt overrides, identity reassignment, jailbreaks, data exfiltration URLs, zero-width Unicode, base64 payloads)\n- **Tool Whitelist** — Three tiers: Safe (read/search/list), Guarded (write/edit), Restricted (bash/network — disabled by default)\n- **Sandbox** — Isolated filesystem per session, path traversal blocked, symlink escape detection, extension whitelist, 10MB file cap, 5-min timeout, no network by default\n\n### API\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/api/prompt` | Send a prompt |\n| `POST` | `/api/session` | Create a sandboxed session |\n| `GET` | `/api/session` | Session info |\n| `DELETE` | `/api/session/:id` | Destroy session + cleanup |\n| `GET` | `/api/events/:sessionId` | Security audit events |\n| `GET` | `/api/health` | Health check |\n\nMiniClaw has **zero external runtime dependencies** — Node.js built-ins only (`http`, `fs`, `path`, `crypto`). The optional React dashboard requires React 18+ as a peer dependency.\n\n## Development\n\n```bash\nnpm install          # Install dependencies\nnpm run dev          # Development mode\nnpm test             # Run tests (912 tests)\nnpm run test:coverage # Coverage report\nnpm run typecheck    # Type check\nnpm run build        # Build\nnpm run scan:demo    # Demo scan against vulnerable examples\n```\n\n## Distribution\n\nAgentShield is available through multiple channels:\n\n| Channel | Use Case | Install |\n|---------|----------|---------|\n| **Standalone CLI** | Direct scanning from your terminal | `npm install -g ecc-agentshield` or `npx ecc-agentshield scan` |\n| **GitHub Action** | Automated security checks on PRs in CI/CD | `uses: affaan-m/agentshield@v1` |\n| **ECC Plugin** | Claude Code users via the ECC skill ecosystem | Install through [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) |\n| **ECC Tools GitHub App** | Integrated scanning across your GitHub org | Install at [github.com/apps/ecc-tools](https://github.com/apps/ecc-tools) |\n\n## License\n\nMIT\n\n---\n\n<div align=\"center\">\n\nBuilt by [@affaanmustafa](https://x.com/affaanmustafa) · Part of [Everything Claude Code](https://github.com/affaan-m/everything-claude-code)\n\n</div>\n","readmeFilename":"README.md"}