Best Practices & Troubleshooting

⚠️ Please do not attempt to fuzz any applications that are not owned or managed by you. The fuzz testing will look like an attack at worst and a probe at best to any organization that's not aware of what's happening. Please make sure to only fuzz your API assets. Thanks!

Here are some recommendations to maximize the value of fuzzing for your API:

  • Avoid running fuzzing against production services, as it can be HIGHLY disruptive. It generates a fair amount of load, and might delete resources you do not want deleted. We recommend using it on a QA or staging instance.

  • Populating the service with some realistic data will help the fuzzer uncover more issues.

  • Since the fuzzer may create many new entities in the service under state, resetting the state between runs will prevent the API from being bogged down by previous fuzzing state.


CLI Logging

The mapi CLI will print info level logs by default. You can control the logging verbosity in order to get more details about what the CLI os doing with the --verbosity flag.

For example, to log debug output, include the --verbosity debug flag before your subcommand:

     Must come BEFORE subcommand
mapi --verbosity debug run ...

You can also use the MAPI_LOG environment variable for the same effect.

MAPI_LOG=debug mapi run ...

Logging levels (not case sensitive) include:


Logging with trace level includes trace, debug, info, and higher.
Logging with debug level includes debug, info, and higher.
... etc


Looking at the job status using the CLI can help you understand what the fuzzer is doing, and if it's running into any issue.

  • The job logs will contain errors, if any. We aim to provide actionable feedback, making it obvious how to resolve the issue. For instance, the job log might contain messages about not being able to connect to the target API.

  • The endpoint coverage table can tell you a lot about what the fuzzer is able to exercise. Ideally you'd see all endpoints having 2xx response codes. If you don't, this means that the fuzzer could not generate a valid request. If you only see 401 unauthorized responses, then the fuzzer is having trouble with authentication. If you only see 400 response codes, that means the fuzzer could not generate a valid input for this endpoint, maybe because it was too complex to be generated by our fuzzer, or maybe because the specification did not match the behavior. If you're not sure why the fuzzer fails to generate 2xx responses, please reach out and we'll look into it and make the fuzzer better.

  • Sometimes, the job log will contain an error due to something on our end. Please feel free to reach out to if you run into one.

  • If you have a Swagger 2.0 specification, we will attempt to convert it to OpenAPI 3 for you. If this fails, you can also try using the swagger2openapi command line tool:

    npm install -g swagger2openapi
    swagger2openapi -p -y swagger-spec.json > openapi-spec.yaml
  • Consider specifying a Postman API key and collection ID instead of an exported Postman file for better fuzzing and more features. If you are using an exported Postman 2.x specification, we will attempt to convert it to OpenAPI 3 for you. If this fails, you can also try using postman-to-openapi.

Tracing Issues

Issues can be traced back to the specification. OpenAPI operationId, summary and tags are attached to issues. Likewise, Postman request ID, request name and folder are attached to issues.


In addition, please feel free to reach out to us on Discord or to if you have any issues, feedback of feature requests. We are happy to help!