Appearance
Security Scan Skill 是 Everything Claude Code 生态下的安全审计利器，结合 AgentShield 工具，自动扫描和分析 .claude/ 目录中的配置文件（如 CLAUDE.md、settings.json、MCP servers、hooks、agent 定义等），识别硬编码密钥、权限过宽、命令注入等高危问题，并支持自动修复与多格式输出。它适用于新项目初始化、配置变更、上线前审查和定期安全巡检，是 Claude Code 用户必备的安全保障。
Everything Claude Code Security Scan Skill：用 AgentShield 扫描 .claude/ 目录的安全漏洞与配置错误
在 AI 编程助手（如 Claude Code、Codex、Cursor）逐渐成为主流开发工具的今天，项目配置的安全性直接影响团队和数据的安全。Security Scan Skill 正是为此而生：它通过集成 AgentShield，为你的 .claude/ 目录提供专业级的安全审计与风险修复能力。
相比传统的人工检查配置文件、零散脚本或静态规则，Security Scan Skill 能自动识别多种安全漏洞和配置错误，极大提升了安全防护的系统性和效率。无论你是初次接触 Claude Code，还是在生产环境深度定制，都能从这一 Skill 中受益。
1. 适用场景与触发时机
Security Scan Skill 适用于以下典型场景：
- 新建 Claude Code 项目：初始化
.claude/配置时，确保一开始就采用安全基线。 - 配置变更后：每次修改
settings.json、CLAUDE.md、MCP 配置等关键文件后，及时发现新引入的风险。 - 上线/提交前：在合并 PR、上线前自动扫描，避免安全漏洞流入生产环境。
- 团队 Onboarding：接手已有仓库时，快速了解并修复遗留的安全隐患。
- 定期安全巡检：作为安全合规流程的一部分，周期性运行，持续提升安全水平。
你可以将其集成到本地开发流程、CI/CD 流水线，或通过 Everything Claude Code Hooks 实现自动化触发。
2. 扫描内容与检测能力
Security Scan Skill 能覆盖 .claude/ 目录下的多类配置文件，具体包括：
| 文件/目录 | 检查点示例 |
|---|---|
CLAUDE.md | 是否有硬编码密钥、自动执行指令、提示注入模式 |
settings.json | 过宽的 allow list、缺失 deny list、危险的 bypass 标志 |
mcp.json | 风险 MCP 服务器、硬编码环境变量、npx 供应链风险 |
hooks/ | 命令插值注入、数据外泄、静默错误抑制 |
agents/*.md | 工具权限过宽、提示注入面、缺失模型规格 |
通过这些检查，Skill 能发现从高危漏洞到配置不规范的各类问题。例如，硬编码 API Key、未限制 Bash 权限、命令行插值注入、自动运行指令等。
3. 前置条件与安装
Security Scan Skill 依赖于 AgentShield 工具。你可以通过以下方式检查和安装：
bash
# 检查是否已安装
npx ecc-agentshield --version
# 推荐全局安装
npm install -g ecc-agentshield
# 或者直接使用 npx（无需全局安装）
npx ecc-agentshield scan .建议在团队开发机、CI/CD 环境都配置好 AgentShield，以便随时调用。
4. Step by Step：使用流程详解
步骤 1：基础扫描
在项目根目录下运行以下命令，自动扫描当前 .claude/ 目录：
bash
npx ecc-agentshield scan你也可以指定目录或调整扫描粒度：
bash
# 指定路径
npx ecc-agentshield scan --path /your/project/.claude
# 只显示 medium 及以上严重级别
npx ecc-agentshield scan --min-severity medium步骤 2：选择输出格式
根据需求选择不同的报告格式：
bash
# 默认终端彩色输出
npx ecc-agentshield scan
# 生成 JSON（适合 CI 集成）
npx ecc-agentshield scan --format json
# 生成 Markdown（适合文档归档）
npx ecc-agentshield scan --format markdown
# 生成 HTML 报告
npx ecc-agentshield scan --format html > security-report.html步骤 3：自动修复（Auto-Fix）
对于可自动修复的问题（如硬编码密钥、权限过宽），可直接一键修正：
bash
npx ecc-agentshield scan --fix自动修复会：
- 将硬编码密钥替换为环境变量引用
- 收紧通配符权限
- 不会修改需要人工判断的建议项
步骤 4：深度对抗分析（Opus 4.6 模式）
如需更高安全保障，可启用三代理对抗分析（需配置 ANTHROPIC_API_KEY）：
bash
export ANTHROPIC_API_KEY=your-key
npx ecc-agentshield scan --opus --stream流程包括：
- 红队（攻击者）：主动寻找攻击路径
- 蓝队（防御者）：给出加固建议
- 审计员：综合评估并给出最终结论
步骤 5：安全配置初始化
新项目可用一条命令生成安全基线配置：
bash
npx ecc-agentshield init会自动创建带权限收敛和 deny list 的 settings.json、包含安全最佳实践的 CLAUDE.md 及 mcp.json 模板。
步骤 6：CI/CD 集成
将安全扫描纳入 CI 流程，确保每次提交都自动审计：
yaml
- uses: affaan-m/agentshield@v1
with:
path: '.'
min-severity: 'medium'
fail-on-findings: true5. 结果解读与输出示例
扫描结果会按严重级别（A-F）评分：
| 等级 | 分数区间 | 含义 |
|---|---|---|
| A | 90-100 | 配置安全 |
| B | 75-89 | 轻微问题 |
| C | 60-74 | 需关注 |
| D | 40-59 | 存在重大风险 |
| F | 0-39 | 严重漏洞 |
输出示例（终端彩色报告）：
✔ settings.json: Allow list overly broad [HIGH]
✘ CLAUDE.md: Hardcoded API key found [CRITICAL]
✔ hooks/pre-push.sh: No issues found
Grade: D (score: 55)输出示例（Markdown）：
markdown
| File | Issue | Severity |
|------------------|------------------------------|-----------|
| CLAUDE.md | Hardcoded API key | CRITICAL |
| settings.json | Allow list too broad | HIGH |
| agents/bot.md | Missing model specification | MEDIUM |6. 常见配套 Agent 与 Skill 协作
- 与 Security Reviewer Agent：Security Scan Skill 负责静态配置审计，Security Reviewer Agent 可对代码和业务逻辑做更深层次的安全分析，二者结合实现全栈安全防护。
- 与 Verification Loop Skill：可作为发布前验证循环的一环，自动阻断含高危配置的上线流程。
- 与 Opensource Sanitizer Agent：开源前联合使用，防止敏感信息泄漏和配置残留。
- 与 Hooks：可通过 PreToolUse/PreCommit 等 Hook 自动触发安全扫描，降低人为疏漏。
7. 实践建议与注意事项
- 定期扫描：不要只在项目初始化时用，建议每次配置变更、PR 合并、上线前都运行一次。
- 关注高危项：如发现硬编码密钥、Bash(*) 权限、命令注入等，务必第一时间修复。
- 自动修复≠全部安全：Auto-Fix 只修正可自动处理的问题，部分复杂风险仍需人工判断。
- CI 集成建议：将扫描结果作为 PR 必过项，防止带风险配置进入主分支。
- 结合多 Agent/Skill：利用 ECC 体系的 Verification Loop、Security Reviewer Agent 等，实现全流程安全闭环。
FAQ
Q: Security Scan Skill 与普通 Lint 工具有何不同？
A: 它专为 Claude Code 配置安全而设计，能识别密钥泄漏、命令注入、权限过宽等 AI 项目特有风险，且支持自动修复和深度对抗分析。
Q: 自动修复会覆盖我的自定义配置吗？
A: 只会自动修复明确可安全处理的项（如密钥替换、权限收紧），不会修改需要人工判断或业务相关的配置。
Q: 如何将扫描纳入 CI/CD？
A: 可用官方 GitHub Action 或在流水线中调用 npx ecc-agentshield scan --format json，并根据输出结果自动阻断有风险的提交。