Security Scan

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

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

# SARIF (v1.4.0+) — for GitHub code scanning upload
npx ecc-agentshield scan --format sarif --output agentshield.sarif

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

Baseline Comparison & PR Gate (v1.4.0+)

Snapshot an accepted state, then fail CI only on regressions:

# Write an accepted baseline snapshot (stores hashed fingerprints, not raw evidence)
npx ecc-agentshield baseline write --path .claude --output .github/agentshield-baseline.json

# Compare a scan against the baseline; --gate fails on new critical/high findings or a score drop
npx ecc-agentshield scan --baseline .github/agentshield-baseline.json --gate

# Or save the current scan as the new baseline
npx ecc-agentshield scan --save-baseline .github/agentshield-baseline.json

Supply-Chain Verification (v1.4.0+)

Verify the provenance of MCP package references (plus root package.json / package-lock.json dependency evidence): npm vs git, pinned vs unpinned, known-good and known-malicious packages.

# Offline provenance checks
npx ecc-agentshield scan --supply-chain

# Also query the npm registry: downloads, maintainers, postinstall scripts,
# deprecation, and package age
npx ecc-agentshield scan --supply-chain --supply-chain-online

Runtime Monitor (v1.4.0+)

Install a PreToolUse hook that intercepts tool calls in real time, beyond static config scanning:

# Install the PreToolUse runtime monitor
npx ecc-agentshield runtime install

# Check whether the hook, policy, and log path are healthy
npx ecc-agentshield runtime status --check

# Back up invalid runtime files and restore a healthy install
npx ecc-agentshield runtime repair

Opus 4.6 Deep Analysis

Run the adversarial three-agent pipeline for deeper analysis:

# Requires ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY=your-key   # real keys: load from a secret manager (1Password, etc.), never hardcode in shell profiles or .env committed to git
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

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