Authenticating With Your API

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"

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

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.