version: "1.0.0" name: security-scan description: Scan a Claude Code configuration surface (.claude/ directory, CLAUDE.md, settings.json, MCP servers, hooks, agent definitions) for security vulnerabilities, misconfigurations, and prompt-injection risks using AgentShield (ecc-agentshield). Sister to security-review (broader OWASP / source-code audit). Use this skill when the target is the AGENT CONFIG, not the application source. disable-model-invocation: true

Security Scan (AgentShield)

Vendor-integration recipe for AgentShield.

Sister to ~/.claude/skills/security-review/SKILL.md (source-code

audit — different scope), ~/.claude/skills/owasp-asvs/SKILL.md

(ASVS L1/L2/L3 verification), ~/.claude/rules-library/common/install-allowlist.md

(publisher review before adoption), ~/.claude/rules-library/common/secrets-management.md

(vault-first secret storage), ~/.claude/rules-library/common/repo-setup-checklist.md

(20-point first-touch checklist).

Size budget: 20 KB — token-budget.mjs --check.

Purpose

AgentShield audits a Claude Code configuration surface (the .claude/ directory + CLAUDE.md + MCP / hook / agent definitions) for the security classes that matter at that LAYER: hardcoded secrets in config, over-permissive allowlists, auto-run / prompt-injection patterns, supply-chain risk in MCP servers, command-injection in hooks, dangerous bypass flags.

This is DIFFERENT FROM auditing application source code (use the security-review skill / security-reviewer agent for that) and DIFFERENT FROM running OWASP ASVS controls (use owasp-asvs). The agent-config layer has its own threat model; this skill addresses it.

When to use

• Setting up a new Claude Code project for the first time

(per ~/.claude/rules-library/common/repo-setup-checklist.md)

• After modifying .claude/settings.json, CLAUDE.md, or MCP

configs

• Before committing configuration changes
• When onboarding to a new repository with existing Claude Code

configs

• Periodic security-hygiene checks (quarterly recommended)
• Pre-deploy when a hook or agent change is in the diff

When NOT to use

• Auditing application source code → use security-review
• Verifying OWASP ASVS controls → use owasp-asvs
• Pen-testing a deployed system → use a real DAST tool

(OWASP ZAP, Burp Suite Pro, Nuclei)

• Dependency CVE scanning → use the sister gates in

~/.claude/rules-library/common/dependency-vulnerabilities.md (pnpm audit, npm audit, osv-scanner, govulncheck, pip-audit, cargo audit, bundler-audit, trivy)

• License auditing → use ~/.claude/rules-library/common/license-allowlist-gate.md

workflow

What it scans

Prerequisites

Per `~/.claude/rules-library/common/install-allowlist.md`: Confirm AgentShield's npm publisher (affaan-m) + recent release cadence + signing posture before adoption. The tool is single-author maintained; treat it as higher supply-chain risk than verified-org publishers (@microsoft/*, @anthropic-ai/*, @github/*).

After review + explicit user approval:

# Check installed version
npx ecc-agentshield --version
 
# Install globally (pin the version)
npm install -g ecc-agentshield@<pinned-version>
 
# Or run via npx with version pin (NOT bare `npx -y`)
npx ecc-agentshield@<pinned-version> scan .

The bare npx -y form is in the global deny list. Always pin the version.

Usage

Basic scan

# Scan current project
npx ecc-agentshield scan
 
# Scan a specific path
npx ecc-agentshield scan --path /path/to/.claude
 
# Filter by minimum severity
npx ecc-agentshield scan --min-severity medium

Output formats

# Terminal (default) — coloured report with grade
npx ecc-agentshield scan
 
# JSON — for CI integration
npx ecc-agentshield scan --format json
 
# Markdown — for documentation
npx ecc-agentshield scan --format markdown
 
# HTML — self-contained dark-theme report
npx ecc-agentshield scan --format html > security-report.html

Auto-fix (review before applying)

npx ecc-agentshield scan --fix

Auto-fix applies only safe, well-defined fixes:

• Replaces hardcoded secrets with env-var references
• Tightens wildcard permissions to scoped alternatives
• Leaves manual-only suggestions untouched

Always review the diff before committing auto-fixes; per ~/.claude/rules-library/common/proper-fixes-first.md, never accept a mechanical fix without verifying the root cause is addressed.

Deep analysis (opus-backed adversarial agents)

# Requires ANTHROPIC_API_KEY in env (vault per secrets-management.md)
export ANTHROPIC_API_KEY="$(security find-generic-password \
  -a "$USER" -s ANTHROPIC_API_KEY -w)"
npx ecc-agentshield scan --opus --stream

Runs the three-agent pipeline:

1. Attacker (Red Team) — find attack vectors
2. Defender (Blue Team) — propose hardening
3. Auditor (Final Verdict) — synthesise both perspectives

Initialise secure config

npx ecc-agentshield init

Scaffolds:

• settings.json with scoped permissions + deny list
• CLAUDE.md with security best practices
• mcp.json placeholder

Useful for new projects; per ~/.claude/rules-library/common/repo-setup-checklist.md, ALSO run the 20-point first-touch checklist in the same pass.

GitHub Action

- uses: affaan-m/agentshield@v1
  with:
    path: '.'
    min-severity: 'medium'
    fail-on-findings: true

Per `~/.claude/rules-library/common/security-controls-org-wide.md` rule on SHA-pinning third-party actions: pin to a full commit SHA, not @v1. Use Dependabot / Renovate to bump the SHA on a documented cadence.

Severity grades

Interpreting results

Critical (fix immediately)

• Hardcoded API keys / tokens in config files
• Bash(*) in the allow list (unrestricted shell access)
• Command injection in hooks via ${file} interpolation
• Shell-running MCP servers

High (fix before production / merge)

• Auto-run instructions in CLAUDE.md (prompt-injection vector)
• Missing deny lists in permissions
• Agents with unnecessary Bash access

Medium (recommended)

• Silent error suppression in hooks (2>/dev/null, || true)
• Missing PreToolUse security hooks
• npx -y auto-install in MCP server configs

Info (awareness)

• Missing descriptions on MCP servers
• Prohibitive instructions correctly flagged as good practice

Core patterns

Pattern 1: Run before every config-touching commit

Per ~/.claude/rules-library/common/hooks.md PostToolUse philosophy, treat AgentShield as part of the local pre-commit gate when the diff touches .claude/**. Adds ~5 seconds; catches the entire class of "I just dropped a secret into mcp.json."

Pattern 2: Combine with the install-allowlist review

When mcp.json adds a new MCP server, AgentShield flags supply-chain risk patterns (npx -y without pin, unknown publisher). Pair with the manual review in ~/.claude/rules-library/common/install-allowlist.md for the full adoption decision.

Pattern 3: Treat auto-fix as a starting point

Auto-fix is mechanical. The proper fix often requires moving a secret to a different vault path, restructuring the hook script, or rewriting the agent's tools list. Review the diff; extend the fix as needed.

Pattern 4: Don't silence findings

Per ~/.claude/rules-library/common/no-discards.md + extreme-lint-policy.md, the answer to a finding is either a fix or a documented exception with expiry — never a per-line suppression directive.

Anti-patterns

Verification checklist

After running a scan, confirm:

• [ ] Grade ≥ B (project may require A; document policy)
• [ ] Zero Critical findings
• [ ] Zero High findings open without documented exception +

expiry

• [ ] All Medium findings either fixed or ticketed with owner
• [ ] No per-line suppressions added to silence findings
• [ ] If auto-fix applied: diff reviewed + tested
• [ ] If a hook was modified by auto-fix: command-injection

vector confirmed closed

• [ ] If a permission was tightened: app-side functionality

tested

Standards + references

• AgentShield —

github.com/affaan-m/agentshield, npm ecc-agentshield

• OWASP Top 10 for LLM Applications —

owasp.org/www-project-top-10-for-large-language-model-applications/

• MITRE ATLAS (Adversarial Threat Landscape for AI Systems)

— adversarial ML threat catalogue

• NIST AI RMF (AI 100-1) — AI risk management framework
• Anthropic Agent Skills security guidance — official

Anthropic guidance on Claude Code config hardening

Cross-references

• ~/.claude/skills/security-review/SKILL.md — source-code

security review (different scope)

• ~/.claude/skills/owasp-asvs/SKILL.md — ASVS L1/L2/L3

verification

• ~/.claude/rules-library/common/install-allowlist.md — publisher

review before MCP / agent / tool adoption

• ~/.claude/rules-library/common/secrets-management.md — vault storage;

no secrets in config files

• ~/.claude/rules-library/common/repo-setup-checklist.md — 20-point

first-touch checklist (includes a security-scan step)

• ~/.claude/rules-library/common/security-controls-org-wide.md —

SHA-pin third-party GitHub Actions

• ~/.claude/rules-library/common/no-discards.md — don't silence

findings

• ~/.claude/rules-library/common/proper-fixes-first.md — auto-fix is

a starting point, not a finished fix

Why this skill exists

Agent configuration is its own attack surface:

• Hardcoded API keys in mcp.json leak just like keys in source
• An over-broad Bash(*) allowlist hands the agent an

unrestricted shell

• A hook that interpolates ${file} enables command injection

the moment a filename contains a backtick

• An MCP server installed via npx -y from an unknown publisher

re-runs whatever the publisher pushes today, not what was reviewed yesterday

• A CLAUDE.md with "always run X" instructions becomes a

prompt-injection vector when an attacker controls a file the agent reads

Source-code audits (security-review, security-reviewer agent) don't catch these. AgentShield is the tool for the config layer; this skill names the guardrails around its use so adoption itself stays safe.

Standards Cited

• OWASP ASVS 4.0.3 — Application Security Verification Standard

(L1 / L2 / L3 control catalogue)

• **OWASP Top 10 (2021) + OWASP Top 10 for LLM Applications

(2025) + OWASP API Security Top 10 (2023)** — Vulnerability taxonomies the scan maps to

• NIST SP 800-53 Rev 5 §RA-5, §SI-2, §SA-11 — Vulnerability

scanning + flaw remediation + developer testing

• NIST SP 800-115 — Technical guide to information security

testing + assessment

• NIST SP 800-218 SSDF §PW.8 + §RV.1 — Test executable code
• identify + confirm vulnerabilities
• CWE Top 25 (2026) — Most dangerous software weaknesses

reference

• ISO/IEC 27001:2022 Annex A.8.8 + A.8.29 — Management of

technical vulnerabilities + security testing

• ISO/IEC 27034:2011 — Application security
• PCI-DSS v4.0 §6.3 + §11.3 — Software vulnerability + secure

coding + penetration testing

• CIS Critical Security Controls v8 — Control 7 (continuous

vulnerability management) + Control 16 (application software security)

• CVSS v3.1 / v4.0 — Vulnerability scoring system
• `~/.claude/rules-library/common/dependency-vulnerabilities.md` —

CVE gate runs as part of every scan

Cross-References

• ~/.claude/rules-library/common/security.md — OWASP Top 10 umbrella +

per-vulnerability sister-rule index

• ~/.claude/rules-library/common/secrets-management.md — secret scan

layer of the audit

• ~/.claude/rules-library/common/dependency-vulnerabilities.md — CVE

gate (MODERATE+ blocks)

• ~/.claude/rules-library/common/license-allowlist-gate.md — SPDX

license gate

• ~/.claude/rules-library/common/security-controls-org-wide.md — 5-layer

non-bypassable enforcement

• ~/.claude/agents/security-reviewer.md — review the findings;

classify severity; propose fixes

• ~/.claude/rules-library/common/audit-logging.md — scan results

audit-logged

Anti-Patterns

Learning hooks

Per ~/.claude/rules/common/continuous-learning-mandate.md:

Signals to watch:

• New mcp.json server added without an AgentShield scan in the

same commit (rule "When to use" weakening)

• Grade drops from A → B+ on a previously-clean config (something

was relaxed; investigate)

• Auto-fix accepted without diff review (anti-pattern 4

recurrence; sister proper-fixes-first.md weakening)

• ANTHROPIC_API_KEY exported in plain shell command for

--opus mode (sister secrets-management.md weakening)

• AgentShield publisher rotates / signing key changes (re-trigger

publisher review per install-allowlist.md)

• GitHub Action pinned by tag (@v1) instead of full SHA (sister

security-controls-org-wide.md weakening)

• Finding silenced via per-line suppression instead of fixed

(sister no-discards.md violation)

• Scan run ONLY at setup; no pre-commit / pre-deploy wiring

(pattern 1 weakening)

Refinement candidates:

• New row in the "What it scans" table when AgentShield ships a

new check class (e.g., subagent permission scan, plugin scan)

• New "tool alternative" entry under "When NOT to use" when a

competing scanner (Anthropic-native, MITRE ATLAS-driven, etc.) becomes the team's primary choice

• Tightening of the publisher-review requirement when a supply-

chain incident surfaces in this category

• New cross-reference when a sister rule / skill defines a

guardrail this skill should chain into (e.g., new prompt-injection-defense.md rule when authored)