Security Scan

/security-scan — Security Scan

Security scanner for Claude Code projects. Checks for hardcoded secrets, MCP server permissions, hook safety, dependency vulnerabilities, and configuration anti-patterns. Read-only — analyzes but never modifies.

Problem

Claude Code projects have a unique attack surface: MCP servers with broad permissions, hook scripts that execute automatically, and configuration files that can disable safety checks. Standard security scanners miss these Claude Code-specific vectors entirely.

Modes

Phase 1: Secret Detection

Scan for hardcoded secrets in source files, configs, and environment handling.

1.1 Hardcoded Secret Patterns

Search all tracked files (respect .gitignore) for these pattern categories.

NOTE: Use the same detection patterns defined in the project's secret-leak-check.sh hook as a baseline. The hook file is the canonical source of secret patterns — do not duplicate regexes here. Instead, reference the hook and add these additional categories:

Exclusions: Skip node_modules/, .git/, dist/, build/, lock files, and binary files. Skip patterns inside comments that are clearly examples (e.g. YOUR_KEY_HERE, xxx, changeme).

Finding: SEC-S-{NN}: Hardcoded {type} found in {file}:{line}

1.2 Environment File Safety

Finding: SEC-S-{NN}: {description}

1.3 Gitignore Completeness

Check .gitignore for these security-relevant patterns:

Finding: SEC-S-{NN}: .gitignore missing pattern for {pattern}

Phase 2: MCP Server Audit

Analyze MCP server configurations for permission and trust issues.

2.1 Locate MCP Config

Read MCP server configs from these locations (in priority order):

1. .claude/settings.json (project-level)
2. ~/.claude/settings.json (user-level)

Parse with node -e (cross-platform). Extract mcpServers object.

2.2 Permission Analysis

For each MCP server, check:

Finding: SEC-M-{NN}: MCP server "{name}" has {permission} — {risk description}

2.3 Trust Assessment

Finding: SEC-M-{NN}: {description}

2.4 Known Safe Servers

Maintain a list of recognized MCP servers (do not flag these as unknown):

• @anthropic-ai/* — Official Anthropic servers
• @modelcontextprotocol/* — Official MCP servers
• playwright — Browser automation
• github — GitHub integration
• context7 — Documentation lookup

Servers not on this list get an INFO finding, not automatic HIGH.

Phase 3: Hook Safety

Analyze hook scripts for dangerous patterns that could indicate supply-chain attacks or accidental security holes.

3.1 Locate Hooks

Search for hook definitions in:

1. .claude/settings.json > hooks object
2. .claude/hooks/ directory (all .sh, .js, .mjs files)

3.2 Dangerous Patterns

Scan each hook script/command for:

Finding: SEC-H-{NN}: Hook "{name}" contains {pattern} — {risk}

3.3 Hook Structure Checks

Finding: SEC-H-{NN}: {description}

Phase 4: Dependency Audit

Check project dependencies for known vulnerabilities and risk signals.

4.1 npm Audit (if applicable)

If package.json exists:

npm audit --json 2>/dev/null | node -e "
  const data = JSON.parse(require('fs').readFileSync(0,'utf8'));
  const meta = data.metadata || {};
  const vulns = meta.vulnerabilities || {};
  console.log(JSON.stringify({
    total: meta.totalDependencies || 0,
    critical: vulns.critical || 0,
    high: vulns.high || 0,
    moderate: vulns.moderate || 0,
    low: vulns.low || 0
  }));
"

Map results to findings:

If npm audit is unavailable or fails, note it as INFO and continue.

4.2 Dependency Risk Signals

Check package.json for:

Finding: SEC-D-{NN}: {description}

4.3 Python Audit (if applicable)

If requirements.txt or pyproject.toml exists:

• Check for pinned versions (== vs >=)
• Flag unpinned dependencies as MEDIUM
• If pip-audit is available, run it

4.4 Outdated Major Versions

If package.json exists, check for major version staleness:

npm outdated --json 2>/dev/null | node -e "
  const data = JSON.parse(require('fs').readFileSync(0,'utf8'));
  Object.entries(data).forEach(([pkg, info]) => {
    const curr = (info.current || '').split('.')[0];
    const latest = (info.latest || '').split('.')[0];
    if (curr && latest && curr !== latest) {
      console.log(pkg + ': ' + info.current + ' -> ' + info.latest);
    }
  });
"

Finding: SEC-D-{NN}: {package} is {N} major versions behind ({current} -> {latest}) — LOW

Phase 5: Configuration Review

Check Claude Code and project configuration for security anti-patterns.

5.1 CLAUDE.md Security Review

Read project CLAUDE.md (if present) and flag:

Finding: SEC-C-{NN}: CLAUDE.md contains {pattern} — {risk}

5.2 Settings Security

Check .claude/settings.json for:

Finding: SEC-C-{NN}: {description}

5.3 Production Config Leaks

Check for development/debug settings that should not be in production:

Finding: SEC-C-{NN}: {description}

Grading System

After all phases complete, calculate a letter grade based on weighted findings.

Point Deductions

Grade Thresholds

Start at 100 points, subtract per finding:

Grade Caps

Regardless of total score, the grade is capped if:

Output Format

Security Scan: {project-name}
====================================

Grade: {letter} ({score}/100)

Phase 1: Secret Detection
  {OK | FINDINGS}
  - SEC-S-01 [CRITICAL] Hardcoded credential in src/config.ts:42
  - SEC-S-02 [HIGH] .env not in .gitignore

Phase 2: MCP Server Audit
  {OK | FINDINGS}
  - SEC-M-01 [HIGH] MCP server "custom-fs" has unrestricted file system access

Phase 3: Hook Safety
  {OK | FINDINGS}

Phase 4: Dependency Audit
  {OK | FINDINGS}
  - SEC-D-01 [CRITICAL] 2 critical vulnerabilities (npm audit)
  - SEC-D-02 [LOW] express is 2 major versions behind (4.x -> 5.x)

Phase 5: Configuration Review
  {OK | FINDINGS}
  - SEC-C-01 [HIGH] CLAUDE.md contains "skip security checks"

------------------------------------
Summary: {total} findings
  CRITICAL: {n}  HIGH: {n}  MEDIUM: {n}  LOW: {n}  INFO: {n}

{grade_explanation}

State File (.security-scan-state.json)

Written after every scan. Enables trend tracking across sessions.

{
  "version": "1.0",
  "scanDate": "2026-04-04",
  "project": "my-project",
  "grade": "B",
  "score": 78,
  "phases": {
    "secrets": { "status": "done", "findings": 2 },
    "mcp": { "status": "done", "findings": 1 },
    "hooks": { "status": "done", "findings": 0 },
    "deps": { "status": "done", "findings": 3 },
    "config": { "status": "done", "findings": 1 }
  },
  "findings": [
    {
      "id": "SEC-S-01",
      "phase": "secrets",
      "severity": "CRITICAL",
      "title": "Hardcoded credential in src/config.ts:42",
      "file": "src/config.ts",
      "line": 42,
      "status": "open"
    }
  ],
  "history": [
    { "date": "2026-03-20", "grade": "C", "score": 58, "findings": 12 },
    { "date": "2026-04-04", "grade": "B", "score": 78, "findings": 7 }
  ]
}

Smart Next Steps

After the scan completes, recommend follow-up actions based on findings:

Rules

1. Read-only — Never modify project files, only analyze and report
2. No false confidence — If a check cannot be performed (tool missing, file inaccessible), report as INFO, do not skip silently
3. Cross-platform — Use node -e for JSON parsing, not jq. Avoid platform-specific commands
4. Respect .gitignore — Do not scan node_modules/, .git/, dist/, build/, or other excluded directories
5. No network calls — Do not send project data anywhere. All analysis is local
6. Severity accuracy — Do not inflate or deflate severity. Follow the definitions exactly
7. Idempotent — Running the scan twice produces the same result (unless project changed)
8. Example detection — Do not flag obvious placeholder values (YOUR_KEY_HERE, changeme, xxx) as real secrets
9. Privacy — Never log or display actual secret values. Show only pattern match and file location
10. Anti-rationalization — Do not skip checks or reduce severity because the project "seems fine". See _shared/anti-rationalization.md

Files

security-scan/
├── SKILL.md      <- This file
└── skill.json    <- Skill metadata and triggers