How to use a HAR file with Mayhem for API

Welcome to Mayhem Tips and Tricks series! Our goal is to help you learn about the best features of Mayhem in small bite-size chunks. Today, we’ll talk about what a HAR file is, how to create one, and how to convert it into an API spec to use with Mayhem for API.

HTTP Archive (HAR)

HAR files, or HTTP Archives, at their core, essentially record traffic between a client and a website. In our use case, this is helpful to record API requests that are made as part of normal user interaction with a website, and responses that are sent by the API. It is possible to fuzz an API without a specification by recording transactions with the API as an HTTP Archive (.har file) and converting the recording into an OpenAPI specification. While this enables fuzzing of APIs without specifications, there is a trade-off in the accuracy of the converted specification compared with one generated from the code or maintained by hand.

HAR Files may contain sensitive information

:warning: HAR files contain everything that was sent between your client/browser and the target API. This may include Authorization headers, cookies, etc. It is not advisable to persist or convert a .har file unless it has been stripped of sensitive information beforehand.

Create a .HAR recording with your Browser

If you have a web frontend that interacts with your API, you can record an HTTP Archive by navigating your website and running through various use cases to build a recording of API interactions based on which features you access from the frontend.

Most modern browsers support recording your interactions and exporting a HAR file. See HAR Analyzer for browser-specific details. In our example, we’ll be using Chrome:

  1. Start Chrome and open the Network Debugger (Ctrl+Shift+I):
  2. Click Network Tab and Enable “Preserve Log”
  3. Start interacting with your web application in as many ways as you can think of.
  4. When you’re finished, right-click and save the interaction as a HAR file.

Converting a .HAR to an OpenAPI 3 specification

The mapi convert command is used to convert from other formats to an OpenAPI 3 specification. The following command converts a recording, recording.har into an OpenAPI spec, openapi.yaml:

mapi convert har recording.har --host "127.0.0.1:8080" --base-path "api/v1" --out openapi.yaml

Let’s examine the arguments:

--host "127.0.0.1:8080"

The conversion will attempt to infer the URL of your API from the recording. If the recording contains requests to multiple URLs, you can specify the --host option to restrict conversion to requests that are only from the specified host.

--base-path "api/v1"

If your API has a common base path this option will strip the common prefix from all request URLs. This can significantly improve the accuracy of the converted spec.

--out opennapi.yaml

This will overwrite any existing file, openapi.yaml, with the converted specification. Without this argument, the conversion will be printed to standard out in your terminal.

See all available options with the mapi convert --help command

Upon successful conversion you may inspect the converted file and make any modifications you feel are necessary or start a new run immediately.

mapi run my-api auto openapi.yaml --url http://127.0.0.1:8080/api/v1

And there you have it. We hope that you found this Tips and Tricks article helpful. If you have any questions, please email us at support@forallsecure.com.

Sincerely,

Your ForAllSecure Customer Success Team