agentshield — Agent Guide

No conflict-matrix pairs for this tool yet.

# AgentShield — Agent Guide

name: agentshield ｜ version_range: 1.4.0~1.4.0｜ generated: 2026-08-28

title_en: AgentShield - Agent Configuration Security Auditor ｜ desc_en: Scans Claude Code configuration for secrets, permissions, hooks, MCP and prompt-injection surfaces.

Preflight

note: Requires Node >= 18.

node --version

预期输出: see command output

Install

note: npmmirror registry recommended in mainland China. Method A (npx) verified in this environment.

Method A: npx direct scan

note: No install; verified in this environment.

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

预期输出: AgentShield Security Report (target = auto-discovered ~/.claude/ or current directory; graded report + findings list)

Method B: global install

note: Officially recommended for long-term use.

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

预期输出: same as above

Operations

View version

note: Verified in this environment.

npx -y ecc-agentshield --version

预期输出: 1.5.0

Scan a specified directory

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

预期输出: security report (Secrets/Permissions/Hooks/MCP Servers/Agents sections + file-level findings)

Integration with Agent flow

note: JSON output for machine post-processing; flag is -f json (verified 2026-08-30).

npx -y ecc-agentshield scan -f json

预期输出: JSON-format report (machine-readable, convenient for Agent post-processing)

（2026-08-30 实测：-f json 可用）

Baseline regression gate (CI)

note: verified 2026-08-30; gate failure exit code is still 0 - parse "Gate: FAILED" text or JSON summary in CI

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

预期输出: first scan saves baseline; later scans print `Gate: FAILED` on new findings (exit code stays 0 - do not rely on it)

Uninstall

note: npx mode leaves no global residue (idempotent); global install requires 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'

预期输出: agentshield removed: OK

Facts

writes: none (read-only auditor) ｜ runtime: Node >= 18, npm/npx ｜ notes: no background process; zero write surface; -f json + CI baseline/gate verified 2026-08-30; gate failure still exits 0 — parse output text/JSON in CI

Source: agentshield · validated 2026-08-28 · v1.4.0~1.4.0

← Agent index