## アプリの実行（`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

Two ways to run every app:
- **Compose** (`make run`) - the canonical multi-service topology the ground
  truth targets (app + Postgres/Redis/etc. as separate containers).
- **Standalone** (`make solo`) - one self-contained image per app
  (`vuln/Dockerfile.standalone`) with the datastores + an internal SSRF sink
  embedded, so `docker build` + `docker run` works with no compose. Behaviour
  and PoCs are identical (compose service names are aliased to `127.0.0.1`).

The root stays deliberately small: this README, the design guide, the shared
tooling, and the apps. Everything operational for a given app is inside that
app's own folder.

## Per-app anatomy

Every app under `vulnerable-apps/` has the identical shape:```
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` には、**アプリが公開する操作**ごとに1つのエントリが記録されます。脆弱な操作も良性の操作も同様に含まれ、これは[エンドポイントカバレッジ](#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/) には、すぐにスコアリングできるファイルが含まれています。検出結果の実行、誤検知の実行、3つのエンドポイントトレース、2つの空のテンプレートがあり、それぞれが生成する数値とともに文書化されています。```bash
dynast-bench score    nextjs examples/findings.json --safe examples/findings-safe.json
dynast-bench coverage nextjs examples/endpoints.json --findings examples/findings.json

## アプリ

| アプリ      | スタック                          | DB         | 追加サービス       | 設計ドキュメント |
|------------|--------------------------------|------------|----------------------|------------|
| 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専用**アプリが3つ（GraphQL、WebSocket、Swagger/OpenAPI）、
ホスト/ポートスキャナ向けの**ネットワークレンジ**フリート、そして**LLM**アプリが2つあります:

| アプリ      | スタック                                       | DB                | 追加サービス                       | 設計ドキュメント |
|------------|---------------------------------------------|-------------------|--------------------------------------|------------|
| llmchat    | Python / FastAPI + LangChain (RAGチャットボット)  | Postgres+pgvector | Redis, Ollama, 内部svc          | [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, 内部svc | [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/`）: スキャナ出力 → 正規化された検出結果 → precision/recall/F1、難易度別のrecall、ニアミスに対する識別スコア、そして探索（ネットワーク）と注入チャネル（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

That is what separates a **discovery miss** (never reached the endpoint - fix the
crawler) from an **analysis miss** (reached it, did not report - fix the scanner).
See [`dynast-bench/README.md`](https://github.com/j3ssie/dynast-bench/blob/HEAD/dynast-bench/README.md#scoring) for the schema, the
matching tiers and every metric.

### Reading the report (`Leg │ Precision │ Recall │ F1`)

A **leg** is one scan run against one target state:

| Leg | What it is |
|---|---|
| `blackbox` | no credentials - the unauthenticated attacker view |
| `credentialed` | same target with the seeded logins injected, so authenticated surface (IDOR, privilege escalation) is reachable |
| `safe-twin` | the patched twin (`--safe`), a false-positive baseline - ideally finds nothing |

All three run `0.0`–`1.0`, and for all three **higher is better** (`1.0` is perfect):

| Metric | Formula | Better | Reads as |
|---|---|---|---|
| **Precision** | `TP / (TP + FP)` | ↑ higher | of everything reported, how much was real. `0.38` = ~38% of findings were genuine, the rest noise. High = few false alarms. |
| **Recall** | `TP / (TP + FN)` | ↑ higher | of the bugs actually planted, how many were found. `0.73` = 8 of 11. High = few misses. |
| **F1** | `2 × P × R / (P + R)` | ↑ higher | harmonic mean of the two - the headline "overall quality" number. Only high when both are, so it penalises being noisy *and* missing bugs. |

The one inversion: on the **`safe-twin` leg there is nothing real to find**, so
every finding there is a false alarm - fewer is better, and an empty report is
the perfect score.

## Endpoint coverage

Recall tells you how many bugs a tool found. It cannot tell you **why** it missed
the rest - and the two reasons need opposite fixes:

| Miss | Meaning | What to fix |
|---|---|---|
| **discovery miss** | never reached the endpoint carrying the bug | the crawler |
| **analysis miss** | reached the endpoint, did not report the bug | the analysis |

Telling them apart needs a second input: the endpoints your tool says it found.
That is `endpoints/v1`, scored against each app's `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%というのは、スキャナーの問題ではなく発見の問題であり、単一のリコール数値では両者は同じように読めてしまいます。

数値を正直に保つための2つのルールがあります：

- **トランスポートは操作ではない。** 1回の `POST /graphql` は、その背後にある25個のGraphQL操作を実行するものではありません。1回のWebSocketハンドシェイクは、そのイベントを実行するものではありません。1回の `POST /api/runs` は、エージェントのツールを実行するものではありません。URLに到達することと、そこに存在するものを実行することは、別々に採点されます。
- **欠落したテレメトリはトラックを一切生成せず**、決して `0%` にはなりません。「これを測定しなかった」と「何にも到達しなかった」は、ツールに関する正反対の主張です。

何にも一致しない報告済みエンドポイントは精度を低下させますが、カバレッジを減らすことは決してないため、ワードリストをばらまいてもスコアを上げる方法にはなりません。完全なモデル：
[`dynast-bench/README.md#endpoint-coverage`](https://github.com/j3ssie/dynast-bench/blob/HEAD/dynast-bench/README.md#endpoint-coverage)

## ライセンス

`dynast-bench` は、**Vigolium** と **Gimora**（自律型オフェンシブセキュリティエージェント）をベンチマークするために [@j3ssie](https://github.com/j3ssie) が ♥ を込めて作成したものであり、[MITライセンス](https://github.com/j3ssie/dynast-bench/blob/HEAD/LICENSE) の下でリリースされています。