Skip to main content
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

FileChecks
CLAUDE.mdHardcoded secrets, auto-run instructions, prompt injection patterns
settings.jsonOverly permissive allow lists, missing deny lists, dangerous bypass flags
mcp.jsonRisky MCP servers, hardcoded env secrets, npx supply chain risks
hooks/Command injection via interpolation, data exfiltration, silent error suppression
agents/*.mdUnrestricted tool access, prompt injection surface, missing model specs

​
Prerequisites

AgentShield must be installed: 
# 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

# 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:
  1. Attacker (Red Team) — finds attack vectors
  2. Defender (Blue Team) — recommends hardening
  3. 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 list
  • CLAUDE.md with security best practices
  • mcp.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

GradeScoreMeaning
A90-100Secure configuration
B75-89Minor issues
C60-74Needs attention
D40-59Significant risks
F0-39Critical 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
  • 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
Security scanning should be part of your regular workflow. Run AgentShield before committing configuration changes.