How to Write Your Own Mayhem for API Plugin

Ross Rogers
December 14, 2022
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.

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:

<code>Mapi</code> 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:

<pre><code class="language-c">token = get_my_system_token()
request.headers.append(Request.Header(name=b"authorization", value=token))
return request</code></pre>

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": "", "headers":[], "body":"body"}' \
'[::]:50051' \

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

"url": "",
"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.

Share this post

Fancy some inbox Mayhem?

Subscribe to our monthly newsletter for expert insights and news on DevSecOps topics, plus Mayhem tips and tutorials.

By subscribing, you're agreeing to our website terms and privacy policy.
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.

Add Mayhem to Your DevSecOps for Free.

Get a full-featured 30 day free trial.

Complete API Security in 5 Minutes

Get started with Mayhem today for fast, comprehensive, API security. 

Get Mayhem

Maximize Code Coverage in Minutes

Mayhem is an award-winning AI that autonomously finds new exploitable bugs and improves your test suites.

Get Mayhem