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.
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.
* The atlantis server must have TCP connectivity to where the terrascan server is running.
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.
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
$PLANFILEreferenced in the above yaml are populated by atlantis)
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
TERRASCAN_SERVERis 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_PORTis the TCP port which terrascan server is listening on. By default, this is
IGNORE_LOW_SERVERITYspecifies if the
terrascan-remote-scan.shshould fail a build if a low-severity finding is found. Some users will want to set this to
trueso they may ignore low-severity findings. *
CLOUD_PROVIDERare terrascan options. Descriptions and valid values can be found by running
terrascan scan -h.
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
exportor similar shell methods)
Additionally, before the first pull request is processed, terrascan must be running in
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.
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
--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