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.
$ npx -y skills add affaan-m/agentshield --agent claude-code
Repo: affaan-m/agentshield
What's inside
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.
Quick Start · What It Catches · API Reference · Opus Pipeline · GitHub Action · Distribution · MiniClaw · Changelog
The AI agent ecosystem is growing faster than its security tooling. In January 2026 alone:
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).
# 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)
# 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 Claude Opus 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.
268 rules across 15 modules, graded A to F with a 0 to 100 numeric score. Recognized defenses are listed and never penalized.
The 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.
| 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 |
| 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 |
| 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 |
| 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.
AgentShield scans both active MCP config and repository-shipped MCP templates.
.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.settings.local.json are emitted as runtimeConfidence: project-local-optional.mcp-configs/, config/mcp/, or configs/mcp/ indicate risky MCP definitions present in repository templates, not guaranteed active runtime enablement.runtimeConfidence: active-runtime | project-local-optional | template-example | docs-example | plugin-cache | plugin-manifest | hook-code.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.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."
View @affaan-m’s profileYour agent can write code, but ECC gives it a coordinated engineering system and toolbox: it plans before it builds, verifies changes with tests, reviews its own work from a fresh context, remembers what matters, and turns repeated wins into reusable skills
@affaan-mYour agent can write code, but ECC gives it a coordinated engineering system and toolbox: it plans before it builds, verifies changes with tests, reviews its own work from a fresh context, remembers what matters, and turns repeated wins into reusable skills
@affaan-mFAQ
agentshield is a Claude Code plugin with 1 hand-picked skill for security work, indexed on Flowy. Install it with the command on its page. It includes agentshield. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
Is this plugin yours?
Claim it with GitHubSubmit a pluginPromote it