AgentShield scans .claude/ for secrets, wildcard Bash rules and hook injection

The gap AgentShield is aimed at

Agent configuration has become executable surface. A settings.json allow list decides which shell commands an agent may run unattended. A hook decides what happens when a file is written. An MCP server definition decides which remote process the agent can talk to. These files are usually copied from a README or a community skill and rarely reviewed by anyone with a security role.

The README opens with numbers from January 2026 that frame the problem: it states that 12% of a major agent skill marketplace was malicious (341 of 2,857 community skills), that a CVSS 8.8 CVE exposed 17,500+ internet-facing instances to one-click RCE, and that the Moltbook breach compromised 1.5M API tokens across 770,000 agents. Those figures come from the project's own README and are not independently verified here.

The intended user is narrow and clear: someone who runs Claude Code and keeps a .claude/ directory, or reviews a repository that does. AgentShield is not a runtime guard. It reads configuration files and reports what it finds.

How the scan works: discovery, 268 rules, weighted scoring

The CLI auto-discovers ~/.claude/ and walks the config files it recognizes. Discovery deliberately skips generated directories such as node_modules, build output and .dmux worktree mirrors, so a transient copy of a config does not produce a second set of findings.

Detection is organized as 268 rules across 15 modules. The README documents the categories it covers in most detail: secrets (Anthropic sk-ant-, OpenAI sk-proj- and sk-, xAI xai-, AWS AKIA, Google AIza, Stripe sk_test_ and sk_live_, GitHub PATs, Slack tokens, JWTs, database connection strings, private key material), permissions (17 rules, including Bash(*), Write(*), Edit(*), missing deny rules for rm -rf and sudo, and --dangerously-skip-permissions), and hooks (40 rules, including ${file} interpolation in shell commands where a filename is attacker-controlled). MCP server risk and agent prompt injection vectors are named in the header but the truncated README does not enumerate their rules.

Scoring is the part worth reading twice. Each category starts at 100 and only findings subtract: critical 25, high 15, medium 5, low 2, info 0. Protective configuration the scanner recognizes (deny and ask lists, sandbox settings, blocking PreToolUse hooks, read-only agent tool lists, Codex sandbox_mode) is listed under Recognized Defenses, but it adds no points. The README states the reason 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 forced to zero deduction in src/reporter/score.ts. That is a defensible design, and it means a high grade reflects absence of findings rather than presence of hardening.

Install and first scan

No install is needed for a first look. The README gives npx as the shortest path, and it auto-discovers ~/.claude/.

npx ecc-agentshield scan

You should see a graded report: a letter grade with a numeric score out of 100, a per-category breakdown for Secrets, Permissions, Hooks, MCP Servers and Agents, then findings with file and line, an evidence excerpt, and a fix. The README's example output shows a CLAUDE.md:13 hardcoded Anthropic key with evidence rendered as sk-ant-a...cdef, and an overly permissive Bash(*) allow rule, each marked CRITICAL.

For repeated use, install globally. The binary name is agentshield.

npm install -g ecc-agentshield
agentshield scan

To scan something other than the default directory, point --path at it. This is the form to use in a repository that checks in .claude/ rather than keeping it in the home directory.

agentshield scan --path /path/to/.claude

CI pipelines want machine-readable output, and the README documents --format json for that, with findings[].runtimeConfidence present when AgentShield can tell active runtime config from project-local settings, template or example inventories, installed plugin caches, declarative plugin manifests, and manifest-resolved non-shell hook implementations.

agentshield scan --format json

Two other commands are worth knowing on day one. --fix applies only the safe subset (the README describes it as replacing hardcoded secrets with environment variable references), and init writes a secure baseline config rather than scanning one.

agentshield scan --fix
agentshield init

Auto-fix is the smallest part of the report

The README's own sample output is the clearest statement of scope: 73 findings, of which 19 critical, 29 high, 15 medium, 4 low and 6 info, and 8 auto-fixable. Roughly one in nine findings is something the tool will repair for you. The rest are judgement calls about permissions, hooks and server definitions that a scanner cannot safely rewrite.

That ratio matters for how the tool fits into a workflow. --fix is useful for the mechanical case of a secret pasted into a config, and it is the one operation that mutates your files. The README does not document rollback, and it does not describe a dry-run mode for --fix. If you run it, you are relying on git to undo it.

The second constraint is interpretive. runtimeConfidence exists precisely because a .claude/ tree can contain several kinds of file that look alike: live configuration, project-local overrides, template and example inventories, installed plugin caches, declarative plugin manifests, and non-shell hook implementations resolved through a manifest. A finding in examples/vulnerable/ is not the same as a finding in settings.json, and the JSON report is where that distinction is available.

Where AgentShield is the wrong tool

AgentShield reads files. If your agent configuration is managed in a hosted console and never materializes on disk, there is nothing for the scanner to discover, and the grade you get is a grade on whatever fragments happen to be checked in.

It is also scoped to Claude Code and adjacent harnesses. The README states that reports 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. That is a list of adapters, not a claim of universal coverage, and the rule set is written around the shape of these configuration files. Bring it a bespoke agent framework with its own permission model and the 268 rules largely will not apply.

Finally, a clean scan is not a security review. The scoring model only subtracts, so a configuration with no recognizable findings scores well even if it grants broad access in a way no rule describes. The absence of findings is evidence about the rule set, not about the system.

How it differs from a general-purpose scanner

The obvious comparison is a secret-scanning tool such as gitleaks or a static analyzer such as semgrep. Those read source code for patterns that indicate a leaked credential or a dangerous construct, and they are general by design. AgentShield reads agent configuration specifically, and its rules encode decisions that only make sense in that context: a Bash(*) allow rule is a finding because it grants an agent unattended shell access, and ${file} interpolation in a hook is a finding because the filename is attacker-controlled.

A generic scanner would flag the same sk-ant- key in CLAUDE.md. It would not tell you that your deny list is missing an entry for rm -rf, and it would not grade the permission surface. The trade-off runs the other way too: AgentShield knows nothing about your application code, your dependencies or your container image, and the README does not present it as covering any of that. The two categories are complements, and running AgentShield does not remove the reason to run a secret scanner over the repository itself.

Maintenance, distribution and licence

The repository is not archived, and the last push was on 2026-09-10. The release history shows v1.4.0 on 2026-03-22, then v1.5.0 and v1.6.0 both on 2026-09-10, so the recent cadence is a burst rather than a steady line. The npm package is ecc-agentshield at version 1.6.0, and the package.json shows a prepublishOnly script that runs the build, which means the published artifact is built from source rather than committed by hand.

The distribution surface is larger than the CLI: the README lists a GitHub Action, a GitHub App integration under the ecc-tools app, and an ECC plugin, with examples/agentshield-workflow.yml and action.yml in the repository. Each of those is another thing to keep current when rules change, and a rule change can move a grade without any change to your configuration. That is the real upgrade cost here: a version bump may reclassify a finding as critical, and a CI job that fails on grade will fail for a reason unrelated to your commit.

The licence is MIT, declared in package.json and referenced by the README badge. MIT is permissive and places few obligations on how you use the output; it also comes with no warranty. Nothing here is legal advice, and if you plan to redistribute the tool or embed it in a commercial product, read LICENSE in the repository rather than this paragraph.

Editorial conclusion

Adopt AgentShield if your team keeps a checked-in .claude/ directory, hooks or MCP server definitions, and you want a graded report before those files reach a shared branch. Skip it if your agent configuration lives entirely in a hosted console you cannot export, or if you expect a general AI-agent security product: this scanner reads Claude Code and adjacent harness config on disk. Before trusting a grade, run npx ecc-agentshield scan --format json on your own repository and read the findings[].runtimeConfidence field, then decide whether the flagged entries are active runtime config or template examples. Anything you intend to fix automatically, run without --fix first and diff the result.

Frequently asked questions

Official sources

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