## Esecuzione delle app (CLI `dynast-bench`)

La CLI è il modo più semplice per gestire la suite: verifica l'avvio tramite health-check, arbitra
le porte condivise e parla `--json` così un harness di scanner può consumarla.
Richiede [Bun](https://bun.sh) 1.2+ e Docker.```bash
make install                             # compile the CLI + link it into ~/.bun/bin
                                         # (BIN_DIR=/somewhere/else to pick the dir)

dynast-bench list                        # every app: vulns, PoCs, near-misses, what's up
dynast-bench vulns nextjs                # the planted bugs as a checklist, one title each
                                         # (--full · --near · --ids for a coverage diff)
dynast-bench start nextjs                # build + boot, wait for health, print the URL
dynast-bench verify nextjs               # run the ground-truth PoCs (expect all exploitable)
dynast-bench validate nextjs             # twin loop: vuln all-exploitable → safe all-fixed
dynast-bench status                      # variant, mode, target, health
dynast-bench stop --all                  # stop everything
dynast-bench clean --all --images --yes  # reclaim containers, volumes, networks, images

dynast-bench start nextjs --variant safe # the patched twin (false-positive run)
dynast-bench start --count 5 --parallel  # 5 apps at once, one port each + a summary table
dynast-bench start --all --solo --parallel   # whole fleet, one image + port each
dynast-bench run nextjs -- my-scanner --url '$TARGET'   # start → scan → stop

Due modi per eseguire ogni app:
- **Compose** (`make run`) - la topologia multi-servizio canonica che i ground
  truth target (app + Postgres/Redis/ecc. come container separati).
- **Standalone** (`make solo`) - un'immagine autonoma per app
  (`vuln/Dockerfile.standalone`) con i datastore + un sink SSRF interno
  incorporati, così `docker build` + `docker run` funziona senza compose. Il
  comportamento e i PoC sono identici (i nomi dei servizi compose sono alias di `127.0.0.1`).

La root resta volutamente piccola: questo README, la guida di design, il
tooling condiviso e le app. Tutto ciò che è operativo per una data app è dentro
la cartella di quella stessa app.

## Anatomia per app

Ogni app sotto `vulnerable-apps/` ha la stessa identica struttura:```
vulnerable-apps/<stack>/
├── README.md            # LOUD banner + run notes
├── Makefile             # up · reset · safe · verify · score · diff  (uniform interface)
├── vuln/                # the vulnerable variant - this is what you scan by default
│   ├── docker-compose.yml   # independent; binds 127.0.0.1 only
│   ├── app/                 # application source; the planted bugs live here
│   └── db/seed.sql          # seed incl. a cross-tenant user + a weak default cred
├── safe/                # the patched twin - same app, every planted bug fixed
│   ├── docker-compose.yml
│   ├── app/
│   └── db/seed.sql
└── ground-truth/        # the answer key - see "Ground truth" below
    ├── VULNERABILITIES.yaml  # every planted bug
    ├── SURFACE.yaml          # every endpoint the app exposes
    ├── verify/          # one runnable PoC per bug
    └── expected/        # optional golden normalized findings

`SURFACE.yaml` registra una voce per ogni **operazione esposta dall'app**, vulnerabile
o benigna che sia - è il denominatore per la [copertura degli
endpoint](#endpoint-coverage):```yaml
operations:
  - id: posts.search
    kind: http                 # http | graphql | ws | llm | net
    method: GET
    path: /api/posts/search
    params: [q]
    discovery: js-runtime      # same crawl tiers as the answer key
    reachability: user
    vulns: [SQLI-001]          # omit when the operation is benign

  - id: graphql.mutation.update-post
    kind: graphql              # the op BEHIND POST /graphql, which is its own entry
    op: updatePost
    graphql_kind: mutation
    via: graphql.transport
    discovery: static-html

[`examples/`](https://github.com/j3ssie/dynast-bench/blob/HEAD/examples/) contiene file che puoi valutare immediatamente: un run di findings, un run di falsi positivi, tre tracce di endpoint e due modelli vuoti, ciascuno documentato con i numeri che produce:```bash
dynast-bench score    nextjs examples/findings.json --safe examples/findings-safe.json
dynast-bench coverage nextjs examples/endpoints.json --findings examples/findings.json

## Le app

| App        | Stack                          | DB         | Servizi extra       | Documento di progettazione |
|------------|--------------------------------|------------|----------------------|------------|
| fastapi    | Python / FastAPI + Jinja2      | Postgres   | MinIO, Mailpit       | [fastapi.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/fastapi.md) |
| golang     | Go / chi                       | Postgres   | Prometheus, Grafana  | [golang.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/golang.md) |
| gin        | Go / Gin                       | Postgres   | chromium, ImageMagick (in-image) | [README](https://github.com/j3ssie/dynast-bench/blob/HEAD/vulnerable-apps/gin/README.md) |
| nextjs     | Node / Next.js 15              | Postgres   | Redis, Mailpit       | [nextjs.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/nextjs.md) |
| nestjs     | Node / NestJS + Handlebars     | Postgres   | Redis, nginx         | [nestjs.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/nestjs.md) |
| springboot | Java / Spring Boot + Thymeleaf | Postgres   | Jenkins, Prometheus  | [springboot.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/springboot.md) |
| rails      | Ruby / Rails 7.2               | Postgres   | MinIO, nginx         | [rails.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/rails.md) |
| wordpress  | PHP / WordPress + plugin       | MySQL      | nginx, Mailpit       | [wordpress.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/wordpress.md) |
| php        | PHP / procedurale LAMP         | MySQL      | phpMyAdmin, Mailpit  | [php.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/php.md) |
| jsp        | Java / JSP + Servlets (Tomcat) | Postgres   | Mailpit              | [jsp.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/jsp.md) |
| aspnet     | C# / ASP.NET Core Razor Pages  | SQL Server | Mailpit              | [aspnet.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/aspnet.md) |

Più tre app **solo API** (GraphQL, WebSocket, Swagger/OpenAPI), una
flotta **network-range** per scanner di host/porte, e due app **LLM**:

| App        | Stack                                       | DB                | Servizi extra                       | Documento di progettazione |
|------------|---------------------------------------------|-------------------|--------------------------------------|------------|
| llmchat    | Python / FastAPI + LangChain (chatbot RAG)  | Postgres+pgvector | Redis, Ollama, servizio interno     | [llmchat.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/llmchat.md) |
| llmagent   | Node / Fastify + Vercel AI SDK + MCP (agente)| Postgres          | Redis, Ollama, partner-MCP, servizio interno | [llmagent.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/llmagent.md) |

Entrambe le app LLM eseguono un **modello locale** tramite un container Ollama
solo interno (`gemma3:1b` per la chat, `qwen2.5:1.5b` per il tool calling) - nessuna API key, nessun egress,
nessun costo per esecuzione - e includono un backend scriptato `LLM_BACKEND=stub` così che i
PoC ground-truth rimangano deterministici contro un modello stocastico.

Vedi [`benchmark-plans/README.md`](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/README.md) per il
modello di dominio condiviso, la matrice di copertura OWASP-Top-10, e i principi
di progettazione del benchmark (near-misses, taint distance, bug solo logici).

## Per iniziare```bash
make install                           # once: puts `dynast-bench` on your PATH
dynast-bench doctor                    # docker reachable? which ports are taken?

dynast-bench start fastapi             # boots the vuln/ variant, waits for health
dynast-bench verify fastapi            # sanity-check: every planted bug's PoC PASSes

# ...point your scanner/agent at $(dynast-bench target fastapi), collect findings.json...

dynast-bench start fastapi --variant safe   # patched twin → measures false positives
dynast-bench reset fastapi                  # restore fresh, re-seeded state
dynast-bench clean --all --yes              # give the disk back

## Stato

- **19 app con una chiave di risposta completa**: 549 vulnerabilità inserite, 146
  quasi-mancati, 546 PoC e un `Dockerfile.standalone` ciascuna (`--solo`).
  `dynast-bench list` stampa la tabella aggiornata.
- **`nextjs` è l'implementazione di riferimento** - costruita e validata end-to-end
  (35 vulnerabilità + 15 quasi-mancati). `make validate APP=nextjs` dimostra che ogni PoC
  è sfruttabile su `vuln/` e corretto su `safe/`; `make solo APP=nextjs` lo esegue da
  un'unica immagine. Copia i suoi pattern.
- **CLI `dynast-bench` - costruita**: esegue, verifica, valuta e pulisce qualsiasi app, in
  modalità compose o immagine singola, con `--json` per gli harness.
- **Lo scorer - costruito** (`dynast-bench/src/`): output dello scanner → risultati
  normalizzati → precision/recall/F1, recall per difficoltà, un punteggio di discriminazione sui
  quasi-mancati, e tracce separate per discovery (rete) e canale di injection (LLM).
- **Copertura degli endpoint - costruita**: un `SURFACE.yaml` per app (~600 operazioni in
  tutta la flotta) che valuta quanto dell'app un'esecuzione ha effettivamente raggiunto, e suddivide
  ogni mancato in "endpoint mai trovato" vs "trovato, ma bug mancato".
- Gli invarianti per-app su tutte le 19 chiavi di risposta e i cataloghi di superficie vengono eseguiti in
  `make test`; `dynast-bench check --all` è il gate CI.

## Valutazione di uno strumento```bash
dynast-bench start nextjs --json | jq -r .target        # boot, get the URL
zap-baseline.py -t http://127.0.0.1:13311 -J zap.json   # scan
dynast-bench score nextjs zap.json --full               # grade it

# measure false positives properly: scan the patched twin too
dynast-bench start nextjs --variant safe
my-scanner --url http://127.0.0.1:13311 --out safe.json
dynast-bench score nextjs zap.json --safe safe.json

Questo è ciò che distingue un **mancato rilevamento di scoperta** (non ha mai raggiunto l'endpoint - correggi il crawler) da un **mancato rilevamento di analisi** (lo ha raggiunto, ma non lo ha segnalato - correggi lo scanner).
Consulta [`dynast-bench/README.md`](https://github.com/j3ssie/dynast-bench/blob/HEAD/dynast-bench/README.md#scoring) per lo schema, i livelli di corrispondenza e ogni metrica.

### Lettura del report (`Leg │ Precision │ Recall │ F1`)

Una **leg** è una singola scansione eseguita contro uno stato del target:

| Leg | Cosa rappresenta |
|---|---|
| `blackbox` | nessuna credenziale - la vista dell'attaccante non autenticato |
| `credentialed` | stesso target con i login seed iniettati, così la superficie autenticata (IDOR, escalation dei privilegi) è raggiungibile |
| `safe-twin` | il gemello patchato (`--safe`), una baseline di falsi positivi - idealmente non trova nulla |

Tutte e tre vanno da `0.0` a `1.0`, e per tutte e tre **più alto è meglio** (`1.0` è perfetto):

| Metrica | Formula | Migliore | Significato |
|---|---|---|---|
| **Precision** | `TP / (TP + FP)` | ↑ più alto | di tutto ciò che viene segnalato, quanto era reale. `0.38` = ~38% dei risultati erano genuini, il resto rumore. Alto = pochi falsi allarmi. |
| **Recall** | `TP / (TP + FN)` | ↑ più alto | dei bug effettivamente piantati, quanti sono stati trovati. `0.73` = 8 su 11. Alto = pochi mancati rilevamenti. |
| **F1** | `2 × P × R / (P + R)` | ↑ più alto | media armonica dei due - il numero "qualità complessiva" principale. È alto solo quando lo sono entrambi, quindi penalizza sia l'essere rumorosi *che* il mancare i bug. |

L'unica inversione: sulla **leg `safe-twin` non c'è nulla di reale da trovare**, quindi ogni risultato lì è un falso allarme - meno è meglio, e un report vuoto è il punteggio perfetto.

## Copertura degli endpoint

Il Recall ti dice quanti bug ha trovato uno strumento. Non può dirti **perché** ha mancato il resto - e i due motivi richiedono correzioni opposte:

| Mancato rilevamento | Significato | Cosa correggere |
|---|---|---|
| **mancato rilevamento di scoperta** | non ha mai raggiunto l'endpoint che contiene il bug | il crawler |
| **mancato rilevamento di analisi** | ha raggiunto l'endpoint, ma non ha segnalato il bug | l'analisi |

Distinguerli richiede un secondo input: gli endpoint che il tuo strumento dichiara di aver trovato.
Questo è `endpoints/v1`, valutato rispetto al `SURFACE.yaml` di ciascuna app.```bash
dynast-bench surface  nextjs                       # the checklist a crawl is graded on
dynast-bench coverage nextjs endpoints.json        # how much did it reach?
dynast-bench coverage nextjs endpoints.json --findings findings.json   # ...and why not the rest
dynast-bench score    nextjs findings.json --endpoints endpoints.json  # both in one report

La ripartizione per livelli è la parte utile: 100% su `static-html` e 0% su `flow` è
un problema di scoperta, non un problema dello scanner, e questi valori si leggono in modo identico in
un singolo numero di recall.

Due regole mantengono onesto il numero:

- **Il trasporto non è operazione.** Un `POST /graphql` non esercita le 25
  operazioni GraphQL che ci sono dietro; un handshake WebSocket non esercita i suoi
  eventi; un `POST /api/runs` non esercita gli strumenti di un agente. Raggiungere un URL
  ed esercitare ciò che vi risiede sono valutati separatamente.
- **La telemetria mancante non produce alcuna traccia**, mai `0%`. "Non abbiamo misurato
  questo" e "non ha raggiunto nulla" sono affermazioni opposte su uno strumento.

Gli endpoint segnalati che non corrispondono a nulla costano precisione ma non riducono mai la copertura,
quindi sparare una wordlist non è un modo per ottenere un punteggio più alto. Modello completo:
[`dynast-bench/README.md#endpoint-coverage`](https://github.com/j3ssie/dynast-bench/blob/HEAD/dynast-bench/README.md#endpoint-coverage).

## Licenza

`dynast-bench` è realizzato con ♥ da [@j3ssie](https://github.com/j3ssie) per fare benchmark di
**Vigolium** e **Gimora** (un agente autonomo di sicurezza offensiva), ed è
rilasciato sotto la [licenza MIT](https://github.com/j3ssie/dynast-bench/blob/HEAD/LICENSE).