security-scan

Security Scan 是一个对 Claude Code 配置进行安全审计的技能，使用 AgentShield 检查 .claude/ 目录中的安全漏洞、错误配置和注入风险。

用途

该技能用于审计 Claude Code 项目的配置安全。适用时机包括：搭建新的 Claude Code 项目、修改 .claude/settings.json 或 CLAUDE.md 或 MCP 配置之后、提交配置更改之前、接手带有现有 Claude Code 配置的新仓库时，以及进行周期性的安全卫生检查。

主要能力

扫描范围覆盖以下文件：

CLAUDE.md：检查硬编码密钥、自动运行指令、提示注入模式。
settings.json：检查过于宽松的允许列表、缺失的拒绝列表、危险的绕过标志。
mcp.json：检查有风险的 MCP 服务器、硬编码环境变量密钥、npx 供应链风险。
hooks/：检查通过插值产生的命令注入、数据外泄、静默错误抑制。
agents/*.md：检查不受限的工具访问、提示注入面、缺失的模型规格。

前置条件

需要先安装 AgentShield。检查与安装命令如下：

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

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

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

使用方式

基本扫描：

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

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

# 按最低严重级别过滤扫描
npx ecc-agentshield scan --min-severity medium

输出格式：

# 终端输出（默认）— 彩色报告并带有评级
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

自动修复（仅修复标记为可自动修复的项目）：

npx ecc-agentshield scan --fix

该命令会将硬编码密钥替换为环境变量引用，把通配符权限收紧为限定范围的替代方案，并且不会修改仅可手动处理的建议。

Opus 4.6 深度分析

运行对抗式三智能体流程进行更深入的分析（需要 ANTHROPIC_API_KEY）：

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

该流程依次运行：攻击方（红队）寻找攻击向量；防御方（蓝队）提出加固建议；审计方（最终裁定）综合双方观点。

初始化安全配置

从头搭建一个新的安全 .claude/ 配置：

npx ecc-agentshield init

会创建：带有范围化权限和拒绝列表的 settings.json、包含安全最佳实践的 CLAUDE.md、mcp.json 占位文件。

GitHub Action

可加入 CI 流程：

- uses: affaan-m/agentshield@v1
  with:
    path: '.'
    min-severity: 'medium'
    fail-on-findings: true

严重级别与评级

A（90-100）：配置安全。
B（75-89）：存在小问题。
C（60-74）：需要关注。
D（40-59）：存在显著风险。
F（0-39）：存在严重漏洞。

结果解读

严重发现（立即修复）：配置文件中硬编码的 API 密钥或令牌；允许列表中的 Bash(*)（不受限的 shell 访问）；hooks 中通过 ${file} 插值产生的命令注入；运行 shell 的 MCP 服务器。

高危发现（生产前修复）：CLAUDE.md 中的自动运行指令（提示注入向量）；权限中缺失拒绝列表；智能体拥有不必要的 Bash 访问权限。

中危发现（建议处理）：hooks 中的静默错误抑制（2>/dev/null、|| true）；缺少 PreToolUse 安全钩子；MCP 服务器配置中的 npx -y 自动安装。

信息级发现（知悉）：MCP 服务器缺少描述；被正确标记为良好实践的禁止性指令。

技能介绍

用途