How to Integrate Mayhem for API Into Your Github Action Workflows

Mayhem for API comes with a GitHub Action and a GitHub App to help you check every change to your API for reliability, performance, and security issues. Our CLI can also upload Mayhem for API results to GitHub Code Scanning from any CI.

GitHub Action

With our GitHub Action, you'll get Mayhem for API testing with every API change in no time.

To integrate Mayhem for API into your GitHub Actions workflows:

1. Create a Service Account token for your organization
2. Add the newly created token to your GitHub secrets.
3. Create a workflow that starts your API and invoke the Mayhem for API action.

Configure Your Workflow

At the base directory of your code repository, add a .github/workflows/mapi.yml file to configure GitHub Actions to run Mayhem for API. Your file should look like this.

name: Mayhem for API
on:
push:
branches: [ main, master ]
pull_request:
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2

- name: Start your API
run: ./run_your_api.sh &
# ^-------------- update this, but keep the '&' to run
# the API in the background.

- name: Run Mayhem for API to check for vulnerabilities
uses: ForAllSecure/mapi-action@v1
with:
mapi-token: ${{ secrets.MAPI_TOKEN }}
api-url: http://localhost:8000 #<-update this
api-spec: your-openapi-spec-or-postman-collection.json #
^------ update this 

This configuration tells GitHub Actions to run a workflow which checks out your code, starts your API, and then runs Mayhem for API against your API. We pass the Mayhem for API token from the GitHub secret, MAPI_TOKEN.

Here's a fully working example repository showing you an ideal integration that you can use as a template. For more details on Mayhem for API Action, visit the Mayem for API Action in the GitHub Actions marketplace.

GitHub Code Scanning

If you are testing a public repository, or a private repository on a GitHub Enterprise plan, we recommend generating a SARIF report. Uploading SARIF reports to GitHub allows you to see any issue found by Mayhem for API in the "Security" tab of your repository.

In addition, if your API is sending back stacktraces as part of the error response body, Mayhem for API will show you exactly where in your code the issue happened, right in your PR diffs:

Using GitHub Action

To do so with our GitHub Action, after starting your API in the workflow, run the Mayhem for API action followed by github/codeql-action/upload-sarif@v1 to upload the report. Note continue-on-error needs to be set to true in the Mayhem for API action in order to run the next step, even if Mayhem for API finds issues.

- name: Run Mayhem for API to check for vulnerabilities
uses: ForAllSecure/mapi-action@v1
continue-on-error: true
with:
mapi-token: ${{ secrets.MAPI_TOKEN }}
api-url: http://localhost:8000 # <- update this
api-spec: your-openapi-spec-or-postman-collection.json #<-update
sarif-report: mapi.sarif

# Upload SARIF file (only available on public repos or github enterprise)
- name: Upload SARIF file
uses: github/codeql-action/upload-sarif@v1
with:
sarif_file: mapi.sarif

mapi run "" "" "" --sarif "mapi.sarif" --github-token ""

Mayhem for API will attempt to infer the git information from the environment set by the CI, and the git repository on the filesystem. If those are not available, Mayhem for API will ask you to pass the missing information so that it can upload the findings to the right place.

In addition, Mayhem for API also supports GitHub Enterprise on premise! Just pass --github-api-url <your-github-api-url> to mapi run so that Mayhem for API knows where to upload the results. Your GitHub instance needs to be accessible from the host running our CLI, but it does not need to be accessible by our cloud infrastructure.

GitHub Application

Installing the Mayhem for API GitHub App into your Personal or Organization GitHub account provides additional benefits by automatically updating the checks for your builds and pull requests with the result of your API Fuzzer jobs.

Install the GitHub app into your Personal or Organization repository by following the direct link:

https://github.com/ForAllSecure/mapi-action.

You must select which repositories you would like Mayhem for API to have access to. Once you have decided and authorized the app, we will attempt to automatically detect GitHub builds whenever you run the CLI as part of your build.

We do this by matching your git repository commit hash/branch/remote with repositories which you have given our app access.

If we cannot determine your repository settings, you may set them manually when calling mapi run with additional options such as --branch, --remote and --sha. See mapi run --help for a full listing.

To see an example of the GitHub App in action, please visit our example repository.