Authenticating With Your API

For most APIs, the next step is setting up authentication. After all, without successfully authenticating, Mayhem 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 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"

Info

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

Info

To specify custom headers that do not contain credentials, use --header instead of --header-auth. Mayhem 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 an API testing job), you can use our rewrite plugin system and code your own.

Rewrite plugins aren't authentication-specific and have lots of capabilities documented.

Postman Authentication

If the specification provided is a postman collection id, the Postman collection's authentication is used.

The authentication methods currently supported are - API Key - Bearer Token - Basic Auth - OAuth 2.0 (Token must be synced)

Authentication on folders or requests is not currently supported. Specifying authentication with arguments to Mayhem overrides Postman's authentication configuration.

Mutual TLS

By default, mapi automatically supports traditional “one-way” TLS, where just the server shares its certificate.

With mutual TLS (mTLS), both the client and the server present their certificates and choose to trust each other based on their trusted certificate authorities (CAs).

The mapi CLI supports both one-way TLS and two-way mTLS to communicate with your target API.

Example - RSA, SEC1 Elliptic Curve or PKCS#8

• --ca-cert (optional) The CA certificate belonging to the CA that signed the server’s certificate (if it is not already included with your OS trusted certs)
• --cert Your client certificate
• --key Your client private key

mapi run [...] --ca-cert ca.crt --cert client.crt --key client.key

If you have combined your client cert and key into a single .pem file you may use that instead for the --cert argument.

mapi run [...] --cert client.pem

Example - PKCS #12 (p12/pfx)

• --ca-cert (optional) The CA certificate belonging to the CA that signed the server’s certificate (if it is not already included with your OS trusted certs)
• --p12cert Your PKCS #12 archive file
• --p12password Password to decrypt archive certificate

mapi run [...] --ca-cert ca.crt --p12cert client.p12 --p12password "SECRET"

Note that p12password can be injected as an environment variable if desired

export P12_PASSWORD=SECRET
mapi run [...] --p12cert client.p12

Suppressing Header Secrets

If, for any reason, a header being generated by the service under test is sensitive and should be scrubbed or sanitized from reports, option --redact-header is available. This option will cause the CLI to replace any value of the header with <REDACTED>.

For example, passing --redact-header "x-my-proxy-token" would change the value of every request or response header with the name x-my-proxy-token to <REDACTED>. If a request had a header like x-my-proxy-token: Foo-42, the reports of that header would read asx-my-proxy-token: <REDACTED>.

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 should be able to exercise even the authenticated endpoints of your API. Excellent!

Info

If we're already uncovering some issues in your API, you might want to take a detour into Identifying Buggy Endpoints, 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 to successfully exercise your entire API.