Fuzz Your Own API
You've seen what Mayhem for API can do in a demo. Now it's time to fuzz your own!
To start testing an API, you only need to provide two things: a specification describing the API, and a URL where it can be reached. You'll be running something like:
mapi run my-api 30 <specification> --url <url>
API Specification
ℹ️ Specifications can be passed to
mapi
as either local files or URLs.
Mayhem for API is built around OpenAPI 3 specifications. If you have an OpenAPI
spec describing your API, you're all set. Pass either a URL or file system path directly to mapi
as the <specification>
argument!
If you don't have an OpenAPI spec, we support a few alternatives, described below.
OpenAPI 2.x (sometimes a.k.a. "Swagger")
mapi run
will automatically detect and work with older OpenAPI/Swagger specs.
Alternatively, you can do a one-time conversion into OpenAPI 3 by running
your old spec through the mapi convert swagger2
command (see mapi help convert swagger2
for details.)
Postman
Mayhem supports Postman collections. Read more about our Postman Collection support here.
HAR
If you don't have any of the above, you'll need to do a little bit more work to generate a spec for Mayhem for API to use. The process is documented in detail over here.
API URL
Mayhem for API needs to know the URL of your API server. Because the requests come
directly from the mapi
CLI tool running locally on your computer, this will
work for APIs that are:
- Behind a corporate firewall
- On localhost
- In a private network
- On the public internet
If the machine running the CLI can access the API - then we can fuzz it!
Proximity and Latency
Although it'll work in just about any configuration, Mayhem for API works better the "closer" it is (in network terms) to the API server. For the best results, this means pointing the fuzzer at a locally-running instance of your server.
Never, Ever, Ever Production
Mayhem for API has one job: finding ways to break an API! You should absolutely not give Mayhem for API the URL of your production services to test against.
Keeping Results Local
Organizations with Enterprise plans can run the mapi
CLI in 'local' mode by passing
the --local
flag to calls to mapi run
. This will fuzz your Target API, as usual,
with some caveats:
What is required to run Mayhem for API in local mode
- An active 'Enterprise' plan for the Organization member running the
mapi
CLI.
What is uploaded to Mayhem for API servers for local runs?
- Anonymized contributor seat counts
- API Target placeholder (if a matching target does not exist)
What is NOT uploaded to Mayhem for API servers for local runs?
- Job details (latency, covered endpoints)
- Issues (requests sent, responses received)
- Specifications for conversion (ie: HAR files will not be automatically uploaded and convert to a specification)
- Custom issue rules from third party integrations, such as OWASP ZAP API Scan rules
How do I get the results of a local run?
All report formats supported by the mapi
CLI will continue to work as described
in the the chapter about reporting issues, except for 'Web UI'
reporting -- because no results are uploaded the Mayhem for API service.
It is the responsibility of the caller to persist the results of local runs.
Files for conversion (no swagger2 → openapi)
All right, hopefully you've got Mayhem for API configured to test your API, congrats!
ℹ️ If we're already uncovering some issues in your API, you might want to take a detour into the chapter about issues, where we'll go into detail about those results.
For most real-world APIs, the next step is going to be telling Mayhem for API how to authenticate, which is what we'll cover next!