Skip to content

Commit

Permalink
Documentation (#768)
Browse files Browse the repository at this point in the history 
* testing doc changes

* More edits done in the readme file

* work in progress draft - info marked as tbd needs to be added

* Update README.md

Co-authored-by: amirbenv <74685902+amirbenv@users.noreply.github.com>

* Update docs/getting-started.md

Co-authored-by: amirbenv <74685902+amirbenv@users.noreply.github.com>

* Update docs/getting-started.md

Co-authored-by: amirbenv <74685902+amirbenv@users.noreply.github.com>

* Update README.md

* Update README.md

* Update README.md

* Update docs/getting-started.md

* Update getting-started.md

Co-authored-by: amirbenv <74685902+amirbenv@users.noreply.github.com>
  • Loading branch information
@lalchand12 @amirbenv
lalchand12 and amirbenv authored May 18, 2021
1 parent 940a446 commit 53eda39
Show file tree
Hide file tree
Showing 2 changed files with 109 additions and 55 deletions.
114 changes: 72 additions & 42 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,49 +8,84 @@
[![community](https://img.shields.io/discourse/status?server=https%3A%2F%2Fcommunity.accurics.com)](https://community.accurics.com)
[![Documentation Status](https://readthedocs.com/projects/accurics-terrascan/badge/?version=latest)](https://docs.accurics.com/projects/accurics-terrascan/en/latest/?badge=latest)
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](code_of_conduct.md)
[![Homebrew](https://img.shields.io/badge/dynamic/json.svg?url=https://formulae.brew.sh/api/formula/terrascan.json&query=$.versions.stable&label=homebrew)](https://formulae.brew.sh/formula/terrascan)

Terrascan detects security vulnerabilities and compliance violations across your Infrastructure as Code. Mitigate risks before provisioning cloud native infrastructure. Run locally or integrate with your CI\CD.
## Introduction

Terrascan is a static code analyzer for Infrastructure as Code. Terrascan allow you to:

* Documentation: https://docs.accurics.com/projects/accurics-terrascan
- seamlessly scan infrastructure as code for misconfigurations
- monitor provisioned cloud infrastructure for configuration changes that introduce posture drift, and enables reverting to a secure posture.
- Detect security vulnerabilities and compliance violations.
- Mitigate risks before provisioning cloud native infrastructure.
- Offers flexibility to run locally or integrate with your CI\CD.

### Resources

* To learn more about Terrascan's features and capabilities, see the documentation portal: https://docs.accurics.com/projects/accurics-terrascan
* Discuss: https://community.accurics.com

## Features
## Key features
* 500+ Policies for security best practices
* Scanning of Terraform (HCL2)
* Scanning of Kubernetes (JSON/YAML), Helm v3, and Kustomize v3
* Support for AWS, Azure, GCP, Kubernetes and GitHub


## Quick Start

1. [Install](#install)
2. [Scan](#scan)
3. [Integrate](#integrate)

### Step 1: Install
Terrascan's supports multiple ways to install, including [brew](https://github.com/accurics/terrascan#install-via-brew).
Here, we will download the terrascan binary directly from the [releases](https://github.com/accurics/terrascan/releases) page. Make sure to select the right binary for your machine. Here's an example of how to install it:
Terrascan's supports multiple ways to install and is also available as a Docker image.
See Terrascan's [releases](https://github.com/accurics/terrascan/releases) page for latest version of builds in all supported platforms. Select the correct binary for your platform.

#### Install as a native executable

```sh
$ 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
$ tar -xf terrascan.tar.gz terrascan && rm terrascan.tar.gz
$ install terrascan /usr/local/bin && rm terrascan
$ terrascan
```
### Step 2: Run

#### Install via `brew`

[Homebrew](https://brew.sh/) users can install by:

```sh
$ brew install terrascan
```

#### Docker image

Terrascan is also available as a Docker image and can be used as follows

```sh
$ docker run accurics/terrascan
```
Refer to [documentation](https://docs.accurics.com/projects/accurics-terrascan/en/latest/getting-started/) for information.

### Step 2: Scan
To scan your code for security issues you can run the following (defaults to scanning Terraform).

```sh
$ terrascan scan
```
Terrascan will exit 3 if any issues are found.
**Note**: Terrascan will exit with an error code 3 if any issues are found during a scan.

### Step 3: Integrate with CI\CD

Terrascan can be integrated into CI/CD pipelines to enforce security best practices.
Please refer to our [documentation to integrate with your pipeline](https://docs.accurics.com/projects/accurics-terrascan/en/latest/integrations/cicd/).

The following commands are available:
## Terrascan Commands
You can use terrascan command with the following options:

```sh
$ 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]

Expand All @@ -71,51 +106,47 @@ Flags:
Use "terrascan [command] --help" for more information about a command.
```

### Step 3: Integrate with CI\CD
Please refer to our [documentation to integrate with your pipeline](https://docs.accurics.com/projects/accurics-terrascan/en/latest/integrations/cicd/).
## Policies
Terrascan policies are written using the [Rego policy language](https://www.openpolicyagent.org/docs/latest/policy-language/). Every rego includes a JSON "rule" file which defines metadata for the policy.
By default, Terrascan downloads policies from Terrascan repositories while scanning for the first time. However if you want to download the latest policies, you need to run the Initialization process. See [Usage](./usage.md) for information about the Initialization process.

Note: The scan command will implicitly run the initialization process there are no policies found.

## Rule Suppression
If a resource should not be tested against a particular rule, you can tell terrascan to skip it.
## Customizing scans

### Terraform
In Terraform scripts, you can tell terrascan to skip rules by inserting a comment with the phrase "ts:skip=RULENAME SKIP_REASON". The comment should be inside the resource.
By default, Terrascan scans your entire configuration against all policies. However you can configure what you want to scan in the following ways:

![tf](https://user-images.githubusercontent.com/74685902/105115888-847b8a00-5a7e-11eb-983e-7f49f7c36ae1.png)

### Kubernetes
In Kubernetes yamls, you can tell terrascan to skip rules by adding an annotation as seen in the snippet below.
- [Exclude a particular policy for a specific resource.](#How_to_exclude_a_policy_while_scanning_a_resource)
- [Manually configure policies to be suppressed or applied globally from a scan across all resources or, for just a particular resource.](#_How_to_include_or_exclude_specific_policies_or_resources_from_being_scanned)

![k8s](https://user-images.githubusercontent.com/74685902/105115885-834a5d00-5a7e-11eb-9190-e8b64d77c5ac.png)
### How to exclude a policy while scanning a resource

### Broad Rule Suppression
Use our config file to manually pick which rules should be applied or suppressed from the entire scan. This is suitable for edge use cases. Please use in-file suppression to specify resources that shouldn't be tested against particular rules. This ensures that the rules are skipped only for particular resources, rather than all of the resources.
You can configure Terrascan to skip a particular policy (rule) while scanning a resource. Follow these steps depending on your platform:

![config](https://user-images.githubusercontent.com/74685902/105115887-83e2f380-5a7e-11eb-82b8-a1d18c83a405.png)
#### Terraform
Use Terraform scripts to configure Terrascan to skip rules by inserting a comment with the phrase `"ts:skip=<RULENAME><SKIP_REASON>"`. The comment should be included inside the resource as shown in the example below.

### Sample Output
![Screenshot 2021-01-19 at 10 52 47 PM](https://user-images.githubusercontent.com/74685902/105115731-32d2ff80-5a7e-11eb-93b0-2f0620eb1295.png)
![tf](https://user-images.githubusercontent.com/74685902/105115888-847b8a00-5a7e-11eb-983e-7f49f7c36ae1.png)

## Other Installation Options
#### Kubernetes
In Kubernetes yamls, you can configure Terrascan to skip policies by adding an annotation as seen in the snippet below.

![k8s](https://user-images.githubusercontent.com/74685902/117906943-b9f4ef00-b28a-11eb-8224-37af18275ba1.png)

### Install via `brew`
### How to include or exclude specific policies or resources from being scanned

[Homebrew](https://brew.sh/) users can install by:
Use the Terrascan config file to manually select the policies which should be included or excluded from the entire scan. This is suitable for edge use cases.
Use the "in-file" suppression option to specify resources that should be excluded from being tested against selected policies. This ensures that the policies are skipped only for particular resources, rather than all of the resources.

```sh
$ brew install terrascan
```
![config](https://user-images.githubusercontent.com/74685902/105115887-83e2f380-5a7e-11eb-82b8-a1d18c83a405.png)

### Docker
Terrascan is also available as a Docker image and can be used as follows
### Sample scan output

```sh
$ docker run accurics/terrascan
```
Terrascan's default output is a list of violations present in the scanned IaC. A sample output:

![Screenshot 2021-01-19 at 10 52 47 PM](https://user-images.githubusercontent.com/74685902/105115731-32d2ff80-5a7e-11eb-93b0-2f0620eb1295.png)

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

```sh
Expand All @@ -136,7 +167,6 @@ RUN git clone https://github.com/accurics/terrascan && cd terrascan \
```


## Developing Terrascan
To learn more about developing and contributing to Terrascan refer to the [contributing guide](CONTRIBUTING.md).

Expand Down
50 changes: 37 additions & 13 deletions docs/getting-started.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,31 @@
# Quickstart
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 often used in automated pipelines to identify policy violations before insecure infrastructure is provisioned.
# Getting started

This document will show you two different methods for running Terrascan, one that installs Terrascan locally and another that leverages a Docker container. We will scan some vulnerable IaC to learn how that works and understand the output. The [usage page](./usage.md) includes more information about how Terrascan can be used.
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
## Quickstart

Terrascan is a portable executable that does not strictly require installation, and is also available as a container image in Docker Hub. The following sections explain how to use it as a [native executable](#native-executable) and how to use the [Docker image](#using-docker). Choose which one you'd like to start with; you don't need to do both.
Quickly get started with common tasks on Terrascan:

- [Running Terrascan for the First Time](#running-terrascan-for-the-first-time): Describes different methods for running Terrascan, one that installs Terrascan locally and another that leverages a Docker container. See below for details.

- [Scanning with Terrascan](#scanning-with-terrascan) - Explains how to scan vulnerable IaC using Terrascan with the an example including the scan output. See below for details.

## Running Terrascan for the First Time

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](#Native_executable)
2. [Using a Docker container](#Using_Docker)

The following sections explain how to use it as a [native executable](#native-executable) and how to use the [Docker image](#docker-image). You can choose from one of the following:

### Native executable
Terrascan's [release page](https://github.com/accurics/terrascan/releases) includes builds for common platforms. Just download and extract the package for your platform. For example, if you use a Mac you might do this:
Terrascan's [release page](https://github.com/accurics/terrascan/releases) 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`


``` Bash
$ 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
Expand All @@ -28,8 +45,15 @@ or:
``` Bash
$ alias terrascan="`pwd`/terrascan"
```
#### Windows

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

### Using Docker
```
tar -zxf terrascan_<version number>_Windows_x86_64.tar.gz
```

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

``` Bash
Expand All @@ -42,13 +66,14 @@ If you want to use the Docker image for the rest of this quickstart, it will hel
$ alias terrascan="docker run --rm -it -v "$(pwd):/iac" -w /iac accurics/terrascan"
```

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

## Scanning with Terrascan

When scanning with Terrascan, it defaults to scanning all supported cloud providers on Terraform HCL files.
### Example of interactive scan or using CLI


Our [KaiMonkey project](https://github.com/accurics/KaiMonkey) contains some vulnerable Terraform files to scan. Try the following:
In this example, the [KaiMonkey project](https://github.com/accurics/KaiMonkey) contains some vulnerable Terraform files to scan. To run a scan, follow these steps:

``` Bash
$ git clone https://github.com/accurics/KaiMonkey
Expand Down Expand Up @@ -116,7 +141,6 @@ Violation Details -
Severity : HIGH
-----------------------------------------------------------------------


Scan Summary -

File/Folder : /var/folders/2g/9lkfm6ld2lv350svwr15fdgc0000gn/T/x9wqg4/terraform/aws
Expand All @@ -131,10 +155,10 @@ Scan Summary -

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

Now that you understand how to run Terrascan, explore the other options available. The [usage page](./usage.md) covers the options in detail, including other IaC providers (e.g. Kubernetes, Helm, etc.), limiting the scan to specific directories or files, and outputting in different formats.
Now that you understand how to run Terrascan, you can explore various options available. The [usage page](./usage.md) covers the options in detail. For more information, see [Related resources](#related_resources).

# Related resources

* The [usage guide](./usage.md) 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.
* [Terrascan Policy Reference](../policies.md)
* The [usage guide](./usage.md) explains general usage and how to scan other types of IaC, such as Kubernetes, Helm, and Kustomize.
* The [CI/CD](../cicd.md) page explains how to integrate Terrascan on CI/CD pipelines.

0 comments on commit 53eda39

Please sign in to comment.