FLAWED

Fix Like Artifacts with Embedded Defects

Un harness di ricerca per misurare quanto bene gli agenti AI correggono le vulnerabilità.

Avvio rapido · Dataset · Documentazione · Modello di sicurezza · Contribuire

FLAWED estrae un progetto open-source a un commit noto come vulnerabile, fornisce a un agente AI una descrizione del bug e gli chiede di scrivere una patch. L'agente non vede mai la vera correzione upstream.

Ogni patch viene poi validata, verificata e valutata in container isolati, così puoi vedere non solo se il modello ha corretto il bug, ma anche se ne ha introdotti di nuovi lungo il percorso.

Come funziona

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]

Ogni fase viene eseguita nel proprio container. Solo clone ha accesso alla rete. Ogni fase successiva è limitata all'API del provider LLM, così gli agenti non possono recuperare suggerimenti o la correzione upstream durante l'esecuzione.

Funzionalità

FLAWED mette a confronto diretto le CLI Claude, Codex e Gemini con gli stessi input.

Avvio rapido

[!WARNING] FLAWED monta il socket Docker (equivalente a root sull'host) ed esegue codice di terze parti non attendibile all'interno dei suoi container di fase. Eseguilo su una macchina di cui ti fidi per sopportare quel carico di lavoro. Vedi docs/security-model.md.

Ti serve Docker, con il socket del daemon accessibile.

# 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

Poi fai la tua prima esecuzione.

1. Importa una bug spec. Le spec di esempio sono incluse in bugs/. Trascinane una nella pagina Bug Specs della web UI, oppure usa la CLI.
   root@kitploit:~

   ./scripts/import-all-bugs.sh
   

2. Avvia un'esecuzione dalla web UI. Scegli la spec, un agente + modello, una variante e un numero di iterazioni. La pagina dell'esecuzione trasmette il progresso in tempo reale.

[!NOTE] La prima esecuzione contro un upstream di grandi dimensioni (ad es. Chromium) è lenta. La fase di validate clona l'intero repo una volta per fare il diff con la vera patch upstream. Il clone viene memorizzato in cache e riutilizzato in seguito.

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

Bug specs

Una bug spec è l'unità di input. Contiene un repo, un commit vulnerabile, una descrizione del bug, un reproducer opzionale e un insieme di varianti di prompt che modellano come il bug potrebbe essere realisticamente segnalato (riscontro SAST, report di bug bounty, advisory in embargo, PoC grezzo, …). Le spec sono versionate e immutabili, così il prompt e il verdetto di un'esecuzione storica non cambiano mai silenziosamente.

Il contratto JSON si trova in bugs.schema.json ed è documentato in docs/bug-specs.md. Tutte le spec incluse descrivono vulnerabilità divulgate pubblicamente e corrette upstream.

Archiviazione

Postgres è l'unica fonte di verità. I metadati delle esecuzioni e i byte degli artefatti (patch, verdetti, trascrizioni, log) risiedono nel database, così un deployment è completamente catturato dal suo DB. La directory data/ è scratch transitorio che le fasi montano a runtime.

• Esegui il backup / ripristino di un intero deployment con scripts/export_dataset.py e scripts/import_dataset.py (disponibili anche dalla web UI).
• Ricostruisci un albero di artefatti su disco per l'ispezione offline con scripts/export_artifacts.py.
• Le modifiche allo schema sono gestite con Alembic (uv run alembic upgrade head viene eseguito automaticamente all'avvio).

Dataset

Pubblichiamo dataset pre-costruiti così puoi caricare campagne completate invece di eseguire tutto da solo. Ogni dataset è un .tar.gz di un singolo snapshot completo, ospitato su https://flawed.s3.us-east-1.amazonaws.com.

Tutte le campagne in un unico bundle.

Dalla web UI (consigliato)

Snapshots → Import datasets, incolla uno dei link agli archivi qui sopra e clicca Find archives. FLAWED importa un link diretto .tar.gz così com'è e lo decomprime nei tuoi snapshot. Poi ripristinalo dalla lista degli snapshot (il ripristino è un passo separato, confermato esplicitamente).

L'importazione scopre più archivi contemporaneamente solo quando l'URL è un bucket elencabile o una pagina indice di directory. Nessuno dei due casi si applica qui, quindi importa i link uno alla volta.

Manualmente

Scarica un archivio, decomprimilo nella directory degli snapshot (FLAWED_HOST_SNAPSHOT_DIR, o ./flawed-snapshots per impostazione predefinita), e comparirà nella lista degli snapshot pronto per il ripristino.

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"

L'importazione prepara solo il bundle su disco. Il ripristino, che sostituisce il deployment corrente, viene eseguito separatamente dalla pagina degli snapshot.

Documentazione

Layout del repository

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)

Sviluppo

I test richiedono Docker. Avviano il proprio Postgres tramite testcontainers.

Licenza e contributi

FLAWED è rilasciato sotto la MIT License. I contributi sono benvenuti. Vedi CONTRIBUTING.md, e segnala i problemi di sicurezza in privato secondo SECURITY.md.