Authenticating With Your API

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...

Accidental Credential Invalidation

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 mapi run, 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.

Basic Authentication

Basic access authentication 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 mapi run 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.

Header Authentication (e.g. Bearer Tokens)

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 instead of --header-auth. Mayhem for API treats --header-auth differently 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.

Authentication Using Rewrite Plugins

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.

Postman Authentication

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.

More to come!

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 support@forallsecure.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.