Discovery
Audit API routes from an exposed OpenAPI spec
swagger-jacker is a Bishop Fox command-line tool, written as sj, that audits exposed Swagger and OpenAPI definition files by checking which API endpoints they reveal and whether access requires authentication, with command templates to drive manual testing.
installgo install github.com/BishopFox/sj@latest
Go · MIT license
overview
What swagger-jacker does
Place swagger-jacker after you locate an exposed Swagger or OpenAPI definition and before fuzzers or template scanners that need concrete routes.
Operators use it when a leaked spec lists methods and paths that would otherwise need guessing. Point --url or --local-file at the definition, then pick a command mode.
Modes cover endpoints listing, automate replay, brute for the definition file, convert to URL lists, and prepare curl stubs. Pair with a crawler when the spec itself is still missing.
source github.com/BishopFox/sj
use cases
Where swagger-jacker fits
Turn a leaked spec into a route list
Run the endpoints command against a discovered Swagger or OpenAPI file to extract every documented path and method as structured data the workflow can act on.
Replay documented requests to audit the live API
Use automate mode to send a request to each endpoint the definition declares, with --rate limiting and a --proxy so the traffic stays controlled and observable.
Locate an undiscovered definition file
Point brute mode at a host to probe common paths where a Swagger or OpenAPI file tends to live, then audit the spec once it turns up.
Test against a separate host
Set --target to a host that differs from where the documentation lives, useful when a spec is served from a CDN but the API runs elsewhere.
Hand the routes to another tool
Use convert mode to write the spec out as a plain list of URLs, or prepare mode to emit curl commands, so a fuzzer or scanner downstream can consume the endpoints cleanly.
reference
swagger-jacker inputs and flags
| Name | Type | Flag | Description |
|---|---|---|---|
| url | STRING | --url | Load the documentation file from a URL. |
| local-file | FILE | --local-file | Load the documentation from a local file. |
| command | STRING | · | Mode to run: automate, brute, convert, endpoints, or prepare. |
| target | STRING | --target | Set a request target if it differs from where the docs reside. |
| format | STRING | --format | Format of the definition file (json, yaml, yml, js). |
| rate | STRING | --rate | Limit the number of requests per second (default 15). |
| headers | STRING | --headers | Add custom headers in Name: Value form, repeatable. |
| proxy | STRING | --proxy | Proxy host and port, for example http://127.0.0.1:8080. |
Showing key inputs. swagger-jacker exposes 15 inputs in total.
Full flag reference (15 inputs)
| Name | Type | Flag | Description |
|---|---|---|---|
| url | STRING | --url | Load the documentation file from a URL. |
| local-file | FILE | --local-file | Load the documentation from a local file. |
| command | STRING | · | Mode to run: automate, brute, convert, endpoints, or prepare. |
| target | STRING | --target | Set a request target if it differs from the host the documentation resides on. |
| format | STRING | --format | Format of the definition file: json, yaml, yml, or js (default json). |
| base-path | STRING | --base-path | Set the API base path if the definition omits it, for example /V2/. |
| rate | STRING | --rate | Limit the number of requests per second (default 15). |
| timeout | STRING | --timeout | Request timeout period in seconds (default 30). |
| headers | STRING | --headers | Add a custom header in Name: Value form; repeatable. |
| agent | STRING | --agent | Set the User-Agent string sent with each request. |
| randomize-user-agent | BOOLEAN | --randomize-user-agent | Randomize the User-Agent string (default false). |
| proxy | STRING | --proxy | Proxy host and port, for example http://127.0.0.1:8080. |
| insecure | BOOLEAN | --insecure | Ignore server certificate validation. |
| safe-word | STRING | --safe-word | Exempt the given word from the dangerous-word check; repeatable. |
| quiet | BOOLEAN | --quiet | Do not prompt for input; use default values for all requests. |
example
Run swagger-jacker
# list every route the exposed spec declares
sj endpoints --url https://example.com/v2/swagger.json
# replay each documented request through Burp, rate-limited
sj automate --url https://example.com/v2/swagger.json --proxy http://127.0.0.1:8080 --rate 10GET https://example.com/api/v2/users
POST https://example.com/api/v2/users
GET https://example.com/api/v2/users/{id}
PUT https://example.com/api/v2/users/{id}
DELETE https://example.com/api/v2/users/{id}
GET https://example.com/api/v2/orders
POST https://example.com/api/v2/orders/{id}/refund
GET https://example.com/api/v2/admin/configguidance
Choosing swagger-jacker
Reach for swagger-jacker once you have a Swagger or OpenAPI definition to audit. Spec-driven only. For routes without a definition, use ffuf. To find the definition first, crawl with katana or run brute mode.
katana
Crawls an app to find the spec and other endpoints. Locate the definition, then audit it here.
ffuf
Brute-forces routes without a spec. Use when no definition file exists.
nuclei
Template-based issue checks. Run after routes are enumerated from the spec.
faq
swagger-jacker questions
related
More Discovery tools
apkurlgrep
Extract URLs and endpoints from Android APK files.
cariddi
Crawl a domain list and scan responses for endpoints, secrets, tokens, and juicy files.
crawlergo
Browser-driven crawler that harvests requests for downstream scanners.
dirsearch
Web path scanner.
fallparams
Crawl pages, harvest potential parameters, write a custom wordlist.
feroxbuster
Recursive content discovery with smart defaults and rich response filters.
Run swagger-jacker yourself
An exposed spec URL feeds Swagger Jacker, which enumerates and tests the documented routes and writes the audited endpoints as an output.
Facts on this page come from the live Trickest tool library.