Jenkins Integration

The Mayhem for API CLI or Docker Image is built to run on any Continuous Integration platform. "Jenkins pipelines" are the most common way to build and test your software on Jenkins today. This guide will describe how to configure a Jenkins Pipeline to run Mayhem for API against your API.

Configure Secrets

You will need an API token to run Mayhem for API in your Jenkins pipeline:

  1. Create a Service Account token for your organization
  2. Add the newly created token as a "Secret text" entry in Jenkins Credentials named MAPI_TOKEN

Configure your pipeline

This will demonstrate how to run mAPI against an API that built and run in a Jenkins scripted pipeline.

Run with Docker

In this scripted pipeline, after building and testing your API, a local instance is started and scanned by "Mayhem for API", using the Docker Hub mapi image.

// Run the build on a node with the 'docker' label
node("docker") {
  checkout scm

  // MAPI_TOKEN - The API Token secret text added to Credentials 
  withCredentials([
      string(credentialsId: "${MAPI_TOKEN}", variable: "MAPI_TOKEN")
      ]) {
      
    //  
    // 1. BUILD AND TEST YOUR API HERE
    //
    
    stage("Run Mayhem for API") {
        //
        // 2. Start your API
        //    eg. http://localhost:8080/api
        //

        
        //
        // 3. Run Mayhem for API
        //
        sh '''
          docker run -t --rm \
            --network=host \
            -e MAPI_TOKEN=${MAPI_TOKEN} \
            -e NO_COLOR=true \
            forallsecure/mapi:latest \
            run my-api auto <path_to_openapi_spec> \
            --url 'http://localhost:8080/api' \
            --junit results.xml
        '''

        //
        // 4.  Collect junit results
        //
        junit testResults: 'results.xml'
        
    }
  }
}

Run with CLI

This example is nearly identical as the one above, except we will use the compiled mapi CLI, rather than a Docker container to run the scan.

It is recommended to take advantage of Jenkins Tool Installer support for the most robust setup, but for simplicity we will download the CLI as part of our pipeline.

// Run the build on a node with the 'docker' label
node("docker") {
  checkout scm

  // MAPI_TOKEN - The API Token secret text added to Credentials 
  withCredentials([
      string(credentialsId: "${MAPI_TOKEN}", variable: "MAPI_TOKEN")
      ]) {
      
    //  
    // 1. BUILD AND TEST YOUR API HERE
    //  
    
    stage("Run Mayhem for API") {
        //
        // 2. Start your API
        //    eg. http://localhost:8080/api
        //

        //
        // 3. Download the CLI (or use Jenkins Tools)
        //
        sh '''
         curl -Lo mapi https://mayhem4api.forallsecure.com/downloads/cli/latest/linux-musl/mapi \
           && chmod +x mapi
        '''
        
        //
        // 4. Run Mayhem for API
        //
        sh '''
          mapi run my-api auto <path_to_openapi_spec> \
            --url 'http://localhost:8080/api' \
            --junit results.xml
        '''

        //
        // 5.  Collect junit results
        //
        junit testResults: 'results.xml'
        
    }
  }
}