## 앱 실행 (`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`) - ground truth가 대상으로 하는 표준 다중 서비스 토폴로지(앱 + Postgres/Redis 등을 별도 컨테이너로 포함).
- **Standalone** (`make solo`) - 앱당 하나의 자체 포함 이미지(`vuln/Dockerfile.standalone`)로, 데이터스토어와 내부 SSRF 싱크가 내장되어 있어 `docker build` + `docker run`만으로 compose 없이 동작합니다. 동작 방식과 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`는 앱이 노출하는 **각 작업(operation)별로 하나의 항목**을 기록하며, 취약한 작업과 정상적인 작업을 모두 포함합니다. 이는 [엔드포인트 커버리지](#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/)에는 즉시 점수를 매길 수 있는 파일이 들어 있습니다. 발견 실행 결과, 오탐(false-positive) 실행 결과, 세 개의 엔드포인트 추적 파일, 그리고 두 개의 빈 템플릿이 있으며, 각각 생성되는 숫자와 함께 문서화되어 있습니다.```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 + plugin       | 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, 내부 서비스          | [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` 백엔드를 제공하여 확률적 모델에서도 ground-truth PoC가 결정적으로 유지되도록 합니다.

공유 도메인 모델, OWASP Top 10 적용 범위 매트릭스, 벤치마크 설계 원칙(근접 실패, taint 거리, 로직 전용 버그)은 [`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개의
  근접 실패(near-miss), 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` leg에는 실제로 찾을 것이 없으므로**, 그곳의 모든 발견은 오탐입니다 - 적을수록 좋으며, 빈 보고서가 완벽한 점수입니다.

## 엔드포인트 커버리지

Recall은 도구가 찾은 버그의 수를 알려줍니다. 나머지를 놓친 **이유**는 알려주지 못합니다 - 그리고 두 가지 이유는 반대되는 수정이 필요합니다:

| 누락 | 의미 | 수정 대상 |
|---|---|---|
| **탐색 누락** | 버그가 있는 엔드포인트에 도달하지 못함 | 크롤러 |
| **분석 누락** | 엔드포인트에 도달했지만 버그를 보고하지 않음 | 분석 |

이 둘을 구분하려면 두 번째 입력이 필요합니다: 도구가 발견했다고 보고한 엔드포인트입니다.
그것이 `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에 도달하는 것과 그곳에 존재하는 것을 실행하는 것은 별도로 점수가 매겨집니다.
- **누락된 텔레메트리는 전혀 트랙을 생성하지 않으며**, 절대 `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)에 따라 배포됩니다.