## 运行应用（`dynast-bench` CLI）

CLI 是驱动该套件最简单的方式——它对启动进行健康检查，仲裁共享端口，并支持 `--json` 输出，以便扫描器框架可以消费其结果。
需要 [Bun](https://bun.sh) 1.2+ 和 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

每个应用都有两种运行方式：
- **Compose**（`make run`）——规范的多服务拓扑，即基准测试目标所针对的环境（应用 + Postgres/Redis 等作为独立容器）。
- **Standalone**（`make solo`）——每个应用一个自包含镜像（`vuln/Dockerfile.standalone`），数据存储和内部 SSRF 接收端都嵌入其中，因此无需 compose 即可直接 `docker build` + `docker run`。行为和 PoC 完全相同（compose 服务名称会别名为 `127.0.0.1`）。

根目录刻意保持精简：本 README、设计指南、共享工具和应用。某个应用的所有运维相关内容都放在该应用自己的文件夹内。

## 每个应用的内部结构

`vulnerable-apps/` 下的每个应用都具有完全相同的结构：```
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` 记录应用所暴露的**每个操作**一条条目，无论其存在漏洞还是良性——它是[端点覆盖率](#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/) 目录中存放着您可以立即评分的文件——一份发现结果运行、一份误报运行、三条端点追踪记录以及两份空白模板，每个文件都附有文档说明其生成的数字：```bash
dynast-bench score    nextjs examples/findings.json --safe examples/findings-safe.json
dynast-bench coverage nextjs examples/endpoints.json --findings examples/findings.json

## 应用

| 应用        | 技术栈                          | 数据库         | 附加服务               | 设计文档 |
|------------|--------------------------------|------------|----------------------|------------|
| 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（镜像内） | [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 + 插件          | MySQL      | nginx, Mailpit       | [wordpress.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/wordpress.md) |
| php        | PHP / 过程式 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) |

另有三个**仅 API** 应用（GraphQL、WebSocket、Swagger/OpenAPI）、一个用于主机/端口扫描器的**网络范围**集群，以及两个 **LLM** 应用：

| 应用        | 技术栈                                       | 数据库                | 附加服务                       | 设计文档 |
|------------|---------------------------------------------|-------------------|--------------------------------------|------------|
| llmchat    | Python / FastAPI + LangChain（RAG 聊天机器人）  | Postgres+pgvector | Redis, Ollama, 内部服务          | [llmchat.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/llmchat.md) |
| llmagent   | Node / Fastify + Vercel AI SDK + MCP（代理）| Postgres          | Redis, Ollama, partner-MCP, 内部服务 | [llmagent.md](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/llmagent.md) |

两个 LLM 应用均通过仅内部访问的 Ollama 容器运行**本地模型**
（聊天用 `gemma3:1b`，工具调用用 `qwen2.5:1.5b`）——无需 API 密钥、无出站流量、
无按次运行成本——并附带脚本化的 `LLM_BACKEND=stub` 后端，使
基准事实 PoC 在随机模型下仍保持确定性。

共享领域模型、OWASP Top 10 覆盖矩阵以及基准设计
原则（近似命中、污点距离、仅逻辑缺陷）请参阅
[`benchmark-plans/README.md`](https://github.com/j3ssie/dynast-bench/blob/HEAD/benchmark-plans/README.md)。

## 快速开始```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

## 状态

- **19 个应用带有完整答案密钥**：549 个植入漏洞、146 个
  接近命中、546 个 PoC，以及每个应用一个 `Dockerfile.standalone`（`--solo`）。
  `dynast-bench list` 会打印实时表格。
- **`nextjs` 是参考实现**——已端到端构建并验证
  （35 个漏洞 + 15 个接近命中）。`make validate APP=nextjs` 证明每个 PoC
  在 `vuln/` 上可利用、在 `safe/` 上已修复；`make solo APP=nextjs` 从
  单个镜像运行它。复制其模式。
- **`dynast-bench` CLI——已构建**：可运行、验证、评分并清理任何应用，
  支持 compose 或单镜像模式，并提供 `--json` 供测试框架使用。
- **评分器——已构建**（`dynast-bench/src/`）：扫描器输出 → 规范化发现
  → 精确率/召回率/F1、按难度划分的召回率、针对
  接近命中的区分度分数，以及独立的发现（网络）和注入通道（LLM）跟踪。
- **端点覆盖率——已构建**：每个应用一个 `SURFACE.yaml`（整个
  集群约 600 个操作），用于评估一次运行实际触及了应用的多少部分，
  并将每次遗漏拆分为“从未找到端点”与“找到了端点但遗漏了漏洞”。
- 针对全部 19 个答案密钥和表面目录的每个应用不变量在
  `make test` 中运行；`dynast-bench check --all` 是 CI 门禁。

## 对工具进行评分```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

这就是**发现遗漏**（从未到达端点——修复爬虫）与**分析遗漏**（已到达端点，但未报告——修复扫描器）之间的区别。有关模式、匹配层级及每项指标，请参阅 [`dynast-bench/README.md`](https://github.com/j3ssie/dynast-bench/blob/HEAD/dynast-bench/README.md#scoring)。

### 阅读报告（`Leg │ Precision │ Recall │ F1`）

**leg（扫描腿）** 是针对一个目标状态执行的一次扫描运行：

| Leg | 含义 |
|---|---|
| `blackbox` | 无凭据——未认证攻击者的视角 |
| `credentialed` | 同一目标，但注入了预置登录凭据，因此可触达已认证的攻击面（IDOR、权限提升） |
| `safe-twin` | 已修补的孪生目标（`--safe`），作为误报基线——理想情况下不应发现任何内容 |

三者均以 `0.0`–`1.0` 计分，且对三者而言**越高越好**（`1.0` 为完美）：

| 指标 | 公式 | 越好 | 解读 |
|---|---|---|---|
| **Precision（精确率）** | `TP / (TP + FP)` | ↑ 越高 | 在所有报告的内容中，有多少是真实的。`0.38` = 约 38% 的发现是真实的，其余为噪声。高值 = 误报少。 |
| **Recall（召回率）** | `TP / (TP + FN)` | ↑ 越高 | 在实际植入的漏洞中，有多少被发现。`0.73` = 11 个中发现了 8 个。高值 = 遗漏少。 |
| **F1** | `2 × P × R / (P + R)` | ↑ 越高 | 两者的调和平均值——即“整体质量”的核心指标。只有当两者都高时才会高，因此它会同时惩罚噪声大和遗漏漏洞的情况。 |

唯一例外：在 **`safe-twin` 扫描腿上没有任何真实内容可发现**，因此该腿上的每个发现都是误报——越少越好，空报告即为满分。

## 端点覆盖率

召回率告诉你工具发现了多少个漏洞，但它无法告诉你**为什么**遗漏了其余部分——而这两种原因需要相反的修复方式：

| 遗漏 | 含义 | 需修复的内容 |
|---|---|---|
| **发现遗漏** | 从未到达承载漏洞的端点 | 爬虫 |
| **分析遗漏** | 已到达端点，但未报告漏洞 | 分析逻辑 |

要区分两者，需要第二个输入：你的工具声称发现的端点。这就是 `endpoints/v1`，它会针对每个应用的 `SURFACE.yaml` 进行评分。```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

层级划分才是最有价值的部分：`static-html` 上 100% 而 `flow` 上 0% 是发现层面的问题，而非扫描器的问题，而这两者在单一召回数字中看起来完全相同。

两条规则确保该数字保持真实：

- **传输不等于操作。** 一次 `POST /graphql` 并不会执行其背后的 25 个 GraphQL 操作；一次 WebSocket 握手并不会执行其事件；一次 `POST /api/runs` 并不会执行代理的工具。访问一个 URL 与执行该 URL 上承载的内容是分别评分的。
- **缺失的遥测不会产生任何轨迹**，绝不会是 `0%`。“我们没有测量到这一点”和“它没有触达任何内容”是对工具截然相反的两种论断。

报告出的端点若与任何内容都不匹配，会降低精确度，但绝不会减少覆盖率，因此喷洒字典并非提高分数的途径。完整模型见：
[`dynast-bench/README.md#endpoint-coverage`](https://github.com/j3ssie/dynast-bench/blob/HEAD/dynast-bench/README.md#endpoint-coverage)。

## 许可证

`dynast-bench` 由 [@j3ssie](https://github.com/j3ssie) 倾心打造，用于对
**Vigolium** 和 **Gimora**（一款自主进攻性安全代理）进行基准测试，并以
[MIT 许可证](https://github.com/j3ssie/dynast-bench/blob/HEAD/LICENSE) 发布。