Skip to main content
Agent skill

Security Scan

Scan your Claude Code configuration (.claude/ directory) for security vulnerabilities, misconfigurations, and injection risks using AgentShield. Checks CLAUDE.md, settings.json, MCP servers, hooks, and agent definitions. Use when auditing a .claude/ directory — CLAUDE.md, settings.json, MCP servers, hooks, or agent definitions.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Security Scan when an AI agent needs a reusable SKILL.md workflow for this job: Scan your Claude Code configuration (.claude/ directory) for security vulnerabilities, misconfigurations, and injection risks using AgentShield. Checks CLAUDE.md, settings.json, MCP servers, hooks, and agent definitions. Use when auditing a .claude/ directory — CLAUDE.md, settings.json, MCP servers, hooks, or agent definitions.

When not to use it

Skip Security Scan when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/security-scan
# Save SKILL.md to ~/.claude/skills/security-scan/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/security-scan/SKILL.md. For a shared project, commit the folder at .claude/skills/security-scan/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Security Scan skill for this task: Use Security Scan when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Security Scan Skill

Audit your Claude Code configuration for security issues using [AgentShield](https://github.com/affaan-m/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:

```bash # 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:

```bash # 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

```bash # 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):

```bash 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:

```bash # 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:

```bash 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:

```yaml - 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

- **GitHub**: [github.com/affaan-m/agentshield](https://github.com/affaan-m/agentshield) - **npm**: [npmjs.com/package/ecc-agentshield](https://www.npmjs.com/package/ecc-agentshield)

Intended uses

  • Use Security Scan when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.