Home

Vespasian: API Discovery and Specification Generation Tool

Vespasian discovers API endpoints by observing real HTTP traffic and generates API specification files from those observations. It captures traffic through headless browser crawling or imports it from existing sources (Burp Suite XML exports, HAR files, and mitmproxy dumps), then classifies requests, probes discovered endpoints, and outputs specifications in the native format for each API type: OpenAPI 3.0 for REST, GraphQL SDL for GraphQL, and WSDL for SOAP services.

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

Key Features

Feature	Description
REST API Discovery	Classifies REST endpoints via content-type, path patterns, and response structure; outputs OpenAPI 3.0
GraphQL API Discovery	Detects GraphQL endpoints, runs tiered introspection queries, and generates GraphQL SDL schemas
WSDL/SOAP Discovery	Identifies SOAP services via SOAPAction headers and envelope detection; fetches and parses WSDL documents
API Type Auto-Detection	Automatically determines API type (REST, GraphQL, WSDL) from captured traffic without manual selection
Browser Crawling	Two backends: a headless Chrome browser (go-rod) for full JavaScript/SPA support (default), or a dependency-free stdlib net/http engine via --headless=false for lightweight crawls
Traffic Import	Import existing captures from Burp Suite XML, HAR 1.2 files, and mitmproxy dumps
Active Probing	OPTIONS discovery, JSON schema inference, WSDL document fetching, and GraphQL introspection
Path Normalization	/users/42 and /users/87 become /users/{id} with known literal preservation (/me, /self)
SSRF Protection	Blocks probing of private and loopback addresses by default
Proxy Support	Route headless browser traffic through Burp Suite or other intercepting proxies
Two-Stage Pipeline	Capture once, generate many: separate capture and generation steps for maximum flexibility

Quick Start

# Crawl and generate an API spec in one step
vespasian scan https://app.example.com -o api.yaml

Wiki Navigation

• Installation — How to install Vespasian
• Quick Start Guide — Discover your first API in minutes
• CLI Reference — Complete command and flag reference
• REST API Discovery — How REST classification and OpenAPI generation works
• GraphQL Discovery — GraphQL detection, introspection tiers, and SDL generation
• SOAP WSDL Discovery — SOAP/WSDL identification and document generation
• Traffic Import Guide — Import from Burp Suite, HAR, and mitmproxy
• Use Cases — Penetration testing, attack surface mapping, and more
• Architecture — Two-stage pipeline design and package layout
• FAQ — Frequently asked questions
• Contributing — How to contribute to Vespasian