Skip to content

Tips & Troubleshooting

Warning

Please do not attempt to test any applications that are not owned or managed by you. The 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 test your own API assets. Thanks!

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

  • Avoid testing 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.

Troubleshooting

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
     v
mapi --verbosity debug run ...
                       ^
                       subcommand

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

MAPI_LOG=debug mapi run ...

Logging levels (not case sensitive) include: 

off
critical
error
warn
info
debug
trace

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

Runs

  • Run 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 run log will contain an error due to something on our end. Please feel free to reach out to support@forallsecure.com 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.

issue-specification-details

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

Suppressing Secret Headers

If sensitive details are leaking through the headers present in the requests to or responses from the service under test see Suppressing Header Secrets which explains how option --redact-header can mitigate this.