Agentshield

AgentShield

Security auditor for AI agent configurations

Scans Claude Code setups for hardcoded secrets, permission misconfigs, hook injection, MCP server risks, and agent prompt injection vectors. Available as CLI, GitHub Action, and GitHub App integration.

[](https://www.npmjs.com/package/ecc-agentshield) [](https://www.npmjs.com/package/ecc-agentshield) []() []() [](LICENSE)

[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)

---

Why

The AI agent ecosystem is growing faster than its security tooling. In January 2026 alone:

• 12% of a major agent skill marketplace was malicious (341 of 2,857 community skills)
• A CVSS 8.8 CVE exposed 17,500+ internet-facing instances to one-click RCE
• The Moltbook breach compromised 1.5M API tokens across 770,000 agents

Developers 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.

Built at the Claude Code Hackathon (Cerebral Valley x Anthropic, Feb 2026). Part of the Everything Claude Code ecosystem (42K+ stars).

Quick Start

# Scan your Claude Code config (no install required)
npx ecc-agentshield scan

# Or install globally
npm install -g ecc-agentshield
agentshield scan

That's it. AgentShield auto-discovers your ~/.claude/ directory, scans all config files, and prints a graded security report.

Discovery intentionally skips common generated directories such as node_modules, build output, and .dmux worktree mirrors so transient copies do not duplicate findings.

  AgentShield Security Report

  Grade: F (0/100)

  Score Breakdown
  Secrets        ░░░░░░░░░░░░░░░░░░░░ 0
  Permissions    ░░░░░░░░░░░░░░░░░░░░ 0
  Hooks          ░░░░░░░░░░░░░░░░░░░░ 0
  MCP Servers    ░░░░░░░░░░░░░░░░░░░░ 0
  Agents         ░░░░░░░░░░░░░░░░░░░░ 0

  ● CRITICAL  Hardcoded Anthropic API key
    CLAUDE.md:13
    Evidence: sk-ant-a...cdef
    Fix: Replace with environment variable reference [auto-fixable]

  ● CRITICAL  Overly permissive allow rule: Bash(*)
    settings.json
    Evidence: Bash(*)
    Fix: Restrict to specific commands: Bash(git *), Bash(npm *), Bash(node *)

  Summary
  Files scanned: 6
  Findings: 73 total — 19 critical, 29 high, 15 medium, 4 low, 6 info
  Auto-fixable: 8 (use --fix)

More commands

# Scan a specific directory
agentshield scan --path /path/to/.claude

# Auto-fix safe issues (replaces hardcoded secrets with env var references)
agentshield scan --fix

# JSON output for CI pipelines
agentshield scan --format json

# Generate an HTML executive security report
agentshield scan --format html > report.html

# Generate a portable audit bundle
agentshield scan --evidence-pack ./agentshield-evidence

# Three-agent Opus 4.6 adversarial analysis (requires ANTHROPIC_API_KEY)
agentshield scan --opus --stream

# Generate a secure baseline config
agentshield init

JSON 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.

What It Catches

102 rules across 5 categories, graded A–F with a 0–100 numeric score.

Secrets Detection

| What | Examples | |------|----------| | API keys | Anthropic (sk-ant-), OpenAI (sk-proj-/sk-), xAI (xai-), AWS (AKIA), Google/Gemini (AIza), Stripe (sk_test_/sk_live_) | | Tokens | GitHub PATs (ghp_/github_pat_), Linear (lin_api_), Cloudflare (CF_API_TOKEN=), Slack (xox[bprs]-), JWTs (eyJ...), Bearer tokens | | Credentials | Hardcoded passwords, database connection strings (postgres/mongo/mysql/redis), private key material | | Env leaks | Secrets passed through environment variables in configs, echo $SECRET in hooks |

Permission Audit (10 rules)

| What | Examples | |------|----------| | Wildcard access | Bash(*), Write(*), Edit(*) — unrestricted tool permissions | | Missing deny lists | No deny rules for rm -rf, sudo, chmod 777 | | Dangerous flags | --dangerously-skip-permissions usage | | Mutable tool exposure | All mutable tools (Write, Edit, Bash) allowed without scoping | | Destructive git | git push --force, git reset --hard in allowed commands | | Unrestricted network | curl *, wget, ssh *, scp * in allow list without scope |

Hook Analysis (34 rules)

| What | Examples | |------|----------| | Command injection | ${file} interpolation in shell commands — attacker-controlled filenames become code | | Data exfiltration | curl -X POST with variable interpolation sending data to external URLs | | Silent errors | 2>/dev/null, \|\| true — failing security hooks that silently pass | | Missing hooks | No PreToolUse hooks, no Stop hooks for session-end validation | | Network exposure | Unthrottled network requests in hooks, sensitive file access without filtering | | Session startup | SessionStart hooks that download and execute remote scripts | | Package installs | Global npm install -g, pip install, gem install, cargo install in hooks | | Container escape | Docker --privileged, --pid=host, --network=host, root volume mounts | | Credential access | macOS Keychain, GNOME Keyring, /etc/shadow reads | | Reverse shells | /dev/tcp, mkfifo + nc, Python/Perl socket shells | | Clipboard access | pbcopy, xclip, xsel, wl-copy — exfiltration via clipboard | | Log tampering | journalctl --vacuum, rm /var/log, history -c — anti-forensics |

MCP Server Security (23 rules)

| What | Examples | |------|----------| | High-risk servers | Shell/command MCPs, filesystem with root access, database MCPs, browser automation | | Supply chain | npx -y auto-install without confirmation — typosquatting vector | | Hardcoded secrets | API tokens in MCP environment config instead of env var references | | Remote transport | MCP servers connecting to remote URLs (SSE/streamable HTTP) | | Shell metacharacters | &&, \|, ; in MCP server command arguments | | Missing metadata | No version pin, no description, excessive server count | | Sensitive file args | .env, .pem, credentials.json passed as server arguments | | Network exposure | Binding to 0.0.0.0 instead of localhost | | Auto-approve | autoApprove settings that skip user confirmation for tool calls | | Missing timeouts | High-risk servers without timeout — resource exhaustion risk |

Supply-chain verification (agentshield scan --supply-chain) extracts MCP package references plus root package.json and package-lock.json dependency evidence, then reports provenance counts for npm vs git, pinned vs unpinned, known-good packages, and npm-registry-backed metadata. Add --supply-chain-online to query npm for downloads, maintainers, postinstall scripts, deprecation, and package age.

Package-manager hardening checks also scan .npmrc, .yarnrc.yml, and pnpm-workspace.yaml for plaintext registry credentials, explicit dependency lifecycle-script enablement, and missing or weak release-age cooldowns where the package manager supports them. npm configs are checked for lifecycle-script blocking and unsupported release-age keys that can create false confidence; use pnpm minimumReleaseAge / minimum-release-age, Yarn npmMinimalAgeGate, or an external package-manager policy wrapper for cooldown enforcement.

AgentShield also scans AI developer-tool persistence surfaces used by recent npm and PyPI campaign payloads, including Claude Code hook settings, .claude/router_runtime.js, VS Code tasks.json folder-open automation, Zed project tasks.json, .vscode/setup.mjs, .zed/setup.mjs, GitHub workflow drop-ins, LaunchAgent/systemd dead-man switch artifacts, gh-token-monitor token-store files, metadata-service credential targets, and reported exfiltration or second-stage network indicators. These indicators are emitted as critical hook findings so CI can fail fast even after the malicious package has been uninstalled.

MCP Confidence Notes

AgentShield scans both active MCP config and repository-shipped MCP templates.

• Findings from mcp.json, .claude/mcp.json, .claude.json, and active settings.json should be treated as the highest-confidence runtime exposure.
• Findings from settings.local.json are emitted as runtimeConfidence: project-local-optional.
• 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.
• 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.
• 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.
• 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."
• Aggregate findings like large MCP server counts are especially likely to overstate runtime exposure when the source file is a template catalog.

Agent Config Review (25 rules)

| What | Examples | |------|----------| | Unrestricted tools | Agents with Bash access, no allowedTools restriction | | Prompt injection surface | Agents processing external/user-provided content without defenses | | Auto-run instructions | CLAUDE.md containing "Always run", "without asking", "automatically install" | | Hidden instructions | Unicode zero-width characters, HTML comments, base64-encoded directives | | URL execution | CLAUDE.md instructing agents to fetch and execute remote URLs | | Time bombs | Delayed execution instructions triggered by time or absence conditions | | Data harvesting | Bulk collection of passwords, credentials, or database dumps | | Prompt reflection | ignore previous instructions, you are now, DAN jailbreak, fake system prompts | | Output manipulation | always report ok, remove warnings from output, suppress security findings |

Structured 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.

Scanner Accuracy Notes

• Live audit notes and follow-up items are tracked in [false-positive-audit.md](./false-positive-audit.md).
• 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.
• 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).
• Cross-file hook-manifest awareness now suppresses settings-only hooks-no-pretooluse when a companion hooks/hooks.json manifest defines PreToolUse hooks.
• 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.
• 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.
• 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.
• Practical reading rule: template-example means "repo ships this risky template", not "this is definitely enabled right now."
• Practical reading rule: docs-example means "repo ships risky sample guidance", not "this example is active runtime config."
• 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.
• Practical reading rule: plugin-manifest means "the repo declares this hook behavior", while hook-code means "the scanner reached the referenced non-shell implementation."
• 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.
• 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.
• Docs-only nested CLAUDE.md roots under docs/ are now skipped unless runtime config companions exist in the same subtree.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• Narrow specialist agents, subagents, and slash commands now downgrade generic Bash-access and escalation-chain findings from high to medium; broader generali

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: affaan-m
• Source: affaan-m/agentshield
• License: MIT
• Homepage: https://cerebralvalley.ai/e/claude-code-hackathon

Install and usage instructions live in the source repository linked above.