Security Scan Skill

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

CLAUDE.md

settings.json

mcp.json

hooks/

agents/*.md

Prerequisites

# 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

.claude/

# 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

npx ecc-agentshield scan --fix

• Replace hardcoded secrets with environment variable references
• Tighten wildcard permissions to scoped alternatives
• Never modify manual-only suggestions

Opus 4.6 Deep Analysis

# Requires ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY=your-key
npx ecc-agentshield scan --opus --stream

1. Attacker (Red Team) — finds attack vectors
2. Defender (Blue Team) — recommends hardening
3. Auditor (Final Verdict) — synthesizes both perspectives

Initialize Secure Config

.claude/

npx ecc-agentshield init

• settings.json

  with scoped permissions and deny list

• CLAUDE.md

  with security best practices

• mcp.json

  placeholder

GitHub Action

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

Severity Levels

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

• GitHub: github.com/affaan-m/agentshield
• npm: npmjs.com/package/ecc-agentshield