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

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

`bin/` を PATH に追加するか（または `bin/raptor` を PATH 上のどこかにシンボリックリンクする）、任意のディレクトリから `raptor` を実行できます。ランチャーが RAPTOR のインストール先を解決し、作業ディレクトリを自動的に設定します。

**重要:** RAPTOR はリポジトリディレクトリから設定を読み込みます。別のディレクトリから `claude` を実行すると、RAPTOR ではなくプレーンな Claude Code が起動します。まずリポジトリに `cd` するか、`raptor` ランチャーを使用してください。

### Option 2: Devcontainer（推奨）

すべてのものがプリインストールされています。VS Code で **Dev Containers: Open Folder in Container** を使用して開くか、プリビルドイメージをプルしてください：```bash
docker pull danielcuthbert/raptor:latest
docker run --privileged -it -v "$(pwd):/workspaces/raptor" danielcuthbert/raptor:latest

`--privileged` フラグは `rr` 決定論的デバッガに必要です。イメージは大きいです（約6GB）。Microsoft Python 3.12 devcontainer をベースに、静的解析、ファジング、ブラウザ自動化ツールを追加しています。

コンテナ内に入ったら、"hi" と入力して始めるか、直接コマンドを実行してください。

---

## 初回実行時の期待

最も簡単な操作は次のとおりです：```
/scan /path/to/code

これにより完全なパイプラインが実行されます：スキャン、重複排除、そして各発見事項を検証段階（A-F）に送信します。中規模のコードベースで約50件の発見がある場合、分析レイヤーのLLMコストはモデルに応じて10〜30分、2〜8ドル程度かかります。デフォルトのコスト上限は実行あたり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の機能

| Command | 機能 | 状態 |
|---------|-------------|--------|
| `/agentic` | 完全自律ワークフロー：スキャン、検証、エクスプロイト、パッチ | 安定 |
| `/scan` | SemgrepおよびCodeQLによる静的解析 | 安定 |
| `/understand` | 攻撃対象領域のマッピング、データフローの追跡、脆弱性バリアントのハンティング | 安定 |
| `/binary` | ブラックボックスバイナリ調査、ランタイムエビデンス、グラフクエリとハンドオフ | ベータ |
| `/validate` | 多段階悪用可能性検証パイプライン（ステージ0-F） | 安定 |
| `/codeql` | SMTデータフロープリスクリーニングによるCodeQL限定の詳細解析 | 安定 |
| `/sca` | ソフトウェア構成分析：依存関係、勧告、サプライチェーンシグナル、SBOM、修正 | ベータ |
| `/exploit` | 概念実証エクスプロイトコードの生成 | ベータ |
| `/patch` | 確認された脆弱性に対するセキュアなパッチの生成 | ベータ |
| `/fuzz` | AFL++によるバイナリファジングとクラッシュ分析 | 安定 |
| `/crash-analysis` | C/C++クラッシュの自律的な根本原因分析 | 安定 |
| `/oss-forensics` | GitHubリポジトリのエビデンスに基づくフォレンジック調査 | 安定 |
| `/project` | 名前付きワークスペースで実行を整理し、経時的に発見事項を追跡 | 安定 |
| `/threat-model` | プロジェクトごとの脅威モデルの作成、検査、維持 | 安定 |
| `/sage` | 永続メモリレイヤー（保存、呼び出し、リンク、確証） | 安定 |
| `/frida` | Fridaを介した動的インストルメンテーション | アルファ |
| `/web` | Webアプリケーションスキャン | アルファ/スタブ |

---

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

まずプロジェクトを作成して、すべての実行を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 を実行し、発見事項を重複排除して、それぞれをエクスプロイテーション検証手法を使用して検証に送ります。

`--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 チェック、バイナリ差分は、後でより強力な証拠を追加できます。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` は、プロジェクトの依存関係とサプライチェーン側を分析します。単なる要件ファイルの 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とクエリパックをダウンロードするためにのみネットワークアクセスが必要です。インストール後はオフラインで動作します。

---

## Custom rules

RAPTORには185のカスタム静的解析ルールが同梱されており、敵対的テストにより偽陽性を排除しています。

- **Semgrep (123ルール)** — Python、Go、Java、JS/TS向けの 汚染追跡とパターンルール。SQLi、XSS、SSRF、SSTI、コマンドインジェクション、デシリアライゼーション、XXE、LDAP/NoSQLインジェクション、パストラバーサル、オープンリダイレクト、ログ/ヘッダーインジェクション、evalインジェクション、ReDoS、プロトタイプ汚染、JWTの設定ミス、弱い暗号、安全でないTLS、ハードコードされたシークレットをカバーしています。
- **Coccinelle (54ルール)** — C/C++向けの構造マッチング。メモリ安全性（double free、use-after-free、非ベースポインタの解放、スタック配列の解放、mmap'dメモリ、use-after-close）、整数バグ（オーバーフロー、符号拡張、double 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/`。これらはレジストリパック（`p/security-audit`、`p/owasp-top-ten`、`p/0xdea`、`p/trailofbits`）を補完し、さらに約950のルールを提供します。重複は最小限です。

---

## Using a different LLM

RAPTORには2つの独立したモデルレイヤーがあり、何かを変更する前に両方の動作を理解しておくことが重要です。

**オーケストレーションレイヤー**は常にClaude Codeです。CLAUDE.md、スキル、コマンドはすべてClaude Codeの指示として実行されます。RAPTORをオーケストレーションするClaudeモデルを変更するには、Claude Codeの`--model`フラグまたはセッション内の`/model`コマンドを使用します。

**分析ディスパッチレイヤー**は、個々の脆弱性の発見を分析する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"
    }
  ]
}

モデルロールを使うと、異なるモデルを異なるタスクに割り当てることができます：

| Role | 説明 |
|------|-------------|
| `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は分析には使えるが、エクスプロイトコードやパッチコードは信頼性に欠ける。コード生成タスクには、フロンティアモデルを使用すること。

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

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

モデルが得意とすることを確認するには、`/scorecard`を使用する（または直接: `libexec/raptor-llm-scorecard list`）。スコアカードはグローバルであり（教訓はプロジェクト間で共有される）、`out/llm_scorecard.json`に永続化される。

---

## Projects

プロジェクトがない場合、各実行は`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 forensics

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

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

---

## Expert personas

7つのエキスパートペルソナをオンデマンドで利用できます。調査結果や特定のテクニックについて別の視点が必要な場合に、1つをロードしてください。

1. `@designer` - フロントエンド、UI/UX、CSS、デザインシステム
2. `@ml-engineer` - 機械学習、PyTorch、Transformers、ファインチューニング
3. `@devops` - CI/CD、Docker、Kubernetes、Terraform、可観測性
4. `@performance` - プロファイリング、最適化、メモリ、並列実行
5. `@security` - OWASP、SAST、DAST、依存関係スキャン
6. `@data-engineer` - ETL、Spark、dbt、データレイク、ストリーミング
7. `@sre` - 信頼性、SLI、SLO、エラーバジェット、インシデント分析```
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
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption