Terrascan: A Comprehensive Guide to the Infrastructure as Code (IaC) Scanning Tool

Column: Infrastructure as Code (IaC)

Infrastructure as Code (IaC) is an IT infrastructure management process that applies best practices from DevOps software development to the management of cloud infrastructure resources. These resources include virtual machines, networks, load balancers, databases, and other applications. 14 Subscribers • 45 Articles

1. Background

Infrastructure assets such as Dockerfiles, Kubernetes resource manifests, and Terraform .tf files require regular detection and scanning to ensure security and compliance. This is where IaC scanning tools like Terrascan play a critical role.

2. What is Terrascan?

2.1 Overview

Terrascan is a static code analyzer specifically designed for Infrastructure as Code (IaC). It supports multiple installation and execution methods, with its most common use case being in automated pipelines — identifying policy violations before insecure infrastructure is provisioned.

2.2 Key Features

Terrascan enables you to:

• Seamlessly scan IaC files for misconfigurations.
• Monitor provisioned cloud infrastructure to prevent configuration drift and restore secure postures when needed.
• Detect security vulnerabilities and compliance violations early in the development cycle.
• Mitigate risks before deploying cloud-native infrastructure.
• Run locally or integrate with CI/CD pipelines for flexible workflow adoption.

3. Installation

Terrascan is a portable executable (no complex installation required) and is also available as a container image on Docker Hub. Choose one of the following methods based on your environment:

3.1 Installation for macOS & Linux

Use the following command sequence to download, extract, and install Terrascan:

# Download the latest Terrascan release for Darwin/x86_64
$ curl -L "$(curl -s https://api.github.com/repos/accurics/terrascan/releases/latest | grep -o -E "https://.+?_Darwin_x86_64.tar.gz")" > terrascan.tar.gz

# Extract the executable and remove the tarball
$ tar -xf terrascan.tar.gz terrascan && rm terrascan.tar.gz

# Install Terrascan to /usr/local/bin and clean up
$ install terrascan /usr/local/bin && rm terrascan

# Verify installation (should display Terrascan help info)
$ terrascan

3.2 Installation via Docker

For containerized environments, use the official Terrascan image from Docker Hub:

# Verify the Docker image and check Terrascan version
$ docker run --rm accurics/terrascan version

# Create an alias for easier execution (mounts current directory to /iac in the container)
$ alias terrascan="docker run --rm -it -v "$(pwd):/iac" -w /iac accurics/terrascan"

4. Usage

Terrascan supports two primary operating modes: Command-Line Interface (CLI) and Server Mode.

4.1 Command-Line Mode

First, run terrascan without arguments to view the core command structure:

$ 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://docs.accurics.com

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")
  -x, --log-type string      log output type (console, json) (default "console")
  -o, --output string        output type (human, json, yaml, xml) (default "human")

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

Scan Specific Providers

Use the scan command with flags to target specific IaC providers or resources:

# Scan AWS IaC configurations (e.g., Terraform)
$ terrascan scan -t aws

# Scan Kubernetes manifests
$ terrascan scan -i k8s

# Scan remote Git repositories (example: AWS Terraform files in KaiMonkey repo)
$ terrascan scan -t aws -r git -u git@github.com:accurics/KaiMonkey.git//terraform/aws

# Scan Helm Charts
$ terrascan scan -i helm

# Scan Dockerfiles
$ terrascan scan -i docker

4.2 Server Mode

Running Terrascan as an API server ensures consistent policy enforcement across multiple stages of a software development pipeline. It also simplifies programmatic interactions with Terrascan.

By default, the HTTP server listens on port 9010 and supports the following core endpoints:

Endpoint 1: Scan IaC Files

• Method: POST
• URL: /v1/{iac}/{iacVersion}/{cloud}/local/file/scan
• Parameter: file (content of the IaC file to scan)

Example 1: Start the Terrascan Server

# Run the server natively
$ terrascan server

# Run the server via Docker (expose port 9010)
$ docker run --rm --name terrascan -p 9010:9010 accurics/terrascan

Example 2: Send a Scan Request via curl

Scan a Terraform file (e.g., aws_cloudfront_distribution.tf) for AWS configurations:

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

Sample Response

The server returns a JSON payload with detected violations, severity levels, and resource details:

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": "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
      }
    ],
    "count": {
      "low": 1,
      "medium": 1,
      "high": 1,
      "total": 3
    }
  }
}

5. CI/CD Integration

Terrascan integrates seamlessly with popular CI/CD platforms. Below is a step-by-step example for GitLab CI:

5.1 GitLab CI Configuration

GitLab CI supports Docker images as part of pipelines. Use the official Terrascan image to scan IaC files in your pipeline.

Update your .gitlab-ci.yml file with the following configuration:

stages:
  - scan  # Define a "scan" stage in the pipeline

terrascan-scan:
  image:
    name: accurics/terrascan:latest  # Use the latest Terrascan Docker image
    entrypoint: ["/bin/sh", "-c"]    # Set the entrypoint to run shell commands
  stage: scan  # Assign this job to the "scan" stage
  script:
    - /go/bin/terrascan scan .  # Run Terrascan on the current directory (IaC files)

References

• Official Terrascan Repository: https://github.com/accurics/terrascan
• Official Documentation: https://docs.accurics.com

About Me

My technical insights and resources are centralized on the following platforms, focusing on cloud-native, DevOps, Kubernetes, AIOps, GenAI,and related technologies:

• Personal Website: https://redhatxl.github.io (a hub for my technical notes, tutorials, and project updates)，https://kaliarch-web.pages.dev/
• GitHub: https://github.com/redhatxl (hosts representative projects like awesome-kubernetes-notes, kubectl-img, and k8s-prometheus-grafana)
• Certification Profile: https://www.credly.com/users/redhatxl (showcases authoritative certifications including AWS Certified DevOps Professional, Azure Solutions Architect Expert, and HashiCorp Terraform Certified Associate)