code-security-audit

代码安全审计

使用 AI 对代码变更进行安全审计，并过滤误报。基于 claude-code-security-review。

捆绑资源

claude-code-security-review/
├── SKILL.md                          # This file — workflow and instructions
├── action.yml                        # GitHub Actions composite action definition
├── claudecode/                       # Python package (imports: from claudecode.*)
│   ├── __init__.py                   # Package init — re-exports main entry points
│   ├── audit.py                      # Entry point — wraps github_action_audit
│   ├── github_action_audit.py        # GitHub Action audit runner (PR fetch, Claude runner, filter pipeline)
│   ├── prompts.py                    # Security audit prompt templates
│   ├── findings_filter.py            # Hard exclusion rules + Claude API false positive filtering
│   ├── claude_api_client.py          # Claude API client for single-finding analysis
│   ├── json_parser.py               # Robust JSON extraction from text (code blocks, nested braces)
│   ├── constants.py                  # Config: model name, timeouts, token limits, exit codes
│   ├── logger.py                     # Stderr logging with GitHub context prefix
│   ├── requirements.txt              # Python deps: anthropic, requests, PyGithub
│   └── evals/                        # Evaluation framework
│       ├── run_eval.py               # CLI: python -m claudecode.evals.run_eval owner/repo#123
│       └── eval_engine.py            # Git worktree management + SAST runner
├── scripts/                          # Standalone scripts (non-Python-package)
│   └── comment-pr-findings.js        # Node.js script to post findings as PR review comments
├── references/                       # Knowledge loaded into context as needed
│   ├── false-positive-filtering.md   # 20 hard exclusions, signal quality criteria, 12 precedents
│   ├── custom-scan-instructions.md   # Industry templates (compliance, finserv, e-commerce, GraphQL)
│   ├── custom-false-positive-filtering.txt   # Example custom FP filtering rules
│   └── custom-security-scan-instructions.txt # Example custom scan categories
└── assets/                           # Files used in output
    └── security-review-command.md    # Claude Code /security-review slash command template

手动审计工作流

直接审计代码变更时使用（不使用 CI 脚本）。

1. 收集变更

git diff --merge-base origin/main        # Branch diff
git diff --cached                         # Staged changes
git diff HEAD~N                           # Last N commits
git diff --name-only origin/main...       # List modified files

2. 三阶段分析

**阶段 1 — 上下文调研：**识别代码库中的安全框架、ORM、身份验证库、清理模式和信任边界。

**阶段 2 — 对比分析：**将新代码与已确立的安全模式进行比较。标记偏差、不一致之处和新的攻击面。

**阶段 3 — 漏洞评估：**检查每个已修改的文件，关注以下方面：

• **输入验证：**SQL 注入、命令注入、XXE、模板注入、NoSQL 注入、路径遍历
• **身份验证与授权：**绕过身份验证、权限提升、会话缺陷、JWT 漏洞
• **加密与密钥：**硬编码的密钥/令牌、弱算法、不当的密钥存储
• **代码执行：**通过反序列化、pickle/YAML 注入、eval 注入、XSS 实现 RCE
• **数据泄露：**日志记录敏感数据、违反 PII 规定、API 泄露、调试信息暴露

追踪从用户输入到敏感操作的数据流。留意跨越权限边界的情况。

3. 过滤误报

加载 references/false-positive-filtering.md 并应用所有规则。为每个发现项分配 1–10 的置信度；只保留置信度 ≥ 8 的发现项。

对于特定领域的类别，加载 references/custom-scan-instructions.md。

4. 输出格式

# Vuln N: [Category]: `file.ts:42`

* Severity: HIGH | MEDIUM
* Confidence: 8/10
* Description: [What the vulnerability is]
* Exploit Scenario: [Concrete attack path]
* Recommendation: [Specific fix]

GitHub Action 集成

通过 CI 在 PR 上运行自动化安全审计。需要 ANTHROPIC_API_KEY 和 GITHUB_TOKEN。

设置

pip install -r claudecode/requirements.txt

环境变量

变量	必需	用途
ANTHROPIC_API_KEY	是	访问 Claude API
GITHUB_TOKEN	是	访问 GitHub API 以获取 PR 数据
GITHUB_REPOSITORY	是	owner/repo 格式
PR_NUMBER	是	Pull request 编号
EXCLUDE_DIRECTORIES	否	要跳过的目录，以逗号分隔
ENABLE_CLAUDE_FILTERING	否	设为 true 以使用 Claude API 过滤误报
FALSE_POSITIVE_FILTERING_INSTRUCTIONS	否	自定义过滤规则的路径
CUSTOM_SECURITY_SCAN_INSTRUCTIONS	否	自定义扫描类别的路径

运行

python claudecode/audit.py

输出为 JSON，包含 findings、analysis_summary 和 filtering_summary。

GitHub Actions 工作流

name: Security Review
permissions:
  pull-requests: write
  contents: read
on:
  pull_request:
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 2
      - uses: anthropics/claude-code-security-review@main
        with:
          comment-pr: true
          claude-api-key: ${{ secrets.CLAUDE_API_KEY }}

PR 评论

将发现项作为行内审查评论发布：

node scripts/comment-pr-findings.js

从当前工作目录读取 findings.json。需要 GITHUB_TOKEN 和 GITHUB_EVENT_PATH。

自定义文件示例

参见 references/ 中的自定义文件示例：

• references/custom-false-positive-filtering.txt — 自定义误报过滤规则模板
• references/custom-security-scan-instructions.txt — 自定义扫描类别模板

评估框架

针对任意公开 PR 测试审计：

export ANTHROPIC_API_KEY=sk-...
python -m claudecode.evals.run_eval owner/repo#123 --verbose

结果以 JSON 格式保存到 ./eval_results/，包含发现项、运行时间和成功状态。

斜杠命令

将 assets/security-review-command.md 复制到任意项目的 .claude/commands/security-review.md，即可在 Claude Code 中启用 /security-review。

核心原则

1. 尽量减少误报 — 仅标记可利用性置信度 >80% 的问题
2. 跳过噪声 — 不报告理论问题、风格问题或影响较低的发现项
3. 关注影响 — 优先处理未授权访问、数据泄露和系统失陷
4. 仅报告新问题 — 不评论已有的安全问题
5. 宁可遗漏理论问题，也不要用误报刷屏

严重性指南

• **高：**可直接利用 → RCE、数据泄露、绕过身份验证
• **中：**需要特定条件，但影响重大
• 不要报告低严重性的发现项