agentshield

What you will run into

You installed a pile of plugins, skills and MCP servers for Claude Code — are there secret leaks, dangerous permissions, or suspicious hooks in the config? AgentShield exists for this: it scans Claude Code config for secrets, permissions, hooks, MCP servers and prompt-injection surfaces, and outputs a severity-graded security report. Its most reassuring property is being read-only: scanning changes nothing (verified zero write surface), so you can run it any time without worry. There are two usage paths: npx no-install trial (verified here) or global install for long-term use (officially recommended). When to use it:

• You just installed a bunch of agent site docs and want to see what risk surfaces exist in the config;
• You want a security check of agent config before CI or opening a PR;
• You want to hand scan results to an agent/CI for decisions (-f json machine-readable).

When not to use it: when you need fixing, not checking — it only reports, it does not fix.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

npm package ecc-agentshield, CLI command agentshield scan. Scan target = auto-discovered ~/.claude/ or the current directory (or a specified directory); output = graded report + findings list (Secrets / Permissions / Hooks / MCP Servers / Agents sections + file-level findings). Two usage forms:

• Method A: npx direct scan (no install, verified here);
• Method B: global install (officially recommended for long-term use).

Where it writes: nowhere — scanning has zero write surface; global install only writes the npm global directory.

Step by step

Step 1: Run the first scan

Why: the npx form does not install anything globally — one scan, done, gone; good for seeing results before deciding on a permanent install. Mainland npm direct is slow, use the npmmirror registry prefix. First scan target = auto-discovered ~/.claude/ or the current directory.

npm_config_registry=https://registry.npmmirror.com npx -y ecc-agentshield scan

Expected output: AgentShield Security Report (target = auto-discovered ~/.claude/ or current directory; graded report + findings list) After install, confirm:

• output is a Security Report with grades and findings;
• version check: npx -y ecc-agentshield --version → 1.5.0 (CLI self-reported version, hardcoded in the program; the npm package is actually 1.4.0 — official versions are not in sync; verified 2026-08-31 on both npmmirror and the npm registry, 1.5.0 was never published).

Stuck? How to recover:

• npx slow/fails to fetch → make sure the command has the npm_config_registry=https://registry.npmmirror.com prefix;
• Node version error → confirm Node >= 18.

Step 2: Global install for long-term use

Why: after a global install you call agentshield directly — good for hooking scans into daily flows (CI, before PRs).

npm_config_registry=https://registry.npmmirror.com npm install -g ecc-agentshield
agentshield scan

Expected output: same as above (Security Report) After install, confirm:

• agentshield --version works;
• agentshield scan outputs a report.

Stuck? How to recover:

• global command not found → confirm the npm global bin directory is on PATH;
• scan shows many findings and you do not know where to start → the report is graded; handle high-risk items first (Secrets / permissions), then review Hooks/MCP one by one.

Step 3: Scan a specific directory + hand to an agent

Why: scanning a specified directory (e.g. /path/to/.claude) targets a specific config; -f json outputs a machine-readable report (verified 2026-08-30: JSON contains timestamp/targetPath/findings[]/score/summary) for agent post-processing.

npx -y ecc-agentshield scan /path/to/.claude

Expected output: security report (Secrets/Permissions/Hooks/MCP Servers/Agents sections + file-level findings)

npx -y ecc-agentshield scan -f json

Expected output: JSON report (verified fields: timestamp / targetPath / findings[] (id/severity/category/title/file/fix) / score (grade/numericScore/breakdown) / summary (totalFindings/critical/high/medium/low/info/filesScanned)) (verified 2026-08-30: -f json works) Operation 4: Baseline regression gate (daily CI use; verified 2026-08-30)

npx -y ecc-agentshield scan --save-baseline
npx -y ecc-agentshield scan --baseline --gate

Expected output: first scan saves a baseline (Baseline saved); later scans compare against it, printing Gate: FAILED when new findings appear (verified: baseline with 2 findings → introduce a new secret → Gate FAILED) — key pitfall: the process exit code is still 0 on gate failure, so CI must parse the output text (Gate: FAILED) or the JSON summary, not just the exit code Stuck? How to recover:

• -f json output misbehaves → confirm the flag is -f json (not --json);
• specified directory missing/no permission → confirm the path exists and is readable, then scan.

How to confirm it works

One command plus a version check:

npx -y ecc-agentshield --version

Expected output: 1.5.0 (verified here — CLI self-reported version; the npm package version is 1.4.0, see Dependency warnings)

npx -y ecc-agentshield scan

Expected output: Security Report (graded + findings list; scanning is read-only, running it any number of times changes nothing)

• version prints correctly = the package fetches and executes;
• a scan produces a report (even all-low/no findings) = the scan path works.

Other environments

• Global vs npx: npx is no-install, run-and-gone; global install (officially recommended) suits CI/daily flows.
• Scan scope: default auto-discovers ~/.claude/ or the current directory; use agentshield scan /path/to/.claude for a specific directory.
• CI integration: -f json output can be handed to an agent/pipeline for post-processing; --save-baseline stores a baseline → --baseline + --gate blocks regressions (verified 2026-08-30: baseline 2 findings → added a new secret → Gate FAILED). Key gotcha: gate failure still exits 0, so CI must parse output text (Gate: FAILED) or the JSON summary, not rely on the exit code.
• Node version: >= 18.

Daily usage

Startup and entry

No background process; entry = agentshield scan (or the npx form).

Common operations

Operation 1: View the version (verified here)

npx -y ecc-agentshield --version

Expected output: 1.5.0 Operation 2: Scan a specific directory

npx -y ecc-agentshield scan /path/to/.claude

Expected output: security report (Secrets/Permissions/Hooks/MCP Servers/Agents sections + file-level findings) Operation 3: Integrate with agent flows (hand the report to an agent after scanning)

npx -y ecc-agentshield scan -f json

Expected output: JSON report (verified fields: timestamp / targetPath / findings[] (id/severity/category/title/file/fix) / score (grade/numericScore/breakdown) / summary (totalFindings/critical/high/medium/low/info/filesScanned)) (verified 2026-08-30: -f json works)

Data and directories

• No dedicated data directory; scanning reads ~/.claude/ (or the specified directory) read-only.

Uninstall & cleanup

note: the npx form leaves no global residue (idempotent); a global install needs explicit uninstall; scanning has zero write surface

npm rm -g ecc-agentshield 2>/dev/null || true
npm ls -g ecc-agentshield 2>/dev/null | grep -q ecc-agentshield && echo '残留: ecc-agentshield 仍存在' || echo 'agentshield removed: OK'

Expected output: agentshield removed: OK

Dependency warnings

• Version: npm package [1.4.0, 1.4.0] (verified 2026-08-31); CLI --version self-reports 1.5.0 as a hardcoded string (program.version in dist), out of sync with the package version — official phenomenon, not an install error.
• Environment: Node >= 18.
• Network: npm via npmmirror prefix (verified mainland path).
• Write surface: zero (read-only auditor, verified); global install writes the npm global directory.
• Co-install: no conflict-matrix pairs (read-only tool, no shared write surface).

FAQ

• Q: Will scanning change my config? A: No. Read-only auditor, verified zero write surface.
• Q: npx or global install? A: try npx first (no install); install globally for long-term use (officially recommended).
• Q: What if the report shows high-risk findings? A: the report is graded; handle Secrets and permission high-risk items first; evaluate Hooks/MCP one by one as needed. This tool only reports, it does not fix.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel; project issues go to the author's repository.