Skip to content

Integration with Atlantis Pull Request Automation

Atlantis is a pull request automation system designed to allow control of terraform execution from github commits.

We have designed two ways to integrate terrascan into an Atlantis setup: * Atlantis Workflow-based integration which sends scan requests to a independently running terraform server * Custom Atlantis container image which has terrascan built in

In either scenario, the configuration of Atlantis is a diverse topic which will vary from installation to installation. For details around installing, configuring, and using Atlantis, please refer to the Atlantis documentation.

Workflow-based integration

Through this method, you will modify or create a custom workflow for atlantis so your repositories will be scanned by terrascan as part of the pull request automation.

Requirements * The atlantis server must have TCP connectivity to where the terrascan server is running. * The curl command needs to be installed on the system so the terrascan-remote-scan.sh script can make the scan request. Atlantis's docker image has curl preinstalled.

Workflow

Next, you will need to modify your workflow to call terrascan-remote-scan.sh during the plan stage. In the plan below, the first three run: terraform commands are the default for an atlantis workflow; the fourth run terrascan-remote-scan.sh is where the terrascan scan is requested. The terrascan-remote-scan.sh script can be found under the scripts directory in this project; you will need to copy it to a location where it can be executed by the atlantis server. If the terrascan-remote-scan.sh script is not in the directory where the atlantis server command is being run to, you will have to specify the path to the script.

repos:
- id: /.*/
  workflow: terrascan

workflows:
  terrascan:
    plan:
      steps:
        - run: terraform init -input=false -no-color
        - run: terraform workspace select -no-color $WORKSPACE
        - run: terraform plan -input=false -refresh -no-color --out $PLANFILE
        - run: terrascan-remote-scan.sh
(the variables $WORKSPACE and $PLANFILE referenced in the above yaml are populated by atlantis)

Script configuration

Next, the terrascan-remote-scan.sh script will need to be modified for your environment. The script is located here. Open the script with your favorite editor and review the following six settings near the top of the file:

TERRASCAN_SERVER=192.168.1.55
TERRASCAN_PORT=9010
IGNORE_LOW_SEVERITY=false
IAC=terraform
IAC_VERSION=v14
CLOUD_PROVIDER=aws
Descriptions of these settings are as follows: * TERRASCAN_SERVER is the hostname or IP address of the host running the terrascan server. This will be used by the script to submit the scan request. * TERRASCAN_PORT is the TCP port which terrascan server is listening on. By default, this is 9010. * IGNORE_LOW_SERVERITY specifies if the terrascan-remote-scan.sh should fail a build if a low-severity finding is found. Some users will want to set this to true so they may ignore low-severity findings. * IAC, IAC_VERSION, and CLOUD_PROVIDER are terrascan options. Descriptions and valid values can be found by running terrascan scan -h.

Running atlantis

Run atlantis with your terrascan-workflow.yaml as a server-side repo configuration. This can depend on how you choose to deploy atlantis. If running the atlantis binary directly, note the following command:

$ atlantis server \
--atlantis-url="$URL" \
--gh-user="$USERNAME" \
--gh-token="$TOKEN" \
--gh-webhook-secret="$SECRET" \
--repo-allowlist="$REPO_ALLOWLIST" \
--repo-config=terrascan-workflow.yaml
(the variables in the example above must be set separately using export or similar shell methods)

Additionally, before the first pull request is processed, terrascan must be running in server mode:

terrascan server

Once the systems are running, when atlantis is called via pull request, or a comment of atlantis plan, terrascan will be called as part of the atlantis plan flow. Scan results will be placed in a comment on the pull request, and if issues are found the test will be marked as failed.

Custom Atlantis Container

We have come up with a custom container built on top of the official atlantis container image, that will allow users to run IaC scans with terrascan, besides the usual atlantis usage. There's a default atlantis workflow setup inside in the container to be used. Users may also override that default workflow using the --repo-config flag.

Usage

On the code repository's end, usage is exactly the same as atlantis, you comment atlantis plan and atlantis plan on your Pull Requests to trigger the custom atlantis-terrascan workflow.

To use our container image:
docker pull accurics/terrascan_atlantis
To build your own container image:
docker build ./integrations/atlantis -t <image_name>
Running the container:
docker run \
--env-file=<.env-file> \
-p 4141:4141 \
-v <pwd>/config_data/:/etc/terrascan/ \
accurics/terrascan_atlantis server \
--gh-user="$USERNAME" --gh-token="$TOKEN" --gh-webhook-secret="$SECRET" \
--repo-allowlist="$REPO_ALLOWLIST" \
-c /etc/terrascan/config.toml

The syntax of the atlantis server command here is same as in atlantis docs, except for an optional -c flag which can be used to pass in the toml config filepath for terrascan. Another way to provide the toml config filepath would be the TERRASCAN_CONFIG environment variable.

You need to provide all the environment variables that terraform requires to operate with your respective cloud providers. It's a good practice to use a specific tag of the container image rather than the latest tag.

The default workflow.yaml file used is the atlantis/workflow.yaml in this repo. You can override the default workflow using the --repo-config flag. It will be up to you how you want to trigger terrascan for your usage. You can do something along the lines of integrations/atlantis/workflow.yaml and integrations/atlantis/terrascan.sh itself.