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. 3 段階の分析

フェーズ 1 — コンテキスト調査： コードベース内のセキュリティフレームワーク、ORM、認証ライブラリ、サニタイズパターン、信頼境界を特定します。

フェーズ 2 — 比較分析： 新しいコードを確立されたセキュアなパターンと比較します。逸脱、不整合、新たな攻撃対象領域にフラグを付けます。

フェーズ 3 — 脆弱性評価： 変更された各ファイルについて、以下を確認します。

• 入力検証： SQL インジェクション、コマンドインジェクション、XXE、テンプレートインジェクション、NoSQL インジェクション、パストラバーサル
• 認証と認可： 認証の回避、権限昇格、セッションの不備、JWT の脆弱性
• 暗号とシークレット： ハードコードされたキー／トークン、脆弱なアルゴリズム、不適切なキー保管
• コード実行： デシリアライズによる RCE、pickle／YAML インジェクション、eval インジェクション、XSS
• データ漏えい： 機密データのログ出力、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 Actions との統合

CI 経由で PR のセキュリティ監査を自動実行します。ANTHROPIC_API_KEY と GITHUB_TOKEN が必要です。

セットアップ

pip install -r claudecode/requirements.txt

環境変数

変数	必須	用途
ANTHROPIC_API_KEY	はい	Claude API へのアクセス
GITHUB_TOKEN	はい	PR データ取得のための GitHub API へのアクセス
GITHUB_REPOSITORY	はい	owner/repo 形式
PR_NUMBER	はい	プルリクエスト番号
EXCLUDE_DIRECTORIES	いいえ	スキップするディレクトリをカンマ区切りで指定
ENABLE_CLAUDE_FILTERING	いいえ	FP 除外に Claude API を使用する場合は true
FALSE_POSITIVE_FILTERING_INSTRUCTIONS	いいえ	カスタム除外ルールへのパス
CUSTOM_SECURITY_SCAN_INSTRUCTIONS	いいえ	カスタムスキャンカテゴリへのパス

実行

python claudecode/audit.py

出力は、findings、analysis_summary、filtering_summary を含む JSON です。

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

cwd から findings.json を読み込みます。GITHUB_TOKEN と GITHUB_EVENT_PATH が必要です。

カスタマイズファイルの例

カスタマイズファイルのサンプルは references/ を参照してください。

• references/custom-false-positive-filtering.txt — カスタム FP 除外ルールのテンプレート
• references/custom-security-scan-instructions.txt — カスタムスキャンカテゴリのテンプレート

評価フレームワーク

公開されている任意の PR に対して監査をテストします。

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

結果は ./eval_results/ に、検出結果、実行時間、成功ステータスを含む JSON として保存されます。

スラッシュコマンド

assets/security-review-command.md を任意のプロジェクトの .claude/commands/security-review.md にコピーすると、Claude Code で /security-review を使用できるようになります。

主な原則

1. 誤検知を最小限にする — 悪用可能性が 80% を超えると確信できる問題のみを報告します
2. ノイズを省く — 理論上の問題、スタイルに関する懸念、影響の小さい検出結果は報告しません
3. 影響に注目する — 不正アクセス、データ侵害、システムの侵害を優先します
4. 新たな問題のみを対象にする — 既存のセキュリティ上の懸念についてコメントしません
5. 誤検知を大量に出すより、理論上の問題を見逃すほうが望ましい

重大度のガイドライン

• HIGH：直接悪用可能 → RCE、データ侵害、認証の回避
• MEDIUM：特定の条件が必要ですが、影響は重大です
• 重大度が LOW の検出結果は報告しないでください