{"_id":"ecc-agentshield","_rev":"5-4e672bbb9599708d02f212f3c7ac4968","name":"ecc-agentshield","dist-tags":{"latest":"1.6.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","keywords":["claude-code","security","ai-agent","mcp","hackathon","opus","anthropic","scanner","audit"],"author":{"name":"Affaan Mustafa"},"license":"MIT","_id":"ecc-agentshield@1.4.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":"2337dfa586c35664d3150183718c27ef0bed1e52","tarball":"https://registry.npmjs.org/ecc-agentshield/-/ecc-agentshield-1.4.0.tgz","fileCount":11,"integrity":"sha512-R98OO1Ujyk2lezDLb+iQmMhF6FwTJCHajy3G4FCB6x7wkSTqR9f8+eAelC5KDzYDsGSbc0sOZvjXOOPRBtMpDg==","signatures":[{"sig":"MEUCIG70EjaGxL/hgbBhbrBKN2ufGVdCPqcnr9YqVcJjAbUeAiEA/vxGpdyN+NTLz9oQSWJgUz6Lr3y3CQ+rEFqNk73ppZc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1058729},"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":"bff08f0bcd5b8501b46a9bd9b493c4910379a3e2","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/","scan":"tsx src/index.ts scan","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","build":"tsup src/index.ts src/action.ts src/miniclaw/index.ts --format esm --dts --clean --no-splitting","scan:demo":"tsx src/index.ts scan --path examples/vulnerable","typecheck":"tsc --noEmit","test:coverage":"vitest --coverage","prepublishOnly":"npm run build","test:batch:core":"vitest run tests/rules/*.test.ts tests/scanner/*.test.ts tests/reporter/*.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: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"},"_npmUser":{"name":"cogsec","email":"me@affaanmustafa.com"},"overrides":{"ajv":"^6.14.0","flatted":"^3.4.0"},"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.4.0_1774070985659_0.22918729475664423","host":"s3://npm-registry-packages-npm-production"}},"1.5.0":{"name":"ecc-agentshield","version":"1.5.0","keywords":["claude-code","security","ai-agent","mcp","hackathon","opus","anthropic","scanner","audit"],"author":{"name":"Affaan Mustafa"},"license":"MIT","_id":"ecc-agentshield@1.5.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":"062a384de2d66e60b16d3f8ba7bbc0dffbb6b205","tarball":"https://registry.npmjs.org/ecc-agentshield/-/ecc-agentshield-1.5.0.tgz","fileCount":12,"integrity":"sha512-XyV5GtoelUm9KlaELun2ezpUbnAy0C8llk1OgkwAqGwRQgNk7m+qNouGVwS/9l4nW6/bcXRToBhhpRLYCUIs0Q==","signatures":[{"sig":"MEUCIBXBiouMR5WJSzpYCYqAhHM041U+XbjN67n1VycFY0qIAiEAhoO4k3XhefAqPNcPpHKBDICTJDY1R6Oux+pvbn5J0YE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1907016},"type":"module","_from":"file:ecc-agentshield-1.5.0.tgz","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"}},"scripts":{"dev":"tsx src/index.ts","lint":"eslint src/","scan":"tsx src/index.ts scan","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","build":"tsup","scan:demo":"tsx src/index.ts scan --path examples/vulnerable","typecheck":"tsc --noEmit","corpus:gate":"node dist/index.js scan --path .github --corpus-gate","test:coverage":"vitest --coverage","prepublishOnly":"npm run build","test:batch:core":"vitest run tests/rules/*.test.ts tests/scanner/*.test.ts tests/reporter/*.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/evidence-pack/*.test.ts tests/supply-chain/*.test.ts tests/policy/*.test.ts tests/sponsor-surface.test.ts","test:batch:analysis":"vitest run tests/integration.test.ts tests/injection.test.ts tests/action.test.ts tests/action-policy.test.ts tests/action-supply-chain.test.ts tests/action-hardening.test.ts tests/action-promotion.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"},"_npmUser":{"name":"cogsec","email":"me@affaanmustafa.com"},"_resolved":"/private/tmp/claude-501/-Users-affoon-GitHub/859e4f0a-e600-45dc-97dd-8a79177e8844/scratchpad/rel/ecc-agentshield-1.5.0.tgz","overrides":{"ajv":"^6.14.0","flatted":"^3.4.0"},"_integrity":"sha512-XyV5GtoelUm9KlaELun2ezpUbnAy0C8llk1OgkwAqGwRQgNk7m+qNouGVwS/9l4nW6/bcXRToBhhpRLYCUIs0Q==","repository":{"url":"git+https://github.com/affaan-m/agentshield.git","type":"git"},"_npmVersion":"10.9.8","description":"Security auditor for AI agent configurations. Scans Claude Code setups for vulnerabilities, misconfigs, and injection risks.","directories":{},"_nodeVersion":"22.23.2","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","globals":"^17.4.0","@eslint/js":"^9.39.2","typescript":"^5.7.3","@types/node":"^22.13.0","typescript-eslint":"^8.58.1","@vitest/coverage-v8":"^3.2.4"},"_npmOperationalInternal":{"tmp":"tmp/ecc-agentshield_1.5.0_1789037953295_0.8233734447295649","host":"s3://npm-registry-packages-npm-production"}},"1.6.0":{"name":"ecc-agentshield","version":"1.6.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","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":"node scripts/test-batch.mjs core","test:batch:analysis":"node scripts/test-batch.mjs analysis","test:batch:miniclaw-a":"node scripts/test-batch.mjs miniclaw-a","test:batch:miniclaw-b":"node scripts/test-batch.mjs miniclaw-b","test:batch:misc":"node scripts/test-batch.mjs misc","test:coverage":"vitest --coverage","lint":"eslint src/","typecheck":"tsc --noEmit","corpus:gate":"node dist/index.js scan --path .github --corpus-gate","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","smol-toml":"^1.8.0","yaml":"^2.7.0","zod":"^3.24.2"},"devDependencies":{"@eslint/js":"^9.39.2","@types/node":"^22.13.0","@vitest/coverage-v8":"^4.1.11","eslint":"^9.19.0","globals":"^17.4.0","tsup":"^8.3.6","tsx":"^4.19.2","typescript":"^5.7.3","typescript-eslint":"^8.58.1","vitest":"^4.1.11"},"overrides":{"ajv":"^6.14.0","flatted":"^3.4.0"},"engines":{"node":">=20"},"_id":"ecc-agentshield@1.6.0","_integrity":"sha512-lpeHG96DtEn7ofq7Iiyvq29piQOwParaiZOdDB206i4ZeCL4yjwT6xN5BSGI4yhCEAN0eO0f9F9hxHLBuRqf/g==","_resolved":"/Users/affoon/GitHub/agentshield/ecc-agentshield-1.6.0.tgz","_from":"file:ecc-agentshield-1.6.0.tgz","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-lpeHG96DtEn7ofq7Iiyvq29piQOwParaiZOdDB206i4ZeCL4yjwT6xN5BSGI4yhCEAN0eO0f9F9hxHLBuRqf/g==","shasum":"79f563b25159ea1ad386275a5a1e5d41ca128724","tarball":"https://registry.npmjs.org/ecc-agentshield/-/ecc-agentshield-1.6.0.tgz","fileCount":12,"unpackedSize":2543162,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCICbYKuhSAhPvi4sb+VYwaKeIrizZUporGE8+23/cY9wIhALA32ybs5NavorttiimjWU/5UCWENnToiQU3K+M9BPYY"}]},"_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.6.0_1789044682292_0.9364185140455881"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-11T10:27:25.230Z","modified":"2026-09-10T12:51:22.612Z","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","1.5.0":"2026-09-10T10:59:13.438Z","1.6.0":"2026-09-10T12:51:22.445Z"},"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<img src=\"./assets/agentshield-logo.png\" alt=\"AgentShield\" width=\"180\" />\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.<br/>\nAvailable as CLI, GitHub Action, and [GitHub App](https://github.com/apps/ecc-tools) integration.\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) · [API Reference](#api-reference) · [Opus Pipeline](#opus-46-deep-analysis---opus) · [GitHub Action](#github-action) · [Distribution](#distribution) · [MiniClaw](#miniclaw) · [Changelog](./CHANGELOG.md)\n\n<a href=\"https://compute.itomarkets.com\">\n  <img src=\"./assets/ito.svg\" alt=\"Itô Markets\" width=\"180\" />\n</a>\n<br />\n<sub><strong>Preferred compute sponsor:</strong> Run or self-host any open-source model. Itô is ECC's suggested compute provider. Any GPU provider works. ECC only links to the Itô dashboard for sign-in and GPU rental or management; it does not create or manage rentals or provision compute or serving. Managed inference through Itô is not live yet.</sub>\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\nDiscovery intentionally skips common generated directories such as `node_modules`, build output, and `.dmux` worktree mirrors so transient copies do not duplicate findings.\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 executive security report\nagentshield scan --format html > report.html\n\n# Generate a portable audit bundle\nagentshield scan --evidence-pack ./agentshield-evidence\n\n# Three-agent Claude Opus adversarial analysis (requires ANTHROPIC_API_KEY)\nagentshield scan --opus --stream\n\n# Generate a secure baseline config\nagentshield init\n```\n\nJSON reports now expose `findings[].runtimeConfidence` when AgentShield can distinguish active runtime config from project-local settings, template/example inventories, installed Claude plugin caches, declarative plugin manifests, and manifest-resolved non-shell hook implementations. Reports also include local harness adapter evidence for Claude Code, OpenCode, Codex, Gemini, Zed, VS Code, dmux, terminal-agent wrappers, and project-local templates when matching markers are present.\n\n## What It Catches\n\n**268 rules** across 15 modules, graded A to F with a 0 to 100 numeric score. Recognized defenses are listed and never penalized.\n\n#### Scoring and recognized defenses\n\nThe score starts at 100 per category and only findings deduct from it: critical 25, high 15, medium 5, low 2, info 0. Protective configuration the scanner finds (deny and ask lists, sandbox settings, blocking PreToolUse hooks, read-only agent tool lists, Codex `sandbox_mode`, Hermes manual approvals, and similar) is listed in every report under \"Recognized Defenses\" so it gets credit and is visibly never penalized. Defenses do not add points either: the score cannot be gamed by adding decorative deny rules, it can only be lowered by real findings. Guard-pattern findings the permission rules emit at info severity (\"Deny/ask rule blocking ...\", \"Prohibition of ...\", \"Mention of ...\") are enforced to a zero deduction in `src/reporter/score.ts`.\n\n### Secrets Detection\n\n| What | Examples |\n|------|----------|\n| API keys | Anthropic (`sk-ant-`), OpenAI (`sk-proj-`/`sk-`), xAI (`xai-`), AWS (`AKIA`), Google/Gemini (`AIza`), Stripe (`sk_test_`/`sk_live_`) |\n| Tokens | GitHub PATs (`ghp_`/`github_pat_`), Linear (`lin_api_`), Cloudflare (`CF_API_TOKEN=`), 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 (17 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 (40 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 (49 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\nSupply-chain verification (`agentshield scan --supply-chain`) extracts MCP\npackage references plus root `package.json` and `package-lock.json` dependency\nevidence, then reports provenance counts for npm vs git, pinned vs unpinned,\nknown-good packages, and npm-registry-backed metadata. Add\n`--supply-chain-online` to query npm for downloads, maintainers, postinstall\nscripts, deprecation, and package age.\n\nPackage-manager hardening checks also scan `.npmrc`, `.yarnrc.yml`, and\n`pnpm-workspace.yaml` for plaintext registry credentials, explicit dependency\nlifecycle-script enablement, and missing or weak release-age cooldowns where the\npackage manager supports them. npm configs are checked for lifecycle-script\nblocking and unsupported release-age keys that can create false confidence; use\npnpm `minimumReleaseAge` / `minimum-release-age`, Yarn `npmMinimalAgeGate`, or an\nexternal package-manager policy wrapper for cooldown enforcement.\n\nAgentShield also scans AI developer-tool persistence surfaces used by recent npm\nand PyPI campaign payloads, including Claude Code hook settings,\n`.claude/router_runtime.js`, VS Code `tasks.json` folder-open automation,\nZed project `tasks.json`, `.vscode/setup.mjs`, `.zed/setup.mjs`, GitHub\nworkflow drop-ins, LaunchAgent/systemd dead-man switch artifacts,\n`gh-token-monitor` token-store files, metadata-service credential targets, and\nreported exfiltration or second-stage network indicators. These indicators are\nemitted as critical hook findings so CI can fail fast even after the malicious\npackage has been uninstalled.\n\n#### MCP Confidence Notes\n\nAgentShield scans both active MCP config and repository-shipped MCP templates.\n\n- Findings from `.mcp.json`, `mcp.json`, `.claude/mcp.json`, `.claude.json`, and active `settings.json` are highest-confidence runtime exposure only under active Claude configuration roots; copies in docs, examples, or template directories are classified separately.\n- Findings from `settings.local.json` are emitted as `runtimeConfidence: project-local-optional`.\n- Findings from locations such as `mcp-configs/`, `config/mcp/`, or `configs/mcp/` indicate risky MCP definitions present in repository templates, not guaranteed active runtime enablement.\n- JSON, markdown, terminal, and HTML outputs now expose source context via `runtimeConfidence: active-runtime | project-local-optional | template-example | docs-example | plugin-cache | plugin-manifest | hook-code`.\n- Non-secret `template-example` MCP findings are score-weighted at `0.25x`, and one template file is capped at `10` deduction points per score category so a single MCP catalog cannot score like dozens of enabled servers.\n- In template files, findings such as risky server type, remote URL transport, `npx -y`, unpinned packages, and environment inheritance are still valuable, but they should be interpreted as \"this repo ships a risky MCP template\" rather than \"this MCP is definitely enabled right now.\"\n- Aggregate findings like large MCP server counts are especially likely to overstate runtime exposure when the source file is a template catalog.\n\n### Agent Config Review (41 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\nStructured JSON under `.claude/subagents/` and `.claude/slash-commands/` is analyzed like agent config when it declares `allowedTools` or similar tool metadata. Slash commands under `commands/` and `slash-commands/` are typed `command-md`: they get the injection and dangerous-instruction rules but not the skill packaging hygiene rules, which only apply to `SKILL.md`. Freeform `skill-md` prompt text still has narrower security coverage than `agent-md` and `CLAUDE.md`.\n\n#### Scanner Accuracy Notes\n\n- Live audit notes and follow-up items are tracked in [`false-positive-audit.md`](./false-positive-audit.md).\n- The most useful operator guidance is in the audit's [`Triage Rules For Current Reports`](./false-positive-audit.md#triage-rules-for-current-reports) section.\n- The audit doc also includes a reusable [`False-Positive Taxonomy`](./false-positive-audit.md#false-positive-taxonomy), [`Repo Audit Worksheet`](./false-positive-audit.md#repo-audit-worksheet), and [`Release Gate For Accuracy Changes`](./false-positive-audit.md#release-gate-for-accuracy-changes).\n- Cross-file hook-manifest awareness now suppresses settings-only `hooks-no-pretooluse` when a companion `hooks/hooks.json` manifest defines PreToolUse hooks.\n- Manifest-referenced hook implementations are now discovered from `hooks/hooks.json`-style indirection; shell targets continue through hook rules, and non-shell `hook-code` targets now emit targeted findings for explicit `output(...)` context injection, transcript input access, and remote shell payloads executed via child-process wrappers.\n- Current known high-signal caveats are broader non-shell hook execution that still needs language-aware analysis beyond those current `hook-code` signals, and `skill-md` prompt text that still bypasses most agent/injection rules.\n- `runtimeConfidence` now appears on MCP findings, `settings.local.json`, docs/examples, installed Claude plugin caches, plugin manifests, and manifest-resolved non-shell hook code. Scoring discounts non-secret `template-example` and `docs-example` findings at `0.25x`, non-secret `project-local-optional` findings at `0.75x`, and non-secret `plugin-cache` / `plugin-manifest` findings at `0.5x`. Non-secret `template-example` findings are also capped at `10` deduction points per file and score category so one catalog file cannot dominate the grade. `hook-code` findings currently stay at full weight, but the active rules there are narrow language-aware implementation signals.\n- Practical reading rule: `template-example` means \"repo ships this risky template\", not \"this is definitely enabled right now.\"\n- Practical reading rule: `docs-example` means \"repo ships risky sample guidance\", not \"this example is active runtime config.\"\n- Practical reading rule: `plugin-cache` means \"installed plugin content is present on disk\", not \"this file is top-level runtime config\"; real secrets still stay critical.\n- Practical reading rule: `plugin-manifest` means \"the repo declares this hook behavior\", while `hook-code` means \"the scanner reached the referenced non-shell implementation.\"\n- Current edge case: docs-only example trees now re-add the standalone `CLAUDE.md` example file for scanning, but still suppress the rest of the nested example subtree unless a runtime companion exists.\n- Current edge case: tutorial/example bundles outside the current `docs/`, `commands/`, `examples/`, `samples/`, `demo/`, `tutorial/`, `guide/`, `cookbook/`, and `playground/` heuristics can still be treated as live config until broader example-root classification lands.\n- Docs-only nested `CLAUDE.md` roots under `docs/` are now skipped unless runtime config companions exist in the same subtree.\n- Exact `Bash(curl https://...)` and `Bash(wget https://...)` allow entries with pinned literal URLs no longer trigger the generic `permissions-permissive-*` finding; wildcard and dynamic network permissions still do.\n- Exact `Bash(node scripts/foo.js ...)` and `Bash(python3 ./tools/audit.py ...)` wrapper commands no longer trigger the generic interpreter-access finding; inline eval forms such as `node -e` and `python -c` still do.\n- Exact read-only Docker inventory commands such as `Bash(docker ps)` and `Bash(docker image ls)` no longer trigger the generic Docker-access finding; execution-oriented forms such as `docker run` and `docker exec` still do.\n- Exact `settings.local.json` allowlists now downgrade `permissions-no-deny-list` from high to medium when every allow entry is fully specified; wildcard or dynamic project-local permissions still keep the higher severity.\n- Exact local-only `settings.local.json` allowlists now also downgrade `hooks-no-pretooluse` from medium to low; broader or network-capable project-local configs still keep the higher severity.\n- Comment-only shell-hook lines are now ignored by the hook exfiltration, sensitive-path, and silent-fail regex rules, so inline remediation notes and commented examples no longer look like live hook behavior.\n- Narrow specialist agents, subagents, and slash commands now downgrade generic Bash-access and escalation-chain findings from high to medium; broader generalist workflows still keep the higher severity.\n- Repo-scoped filesystem MCP servers using relative paths like `./` now grade lower than unrestricted root/home filesystem access; root-level filesystem exposure still stays high.\n- Defensive agent-review content that mentions patterns like ``fetch(userProvidedUrl)`` no longer triggers `agents-injection-surface`; direct instructions to fetch/process external content still do.\n- `agents-explorer-write` now uses role metadata and the lead agent intro instead of any later workflow/example text, so procedural `search for ...` steps in normal worker prompts no longer get mislabeled as explorer-style agents. Example: `chief-of-staff.md` no longer trips that rule just because it contains `gog gmail search ...`.\n- `agents-oversized-prompt` now measures effective prompt size instead of raw file length, discounting fenced code blocks and Markdown tables. Example-heavy agents like `chief-of-staff.md` and `planner.md` no longer trip the rule, while prose-heavy agents still do.\n- Markdown example/test passwords in example-like paths such as `docs/`, `commands/`, `examples/`, `tutorials/`, and `demos/` are now suppressed when the surrounding context is clearly instructional; that suppression does not apply to normal agent/config markdown.\n\n#### False-Positive Audit Workflow\n\nUse this workflow when a repo scan looks noisy or when you are tuning AgentShield rules.\n\n1. Start with JSON output so you can inspect file paths, `runtimeConfidence`, and score impact directly.\n2. Separate active runtime findings from lower-confidence source kinds before changing any rules.\n3. Validate suspected false positives against at least one real repo and one minimal synthetic fixture.\n4. Prefer source-aware reclassification and wording changes before adding blanket suppression.\n5. Keep real secrets and explicit execution paths visible even inside examples, manifests, or templates.\n6. Re-run targeted tests, then the full gate, before changing release behavior.\n\nRecommended commands:\n\n```bash\nagentshield scan --path /repo --format json > report.json\n\njq '.findings | group_by(.runtimeConfidence // \"none\") | map({\n  runtimeConfidence: (.[0].runtimeConfidence // \"none\"),\n  count: length\n})' report.json\n\njq '.findings | group_by(.file) | map({\n  file: .[0].file,\n  count: length\n}) | sort_by(-.count)[:20]' report.json\n```\n\nConfidence-first triage commands:\n\n```bash\n# Highest-signal findings first: active runtime + project-local\njq '.findings\n  | map(select((.runtimeConfidence // \"active-runtime\") | IN(\"active-runtime\",\"project-local-optional\")))\n  | map(select(.severity | IN(\"critical\",\"high\",\"medium\")))\n  | map({file, severity, runtimeConfidence, title})' report.json\n\n# Lower-confidence inventory that usually needs interpretation, not suppression\njq '.findings\n  | map(select((.runtimeConfidence // \"\") | IN(\"template-example\",\"docs-example\",\"plugin-cache\",\"plugin-manifest\")))\n  | map({file, severity, runtimeConfidence, title})' report.json\n```\n\nRecommended audit order:\n- `active-runtime` and `project-local-optional`: treat as highest-signal findings first.\n- `template-example`, `docs-example`, and `plugin-cache`: confirm whether the repo or installed plugin cache is shipping risky guidance versus actually enabling it.\n- `plugin-manifest`: confirm whether the risk is in declarative hook wiring or the referenced implementation.\n- `hook-code`: confirm whether the implementation actually injects context, reads transcripts, or shells out in a risky way.\n\nRule-design guidelines:\n- Prefer source-aware labeling over suppression. If a finding is real but lower confidence, keep it visible and say why.\n- Prefer cross-file context over single-file guesses. Companion manifests and referenced hook implementations usually matter more than isolated config.\n- Prefer narrow, behavior-based `hook-code` rules over generic wrapper heuristics. `spawnSync(\"bash\", [\"-lc\", \"curl ... | bash\"])` is high-signal; ordinary `spawnSync(\"prettier\", ...)` is not.\n- Do not downgrade real secrets just because they appear in docs or examples. Structural findings can be downgraded; committed credentials should stay critical.\n- Keep example-root heuristics evidence-based. Today the scanner treats `docs/`, `commands/`, `examples/`, `example/`, `samples/`, `sample/`, `demo/`, `demos/`, `tutorial/`, `tutorials/`, `guide/`, `guides/`, `cookbook/`, and `playground/` as example-like paths.\n\nWhen you change rule accuracy, update both:\n- [`false-positive-audit.md`](./false-positive-audit.md) with the new baseline and remaining gaps\n- the targeted regression tests for the specific rule family you changed\n- `agentshield scan --corpus-gate` in CI so the built-in attack corpus must stay fully detected; failed corpus gates now include a prioritized accuracy improvement plan by category, missing rule, and missed config\n- the corpus now includes an env proxy/DNS exfiltration fixture so proxy hijack, runtime import mutation, env-token exfiltration, credential-store access, and clipboard access stay covered together\n- if you are filing a scanner-noise bug, start from the audit doc's [`False-Positive Issue Template`](./false-positive-audit.md#false-positive-issue-template)\n\n#### Reducing False Positives In Practice\n\nThe current scan profile is not dominated by broken matchers. It is mostly dominated by lower-confidence source kinds that need different interpretation.\n\nCurrent patterns from the latest live scans:\n- template MCP inventory is still the biggest noise source by count in `everything-claude-code`\n- example/tutorial config needs example-aware wording and weighting, not blanket suppression\n- declarative hook manifests and executable hook implementations need different handling\n- many remaining agent findings are policy findings about intentionally privileged agents, not obvious rule bugs\n- the latest alert review reduced specialist agent-capability severity inflation, repo-scoped filesystem MCP inflation, and template-catalog score inflation; remaining noise is now mostly template count/interpretation and active-runtime remote MCP URLs\n\nRecurring pattern signatures to recognize:\n- one template file dominating the report usually means confidence/weighting work, not a broken matcher\n- broad `agents-*` clusters across files with explicit tool metadata usually mean policy review, not false-positive suppression\n- very small `project-local-optional` clusters usually mean scope is already modeled and only severity may need tuning\n- a repo-scoped filesystem MCP with relative-path args should not be treated like root/home filesystem access\n\nWhen to open a false-positive issue instead of just triaging the report:\n- the same finding pattern reproduces across at least one real repo and one minimal synthetic fixture\n- the finding is wrong for its own source kind, not just lower-confidence than `active-runtime`\n- the fix needs matcher changes, not just better wording, score weighting, or cross-file context\n- the finding would still be misleading even after reading `runtimeConfidence`\n\nRecommended operating model:\n- Start with `runtimeConfidence` before changing any rule. Separate `active-runtime` from `template-example`, `docs-example`, `plugin-cache`, `plugin-manifest`, and `project-local-optional`.\n- Reclassify before suppressing. If the finding is real but lower confidence, keep it visible and adjust wording or score weight instead of hiding it.\n- Keep secrets on a stricter standard. Real credentials should stay critical even in docs, examples, plugin caches, or manifests.\n- Use cross-file context whenever possible. Settings, manifests, and referenced hook implementations usually need to be read together.\n- For `hook-code`, add only narrow language-aware rules for explicit risky behavior. Avoid broad wrapper heuristics.\n- For agent rules, anchor on role metadata and lead instructions before matching arbitrary later prose.\n\nRepo conventions that help AgentShield scan accurately:\n- put reusable MCP catalogs under template paths such as `mcp-configs/` instead of live runtime config files\n- keep local-only overrides in `settings.local.json`\n- keep tutorials and examples under example-like paths such as `docs/`, `examples/`, `tutorials/`, `demos/`, or `guides/`\n- keep `hooks/hooks.json` declarative and put the implementation in separate hook script files\n- keep large agent examples inside fenced code blocks so prompt-size and role heuristics stay accurate\n\nCurrent high-value places to audit first:\n- files with the highest finding count\n- files with `runtimeConfidence: template-example` or `plugin-cache`\n- `settings.local.json` findings that may be project-local rather than repo-wide\n- `plugin-manifest` findings that need confirmation in the referenced implementation\n- `hook-code` findings that involve context injection, transcript access, or child-process execution\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**Verify-after-fix:** `--fix` does not trust itself. After applying fixes it re-scans the target, and if the posture score regressed or a new high/critical finding appeared (the kind of churn a naive permission tighten can cause), it rolls every modified file back to its original content. On success it prints a tamper-evident attestation digest binding the before/after score and finding deltas, so the kept fixes are provably non-regressing.\n\n### External Rule Packs (`--rule-pack`)\n\nRun community or private detection rules alongside the built-ins, without recompiling:\n\n```bash\nagentshield scan --rule-pack ./my-pack.json\nagentshield scan --rule-pack ./pack-a.json --rule-pack ./pack-b.json   # repeatable\n```\n\nA pack is a JSON file validated with the same fail-closed approach as `--policy` (bad JSON, schema violations, duplicate ids, or an uncompilable regex abort the scan):\n\n```json\n{\n  \"version\": 1,\n  \"name\": \"my-pack\",\n  \"rules\": [\n    {\n      \"id\": \"tool-poisoning-001\",\n      \"name\": \"Tool description poisoning\",\n      \"description\": \"Hidden instruction in a tool description\",\n      \"severity\": \"high\",\n      \"category\": \"injection\",\n      \"patterns\": [\"ignore (?:all )?previous instructions\"],\n      \"fileTypes\": [\"agent-md\", \"claude-md\"]\n    }\n  ]\n}\n```\n\nEach pattern is a JS regex run against file content; `fileTypes` is optional and scopes a rule to specific config types. External findings count toward the overall grade. Anyone with a pack in this shape can plug in.\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### Claude Opus Deep Analysis (`--opus`)\n\nThree-agent adversarial pipeline powered by Claude Opus (claude-opus-5 by default; the injection tester uses claude-sonnet-5):\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#### OrcaRouter provider\n\nThe `--opus` and `--injection` analysis modes can also run through\n[OrcaRouter](https://www.orcarouter.ai), an OpenAI/Anthropic-compatible gateway\nthat routes each request to the most cost-effective upstream model:\n\n```bash\nexport ORCAROUTER_API_KEY=your-key-here\nagentshield scan --opus --provider orcarouter\nagentshield scan --injection --provider orcarouter\n```\n\nThe provider points the Anthropic client at `https://api.orcarouter.ai` and\nuses the gateway's namespaced model ids (e.g. `anthropic/claude-sonnet-5`,\n`anthropic/claude-opus-5`). The default provider remains Anthropic.\n\nWith `--provider orcarouter` the scanned configuration contents are sent to\nOrcaRouter's API instead of Anthropic's, so do not use it on configs containing\nsecrets you have not redacted.\n\n### Compliance Mapping (`--compliance`)\n\nMap findings to audit-framework control IDs so GRC teams get an auditor-ready coverage artifact instead of a raw findings list:\n\n```bash\nagentshield scan --compliance soc2          # SOC 2 Trust Services Criteria\nagentshield scan --compliance pci,iso       # comma-separated\nagentshield scan --compliance all           # SOC 2 + PCI DSS + ISO 27001\n```\n\nEach framework prints a control-coverage table (control id, title, highest severity, finding count, examples), ordered by severity:\n\n```\n## Compliance Mapping: SOC 2 (Trust Services Criteria)\n\nMapped 194/194 findings to 5 control(s). 0 finding(s) had no mapped control.\n\n| Control | Title                        | Highest  | Findings | Examples |\n| CC6.1   | Logical access - credentials | critical | 76       | Hardcoded Anthropic API key; ... |\n```\n\nMapping is finding-category-level guidance (SOC 2, PCI DSS v4.0, ISO/IEC 27001:2022 Annex A), not a certified crosswalk; confirm control applicability with your auditor.\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` | Executive report with risk posture and priorities |\n| Evidence pack | `--evidence-pack <dir>` | Audit and buyer reviews |\n| Remediation plan | `--remediation-plan <path>` | Stable-fingerprint fix queue for CI and ticketing |\n\nEvidence packs write a deterministic directory containing `manifest.json`,\n`README.md`, `agentshield-report.json`, `agentshield-report.html`,\n`agentshield-results.sarif`, `policy-evaluation.json`,\n`baseline-comparison.json`, `supply-chain.json`, and\n`ci-context.json`, and `remediation-plan.json`. The manifest records SHA-256\ndigests and byte counts for bundle artifacts plus a bundle digest over the\nmachine-readable evidence. `ci-context.json` records whitelisted GitHub Actions\nworkflow, commit, run, and runner provenance without copying arbitrary\nenvironment variables into the bundle.\nRedaction is enabled by default for local paths, usernames, emails, and\ntoken-shaped strings; use `--no-evidence-redact` only for private internal\nbundles.\n\nRemediation plans write a JSON queue of findings with stable hashed\nfingerprints, severity, file, fixability, ordered workflow phases, and the\nrecommended next command. The workflow phases route safe auto-fixes first,\nmanual-review findings second, and verification last so maintainers can attach\nthe plan to CI tickets without turning every finding into a separate thread.\nThey intentionally omit raw evidence and fix before/after values so teams can\nattach the plan to tickets without copying token-shaped strings.\n\nVerify a saved evidence pack before attaching it to CI artifacts or customer\nhandoffs:\n\n```bash\nagentshield evidence-pack verify ./agentshield-evidence\nagentshield evidence-pack verify ./agentshield-evidence --json\n```\n\nInspect a verified evidence pack when a downstream GitHub App, Linear sync, or\nsecurity-review workflow needs a compact readback without opening every artifact:\n\n```bash\nagentshield evidence-pack inspect ./agentshield-evidence\nagentshield evidence-pack inspect ./agentshield-evidence --json\n```\n\nAggregate multiple verified evidence packs when an operator needs fleet-level\nrouting across repos, teams, or harnesses. The JSON output includes\n`operatorReadback` for promotion status/digest checks and `reviewItems` with\nsource evidence paths and owner-ready recommendations for packs that need\nfollow-up:\n\n```bash\nagentshield evidence-pack fleet ./repo-a-evidence ./repo-b-evidence\nagentshield evidence-pack fleet ./repo-a-evidence ./repo-b-evidence --json\n```\n\n`operatorReadback` is the stable field for downstream GitHub App, Linear, or\nECC Tools routing. It reports `ready`, `status`, `digest`, owner counts,\nblocking review counts, approval routes, deterministic `approvalIds`, and the\nnext operator action so fleet promotion can be gated without parsing terminal\nprose. Each review item also carries the same `approvalId` plus a\nLinear-friendly ticket `externalId`, allowing sync jobs to dedupe owner approval\nthreads across reruns.\n\n### JSON Report Shape\n\n`agentshield scan --format json` is the supported machine-readable scanner interface today.\n\n```json\n{\n  \"timestamp\": \"2026-03-13T19:42:00.000Z\",\n  \"targetPath\": \"/repo/.claude\",\n  \"score\": {\n    \"grade\": \"C\",\n    \"numericScore\": 66,\n    \"breakdown\": {\n      \"secrets\": 100,\n      \"permissions\": 70,\n      \"hooks\": 80,\n      \"mcp\": 35,\n      \"agents\": 45\n    }\n  },\n  \"summary\": {\n    \"totalFindings\": 29,\n    \"critical\": 1,\n    \"high\": 7,\n    \"medium\": 8,\n    \"low\": 10,\n    \"info\": 3,\n    \"filesScanned\": 17,\n    \"autoFixable\": 2,\n    \"defenses\": 4\n  },\n  \"defenses\": [\n    {\n      \"id\": \"defense-deny-list\",\n      \"title\": \"Permission deny list\",\n      \"file\": \".claude/settings.json\",\n      \"detail\": \"6 deny rules; covers .env, ~/.ssh, curl, sudo, rm -rf. Deny wins over allow regardless of specificity.\",\n      \"harness\": \"claude-code\"\n    }\n  ],\n  \"findings\": [\n    {\n      \"id\": \"mcp-risky-filesystem\",\n      \"severity\": \"medium\",\n      \"category\": \"mcp\",\n      \"title\": \"Template defines risky MCP server: filesystem\",\n      \"description\": \"Repository template includes a high-risk filesystem MCP server.\",\n      \"file\": \"mcp-configs/mcp-servers.json\",\n      \"runtimeConfidence\": \"template-example\"\n    }\n  ]\n}\n```\n\nNotes:\n- `runtimeConfidence` is emitted for active runtime config, `settings.local.json`, docs/examples, installed Claude plugin caches, plugin manifests, and manifest-resolved non-shell hook code.\n- `harnessAdapters` is local marker evidence only. It does not call external services or imply a hosted/team entitlement.\n- Adapter `confidence` is `strong` when a primary harness marker exists, and `partial` when only supporting directories or secondary markers are present.\n- `active-runtime` means active config such as `.mcp.json`, `mcp.json`, `.claude/mcp.json`, `.claude.json`, or active `settings.json`.\n- `project-local-optional` means project-local settings such as `settings.local.json`.\n- `template-example` means template/catalog files such as `mcp-configs/` or `config/mcp/`.\n- `docs-example` means docs/tutorial/example content such as `docs/guide/settings.json` or `commands/*.md`.\n- `plugin-cache` means installed Claude plugin cache content such as `.claude/plugins/cache/...`.\n- `plugin-manifest` means declarative hook manifests such as `hooks/hooks.json`.\n- `hook-code` means a manifest-resolved non-shell implementation such as `scripts/hooks/session-start.js`.\n- Recognized defenses (`defenses[]` in JSON, \"Recognized Defenses\" in terminal and markdown) are credited, never penalized, and never add points.\n- Score weighting discounts non-secret `template-example` and `docs-example` findings to `0.25x`, non-secret `project-local-optional` findings to `0.75x`, and non-secret `plugin-cache` / `plugin-manifest` findings to `0.5x`; committed secrets still count at full weight. Non-secret `template-example` findings are also capped at `10` deduction points per file and score category. See [`false-positive-audit.md`](./false-positive-audit.md).\n\n## API Reference\n\nAgentShield currently has three distinct automation surfaces:\n\n- CLI: `agentshield scan`, `agentshield init`, and `agentshield miniclaw start`\n- Scanner report JSON/SARIF: `agentshield scan --format json` or `agentshield scan --format sarif --output agentshield.sarif`\n- Organization policy gate: `agentshield scan --policy agentshield-policy.json`\n- MiniClaw package + HTTP API: `ecc-agentshield/miniclaw`\n\nImportant packaging note:\n- The npm package root export currently points at the CLI entrypoint, not a semver-stable scanner library module.\n- Internal scanner modules such as `src/scanner/index.ts` and `src/reporter/score.ts` are useful for contributors, but they should not be documented as supported `import` paths for package consumers yet.\n- If you need automation around scanner results today, prefer the JSON report format over importing scanner internals from the package root.\n\nDetailed request/response and schema notes live in [`API.md`](./API.md).\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: terminal, json, markdown, sarif |\n| `sarif-output` | `agentshield-results.sarif` | SARIF output path when `format` is `sarif` |\n| `baseline` | `\"\"` | Optional AgentShield baseline JSON path for drift comparison |\n| `save-baseline` | `\"\"` | Optional path to write the current scan as a new baseline |\n| `policy` | `\"\"` | Optional organization policy JSON path |\n| `fail-on-policy` | `true` | Fail the action if the organization policy is non-compliant |\n| `supply-chain` | `true` | Verify MCP npm/git package provenance and known malicious package risk |\n| `supply-chain-online` | `false` | Query npm registry metadata during supply-chain verification |\n| `fail-on-supply-chain` | follows `fail-on-findings` | Fail the action when supply-chain verification finds critical or high package risks |\n| `evidence-pack` | `\"\"` | Optional directory for a portable audit evidence bundle |\n| `verify-evidence-pack` | `true` | Verify evidence-pack artifact hashes after writing |\n| `policy-promotion-manifest` | `\"\"` | Optional policy export manifest to verify and promote or dry-run |\n| `policy-promotion-pack` | `\"\"` | Policy pack id when the manifest contains multiple packs |\n| `policy-promotion-output` | `.agentshield/policy.json` | Active policy path to write when promotion dry-run is disabled |\n| `policy-promotion-dry-run` | `true` | Verify promotion review evidence without writing the active policy |\n| `fail-on-policy-promotion` | `false` | Fail when promotion review items still require action |\n\n**Outputs:** `score` (0–100), `grade` (A–F), `total-findings`, `critical-count`, `sarif-path`, `baseline-path`, `baseline-status`, `new-findings`, `resolved-findings`, `unchanged-findings`, `score-delta`, `policy-status`, `policy-violations`, `policy-promotion-status`, `policy-promotion-pack`, `policy-promotion-review-items`, `policy-promotion-action-required-count`, `policy-promotion-digest`, `supply-chain-status`, `supply-chain-risky-packages`, `supply-chain-critical-count`, `supply-chain-high-count`, `package-manager-hardening-status`, `package-manager-hardening-findings`, `package-manager-hardening-critical-count`, `package-manager-hardening-high-count`, `package-manager-hardening-registry-credentials`, `package-manager-hardening-lifecycle-scripts`, `package-manager-hardening-release-age-gates`, `evidence-pack-path`, `evidence-pack-status`, `evidence-pack-digest`\n\nThe action writes a markdown job summary and emits GitHub annotations inline on affected files. When `format: sarif` is set, it also writes a SARIF 2.1.0 report that can be uploaded to GitHub code scanning with `github/codeql-action/upload-sarif`. When `baseline` is set, the action appends a baseline drift summary, emits regression annotations for new findings, and reports `baseline-status` as `passed`, `failed`, `missing`, or `not-run`. When `policy` is set, the SARIF report includes organization-policy violations as `agentshield-policy/*` code-scanning results, appends the organization policy result to the job summary, emits policy violation annotations, and fails by default unless `fail-on-policy: \"false\"` is set. When `policy-promotion-manifest` is set, the action verifies the selected policy export digest, emits promotion review-item counts, appends the owner/protected-rollout/runtime-smoke review items to the job summary, and marks runtime smoke as verified when the same job also scans with the promoted policy. Supply-chain verification runs offline by default for MCP package references, appends package-risk evidence to the job summary, writes real `supply-chain.json` evidence packs, and fails on critical/high package risk whenever the action is in failing mode unless `fail-on-supply-chain: \"false\"` is set. Package-manager hardening outputs and job-summary evidence separately count plaintext registry credentials, lifecycle-script drift, and release-age gate drift so CI and hosted consumers can route supply-chain configuration risk even when the main finding gate is collecting evidence only.\n\nBaseline drift gate:\n\n```yaml\n- name: AgentShield Drift Gate\n  uses: affaan-m/agentshield@v1\n  with:\n    path: \".\"\n    baseline: \".github/agentshield-baseline.json\"\n    fail-on-findings: \"false\"\n```\n\nUse `fail-on-findings: \"false\"` when the workflow should fail only on drift from the baseline. Keep the default `fail-on-findings: \"true\"` when any current finding at or above `min-severity` should still fail the action.\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, sarif\n  -o, --output <path>              Write the primary report output to a file\n  --fix                            Auto-apply safe fixes\n  --opus                           Enable Claude Opus multi-agent analysis\n  --provider <provider>            LLM provider for --opus/--injection: anthropic or orcarouter\n  --stream                         Stream Opus analysis in real-time\n  --injection                      Run active prompt injection testing\n  --sandbox                        Execute hooks in a sandbox and observe behavior\n  --taint                          Run taint analysis (data flow tracking)\n  --deep                           Run injection + sandbox + taint + opus together\n  --log <path>                     Write structured scan logs to a file\n  --log-format <format>            Log format: ndjson or json\n  --corpus                         Run built-in attack corpus benchmark\n  --corpus-gate                    Fail if the built-in attack corpus regresses\n  --baseline <path>                Compare against a baseline file\n  --save-baseline <path>           Save current scan results as a baseline file\n  --gate                           Fail on new critical/high findings or score drop\n  --supply-chain                   Verify MCP package provenance and risk\n  --supply-chain-online            Include npm registry metadata\n  --compliance <frameworks>        Map findings to controls: soc2, pci, iso, all\n\n  --rule-pack <path>               Load an external JSON rule pack (repeatable)\n  --policy <path>                  Validate against an organization policy\n  --evidence-pack <dir>            Write portable evidence bundle\n  --remediation-plan <path>        Write stable-fingerprint JSON remediation plan\n  --no-evidence-redact             Disable evidence-pack redaction\n  --min-severity <severity>        Filter: critical, high, medium, low, info\n  -v, --verbose                    Show detailed output\n\nagentshield init                   Generate secure baseline config\nagentshield baseline write         Write a scan baseline JSON file\nagentshield evidence-pack fleet    Summarize multiple evidence packs for routing\nagentshield evidence-pack inspect  Verify and summarize an evidence bundle\nagentshield evidence-pack verify   Verify artifact and bundle digests\nagentshield policy export          Export policy packs plus checksum manifest\nagentshield policy init            Generate an organization policy preset\nagentshield policy promote         Verify and promote an exported policy\n```\n\nReport footer CTA: terminal and markdown reports can append a one-line ECC\nTools Pro footer. It is off by default. Set `AGENTSHIELD_CTA=1` (or\n`ECC_CTA=1`) to enable it; set `AGENTSHIELD_NO_CTA=1` (or `ECC_NO_CTA=1`) to\nhard-suppress it, which wins over opt-in. JSON and SARIF output never include\nit.\n\nBaseline write:\n\n```bash\nagentshield baseline write --path .claude --output .github/agentshield-baseline.json\nagentshield baseline write --path .claude --output baseline.json --json\n```\n\nThe baseline command is a first-class wrapper around the existing scan baseline\nformat. New baselines store stable hashed evidence fingerprints and omit raw\nevidence values, so teams can keep baseline snapshots in CI without copying\ntoken-shaped strings into long-lived artifacts. Existing raw-evidence baselines\nremain comparable during migration. Use it to create the accepted snapshot,\nthen compare future scans with\n`agentshield scan --baseline .github/agentshield-baseline.json --gate`.\n\nRuntime monitor lifecycle:\n\n```bash\n# Install the PreToolUse runtime monitor\nagentshield runtime install\n\n# Check whether the hook, policy, and log path are healthy\nagentshield runtime status --check\n\n# Back up invalid runtime files and restore a healthy install\nagentshield runtime repair\n```\n\nOrganization policy files support enterprise metadata and temporary exceptions:\n\n```bash\nagentshield policy init --pack enterprise --owner security-platform@acme.example\nagentshield policy init --pack regulated --name \"Acme Regulated Policy\"\nagentshield policy export --output-dir .github/agentshield-policies --owner security-platform@acme.example\nagentshield policy export --pack ci-enforcement --name-prefix \"Acme\" --json\nagentshield policy promote --manifest .github/agentshield-policies/manifest.json --pack ci-enforcement --output .agentshield/policy.json\nagentshield policy promote --manifest .github/agentshield-policies/manifest.json --pack ci-enforcement --dry-run --json\n```\n\nPolicy pack presets are starter baselines, not hidden SaaS policy. `oss` keeps\npublic repos permissive while requiring destructive-command deny entries;\n`team` adds the runtime hook; `enterprise` raises score gates and blocks broad\ntool allowlists; `regulated` disallows critical/high findings and bans broader\nMCP/tool surfaces; `high-risk-hooks-mcp` focuses on hook/MCP-heavy repos; and\n`ci-enforcement` is tuned for branch-protection evidence.\n\nPolicy export writes one JSON policy file per selected pack plus a\n`manifest.json` containing SHA-256 digests. This gives platform teams a stable\nartifact bundle for branch-protection review, audit attachment, or downstream\npolicy promotion without relying on generated console output.\n\nPolicy promotion is the review gate for those exported bundles. It reads the\nexport manifest, verifies the selected policy file digest, validates the policy\nschema, and only then writes the active policy path. Use `--dry-run --json` in\nreview workflows to prove the exact pack, source file, output path, owner list,\nand digest before a protected branch or operator copies the policy into place.\nPromotion results also include `reviewItems` for owner approval, protected PR\nrollout, and the runtime smoke test needed before enabling an enforcing CI gate.\n\n```json\n{\n  \"version\": 1,\n  \"name\": \"Acme Corp Security Policy\",\n  \"policy_pack\": \"enterprise\",\n  \"owners\": [\"security-platform@acme.example\"],\n  \"min_score\": 85,\n  \"max_severity\": \"high\",\n  \"required_deny_list\": [\"Bash(rm -rf\"],\n  \"exceptions\": [\n    {\n      \"id\": \"AS-EX-001\",\n      \"rule\": \"required_hooks\",\n      \"owner\": \"security-platform@acme.example\",\n      \"reason\": \"Legacy repository migration window\",\n      \"expires_at\": \"2026-06-30T23:59:59.000Z\",\n      \"scope\": \"agentshield\",\n      \"ticket\": \"SEC-1234\"\n    }\n  ]\n}\n```\n\nPolicy evaluation now includes an exception lifecycle audit in terminal output\nand GitHub Action summaries: total exceptions, active exceptions, exceptions\nexpiring within seven days, expired exceptions, owners, tickets, scopes, and\ndays until expiry. This keeps temporary waivers visible in branch-protection\nevidence instead of letting them become silent permanent bypasses.\n\nExit codes:\n- `0`: scan completed without critical findings\n- `1`: CLI usage or runtime error\n- `2`: scan completed and found at least one critical issue\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 (17 rules)\n│   ├── mcp.ts            MCP server security (26 rules)\n│   ├── hooks.ts          Hook analysis (40 rules)\n│   └── agents.ts         Agent config review (41 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 Claude Opus pipeline\n    └── render.ts         Opus analysis rendering\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\nMiniClaw-specific package exports and HTTP endpoints are documented in [`src/miniclaw/README.md`](./src/miniclaw/README.md) and summarized in [`API.md`](./API.md). The React dashboard source lives in [`src/miniclaw/dashboard.tsx`](./src/miniclaw/dashboard.tsx), but it is not yet published as a separate npm subpath.\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### HTTP 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## Development\n\n```bash\nnpm install          # Install dependencies\nnpm run dev          # Development mode\nnpm test             # Run 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| **ECC Tools Pro** | GitHub App with automated repo analysis, Stripe billing ($19/seat/mo) | [Install](https://github.com/apps/ecc-tools) |\n## FAQ\n\n### What is AgentShield?\n\nAgentShield is a **security auditor for AI agent configurations**. It scans Claude Code setups for hardcoded secrets, permission misconfigs, hook injection, MCP server risks, and agent prompt injection vectors.\n\n| Feature | Description |\n|---------|-------------|\n| **Security Auditor** | Scans `.claude/` directory for vulnerabilities |\n| **Multiple Surfaces** | CLI, GitHub Action, GitHub App integration |\n| **Auto-Fix** | Replaces hardcoded secrets with env var references |\n| **Graded Reports** | Security score (0-100) with findings breakdown |\n| **Opus Pipeline** | Three-agent adversarial analysis with Anthropic API |\n| **Evidence Pack** | Portable audit bundle for compliance |\n\n### What can AgentShield detect?\n\n| Category | Examples |\n|----------|----------|\n| **Secrets** | Hardcoded API keys, tokens, private keys, connection strings |\n| **Permissions** | Overly permissive allow rules like `Bash(*)` |\n| **Hooks** | Hook injection vectors, unsafe hooks |\n| **MCP Servers** | MCP server risks, malicious MCP configs |\n| **Agents** | Agent prompt injection vectors |\n\n### How to get started?\n\n**Quick Start (no install):**\n```bash\nnpx ecc-agentshield scan\n```\n\n**Install globally:**\n```bash\nnpm install -g ecc-agentshield\nagentshield scan\n```\n\n**Auto-fix safe issues:**\n```bash\nagentshield scan --fix\n```\n\n### What output formats are available?\n\n| Format | Use Case |\n|--------|----------|\n| **Default** | Terminal graded security report |\n| **JSON** | CI pipelines and automation |\n| **HTML** | Executive security report |\n| **Evidence Pack** | Portable audit bundle for compliance |\n\n### What is the Opus Pipeline?\n\nThe Opus Pipeline is a **three-agent adversarial analysis** that runs on Claude Opus through the Anthropic API:\n1. **Attacker**: hunts for exploitable weaknesses in the scanned config\n2. **Defender**: proposes concrete hardening for each weakness\n3. **Auditor**: reconciles both views into a ranked risk assessment\n\n**Usage:**\n```bash\nagentshield scan --opus --stream\n```\n\n### What is MiniClaw?\n\nMiniClaw is a **sandboxed agent runtime** included with AgentShield:\n- **Prompt Router**: Strips 12+ injection pattern categories\n- **Tool Whitelist**: Safe/Guarded/Restricted tiers\n- **Sandbox**: Isolated filesystem, path traversal blocked\n- **HTTP API**: REST endpoints for session management\n\n### Is AgentShield free and open source?\n\nYes! AgentShield is **MIT licensed** and free to use. Built at the Claude Code Hackathon (Cerebral Valley x Anthropic, Feb 2026).\n\n### How to contribute?\n\nContributions welcome! Check the [repository](https://github.com/affaan-m/agentshield) for issues and pull requests. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n### Where to get help?\n\n| Resource | Link |\n|----------|------|\n| **Repository** | [github.com/affaan-m/agentshield](https://github.com/affaan-m/agentshield) |\n| **npm Package** | [npmjs.com/package/ecc-agentshield](https://www.npmjs.com/package/ecc-agentshield) |\n| **Changelog** | [CHANGELOG.md](./CHANGELOG.md) |\n| **Everything Claude Code** | [github.com/affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) |\n| **Twitter** | [@affaanmustafa](https://x.com/affaanmustafa) |\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"}