InsightCloudSec Docs

Welcome to the InsightCloudSec Docs!

InsightCloudSec by Rapid7 (formerly DivvyCloud) is a Cloud-Native Security Platform that provides real-time analysis and automated remediation for continuous security and compliance for your multi-cloud environment.

For questions reach out to us through [email protected].

Take Me to the Docs!    Release Notes

Using the IaC Analyzer (via the API)

Using the IaC Analyzer in CI/CD Pipelines via the API

Overview

The primary use case for IaC Security, for most users, is the automated use in CI/CD pipelines via the API. For a high-level overview of IaC Security (including prerequisites to get started) check out IaC Security Overview or take a look at the IaC Workflow.

Once an IaC Configuration has been created, users can begin scanning templates. We recommend using our Python script to run scans against the API. You can also use our API documentation to develop your own scripts if you like.

We provide suggested configuration instructions for Jenkins and general instructions for CI/CD platforms.

General CI/CD Guidelines

These steps are provided as general guidelines for most CI/CD pipelines. They will need to be implemented based on the specifics of your environment. Keep in mind the following, however:

  • If you are writing your own script 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.

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 InsightCloudSec /scan endpoint. We suggest using our script, but you can develop your own tools using our API documentation for reference. Note: The /scan endpoint expects a Terraform template by default, so ensure the provider is set to cft.

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 InsightCloudSec /scan endpoint. We suggest using our script, but you can develop your own tools using our API documentation for reference.

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

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.

Example HTML IaC Security ReportExample HTML IaC Security Report

Example HTML IaC Security Report

Jenkins Guidelines

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.

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.

Jenkins Freestyle ProjectJenkins Freestyle Project

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 script, the expected variable name is DIVVY_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.
  • Our provided script will require authentication if it is run with both --html_out and --json_out flags, as doing so will require a scan-getting request, which requires authentication for data security reasons.
Jenkins Build Environment BindingsJenkins Build Environment Bindings

Jenkins Build Environment Bindings

5. Configure an Execute Shell build step with the following command calling our Python script.

  • 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.
python3 iac_api.py <InsightCloudSec Base URL> <Config Name> tf.plan.json \
--provider terraform \
--auth_for_submission \ # only required if your InsightCloudSec IaC installation requires auth
--html_out scan_output.html \
--json_out scan_output.json
  • If using AWS CloudFormation:
# Run our IaC script and configure it according to the docstrings in the script.
python3 iac_api.py <InsightCloudSec Base URL> <Config Name> <CFT Template> \
--provider cft \
--auth_for_submission \ # only required if your InsightCloudSec IaC installation requires auth
--html_out scan_output.html \
--json_out scan_output.json

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

Post-build ActionsPost-build Actions

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

pipeline {
   agent any
 
   stages {
        stage('Submit CloudFormation Template to InsightCloudSec') {
            steps {
                script {
                    try {
                        sh 'python3 iac_api.py <InsightCloudSec Base URL> <Configuration Name> <CFT Template> --provider cft --auth_for_submission --html_out scan_output.html'
                    } catch (e) {
                        throw e
                    } finally {
                        archiveArtifacts 'scan_output.html'   
                    }
                }
            }
        }
    }
}

Terraform

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') {
            steps {
                unstash 'cloudsec-iac-security-stash'
                script {
                    try {
                        sh 'python3 iac_api.py <InsightCloudSec Base URL> <Configuration Name> tf.plan.json --provider terraform --auth_for_submission --html_out scan_output.html'
                    } catch (e) {
                        throw e
                    } finally {
                        archiveArtifacts 'scan_output.html'   
                    }
                }
            }
        }
    }
}

CircleCI Guidelines

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. The script assumes that you have put our Python script into the repository to be analyzed and can use it for analysis.

Terraform

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: |
            # Install Python and pip, and give them non-3-suffixed names
            apk add python3
            python3 -m ensurepip
            if [ ! -e /usr/bin/pip ]; then ln -s pip3 /usr/bin/pip ; fi
            if [ ! -e /usr/bin/python ]; then ln -sf /usr/bin/python3 /usr/bin/python; fi

            # Upgrade pip and install requests
            pip install -U pip
            pip install requests

            # Generate JSON-formatted Terraform plan
            terraform init
            terraform plan -out tf.plan
            terraform show -json tf.plan > tf.plan.json
            cd ..
            
            # Use script in repository to POST the plan to DivvyCloud
            ./api_test.py <InsightCloudSec Instance URL> <InsightCloudSec IaC Configuration name> tf.plan.json\
              --html_out /tmp/scan_output.html

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

Updated 18 days ago

Using the IaC Analyzer (via the API)


Using the IaC Analyzer in CI/CD Pipelines via the API

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.