Vespasian: API Discovery and Specification Generation

Overview

Vespasian is an API discovery tool that maps attack surfaces from captured traffic and generates specifications for REST, GraphQL, SOAP, and WebSocket APIs. It captures traffic through headless browser crawling or imports it from proxy tools like Burp Suite, HAR archives, and mitmproxy, then classifies the requests, probes discovered endpoints, and outputs specifications in the native format for each API type.

Built for penetration testers and security engineers who need to map the API attack surface of applications when clients don't provide API documentation.

How It Works

Vespasian uses a two-stage pipeline that separates traffic capture from specification generation:

1. Capture — Drive a headless browser through the target application or import traffic from Burp Suite XML, HAR archives, or mitmproxy captures

2. Generate — Classify captured requests as API calls, probe endpoints for enrichment, execute JS static analysis to recover SPA-only endpoints, and produce structured API specifications (OpenAPI 3.0 for REST)

This separation means you capture once, generate many — run different generators against the same capture without re-scanning. The capture file is inspectable JSON for debugging.

Deterministic API Maps

API maps produced by Vespasian are deterministic: identical input yields identical output on every run. This applies to endpoint coverage, REST vs. non-REST classification, and the structure of the generated specification.

Previously, successive runs against the same capture could produce different API inventories — routes were silently dropped, and REST classification could vary between executions. These inconsistencies are resolved. You can now rely on Vespasian output to be stable and reproducible across runs, which makes it suitable for diffing captures over time, sharing results across teams, and integrating into automated workflows.

Specifically:

• Complete endpoint coverage — Routes that were previously omitted due to gaps in the mapping pipeline are now included.
• Stable REST classification — Whether a request is classified as REST or non-REST is consistent and based on deterministic heuristics, not run-to-run variation.
• Higher mapping fidelity — Endpoints that were previously miscategorized or absent from the generated specification are correctly represented.

SPA Endpoint Recovery

Single-page applications frequently embed API paths inside JavaScript bundles rather than issuing observable network requests during a crawl. Vespasian's generate step runs a JS static analysis pass to extract these paths — including endpoints assembled at runtime via string concatenation or service-prefix patterns — and folds them into the generated specification.

This analysis runs entirely from the captured snapshot. No outbound HTTP to the original target is required, which means:

• Teams working from shared captures receive the same endpoint coverage as those with direct target access.
• Endpoints are recovered even when the target is intermittently or permanently unavailable at generate time.
• Previously, concat/service-prefix SPA endpoints were silently dropped in these offline scenarios; they are now recovered automatically.

To enable SPA endpoint recovery, pass --probe --analyze-js to vespasian generate. No additional flags are needed; offline recovery is applied automatically when the target is unreachable.

Proxy Support

Vespasian supports routing all outbound traffic through an intercepting proxy with --proxy. This is useful when you want to observe, record, or manipulate Vespasian's requests in a tool such as Burp Suite or mitmproxy during a scan.

The --proxy flag covers every stage of the pipeline:

--proxy-insecure skips TLS verification and is honoured consistently across all stages.

Prior to the Vespasian release that introduced full proxy coverage, only crawl traffic was routed through the proxy; all subsequent stages built independent HTTP clients and bypassed it. If you previously observed incomplete traffic in your proxy, updating to the current version and re-running with --proxy will surface the full stream.

Key Capabilities

Traffic Capture

Drives a headless browser with JavaScript execution and authentication injection. Captures every HTTP request the frontend makes during real usage.

Traffic Import

Converts traffic from Burp Suite XML, HAR archives, and mitmproxy into the Vespasian capture format. Reuse work from manual testing sessions.

REST API Classification

Classifies observed requests as API calls based on content-type, static asset exclusion, path heuristics (/api/, /v1/), HTTP method analysis, and response structure. Classification is deterministic and consistent across runs for a fixed capture. Configurable confidence threshold.

OpenAPI Specification Generation

Generates OpenAPI 3.0 specs with path normalization (/users/42 becomes /users/{id}), schema inference from response bodies, and parameter extraction from query strings. Includes JS static analysis to surface endpoints embedded in JavaScript bundles, including string-concatenated and service-prefixed paths, with no live target required. Output is deterministic: the same capture produces the same specification on every run.

Quick Start

# Scan a web application end-to-end
vespasian scan https://app.example.com -o api.yaml

# With authentication
vespasian scan https://app.example.com -H "Authorization: Bearer <token>" -o api.yaml

# Route all traffic through an intercepting proxy
vespasian scan https://app.example.com --proxy http://127.0.0.1:8080 -o api.yaml

# Route through a proxy with a self-signed certificate
vespasian scan https://app.example.com --proxy http://127.0.0.1:8080 --proxy-insecure -o api.yaml

# Two-stage: capture then generate (includes offline JS analysis for SPA endpoint recovery)
vespasian crawl https://app.example.com -o capture.json
vespasian generate rest capture.json --probe --analyze-js -o api.yaml

# Import from Burp Suite (offline target — SPA endpoints recovered from snapshot)
vespasian import burp traffic.xml -o capture.json
vespasian generate rest capture.json --probe --analyze-js -o api.yaml

Use Cases

• Penetration testing without API documentation — Crawl the target, capture API calls, produce an OpenAPI spec

• Generating specs from proxy captures — Import existing Burp Suite or mitmproxy traffic from manual testing

• Intercepting the full scan with a proxy — Pass --proxy to route every stage of Vespasian's outbound traffic — crawl, active probing, JS-replay, and sourcemap fetches — through your intercepting proxy for inspection or manipulation

• Mapping API attack surface — Identify which endpoints a web application exposes by executing its JavaScript, including paths embedded in SPA bundles via string concatenation or service prefixes

• Shared-capture workflows — One team member captures traffic; others run generate against the same snapshot, including full SPA endpoint recovery, without needing access to the original target

• Repeatable, diffable API inventories — Because output is deterministic for a fixed capture, you can compare specifications across captures over time to track API surface changes

Installation

go install github.com/praetorian-inc/vespasian/cmd/vespasian@latest

Requires Go 1.24+.

Tracking Changes and Breaking Changes

Vespasian ships a hand-maintained CHANGELOG.md in the repository that serves as the canonical reference for user-visible changes across versions. It follows the Keep a Changelog format and adheres to Semantic Versioning.

Each release section records:

• Behavioral changes and new capabilities
• Breaking changes — including field-shape differences in capture.json that may affect downstream tooling or scripts that consume Vespasian output

Consult CHANGELOG.md before upgrading across major or minor versions, particularly if you have automation that parses or stores capture.json files, since breaking changes to that format are documented there.

The repository also includes CONTRIBUTING.md, which describes the changelog workflow for contributors. New entries are added under the [Unreleased] section per pull request and promoted to a versioned section at release time.

Learn More

Full documentation and CHANGELOG at github.com/praetorian-inc/vespasian.