deepsec

vercel-labs/deepsec — 自前インフラで動かすエージェント駆動の脆弱性スキャナ。大規模リポジトリのオンデマンドレビュー向け。

1 — 概要

何か

deepsec は、既存の大規模リポジトリを対象に、見つかりにくい脆弱性を掘り出す AI スキャナ。まず regex マッチャで候補を拾い、続けてコーディングエージェントがファイル単位で調査する。中断しても同じコマンドを再実行すれば、未完了分だけ再開する。

本番スキャンはモデルを最大 thinking レベルで回す前提で、大規模コードベースではコストが数千〜数万ドル規模になり得る。顧客は「放置されていた脆弱性を早く直せた」ならペイすると記載されている。

Node 22+

Runtime

~110

Built-in matchers

Apache 2.0

License

Vercel

Maintainer

設計の核: 作業単位は「finding」ではなくソースファイル 1 本 = FileRecord 1 件。scan / process / revalidate はすべてファイルに対して動き、ロックと idempotent merge が自然に成り立つ。

2 — はじめ方

ワークスペース

スキャン対象リポジトリのルートで npx deepsec init を実行すると、同梱の .deepsec/ ワークスペースができる。設定・INFO.md・カスタムマッチャは git に乗せ、生成物（findings / runs）はデフォルトで gitignore。

npx deepsec init       # .deepsec/ を作成し、この repo を最初の project にする
cd .deepsec
pnpm install

# INFO.md を埋めたあと（エージェント推奨）
pnpm deepsec scan
pnpm deepsec process
pnpm deepsec revalidate   # 任意。FP を減らす
pnpm deepsec export --format md-dir --out ./findings

STEP 01

init + 認証

.env.local に AI_GATEWAY_API_KEY、または Vercel OIDC。ローカル評価なら既存の Claude / Codex ログインも可（フルスキャンには頭打ちになりやすい）。

STEP 02

INFO.md

プロジェクト固有の文脈（認証ヘルパ、ミドルウェア等）を 50–100 行程度で書く。全バッチのプロンプトに注入されるので、長いと信号が薄まる。

STEP 03

scan → process

scan は AI なし（2k files で約 15s）。process が本命の AI 調査。最初は --limit 50 でコスト感を校正する。

STEP 04

revalidate / export

HIGH+ に revalidate（多くの repo で FP を 50%+ 削減）。出力は export（md-dir / json）か report / metrics。

Files	概算コスト (Opus 既定)	概算時間
100	$25–60	5–15 min
500	$130–300	25–60 min
2,000	$500–1,200	1.5–4 hr

複雑さで 2–3x 振れる。出典: getting-started.md

3 — パイプライン

Append-only

各ステージは独立した CLI サブコマンド。ディスク上の表現を読み書きし、再実行は上書きではなくマージ。中断後も同じコマンドで再開できる。

flowchart TD
  scan["scan
regex 候補 / 無料"] --> process["process
AI 調査 / $$"]
  process --> revalidate["revalidate
TP / FP / Fixed"]
  revalidate --> enrich["enrich
committer / ownership"]
  enrich --> export["export / report / metrics
読み取り専用"]

ステージ	役割	コスト
`scan`	プロジェクトを glob し、ビルトイン + プラグインのマッチャで `candidates` を書く。`status: pending`。	無料（AI なし）
`process`	pending ファイルをバッチ化し、エージェントに投げて `findings` を書く。`analysisHistory` に追記。	高い（本命）
`revalidate`	既存 finding を再読し、git 履歴も見て verdict（true-positive / false-positive / fixed / uncertain）。	process 並み
`enrich`	git committer と（プラグイン経由で）ownership を付与。	無料〜HTTP 往復
`export` 等	FileRecord を変更せず、人間・下流向けに整形。	無料

4 — データレイアウト

data/<projectId>/

data/ はプロジェクトごとのオンディスク状態。デフォルト gitignore。FileRecord が「そのソースについて deepsec が知っていること」の単一の正。

data/<projectId>/
├── project.json     # rootPath, githubUrl
├── INFO.md          # AI プロンプトへ注入する文脈
├── config.json      # priorityPaths / ignorePaths など（任意）
├── files/            # ソース 1 本 → JSON 1 件（FileRecord）
│   └── path/to/file.ts.json
├── runs/             # RunMeta（実行メタ）
└── reports/          # markdown + JSON

マージ規則: re-scan は候補をマージ、re-process は analysisHistory に追記して findings を slug+title で重複排除、revalidate は既存 finding に verdict を付ける。破壊的上書きはしない。

5 — コマンド

Command	内容
`scan`	regex マッチャで候補サイトを発見（高速・AI なし）
`process`	AI 調査。finding と recommendation を出力
`process --diff`	PR モード。diff 内の変更ファイルだけ scan + 調査
`triage`	安価モデルで P0/P1/P2 分類
`revalidate`	既存 finding の再確認。git 履歴で修正済みも検知
`enrich`	committer 情報 +（プラグインで）ownership
`report`	プロジェクト単位の Markdown + JSON サマリ
`export`	finding ごとの JSON、または md-dir
`metrics`	severity・脆弱性タイプ・TP など横断集計
`status`	プロジェクトミラーのスナップショット
`sandbox <cmd>`	上記を Vercel Sandbox microVM 上で実行

6 — エージェントとモデル

バックエンド

プロンプトと JSON 出力スキーマは共通。プロジェクト内でエージェントを混ぜてもよく、再 process した結果は既存 findings にマージされる。

`--agent`	SDK	既定モデル
`codex`（default）	`@openai/codex-sdk`	`gpt-5.5`
`claude`	`@anthropic-ai/claude-agent-sdk`	`claude-opus-4-8`
`pi`	`@earendil-works/pi-coding-agent`	`zai/glm-5.2`

--concurrency 5 --batch-size 5 なら同時に最大 25 ファイル。プロセッサは lockedByRunId でファイルをアトミックに claim し、複数ワーカーが衝突しない。

7 — サンドボックスとセキュリティ

分散実行

大規模 monorepo は Vercel Sandbox にファンアウトできる。

pnpm deepsec sandbox process --project-id my-app --sandboxes 10 --concurrency 4

ローカル作業ツリーを tarball して upload（.git は除外）。OIDC（ローカル）と access token（CI）の両方に対応。手順は docs/vercel-setup.md。

deepsec 自体の脅威モデル: フルシェル権限を持つコーディングエージェントとして扱う。信頼できる入力（自社ソース）向け。サンドボックスではエージェント API キーを VM 外注入し、ワーカーの egress をコーディングエージェントホストに制限する（bootstrap 時は別扱い）。

8 — パッケージ構成

packages/core

型・スキーマ・設定ロード・プラグインレジストリ。FileRecord / Finding の契約の中心。

packages/scanner

技術検出と ~110 の regex マッチャ。プラグインマッチャは同じ slug でビルトインを上書き可能。

packages/processor

エージェント呼び出し、プロンプト組み立て、triage / revalidate / enrich。

packages/deepsec

CLI・サンドボックス orchestrator・init / export / report。配布パッケージの入口。

プラグイン拡張点

packages/core の plugin 契約: matchers / notifiers / agents（加算）、ownership / people / executor（単一スロット）。deepsec.config.ts で登録し、CLI が起動時に PluginRegistry を組む。

9 — 参考リンク

vercel-labs/deepsec — ソースリポジトリ
README.md — インストールとワークフロー
docs/getting-started.md — 初回スキャン手順
docs/architecture.md — パイプライン内部
docs/data-layout.md — FileRecord / RunMeta
docs/writing-matchers.md — マッチャ拡張
docs/plugins.md — プラグイン作者向け
docs/models.md — モデル選択
docs/vercel-setup.md — AI Gateway / Sandbox
samples/webapp — 設定の参照実装

出典: README.md · docs/architecture.md · docs/getting-started.md · docs/data-layout.md · packages/deepsec/SKILL.md