security-scan

安全扫描技能

使用 AgentShield 审计您的 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 .

使用方法

基本扫描

针对当前项目的 .claude/ 目录运行：

# 扫描当前项目
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

运行：

1. 攻击者（红队）——寻找攻击向量
2. 防御者（蓝队）——推荐加固措施
3. 审计者（最终裁决）——综合双方观点

初始化安全配置

从头搭建新的安全 .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 安全 hooks
• MCP 服务器配置中的 npx -y 自动安装

信息发现（知晓即可）

• MCP 服务器缺失描述
• 禁止性指令被正确标记为良好实践

链接

• GitHub: github.com/affaan-m/agentshield
• npm: npmjs.com/package/ecc-agentshield