| name | security-scan |
| description | Scan a Claude Code config (.claude/) for vulnerabilities, misconfigurations, and injection risks with AgentShield, covering CLAUDE.md, settings.json, MCP servers, hooks, and agents. USE WHEN setting up a project, after editing settings.json or MCP configs, before committing config, or onboarding to a repo. |
| cluster | security |
| version | 1.0.0 |
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:
npx ecc-agentshield --version
npm install -g ecc-agentshield
npx ecc-agentshield scan .
Usage
Basic Scan
Run against the current project's .claude/ directory:
npx ecc-agentshield scan
npx ecc-agentshield scan --path /path/to/.claude
npx ecc-agentshield scan --min-severity medium
Output Formats
npx ecc-agentshield scan
npx ecc-agentshield scan --format json
npx ecc-agentshield scan --format markdown
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:
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.json with scoped permissions and deny listCLAUDE.md with security best practicesmcp.json placeholder
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 -y auto-install in MCP server configs
Info Findings (awareness)
- Missing descriptions on MCP servers
- Prohibitive instructions correctly flagged as good practice
Links
