For most APIs, the next step is setting up authentication. After all, without successfully authenticating, Mayhem for API can only test for very superficial problems! Giving the fuzzer a way to authenticate to the target API will enable it to exercise more endpoints and maximize coverage.
Mayhem for API has built-in support for basic authentication, header-based authentication (such as bearer tokens) and cookie-based authentication. If none of these are sufficient, our rewrite plugin system gives you a powerful option to implement whatever you need for your specific authentication scheme. All of these are described in more detail below. But first, a common gotcha...
If the credentials you use in fuzzing can be invalidated through a logout
endpoint, you will almost certainly need to prevent the fuzzer from issuing
requests to that endpoint, using the
--ignore-endpoint flag to
something like this:
mapi run [...] --ignore-endpoint "/api/logout"
ℹ️ For more details on this and other mechanisms for choosing which endpoints to fuzz, see Selective Route Testing.
is a simple technique for enforcing access control to web resources,
which is supported by most web servers. You can specify basic
authentication credentials when you fuzz your target with
with a command line option:
mapi run --basic-auth "username:password" <target> <duration> <specification>
... or as an environment variable:
export MAPI_BASIC_AUTH="username:password" mapi run <target> <duration> <spec>
Note that basic authentication does not protect the username and password by itself. They are simply encoded with base64 in transit, but not encrypted or hashed. Basic authentication should be used in conjunction with HTTPS to protect the credentials, or on a trusted network.
Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens The client must send this token in the Authorization header when making requests to protected resources:
mapi run --header-auth "Authorization: bearer <token>" <target> <duration> <spec>
In Mayhem for API, the same mechanism is generalized to work with any header-based authentication, for instance:
mapi run --header-auth "X-Custom: auth <token>" <target> <duration> <spec>
You can also use an environment variable to pass such headers:
export MAPI_HEADER_AUTH="Authorization:Bearer <token>" mapi run <target> <duration> <spec>
Note that the authorization header does not protect the token by itself. It is not encrypted or hashed before sending it to the server. As with basic authentication, this authentication method should be used in conjunction with HTTPS to protect the credentials, or on a trusted network.
ℹ️ To specify custom headers that do not contain credentials, use
--header-auth. Mayhem for API treats
--header-authdifferently when probing for issues, and when redacting potentially sensitive data.
Cookie authentication uses HTTP cookies to authenticate client requests
and maintain session information. Cookies are generally returned by the
server after a successful login, and sent by the clients in subsequent
requests. You can specify cookies when you fuzz your target with
mapi run with a command line option:
mapi run --cookie-auth "PHPSESSID=abe67cd" <target> <duration> <spec>
... or as an environment variable:
export MAPI_COOKIE_AUTH="PHPSESSID=abe67cd" mapi run <target> <duration> <spec>
Note that cookies are not encrypted or hashed before being sent to the server. As with basic and header authentication, this authentication method should be used in conjunction with HTTPS to protect the credentials, or on a trusted network.
For cases where the above built-in methods are insufficient (e.g. if the authentication is dynamic over the course of a fuzzing job), you can use our rewrite plugin system and code your own.
Rewrite plugins aren't authentication-specific and have lots of capabilities documented over here.
If the specification provided is a postman collection id, the Postman collection's authentication is used.
The authentication methods currently supported are
Authentication on folders or requests is not currently supported. Specifying authentication with arguments to Mayhem overrides Postman's authentication configuration.
We are planning on adding built-in support for more authentication methods soon, and we'd love to hear from you. Please reach out to us on Discord or by emailing email@example.com to let us know what you'd like to see!
At this point, Mayhem for API should be able to exercise even the authenticated endpoints of your API. Excellent!
ℹ️ 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.
We're not quite done, though. Most real-world APIs have other, non-authentication input requirements that are too specific to be reliably found through random fuzzing alone. The next section covers the why and the how of getting Mayhem for API to successfully exercise your entire API.