## Ejecutar aplicaciones (CLI `dynast-bench`)

La CLI es la forma más sencilla de manejar el conjunto de pruebas: verifica el estado de los arranques, arbitra
los puertos compartidos y habla `--json` para que un arnés de escáner pueda consumirlo.
Requiere [Bun](https://bun.sh) 1.2+ y 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

Dos formas de ejecutar cada aplicación:
- **Compose** (`make run`) - la topología multi-servicio canónica que los
  objetivos de ground truth (app + Postgres/Redis/etc. como contenedores separados).
- **Standalone** (`make solo`) - una imagen autocontenida por aplicación
  (`vuln/Dockerfile.standalone`) con los almacenes de datos + un sumidero SSRF interno
  integrado, de modo que `docker build` + `docker run` funcionan sin compose. El comportamiento
  y los PoCs son idénticos (los nombres de los servicios de compose están aliasados a `127.0.0.1`).

La raíz se mantiene deliberadamente pequeña: este README, la guía de diseño, las herramientas
compartidas y las aplicaciones. Todo lo operativo para una aplicación determinada está dentro de la
carpeta propia de esa aplicación.

## Anatomía por aplicación

Cada aplicación bajo `vulnerable-apps/` tiene la misma estructura:```
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 entrada por **operación que expone la aplicación**, tanto vulnerable como benigna: es el denominador para la [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) contiene archivos que puedes puntuar de inmediato: una ejecución de hallazgos, una ejecución de falsos positivos, tres trazas de endpoints y dos plantillas en blanco, cada una documentada con los números que 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

## Las aplicaciones

| App        | Stack                          | DB         | Servicios adicionales | Documento de diseño |
|------------|--------------------------------|------------|----------------------|------------|
| 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 (en la imagen) | [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) |

Más tres aplicaciones **solo API** (GraphQL, WebSocket, Swagger/OpenAPI), una
flota de **rango de red** para escáneres de host/puertos, y dos aplicaciones **LLM**:

| App        | Stack                                       | DB                | Servicios adicionales                       | Documento de diseño |
|------------|---------------------------------------------|-------------------|--------------------------------------|------------|
| 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) |

Ambas aplicaciones LLM ejecutan un **modelo local** mediante un contenedor Ollama
de solo acceso interno (`gemma3:1b` para chat, `qwen2.5:1.5b` para llamadas a herramientas) - sin clave API, sin salida de red,
sin coste por ejecución - e incluyen un backend con script `LLM_BACKEND=stub` para que
los PoCs de referencia sigan siendo deterministas frente a un modelo estocástico.

Consulta [`benchmark-plans/README.md`](https://github.com/j3ssie/dynast-bench/blob/main/benchmark-plans/README.md) para el
modelo de dominio compartido, la matriz de cobertura OWASP-Top-10 y los
principios de diseño del benchmark (casi aciertos, distancia de taint, errores solo de lógica).

## Primeros pasos```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

## Estado

- **19 aplicaciones incluyen una clave de respuestas completa**: 549 vulnerabilidades plantadas, 146
  casi-aciertos, 546 PoCs y un `Dockerfile.standalone` cada una (`--solo`).
  `dynast-bench list` imprime la tabla en vivo.
- **`nextjs` es la implementación de referencia**: construida y validada de extremo a extremo
  (35 vulns + 15 casi-aciertos). `make validate APP=nextjs` demuestra que cada PoC
  es explotable en `vuln/` y está corregido en `safe/`; `make solo APP=nextjs` lo ejecuta desde
  una sola imagen. Copia sus patrones.
- **CLI `dynast-bench`: construida**: ejecuta, verifica, puntúa y limpia cualquier aplicación, en
  modo compose o de imagen única, con `--json` para harnesses.
- **El puntuador: construido** (`dynast-bench/src/`): salida del escáner → hallazgos normalizados
  → precisión/recall/F1, recall por dificultad, una puntuación de discriminación sobre los
  casi-aciertos, y pistas separadas de descubrimiento (red) y canal de inyección (LLM).
- **Cobertura de endpoints: construida**: un `SURFACE.yaml` por aplicación (~600 operaciones en
  toda la flota) que califica cuánto de la aplicación alcanzó realmente una ejecución, y divide
  cada fallo en "nunca encontró el endpoint" vs "lo encontró, pero falló el bug".
- Las invariantes por aplicación sobre las 19 claves de respuestas y los catálogos de superficie se ejecutan en
  `make test`; `dynast-bench check --all` es la puerta de CI.

## Puntuando una herramienta```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

Eso es lo que separa un **fallo de descubrimiento** (nunca llegó al endpoint - arregla el
crawler) de un **fallo de análisis** (llegó a él, no lo reportó - arregla el escáner).
Consulta [`dynast-bench/README.md`](https://github.com/j3ssie/dynast-bench/blob/main/dynast-bench/README.md#scoring) para ver el esquema, los
niveles de coincidencia y cada métrica.

### Lectura del informe (`Leg │ Precision │ Recall │ F1`)

Una **leg** es una ejecución de escaneo contra un estado objetivo:

| Leg | Qué es |
|---|---|
| `blackbox` | sin credenciales - la vista del atacante no autenticado |
| `credentialed` | el mismo objetivo con los inicios de sesión sembrados inyectados, de modo que la superficie autenticada (IDOR, escalada de privilegios) es alcanzable |
| `safe-twin` | el gemelo parcheado (`--safe`), una línea base de falsos positivos - idealmente no encuentra nada |

Las tres se ejecutan en `0.0`–`1.0`, y para las tres **más alto es mejor** (`1.0` es perfecto):

| Métrica | Fórmula | Mejor | Se lee como |
|---|---|---|---|
| **Precision** | `TP / (TP + FP)` | ↑ más alto | de todo lo reportado, cuánto era real. `0.38` = ~38% de los hallazgos eran genuinos, el resto ruido. Alto = pocas falsas alarmas. |
| **Recall** | `TP / (TP + FN)` | ↑ más alto | de los bugs realmente plantados, cuántos se encontraron. `0.73` = 8 de 11. Alto = pocos fallos. |
| **F1** | `2 × P × R / (P + R)` | ↑ más alto | media armónica de ambos - el número principal de "calidad general". Solo es alto cuando ambos lo son, por lo que penaliza ser ruidoso *y* fallar bugs. |

La única inversión: en la **leg `safe-twin` no hay nada real que encontrar**, así que
cada hallazgo allí es una falsa alarma - menos es mejor, y un informe vacío es
la puntuación perfecta.

## Cobertura de endpoints

El recall te dice cuántos bugs encontró una herramienta. No puede decirte **por qué** falló
el resto - y las dos razones necesitan correcciones opuestas:

| Fallo | Significado | Qué arreglar |
|---|---|---|
| **fallo de descubrimiento** | nunca llegó al endpoint que contiene el bug | el crawler |
| **fallo de análisis** | llegó al endpoint, no reportó el bug | el análisis |

Distinguirlos requiere una segunda entrada: los endpoints que tu herramienta dice haber encontrado.
Eso es `endpoints/v1`, puntuado contra el `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

El desglose por niveles es la parte útil: 100% en `static-html` y 0% en `flow` es
un problema de descubrimiento, no un problema del escáner, y ambos se leen de forma
idéntica en un único número de recall.

Dos reglas mantienen honesto el número:

- **El transporte no es la operación.** Un `POST /graphql` no ejercita las 25
  operaciones GraphQL que hay detrás; un handshake de WebSocket no ejercita sus
  eventos; un `POST /api/runs` no ejercita las herramientas de un agente. Alcanzar
  una URL y ejercitar lo que vive allí se puntúan por separado.
- **La telemetría ausente no produce ningún track en absoluto**, nunca `0%`. "No
  medimos esto" y "no alcanzó nada" son afirmaciones opuestas sobre una herramienta.

Los endpoints reportados que no coinciden con nada cuestan precisión pero nunca
reducen la cobertura, así que rociar una wordlist no es una forma de puntuar más
alto. Modelo completo:
[`dynast-bench/README.md#endpoint-coverage`](https://github.com/j3ssie/dynast-bench/blob/main/dynast-bench/README.md#endpoint-coverage).

## Licencia

`dynast-bench` está hecho con ♥ por [@j3ssie](https://github.com/j3ssie) para
evaluar **Vigolium** y **Gimora** (un agente autónomo de seguridad ofensiva), y se
publica bajo la [licencia MIT](https://github.com/j3ssie/dynast-bench/blob/main/LICENSE).