| name | security-scan |
| description | 使用 AgentShield 扫描你的 Claude Code 配置(.claude/ 目录),检查安全漏洞、配置错误和注入风险。检查 CLAUDE.md、settings.json、MCP 服务器、hooks 和代理定义。 |
Security Scan Skill(安全扫描技能)
使用 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 ecc-agentshield scan .
什么是 npx? 它是 npm 的包运行器,可以直接运行包而无需安装。
用法
基本扫描
针对当前项目的 .claude/ 目录运行:
npx ecc-agentshield scan
npx ecc-agentshield scan --path /path/to/.claude
npx ecc-agentshield scan --min-severity medium
什么是严重性级别? 它表示问题的危险程度——critical(严重)> high(高)> medium(中)> low(低)。
输出格式
npx ecc-agentshield scan
npx ecc-agentshield scan --format json
npx ecc-agentshield scan --format markdown
npx ecc-agentshield scan --format html > security-report.html
为什么有多种格式? 不同场景需要不同格式——终端适合人看,JSON 适合机器处理。
自动修复
自动应用安全修复(只修复标记为可自动修复的):
npx ecc-agentshield scan --fix
这将:
- 用环境变量引用替换硬编码密钥
- 将通配符权限收紧为范围限定的替代方案
- 永不修改仅限手动的建议
注意: --fix 只修复安全的问题,不会破坏你的配置。
Opus 4.6 深度分析
运行对抗性三代理管道进行更深入的分析:
export ANTHROPIC_API_KEY=your-key
npx ecc-agentshield scan --opus --stream
这运行:
- 攻击者(红队) ——找出攻击向量
- 防御者(蓝队) ——推荐加固措施
- 审计员(最终裁决) ——综合两种观点
什么是对抗性分析? 三个 AI 模拟攻击者和防御者,找出更多潜在问题。
初始化安全配置
从头搭建新的安全 .claude/ 配置:
npx ecc-agentshield init
创建:
settings.json ——带范围权限和拒绝列表
CLAUDE.md ——带安全最佳实践
mcp.json ——占位符
为什么使用 init? 它给你一个安全的起点,避免常见错误。
GitHub Action
添加到你的 CI 管道:
- uses: affaan-m/agentshield@v1
with:
path: '.'
min-severity: 'medium'
fail-on-findings: true
什么是 CI 管道? 持续集成——每次提交代码时自动运行的测试。
严重级别
| 等级 | 分数 | 含义 |
|---|
| A | 90-100 | 安全配置 |
| B | 75-89 | 小问题 |
| C | 60-74 | 需要关注 |
| D | 40-59 | 重大风险 |
| F | 0-39 | 严重漏洞 |
评分系统: 像学校成绩一样,A 是最好,F 是不及格。
解读结果
关键发现(立即修复)
- 配置文件中硬编码的 API 密钥或令牌
- 允许列表中的
Bash(*)(不受限制的 shell 访问)
- 通过
${file} 插值在 hooks 中的命令注入
- 运行 shell 的 MCP 服务器
为什么关键? 这些问题让攻击者完全控制你的系统。
高危发现(生产前修复)
- CLAUDE.md 中的自动运行指令(提示注入向量)
- 权限中缺少拒绝列表
- 代理有不必要的 Bash 访问权限
为什么高危? 这些问题可能导致数据泄露或系统损坏。
中等发现(推荐)
- hooks 中的静默错误抑制(
2>/dev/null、|| true)
- 缺少 PreToolUse 安全 hooks
- MCP 服务器配置中的
npx -y 自动安装
为什么中等? 这些是最佳实践问题,不会立即造成危险。
信息级发现(了解)
- MCP 服务器缺少描述
- 正确标记为良好实践的禁止性指令
为什么信息级? 这些是提醒,帮助你改进配置。
链接
记住:安全扫描应该定期运行,就像定期体检一样。