README
¶
terrasec uses static analysis of your terraform code to spot potential misconfigurations.
Features
- ☁ Checks for misconfigurations across all major (and some minor) cloud providers
- ⛔ Hundreds of built-in rules
- 🪆 Scans modules (local and remote)
- ➕ Evaluates HCL expressions as well as literal values
- ↪ Evaluates Terraform functions e.g.
concat() - 🔗 Evaluates relationships between Terraform resources
- 🧰 Compatible with the Terraform CDK
- 🙅 Applies (and embellishes) user-defined Rego policies
- 📃 Supports multiple output formats: lovely (default), JSON, SARIF, CSV, CheckStyle, JUnit, text, Gif.
- 🛠 Configurable (via CLI flags and/or config file)
- ⚡ Very fast, capable of quickly scanning huge repositories
- 🔌 Plugins for popular IDEs available (JetBrains, VSCode and Vim)
- 🏡 Community-driven - come and chat with us on Slack!
Recommended by Thoughtworks
Rated Adopt by the Thoughtworks Tech Radar:
For our projects using Terraform, terrasec has quickly become a default static analysis tool to detect potential security risks. It's easy to integrate into a CI pipeline and has a growing library of checks against all of the major cloud providers and platforms like Kubernetes. Given its ease of use, we believe terrasec could be a good addition to any Terraform project.
Installation
Install with brew/linuxbrew
brew install terrasec
Install with Chocolatey
choco install terrasec
Install with Scoop
scoop install terrasec
Bash script (Linux):
curl -s https://raw.githubusercontent.com/khulnasoft-labs/terrasec/master/scripts/install_linux.sh | bash
You can also grab the binary for your system from the releases page.
Alternatively, install with Go:
go install github.com/khulnasoft-labs/terrasec/cmd/terrasec@latest
Please note that using go install will install directly from the master branch and version numbers will not be reported via terrasec --version.
Signing
The binaries on the releases page are signed with the terrasec signing key D66B222A3EA4C25D5D1A097FC34ACEFB46EC39CE
Form more information check the signing page for instructions on verification.
Usage
terrasec will scan the specified directory. If no directory is specified, the current working directory will be used.
The exit status will be non-zero if terrasec finds problems, otherwise the exit status will be zero.
terrasec .
Use with Docker
As an alternative to installing and running terrasec on your system, you may run terrasec in a Docker container.
There are a number of Docker options available
| Image Name | Base | Comment |
|---|---|---|
| khulnasoft/terrasec | alpine | Normal terrasec image |
| khulnasoft/terrasec-alpine | alpine | Exactly the same as khulnasoft/terrasec, but for those whole like to be explicit |
| khulnasoft/terrasec-ci | alpine | terrasec with no entrypoint - useful for CI builds where you want to override the command |
| khulnasoft/terrasec-scratch | scratch | An image built on scratch - nothing frilly, just runs terrasec |
To run:
docker run --rm -it -v "$(pwd):/src" khulnasoft/terrasec /src
Use with Visual Studio Code
A Visual Studio Code extension is being developed to integrate with terrasec results. More information can be found on the terrasec Marketplace page
Use as GitHub Action
If you want to run terrasec on your repository as a GitHub Action, you can use https://github.com/khulnasoft-labs/terrasec-pr-commenter-action.
Use as an Azure DevOps Pipelines Task
You can now install the official terrasec task. Please raise any issues/feature requests on the task repository.
Ignoring Warnings
You may wish to ignore some warnings. If you'd like to do so, you can
simply add a comment containing terrasec:ignore:<rule> to the offending
line in your templates. Alternatively, you can add the comment to the line above the block containing the issue, or to the module block to ignore all occurrences of an issue inside the module.
For example, to ignore an open security group rule:
resource "aws_security_group_rule" "my-rule" {
type = "ingress"
cidr_blocks = ["0.0.0.0/0"] #terrasec:ignore:aws-vpc-no-public-ingress-sgr
}
...or...
resource "aws_security_group_rule" "my-rule" {
type = "ingress"
#terrasec:ignore:aws-vpc-no-public-ingress-sgr
cidr_blocks = ["0.0.0.0/0"]
}
If you're not sure which line to add the comment on, just check the terrasec output for the line number of the discovered problem.
You can ignore multiple rules by concatenating the rules on a single line:
#terrasec:ignore:aws-s3-enable-bucket-encryption terrasec:ignore:aws-s3-enable-bucket-logging
resource "aws_s3_bucket" "my-bucket" {
bucket = "foobar"
acl = "private"
}
Expiration Date
You can set expiration date for ignore with yyyy-mm-dd format. This is a useful feature when you want to ensure ignored issue won't be forgotten and should be revisited in the future.
#terrasec:ignore:aws-s3-enable-bucket-encryption:exp:2025-01-02
Ignore like this will be active only till 2025-01-02, after this date it will be deactivated.
Disable checks
You may wish to exclude some checks from running. If you'd like to do so, you can
simply add new argument -e check1,check2,etc to your cmd command
terrasec . -e general-secrets-sensitive-in-variable,google-compute-disk-encryption-customer-keys
Including values from .tfvars
You can include values from a tfvars file in the scan, using, for example: --tfvars-file terraform.tfvars.
Included Checks
terrasec supports many popular cloud and platform providers
| Checks |
|---|
| AWS Checks |
| Azure Checks |
| GCP Checks |
| CloudStack Checks |
| DigitalOcean Checks |
| GitHub Checks |
| Kubernetes Checks |
| OpenStack Checks |
| Oracle Checks |
Running in CI
terrasec is designed for running in a CI pipeline. You may wish to run terrasec as part of your build without coloured
output. You can do this using --no-colour (or --no-color for our American friends).
Output options
You can output terrasec results as JSON, CSV, Checkstyle, Sarif, JUnit or just plain old human-readable format. Use the --format flag
to specify your desired format.
GitHub Security Alerts
If you want to integrate with Github Security alerts and include the output of your terrasec checks you can use the terrasec-sarif-action Github action to run the static analysis then upload the results to the security alerts tab.
The alerts generated for terrasec-example-project look like this.
When you click through the alerts for the branch, you get more information about the actual issue.
For more information about adding security alerts, check the GitHub documentation
Support for older terraform versions
If you need to support versions of terraform which use HCL v1
(terraform <0.12), you can use v0.1.3 of terrasec, though support is
very limited and has fewer checks.
Contributing
We always welcome contributions; big or small, it can be documentation updates, adding new checks or something bigger. Please check the Contributing Guide for details on how to help out.
Some People who have contributed
Made with contributors-img.
terrasec is an KhulnaSoft Security open source project.
Learn about our open source work and portfolio here.
Join the community, and talk to us about any matter in GitHub Discussion or Slack.
Directories