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 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?
mkdir -p ~/.claude/skills/security-scan # Save SKILL.md to ~/.claude/skills/security-scan/SKILL.md
- 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.
- 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.
- 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.
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.