Skip to content

Commit

Permalink
adds getting started guide
Browse files Browse the repository at this point in the history
  • Loading branch information
Cesar Rodriguez committed Aug 16, 2020
1 parent 949b9d9 commit 9814799
Showing 1 changed file with 167 additions and 39 deletions.
206 changes: 167 additions & 39 deletions docs/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Terrascan is a static code analyzer for Infrastructure as Code tooling. It can e
## Installation
Terrascan's binary can be found on the package for each [release](/~https://github.com/accurics/terrascan/releases). Here's an example of how to install it:

``` Bash linenums="1"
``` Bash
$ curl --location /~https://github.com/accurics/terrascan/releases/download/v1.0.0/terrascan_darwin_amd64.zip --output terrascan_darwin_amd64.zip
$ unzip terrascan_darwin_amd64.zip
Archive: terrascan_darwin_amd64.zip
Expand All @@ -16,84 +16,212 @@ $ terrascan --help
### Using Docker
Terrascan is available as a Docker image and can used as follows:

``` Bash linenums="1"
``` Bash
$ docker run accurics/terrascan
```

### Installing on macOS
For Mac users, Terrascan can be installed using Homebrew:

``` Bash linenums="1"
``` Bash
brew install terrascan
```

### Building Terrascan
Terrascan can be built locally. This is helpful if you want to be on the latest version or when developing Terrascan.

``` Bash linenums="1"
``` Bash
$ git clone git@github.com:accurics/terrascan.git
$ cd terrascan
$ make build
$ ./bin/terrascan
```

## Scanning
## Terrascan Commands
Terrascan's interface is divided into subcommands as follows:

* init = Will initialize Terrascan by downloading the latest Rego policies into ~/.terrascan. Note that the scan command will implicitly call this if it detects that there are no policies found.
* scan = Will scan IaC files based on the policies contained within the .terrascan directory
* server = Will start Terrascan's API server
* help = You can obtain the usage menu by typing `help` or using the `-h` flag on any subcommand (e.g. `terrascan init -h`)

By typing `terrascan` without flags or other arguments, you can display the usage information.

``` Bash linenums="1"
``` Bash
$ terrascan

Terrascan

Scan IaC files for security violations
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
Usage:
terrascan [command]

terrascan -cloud [aws|azure|gcp] [options...]
Available Commands:
help Help about any command
init Initialize Terrascan
scan Detect compliance and security violations across Infrastructure as Code.
server Run Terrascan as an API server

Options
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 (json, yaml, xml) (default "yaml")
-v, --version version for terrascan

Cloud
-cloud Required. Cloud provider (supported values: aws, azure, gcp)

IaC (Infrastructure as Code)
-d IaC directory path (default: current working directory)
-f IaC file path
-iac IaC provider (supported values: terraform, default: terraform)
-iac-version IaC version (supported values: 'v12' for Terraform, default: v12)
-p Policy directory path
Use "terrascan [command] --help" for more information about a command.
```

Mode
-server Run Terrascan in server mode
### Initializing
The initialization process downloads the latest policies from the [repository](/~https://github.com/accurics/terrascan) into `~/.terrascan`. The policies are located at `~/.terrascan/pkg/policies/opa/rego` and are fetched when scanning the IaC. This command is implicitly executed if the `scan` command doesn't found policies while executing.

Logging
-log-level Logging level (supported values: debug, info, warn, error, panic, fatal)
-log-type Logging type (supported values: json, yaml, console, default: console)
### Scanning
The CLI will default to the `scan` command if no other subcommands are used. For example, the below two commands will scan the current directory containing Terraform HCL2 files for AWS resources:

Miscellaneous
-config Configuration file path
-version Print the Terrascan version
``` Bash
$ terrascan -t aws
$ terrascan scan -t aws
```

The `scan` command support flags to configure: the directory being scanned, scanning of a specific file, IaC provier type, path to policies, and policy type. The full list of flags can be found by typing `terrascan scan -h`

``` Bash linenums="1"
$ terrascan -cloud aws -iac terraform -iac-version v12 -p $REGO_POLICIES -d . --output json
``` Bash
$ 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:
-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 (terraform) (default "terraform")
--iac-version string iac version (v12) (default "v12")
-p, --policy-path string policy path directory
-t, --policy-type string <required> policy type (aws, azure, gcp)

Global Flags:
-c, --config-path string config file path
-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 (json, yaml, xml) (default "yaml")
```

### Example scanning Terraform (HCL2)
By default Terrascan will output YAML. This can be changed to JSON or XML by using the `-o` flag.

### Server mode
Server mode will execute Terrascan's API server. This is useful when using Terrascan to enforce policies in a centralized way. By default the server will be started listening in port 9010 and supports the following routes:

Here's an example of scanning Terraform HCL2 files containing AWS resources:
* GET /health = Returns the health status of the server
* POST /v1/{iacType}/{iacVersion}/{policyType}/local/file/scan} = The payload for this request should include a `file` parameter with the value being the contents of the file.

``` Bash linenums="1"
terrascan -cloud aws -d ~/iac_folder
You can launch server mode by executing the Terrascan CLI or with the Docker container:

``` Bash
$ terrascan server
```
You can also launch Terrascan using Docker:

``` Bash
$ docker run --rm --name terrascan -p 9010:9010 accurics/terrascan
```
In the example above, the `-cloud` flag is used to specify AWS as the cloud provider and the `-d` flag is used to specify the directory to scan.

### Launch Terrascan in server mode
Here's an example of how to send a request to the Terrascan server using curl:

``` Bash
$ curl -i -F "file=@aws_cloudfront_distribution.tf" localhost:9010/v1/terraform/v12/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
}
}
}
```

To launch Terrascan in server mode you can execute the following:
### Config File
The `-c` or `--config-path` global variable allows you to provide a TOML configuration file for Terrascan. This file can be use to configure the webhook notifications. Here's an example configuration:

``` Bash linenums="1"
terrascan -server
``` TOML
[notifications]
[notifications.webhook]
url = "https://httpbin.org/post"
token = "my_auth_token"
```

### 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`.

0 comments on commit 9814799

Please sign in to comment.