Mayhem for API GitHub Action

A GitHub Action for using Mayhem for API to check for reliability, performance and security issues in your APIs.

About Mayhem for API

🧪 Modern App Testing: Mayhem for API is a dynamic testing tool that catches reliability, performance and security bugs before they hit production.

🧑‍💻 For Developers, by developers: The engineers building software are the best equipped to fix bugs, including security bugs. As engineers ourselves, we're building tools that we wish existed to make our job easier!

🤖 Simple to Automate in CI: Tests belong in CI, running on every commit and PRs. We make it easy, and provide results right in your PRs where you want them. Adding Mayhem for API to a DevOps pipeline is easy.

Want to try it? Sign up for free today!

Usage

1. Get a Mayhem for API token

   a. Sign up for Mayhem for API for free and install mapi

   b. Create a service account token using the Mayhem for API CLI

     mapi organization service-account create <your-org> <service-account-name>
   

   c. Add your service account token with name MAPI_TOKEN on your repository's GitHub page at Settings → Secrets → New repository secret

2. Create a file in your GitHub repository at:

    .github/workflows/ForAllSecure-Mayhem-for-API.yml

3. Add the following text to the file and tweak it for your codebase

name: Mayhem for API
on:
    push:
    pull_request:
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2

    - name: Start your API
      run: ./run_your_api.sh & # <----------------------------------- UPDATE THIS

    - 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

4. Commit the new file and push it up to GitHub

5. Your new Mayhem for API action will be visible at

   https://github.com/<USERNAME>/<REPO_NAME>/actions

This repo contains a full example for reference.

The action accepts the follow inputs:

  run-args: |
    # Basic Auth
    --basic-auth
    login:password

Continuing on error

The above examples will fail the workflow when issues are found. If you want to ensure the Action continues, even if Mayhem for API found issues, then continue-on-error can be used.

name: Mayhem for API
on:
    push:
    pull_request:
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2

    - name: Start your API
      run: ./run_your_api.sh &

    - 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
        # Additional 'mapi run' arguments
        run-args: |
          # Basic Auth
          --basic-auth
          login:password
          # Do not fuzz the '/logout' endpoint
          --ignore-endpoint
          /logout
          # Treat all warnings as errors
          --warnaserror

Reports

Mayhem for API generate reports when you pass sarif-report or html-report to the input. Make sure to pass continue-on-error to the Mayhem for API step if you want to process the reports in follow-up steps.

Artifact HTML Report

To artifact the report in your build, add this step to your pipeline:

- 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
    html-report: mapi.html

# Archive HTML report
- name: Archive Mayhem for API report
  uses: actions/upload-artifact@v2
  with:
    name: mapi-report
    path: mapi.html

GitHub Code Scanning support

Uploading SARIF reports to GitHub allows you to see any issue found by Mayhem for API right on your PR, as well as in the "Security" tab of your repository. This currently requires you to have a GitHub Enterprise Plan or have a public repository. To upload the SARIF report, add this step to your pipeline:

- 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

If your API server sends back stacktraces in the 500 Internal Server Error (only do this in a test environment -- never in production!), Mayhem for API will try to map issues it finds to the exact line of code that triggered the issue.