oma-deepsec

Deepsec：エージェント駆動の脆弱性スキャナードライバー

スケジューリング

目標

対象リポジトリ内で Vercel の deepsec セキュリティスキャナーを、安全かつコストを意識して運用します。.deepsec/ ワークスペースを初期化し、的を絞った INFO.md を作成して、適切なスキャン／処理／トリアージ／再検証／エクスポートの手順を実行します。process --diff を使って CI で PR をゲートし、プロジェクト固有のマッチャーを拡充しながら、過剰な支出を防ぎ、実際の再検証済みの検出結果を提示します。

インテントシグネチャ

• ユーザーが deepsec、「deep security scan」、「bunx deepsec」、「pnpm deepsec」、「npx deepsec」に言及している。
• ユーザーがエージェントにリポジトリの脆弱性、セキュリティ上の問題、または CVE のスキャンを依頼しており、プロジェクトに .deepsec/ ディレクトリがある、または作成すべきである。
• ユーザーが deepsec による PR／CI セキュリティゲートの追加方法や、process --diff、--diff-staged、--diff-working、--files-from、--comment-out について尋ねている。
• ユーザーが deepsec の成果物に言及している：INFO.md、SETUP.md、data/<id>/files/、FileRecord、RunMeta、revalidation、triage、カスタムマッチャー、MatcherPlugin、noiseTier、priorityPaths。
• ユーザーが deepsec の設定について尋ねている：deepsec.config.ts、defaultAgent、AI_GATEWAY_API_KEY、VERCEL_OIDC_TOKEN、AI Gateway、Vercel Sandbox、--agent codex、--agent claude。
• ユーザーが deepsec のコスト削減、誤検出率の低減、重大度／トリアージ／再検証の判定の解釈方法について尋ねている。

使用する場合

• リポジトリへの deepsec の初回インストール（init、INFO.md の作成、初回の調整スキャン）。
• 完全スキャンまたは範囲を限定したスキャンの実行と、検出結果の処理。
• process --diff と --comment-out を使った、PR ごとの CI ゲートの設定。
• デフォルトのセットでは対象にならないエントリーポイントをカバーする、プロジェクト固有のマッチャーの作成。
• 検出結果のバックログのトリアージ（重大度による分類、revalidate による誤検出の削減、課題トラッカーへのエクスポート）。
• deepsec の不具合の診断：認証情報の不足、AI Gateway のクォータによる停止、拒否、サンドボックス認証。

使用しない場合

• deepsec を使わない一般的な OWASP／リンター形式のレビュー → oma-qa を使用します。
• 一般的な CVE／依存関係のアドバイザリ → oma-qa または oma-search を使用します。
• deepsec ではない新規 SAST パイプラインの設計 → oma-architecture を使用します。
• アプリケーションコード自体の作成または監査 → oma-backend／oma-frontend／oma-mobile に振り分けます。
• クラウド／IAM／Terraform の強化 → oma-tf-infra を使用します（deepsec は IaC のスキャンのみを行い、修正はそちらで扱います）。
• 検出結果のプロダクトコード上の修正についての推論のみ → deepsec が検出結果を生成した後に oma-debug を使用します。

期待される入力

• target_repo_root：スキャン対象のコードベースの絶対パス（.deepsec/ の親ディレクトリ）。
• intent：setup | scan | pr-review | matchers | triage | config | troubleshoot のいずれか。
• credential_mode：ai-gateway-key | vercel-oidc | direct-anthropic | direct-openai | subscription。
• agent_choice：ユーザーが指定したバックエンド、設定済みの defaultAgent、または委任された範囲内で選択します。重要な選択が未解決の場合に限り、確認します。
• severity_floor：提示する最低重大度（通常は HIGH）。
• 任意項目：既存の .deepsec/data/<id>/、deepsec.config.ts、カスタムマッチャー、CI プロバイダー。

期待される出力

• 対象リポジトリに紐付けられた、動作可能な .deepsec/ ワークスペース。
• 内容が記入された data/<id>/INFO.md（50～100 行、プロジェクト固有、行番号なし）。
• コストの再現可能な記録を添えた、1 回以上の完了済み scan → process（→ triage／revalidate）実行。
• PR モードの場合：2 ジョブに分割した process --diff <base> を使う CI ワークフローファイル（PR コードのジョブでは PR への書き込みを行わない）。
• マッチャーの場合：deepsec.config.ts のインラインプラグインを通じて接続された、新しい .deepsec/matchers/<slug>.ts ファイル。
• 検出結果のエクスポート（md-dir および／または json）と、重大度の高い検出結果および誤検出率に関する簡潔な概要。
• 約 25 ドルを超える可能性がある作業を開始する前に、金額と時間を明示した計画。

依存関係

• Node.js 22+ とパッケージマネージャー：bun / bunx（このモノレポでは推奨）、pnpm、npm、または yarn。
• 有効な AI 認証情報：AI_GATEWAY_API_KEY=vck_…、または VERCEL_OIDC_TOKEN、または ANTHROPIC_AUTH_TOKEN と ANTHROPIC_BASE_URL の直接指定、またはログイン済みの claude / codex CLI サブスクリプション。
• Git（revalidate と --diff モードでは履歴を参照します）。
• 任意：deepsec sandbox … の分散実行に使用する Vercel Sandbox 認証情報。
• resources/ 以下の参照リソース（シナリオで必要な場合にのみ読み込まれます）。

制御フロー機能

• intent に応じて分岐します（setup、scan、pr-review、matchers、triage、config、troubleshoot）。
• リポジトリのサイズに応じて分岐します（大規模な処理を始める前に --limit 50 で調整します）。
• 認証情報の取得元に応じて分岐します（gateway key、OIDC、direct、subscription）。
• クォータやクレジットが尽きた場合は停止し、補充後に同じコマンドを再開します。
• 調整を行っておらず、リポジトリが大規模な場合は、上限のない process の起動を拒否します。
• コードベースを読み取り、.deepsec/ ファイルと CI 設定を書き込み、長時間稼働する AI プロセスを実行します。

構造的なフロー

開始

1. .deepsec/ がすでに存在するか確認します。存在する場合は、初期化をやり直さず、増分実行として扱います。
2. ユーザープロンプトから intent を特定します。「このリポジトリをスキャンして」のように曖昧な場合は、まず setup、次に scan（調整モード）を実行します。
3. AI 処理を行う前に、ソースファイル数（node_modules、.git、dist を除外した概算の rg --files | wc -l）を数えて規模を推定し、コストを見積もります。
4. 選択された認証モードとバックエンドを特定します。必要な環境設定、または既存の claude / codex サブスクリプションへのログイン状態を確認します。秘密情報を表示してはいけません。有効なサブスクリプションセッションでは、API キーの環境変数は不要です。AI の呼び出し前に、不足している設定のみを解決します。
5. ../_shared/core/execution-policy.md 以下の既存の指示と設定から、バックエンド、対象範囲、支出を特定します。有料作業またはカスタム対象範囲の作業を行う前に、実際に承認、制限、または却下された内容を resources/decision-records.md に記録します。バックエンドが設定済みでも、追加支出が承認されたことにはなりません。重要な選択肢が不足している場合や、新たな承認が必要な場合にのみ確認します。

遷移

• .deepsec/ がなく、意図にスキャンが含まれる場合 → bunx deepsec init（または npx deepsec init）を実行し、AI 処理の前に、表示されたプロンプトに従って INFO.md を記入します。
• INFO.md が空、またはテンプレートのままの場合 → 内容を記入します（50～100 行、プロジェクト固有の内容、各セクションに例を 3～5 件、行番号なし、一般的な CWE の列挙なし）。
• リポジトリが 500 ファイルを超え、調整がまだ行われていない場合 → まず調整処理を実行します（deepsec のドキュメントでは --limit 50 --concurrency 5 を推奨）。全体処理の前に、コストの推定値を報告します。
• process / revalidate の実行がクォータ不足で停止した場合 → ファイルロックはそのまま維持し、正確な解決用 URL を提示して、補充後に同じコマンドを再実行します。
• エージェントが拒否（refused: true）を報告した場合 → その報告を黙って無視してはいけません。対象ファイルを記録し、別のバックエンドで再試行するか、再現性がある場合に限り、そのパスを config.json:ignorePaths に追加します。
• ユーザーが CI ゲートを希望する場合 → 2 ジョブ構成を出力します（PR コードのジョブには pull-requests: write を付与せず、コメント用ジョブでは PR コードを実行しません）。
• ユーザーがマッチャーのカバレッジ拡大を希望する場合 → data/<id>/files/ と親リポジトリのエントリポイントを対象に、マッチャー作成ワークフローを実行します。

失敗と復旧

失敗	復旧方法
Missing AI credentials for --agent claude / codex	resources/config.md に従って、選択したモードを確認してください。キー／OIDC／直接接続モードでは環境設定を、サブスクリプションモードでは CLI へのログインを確認します。有効なサブスクリプションセッションに .env.local の認証情報を要求しないでください。
ゲートウェイからの 401 Unauthorized	OIDC の場合：vercel env pull を再実行します（有効期限は 12 h）。API キーの場合：再生成します。.env.local が deepsec の実行元の cwd にあることを確認してください。
Stopped: AI Gateway credits exhausted	表示された URL からクレジットを追加し、同じコマンドを再実行します。処理済みのファイルはスキップされます。
Stopped: Claude Pro/Max subscription exhausted	AI Gateway に切り替えます。サブスクリプションではフルスキャンを実行できません。
単一ファイルで拒否が継続する（バッチの 5% 超）	パスを data/<id>/config.json:ignorePaths に追加するか、--batch-size 1 でそのファイルだけを実行します。
HIGH+ で FP 率が高すぎる	revalidate --min-severity HIGH を実行し、INFO.md の脅威モデルと FP に関する注記を詳しくし、マッチャーを precise に寄せます。
100k ファイルのリポジトリで noisy マッチャーがスキャナーを停止させる	filePatterns を言語またはディレクトリに限定した glob に絞り込みます。
サンドボックス認証に失敗する	OIDC の場合：vercel env pull を再実行します。アクセストークンモードの場合：VERCEL_TOKEN、VERCEL_TEAM_ID、VERCEL_PROJECT_ID を確認します。
フルパスの費用が既存のスコープまたは支出承認を超える	調整済みの見積もりを報告し、完了済みの無料／制限付き作業を保持します。不足している承認だけを解決し、実行前に、実際に承認・制限・却下されたパスを記録します。

終了

• 成功：計画したパスを実行し、判定済みの検出結果がある（または検出結果がない）こと、書き込んだファイルの一覧、残りの費用／フォローアップを明示します。
• 部分的な成功：一部のパスが認証情報／クォータ／拒否によってブロックされた場合、ブロック要因、安全に再開するコマンド、推奨する次のステップを報告します。
• 失敗：破壊的な操作は何も行われず、作業を再開するための次のコマンドをユーザーに正確に提示します。

論理操作

ツールとユーティリティ

• パッケージマネージャー：bun / bunx（推奨）、pnpm、npm、yarn は相互に置き換えて使用できます。
• CLI コマンド：deepsec init、init-project、scan、process、process --diff、triage、revalidate、enrich、report、export、metrics、status、sandbox <cmd>。
• PR モードの差分ソース：--diff <ref|range>、--diff-staged、--diff-working、--files <csv>、--files-from <path>（または標準入力の場合は -）。
• 調査：アドホックな重大度／TP クエリには data/<id>/files/**/*.json に対する jq を使用します。
• 認証情報：AI_GATEWAY_API_KEY、VERCEL_OIDC_TOKEN、ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL、OPENAI_API_KEY / OPENAI_BASE_URL、claude login、codex login。
• resources/ 内のセットアップ、スキャン、PR レビュー、マッチャー、トリアージ、設定用リソースファイルは必要に応じて読み込みます。

標準的なワークフロー

1. ブートストラップ（リポジトリごとに一度）：

   cd <target-repo>
   bunx deepsec init
   cd .deepsec
   bun install
   # Edit .env.local: set AI_GATEWAY_API_KEY=vck_… (or VERCEL_OIDC_TOKEN via `vercel env pull`)
   

   次に、コーディングエージェント（このスキル）に .deepsec/node_modules/deepsec/SKILL.md と .deepsec/data/<id>/SETUP.md を読み、 README／AGENTS.md／CLAUDE.md と代表的なファイルをいくつかざっと確認してから、 data/<id>/INFO.md の各セクションを置き換えるよう指示します（50～100 行、 セクションごとに例を 3～5 個、行番号なし、一般的な CWE の繰り返しはしないでください）。
2. 全体スキャンの前に調整します。 まず、選択した承認済みの調整スコープを resources/decision-records.md に記録します。--limit はファイル数を制限するもので、費用を制限するものではありません。deepsec のドキュメント（getting-started.md、vercel-setup.md、faq.md）では、調整の開始時に --limit 50 --concurrency 5 を推奨しています。

   bunx deepsec scan
   bunx deepsec status
   bunx deepsec process --limit 50 --concurrency 5
   

   実行コストを確認し、resources/scanning.md を使ってリポジトリ全体でのコストを見積もります。バックエンド、スコープ、推定費用をカバーする既存の承認を再利用します。調整の前、および範囲を拡大したスキャンの前に、実際のスコープ判断を記録し、未承認の項目のみ解決します。ユーザーが異なる --limit／--concurrency の値を指定した場合は、その値を使用します。
3. 全体調査、トリアージ、再検証、エクスポート：

   bunx deepsec process --concurrency 5
   bunx deepsec triage --severity HIGH
   bunx deepsec revalidate --min-severity HIGH
   

   フィルタリングまたは抑制の前に、表面化しないものも含め、トリアージしたすべての検出結果について、実際の判定を resources/decision-records.md を使って記録し、確認します。その後、エクスポートします。

   bunx deepsec export --format md-dir --out ./findings
   bunx deepsec metrics
   

4. PR モード（CI ゲート、変更されたファイルを対象とし、終了コードは 0／1）：

   bunx deepsec process \
     --diff origin/${BASE_REF} \
     --comment-out comment.md
   

   resources/pr-review.md に記載された 2 ジョブの CI パターンを組み込みます。PR の制御下にあるコードを実行するジョブに pull-requests: write を決して付与しないでください。
5. カスタムマッチャー（手順 3 で判明したエントリーポイントの不足を補います）：
   • .deepsec/node_modules/deepsec/dist/config.d.ts の仕様と、samples/webapp/matchers/* の例を読みます。
   • .deepsec/matchers/<slug>.ts を作成し、.deepsec/deepsec.config.ts のインラインプラグインを通じて組み込みます。
   • ヒット率を確認します。bunx deepsec scan --matchers <slug> のヒット数は、1,000 ファイルあたり precise で 1～20 件、normal で 5～100 件、noisy でフレームワークのエントリーポイント数程度になるはずです。
6. 再開：クォータ超過、ネットワークの一時的な切断、または Ctrl-C の後は、同じコマンドを再実行します。状態は .deepsec/data/<id>/ に保存されています。

リソースのスコープ

スコープ	リソースの対象
CODEBASE	対象リポジトリのソースファイル、フレームワーク設定、ルートディレクトリ、README／AGENTS.md／CLAUDE.md。
LOCAL_FS	.deepsec/deepsec.config.ts、.deepsec/.env.local、.deepsec/matchers/、.deepsec/data/<id>/{project.json,INFO.md,config.json,files/,runs/,reports/}、生成された findings/、comment.md、CI ワークフローファイル。
PROCESS	`bunx deepsec scan
NETWORK	Vercel AI Gateway 経由（デフォルト）またはプロバイダーの直接エンドポイント経由の Anthropic／OpenAI。任意の Vercel Sandbox microVM コントロールプレーン。
CREDENTIALS	AI_GATEWAY_API_KEY、VERCEL_OIDC_TOKEN、ANTHROPIC_AUTH_TOKEN、OPENAI_API_KEY、VERCEL_TOKEN／VERCEL_TEAM_ID／VERCEL_PROJECT_ID、claude／codex のサブスクリプショントークン。読み取り専用で使用します。シークレットをユーザーにそのまま返したり、コミットしたりしないでください。
MEMORY	現在のセッションについて、ユーザーが指定した予算上限、重大度の下限、停止条件。

前提条件

• Node.js 22 以降が利用可能であること。
• リポジトリが git チェックアウトであること（deepsec は revalidate と --diff に git の履歴を使用します）。
• AI コマンドを実行する場合は、呼び出し前に少なくとも 1 つの認証情報モードが設定されていること。設定されていない場合は、設定されるまで呼び出しを保留します。
• sandbox モードでは Vercel 認証が設定されていること。そうでない場合はローカルで実行します。
• 上限なしの process では、測定したファイルスコープと調整済みコストが既存の承認範囲内に収まること。そうでない場合は、承認済みの制限付きスキャンを使用するか、不足している費用／スコープの判断を解決します。

影響と副作用

• 対象のリポジトリ内に .deepsec/（設定、ロックファイル、スキャフォールディング）と .deepsec/data/<id>/（Git の追跡対象外）を作成します。

• .env.local（コミット禁止）を書き込み、vercel link／vercel env pull を実行する場合があります（.vercel/project.json とトークンを書き込みます）。

• 長時間実行される AI プロセスを起動し、実際の費用が発生します。公式の費用ガイドによると、単一のフルスキャンは 25 ドルから 1,200 ドル超の範囲で、大規模なリポジトリでは数万ドルに達することがあります。

• ソースコードを読み取り、設定された LLM にスニペットを送信します（ゲートウェイはデータを保持しません。プロバイダーに直接送信する場合は、そのプロバイダーのポリシーが適用されます）。シークレットを外部に送信することはありません。sandbox モードでは、ゲートウェイキーはワーカーのサンドボックスの外部に保管されます。

• CI ゲートをユーザーが求めた場合、.github/workflows/deepsec.yml（または同等のファイル）を書き込む場合があります。

• マッチャーを作成する際、deepsec.config.ts を編集し、.deepsec/matchers/*.ts を追加します。

• ユーザーが別途コミット手順を明示的に許可しない限り、コミット、プッシュ、PR の作成は行いません（oma-scm を介して実行します）。

ガードレール

1. サイズを測定していないリポジトリで、上限のない process を決して起動しないでください。 ファイル数が不明、または 500 を超える場合は、必ず最初にキャリブレーションを実行してください（deepsec のドキュメントでは --limit 50 --concurrency 5 を推奨しています。ユーザーが指定した値がある場合はそれに従います）。
2. AI パスを実行する前に、費用と停止条件を伝えてください。 公開されている費用の目安を使用します（100 ファイル ≈ 25～60 ドル、500 ファイル ≈ 130～300 ドル、2,000 ファイル ≈ 500～1,200 ドル。変動幅は 2～3 倍）。
3. リセットせず、再開してください。 ネットワーク、クォータ、Ctrl-C による中断後は、同じコマンドを再実行してください。ユーザーの明示的な指示なしに、「最初からやり直す」ため data/<id>/ を削除してはいけません。
4. INFO.md は短く、プロジェクト固有の内容にしてください。 50～100 行とし、各セクションに例を 3～5 個記載します。プリミティブの名前は記載しますが、行番号は記載しません。一般的な CWE カテゴリは省略してください。これらは組み込みマッチャーでカバーされています。
5. PR／CI ゲートでは、PR によって制御されるコードを、書き込み権限のないジョブで実行してください。 PR によって制御される pnpm install／設定の読み込みを実行するジョブに、pull-requests: write を決して付与しないでください。resources/pr-review.md に記載された 2 ジョブのパターンを使用します。
6. 本番 CI ではアクションを完全な SHA に固定してください。メジャーバージョンタグは例でのみ使用します。
7. 拒否を黙って無視しないでください。 エージェントが refused: true を報告した場合は、ログに記録し、別のバックエンドで再試行するか、再現性が確認できた場合に限りファイルを ignorePaths に追加してください。
8. バグの形が明確な場合は、マッチャーを precise に寄せてください。noisy はエントリーポイントのカバレッジと絞り込んだ glob に限って使用します。
9. 認証情報（vck_…、sk-ant-…、sk-…、OIDC トークン）を表示したり、コミットしたりしないでください。 .env.local はシークレットとして扱います。data/ はデフォルトで Git の追跡対象外として扱います。
10. deepsec はシェルアクセス権を持つエージェントとして扱ってください。 プロンプトインジェクションのリスクが高いリポジトリ（ベンダーコード、信頼できない依存関係）では、sandbox を推奨します。
11. 検出結果には判定が必要です。 ユーザーに提示する HIGH 以上の検出結果には、生の process 出力よりも、revalidate タグ付きの判定（true-positive／false-positive／fixed／uncertain）を優先してください。
12. CLI フラグを捏造せず、このメモより CLI を優先してください。 resources/scanning.md のフラグ一覧に記載されていない項目は、まず --help で確認してください。同様に、CLI が出力するモデル名、デフォルト値、バッチごとの費用が、このスキルに記載された値と異なる場合は、CLI の値が正しいものです。上流の変更は、これらのリソースより速く反映されます。
13. 既存のバックエンド、スコープ、費用の判断を再利用してください。 重要な実行上の選択と各検出結果の判定は、resources/decision-records.md を通じて記録してください。既存の許可がその操作をカバーしている場合、確認を追加してはいけません。

リファレンス

• L1 の実行スコープと検出結果ごとの判定記録：resources/decision-records.md（有料作業／カスタムスコープの作業を行う前、またはトリアージ済みの検出結果をフィルタリングする前に確認してください）。
• ワークスペースへのインストールと INFO.md のブートストラップ：resources/setup.md
• スキャン／処理／トリアージ／再検証／エクスポートの全ワークフローとコストガイド：resources/scanning.md
• process --diff による PR／CI ゲート（二段階ジョブのパターン、終了コードの意味）：resources/pr-review.md
• カスタムマッチャーの作成（スラッグ、ノイズレベル、ファイルグロブ、プラグインの設定）：resources/matchers.md
• 検出結果、重大度、トリアージ／再検証の判定、FP の除外方法：resources/triage.md
• deepsec.config.ts のリファレンス、環境変数、プラグインの順序、AI Gateway／Vercel Sandbox の認証：resources/config.md
• 上流ドキュメント（リソースファイルから参照されている場合にのみ読み込んでください）：
  • リポジトリと README：https://github.com/vercel-labs/deepsec
  • トピックごとのドキュメント：https://github.com/vercel-labs/deepsec/tree/main/docs（`getting-started`、`reviewing-changes`、`writing-matchers`、`configuration`、`models`、`plugins`、`architecture`、`data-layout`、`vercel-setup`、`supported-tech`、`faq`）
• コンテキストの共有読み込み：../_shared/core/context-loading.md
• 品質原則の共有：../_shared/core/quality-principles.md