Documentation

• 1: Getting Started
• 2: Usage
• 2.1: Command Line Options
• 2.2: Server mode
• 2.3: In-file Instrumentation
• 2.4: Configuration File
• 3: Integrations
• 3.1: Kubernetes Admission Controller
• 3.2: Argo CD
• 3.3: Atlantis PR Automation
• 3.4: GitHub and GitLab
• 3.5: Pre-commit hook
• 4: Architecture
• 5: Policies
• 5.1: Policy Overview
• 5.2: AWS Policies
• 5.3: Azure Policies
• 5.4: GCP Policies
• 5.5: GitHub Policies
• 5.6: Docker Policies
• 5.7: Kubernetes Policies
• 6: Contribution Guidelines
• 7: Changelog

1 - Getting Started

Terrascan is a static code analyzer for Infrastructure as Code. It can be installed and run in a number of different ways, and is most commonly used in automated pipelines to identify policy violations before insecure infrastructure is provisioned.

Running Terrascan for the First Time

Quickly get started with these common first tasks:

• Installing Terrascan
• Scanning with Terrascan

Installing Terrascan

Terrascan is a portable executable that does not strictly require installation, and is also available as a container image in Docker Hub. You can use Terrascan in two different methods based on your preference:

1. Installing Terrascan locally
2. Using a Docker container

Native executable

Terrascan’s release page includes latest version of builds for common platforms. Download and extract the package for your platform. Follow instructions that apply to your platform:

macOS and Linux

Download the latest version of builds for macOS and enter the following command. Note: for linux, replace Darwin with Linux

$ curl -L "$(curl -s https://api.github.com/repos/tenable/terrascan/releases/latest | grep -o -E "https://.+?_Darwin_x86_64.tar.gz")" > terrascan.tar.gz
$ tar -xf terrascan.tar.gz terrascan && rm terrascan.tar.gz
$ install terrascan /usr/local/bin && rm terrascan
$ terrascan

If you want to use this executable for the rest of this quickstart, it will help to create an alias or install the executable onto your path. For example with bash you could do something like this:

$ sudo install terrascan /usr/local/bin

or:

$ alias terrascan="`pwd`/terrascan"

Windows

Download the latest version of builds for Windows and enter the following command:

tar -zxf terrascan_<version number>_Windows_x86_64.tar.gz

Using a Docker Container

Terrascan is also available as a Docker image in Docker Hub and can be used as follows (assuming you have Docker installed):

$ docker run --rm tenable/terrascan version

If you want to use the Docker image for the rest of this “Getting Started” guide, please refer to the following command. Note the volume (-v) that is being mapped to the docker, and modify it if necessary to suit your environment.

$ alias terrascan="docker run --rm -it -v "$(pwd):/iac" -w /iac tenable/terrascan"

Note: This command includes a few extra options to enable Terrascan has access to the current directory when it is run.

Scanning with Terrascan

Example of interactive scan or using CLI

In this example, the KaiMonkey project contains some vulnerable Terraform files to scan. To run a scan, follow these steps:

$ git clone https://github.com/tenable/KaiMonkey
...
$ cd KaiMonkey/terraform/aws
$ terrascan scan

By default Terrascan will output its findings in human friendly format:

Violation Details -

	Description    :	S3 bucket Access is allowed to all AWS Account Users.
	File           :	modules/storage/main.tf
	Line           :	104
	Severity       :	HIGH
	-----------------------------------------------------------------------

	Description    :	S3 bucket Access is allowed to all AWS Account Users.
	File           :	modules/storage/main.tf
	Line           :	112
	Severity       :	HIGH
	-----------------------------------------------------------------------

	Description    :	Ensure that your RDS database has IAM Authentication enabled.
	File           :	modules/storage/main.tf
	Line           :	45
	Severity       :	HIGH
	-----------------------------------------------------------------------

	Description    :	Ensure VPC flow logging is enabled in all VPCs
	File           :	modules/network/main.tf
	Line           :	4
	Severity       :	MEDIUM
	-----------------------------------------------------------------------

	Description    :	EC2 instances should disable IMDS or require IMDSv2
	File           :	modules/compute/main.tf
	Line           :	124
	Severity       :	MEDIUM
	-----------------------------------------------------------------------

	Description    :	http port open to internet
	File           :	modules/network/main.tf
	Line           :	102
	Severity       :	HIGH
	-----------------------------------------------------------------------

	Description    :	Enabling S3 versioning will enable easy recovery from both unintended user actions, like deletes and overwrites
	File           :	modules/storage/main.tf
	Line           :	104
	Severity       :	HIGH
	-----------------------------------------------------------------------

	Description    :	Enabling S3 versioning will enable easy recovery from both unintended user actions, like deletes and overwrites
	File           :	modules/storage/main.tf
	Line           :	112
	Severity       :	HIGH
	-----------------------------------------------------------------------

	Description    :	AWS CloudWatch log group is not encrypted with a KMS CMK
	File           :	modules/compute/main.tf
	Line           :	115
	Severity       :	HIGH
	-----------------------------------------------------------------------

Scan Summary -

	File/Folder         :	/var/folders/2g/9lkfm6ld2lv350svwr15fdgc0000gn/T/x9wqg4/terraform/aws
	IaC Type            :	terraform
	Scanned At          :	2021-01-15 03:11:31.869816 +0000 UTC
	Policies Validated  :	571
	Violated Policies   :	9
	Low                 :	0
	Medium              :	2
	High                :	7

You should see a total of 9 violations, which are detailed in the output.

Now that you understand how to run Terrascan, you can explore various options available. The usage page covers the options in detail. For more information, see Related resources.

If you do not want terrascan to use os.TempDir() for downloading/cloning of remote repository, terraform module or template files you can specify the directory to use by setting TERRRASCAN_CUSTOM_TEMP_DIR environment variable.

Related resources

• The usage guide explains general usage, how to scan other types of IaC (such as: Kubernetes, Helm, and Kustomize), List of other IaC providers (e.g. Kubernetes, Helm, etc.), instructions to limit the scan to specific directories or files, and generating the output in different formats.
• The CI/CD page explains how to integrate Terrascan on CI/CD pipelines.
• Terrascan Policy Reference

2 - Usage

For steps to install locally, or run Terrascan from docker, see this section.

Building Terrascan

Terrascan is a Go binary that you can build locally. This is useful if you want to be on the latest version, or when modding Terrascan.

$ git clone git@github.com:tenable/terrascan.git
$ cd terrascan
$ make build
$ ./bin/terrascan

Using Terrascan

This section provides an overview of the different ways you can use Terrascan:

1. Command line mode provides list of Terrascan commands with descriptions.
2. Server mode using Terrascan as API server

See Configuring Terrascan to learn more about Terrascan’s configuration file.

See In-File Instrumentation to learn how to granularly customize your scan based on particular resources and rules. For example, by skipping certain rules or resources.

Integrations

Terrascan can be integrated into various platforms and configured to validate policies to provide run time security. Currently Terrascan supports the following integrations:

1. Kubernetes (K8s) Admissions webhooks
2. ArgoCD
3. Atlantis
4. Github and GitLab or CI/CD pipelines

2.1 - Command Line Options

This section contains the following information:

• Terrascan commands
• Scanning with examples
• Configuring the output format for a scan

The following is a description of all the commands available. Terrascan’s interface is divided into subcommands as follows:

• init = Initializes Terrascan by downloading the latest Rego policies into ~/.terrascan. The scan command will implicitly run this before a scan if it detects that there are no policies found.
• scan = scans Infrastructure as code files based on the policies contained within the “.terrascan” directory
• server = Starts the Terrascan’s API server
• help = You can view the usage menu by typing help or using the -h flag on any subcommand (e.g. terrascan init -h). You can also view this by typing terrascan without flags or other arguments.

Terrascan Commands

$ terrascan
Terrascan

Detect compliance and security violations across Infrastructure as Code to mitigate risk before provisioning cloud native infrastructure.
For more information, please visit https://runterrascan.io/

Usage:
  terrascan [command]

Available Commands:
  help        Provides usage info about any command
  init        Initialize Terrascan
  scan        Start scan to detect compliance and security violations across Infrastructure as Code.
  server      Run Terrascan as an API server
  version     Shows the Terrascan version you are currently using.

Flags:
  -c, --config-path string      config file path
  -h, --help                    help for terrascan
  -l, --log-level string        log level (debug, info, warn, error, panic, fatal) (default "info")
      --log-output-dir string   directory path to write the log and output files
  -x, --log-type string         log output type (console, json) (default "console")
  -o, --output string           output type (human, json, yaml, xml, junit-xml, sarif, github-sarif) (default "human")
      --temp-dir string         temporary directory path to download remote repository,module and templates

Use "terrascan [command] --help" for more information about a command.

Initializing (optional)

The initialization process downloads the latest policies from the repository into ~/.terrascan. By default the policies are installed here: ~/.terrascan/pkg/policies/opa/rego and are fetched while scanning an IaC. Use the following command to start the initialization process if you are updating the policies:

$ terrascan init

Note: The init command is implicitly executed if the scan command does not find policies while executing.

Scanning

If the scan command is used with no arguments (as shown below), the scan will include all supported cloud providers on Terraform HCL files:

$ terrascan scan

The scan command supports flags to configure the following:

• Specify a directory to be scanned
• Specify a particular IaC file to be scanned
• Configure IaC provider type
• Directory path to policies
• Specify policy type
• Retrieve vulnerability scanning results from docker images referenced in IaC

The full list of flags for the scan command can be found by typing terrascan scan -h

Scanning current directory containing terraform files for AWS Resources

The following will scan the current directory containing Terraform HCL2 files for AWS resources:

$ terrascan scan -t aws

Scanning for a specific IaC provider

By default, Terrascan defaults to scanning Terraform HCL files. Use the -i flag to change the IaC provider. Here’s an example of scanning kubernetes yaml files:

$ terrascan scan -i k8s

Scanning code remotely

Terrascan can be installed remotely to scan remote repositories or code resources using the -r and -u flags. Here’s an example:

$ terrascan scan -t aws -r git -u git@github.com:tenable/KaiMonkey.git//terraform/aws

Important: The URLs for the remote repositories should follow similar naming conventions as the source argument for modules in Terraform. For more details, see this article.

Scanning private Terraform module repositories

When scanning Terraform code, Terrascan checks for the environment variable TF_CLI_CONFIG_FILE. If found uses the credential file provided in that environment variable to authenticate a private terraform module registry. If the env variable is not found then checks for the availability of the file ~/.terraformrc. This file contains credential information to authenticate a private terraform module registry. If this file is present, Terrascan will attempt to use the credentials when authenticating the private repository. For more details on the format of this file, please see Terraform’s config file documentation.

Configuring the output format for a scan

By default, Terrascan output is displayed in a human friendly format. Use the -o flag to change this to YAML, JSON, XML, JUNIT-XML and SARIF formats.

Note: Terrascan will exit with an error code if any errors or violations are found during a scan.

List of possible Exit Codes

Scenario	Exit Code
scan summary has errors and violations	5
scan summary has errors but no violations	4
scan summary has violations but no errors	3
scan summary has no violations or errors	0
scan command errors out due to invalid inputs	1

Terrascan’s output is a list of security violations present in the scanned IaC files. The example below is terrascan’s output in YAML.

$ terrascan scan -t aws
results:
  violations:
  - rule_name: scanOnPushDisabled
    description: Unscanned images may contain vulnerabilities
    rule_id: AWS.ECR.DataSecurity.High.0578
    severity: MEDIUM
    category: Data Security
    resource_name: scanOnPushDisabled
    resource_type: aws_ecr_repository
    file: ecr.tf
    line: 1
  count:
    low: 0
    medium: 1
    high: 0
    total: 1

Scanning a Helm Chart

Helm chart can be scanned by specifying “helm” on the -i flag as follows:

$ terrascan scan -i helm

This command will recursively look for Chart.yaml files in the current directory and scan rendered .yaml, .yml, .tpl template files found under the corresponding /templates directory.

A specific directory to scan can be specified using the -d flag. The Helm IaC provider does not support scanning of individual files using the -f flag.

Scanning a Kustomize Chart

A Kustomize chart can be scanned by specifying “kustomize” on the -i flag as follows:

$ terrascan scan -i kustomize

This command looks for a kustomization.yaml file in the current directory and scans rendered .yaml or .yml template files.

Terrascan considers Kustomize v4 as the default version. Other supported versions (v2 and v3) of Kustomize could be scanned by specifying –iac-version flag as follows:

$ terrascan scan -i kustomize --iac-version v2

Scanning v2 and v3 requires the corresponding Kustomize binary and the path to the binary must be specified in the KUSTOMIZE_<VERSION> ENV variable.

e.g: For –iac-version v2, we need to have:

KUSTOMIZE_V2=path/to/kustomize/v2/binary

To install Kustomize one can use this script

A specific directory to scan can be specified using the -d flag. The Kustomize IaC provider does not support scanning of individual files using the -f flag.

Scanning a Dockerfile

A Dockerfile can be scanned by specifying “docker” on the -i flag as follows:

$ terrascan scan -i docker

This command looks for a Dockerfile in the current directory and scans that file.

A specific directory to scan can be specified using the -d flag. With the -d flag, it will check for all the docker files (named as Dockerfile) in the provided directory recursively. A specific dockerfile can be scanned using -f flag by providing a path to the file.

Retrieve Container Image Vulnerabilities

Terrascan can display vulnerabilities for container images present in the IaC files being scanned by specifying the --find-vuln flag along with the scan command as follows:

$ terrascan scan -i <IaC Provider> --find-vuln

This command looks for container images referenced in the IaC files and retrieves any vulnerabilities as reported by its container registry.

Supported container registries: AWS Elastic Container Registry (ECR), Azure Container Registry, Google Container Registry, Google Artifact Registry, and Harbor Container Registry.

The following environment variables are required when connecting to the container registries:

AWS Elastic Container Registry (ECR)

ECR requires your environment to be configured similar to the requirements of AWS’s SDK. For example, the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION environment variables can be set when connecting to AWS using API keys for an AWS user. More information here.

Google Container Registry and Artifact Registry

Terrascan requires a service account with access to the Container Analysis and Container Registry permissions. The GOOGLE_APPLICATION_CREDENTIALS environment variable can be set to the path of the service account’s key when scanning. More information about GCP authentication available here.

Azure Container Registry

When integrating vulnerability results from Azure, Terrascan requires the AZURE_AUTH_LOCATION, and AZURE_ACR_PASSWORD environment variables.

The AZURE_AUTH_LOCATION should contain the path to your azure authentication json. You can generate this as follows:

az ad sp create-for-rbac --sdk-auth > azure.auth

After generating the file, set the azure.auth file path as the AZURE_AUTH_LOCATION environment variable. More information about using file based authentication for the Azure SDK available here.

Terrascan also requires the password to the registry set into the AZURE_ACR_PASSWORD environment variable. This can be fetched using the az cli as follows:

az acr credential show --name RegistryName

Harbor Container Registry

When integrating vulnerability results from Harbor, Terrascan requires the HARBOR_REGISTRY_USERNAME, HARBOR_REGISTRY_PASSWORD,HARBOR_REGISTRY_CACERT, HARBOR_SKIP_TLS, and HARBOR_REGISTRY_DOMAIN environment variables.

The HARBOR_REGISTRY_DOMAIN environment variable helps Terrascan identify the registry’s domain.

The HARBOR_SKIP_TLS environment variable can be set to true to avoid TLS errors when Harbor is using a non-trusted TLS certificate. This is not recommended for production use.

Resource Config

While scanning a IaC, Terrascan loads all the IaC files, creates a list of resource configs and then processes this list to report violations. For debugging purposes, you can print this resource configs list as an output by using the --config-only flag to the terrascan scan command.

$  terrascan scan -i terraform -t aws -f elb.tf --config-only -o json
{
  "aws_elb": [
    {
      "id": "aws_elb.public_elb",
      "name": "public_elb",
      "module_name": "root",
      "source": "elb.tf",
      "line": 1,
      "type": "aws_elb",
      "config": {
        "connection_draining": true,
        "health_check": [
          {
            "healthy_threshold": 2,
            "interval": 15,
            "target": "HTTP:80/index.html",
            "timeout": 3,
            "unhealthy_threshold": 2
          }
        ],
        "instances": "${aws_instance.web.*.id}",
        "listener": [
          {
            "instance_port": 80,
            "instance_protocol": "http",
            "lb_port": 80,
            "lb_protocol": "http"
          }
        ],
        "name": "${local.prefix.value}-public-elb",
        "security_groups": [
          "${aws_security_group.public_internet.id}"
        ],
        "subnets": "${aws_subnet.public.*.id}",
        "tags": {
          "Name": "${local.prefix.value}-public-elb"
        }
      },
      "line_config": {
        "connection_draining": 16,
        "health_check": [
          {
            "healthy_threshold": 9,
            "interval": 13,
            "target": 12,
            "timeout": 11,
            "unhealthy_threshold": 10
          }
        ],
        "instances": 6,
        "listener": [
          {
            "instance_port": 18,
            "instance_protocol": 19,
            "lb_port": 20,
            "lb_protocol": 21
          }
        ],
        "name": 2,
        "security_groups": 5,
        "subnets": 4,
        "tags": {
          "Name": 25
        }
      },
      "skip_rules": null,
      "max_severity": "",
      "min_severity": ""
    }
  ]
}

More details on scan command

List of options for scan command:

Full help for scan command:

$ terrascan scan -h
Terrascan

Detect compliance and security violations across Infrastructure as Code to mitigate risk before provisioning cloud native infrastructure.

Usage:
  terrascan scan [flags]

Flags:
      --categories strings                  list of categories of violations to be reported by terrascan (example: --categories="category1,category2")
      --config-only                         will output resource config (should only be used for debugging purposes)
      --find-vuln                           fetches vulnerabilities identified in Docker images
  -h, --help                                help for scan
  -d, --iac-dir string                      path to a directory containing one or more IaC files (default ".")
  -f, --iac-file string                     path to a single IaC file
  -i, --iac-type string                     iac type (arm, cft, docker, helm, k8s, kustomize, terraform, tfplan)
      --iac-version string                  iac version (arm: v1, cft: v1, docker: v1, helm: v3, k8s: v1, kustomize: v2, v3, v4, terraform: v12, v13, v14, v15, tfplan: v1)
      --non-recursive                       do not scan directories and modules recursively
      --webhook-token string   the auth token to call the notification webhook URL
      --webhook-url string     the URL where terrascan will send the scan report and normalized config json
  -p, --policy-path stringArray             policy path directory
  -t, --policy-type strings                 policy type (all, aws, azure, docker, gcp, github, k8s) (default [all])
  -r, --remote-type string                  type of remote backend (git, s3, gcs, http, terraform-registry)
  -u, --remote-url string         url pointing to remote IaC repository
      --repo-ref string           branch of the repo being scanned
      --repo-url string           URL of the repo being scanned, will be reflected in scan summary
      --scan-rules strings                  one or more rules to scan (example: --scan-rules="ruleID1,ruleID2")
      --severity string                     minimum severity level of the policy violations to be reported by terrascan
      --show-passed                         display passed rules, along with violations
      --skip-rules strings                  one or more rules to skip while scanning (example: --skip-rules="ruleID1,ruleID2")
      --use-colors string                   color output (auto, t, f) (default "auto")
      --use-terraform-cache                 use terraform init cache for remote modules (when used directory scan will be non recursive, flag applicable only with terraform IaC provider)
  -v, --verbose                             will show violations with details (applicable for default output)

Global Flags:
  -c, --config-path string      config file path
  -l, --log-level string        log level (debug, info, warn, error, panic, fatal) (default "info")
      --log-output-dir string   directory path to write the log and output files
  -x, --log-type string         log output type (console, json) (default "console")
  -o, --output string           output type (human, json, yaml, xml, junit-xml, sarif, github-sarif) (default "human")
      --temp-dir string         temporary directory path to download remote repository,module and templates

2.2 - Server mode

Server mode will execute Terrascan’s API server. This is useful when using Terrascan to enforce a unified set of policies and configuration in multiple parts of the software development pipelines. It also simplifies programmatically interacting with Terrascan. By default the http server listens in port 9010 and supports the following routes:

Note: URL placeholders are equivalent to the command line flags in the scan command

API Routes

Check health of server

• GET - /health

Scan IaC File

• POST - /v1/{iac}/{iacVersion}/{cloud}/local/file/scan

POST Parameter: file - Content of the file to be scanned

Example: curl -i -F "file=@aws_cloudfront_distribution.tf" localhost:9010/v1/terraform/v14/aws/local/file/scan

Scan Remote IaC

• POST - /v1/{iac}/{iacVersion}/{cloud}/remote/dir/scan

Run Terrascan in Server Mode

You can launch server mode by executing the Terrascan binary, or with a Docker container. Use the following to execute the Terrascan CLI:

$ terrascan server

Use this command to launch Terrascan server mode using Docker:

$ docker run --rm --name terrascan -p 9010:9010 tenable/terrascan

Example of how to send a request to the Terrascan server using curl:

$ curl -i -F "file=@aws_cloudfront_distribution.tf" localhost:9010/v1/terraform/v14/aws/local/file/scan
HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Date: Sun, 16 Aug 2020 02:45:35 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked

{
  "results": {
    "violations": [
      {
        "rule_name": "cloudfrontNoGeoRestriction",
        "description": "Ensure that geo restriction is enabled for your Amazon CloudFront CDN distribution to whitelist or blacklist a country in order to allow or restrict users in specific locations from accessing web application content.",
        "rule_id": "AWS.CloudFront.Network Security.Low.0568",
        "severity": "LOW",
        "category": "Network Security",
        "resource_name": "s3-distribution-TLS-v1",
        "resource_type": "aws_cloudfront_distribution",
        "file": "terrascan-492583054.tf",
        "line": 7
      },
      {
        "rule_name": "cloudfrontNoHTTPSTraffic",
        "description": "Use encrypted connection between CloudFront and origin server",
        "rule_id": "AWS.CloudFront.EncryptionandKeyManagement.High.0407",
        "severity": "HIGH",
        "category": "Encryption and Key Management",
        "resource_name": "s3-distribution-TLS-v1",
        "resource_type": "aws_cloudfront_distribution",
        "file": "terrascan-492583054.tf",
        "line": 7
      },
      {
        "rule_name": "cloudfrontNoHTTPSTraffic",
        "description": "Use encrypted connection between CloudFront and origin server",
        "rule_id": "AWS.CloudFront.EncryptionandKeyManagement.High.0407",
        "severity": "HIGH",
        "category": "Encryption and Key Management",
        "resource_name": "s3-distribution-TLS-v1",
        "resource_type": "aws_cloudfront_distribution",
        "file": "terrascan-492583054.tf",
        "line": 7
      },
      {
        "rule_name": "cloudfrontNoLogging",
        "description": "Ensure that your AWS Cloudfront distributions have the Logging feature enabled in order to track all viewer requests for the content delivered through the Content Delivery Network (CDN).",
        "rule_id": "AWS.CloudFront.Logging.Medium.0567",
        "severity": "MEDIUM",
        "category": "Logging",
        "resource_name": "s3-distribution-TLS-v1",
        "resource_type": "aws_cloudfront_distribution",
        "file": "terrascan-492583054.tf",
        "line": 7
      },
      {
        "rule_name": "cloudfrontNoSecureCiphers",
        "description": "Secure ciphers are not used in CloudFront distribution",
        "rule_id": "AWS.CloudFront.EncryptionandKeyManagement.High.0408",
        "severity": "HIGH",
        "category": "Encryption and Key Management",
        "resource_name": "s3-distribution-TLS-v1",
        "resource_type": "aws_cloudfront_distribution",
        "file": "terrascan-492583054.tf",
        "line": 7
      }
    ],
    "count": {
      "low": 1,
      "medium": 1,
      "high": 3,
      "total": 5
    }
  }
}

2.3 - In-file Instrumentation

Today, Terrascan supports these instrumentations:

• Rule Skipping
• Resource Prioritization

Rule Skipping

Rule skipping allows you to specify a rule that should not be applied to a particular resource.

Note: In-file instrumentation will skip the rule only for the resource it is defined in. The skip_rules parameter in the config file will skip the rule for the entire scan.

In Terraform

Use the syntax #ts:skip=RuleID optional_comment inside a resource to skip the rule for that resource.

Example

resource "aws_db_instance" "PtShGgAdi4" {
  #ts:skip=AWS.RDS.DataSecurity.High.0414 Reason to skip this rule
  allocated_storage       = 20
  storage_type            = "gp2"
  engine                  = "mysql"
  engine_version          = "5.7"
  instance_class          = "db.t2.micro"
 .
 .
 .
}

In Kubernetes

Use the annotation runterrascan.io/skip:[{\"rule\": \RuleID\", \"comment\": \"reason to skip the rule\"}] inside a resource to skip the rule for that resource.

Example

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: ingress-demo-disallowed
  annotations:
    runterrascan.io/skip: "[{\"rule\": \"AC-K8-NS-IN-H-0020\", \"comment\": \"reason to skip the rule\"}]"
spec:
  rules:
    - host: example-host.example.com
      http:
        paths:
          - backend:
              serviceName: nginx
              servicePort: 80

In Dockerfile

Use the syntax #ts:skip=RuleID optional_comment inside the dockerfile to skip the rule for that resource.

Example

FROM runatlantis/atlantis:v0.16.1
#ts:skip=AC_DOCKER_0001 skip this rule.
ENV DEFAULT_TERRASCAN_VERSION=1.5.1
RUN terrascan init
ENTRYPOINT ["/bin/bash", "entrypoint.sh"]
CMD ["server"]

Resource Prioritization

Resource prioritization allows you set maximum and minimum severities for violations in a given resource. Are you configuring a very sensitive resource? Set the minimum severity to High, so low and medium violations will be escalated. Need to suppress all violations from a particular resource? Set the maximum severity to None.

For maximum severity, meaningful options are Medium, Low, and None.

For minimum severity, meaningful options are High and Medium.

In Terraform

Use the syntax #ts:maxseverity=SEVERITY, or #ts:minseverity=SEVERITY inside a resource to skip the rule for that resource.

Example

resource "aws_db_instance" "PtShGgAdi4" {
  #ts:maxseverity=Low
  allocated_storage       = 20
  storage_type            = "gp2"
  engine                  = "mysql"
  engine_version          = "5.7"
  instance_class          = "db.t2.micro"
  .
  .
  .
}

In Kubernetes

Use the annotation runterrascan.io/minseverity: SEVERITY, or runterrascan.io/maxseverity: SEVERITY inside a resource to skip the rule for that resource.

Example

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: ingress-demo-disallowed
  annotations:
    runterrascan.io/minseverity: Low
spec:
  rules:
    - host: example-host.example.com
      http:
        paths:
          - backend:
              serviceName: nginx
              servicePort: 80

In Dockerfile

Use the syntax #ts:maxseverity=SEVERITY, or #ts:minseverity=SEVERITY inside a dockerfile to skip the rule for that resource.

Example

#ts:maxseverity=None
FROM runatlantis/atlantis:v0.16.1
ENV DEFAULT_TERRASCAN_VERSION=1.5.1
RUN terrascan init
ENTRYPOINT ["/bin/bash", "entrypoint.sh"]
CMD ["server"]

2.4 - Configuration File

You can provide a configuration file in TOML format to configure the Terrascan.

Command to specify config File

Use the -c or --config-path flag provide a TOML configuration file for Terrascan.

$ terrascan scan -c <config file path>

Here’s an example config file:

[notifications]
    [notifications.webhook]
    url = "https://httpbin.org/post"
    token = "my_auth_token"

[severity]
level = "medium"
[rules]
    skip-rules = [
        "accurics.kubernetes.IAM.107"
    ]

[k8s-admission-control]
    denied-categories = [
        "Network Ports Security"
    ]
    denied-severity = "high"
    dashboard=true

[policy]
environment = "<environment_url>"
access_token = "<access_token>"

You can specify the following configurations:

• scan-rules - Specify one or more rules to scan. All other rules in the policy pack will be skipped.
• skip-rules - Specify one or more rules to skip while scanning. All other rules in the policy pack will be applied.
• severity - the minimal level of severity of the policies to be scanned and displayed. Options are high, medium and low
• category - the list of type of categories of the policies to be scanned and displayed
• notifications - This configuration can be used, as seen in the example above, to send the output of scans as a webhook to a remote server. Note that the --notification-webhook-url CLI flag will override any URLs configured through a configuration file.

k8s-admission-control - Config options for K8s Admission Controllers and GitOps workflows:

• denied-severity - Violations of this or higher severity will cause and admission rejection. Lower severity violations will be warnings. Options are high, medium. and low
• denied-categories - Violations from these policy categories will lead to an admission rejection. Policy violations of other categories will lead to warnings.
• dashboard=true - enable the /logs endpoint to log and graphically display K8s admission requests and violations. Default is false

policy - Config options for policy source and destination path information

• path - Sets the local path for terrascan files including policies

• rego_subdir - Sub directory within the base path for caching policies

• repo_url - Repository from which all the policies must be downloaded

• branch - Specific branch out of the repository to pull the policies

• environment - Authenticated environment URL for downloading policies. Supercedes any other source if its set along with a valid access token

• access_token - Authentication token to download policies from authenticated environment

Logging

Logging can be configured by using the -l or --log-level flags with possible values being: debug, info, warn, error, panic, or fatal. This defaults to “info”.

In addition to the default “console” logs, the logs can be configured to be output in JSON by using the -x or --log-type flag with the value of json.

3 - Integrations

Terrascan can be integrated into many tools in the development pipeline. When integrated into a tool, vulnerability scanning is automated as part of the commit or build process. It can run on a developer’s laptop, a SCM (e.g. GitHub), and CI\CD servers (e.g. ArgoCD and Jenkins). It also has a built in Admission Controller for Kubernetes.

Please see the following guides for integrating Terrascan in different use cases. If the product you want to integrate with is not listed, do not fret. Terrascan supports many output formats (YAML, JSON, XML, JUNIT-XML and SARIF) to suit the variety of tools in the ecosystem. For example, it’s straightforward to integrate with Jenkins using the JUNIT-XML format.

Go to the Usage page for more details.

Community Guides and Blogs:

• Azure DevOps Credit to @lrgulliver (Liam Gulliver)
• Static Code Analyses - Terrascan, Terraform and Azure DevOps. Credit to James Cook

Our Integration Guides:

3.1 - Kubernetes Admission Controller

Overview

Terrascan can be integrated with K8s admissions webhooks. Admission controllers help you control resources created on a kubernetes cluster. By using Terrascan as an admission controller, resources violating security policies can be prevented from getting created in a Kubernetes cluster.

Note on SSL certificates: You can use valid SSL certificates or create self signed certificates and have your Kubernetes cluster trust it.

Installation Guide

To configure Terrascan as an admission controller, follow these steps:

1. Create an instance of Terrascan which meets specified requirements as detailed below. Ensure Terrascan is accessible via HTTPS from the kubernetes API server.
2. Create Terrascan config file.
3. Run Terrascan in server mode.
4. Configure a ValidatingWebhookConfiguration resource in kubernetes cluster pointing to the Terrascan server.
5. Test your set up.

Step 1: Create an instance of Terrascan

Create an instance of Terrascan. To scan K8s configurations, your Terrascan instance must meet the following requirements.

1. Make sure Terrascan is accessible via HTTPS. Ensure your cloud firewall is configured to allow this.
2. Have a valid SSL certificate for the served domain name using one of the suggested methods below:
   • Use a subdomain of your choice (e.g dev-terrascan-k8s.tenable.com) and create a valid certificate for this subdomain through your SSL certificate provider. You can use Let’s Encrypt which is a free, simple to use certificate authority.
   • Use a reverse-proxy to serve SSL requests; for example, use Cloudflare Flexible to get a certificate by a trusted-CA to your self-signed certificate.
   • Generate a self-signed certificate and configure your K8s cluster to trust it. To add a trusted CA to ca-pemstore, as demonstrated in paraspatidar’s blog post.
3. Use the Terrascan docker as demonstrated in this document, or run it from the sources.

Step 2: Create a Terrascan config file

For instructions to create a config file, see Usage . You can create a config file that specifies which policies to use in the scan and which violations should be rejected during admission.

• Policies below the [severity] level will be ignored.
• Policies below the [k8s-admission-control] denied-severity will be logged and displayed by Terrascan, but will not lead to a rejected admission response to the k8s API server.

Sample config file

A config file example: config.toml

  [severity]
  level = "medium"
  [rules]
      skip-rules = [
          "accurics.kubernetes.IAM.107"
      ]

  [k8s-admission-control]
    denied-categories = [
        "Network Ports Security"
    ]
    denied-severity = "high"
    dashboard=true

You can specify the following configurations:

• scan-rules - one or more rules to scan
• skip-rules - one or more rules to skip while scanning
• severity - the minimal level of severity of the policies to be scanned and displayed. Options are high, medium and low
• category - the list of type of categories of the policies to be scanned and displayed

k8s-admission-control - Config options for K8s Admission Controllers and GitOps workflows:

• denied-severity - Violations of this or higher severity will cause and admission rejection. Lower severity violations will be warnings. Options are high, medium. and low
• denied-categories - violations from these policy categories will lead to an admission rejection. Policy violations of other categories will lead to warnings.
• dashboard=true - enable the /logs endpoint to log and graphically display admission requests and violations. Default is false

Step 3: Run Terrascan in Server Mode

Run Terrascan docker image in your server using the following command:

 sudo docker run -p 443:9443 -v <DATA_PATH>:/data -u root -e K8S_WEBHOOK_API_KEY=<API_KEY> tenable/terrascan server --cert-path /data/cert.pem --key-path /data/key.pem -c /data/config.toml

Where,

• <API_KEY> is a key used for authentication between your K8s environment and the Terrascan server. Generate your preferred key and use it here.
• <DATA_PATH> is a directory path in your server where both the certificate and the private key .pem files are stored. This directory is also used to save the webhook logs. (Logs are in saves in SQLite file format)

Step 4: Configure a ValidatingWebhookConfiguration Resource in Kubernetes Cluster

Configure a new ValidatingWebhookConfiguration in your Kubernetes environment and specify your Terrascan server endpoint.

Example:

  cat <<EOF | kubectl apply -f -
  apiVersion: admissionregistration.k8s.io/v1
  kind: ValidatingWebhookConfiguration
  metadata:
    name: my.validation.example.check
  webhooks:
    - name: my.validation.example.check
      rules:
        - apiGroups:
            - ""
          apiVersions:
            - v1
          operations:
            - CREATE
            - UPDATE
          resources:
            - pods
            - services
      failurePolicy: Fail
      clientConfig:
        url: https://<SERVER_ADDRESS>/v1/k8s/webhooks/<API_KEY>/scan
      sideEffects: None
      admissionReviewVersions: ["v1"]
  EOF

• You can modify the rules that trigger the webhook according to your preferences.
• Update the clientConfig URL with your terrascan server address and the API key you generated before.

Step 5: Test your settings

Try to run a new pod / service. For example:

  kubectl run mynginx --image=nginx

Go to https://<SERVER_ADDRESS>/k8s/webhooks/<API_KEY>/logs and verify your request is logged.

3.2 - Argo CD

Terrascan can be integrated with Argo CD in two ways

1. Use terrascan as a pre-sync hook to scan remote repositories
2. Use terrascan’s k8s admission controller along with a pre-sync that scans a configured repository with the admission controller webhook

Method 1. Configure terrascan as a PreSync hook and scan the remote repository.

Configure a PreSync hook

The following example of a hook yaml is nearly ready to be added to an existing kubernetes configuration. To complete the configutation, you need to:

• Ensure that the secrets, known_hosts, and ssh_config volume are relevant for your specific environment.
• Specify a terrascan image.

You can also map a slack notification script to the container which will send notifications to your Slack webhook endpoint after the embedded script scans the repo.

apiVersion: batch/v1
kind: Job
metadata:
 generateName: terrascan-hook-
 annotations:
   argocd.argoproj.io/hook: PreSync
spec:
 ttlSecondsAfterFinished: 3600
 template:
   spec:
     securityContext:
       seccompProfile:
         type: RuntimeDefault
     volumes:
       #add a configmap for the slack notification scripts
       - name: notification-scripts
         configMap:
           name: slack-notifications
       #add all required ssh keys need to clone your repos
       - name: ssh-key-secret
         secret:
           secretName: ssh-key-secret
       #add a secret for git config file
       - name: ssh-config
         secret:
           secretName: ssh-config-secret
       #add a configmap for the ssh known_hosts file
       - name: ssh-known-hosts
         configMap:
           name: known-hosts-config
     containers:
     - name: terrascan-argocd
       image: <terrscan-image>
       resources:
         requests:
           cpu: "1"
           memory: "256Mi"
         limits:
           cpu: "1"
           memory: "256Mi"
       command: ["/bin/sh", "-c"]
       args:
       - >
         cp /etc/secret-volume/ssh-private-key /home/terrascan/.ssh/id_ed25519_github &&
         cp /etc/ssh-config-secret/ssh-config /home/terrascan/.ssh/config &&
         cp /etc/ssh-known-hosts-secret/ssh-known-hosts /home/terrascan/.ssh/known_hosts &&
         chmod -R 400 /home/terrascan/.ssh/* &&
         /go/bin/terrascan scan -r git -u <YOUR REPOSITORY PATH>-i k8s -t k8s | /data/notify_slack.sh webhook-tests argo-cd https://hooks.slack.com/services/TXXXXXXXX/XXXXXXXXXXX/0XXXXXXXXXXXXXXXXXX         
       securityContext:
         seccompProfile:
           type: RuntimeDefault
         allowPrivilegeEscalation: false
         runAsNonRoot: true
         runAsUser: 101
       livenessProbe:
         exec:
           command:
           - /go/bin/terrascan
           - version
         periodSeconds: 10
         initialDelaySeconds: 10
       readinessProbe:
         exec:
           command:
           - /go/bin/terrascan
           - version
         periodSeconds: 10
       #if want to use private repo
       volumeMounts:
         - mountPath: /etc/secret-volume
           name: ssh-key-secret
           readOnly: true
         - mountPath: /etc/ssh-config-secret
           name: ssh-config
           readOnly: true
         - mountPath: /etc/ssh-known-hosts-secret
           name: ssh-known-hosts
           readOnly: true
         - mountPath: /data
           name: notification-scripts
           readOnly: true

     restartPolicy: Never
 backoffLimit: 1

Note: As shown above, the PreSync requires access to the repository where IaC is stored, using the same branch (default) as the ArgoCD application pipeline.

To allow users to check for violations in the web interface, configure the job to delete after the specified time, using the parameter ttlSecondsAfterFinished. In addition, violation can be reported as webhook notifications, as shown below.

Example slack notification script

#!/bin/sh

function send_slack_notificaton {
  channel=$1
  username=$2
  slack_hook=$3

  curl -X POST --data-urlencode payload="{\"channel\": \"#${channel}\", \"username\": \"${username}\", \"text\": \" \`\`\` $(cat results.out) \`\`\` \", \"icon_emoji\": \":ghost:\"}" ${slack_hook}
}

if [ -p /dev/stdin ]; then
  echo "processing terrascan results"
  while IFS= read line; do
          echo "${line}" | tr '\\"' ' ' >> results.out
  done

  cat results.out

  send_slack_notificaton $1 $2 $3

  echo "notification exit code: $?"
else
  echo "no response skipping"
fi

For private repositories, the private following keys must be added as kubernetes secret:

• private key and ssh config as Secret
• known_hostsas ConfigMap

 kubectl create secret generic ssh-key-secret \
   --from-file=ssh-privatekey= < path to your private key > \
    --from-file=ssh-publickey=< path to your public key >

Config-map:

  kubectl  create configmap ssh-known-hosts --from-file=< path to your known hosts file >

  kubectl  create configmap slack-notifications --from-file=< path to your notification script >

ssh config secret

 kubectl create secret generic ssh-config-secret \
   --from-file=< path to your ssh config file >

Example ssh config file

 Host github.com
  HostName github.com
  IdentityFile ~/.ssh/id_ed25519_github

After configuring the presynchook yaml file, add the file to the relevant repository folder to configure Argo CD.

Method 2. Use PreSyncHook to trigger the Terrascan Server Service

You can use a pre-deployed terrascan server service in K8s cluster to scan the remote repository from Argo CD PreSync hook. To configure, follow these steps:

Step 1: Configure Terrascan Server webhook deployment yaml file with required keys and volumes and service to expose the controller pod.

apiVersion: apps/v1
kind: Deployment
metadata:
name: terrascan-server
labels:
  app: terrascan
spec:
replicas: 1
selector:
  matchLabels:
    app: terrascan
template:
  metadata:
    labels:
      app: terrascan
  spec:
    containers:
    - name: terrascan
      image: <TERRASCAN LATEST IMAGE>
      resources:
        limits:
          memory: "256Mi"
          cpu: "1"
      ports:
        - containerPort: 443
      livenessProbe:
        initialDelaySeconds: 30
        periodSeconds: 10
        timeoutSeconds: 5
        httpGet:
          path: /health
          port: 443
          scheme: HTTPS
      env:
        - name: K8S_WEBHOOK_API_KEY
          value: yoursecretapikey
      volumeMounts:
        - mountPath: /data/certs
          name: terrascan-certs-secret
          readOnly: true
        - mountPath: /data/config
          name: terrascan-config
          readOnly: true
        - mountPath: /etc/secret-volume
          name: ssh-key-secret
          readOnly: true
        - mountPath: /etc/ssh-config-secret
          name: ssh-config
          readOnly: true
        - mountPath: /etc/ssh-known-hosts-secret
          name: ssh-known-hosts
          readOnly: true
      command: ["/bin/sh", "-c"]
      args:
        - >
          cp /etc/secret-volume/ssh-private-key /home/terrascan/.ssh/id_ed25519_github &&
          cp /etc/ssh-config-secret/ssh-config /home/terrascan/.ssh/config &&
          cp /etc/ssh-known-hosts-secret/ssh-known-hosts /home/terrascan/.ssh/known_hosts &&
          chmod -R 400 /home/terrascan/.ssh/* &&
          terrascan server --cert-path /data/certs/server.crt --key-path /data/certs/server.key -p 443 -l debug -c /data/config/config.toml          
    volumes:
      #add all required ssh keys need to clone your repos
      - name: ssh-key-secret
        secret:
          secretName: ssh-key-secret
      #add a secret for git config file
      - name: ssh-config
        secret:
          secretName: ssh-config-secret
      #add a configmap for the ssh known_hosts file
      - name: ssh-known-hosts
        configMap:
          name: known-hosts-config
      #add a configmap for the terrascan config.toml file
      - name: terrascan-config
        configMap:
          name: terrascan-config
      #add a secret for the tls certificates
      - name: terrascan-certs-secret
        secret:
          secretName: terrascan-certs-secret

Service example

apiVersion: v1
kind: Service
metadata:
  name: terrascan-service
spec:
  selector:
    app: terrascan
  ports:
  - port: 443
    targetPort: 443

For private repositories, the following private keys needs to be added as a kubernetes secret:

• private key and ssh config as Secret
• known_hostsas ConFigmap

kubectl create secret generic ssh-key-secret \
  --from-file=ssh-privatekey= < path to your private key > \
  --from-file=ssh-publickey=< path to your public key >

kubectl create secret generic terrascan-certs-secret \
  --from-file= < path to your .key file > \
  --from-file= < path to your .crt file >

Config-map:

kubectl create configmap ssh-known-hosts --from-file=< path to your known hosts file >

kubectl create configmap terrascan-config  --from-file=<path to your config.toml file >

ssh config secret

kubectl create secret generic ssh-config-secret \
  --from-file=< path to your ssh config file >

Example ssh config file

Host github.com
  HostName github.com
  IdentityFile ~/.ssh/id_ed25519_github

After making changes to the webhook deployment file, apply this yaml in your cluster.

You can also run terrascan admission controller server outside cluster, for more information and instructions on configuring terrascan as an admission controller webhook, see https://runterrascan.io/docs/integrations/k8s/.

Step 2: Create a Dockerfile

Create a Dockerfile for the container. This container will run the script that triggers the remote Terrascan API server. The template for the script is below, after the Dockerfile. Please fill the values in the template to match your environment.

# Dockerfile with a script to use terrascan's validating webhook
# configured in the kubernetes cluster, to scan a repo for violations
FROM alpine:3.12.0

#curl to send request to terrascan validating webhook
RUN apk add --no-cache curl

WORKDIR /home/terrascan

RUN mkdir bin

COPY scripts/argocd-terrascan-remote-scan.sh  bin/terrascan-remote-scan.sh

# create non root user
RUN addgroup --gid 101 terrascan && \
  adduser -S --uid 101 --ingroup terrascan terrascan && \
  chown -R terrascan:terrascan bin && \
  chmod u+x bin/terrascan-remote-scan.sh

USER 101

CMD ["sh"]

The terrascan-remote-scan script

#!/bin/sh

set -o errexit


TERRASCAN_SERVER="https://${SERVICE_NAME}"
IAC=${IAC_TYPE:-"k8s"}
IAC_VERSION=${IAC_VERSION:-"v1"}
CLOUD_PROVIDER=${CLOUD_PROVIDER:-"all"}
REMOTE_TYPE=${REMOTE_TYPE:-"git"}

if [ -z ${SERVICE_NAME} ]; then
    echo "Service Name Not set"
    exit 6
fi

if [ -z ${REMOTE_URL} ]; then
    echo "Remote URL Not set"
    exit 6
fi

SCAN_URL="${TERRASCAN_SERVER}/v1/${IAC}/${IAC_VERSION}/${CLOUD_PROVIDER}/remote/dir/scan"

echo "Connecting to the service: ${SERVICE_NAME} to scan the remote url: ${REMOTE_URL} \
  with configurations { IAC type: ${IAC}, IAC version: ${IAC_VERSION},  remote type: ${REMOTE_TYPE} , cloud provider: ${CLOUD_PROVIDER}}"


RESPONSE=$(curl -s -w \\n%{http_code} --location -k  --request POST "$SCAN_URL" \
--header 'Content-Type: application/json' \
--data-raw '{
"remote_type":"'${REMOTE_TYPE}'",
"remote_url":"'${REMOTE_URL}'"
}')

echo "$RESPONSE"

HTTP_STATUS=$(printf '%s\n' "$RESPONSE" | tail -n1)

if [ "$HTTP_STATUS" -eq 403 ]; then
    exit 3
elif [ "$HTTP_STATUS" -eq 200 ]; then
    exit 0
else
    exit 1
fi

Step 3: Configure PreSync hook to use container created in step 2

The following example hook yaml is mostly ready to be added to an existing kubernetes configuration.

apiVersion: batch/v1
kind: Job
metadata:
generateName: terrascan-hook-
namespace: <YOUR APP NAMESPACE>
annotations:
  argocd.argoproj.io/hook: PreSync
spec:
ttlSecondsAfterFinished: 3600
template:
  spec:
    securityContext:
      seccompProfile:
        type: RuntimeDefault
    containers:
    - name: terrascan-argocd
      image: <IMAGE FROM STEP TWO>
      resources:
        requests:
          cpu: "1"
          memory: "256Mi"
        limits:
          cpu: "1"
          memory: "256Mi"
      env:
        - name: SERVICE_NAME
          value: <Name of service exposed for terrascan controller pod>
        - name: REMOTE_URL
          value: <YOUR PRIVATE REPOSITORY PATH>
        - name: IAC_TYPE
          value: <IAC TYPE YOU WANT SCAN> # If not provided default value is 'k8s'
        - name: IAC_VERSION
          value: <VERSION OF IAC TYPE SELECTED> # If not provided default value is 'v1'
        - name: CLOUD_PROVIDER
          value: <TYPE OF CLOUD PROVIDER> #If not provided default value is 'all'
        - name: REMOTE_TYPE
          value: <TYPE OF REMOTE> #If not provided default value is 'git'
      args:
      - sh
      - /home/terrascan/bin/terrascan-remote-scan.sh
      securityContext:
        seccompProfile:
          type: RuntimeDefault
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        runAsNonRoot: true
        runAsUser: 101
      livenessProbe:
        exec:
          command:
          - cat
          - /home/terrascan/bin/terrascan-remote-scan.sh
        periodSeconds: 10
        initialDelaySeconds: 10
      readinessProbe:
        exec:
          command:
          - cat
          - /home/terrascan/bin/terrascan-remote-scan.sh
        periodSeconds: 10
        initialDelaySeconds: 10
    restartPolicy: Never
backoffLimit: 1

To allow users to check for violations in the web interface, configure the job to delete after the specified time, using the parameter ttlSecondsAfterFinished. In addition, violation can be reported as webhook notifications, as shown in Method 1.

After configuring the presynchook yaml file, add the file to the relevant repository folder to configure Argo CD.

Note: All the example yaml configuration files present in documentation are tested with k8s 1.19.7 version.

3.3 - Atlantis PR Automation

You can integrate Terrascan into an Atlantis setup using one of the two ways:

• Method 1: Atlantis Workflow-based integration which sends scan requests to an independently running terraform server
• Method 2: Custom Atlantis container image which has an integrated Terrascan

In either scenario, the configuration of Atlantis varies from installation to installation. For instructions to install, configure, and use Atlantis, see the Atlantis documentation.

Method 1: Workflow-based integration

In this method, you can 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 following requirements must be met before starting the integration workflow:

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

Integration steps for Workflow based integration

• Modify Workflow
• Configure the Script
• Run Atlantis

Modify Workflow

1. Modify your workflow to call terrascan-remote-scan.sh during the plan stage.
2. See the ‘plan’ detailed below:

• the first three run: terraform commands are the default for an atlantis workflow.

Note: The values for the variables $WORKSPACE and $PLANFILE referenced in the second and third run commands in the yaml below are automatically provided by atlantis

• The fourth run terrascan-remote-scan.sh initiates the Terrascan scan request.

Note: By default, the terrascan-remote-scan.sh script can be found under the scripts directory in this project; copy this 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 in the fourth run command.

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

Script configuration

Modify the terrascan-remote-scan.sh script according your environment. The script is located here. Open the script with your any editor of your choice and review the following six settings which is found at 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 allows you to specify the scan response for low-severity findings in the code. During a scan 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 the terrascan-workflow.yaml as a server-side repo configuration. The command for this depends on how you choose to deploy Atlantis. If running the Atlantis binary directly, use 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

Note: The variables in the example above must be configured separately using export or similar shell methods.

Important: Before the first pull request is processed, run Terrascan in server mode using the following command:

terrascan server

Automated scanning and results

When the systems are running, if Atlantis is initiated either via a pull request, or via a comment of atlantis plan, Terrascan will be also be invoked as part of the atlantis plan flow. Scan results are reported as part of the pull request as comments, this notifies the reviewers before approving a requests. If any issues are found the test will be marked as failed.

Method 2: Custom Atlantis Container

Terrascan offers a custom container built on top of the official Atlantis container image, which allows users to run IaC scans with Terrascan, in addition to the usual atlantis usage. There’s a built-in atlantis workflow configured inside the container which is ready to be used. The default workflow.yaml file used is the atlantis/workflow.yaml in the Terrascan repo. Alternatively, you can also override that default workflow using the --repo-config flag.

Steps to use the custom Atlantis container

In code repository, usage is exactly the same as atlantis, add a comment atlantis plan and atlantis plan to your Pull Requests to trigger the custom atlantis-terrascan workflow.

To use the default built-in container image:

docker pull tenable/terrascan_atlantis

To build your own container image:

docker build ./integrations/atlantis -t <image_name>

Run the container:

docker run \
--env-file=<.env-file> \
-p 4141:4141 \
-v <pwd>/config_data/:/etc/terrascan/ \
tenable/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 specify the file path for the toml config to be used by 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.

Note: As a good practice, Terrascan recommends use of a specific tag of the container image rather than the latest tag.

Running a scan

With everything configured, a local Terrascan scan will be triggered as part of the Atlantis plan workflow.

3.4 - GitHub and GitLab

GitHub Action

The Terrascan GitHub Action can be used as part of GitHub workflows to scan your repository for IaC issues as part of code pushes or pull requests.

Using Terrascan’s SARIF output, the action can include issues found during the scan within GitHub’s code scanning results for the repository.

Below is an example workflow configuration where the action is configured to scan a repository including Terraform v14+ HCL files for AWS resources and the SARIF output of the scan is uploaded to GitHub code scanning.

on: [push]

jobs:
  terrascan_job:
    runs-on: ubuntu-latest
    name: terrascan-action
    steps:
    - name: Checkout repository
      uses: actions/checkout@v2
    - name: Run Terrascan
      id: terrascan
      uses: tenable/terrascan-action@main
      with:
        iac_type: 'terraform'
        iac_version: 'v14'
        policy_type: 'aws'
        only_warn: true
        sarif_upload: true
        #non_recursive:
        #iac_dir:
        #policy_path:
        #skip_rules:
        #config_path:
    - name: Upload SARIF file
      uses: github/codeql-action/upload-sarif@v1
      with:
        sarif_file: terrascan.sarif

A detailed explanation of the action’s input variables is available in the terrascan-action repository.

GitLab CI

GitLab CI can use Docker images as part of a pipeline. We can take advantage of this functionality and use Terrascan’s docker image as part of your pipeline to scan infrastructure as code.

To do this you can update your .gitlab-ci.yml file to use the “accurics/terrascan:latest” image with the [“bin/sh”, “-c”] entrypoint. Terrascan can be found on “/go/bin” in the image and you can use any Terrascan command line options according to your needs. Here’s an example .gitlab-ci.yml file:

stages:
  - scan

terrascan:
  image:
    name: tenable/terrascan:latest
    entrypoint: ["/bin/sh", "-c"]
  stage: scan
  script:
    - /go/bin/terrascan scan .

Argo CD Application PreSync Hooks

Terrascan can be configured as an Argo CD job during the application sync process using resource hooks. The PreSync resource hook is the best way to evaluate the kubernetes deployment configuration and report any violations.

Adding the Terrascan job consists of two steps:

1. Creating a container which runs Terrascan
2. Configuring a PreSync hook which uses that container

We’ll address the PreSync hook first.

Step 1: Configure PreSync resource hook

The following example hooks yaml is mostly ready to be added to an existing kubernetes configuration. Just make sure the secrets volume is relevant, specify your new Terrascan container image, and make sure the embedded script scans your repo and sends notifications to your Slack webhook endpoint.

apiVersion: batch/v1
kind: Job
metadata:
  generateName: terrascan-hook-
  annotations:
    argocd.argoproj.io/hook: PreSync
spec:
  ttlSecondsAfterFinished: 3600
  template:
    spec:
      volumes:
      - name: secret-volume
        secret:
          secretName: ssh-key-secret
      containers:
      - name: terrascan-argocd
        image: "<your container namespace>/<your container build from step #2 below>:<hash>"
        command: ["/bin/ash", "-c"]
        args:
        - >
          cp /etc/secret-volume/ssh-privatekey /home/terrascan/.ssh/id_rsa &&
          chmod 400 /home/terrascan/.ssh/id_rsa &&
          /go/bin/terrascan scan -r git -u <git URL to scan> -i k8s -t k8s | /home/terrascan/bin/notify_slack.sh webhook-tests argo-cd https://hooks.slack.com/services/TXXXXXXXX/XXXXXXXXXXX/0XXXXXXXXXXXXXXXXXX          
        volumeMounts:
          - name: secret-volume
            readOnly: true
            mountPath: "/etc/secret-volume"
      restartPolicy: Never
  backoffLimit: 1

As shown, the PreSync requires access to the repository where IaC is stored, using the same branch (default) as the Argo CD application pipeline.

For non-public repositories, the private key needs to be added as a kubernetes secret.

  kubectl create secret generic ssh-key-secret \
    --from-file=ssh-privatekey=/path/to/.ssh/id_rsa \
    --from-file=ssh-publickey=/path/to/.ssh/id_rsa.pub

Configuring the job to delete only after the specified time see ttlSecondsAfterFinished will allow users to check for violations in the User Interface, the alternative is through notifications.

Step 2: Create Terrascan container

The container which runs Terrascan can be built using the following files: known_hosts, notify_slack.sh, Dockerfile.

known_hosts

The known_hosts file ensures that the container will be able to clone your project’s git repository in order to scan it. Hashes for the most common public repository hosts are included here, and you may add hashes for any private hosts which you need to access in order to clone your project.

# known_hosts
github.com,192.30.255.113 ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==
bitbucket.org,104.192.141.1 ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAubiN81eDcafrgMeLzaFPsw2kNvEcqTKl/VqLat/MaB33pZy0y3rJZtnqwR2qOOvbwKZYKiEO1O6VqNEBxKvJJelCq0dTXWT5pbO2gDXC6h6QDXCaHo6pOHGPUy+YBaGQRGuSusMEASYiWunYN0vCAI8QaXnWMXNMdFP3jHAJH0eDsoiGnLPBlBp4TNm6rYI74nMzgz3B9IikW4WVK+dc8KZJZWYjAuORU3jc1c/NPskD2ASinf8v3xnfXeukU0sJ5N6m5E8VLjObPEO+mN2t/FZTMZLiFqPWc/ALSqnMnnhwrNi2rbfg/rd/IpL8Le3pSBne8+seeFVBoGqzHM9yXw==
gitlab.com,172.65.251.78 ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFSMqzJeV9rUzU4kWitGjeR4PWSa29SPqJ1fVkhtj3Hw9xjLVXVYrU9QlYWrOLXBpQ6KWjbjTDTdDkoohFzgbEY=

notify_slack.sh

The notify_slack.sh script is used to send a Slack notification after the scan completes. This example expects the channel name, username, and webhook URL to be passed as command line arguments from the PreSync hook which invokes this container. You may modify this script if you wish to send notifications in a different way.

#!/bin/ash
# notify_slack.sh

function send_slack_notificaton {
  channel=$1
  username=$2
  slack_hook=$3

  curl -X POST --data-urlencode payload="{\"channel\": \"#${channel}\", \"username\": \"${username}\", \"text\": \" \`\`\` $(cat results.out) \`\`\` \", \"icon_emoji\": \":ghost:\"}" ${slack_hook}
}

if [ -p /dev/stdin ]; then
  echo "processing terrascan results"
  while IFS= read line; do
          echo "${line}" | tr '\\"' ' ' >> results.out
  done

  cat results.out

  send_slack_notificaton $1 $2 $3

  echo "notification exit code: $?"
else
  echo "no response skipping"
fi

Dockerfile

The Dockerfile is, of course, used to build the container. In this case, we start with the official Terrascan image and we add in the above files to ensure we can access the repository and send notifications.

# Dockerfile
  FROM tenable/terrascan:929e377

  ENTRYPOINT []

  USER root

  RUN apk add --no-cache openssh curl

  WORKDIR /home/terrascan

  RUN mkdir -p .ssh && mkdir -p bin

  COPY known_hosts .ssh

  COPY notify_slack.sh bin/

  RUN chown -R terrascan:terrascan .ssh && \
      chown -R terrascan:terrascan bin && \
      chmod 400 .ssh/known_hosts && \
      chmod u+x bin/notify_slack.sh

  USER terrascan

  CMD ["ash"]

Once you’ve built the image and pushed to your container registry, you can add the PreSync hook which will automatically run Terrascan during the application sync process.

3.5 - Pre-commit hook

Integrating Terrascan with Pre-commit

Overview

Terrascan scan can be used as a pre-commit hook in order to automatically scan your IaC before every commit. For more information about pre-commit hooks see https://pre-commit.com/#intro

Requirements

• Ensure Terrascan is properly installed (See https://runterrascan.io/docs/getting-started/#installing-terrascan)
• Have Pre-commit package manager installed (See https://pre-commit.com/#install)

Integration Method

Add config file

1. Add file called .pre-commit-config.yaml to root of repo you wish to scan with pre-commit. It should look like this:

repos:
    - repo: https://github.com/tenable/terrascan
        rev: <COMMIT/VERSION>
        hooks:
        - id: terraform-pre-commit
            args: [ '-i <IAC PROVIDER>'] #optional

Note: The optional args line allows you to specify the IaC provider. For example,

repos:
    - repo: https://github.com/tenable/terrascan
        rev: <COMMIT/VERSION>
        hooks:
        - id: terraform-pre-commit
            args: [ '-i k8s']

will cause

'terrascan scan -i k8s'

to run and thus scan kubernetes yaml files. You may exclude the args like so:

repos:
    - repo: https://github.com/tenable/terrascan
        rev: <COMMIT/VERSION>
        hooks:
        - id: terraform-pre-commit

which causes the default

'terrascan scan'

to be run, scanning all IaC provider types.

Once you have everything installed, and add the appropriate config file to your repo,

'terrascan scan -i <IAC PROVIDER>'

everytime you attempt to commit your staged changes. You can also call the hook directly on all files using pre-commit run –all-files

4 - Architecture

Terrascan’s architecture is built to be modular to facilitate adding IaC languages and policies. At a high level Terrascan is composed of the following architectural components: a command line interface, API server, runtime, pluggable IaC providers, pluggable policy engine, notifier, and writer.

• Command Line Interface = Provides CLI input to Terrascan.
• API Server = Provides input to Terrascan through an API.
• Runtime = Performs input validation and process inputs
• IaC Providers = Converts IaC language into normalized JSON
• Policy Engine = Applies policies against normalized JSON
• Notifier = Provides webhooks for results of Terrascan scans.
• Writer = Writes results into various formats like JSON, YAML, or XML.

5 - Policies

5.1 - Policy Overview

Terrascan policies are written using the Rego policy language. With each rego policy, a JSON “rule” file is included which defines metadata for the policy. Policies included within Terrascan are stored in the pkg/policies/opa/rego directory.

Updating Terrascan with the latest policies

The first time using Terrascan, if the -p flag is not specified, Terrascan will download the latest policies from the Terrascan repository. You can update your local environment to the latest policies published in the repository by running terrascan init.

Ignoring Policies on a scan

Terrascan keeps a copy of policies on your local filesystem on the ~/.terrascan/pkg/policies/opa/rego directory. You can also specify a particular directory with rego policies to scan by using the -p flag. Terrascan allows you to ignore policies from scans by using the –skip-rules flag or using in-file instrumentation to skip policies on a particular resource.

Adding policies

For each policy, there are 2 files required by Terrascan, a rule .json file with metadata for the policy and a .rego rego file for the policy itself.

Writing an OPA rego policy file

The input for the rego policies is the normalized input from the IaC provider. When writing policies you can obtain this as a normalized .json by using the --config-only flag of the scan command in combination with -o json. Let’s use this Terraform HCL file for example:

resource "github_repository" "example" {
  name        = "example"
  description = "My awesome codebase"

  private = false

  template {
    owner = "github"
    repository = "terraform-module-template"
  }
}

Here’s the output of the --config-only flag.

$ terrascan scan -i terraform --config-only -o json
{
  "github_repository": [
    {
      "id": "github_repository.example",
      "name": "example",
      "source": "main.tf",
      "line": 1,
      "type": "github_repository",
      "config": {
        "description": "My awesome codebase",
        "name": "example",
        "private": false,
        "template": [
          {
            "owner": "github",
            "repository": "terraform-module-template"
          }
        ]
      }
    }
  ]
}

You can use this .json output as the input in the rego playgound. The following policy can be used on the above Terraform to flag if the GitHub repository has been created with private = false.

package accurics

privateRepoEnabled[api.id] {
    api := input.github_repository[_]
    not api.config.private == true
    not api.config.visibility == "private"
}

A successful policy will trigger the following output:

{
    "privateRepoEnabled": [
        "github_repository.example"
    ]
}

The Rule JSON file

The rule files follow this naming convention: AC_<policy_type>_<next_available_rule_number>.json where <policy_type> is the upper case of any supported policy types by terrascan. The supported policy types can be fetched from Terrascan’s help menu: terrascan scan -h | grep "policy-type".

Note: The previous naming convention was: <cloud-provider>.<resource-type>.<rule-category>.<severity>.<next-available-rule-number>.json. This has been deprecated.

Here’s an example of the contents of a rule file:

{
	"name": "unrestrictedIngressAccess",
	"file": "unrestrictedIngressAccess.rego",
	"policy_type": "aws",
	"resource_type": "aws_db_security_group",
	"template_args": {
		"name": "unrestrictedIngressAccess",
		"prefix": "",
		"suffix": ""
	},
	"severity": "HIGH",
	"description": "It is recommended that no security group allows unrestricted ingress access",
	"category": "NETWORK_SECURITY",
	"version": 1,
	"id": "AC_AWS_0001"
}

5.2 - AWS Policies

aws_iam_role_policy

aws_route53_record

aws_elasticsearch_domain_policy

aws_lb_target_group

aws_api_gateway_method_settings

aws_workspaces_workspace

aws_vpc

aws_iam_account_password_policy

aws_mq_broker

aws_db_instance

aws_secretsmanager_secret_policy

aws_ebs_volume

aws_api_gateway_rest_api

aws_iam_role

aws_iam_user_policy_attachment

aws_ebs_encryption_by_default

aws_sns_topic

aws_apigatewayv2_api

aws_efs_file_system

aws_lb_listener

aws_sqs_queue

aws_docdb_cluster

aws_cloudwatch_log_group

aws_instance

aws_config

aws_cloudformation_stack

aws_iam_user_policy

aws_ecs_task_definition

aws_ecr_repository_policy

aws_iam_policy

aws_dynamodb_table

aws_apigatewayv2_stage

aws_ecr_repository

aws_cloudfront_distribution

aws_cloudwatch

aws_ami_launch_permission

aws_launch_configuration

aws_athena_database

aws_api_gateway_stage

aws_elasticsearch_domain

aws_iam_user_login_profile

aws_iam_group_policy

aws_load_balancer_policy

aws_s3_bucket

aws_eks_cluster

aws_elb

aws_redshift_cluster

aws_elasticcache_replication_group

aws_kinesis_stream

aws_config_configuration_aggregator

aws_s3_bucket_object

aws_route53_query_log

aws_secretsmanager_secret

aws_iam_access_key

aws_neptune_cluster

aws_dax_cluster

aws_guardduty_detector

aws_db_security_group

aws_s3_bucket_policy

aws_ami

aws_elasticache_cluster

aws_kinesis_firehose_delivery_stream

aws_rds_cluster

aws_cloudtrail

aws_sagemaker_notebook_instance

aws_lambda_function

aws_kms_key

aws_security_group

aws_api_gateway_method

aws_efs_file_system_policy

aws_ecs_service

aws_globalaccelerator_accelerator

aws_api_gateway_rest_api_policy

5.3 - Azure Policies

azurerm_storage_container

azurerm_mysql_server

azurerm_sql_firewall_rule

azurerm_key_vault

azurerm_resource_group

azurerm_storage_account_network_rules

azurerm_storage_account

azurerm_sql_server

azurerm_postgresql_configuration

azurerm_sql_database

azurerm_redis_cache

azurerm_mssql_server

azurerm_kubernetes_cluster

azurerm_managed_disk

azurerm_network_watcher_flow_log

azurerm_key_vault_secret

azurerm_key_vault_key

azurerm_security_center_contact

azurerm_network_security_rule

azurerm_cosmosdb_account

azurerm_security_center_subscription_pricing

azurerm_sql_active_directory_administrator

azurerm_container_registry

azurerm_virtual_network

azurerm_role_assignment

azurerm_application_gateway

azurerm_postgresql_server

5.4 - GCP Policies

google_container_node_pool

github_repository

google_bigquery_dataset

google_compute_project_metadata

google_compute_subnetwork

google_project_iam_audit_config

google_sql_database_instance

google_compute_instance

google_storage_bucket_iam_binding

google_container_cluster

google_project

google_compute_firewall