## Executar aplicações (CLI `dynast-bench`)

A CLI é a forma mais fácil de conduzir a suíte — ela faz health-gates nos boots, arbitra
as portas partilhadas e fala `--json` para que um harness de scanner possa consumi-la.
Requer [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

Duas formas de executar cada aplicação:
- **Compose** (`make run`) - a topologia multi-serviço canônica que o ground
  truth tem como alvo (app + Postgres/Redis/etc. como contêineres separados).
- **Standalone** (`make solo`) - uma imagem autocontida por aplicação
  (`vuln/Dockerfile.standalone`) com os datastores + um sink SSRF interno
  embutido, de modo que `docker build` + `docker run` funcionem sem compose. O
  comportamento e os PoCs são idênticos (os nomes dos serviços do compose são
  aliased para `127.0.0.1`).

A raiz permanece deliberadamente pequena: este README, o guia de design, as
ferramentas compartilhadas e as aplicações. Tudo o que é operacional para uma
determinada aplicação fica dentro da própria pasta dessa aplicação.

## Anatomia por aplicação

Cada aplicação em `vulnerable-apps/` tem a mesma estrutura:```
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` regista uma entrada por **operação que a aplicação expõe**, vulnerável
e benigna igualmente - é o denominador para [cobertura de
endpoints](#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/main/examples) contém ficheiros que pode pontuar imediatamente - uma execução de descobertas, uma
execução de falsos positivos, três rastreios de endpoints e dois modelos em branco, cada um documentado
com os números que produz:```bash
dynast-bench score    nextjs examples/findings.json --safe examples/findings-safe.json
dynast-bench coverage nextjs examples/endpoints.json --findings examples/findings.json

## Os aplicativos

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

Mais três aplicativos **somente API** (GraphQL, WebSocket, Swagger/OpenAPI), uma
frota de **intervalo de rede** para scanners de host/porta e dois aplicativos **LLM**:

| App        | Stack                                       | DB                | Serviços extras                       | Documento de design |
|------------|---------------------------------------------|-------------------|--------------------------------------|------------|
| llmchat    | Python / FastAPI + LangChain (chatbot RAG)  | Postgres+pgvector | Redis, Ollama, svc interno          | [llmchat.md](https://github.com/j3ssie/dynast-bench/blob/main/benchmark-plans/llmchat.md) |
| llmagent   | Node / Fastify + Vercel AI SDK + MCP (agente)| Postgres          | Redis, Ollama, partner-MCP, svc interno | [llmagent.md](https://github.com/j3ssie/dynast-bench/blob/main/benchmark-plans/llmagent.md) |

Ambos os aplicativos LLM executam um **modelo local** por meio de um contêiner Ollama
somente interno (`gemma3:1b` para chat, `qwen2.5:1.5b` para chamada de ferramentas) — sem chave de API, sem egresso,
sem custo por execução — e incluem um backend com script `LLM_BACKEND=stub` para que os
PoCs de verdade fundamental permaneçam determinísticos contra um modelo estocástico.

Consulte [`benchmark-plans/README.md`](https://github.com/j3ssie/dynast-bench/blob/main/benchmark-plans/README.md) para o
modelo de domínio compartilhado, a matriz de cobertura do OWASP Top 10 e os
princípios de design do benchmark (quase-acertos, distância de taint, bugs somente de lógica).

## Primeiros passos```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

## Status

- **19 aplicações trazem um gabarito completo**: 549 vulnerabilidades plantadas, 146
  quase-acertos, 546 PoCs e um `Dockerfile.standalone` cada (`--solo`).
  `dynast-bench list` imprime a tabela ao vivo.
- **`nextjs` é a implementação de referência** - construída e validada de ponta a ponta
  (35 vulns + 15 quase-acertos). `make validate APP=nextjs` prova que cada PoC é
  explorável em `vuln/` e corrigida em `safe/`; `make solo APP=nextjs` a executa a partir de
  uma única imagem. Copie seus padrões.
- **CLI `dynast-bench` - construída**: executa, verifica, pontua e limpa qualquer aplicação, em
  modo compose ou imagem única, com `--json` para harnesses.
- **O avaliador - construído** (`dynast-bench/src/`): saída do scanner → achados normalizados
  → precisão/recall/F1, recall por dificuldade, uma pontuação de discriminação sobre os
  quase-acertos, e trilhas separadas de descoberta (rede) e canal de injeção (LLM).
- **Cobertura de endpoints - construída**: um `SURFACE.yaml` por aplicação (~600 operações em
  toda a frota) avaliando quanto da aplicação uma execução realmente alcançou, e dividindo
  cada falha em "nunca encontrou o endpoint" vs "encontrou, mas errou o bug".
- Invariantes por aplicação sobre todos os 19 gabaritos e catálogos de superfície rodam em
  `make test`; `dynast-bench check --all` é o gate de CI.

## Pontuando uma ferramenta```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

É isso que separa uma **falha de descoberta** (nunca alcançou o endpoint — corrija o
crawler) de uma **falha de análise** (alcançou-o, não reportou — corrija o scanner).
Consulte [`dynast-bench/README.md`](https://github.com/j3ssie/dynast-bench/blob/main/dynast-bench/README.md#scoring) para o esquema, os
níveis de correspondência e cada métrica.

### Como ler o relatório (`Leg │ Precision │ Recall │ F1`)

Uma **leg** é uma execução de scan contra um estado-alvo:

| Leg | O que é |
|---|---|
| `blackbox` | sem credenciais — a visão do atacante não autenticado |
| `credentialed` | o mesmo alvo com os logins semeados injetados, para que a superfície autenticada (IDOR, escalonamento de privilégios) seja alcançável |
| `safe-twin` | o gémeo corrigido (`--safe`), uma linha de base de falsos positivos — idealmente não encontra nada |

Todas as três correm de `0.0`–`1.0`, e para todas as três **quanto mais alto, melhor** (`1.0` é perfeito):

| Métrica | Fórmula | Melhor | Leia-se como |
|---|---|---|---|
| **Precision** | `TP / (TP + FP)` | ↑ mais alto | de tudo o que foi reportado, quanto era real. `0.38` = ~38% dos achados eram genuínos, o resto ruído. Alto = poucos falsos alarmes. |
| **Recall** | `TP / (TP + FN)` | ↑ mais alto | dos bugs efetivamente plantados, quantos foram encontrados. `0.73` = 8 de 11. Alto = poucas falhas. |
| **F1** | `2 × P × R / (P + R)` | ↑ mais alto | média harmónica dos dois — o número principal de "qualidade geral". Só é alto quando ambos o são, por isso penaliza ser ruidoso *e* falhar bugs. |

A única inversão: na **leg `safe-twin` não há nada real para encontrar**, por isso
cada achado aí é um falso alarme — menos é melhor, e um relatório vazio é
a pontuação perfeita.

## Cobertura de endpoints

O Recall diz-lhe quantos bugs uma ferramenta encontrou. Não lhe pode dizer **porquê** falhou
o resto — e as duas razões exigem correções opostas:

| Falha | Significado | O que corrigir |
|---|---|---|
| **falha de descoberta** | nunca alcançou o endpoint que contém o bug | o crawler |
| **falha de análise** | alcançou o endpoint, não reportou o bug | a análise |

Distingui-las exige uma segunda entrada: os endpoints que a sua ferramenta diz ter encontrado.
Isso é `endpoints/v1`, pontuado contra o `SURFACE.yaml` de cada 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

A repartição por camadas é a parte útil: 100% em `static-html` e 0% em `flow` é
um problema de descoberta, não um problema do scanner, e essas leituras são idênticas em
um único número de recall.

Duas regras mantêm o número honesto:

- **Transporte não é operação.** Um `POST /graphql` não exercita as 25
  operações GraphQL por trás dele; um handshake WebSocket não exercita os seus
  eventos; um `POST /api/runs` não exercita as ferramentas de um agente. Alcançar um URL
  e exercitar o que vive lá são pontuados separadamente.
- **Telemetria ausente não produz nenhum rasto**, nunca `0%`. "Não medimos
  isto" e "não alcançou nada" são afirmações opostas sobre uma ferramenta.

Endpoints reportados que não correspondem a nada custam precisão, mas nunca reduzem a cobertura,
portanto, pulverizar uma wordlist não é uma forma de pontuar mais alto. Modelo completo:
[`dynast-bench/README.md#endpoint-coverage`](https://github.com/j3ssie/dynast-bench/blob/main/dynast-bench/README.md#endpoint-coverage).

## Licença

`dynast-bench` é feito com ♥ por [@j3ssie](https://github.com/j3ssie) para avaliar
**Vigolium** e **Gimora** (um agente autónomo de segurança ofensiva), e é
disponibilizado sob a [licença MIT](https://github.com/j3ssie/dynast-bench/blob/main/LICENSE).