Security Scan Skill
Audit your Claude Code configuration for security issues using AgentShield.
When to Activate
- Setting up a new Claude Code project
- 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
What It Scans
| File | Checks |
|---|---|
CLAUDE.md |
Hardcoded secrets, auto-run instructions, prompt injection patterns |
settings.json |
Overly permissive allow lists, missing deny lists, dangerous bypass flags |
mcp.json |
Risky MCP servers, hardcoded env secrets, npx supply chain risks |
hooks/ |
Command injection via interpolation, data exfiltration, silent error suppression |
agents/*.md |
Unrestricted tool access, prompt injection surface, missing model specs |
Prerequisites
AgentShield must be installed. Check and install if needed:
# Check if installed
npx ecc-agentshield --version
# Install globally (recommended)
npm install -g ecc-agentshield
# Or run directly via npx (no install needed)
npx ecc-agentshield scan .
Usage
Basic Scan
Run against the current project's .claude/ directory:
# Scan current project
npx ecc-agentshield scan
# Scan a specific path
npx ecc-agentshield scan --path /path/to/.claude
# Scan with minimum severity filter
npx ecc-agentshield scan --min-severity medium
Output Formats
# Terminal output (default) — colored report with grade
npx ecc-agentshield scan
# JSON — for CI/CD 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
Apply safe fixes automatically (only fixes marked as auto-fixable):
npx ecc-agentshield scan --fix
This will:
- Replace hardcoded secrets with environment variable references
- Tighten wildcard permissions to scoped alternatives
- Never modify manual-only suggestions
Opus 4.6 Deep Analysis
Run the adversarial three-agent pipeline for deeper analysis:
# Requires ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY=your-key
npx ecc-agentshield scan --opus --stream
This runs:
- Attacker (Red Team) — finds attack vectors
- Defender (Blue Team) — recommends hardening
- Auditor (Final Verdict) — synthesizes both perspectives
Initialize Secure Config
Scaffold a new secure .claude/ configuration from scratch:
npx ecc-agentshield init
Creates:
settings.jsonwith scoped permissions and deny listCLAUDE.mdwith security best practicesmcp.jsonplaceholder
GitHub Action
Add to your CI pipeline:
- uses: affaan-m/agentshield@v1
with:
path: '.'
min-severity: 'medium'
fail-on-findings: true
Severity Levels
| Grade | Score | Meaning |
|---|---|---|
| A | 90-100 | Secure configuration |
| B | 75-89 | Minor issues |
| C | 60-74 | Needs attention |
| D | 40-59 | Significant risks |
| F | 0-39 | Critical vulnerabilities |
Interpreting Results
Critical Findings (fix immediately)
- Hardcoded API keys or tokens in config files
Bash(*)in the allow list (unrestricted shell access)- Command injection in hooks via
${file}interpolation - Shell-running MCP servers
High Findings (fix before production)
- Auto-run instructions in CLAUDE.md (prompt injection vector)
- Missing deny lists in permissions
- Agents with unnecessary Bash access
Medium Findings (recommended)
- Silent error suppression in hooks (
2>/dev/null,|| true) - Missing PreToolUse security hooks
npx -yauto-install in MCP server configs
Info Findings (awareness)
- Missing descriptions on MCP servers
- Prohibitive instructions correctly flagged as good practice