security-scan

Security Scan Skill

Use AgentShield to audit your Claude Code configuration for security issues.

When to activate

When setting up a new Claude Code project
After modifying .claude/settings.json、CLAUDE.md or MCP configuration
Before committing configuration changes
When joining a new repository that has an existing Claude Code configuration
Regular security hygiene checks

Scan targets

File	Check items
`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 environment variable secrets, npx supply chain risks
`hooks/`	Command injection via interpolation, data exfiltration, silent error suppression
`agents/*.md`	Unrestricted tool access, prompt injection attack surface, missing model specification

Prerequisites

AgentShield must be installed. If needed, check and install:

# 检查是否已安装
npx ecc-agentshield --version

# 全局安装（推荐）
npm install -g ecc-agentshield

# 或通过 npx 直接运行（无需安装）
npx ecc-agentshield scan .

Usage

Basic Scan

For the current project's .claude/ directory, run:

# 扫描当前项目
npx ecc-agentshield scan

# 扫描特定路径
npx ecc-agentshield scan --path /path/to/.claude

# 使用最低严重程度过滤进行扫描
npx ecc-agentshield scan --min-severity medium

Output Formats

# 终端输出（默认） — 带有评分的彩色报告
npx ecc-agentshield scan

# JSON — 用于 CI/CD 集成
npx ecc-agentshield scan --format json

# Markdown — 用于文档记录
npx ecc-agentshield scan --format markdown

# HTML — 独立包含的深色主题报告
npx ecc-agentshield scan --format html > security-report.html

Auto-Fix

Automatically apply security fixes (only for items marked as auto-fixable):

npx ecc-agentshield scan --fix

This operation will:

Replace hardcoded secrets with environment variable references
Tighten wildcard permissions into specific-scope alternatives
Never modify items that are manual-suggestion-only

Opus 4.6 Deep Analysis

Run the adversarial three-agent pipeline for deeper analysis:

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

This operation runs:

Attacker (Red Team) — looks for attack vectors
Defender (Blue Team) — recommends hardening measures
Auditor (final verdict) — synthesizes both sides' views

Initialize Secure Config

Build a new secure .claude/ configuration from scratch:

npx ecc-agentshield init

Created content:

With specific permission scopes and a deny list (Deny list), settings.json
In line with security best practices, CLAUDE.md
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

Level	Score	Meaning
A	90-100	Secure configuration
B	75-89	Minor issues exist
C	60-74	Needs attention
D	40-59	Significant risk exists
F	0-39	Critical vulnerabilities exist

Interpreting results

Critical findings (fix immediately)

Hardcoded API keys or tokens (Tokens) in configuration files
The allow list includes Bash(*)(unrestricted Shell access)
Command injection via ${file} interpolation in Hooks
MCP server running Shell

High-risk findings (fix before production deployment)

Auto-run instructions in CLAUDE.md (prompt injection vector)
Missing deny lists in permission settings
Agents have unnecessary Bash access

Medium-risk findings (recommended to fix)

Silent error suppression in Hooks (2>/dev/null，|| true）
Missing PreToolUse security Hooks
In MCP server configuration, npx -y auto-install

Informational findings (for reference only)

MCP server missing description information
Preventive instructions correctly marked as good practice

About this skill