ForAllSecure Blog

How to Write Your Own Mayhem for API Plugin

Mayhem for API can’t even begin to imagine every single configuration of an API. Working systems grow and add layers of complexity with all sorts of different configurations.

Sometimes an API service has an exotic authentication protocol, or nonce values need to be carefully managed in the headers of requests, or you have to go through a load balancer with minute-by-minute expiring access tokens. Perhaps a system is quirky and some would call it a “legacy system”.

If you have any one of these scenarios, or something completely different, then Mayhem for API supports the writing of your own plugins to guide Mayhem for API into making legitimate requests to your API.

How do Rewrite Plugins Work?

Normally, the Mayhem for API program, mapi, generates requests to your API like:

With a rewrite plugin, mapi sends the generated request to your plugin for tweaking:

Mapi sends the url, headers, and body of the generated request to the plugin over the gRPC protocol. The plugin receives this request, modifies the request, and sends it back. After this, mapi forwards the modified request on to the API Under Test.

Writing a Plugin

The heart of a plugin to modify the request is as simple as the following python code:

token = get_my_system_token()
request.headers.append(Request.Header(name=b"authorization", value=token))
return request

Around this plugin heart is the boilerplate of a gRPC program. For this boilerplate we have complete examples written in Python, Java, and Rust. It is recommended to copy one of these examples and modify the rewrite method.

Once you get a rewrite plugin running, you can test that it does what you want using grpcurl, which is like curl, but for gRPC. You will need to be in a directory with the file request-rewrite-plugin.proto, which is the gRPC specification for a mapi rewrite plugin and then you can run:

grpcurl \
    -plaintext  \
    -proto request-rewrite-plugin.proto \
    -d '{"url": "http://example.com", "headers":[], "body":"body"}' \
    '[::]:50051' \
    mapi.rewrite.RewritePlugin/Rewrite

If successful, the response will look something like the following, with base64-encoded values for the header like:

{
  "url": "http://example.com",
  "headers": [
    {
      "name": "eC1ub25jZQo=",
      "value": "NDIK"
    }
  ],
  "body": "body"
}

 

Using a Plugin

Once you have a functioning plugin, you run the plugin as a parallel service to mapi and pass in the gRPC URL to mapi with the --rewrite-plugin option:

mapi run [...] --rewrite-plugin http://localhost:50051

Your API Under Test should now receive your HTTP request tweaks and hit more interesting pieces of your API.

More details may be found in our docs and our mapi examples repository.