> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# forallsecure/mapi

Probe your REST API with an infinite stream of test cases generated automatically from your OpenAPI specification or Postman collection.
Get a Mayhem for API token
1. [Sign up for Mayhem for API for free and install `mapi`](https://www.mayhem.security/get-started)
2. Create an [API Token](https://app.mayhem.security/-/settings/user/api-tokens)
3. Add the new API Token, with name `MAPI_TOKEN`, to your Circle CI project's Environment Variables.


## Commands

### scan

Automatically test your REST APIs with your OpenAPI specs and Postman collections


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api-spec` | string |  | Path to your Swagger 2.0 or OpenAPI 3.0 specification, or your Postman collection. Can be a URL or postman collection ID. |
| `api-url` | string |  | URL pointing to your running API you started before calling this action (don't fuzz your production API!) |
| `duration` | string | auto | Scan duration |
| `github-token` | env_var_name | GITHUB_TOKEN | github token for posting feedback |
| `html-report` | string | /tmp/mapi/report.html | HTML output path. Store the artifact using the `store_artifacts` step. |
| `ignore-exit-code` | boolean | false | The `mapi` CLI will exit with with code '1' if any High severity defects are detected in your run. Setting this to true will always exit with code '0', regardless of any discovered defects. |
| `junit-report` | string | /tmp/mapi/junit.xml | junit output path. Store the artifact using the `store_test_results` step. |
| `mapi-path` | string | $HOME/bin | The path to install the latest binary executable to. |
| `mapi-token` | env_var_name | MAPI_TOKEN | Mayhem for API service account token |
| `postman-api-key` | env_var_name | POSTMAN_API_KEY | A postman api key to authenticate with Postman's API. |
| `postman-environment-id` | string |  | A postman environment to use together with a postman collection. |
| `run-args` | string |  | A list of additional arguments (separated by '\n') to include in the call to 'mapi run'. Run 'mapi run --help' for a complete list of arguments. |
| `sarif-report` | string |  | SARIF (Static Analysis Results Interchange Format) report output path. Store the artifact using the `store_artifacts` step. |
| `target` | string |  | The organization-scoped name of your target, such as example/my-test-target. Auto-generated from your repository name if unspecified. |
| `zap-api-scan` | boolean | false | Include results from ZAP - API Scan. This run ZAP - API Scan and merge the results with your Mayhem for API results. |

## Jobs

### scan

Run Mayhem for API to check for vulnerabilities.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api-spec` | string |  | Path to your Swagger 2.0 or OpenAPI 3.0 specification, or your Postman collection. Can be a URL or postman collection ID. |
| `api-url` | string |  | URL pointing to your running API you started before calling this action (don't fuzz your production API!) |
| `duration` | string | auto | Scan duration |
| `github-token` | env_var_name | GITHUB_TOKEN | github token for posting feedback |
| `html-report` | string | /tmp/mapi/report.html | HTML output path. |
| `ignore-exit-code` | boolean | false | The `mapi` CLI will exit with with code '1' if any High severity defects are detected in your run. Setting this to true will always exit with code '0', regardless of any discovered defects. |
| `junit-report` | string | /tmp/mapi/junit.xml | junit output path. |
| `mapi-path` | string | $HOME/bin | The path to install the latest binary executable to. |
| `mapi-token` | env_var_name | MAPI_TOKEN | Mayhem for API service account token |
| `postman-api-key` | env_var_name | POSTMAN_API_KEY | A postman api key to authenticate with Postman's API. |
| `postman-environment-id` | string |  | A postman environment to use together with a postman collection. |
| `run-args` | string |  | A list of additional arguments (separated by '\n') to include in the call to 'mapi run'. Run 'mapi run --help' for a complete list of arguments. |
| `sarif-report` | string |  | SARIF (Static Analysis Results Interchange Format) report output path. Store the artifact using the `store_artifacts` step. |
| `target` | string |  | The organization-scoped name of your target, such as example/my-test-target. Auto-generated from your repository name if unspecified. |
| `zap-api-scan` | boolean | false | Include results from ZAP - API Scan. This run ZAP - API Scan and merge the results with your Mayhem for API results. |

## Executors

### default

Execute Mayhem for API on ubuntu.


## Examples

### scan

Run Mayhem for API to check for vulnerabilities.


```yaml
version: '2.1'
orbs:
  mapi: forallsecure/mapi@1.1.0
workflows:
  security:
    jobs:
      - mapi/scan:
          api-spec: your-openapi-spec-or-postman-collection.json
          api-url: http://localhost:8000
          run-args: |
            # Basic Auth
            --basic-auth
            login:password
            # Treat all warnings as errors
            --warnaserror
          sarif-report: /tmp/mapi/report.sarif
```