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에 준하는 권한)을 마운트하고, 신뢰할 수 없는 제3자 코드를 스테이지 컨테이너 내부에서 실행합니다. 해당 워크로드를 감당할 수 있다고 신뢰하는 머신에서 실행하세요. 자세한 내용은 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/ 아래에 포함되어 있습니다. 웹 UI의 Bug Specs 페이지로 드래그하거나 CLI를 사용하세요.
   root@kitploit:~

   ./scripts/import-all-bugs.sh
   

2. 웹 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가 단일 진실 공급원입니다. 실행 메타데이터와 아티팩트 바이트 (패치, 판정, 트랜스크립트, 로그)가 데이터베이스에 저장되므로, 배포는 DB에 의해 완전히 포착됩니다. data/ 디렉터리는 스테이지가 런타임에 마운트하는 일시적 스크래치 공간입니다.

• 전체 배포 백업 / 복원은 scripts/export_dataset.py와 scripts/import_dataset.py로 수행합니다(웹 UI에서도 사용 가능).
• 오프라인 검사를 위한 디스크상 아티팩트 트리 재구성은 scripts/export_artifacts.py로 수행합니다.
• 스키마 변경은 Alembic으로 관리됩니다(uv run alembic upgrade head가 시작 시 자동으로 실행됨).

데이터셋

모든 것을 직접 실행하는 대신 완료된 캠페인을 로드할 수 있도록 미리 빌드된 데이터셋을 게시합니다. 각 데이터셋은 하나의 전체 스냅샷을 담은 .tar.gz이며, **https://flawed.s3.us-east-1.amazonaws.com**에 호스팅됩니다.

단일 번들에 담긴 모든 캠페인.

웹 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에 따라 비공개로 신고해 주세요.