╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║
║                                                                           ║
║             Autonomous Offensive/Defensive Research Framework             ║
║             Based on Claude Code (v3.1.0)                                 ║
║                                                                           ║
║             Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake)    ║
║             Michael Bargury, John Cartwright                              ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣤⣤⣀⣀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⣿⣿⠿⠿⠟
⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣀⣀⣀⣤⣴⣶⣶⣶⣤⣿⡿⠁⠀⠀⠀
⣀⠤⠴⠒⠒⠛⠛⠛⠛⠛⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⣿⣿⣿⡟⠻⢿⡀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⢿⣿⠟⠀⠸⣊⡽⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⣿⡁⠀⠀⠀⠉⠁⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⠿⣿⣧⠀ Get them bugs.....⠀⠀⠀⠀⠀

`raptor` ランチャーはセッションを開始するための推奨方法であり、どのディレクトリからでも動作します -- RAPTOR のインストール先を解決し、起動したディレクトリを記憶し（そのため `/scan` などのコマンドはデフォルトでそこを対象とします）、事前の信頼性チェックとプロジェクトチェックを実行し、カバレッジ追跡プラグインを読み込み、Claude Code に引き渡す前に環境をサニタイズします。また、オプションのターゲットパスや `--project`、`--continue`、`--model` などのフラグも受け付けます -- `raptor --help` を参照してください。

リポジトリディレクトリ内から素の `claude` を実行することもできます -- Claude Code はチェックアウトから RAPTOR の設定を読み取ります -- ただし、上記のランチャーが行うすべての処理がスキップされます: 事前チェックなし、カバレッジ追跡なし、そして「これを実行したディレクトリ」をデフォルトとするコマンドはそれを見ることができません。

**重要:** RAPTOR はリポジトリディレクトリから設定を読み込みます。他のディレクトリから `claude` を実行すると、RAPTOR ではなく素の Claude Code が起動します。`raptor` ランチャーはこの失敗モードを完全に回避します。

### オプション 2: コンテナ内で実行する（推奨）

コンテナの使用は、エージェントがファイルシステムのアクセスされたくない領域にアクセスするのを制限し、実行される可能性のある悪意のあるコード（サプライチェーン攻撃などによるもの）の影響範囲を限定する、一般的なセキュリティプラクティスです。イメージは大容量（約 6 GB）です。Microsoft Python 3.12 devcontainer をベースに、静的解析、ファジング、ブラウザ自動化ツールを追加しています。

ビルド済みイメージをプルできます:```bash
docker pull danielcuthbert/raptor:latest

このイメージは、起動時に RAPTOR フレームワーク（このリポジトリ）が `/workspaces/raptor` にマウントされることを想定しています。オプションで、ローカル分析用のターゲットフォルダをマウントできます。

コンテナを起動するには:```bash
docker run -it \
  -v "$(pwd):/workspaces/raptor" \
  raptor:latest

`rr` 決定論的デバッガーが必要な場合は `--privileged` を追加してください。

VS Code devcontainers もサポートされています。対象フォルダーをマウントするには、`.devcontainer/devcontainer.json` の `mounts` セクションに追加してください:```jsonc
"mounts": [
  // ...existing entries...
  "source=/path/to/target-folder,target=/workspaces/target,type=bind,consistency=cached"
]

いずれにせよ、コンテナ内に入ったら `raptor` を実行して始めてください。

---

## 初回実行時に予想されること

最も簡単にできること:```
/scan /path/to/code

これにより、パイプライン全体が実行されます。スキャン、重複排除、そして各検出結果を検証ステージ（A-F）に通します。約50件の検出結果がある中規模のコードベースでは、10〜30分と、分析レイヤーのLLMコストとして$2〜$8（モデルによる）を見込んでください。デフォルトのコスト上限は1回の実行あたり$10です。`--max-cost-usd`で調整できます。

**コストに関する注意:** Claude Codeのオーケストレーション層は、あなたのClaudeサブスクリプションを使用します。分析ディスパッチ層は、トークン単位で課金される別のLLM API呼び出しを行います。分析モデルとしてClaude Codeのみを使用する場合（デフォルト）、サブスクリプション以外の追加コストは発生しません。外部モデル（OpenAI、Geminiなど）を設定した場合、それらのAPI呼び出しは各プロバイダーに課金されます。

---

## セキュリティモデル

RAPTORはLLMが生成したコードを実行し、信頼できないリポジトリを分析します。信頼できないコンテンツを扱うサブプロセスは、Linux名前空間、Landlock、seccompを使用してサンドボックス化されます。サンドボックスはネットワークアクセスをブロックし、ファイルシステムの可視性を制限し、リソース消費を制限します。完全な脅威モデルと設定については`docs/sandbox.md`を参照してください。

ランチャーチェーンにコードを注入する可能性のある環境変数は、起動時に除去されます（`core/security/_dangerous_env_strip.sh`）。スキャン対象リポジトリからのファイルパスは、シェル文字列に補間されることはありません。すべてのサブプロセス呼び出しはリストベースの引数を使用します。

---

## RAPTORにできること

| コマンド | 機能 | ステータス |
|---------|-------------|--------|
| `/agentic` | 完全自律ワークフロー: スキャン、検証、エクスプロイト、パッチ | 安定 |
| `/scan` | SemgrepとCodeQLによる静的解析 | 安定 |
| `/understand` | 攻撃対象領域のマッピング、データフローの追跡、脆弱性バリアントの探索 | 安定 |
| `/binary` | ブラックボックスバイナリ調査、ランタイム証拠、グラフクエリとハンドオフ | ベータ |
| `/ghidra` | Ghidra REブリッジ: `.gpr`プロジェクトのアタッチ/インポート、バージョン間diff、検出結果のエクスポート | ベータ |
| `/audit` | 仮説駆動型、ツールに基づく体系的なコードレビュー | ベータ |
| `/review` | 監査状態のクエリ: 検出結果、ギャップ、カバレッジ、オペレーターノート | 安定 |
| `/annotate` | 関数ごとの自由形式の散文注釈（オペレーターレビューノート）を添付 | 安定 |
| `/validate` | 多段階のエクスプロイト可能性検証パイプライン（ステージ0-F） | 安定 |
| `/diagram` | `/understand`と`/validate`のJSON出力からMermaidビジュアルマップを生成 | ベータ |
| `/codeql` | SMTデータフロープレスクリーニングを伴うCodeQL専用の深層分析 | 安定 |
| `/analyze` | 再スキャンせずに、既存のSARIF検出結果をLLMで分析 | 安定 |
| `/openant` | OpenAnt LLMソースコードスキャン: AST分析と関数ごとのLLM推論 | ベータ |
| `/sca` | ソフトウェア構成分析: 依存関係、アドバイザリ、サプライチェーンシグナル、SBOM、修正 | ベータ |
| `/cve-diff` | OSV、NVD、GitHub、GitLabを横断してCVEの修正コミットを発見しdiffを取得 | ベータ |
| `/cve-env` | CVEの影響を受けるアプリケーションをパッチ前バージョンで実行するDocker環境を構築・検証 | 実験的 |
| `/exploit` | 概念実証エクスプロイトコードを生成 | ベータ |
| `/patch` | 確認された脆弱性に対する安全なパッチを生成 | ベータ |
| `/fuzz` | AFL++によるバイナリファジングとクラッシュ分析 | 安定 |
| `/crash-analysis` | C/C++クラッシュに対する自律的な根本原因分析 | 安定 |
| `/oss-forensics` | GitHubリポジトリに対する証拠に基づくフォレンジック調査 | 安定 |
| `/project` | 実行を整理し、検出結果を経時的に追跡するための名前付きワークスペース | 安定 |
| `/describe` | ターゲットの記述: 言語構成、ビルドシステム、ツールのギャップ、コスト見積もり（読み取り専用） | 安定 |
| `/threat-model` | プロジェクトごとの脅威モデルの作成、検査、保守 | 安定 |
| `/sage` | 永続メモリ層（保存、想起、リンク、裏付け） | 安定 |
| `/ask` | 設定された任意のLLMモデルに自由形式のプロンプトを送信 | 安定 |
| `/scorecard` | 意思決定クラスごとのモデル別信頼性を検査 | 安定 |
| `/frida` | Fridaによる動的インストルメンテーション | アルファ |
| `/web` | Webアプリケーションスキャン: クロール、ffuf/nuclei統合、オラクル検証済みインジェクション、ブラインドSSRFコールバック | ベータ |

---

## パイプラインの仕組み

まずプロジェクトを作成して、すべての実行を1か所にまとめます:```
/project create myapp --target /path/to/code   # create a project first
/project use myapp                             # set it as active
/understand --map                              # map the attack surface
/agentic --threat-model --validate             # map, model, scan, validate
/project findings                              # review everything in one place

`/understand` は、スキャンが一行も実行される前に、エントリポイント、信頼境界、シンクのコンテキストマップを構築します。次に `/agentic` が Semgrep と CodeQL を実行し、検出結果を重複排除し、exploitation-validator の方法論を用いて検証のために各検出結果をディスパッチします:

`--threat-model` を指定すると、RAPTOR はまずマップを実行し、プロジェクトにまだ存在しない場合は `threat-model.json` と `THREAT_MODEL.md` を作成し、そのコンパクト版を `/understand`、自律分析、`/validate` に供給します。既存のプロジェクト脅威モデルは、`--threat-model-refresh` を渡さない限り保持されます。古いフォールバックマップは、明示的に `--threat-model-use-stale` を渡さない限り拒否されます。また、マップされた未チェックのフローを候補 SARIF に変換するため、スキャナーの見逃しが実行を止めることはありません。これはオペレーターが所有するコンテキストであり、魔法の証明ではありません。検出結果には依然としてコードの証拠またはオラクルに裏付けられた確認が必要です。`docs/threat-model.md` を参照してください。

- ステージ A: そのパターンは実際に脆弱性なのか、それともツールのパターンマッチングによるノイズなのか?
- ステージ B: 攻撃者がそこに到達するには何が必要で、何が妨げになるのか?
- ステージ C: そのコードパスは実際に存在するのか? 外部から到達可能か?
- ステージ D: 最終判断 -- これはテストコードか、非現実的な前提条件が必要か、モデルは曖昧に逃げていないか?
- ステージ E: バイナリエクスプロイトの実現可能性 (コンパイル済み成果物が利用可能な場合)
- ステージ F: 自己レビュー -- 以前のステージのいずれかが曖昧に逃げたり矛盾したりしていないか?

検証を通過した検出結果には、エクスプロイト PoC とパッチが生成されます。最後にクロス検出分析が実行され、共通の根本原因と攻撃チェーンが特定されます。

`/validate` は、以前のスキャンからすでに検出結果がある場合、この同じパイプラインをスタンドアロンのステップとして実行します。

コンパイル済み成果物に対して、`/binary <path>` は、生のリバースエンジニアリング成果物の山をオペレーターに投げつけるのではなく、証拠優先の調査を実行するようになりました。その内部では依然として、ファイルメタデータ、インポート、radare2 の xref から、SHA-256 に紐付けられたマニフェスト、証拠台帳、コンテキストマップ、チェックリスト、SQLite グラフを構築します。Mach-O アプリはスライスインベントリ、バンドルメタデータ、Objective-C / Swift クラスセレクタも取得します。価値の高い擬似コードは、実行中に消えるのではなく永続化されます。PE DLL エクスポート、Windows ドライバディスパッチャ、Linux カーネルモジュールの ioctl ハンドラも、それぞれ独自の侵入候補として扱われ、PE アーキテクチャは推測ではなく COFF ヘッダから読み取られます。その後、調査レイヤーがそのグラフをクエリし、汎用的なシンクの手がかりより外部侵入を優先してランク付けし、宣言されたヘルパー/兄弟バイナリを発見し、事実、構造的推論、未証明の仮説に分割されたコンパクトなレポートを書き出します。Frida の観察、ファズクラッシュの証人、明示的な Z3 チェック、バイナリ diff は、後でより強力な証拠を追加できます。RAPTOR はまた、境界付けられた侵入からパーサーへの候補を復元するために必要な内部コールグラフを保持するため、アプリのコールバックを、`XML_Parse`、`d2i_X509`、`jpeg_read_header`、または別の実際のパーサーサーフェスを実際に呼び出す内部関数に絞り込むことができ、それをテイントの証明であるかのように偽ることはありません。`/binary trace-parser <run-dir>` は明示的な動的フォローオンです: 狭い Frida パーサートレースを実行し、その後、同じコンテキストマップ、ハンドオフ、グラフ、調査レポートをその場で更新します。`/binary investigate --active` はまずマップし、具体的なハーネス境界が存在する場合にのみ実際のファズキャンペーンを起動します。アプリ、DLL、ドライバのターゲットには代わりにハーネスまたはスナップショットのステップが与えられます。`/binary harness` は、選択された侵入に対する証拠に裏付けられたハーネス仕様を書き出し、ABI または IOCTL コントラクトが明示されている場合にのみ候補ソースを出力します。「`memcpy` が存在する」から「これは悪用可能だ」へと言いくるめることはありません: インポート、セレクタ、コールエッジは、何かが機械的に証明するまで候補のままです。`docs/binary-analysis.md` を参照してください。

---

## ソフトウェア構成分析

`/sca` はプロジェクトの依存関係とサプライチェーン側を分析します。これは単なる requirements ファイルの CVE 検索ではありません: RAPTOR はマニフェスト、ロックファイル、インラインインストールコマンド、ワークフロー依存関係、コンテナ/ベースイメージのパッケージソースを発見し、それらを単一の依存関係ビューに正規化します。

スキャンは、OSV アドバイザリ、CISA KEV、EPSS、CISA Vulnrichment/SSVC、到達可能性、エクスプロイト証拠シグナル、衛生チェック、サプライチェーンヒューリスティック、ライセンスポリシー検出結果、およびオプションの LLM レビュー/トリアージで依存関係を強化します。RAPTOR ネイティブの検出結果に加えて、SBOM と CI フレンドリーな出力を生成します:

- `findings.json` - 正規の RAPTOR 検出結果
- `report.md` - 人間が読めるサマリー
- `sbom.cdx.json` - VEX データを含む CycloneDX SBOM
- `findings.sarif` - GitHub/GitLab コードスキャン出力

一般的なコマンド:```bash
python3 raptor.py sca --repo /path/to/project
python3 raptor.py sca --repo /path/to/project --no-llm
python3 raptor.py sca --repo /path/to/project --fail-on-severity high --fail-on-kev
python3 raptor.py sca --repo /path/to/project fix
python3 raptor.py sca check PyPI django 4.2.10

キャッシュが一度構築されると、スキャナはパック ID をローカルファイルに解決し、ネットワーク呼び出しは発生しません。キャッシュがない場合、RAPTOR はスキャン時に semgrep.dev からレジストリパックを取得しようとします。オフラインの場合、キャッシュされていないパックを適切にスキップし、カスタムルールのみで実行します。

CodeQL は、CLI とクエリパックをダウンロードする初期セットアップ時にのみネットワークアクセスを必要とします。一度インストールされれば、オフラインで実行されます。

---

## カスタムルール

RAPTOR には 200 を超えるカスタム静的解析ルールが同梱されており、誤検知を排除するために敵対的テストが施されています:

- **Semgrep (約 150 ルール)** — Python、Go、Java、JS/TS 向けのテイント追跡およびパターンルール。SQLi、XSS、SSRF、SSTI、コマンドインジェクション、デシリアライゼーション、XXE、LDAP/NoSQL インジェクション、パストラバーサル、オープンリダイレクト、ログ/ヘッダーインジェクション、eval インジェクション、ReDoS、プロトタイプ汚染、JWT の設定ミス、弱い暗号、安全でない TLS、ハードコードされたシークレットをカバーします。
- **Coccinelle (68 ルール)** — C/C++ 向けの構造的マッチング。メモリ安全性 (二重解放、use-after-free、非ベースポインタの解放、スタック配列の解放、mmap されたメモリ、use-after-close)、整数バグ (オーバーフロー、符号拡張、二重 sizeof)、リソースリーク (popen/fclose の不一致、fdopendir の二重クローズ)、バッファ処理 (NUL なしの strncpy、copy_user のサイズ不一致、malloc/strlen のオフバイワン)、シグナルハンドラの安全性、API の誤用 (fcntl フラグドメイン、SIGKILL/SIGSTOP、二重バイトスワップ、inet_ntoa 静的バッファ)、コンパイラのデッドストア除去、カーネルの IS_ERR/PTR_ERR 混同、フォーマット文字列インジェクション、TOCTOU 競合など。
- **CodeQL (8 クエリ)** — C++ (フォーマット文字列インジェクション、整数切り捨て、use-after-move、イテレータ無効化) および Java (XXE、安全でないデシリアライゼーション、ログインジェクション、Spring SSRF) 向けの手続き間テイント追跡。

ルールを直接閲覧できます: `engine/semgrep/rules/`、`engine/coccinelle/rules/`、`engine/codeql/queries/`。これらは RAPTOR が取り込む Semgrep レジストリパック (`p/security-audit`、`p/owasp-top-ten`、`p/secrets` は常時、加えて `p/command-injection`、`p/jwt`、`p/xss` などのポリシーグループ別パック) を補完します — 重複は最小限です。

---

## RAPTOR が自身をチェックする方法

RAPTOR は自身のセキュリティツールの多くをドッグフーディングしていますが、実際に PR をブロックするものと、単に私たちを律するためにバックグラウンドで実行されるものを正直に区別する価値があります。これらの中にはハードゲート、スケジュールされたチェック、そして物事を悪化させたときに気づけるように維持しているベンチマークもあります。実際のパラメータやチェックの再現方法を含む詳細な内訳は `docs/ci-controls.md` にあります。

| コントロール | チェック内容 | トリガー | 設定 / エビデンス |
|---|---|---|---|
| Ruff | Python の正確性リンティング (`F401`、`F811`、`F821`、`F841`) | PR diff ゲート、加えて週次の全ツリー監査 | `pyproject.toml`、`.github/workflows/lint.yml` |
| Pytest | 高速なユニット/統合境界、サブシステム固有のティア (import-graph ディスパッチ経由)、プロンプトエンベロープ監査 | PR、`main` へのプッシュ、マージキュー、スケジュールされたフルスイート | `pytest.ini`、`.github/workflows/tests.yml`、`.github/workflows/nightly.yml` |
| CodeQL Advanced | import-graph スコープ絞り込みによる Python、C/C++、GitHub Actions のコードスキャン | PR、`main` へのプッシュ、マージキュー、週次スケジュール | `.github/workflows/codeql.yml`、`.github/codeql/codeql-config.yml` |
| ワークフローの堅牢化 | SHA ピン留めされたサードパーティ Actions、最小権限のパーミッション、コマンドメタデータのリンティング | すべてのワークフロー変更とすべての lint 実行 | `.github/workflows/`、`.github/scripts/check_command_metadata.py` |
| コーパスラベル lint | 監査コーパスラベルスキーマの検証とアップストリームピンの検証 | PR (変更されたラベル)、週次の全スイープ | `.github/workflows/corpus-labels.yml` |
| RAPTOR SCA PR ゲート | PR によって導入された依存関係およびサプライチェーンのリグレッション | マニフェスト / ロックファイル / ワークフローの変更 | `.github/workflows/sca-pr-gate.yml` |
| RAPTOR SCA セルフバンプ | 機械的な依存関係の堅牢化と安全なアップグレード提案 | 週次スケジュール、手動実行 | `.github/workflows/sca-self-bump.yml` |
| SCA 侵害コーパス | 既知の依存関係侵害が依然として期待されるシグナルをトリガーするかどうか | 週次スケジュール、関連する PR 変更 | `test/data/sca-e2e/compromise-corpus/`、`.github/workflows/sca-compromise-check.yml` |
| リポジトリ不変条件検出器 | デッドコード / 誤った呼び出しの検出、環境変数ドキュメントのドリフト、語彙リストのガードレール、正規 JSON バイト形式、オプション依存の import lint | PR ゲート (`lint.yml` の `repo-invariants` ジョブ)、加えて日次スイープ | `.github/workflows/lint.yml`、`.github/workflows/miswiring-scan.yml`、`.github/scripts/*_baseline.json` |
| SCA キャリブレーション + ストレスコーパス | リスクスコアリングとパーサカバレッジが時間とともにドリフトするかどうか | 週次 / 月次のスケジュールジョブ | `packages/sca/data/calibration/`、`.github/workflows/refresh-sca-calibration.yml`、`.github/workflows/sca-stress-sweep.yml` |
| データフローコーパス | バリデータ動作の精度 / 再現率 / FP カテゴリの追跡 | 開発者実行のベンチマークとコーパステスト | `core/dataflow/corpus/`、`core/dataflow/scripts/corpus-metrics` |
| CI コントロールドキュメントガード | 文書化されたパスが存在し、ruff 設定が一致し、README がドキュメントにリンクしていること | PR | `.github/tests/test_ci_controls_docs.py` |

現在強制されていないもの: `mypy` は `pyproject.toml` にピン留めされていますが、何もブロックしません。Ruff フォーマットは強制されていません。Semgrep は RAPTOR のスキャナサーフェスの一部ですが、RAPTOR を RAPTOR でスキャンする専用の Semgrep ワークフローはまだありません。

---

## 別の LLM の使用

RAPTOR には 2 つの別個のモデルレイヤーがあり、何かを変更する前に両方がどのように機能するかを知っておく価値があります。

**オーケストレーションレイヤー** は Claude Code です — ただし対話型の `raptor` シェル (この会話型のスラッシュコマンドレイヤー) のみです。CLAUDE.md、スキル、コマンドはすべてそこで Claude Code の指示として実行されます。そのレイヤーをオーケストレーションする Claude モデルを変更するには、Claude Code の `--model` フラグまたはセッション内の `/model` コマンドを使用します。このレイヤーをまったく使いたくない場合は、以下の [完全スタンドアロンでの実行](#running-fully-standalone-no-claude-code) を参照してください。

**分析ディスパッチレイヤー** は、個々の脆弱性所見を分析する LLM です。これはオーケストレーションレイヤーとは別であり、サポートされている任意のプロバイダを使用できます。`~/.config/raptor/models.json` で設定します:```json
{
  "models": [
    {
      "provider": "anthropic",
      "model": "claude-opus-4-6",
      "api_key": "sk-ant-...",
      "role": "analysis"
    },
    {
      "provider": "openai",
      "model": "gpt-5.4",
      "api_key": "sk-...",
      "role": "analysis"
    },
    {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "api_key": "sk-ant-...",
      "role": "aggregate"
    }
  ]
}

モデルの役割を使うと、異なるタスクに異なるモデルを割り当てられます：

| 役割 | 実行内容 |
|------|-------------|
| `analysis` | 各検出結果を検証・分析する（ステージA-F） |
| `code` | エクスプロイトPoCとパッチコードを書く |
| `consensus` | 真陽性に対するセカンドオピニオン投票 |
| `aggregate` | オプション。決定論的なマルチモデル相関の上にLLMが書いたナラティブ統合を加え、`aggregation.json`と最終的な`agentic-report.md`に書き込む |
| `fallback` | プライマリモデルが失敗した場合、またはレート制限に達した場合に使用される |

役割が設定されていない場合、リストの最初のモデルがすべてを処理します。マルチモデル
ソースコード分析では、2つ以上の`analysis`モデルを設定してください — デフォルトで
決定論的な相関が得られます。`aggregate`役割はオプションで、その上に
LLMが書いたサマリーを追加します：```bash
python3 raptor.py agentic --repo /code \
  --model claude-opus-4-6 \
  --model gpt-5.4 \
  --aggregate claude-sonnet-4-6

Ollama は分析には適しています。エクスプロイト／パッチコード生成における信頼性は、ローカルモデルに固定された特性ではなく、モデルの規模と量子化に連動します — LLM ガイドの [Quality Tradeoffs](https://github.com/gadievron/raptor/blob/main/llm.md#quality-tradeoffs) を参照し、`/scorecard` で自分の特定のモデルが実際に何を測定しているかを確認してください。

### 完全スタンドアロンでの実行（Claude Code なし）

`bin/raptor` -- バナーとスラッシュコマンドを備えたインタラクティブシェル、つまりこの会話レイヤー -- は Claude Code CLI に直接 exec し、常に独自のログインを必要とします。しかしその下にある実際の仕組みはそうではありません。`python3 raptor.py <mode>` は Claude Code に一切依存しない、素の Python CLI です。```bash
# No `claude` process involved at any point
python3 raptor.py doctor                        # status check -- explicitly "no claude needed"
python3 raptor.py agentic --repo /path/to/code   # scan -> dedup -> analysis
python3 raptor.py scan --repo /path/to/code

`models.json` / `OLLAMA_HOST` をローカルの Ollama インスタンス（上記参照）に向ければ、このパス全体が Anthropic と通信することはありません -- エアギャップ環境やローカル専用ハードウェアで有用です。会話型のスラッシュコマンドレイヤー（このチャット）は失われますが、スキャン／解析／エクスプロイトのパイプライン自体は影響を受けません。

### 高速ティアのショートサーキット + モデルスコアカード

解析ティアのモデルに同一プロバイダーのより安価な兄弟モデル（Anthropic Opus → Haiku、OpenAI 5.x → 4o-mini、Gemini Pro → Flash-Lite、Mistral Large → Small）がある場合、RAPTOR はそれをサブストレートに接続するコンシューマー（現在は codeql、SCA などは今後のフォローアップで対応）のプレフィルターとして使用します。安価なモデルがショートサーキットするのは**確信度の高い誤検知**のみです。曖昧なケースと確信度の高い真陽性は常に完全な解析を実行します。信頼は `(model, decision_class)` セルごとに蓄積されます — RAPTOR は安価モデルと完全解析の一致を記録し、そのセルの見逃し率の Wilson 95% 上限が 5% 以下になった時点でのみショートサーキットします。

自分のモデルが何を得意としているかを確認するには、`/scorecard` を使用します（または直接: `libexec/raptor-llm-scorecard list`）。スコアカードはグローバル（レッスンはプロジェクトをまたいで引き継がれる）で、`out/llm_scorecard.json` に永続化されます。

---

## プロジェクト

プロジェクトがない場合、各実行は `out/` 配下に独自のタイムスタンプ付きディレクトリを取得します。プロジェクトがある場合、すべてが 1 か所にまとまり、マージされた検出結果、カバレッジ追跡、実行間の差分が得られます。```bash
/project create myapp --target /path/to/code -d "Short description"
/project use myapp

/scan
/understand --map
/validate

/project status                # all runs, pass/fail, timestamps
/project findings              # merged findings across all runs
/project findings --detailed   # per-finding detail
/project coverage --detailed   # which files were reviewed
/project diff myapp run1 run2  # compare two runs
/project report                # full merged report
/project clean --keep 3        # remove old runs, keep the last 3
/project export myapp /tmp/myapp.zip
/project none                  # clear active project

分割により、CI パイプラインから Python レイヤーを実行して（`python3 raptor.py scan --repo ...`）Claude Code なしで構造化された SARIF 出力を得ることも、完全なエージェントワークフローで対話的に実行することもできます。

---

## OSS フォレンジック

`/oss-forensics` は、複数のソースからの証拠を用いて公開 GitHub リポジトリを調査します。GitHub API、GH Archive（BigQuery 経由の不変イベント履歴）、Wayback Machine、およびローカルの git 履歴です。証拠収集から仮説形成、最終的なフォレンジックレポートに至るまで、構造化されたパイプラインを実行します。

BigQuery アクセスには `GOOGLE_APPLICATION_CREDENTIALS` が必要です。詳細は `.claude/commands/oss-forensics.md` を参照してください。

---

## エキスパートペルソナ

8 つのエキスパートペルソナをオンデマンドで利用できます。所見や特定のテクニックについて異なる視点が欲しいときに、1 つをロードしてください：```
Exploit Developer (Mark Dowd)                  Exploit PoC generation
Crash Analyst (Charlie Miller / Halvar Flake)  Crash analysis and exploitability assessment
Security Researcher                            General adversarial code review
Patch Engineer                                 Secure fix generation
Penetration Tester                             Realistic attack scenario assessment
Web Researcher (James Kettle)                  Web endpoint research (smuggling, cache poisoning, SSRF)
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption

`/web`、Z3、SAGE、およびクラウドプロバイダーSDKをオプションの追加機能として維持することで、デフォルトのRAPTORインストールが必要以上に重く、壊れやすくなるのを避けられます。