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 socket（在宿主机上等同于 root 权限），并在其阶段容器内执行不受信任的第三方代码。请在你信任能够承载此工作负载的机器上运行它。参见 docs/security-model.md。

你需要 Docker，并且守护进程 socket 可访问。

# 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 发现、漏洞赏金报告、禁运公告、原始 PoC……）。规格是版本化且不可变的，因此历史运行的提示和判定永远不会被悄悄改变。

JSON 契约位于 bugs.schema.json，并在 docs/bug-specs.md 中有文档说明。所有随附的规格都描述已公开披露、上游已修复的漏洞。

存储

Postgres 是唯一事实来源。运行元数据以及产物字节（补丁、判定、记录、日志）都存放在数据库中，因此一次部署完全由其数据库所捕获。data/ 目录是临时暂存区，各阶段在运行时挂载它。

• 备份 / 恢复整个部署，使用 scripts/export_dataset.py 和 scripts/import_dataset.py（也可从 Web UI 使用）。
• 重建磁盘上的产物树以便离线检查，使用 scripts/export_artifacts.py。
• 模式变更由 Alembic 管理（uv run alembic upgrade head 会在启动时自动运行）。

数据集

我们发布预构建的数据集，以便你可以加载已完成的活动，而不必自己运行所有内容。每个数据集是一个完整快照的 .tar.gz，托管在 https://flawed.s3.us-east-1.amazonaws.com。

单个捆绑包中的所有活动。

从 Web UI 导入（推荐）

Snapshots → Import datasets，粘贴上面的某个归档链接，然后点击 Find archives。FLAWED 会按原样导入直接的 .tar.gz 链接，并将其解包到你的快照中。然后从快照列表中恢复它（恢复是一个单独的、需明确确认的步骤）。

仅当 URL 是可列举的存储桶或目录索引页面时，导入才会一次性发现多个归档。此处两者都不适用，因此请逐个导入链接。

手动操作

下载一个归档，将其解包到快照目录 （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 私下报告安全问题。