FLAWED

Fix Like Artifacts with Embedded Defects

AIエージェントが脆弱性をどれだけうまく修正できるかを測定するための研究ハーネス。

クイックスタート · データセット · ドキュメント · セキュリティモデル · コントリビューション

FLAWEDは、既知の脆弱なコミット時点でオープンソースプロジェクトをチェックアウトし、AIエージェントにバグの説明を渡してパッチを書くよう依頼します。エージェントが実際のアップストリームの修正を目にすることはありません。

その後、すべてのパッチは隔離されたコンテナ内で検証、監査、採点されるため、モデルがバグを修正したかどうかだけでなく、その過程で新たなバグを混入させなかったかどうかも確認できます。

仕組み

flowchart LR
    spec[bug spec] --> clone
    clone["clone<br/>(open net)"] --> generate
    generate["generate<br/>(offline)"] --> validate
    validate["validate<br/>(offline)"] --> ast["ast<br/>(offline)"]
    generate -.->|"patch.diff"| store[(Postgres)]
    validate -.->|"verdict"| store
    ast -.->|"summary"| store
    store --> ui[web UI + notebook]

各ステージはそれぞれ独自のコンテナ内で実行されます。ネットワークアクセスを持つのはcloneだけです。それ以降のすべてのステージはLLMプロバイダーのAPIのみに制限されているため、エージェントは実行中にヒントやアップストリームの修正を取得できません。

機能

FLAWEDはClaude、Codex、GeminiのCLIを同じ入力で直接対決させます。

クイックスタート

[!WARNING] FLAWEDはDockerソケット（ホスト上ではroot相当）をマウントし、ステージコンテナ内で信頼できないサードパーティのコードを実行します。そのワークロードを処理できると信頼できるマシン上で実行してください。詳細は docs/security-model.mdを参照してください。

Dockerが必要で、デーモンソケットにアクセスできる必要があります。

# 1. Configure. Writes .env for you (data dir + provider API keys)
./setup.sh

# 2. Bring up the stack (Postgres, API + worker, web UI, notebook)
docker compose up --build

# 3. Open http://127.0.0.1:8080

次に最初の実行を行います。

1. バグスペックをインポートします。 サンプルスペックはbugs/以下に同梱されています。Web UIのBug Specsページにドラッグするか、CLIを使用します。
   root@kitploit:~

   ./scripts/import-all-bugs.sh
   

2. Web UIから実行を起動します。 スペック、エージェント+モデル、バリアント、反復回数を選択します。実行ページは進捗をライブでストリーミングします。

[!NOTE] 大規模なアップストリーム（例: Chromium）に対する最初の実行は遅くなります。validateステージは、実際のアップストリームパッチと差分を取るためにリポジトリ全体を一度クローンします。クローンはキャッシュされ、その後再利用されます。

make dev                        # uv sync + web deps
docker compose up -d postgres   # FLAWED needs a Postgres to talk to
cp .env.example .env            # points FLAWED_DB_URL at it
uv run flawed init              # builds base images, creates the schema
uv run flawed serve             # API + worker + webapp on port 8080

バグスペック

バグスペックは入力の単位です。リポジトリ、脆弱なコミット、バグの説明、オプションの再現手順、およびバグが現実的にどのように報告されるかをモデル化した一連のプロンプトバリアント（SASTの検出結果、バグバウンティレポート、 embargoされたアドバイザリ、生のPoCなど）を保持します。スペックはバージョン管理され不変であるため、過去の実行のプロンプトと判定が黙って変わることはありません。

JSONコントラクトはbugs.schema.jsonにあり、docs/bug-specs.mdに文書化されています。同梱されているすべてのスペックは、公開開示され、アップストリームで修正された脆弱性を記述しています。

ストレージ

Postgresが唯一の信頼できる情報源です。実行メタデータおよびアーティファクトのバイト列（パッチ、判定、トランスクリプト、ログ）はデータベース内に存在するため、デプロイメントはそのDBによって完全に捕捉されます。data/ディレクトリは、ステージが実行時にマウントする一時的なスクラッチ領域です。

• デプロイメント全体のバックアップ/リストアはscripts/export_dataset.pyとscripts/import_dataset.pyで行います（Web UIからも利用可能）。
• オフライン検査用にディスク上のアーティファクトツリーを再構築するにはscripts/export_artifacts.pyを使用します。
• スキーマ変更はAlembicで管理されます（uv run alembic upgrade headは起動時に自動的に実行されます）。

データセット

すべてを自分で実行する代わりに、完了したキャンペーンをロードできるよう、事前構築済みのデータセットを公開しています。各データセットは1つの完全なスナップショットの.tar.gzで、**https://flawed.s3.us-east-1.amazonaws.com**でホストされています。

単一のバンドル内のすべてのキャンペーン。

Web UIから（推奨）

Snapshots → Import datasetsで、上記のアーカイブリンクのいずれかを貼り付け、Find archivesをクリックします。FLAWEDは直接の.tar.gzリンクをそのままインポートし、スナップショットに展開します。その後、スナップショットリストからリストアします（リストアは別の、明示的に確認されるステップです）。

インポートが複数のアーカイブを一度に検出するのは、URLがリスト可能なバケットまたはディレクトリインデックスページである場合のみです。ここではどちらにも該当しないため、リンクを1つずつインポートしてください。

手動で

アーカイブをダウンロードし、スナップショットディレクトリ（FLAWED_HOST_SNAPSHOT_DIR、デフォルトでは./flawed-snapshots）に展開すると、スナップショットリストに表示され、リストアできる状態になります。

curl -LO https://flawed.s3.us-east-1.amazonaws.com/compressed/campaigns/full/cve-2026-45185-exim-bdat-uaf_full_gpt-5.5_1782988292.tar.gz
mkdir -p "$FLAWED_HOST_SNAPSHOT_DIR"
tar -xzf cve-2026-45185-exim-bdat-uaf_full_gpt-5.5_1782988292.tar.gz -C "$FLAWED_HOST_SNAPSHOT_DIR"

インポートはバンドルをディスク上にステージングするだけです。現在のデプロイメントを置き換えるリストアは、スナップショットページから別途行います。

ドキュメント

リポジトリレイアウト

packages/
  flawed-core/             models, DB schema, settings
  flawed-orchestrator/     run lifecycle, worker pool, devcontainer driver
  flawed-stage-*/          the pipeline stages (clone, generate, validate, …)
  flawed-agent-runner/     runs INSIDE the container (Claude / Codex / Gemini CLIs)
  flawed-api/              FastAPI + SSE + notebook proxy
  flawed-cli/              the `flawed` CLI
apps/web/                  React + Vite + Tailwind webapp
containers/                base image, network lockdown, notebook container
bugs/                      example bug specs
docs/                      documentation (see above)

開発

テストにはDockerが必要です。テストはtestcontainersを介して独自のPostgresを起動します。

ライセンスとコントリビューション

FLAWEDはMIT Licenseの下でリリースされています。コントリビューションを歓迎します。CONTRIBUTING.mdを参照し、セキュリティ問題はSECURITY.mdに従って非公開で報告してください。