AgentShield scans Claude Code configs for secrets, permission gaps and hook injection

The gap AgentShield targets: config files nobody audits

Agent setups accumulate files that carry real authority and get almost no review. A settings.json grants Bash(*). A hook interpolates a filename into a shell command. A CLAUDE.md line holds an API key that was pasted in for a quick test. AgentShield exists to read those files and report what they permit. Its README frames the motivation with three January 2026 incidents: a marketplace where 341 of 2,857 community skills were malicious, a CVSS 8.8 CVE affecting 17,500 or more internet-facing instances, and a breach described as compromising 1.5M API tokens across 770,000 agents. Those figures come from the project's own write-up, and the scanner does not independently verify them. Treat them as the author's stated rationale, not as measurements the tool produces. The audience is narrow and clear: developers running Claude Code who install community skills, connect MCP servers and configure hooks without a review step. That is who the tool is for.

How the scan works: discovery, rules, scoring

The mechanism is static analysis over a directory tree. Running agentshield scan auto-discovers ~/.claude/, walks the config files, and prints a graded report. Discovery deliberately skips generated directories such as node_modules, build output and .dmux worktree mirrors, so transient copies do not produce duplicate findings. The rule set is described as 268 rules across 15 modules. Scoring is per category, starting at 100, with deductions of 25 for critical, 15 for high, 5 for medium, 2 for low and 0 for info. The overall grade runs from A to F on a 0 to 100 scale. One design detail is worth calling out because most scanners get it wrong: defenses do not add points. Deny and ask lists, sandbox settings, blocking PreToolUse hooks and read-only agent tool lists are listed under Recognized Defenses and are never penalized, but they cannot raise a score either. The README states the intent directly: the score cannot be gamed by adding decorative deny rules, it can only be lowered by real findings. Guard-pattern findings that the permission rules emit at info severity are pinned to zero deduction in src/reporter/score.ts. That is a defensible choice. A scanner that rewarded defensive-looking config would be trivially satisfied by a deny rule nobody enforces.

What the rule modules actually check

Secrets detection matches provider-shaped strings: Anthropic sk-ant-, OpenAI sk-proj- and sk-, xAI xai-, AWS AKIA, Google and Gemini AIza, Stripe sk_test_ and sk_live_, plus GitHub personal access tokens, Linear lin_api_, Cloudflare CF_API_TOKEN=, Slack xox[bprs]-, JWTs beginning eyJ, and Bearer tokens. It also looks for hardcoded passwords, database connection strings for postgres, mongo, mysql and redis, private key material, and secrets passed through environment variables inside configs, including echo $SECRET in hook commands. The permission module carries 17 rules and covers wildcard grants such as Bash(*), Write(*) and Edit(*), missing deny lists for rm -rf, sudo and chmod 777, the --dangerously-skip-permissions flag, mutable tools allowed without scoping, destructive git commands such as git push --force and git reset --hard, and unscoped network commands including curl *, wget, ssh * and scp *. Hook analysis runs 40 rules, with command injection through ${file} interpolation in shell commands as the headline case, where an attacker-controlled filename reaches the shell. MCP server risks and agent prompt injection vectors are named in the project description and README but the supplied material does not enumerate their rules, so the depth there is unverified. The README's own example report shows the output shape: a grade of F at 0/100, a per-category breakdown across Secrets, Permissions, Hooks, MCP Servers and Agents, individual findings with file and line references, masked evidence such as sk-ant-a...cdef, and a suggested fix. The sample summary reports 73 findings across 6 files, with 19 critical, 29 high, 15 medium, 4 low and 6 info, of which 8 are marked auto-fixable.

Running it: commands, flags and the fix boundary

The fastest path needs no install: npx ecc-agentshield scan. Global installation is npm install -g ecc-agentshield followed by agentshield scan. The package name on npm is ecc-agentshield while the binary is agentshield, which is worth knowing before you script either. Useful flags from the README: scan --path /path/to/.claude to target a specific directory, scan --fix to auto-fix safe issues, scan --format json for CI pipelines, scan --format html to emit an executive report, scan --evidence-pack ./agentshield-evidence for a portable audit bundle, scan --opus --stream for three-agent Claude Opus adversarial analysis, and init to generate a secure baseline config. The --opus mode requires ANTHROPIC_API_KEY, which means that path sends your configuration to Anthropic. The offline scan does not, but the deep analysis does, and that distinction matters if the config contains the very secrets the scanner is looking for. Auto-fix scope is stated narrowly: it replaces hardcoded secrets with environment variable references. The README does not claim it rewrites permission rules or hook logic, and the example output marks only 8 of 73 findings as auto-fixable. Do not read --fix as remediation of the report.

The limitation that decides most evaluations

AgentShield is a static analyzer for a specific configuration format. It reads files. It does not observe what an agent does at runtime, so a hook that is syntactically clean but calls a compromised remote script will pass. It cannot tell you whether an MCP server behaves as its manifest claims. It cannot detect a secret that is fetched at runtime from a vault or injected by a wrapper outside the scanned tree. The rule set is tuned to Claude Code config surfaces, and while JSON reports expose findings[].runtimeConfidence and the project lists local harness adapter evidence for Claude Code, OpenCode, Codex, Gemini, Zed, VS Code, dmux, terminal-agent wrappers and project-local templates, that evidence appears when matching markers are present. A non-Claude agent stack with different config conventions is largely outside the rule set's assumptions. The runtimeConfidence field itself is an admission that the scanner sees files, not deployments: it distinguishes active runtime config from project-local settings, template and example inventories, installed Claude plugin caches, declarative plugin manifests, and manifest-resolved non-shell hook implementations. If you scan a repository of examples, you can get a grade that describes templates rather than anything running. Read that field before acting on a score.

Where it sits next to general secret scanners

The obvious comparison is a general-purpose secret scanner such as gitleaks or trufflehog, and the difference is the unit of analysis. Those tools scan a repository or history for credential-shaped strings and stop there. AgentShield scans a configuration directory and reasons about what the configuration permits. A settings.json with Bash(*) contains no secret at all, and a secret scanner will report nothing, yet AgentShield treats that wildcard as a finding and suggests restricting it to specific commands such as Bash(git *), Bash(npm *), Bash(node *). Conversely, a general secret scanner with git history coverage will catch a key that was committed and later removed, which a directory scan of the current tree will not. The two are complementary rather than substitutes, and running AgentShield does not remove the reason to keep a history-aware secret scanner in the pipeline.

Distribution, maintenance and licence

The project ships as a CLI, a GitHub Action, an ECC plugin and a GitHub App integration, which means you can wire it into CI without writing a wrapper, and the JSON format exists for that purpose. Maintenance signals visible in the supplied material: the repository is not archived, the last push and the v1.6.0 release both fall on 2026-09-10, v1.5.0 landed the same day, and v1.4.0 dates to 2026-03-22. Two releases in a single day suggests active iteration, and it also suggests the rule set and output schema can move quickly. If you parse --format json in a pipeline, pin the version and expect findings[].runtimeConfidence and similar fields to be added between minors. The licence is MIT. That permits commercial use, modification and redistribution with the licence and copyright notice retained, but it also means no warranty, and this is a security tool whose output you may act on. Nothing here is legal advice; if you redistribute a modified build, read the LICENSE file rather than this summary. The README also names a compute sponsor and states that managed inference through that provider is not live yet, and that the project links to the dashboard for sign-in and GPU rental without creating or managing rentals itself. That is sponsorship disclosure, not a functional dependency of the scanner.

Editorial conclusion

Adopt AgentShield if you run Claude Code with community skills, MCP servers or project-local hooks and you want a fast, offline check of the configuration files before they reach a shared repository. Skip it if your agent stack is not Claude Code or a recognized local harness adapter, because the rule set is written around those config surfaces. Before trusting a clean grade, run agentshield scan --format json on the exact directory you care about and read findings[].runtimeConfidence, since a passing score on a template directory says nothing about the active config.

Official sources

1. affaan-m/agentshield on GitHub
2. License: MIT
3. Project website
4. README
5. Releases