{"id":44509676,"url":"https://github.com/affaan-m/agentshield","last_synced_at":"2026-04-01T20:40:25.950Z","repository":{"id":337790336,"uuid":"1155123554","full_name":"affaan-m/agentshield","owner":"affaan-m","description":"AI agent security scanner. Detect vulnerabilities in agent configurations, MCP servers, and tool permissions. Available as CLI, GitHub Action, ECC plugin, and GitHub App integration. 🛡️","archived":false,"fork":false,"pushed_at":"2026-03-31T21:59:00.000Z","size":1244,"stargazers_count":279,"open_issues_count":0,"forks_count":54,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-03-31T23:49:32.553Z","etag":null,"topics":["ai-agent","anthropic","claude-code","hackathon","mcp","opus","security"],"latest_commit_sha":null,"homepage":"https://cerebralvalley.ai/e/claude-code-hackathon","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/affaan-m.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"affaan-m"}},"created_at":"2026-02-11T06:31:44.000Z","updated_at":"2026-03-31T23:16:21.000Z","dependencies_parsed_at":"2026-02-17T17:00:57.863Z","dependency_job_id":null,"html_url":"https://github.com/affaan-m/agentshield","commit_stats":null,"previous_names":["affaan-m/agentshield"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/affaan-m/agentshield","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/affaan-m%2Fagentshield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/affaan-m%2Fagentshield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/affaan-m%2Fagentshield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/affaan-m%2Fagentshield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/affaan-m","download_url":"https://codeload.github.com/affaan-m/agentshield/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/affaan-m%2Fagentshield/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291752,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","claude-code","hackathon","mcp","opus","security"],"created_at":"2026-02-13T13:16:06.579Z","updated_at":"2026-04-01T20:40:25.923Z","avatar_url":"https://github.com/affaan-m.png","language":"TypeScript","funding_links":["https://github.com/sponsors/affaan-m"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./assets/agentshield-logo.png\" alt=\"AgentShield\" width=\"180\" /\u003e\n\n# AgentShield\n\n**Security auditor for AI agent configurations**\n\nScans Claude Code setups for hardcoded secrets, permission misconfigs,\u003cbr/\u003e\nhook injection, MCP server risks, and agent prompt injection vectors.\u003cbr/\u003e\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\u003c/div\u003e\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 security report\nagentshield scan --format html \u003e 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\nJSON reports now expose `findings[].runtimeConfidence` when AgentShield can distinguish active runtime config from project-local settings, template/example inventories, declarative plugin manifests, and manifest-resolved non-shell hook implementations.\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\u003e/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 | `\u0026\u0026`, `\\|`, `;` 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#### MCP Confidence Notes\n\nAgentShield scans both active MCP config and repository-shipped MCP templates.\n\n- Findings from `mcp.json`, `.claude/mcp.json`, `.claude.json`, and active `settings.json` should be treated as the highest-confidence runtime exposure.\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-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 (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\nStructured JSON under `.claude/subagents/` and `.claude/slash-commands/` is analyzed like agent config when it declares `allowedTools` or similar tool metadata. 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, 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-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-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 \u003e 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-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` and `docs-example`: confirm whether the repo 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- 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-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, 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`\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### 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### 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  },\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, plugin manifests, and manifest-resolved non-shell hook code.\n- `active-runtime` means active config such as `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-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- 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-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: `agentshield scan --format 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 |\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 \u003cpath\u003e                Path to scan (default: ~/.claude or cwd)\n  -f, --format \u003cformat\u003e            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  --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 \u003cpath\u003e                     Write structured scan logs to a file\n  --log-format \u003cformat\u003e            Log format: ndjson or json\n  --corpus                         Run built-in attack corpus validation\n  --min-severity \u003cseverity\u003e        Filter: critical, high, medium, low, info\n  -v, --verbose                    Show detailed output\n\nagentshield init                   Generate secure baseline config\n```\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 (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```\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## License\n\nMIT\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nBuilt by [@affaanmustafa](https://x.com/affaanmustafa) · Part of [Everything Claude Code](https://github.com/affaan-m/everything-claude-code)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faffaan-m%2Fagentshield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faffaan-m%2Fagentshield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faffaan-m%2Fagentshield/lists"}