Postman Collections¶

Mayhem supports testing APIs that are specified in a Postman Collection. To get the most of out Postman, let's review terminology for supported Postman features.

1. The Postman API (API Key)¶

In order to access Postman Collections for your Postman Workspace, you will need an API Key.

To create a Postman API Key, please visit https://learning.postman.com/docs/developer/postman-api/authentication/.

To use your API Key, you must either set the POSTMAN_API_KEY environment variable (recommended):

POSTMAN_API_KEY=PMAK-1234... mapi run

or pass the value as an argument to mapi run:

mapi run ... --postman-api-key PMAK-1234

2. Postman Collection¶

A Postman Collection is a specification for how to interact with an API.

Mayhem can analyze an API using a Postman Collection ID directly (recommended). See https://support.postman.com/hc/en-us/articles/5063785095319-How-to-find-the-ID-of-an-element-in-Postman for details on how to find the ID of a Collection.

For example, a collection with id 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7d will be used to scan an API running on http://localhost:8080 with the following command:

mapi run my-api auto 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7d \
  --url http://localhost:8080

Alternatively, you can use an exported Postman Collection JSON file:

mapi run my-api auto /home/mayhem/api/postman_collection.json \
  --url http://localhost:8080

3. Postman Environment¶

A Postman environment is a set of variables that you can reuse in your requests and share with your team. You can reference them in request authentication, query and path parameters, request bodies, and scripts. Variables help you work efficiently, collaborate with teammates, and set up dynamic workflows.

Requests that use many of the Postman dynamic variables as path variables, headers, query parameters, or within a request body are handled by Mayhem and mapped to appropriate types during fuzzing.

When using an Environment with Mayhem, the variables in your Postman Collection will automatically be replaced with variables from your Environment when you specify an environment ID (or exported environment JSON file).

See https://support.postman.com/hc/en-us/articles/5063785095319-How-to-find-the-ID-of-an-element-in-Postman for instructions on how to get the ID of an environment.

For example, an environment with id 12345 will be used to inject values into variables from the collection 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7 with the following command:

mapi run my-api auto 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7d \
  --postman-environment 12345 \
  --url http://localhost:8080

Alternatively, you can use an exported Postman Environment JSON file:

mapi run my-api auto 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7d \
  --postman-environment /home/mayhem/api/envs/exported_postman_environment.json \
  --url http://localhost:8080

4. Postman Workspace Global Variables¶

Global variables enable you to access data between collections, requests, test scripts, and environments. Global variables are available throughout a workspace.

When using a Workspace Global Variables with Mayhem, the variables in your Postman Collection will automatically be replaced with global variables when you specify a workspace ID (or exported global variable JSON file).

See https://support.postman.com/hc/en-us/articles/5063785095319-How-to-find-the-ID-of-an-element-in-Postman for instructions on how to get the ID of a workspace.

For example, a workspace with id abcdef will be used to inject values into variables from the collection 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7 with the following command:

mapi run my-api auto 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7d \
  --postman-global-variables abcdef \
  --url http://localhost:8080

Alternatively, you can use an exported Postman Global Variables JSON file:

mapi run my-api auto 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7d \
  --postman-global-variables /home/mayhem/api/envs/exported_global_variables.json \
  --url http://localhost:8080

When using both global variables AND an environment, the environment will always take precedence over global variables if there is an overlap in variable keys.

Putting it all together¶

Using all of the above options, we can now analyze an API using a Postman Collection, environment, and workspace global variables with the following command:

export POSTMAN_API_KEY=PMAK-1234...

mapi run my-postman-api auto <postman collection id> \
  --url <url> \
  --postman-environment <postman environment id or exported environment> \
  --postman-global-variables <postman workspace id or exported global variables>

Postman Variables and Scripts¶

Postman has a scripting engine that is not supported by Mayhem.

Typically, these scripts are used to seed requests with values that are returned from another API's response. Mayhem uses API responses automatically during fuzzing.

It may be useful to fork a Postman collection that makes use of scripts, replace scripts with variables where possible, and target the forked collection with Mayhem.