GitHub Integration

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

GitHub Action

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

To integrate Mayhem for API into 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 & 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
        with:
          # fetch a greater number of commits for computing diffs between jobs
          fetch-depth: 50

      - 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:

GitHub

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 this
    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

Using our CLI

To upload our results to GitHub code scanning from anywhere, locally or from a CI, you can use our CLI. You'll need to pass a GitHub token with the security_event scope so that Mayhem for API can upload findings. See GitHub documentation on creating access tokens for more information. Once you have your token, simply run:

mapi run "<target>" "<duration>" "<spec>" --sarif "mapi.sarif" --github-token "<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/apps/mayhem-for-api

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:

https://github.com/ForAllSecure/api-fuzzer-swagger-petstore-demo