velimattiv/claude-security-audit

# /security-audit — Claude Code 技能 [](https://github.com/velimattiv/claude-security-audit/actions/workflows/ci.yml) [](https://github.com/velimattiv/claude-security-audit/actions/workflows/codeql.yml) [](LICENSE) 一个专为 [Claude Code](https://code.claude.com) 设计的彻底、多阶段的安全审计技能。 它超越了常规的漏洞扫描，通过枚举每一个攻击面（HTTP、gRPC、GraphQL、WebSocket、队列消费者、无服务器处理程序、移动端/桌面端 IPC——跨 60 多种框架的 polyglot 架构），运行基于 OWASP 方法论标记的扫描器套件，并执行 9 个并行的深度挖掘类别（Auth/Authz、IDOR/BOLA、Token Scope、MITM、Crypto、Secrets、Deployment、Injection/SSRF、LLM-specific）。 **支持的运行时：** 仅限 Claude Code。不支持其他运行环境。 ## 版本 - **v2.0.6** (当前版本) — 修复了 Path B 冒烟测试中 DinD 探针的 `:ro,z` SELinux 问题（探针曾将 SELinux 限制误判为 DinD 阻断，导致每位 Fedora / RHEL / CentOS 贡献者得到令人误解的 PASS-WITH-LIMITATIONS 退出状态）。 - **v2.0.5** — Phase 4 ↔ Path B 包装器集成。 该技能现在会在主机扫描器未在 PATH 中（或设置 `$AUDIT_FORCE_PATH_B=1` 时）真正使用容器包装器。 填补了 v2.0.2-2.0.4 中 Path B 半成品的空缺。 还包括包装器加固（`$AUDIT_CONTAINER_RUNTIME` 覆盖，`docker build --load`，`--build` 在构建后退出）以及 `run-e2e-test.sh --path-b` 标志。 - **v2.0.4** — `install-scanners.sh` 中修复了大小写不敏感的校验和匹配（修复了因 hadolint 供应商发布其 `.sha256` 文件内容为小写，而资产 URL 使用大写字母 `L` 的 `Linux` 所导致的静默安装失败）。 - **v2.0.3** — Path B Containerfile 修复 (PEP 668) + 回归测试门禁 (`tests/e2e/test-path-b-build.sh`)。 - **v2.0.2** — 技能内置工件指令（不使用外部 `--append-system-prompt`）；E2E PASS 测试基于 juice-shop@v19.2.1，匹配 12/12 个测试夹具，474 个发现，60 个独特的 CWE。 参见 `docs/test-runs/e2e-full-run-v2.0.2-2026-04-25T0250Z.md`。 - **v2.0.0** — 完整的 polyglot 审计，9 个深度挖掘类别，6 个必需 + 6 个条件性扫描器，SARIF + SBOM + 增量模式基线。 设计规范详见 `docs/V2-SCOPE.md`。 - **v2.1 候选版本** — 列于 `docs/ROADMAP.md` 中。 ## 功能特性 1. **发现** — 构建项目地图：语言、框架、单仓拓扑、ORM 模式、PII 列、LLM SDK 使用情况、信任区域（Phase 0）。 2. **分区** — 将仓库拆分为审计分区并进行风险排序，以便将深度挖掘的算力预算投入到最重要的地方（Phase 1）。 3. **盘点攻击面** — 不仅仅是 HTTP 路由：还包括队列、调度器、webhook、文件上传、无服务器架构、移动端/桌面端 IPC、管理员/调试端点（Phase 2）。 4. **基石索引** — 那些被修改后会导致级联失效的文件（Phase 3）。 5. **并行运行扫描器套件** — semgrep, osv-scanner, gitleaks, trufflehog, trivy, hadolint；根据检测到的上下文可选 brakeman, checkov, kube-linter, govulncheck, psalm, zizmor。全部输出 SARIF（Phase 4）。 6. **深度挖掘 9 个类别** — 每个类别都作为 Claude Opus 4.7 的子代理，按分区 × 类别进行扇出执行（Phase 5）。 7. **配置审计与方法论骨架** — CORS/CSP/cookies/headers 以及 ASVS L2 / API Top 10 / LLM Top 10 / LINDDUN / STRIDE（Phase 6）。 8. **综合** — 去重、交叉引用、排序，并使用 OWASP / CWE 方法论 ID 进行标记。生成人类可读的 Markdown 报告、SARIF 2.1.0 和 CycloneDX SBOM（Phase 7）。 9. **基线** — 持久化存储，以便在 PR 时进行少于 1 分钟的增量模式重新审计（Phase 8）。 典型运行时间：15–60 分钟（完整模式）或 2–5 分钟（存在基线后的增量模式）。 ## 安装 用户级别（在每个项目中可用），固定到特定标签的发布版本： ``` git clone --depth 1 --branch v2.0.6 \ https://github.com/velimattiv/claude-security-audit.git ~/Code/claude-security-audit cp -R ~/Code/claude-security-audit/skills/security-audit ~/.claude/skills/security-audit cat ~/.claude/skills/security-audit/VERSION # → 2.0.2 ``` 项目级别（仅限当前仓库）： ``` git clone --depth 1 --branch v2.0.6 \ https://github.com/velimattiv/claude-security-audit.git /tmp/csa mkdir -p .claude/skills cp -R /tmp/csa/skills/security-audit .claude/skills/security-audit ``` 如需分步安装指南（包括备份已有的 `security-audit` 技能、冒烟测试、完整的端到端验证、故障排除和卸载），请参阅 **[`docs/INSTALL.md`](docs/INSTALL.md)**。 ## 扫描器前置条件 该技能自带六个安全工具（semgrep、osv-scanner、gitleaks、trufflehog、trivy、hadolint）及其规则数据库。**推荐的部署方式是在一个独立的容器内运行整个审计过程——包括 Claude Code、该技能、扫描器以及项目克隆。** 这样可以保持你的日常主机环境整洁，并与 CI/生产环境的隔离级别保持一致。 ### 推荐 — 独立容器（所有内容均在内部运行） 使用任何能为你提供干净工作环境的容器，需包含 `git`、Node 20+、Python 3.10+，以及运行 `claude` 的方法。常见模式： - **VS Code Dev Container / GitHub Codespaces** — 在 `.devcontainer/devcontainer.json` 中声明 `git`/`claude`/`python3`，打开项目，在内部运行扫描器安装程序和审计。 - **`cw` 启动器 / 类似的基于 tmux 的容器启动器** — 每次审计启动一个全新的容器，在内部安装所有内容，完成后销毁容器。 - **原生 Docker / Podman** — 使用 `docker run --rm -it` 运行基础镜像，安装依赖项，以只读方式挂载项目。 在独立容器内： ``` # Clone 审计目标到容器内部 git clone /workspace/target # 安装 Claude Code (https://docs.anthropic.com/claude-code/install) # 并仅在此容器实例内进行身份验证 claude login # 在容器内部以用户级别安装该 skill git clone --depth 1 --branch v2.0.6 \ https://github.com/velimattiv/claude-security-audit.git ~/Code/csa cp -R ~/Code/csa/skills/security-audit ~/.claude/skills/security-audit # 安装扫描器捆绑包（路径 A — 直接安装）。这是 # 适用于隔离容器的正确安装模型：扫描器是 # 容器用途的一部分，宿主机环境污染无需顾虑。 bash ~/Code/csa/scripts/install-scanners.sh # 运行审计 cd /workspace/target claude --dangerously-skip-permissions > /security-audit ``` 审计完成后，整个容器即可被弃用——包括身份验证信息、扫描器二进制文件和任何缓存的规则数据库。不会发生任何数据泄漏到你的主机。 ### 可接受 — Path B（仅扫描器在容器内，Claude 在主机上） 如果你确实希望 Claude 运行在你的日常主机上（例如，你已经在那里安装并认证了 Claude Code，且审计只是一次性操作），Path B 仅隔离扫描器套件： ``` scripts/run-audit-in-container.sh --build # one-time scripts/run-audit-in-container.sh preflight # verify scripts/run-audit-in-container.sh scan semgrep # per-scanner runs ``` 包装器使用 Podman（首选，无 root 权限）或 Docker。容器加固包括：`--cap-drop=ALL`、`--security-opt=no-new-privileges`、`--read-only` rootfs、非 root 的 `audit` 用户。目标仓库以只读方式绑定挂载；仅 `.claude-audit/` 目录可写。 这仍然会将 Claude Code 留在你的主机上。技能编排器（orchestrator）会在那里运行，且构成了更大的信任边界。 ### 强烈不建议 — 在日常主机上使用 Path A ``` scripts/install-scanners.sh # only if you really mean it ``` 在你的笔记本电脑上安装六个安全工具会带来侵入性的主机状态变更，而这个工具可能每周只运行一次。扫描器会自动更新其检测数据库——这意味着你为了检查安全性而安装的安全工具会持续对主机造成变动。除非你真的别无选择，否则请使用上述的独立容器模式。 如果你确实选择此路线：不要只安装一半。部分安装（存在部分扫描器，缺少部分扫描器）比完全不安装更糟糕——审计报告不会告诉你哪些扫描器协同验证的类别被静默跳过了。运行 `scripts/install-scanners.sh --check` 来验证这六个工具是否全部安装成功；如果其中任何一个失败，请彻底修复问题后重新运行。 支持的主机环境：macOS (Homebrew)、Debian/Ubuntu (apt)、Fedora (dnf)、Arch (pacman)。**不支持** Windows —— 请使用 WSL 或独立容器模式。 **Path B 无法隔离的内容。** 该技能的编排器（`workflow.md`）、深度挖掘子代理（Phase 5）、内置审查子代理（Phase 4 的 `/security-review`、对抗性审查）以及综合模块（Phase 7）全部运行在 Claude Code 所使用的任何运行时环境中。请将 Path B 视为“沙盒化的扫描器”，而非“沙盒化的审计”。 ### 必需的扫描器套件（六个，均输出 SARIF，免费 / 开源） - **semgrep** — polyglot SAST，社区规则集。 - **osv-scanner** — 跨所有清单生态系统的 SCA。 - **gitleaks** — 检查工作树 + git 历史中的 secrets。 - **trufflehog** — 已验证的 secret 扫描。 - **trivy** — IaC + Dockerfile + 漏洞 + SBOM。 - **hadolint** — Dockerfile lint。 条件性添加（根据上下文按需安装）：brakeman (Rails)、checkov (Terraform 较多时)、kube-linter (Kubernetes)、govulncheck (Go 可达性)、psalm (PHP taint)、zizmor (GitHub Actions)。 如果缺少任何扫描器，该技能会打印降级模式警告，并继续使用已安装的组件。**绝不会**因缺少扫描器而硬性报错失败。 ## 使用方法 在 Claude Code 中，使用以下命令调用： ``` /security-audit # full audit /security-audit mode: delta # requires baseline /security-audit scope: "services/api" # narrow to a path /security-audit categories: "crypto,mitm,secrets" # run only named deep-dives /security-audit mode: report # re-emit from artifacts /security-audit top_n: 12 # override partition cap ``` 报告将生成在 `docs/security-audit-report.md`（如果项目中已存在 BMAD 输出目录，则为 `_bmad-output/implementation-artifacts/security-audit-report.md`）。 ## CI 集成 请参见 `docs/ci-examples/github-actions/security-audit.yml` 获取有效示例：在 push / PR / 每日夜间构建时运行，将 SARIF 上传到 Security 选项卡，并在发现 CRITICAL 级别问题时导致 PR 失败。适配到 GitLab / Buildkite / CircleCI 的方法是机械相似的；欢迎提交 PR。 ## 运行时状态 该技能将其工作状态写入项目根目录下的 `.claude-audit/` 目录中。请将 `.claude-audit/` 添加到项目的 `.gitignore` 中（该技能在首次运行时会主动提示执行此操作）。增量模式的基线存储在两个地方：精简版 `docs/security-audit-baseline.json`（需提交至版本控制）和完整版 `.claude-audit/baseline.json`（被 gitignore 忽略）。 ## 故障排除 有关常见问题（扫描器安装、网络受阻的漏洞库、semgrep 自动与显式规则集、增量模式陈旧、SARIF 上传被拒），请参见 `docs/TROUBLESHOOTING.md`。 ## 许可证与归属 - 本技能：MIT（参见 `LICENSE`）。 - `skills/security-audit/vendored/adversarial-review/` 下的对抗性审查提示词是从 [bmad-method](https://github.com/bmad-code-org/BMAD-METHOD) 由 BMad Code, LLC 基于 MIT 许可证原样引入的未修改版本。 - `skills/security-audit/lib/cwe-map.json` 基于 CC BY 4.0 许可证复现了 MITRE Common Weakness Enumeration 中的 CWE ID 和名称。 - `skills/security-audit/lib/asvs-l2.md` 引用了 OWASP ASVS 5.0 类别主题（规范文本位于 https://github.com/OWASP/ASVS）。 - 完整的逐文件归属和扫描器套件许可证透明度请参见 `NOTICE.md`。 - CodeQL **默认被排除**，因为其 CLI 许可证仅限于经 OSI 批准的 OSS 仓库。符合条件的仓库用户可以手动启用它；请参见 `NOTICE.md` 和条件性扫描器文档。

标签：AI安全, BOLA, Chat Copilot, CISA项目, Claude Code, CodeQL, DAST, DevSecOps, DLL 劫持, Docker, GitHub Actions, GraphQL, gRPC, IDOR, LLM防护, MITM, SARIF, SAST, SSRF, StruQ, Token安全, WebSocket, Web截图, 上游代理, 中间人攻击, 代码安全扫描, 依赖分析, 动态应用安全测试, 多语言代码审计, 多阶段安全测试, 大语言模型, 威胁模型, 安全评估工具, 安全防御评估, 容器安全, 密码学安全, 密钥安全, 恶意软件分析, 攻击面枚举, 无服务器安全, 注入攻击, 盲注攻击, 私有化部署, 自动化安全合规, 自动笔记, 请求拦截, 越权访问, 跨站请求伪造, 身份验证与授权, 防御规避, 静态应用安全测试