CI/CD Pipeline Guidelines

Guidelines for Integrating InsightCloudSec IaC functionality with a CI/CD Pipeline

General Guidelines

These steps are provided as general guidelines for an example CI/CD pipeline. While our larger example uses Jenkins, your specific pipeline and tooling and will need to be implemented based on the specifics of your environment. Keep in mind the following:

  • If you are writing your own script using the API instead of the CLI tool and want both HTML and JSON outputs, make a second request to the /scans endpoint using the build_id returned from the /scan endpoint (in the first request - see the steps below for more information). This endpoint always requires authentication, so make sure to pass an API key as specified on the Initiate IaC Scan reference page.
  • If you are serving HTML from your CI/CD platform, you may have to disable some content security features, as our HTML report includes some inline images and remotely-hosted images that are blocked by HTML-serving features of some CI/CD platforms.

📘

Integrations & Examples

IaC Security works most CI/CD pipelines and can be configured to use a variety of third-party tools as listed below (GitHub, Jenkins, CircleCI, etc).

The integrations included below are examples and as such may not reflect your specific environment. The Jenkins example walks through the details of a typical integration setup and sample implementation. Reach out to us with any questions you might have about implementing a setup in your specific environment.

AWS CloudFormation

1. Set up your CI/CD platform to trigger when code is pushed to the repository that hosts your CloudFormation templates.

2. Configure a step in your pipeline to send the JSON- or YAML-formatted CloudFormation template to the mimics scan function.

3. Save all results returned from these endpoints using your CI/CD platform's artifact-saving feature.

Terraform

1. Set up your CI/CD platform to trigger when code is pushed to your Terraform repository.

2. Configure a step in your pipeline to generate the Terraform plan as JSON with the commands terraform plan -out out.plan && terraform show -json out.plan > out.plan.json

3. Configure another step in your pipeline to send the JSON-formatted Terraform plan to the mimics scan function.

4. Save all results returned from these endpoints using your CI/CD platform's artifact-saving feature.

GitHub Action Integration

The InsightCloudSec Scan Github Action allows security and development teams to integrate infrastructure-as-code (IaC) scanning in their CI/CD pipelines through GitHub, check out the details on the GitHub marketplace page for this tool. An example of what this integration might look like follows.

on:
  push:
    # triggers on pushing to non-trunk branches
    branches-ignore:    
      - master
      - main

jobs:
  ics-scan-and-upload:
    name: insightCloudSec scan and upload
    runs-on: ubuntu-latest
    steps:
      - uses: actions/[email protected]
      - name: Scan cloudformation template
        uses: rapid7/[email protected]
        with:
          api_key: ${{ secrets.ics_api_key }}
          base_url: ${{ secrets.ics_base_url }}
          config_name: AWS CIS Benchmark 1.4
          scan_name: Scan on Push
          target: example.yml
      # recommended to surface results to Github Code Scanning
      - name: Upload SARIF file
        if: always()
        uses: github/codeql-action/[email protected]
        with:
          sarif_file: scan_output.sarif

Jenkins Integration (Example)

Jenkins's default content security policies don't allow Jenkins to serve the HTML generated by IaC without some configuration in advance. We require you to modify the content security policy if you want to serve the HTML directly from Jenkins. (Note: This integration is provided as an example setup and may vary based on your specific environment.)

To temporarily relax these policies, run

  • System.setProperty("hudson.model.DirectoryBrowserSupport.CSP", "default-src 'self'; style-src 'self' 'unsafe-inline'; font-src *; img-src *;") in the Jenkins Console.

Note: Changing content security policies in this way will only be effective until Jenkins's next startup.

📘

Value Names (DivvyCloud vs. InsightCloudSec)

Some values specified on this page use our former product name DivvyCloud vs. InsightCloudSec.

Updates to the naming of these configuration components will be communicated when changes are made.

Create a Jenkins Project

To configure a freeform Jenkins project to scan a template with IaC Security, you will need to set up a project using the steps below:

1. Click the "New Item" button.

2. Click "Freestyle Project" and enter a name.

809809

Jenkins Freestyle Project

3. Configure the integration with your version control system using the "Source Code Management" portion of the Project configuration page.

  • Configure Build Triggers as desired.

4. If your InsightCloudSec installation or script requires authentication to run IaC Security scans, choose credentials and bind them to environment variables in your build environment.

  • For our provided tool mimics, the expected flag is --api-key. You'll need to generate an API Key prior to setting up this integration.
  • IaC will require authentication to initiate scans if it is configured with the iac_auth_required variable set to 1 in the SystemSettings table.
16021602

Jenkins Build Environment Bindings

5. Configure an Execute Shell build step with the following command calling mimics.

  • If using Terraform:
# Generate a Terraform plan and convert it to JSON
terraform plan -out tf.plan
terraform show -json tf.plan > tf.plan.json

# Run our IaC script and configure it according to the docstrings in the script.
docker run \
-v $WORKSPACE:/data \
-e MIMICS_BASE_URL=$ICS_BASE_URL \
-e MIMICS_API_KEY=$ICS_API_KEY \
public.ecr.aws/rapid7-insightcloudsec/ics/mimics:latest scan \
data/tf.plan.json \
-p terraform \
-c "My IaC Config Name" \
--report-formats all \
--report-path "/data/reports" \
--no-progress
  • If using AWS CloudFormation:
# Run our IaC script and configure it according to the docstrings in the script.
docker run \
-v $WORKSPACE:/data \
-e MIMICS_BASE_URL=$ICS_BASE_URL \
-e MIMICS_API_KEY=$ICS_API_KEY \
public.ecr.aws/rapid7-insightcloudsec/ics/mimics:latest scan \
data/my_cft.yml \
-p cft \
-c "My IaC Config Name" \
--report-formats all \
--report-path "/data/reports" \
--no-progress

6. Configure a post-build action to archive the HTML and/or JSON output created by the command above.

735735

Post-build Actions

7. Click "Save".

Jenkins Pipeline

If you use Jenkins pipelines for configuration-as-code and repeatability benefits, check out the following example pipeline configurations for reference and modify to fit your needs.

AWS CloudFormation (Jenkins)

pipeline {
   agent any
 
   stages {
        stage('Submit CloudFormation Template to InsightCloudSec') {
            environment {
                ICS_BASE_URL = "https://<ICS Base URL>/"
                ICS_API_KEY = credentials("ics-api-key")
                WORKSPACE = "${env.WORKSPACE}"
            }
            steps {
                script {
                    try {
                        sh 'docker run -v $WORKSPACE:/data -e MIMICS_BASE_URL=$ICS_BASE_URL -e MIMICS_API_KEY=$ICS_API_KEY public.ecr.aws/rapid7-insightcloudsec/ics/mimics:latest scan data/my_cft.yml -p cft -c "My IaC Config Name" --report-formats all --report-path "/data/reports" --no-progress'
                    } catch (e) {
                        throw e
                    } finally {
                        archiveArtifacts 'reports/scan_output.*'   
                    }
                }
            }
        }
    }
}

Terraform (Jenkins)

pipeline {
   agent any
 
   stages {
       stage('Generate Terraform Plan') {
            steps {
                sh 'terraform plan -out tf.plan'
                sh 'terraform show -json tf.plan > tf.plan.json'
                stash includes: 'tf.plan.json', name: 'cloudsec-iac-security-stash'
            }
        }   
        stage('Submit Terraform Plan to InsightCloudSec') {
            environment {
                ICS_BASE_URL = "https://<ICS Base URL>/"
                ICS_API_KEY = credentials("ics-api-key")
                WORKSPACE = "${env.WORKSPACE}"
            }
            steps {
                unstash 'cloudsec-iac-security-stash'
                script {
                    try {
                        sh 'docker run -v $WORKSPACE:/data -e MIMICS_BASE_URL=$ICS_BASE_URL -e MIMICS_API_KEY=${{ ICS_API_KEY }} public.ecr.aws/rapid7-insightcloudsec/ics/mimics:latest scan data/tf.plan.json -p terraform -c "My IaC Config Name" --report-formats all --report-path "/data/reports" --no-progress'
                    } catch (e) {
                        throw e
                    } finally {
                        archiveArtifacts 'scan_output.html'   
                    }
                }
            }
        }
    }
}

CircleCI Integration (Example)

As is standard for CircleCI, you can easily define IaC analysis as a step in your pipelines by specifying it in your .circleci/config.yml file.

  • Below is a minimal example of a config.yml for reference.

Terraform (CircleCI)

version: 2
jobs:
  build:
    docker:
      # Here we use Hashicorp's Alpine image with terraform already installed
      - image: hashicorp/terraform:light

    steps:
      - checkout
      - run:
          name: InsightCloudSec IaC Security Scan
          command: |
            # Generate JSON-formatted Terraform plan
            terraform init
            terraform plan -out tf.plan
            terraform show -json tf.plan > tf.plan.json
            cd ..
            
            # Use the mimics Docker image
            docker run -v $(pwd):/data -e MIMICS_BASE_URL=$ICS_BASE_URL -e MIMICS_API_KEY=$ICS_API_KEY public.ecr.aws/rapid7-insightcloudsec/ics/mimics:latest scan data/tf.plan.json -p terraform -c "My IaC Config Name" --report-formats all --report-path "/data/reports" --no-progress

      # Store results. CircleCI caches this for 30 days.
      - store_artifacts:
          path: /tmp/scan_output.html

Viewing HTML Reports

From an IaC Security scan, InsightCloudSec produces a JSON blob that is described in our API documentation. We also produce an HTML report that's designed to be shared via your CI/CD pipeline and is optimized for your DevOps users.

A screenshot of that report is below. You can also download a sample report to review.

15781578

Example HTML IaC Security Report


Did this page help you?