diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 2aad44f65..26f627e1e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -2,12 +2,12 @@ # This file designates required PR reviewers for this repository # https://help.github.com/articles/about-codeowners/ -* @accurics/terrascan-maintainers @bkizer-tenable +* @accurics/terrascan-maintainers @bkizer-tenable @tenable/terrascan-maintainers -*.rego @accurics/terrascan-policy-maintainers +*.rego @accurics/terrascan-policy-maintainers @tenable/terrascan-policy-maintainers -*.go @accurics/terrascan-maintainers +*.go @accurics/terrascan-maintainers @tenable/terrascan-maintainers -/pkg/ @accurics/terrascan-maintainers +/pkg/ @accurics/terrascan-maintainers @tenable/terrascan-maintainers -/pkg/policies/opa/rego/ @accurics/terrascan-policy-maintainers \ No newline at end of file +/pkg/policies/opa/rego/ @accurics/terrascan-policy-maintainers @tenable/terrascan-policy-maintainers diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f6714b8aa..9e0cfc095 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ You can contribute in many ways: ### Report Bugs -Report bugs at [https://github.com/accurics/terrascan/issues](https://github.com/accurics/terrascan/issues). +Report bugs at [https://github.com/tenable/terrascan/issues](https://github.com/tenable/terrascan/issues). If you are reporting a bug, please include: @@ -30,11 +30,11 @@ and "help wanted" is open to whoever wants to implement it. Terrascan could always use more documentation, whether as part of the official Terrascan docs, or even on the web in blog posts, -articles, videos, and such. +articles, videos, and such. Documentation for Terrascan is located in [tenable/runterrascan.io](https://github.com/tenable/runterrascan.io) and accessible through [runterrascan.io](www.runterrascan.io). Any PRs with changes in functionality or the CLIs user interface should include a corresponding PR for documentation updates. ### Submit Feedback -The best way to send feedback is to file an issue at [https://github.com/accurics/terrascan/issues](https://github.com/accurics/terrascan/issues). +The best way to send feedback is to file an issue at [https://github.com/tenable/terrascan/issues](https://github.com/tenable/terrascan/issues). If you are proposing a feature: diff --git a/README.md b/README.md index 775613046..73145e384 100644 --- a/README.md +++ b/README.md @@ -194,7 +194,7 @@ Terrascan's default output is a list of violations present in the scanned IaC. A Terrascan can be built locally. This is helpful if you want to be on the latest version or when developing Terrascan. ```sh -$ git clone git@github.com:accurics/terrascan.git +$ git clone git@github.com:tenable/terrascan.git $ cd terrascan $ make build $ ./bin/terrascan diff --git a/code_of_conduct.md b/code_of_conduct.md index 2c1c04060..571371699 100644 --- a/code_of_conduct.md +++ b/code_of_conduct.md @@ -61,7 +61,7 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at -terrascan@accurics.com. +terrascan@tenable.com. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the @@ -119,11 +119,11 @@ This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at [https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0]. -Community Impact Guidelines were inspired by +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC]. For answers to common questions about this code of conduct, see the FAQ at -[https://www.contributor-covenant.org/faq][FAQ]. Translations are available +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations]. [homepage]: https://www.contributor-covenant.org diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..3165e2868 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,3 @@ +# Terrascan documentation + +Documenation for terrascan lives at [runterrascan.io](www.runterrascan.io). Any updates or contributions to the documentation can be made in the [tenable/runterrascan.io](https://github.com/tenable/runterrascan.io) GitHub repository. diff --git a/docs/about.md b/docs/about.md index b99247460..c82439e2f 100644 --- a/docs/about.md +++ b/docs/about.md @@ -1,7 +1,7 @@ # About Terrascan -Terrascan is a static code analyzer for infrastructure as code. Originally developed in 2017, Terrascan has evolved from a Python application specifically focused on scanning of security issues for Terraform into a Golang application with pluggable support for multiple IaC tools and technologies. The project is maintained by [Accurics](https://www.accurics.com) +Terrascan is a security analyzer for infrastructure as code. Originally developed in 2017, Terrascan has evolved from a Python application specifically focused on scanning of security issues for Terraform into a Golang application with pluggable support for multiple IaC tools and technologies. The project is maintained by [Tenable](https://www.tenable.com) -## About Accurics +## About Tenable -[Accurics](https://www.accurics.com) enables organizations to protect their cloud native infrastructure in hybrid and multi-cloud environments. It seamlessly scans infrastructure as code for misconfigurations, monitors provisioned cloud infrastructure for configuration changes that introduce posture drift, and enables reverting to a secure posture. +[Tenable.cs](https://www.tenable.com/products/tenable-cs/evaluate) enables organizations to protect their cloud native infrastructure in hybrid and multi-cloud environments. It seamlessly scans infrastructure as code for misconfigurations, monitors provisioned cloud infrastructure for configuration changes that introduce posture drift, and enables reverting to a secure posture. diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index 8c8cd3f8e..000000000 --- a/docs/architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# 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. - -![Terrascan architecture](terrascan_architecture.png) - - diff --git a/docs/changelog.md b/docs/changelog.md deleted file mode 100644 index 786b75d5a..000000000 --- a/docs/changelog.md +++ /dev/null @@ -1 +0,0 @@ ---8<-- "CHANGELOG.md" diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index d2c426c11..000000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,162 +0,0 @@ -# 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](#installing-terrascan): -- [Scanning with 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](#native-executable) -2. [Using a Docker container](#using-a-docker-container) - -### Native executable -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 -$ 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: - -``` Bash -$ sudo install terrascan /usr/local/bin -``` - -or: - -``` Bash -$ alias terrascan="`pwd`/terrascan" -``` -#### Windows - -Download the latest version of builds for Windows and enter the following command: - -``` -tar -zxf terrascan__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): - -``` Bash -$ docker run --rm accurics/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. - -``` Bash -$ alias terrascan="docker run --rm -it -v "$(pwd):/iac" -w /iac accurics/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](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 -... -$ cd KaiMonkey/terraform/aws -$ terrascan scan -``` - -By default Terrascan will output its findings in human friendly format: - -``` sh -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](usage/usage.md) covers the options in detail. For more information, see [Related resources](#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](usage/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. -* The [CI/CD](integrations/overview.md) page explains how to integrate Terrascan on CI/CD pipelines. -* [Terrascan Policy Reference](../policies.md) - diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 329157864..000000000 --- a/docs/index.md +++ /dev/null @@ -1,12 +0,0 @@ -![Terrascan_Logo](img/Terrascan_By_Accurics_Logo_38B34A-333F48.svg) - -# Terrascan Documentation - -Terrascan documentation is composed of the following major sections: - -* [Getting Started](getting-started.md): Tutorial on how to install and run Terrascan for the first time. -* [Usage](usage/usage.md): Read in depth about the different configurations Terrascan supports. -* [Integrations](integrations/overview.md): A growing list of guides on integrating Terrascan with different tools in the software development lifecycle. -* [Architecture](architecture.md): Understand the pluggable architecture powering Terrascan. -* [Policies](policies.md): Read more about how to write custom policies, and review parts of the policy pack included in Terrascan by default. - diff --git a/docs/integrations/admission-controller-webhooks-usage.md b/docs/integrations/admission-controller-webhooks-usage.md deleted file mode 100644 index cc27f7399..000000000 --- a/docs/integrations/admission-controller-webhooks-usage.md +++ /dev/null @@ -1,127 +0,0 @@ -# Using Terrascan as a Kubernetes (K8s) Admission Controller - -This section provides steps to integrate Terrascan with Kubernetes. - -## Overview -Terrascan can be integrated with K8s [admissions webhooks](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/). -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. For more details and instructions, [click here to see our blog](https://www.accurics.com/blog/terrascan-blog/kubernetes-security-terrascan-validating-admission-controller/). - -> **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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#validatingwebhookconfiguration-v1-admissionregistration-k8s-io) resource in kubernetes cluster pointing to the Terrascan server. -6. 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.accurics.com) and create a valid certificate for this subdomain through your SSL certificate provider. You can use [Let's Encrypt](https://letsencrypt.org/) 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](https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs). - - 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](https://medium.com/@paraspatidar/add-ssl-tls-certificate-or-pem-file-to-kubernetes-pod-s-trusted-root-ca-store-7bed5cd683d). -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](./usage.md) -. 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``` - -``` Bash - [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: - - ``` Bash - sudo docker run -p 443:9443 -v :/data -u root -e K8S_WEBHOOK_API_KEY= accurics/terrascan server --cert-path /data/cert.pem --key-path /data/key.pem -c /data/config.toml - ``` -Where, - -- `` is a key used for authentication between your K8s environment and the Terrascan server. Generate your preferred key and use it here. -- `` 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: - -``` Bash - cat </v1/k8s/webhooks//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: - -``` Bash - kubectl run mynginx --image=nginx -``` - -Go to ```https:///k8s/webhooks//logs``` and verify your request is logged. diff --git a/docs/integrations/argocd-integration.md b/docs/integrations/argocd-integration.md deleted file mode 100644 index ef1e34ed1..000000000 --- a/docs/integrations/argocd-integration.md +++ /dev/null @@ -1,489 +0,0 @@ -# Integration of Terrascan with Argo CD - -Terrascan can be configured as an Argo CD job during the application sync process using ArgoCD’s resource hook. The PreSync resource hook is the best way to evaluate the kubernetes deployment configuration and report any violations. - -## 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 configuration, 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. - -```yaml -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: - 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 -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 - - - -```sh -#!/bin/sh - -function send_slack_notification { - 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_notification $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_hosts`as 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. - -```yaml -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: - 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** - -```yaml -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_hosts`as 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= -``` -**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 -# 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 - -```sh -#!/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. - -[comment]: <> (it says 'mostly', what is the pending thing for user to add/configure?) - -```yaml -apiVersion: batch/v1 -kind: Job -metadata: -generateName: terrascan-hook- -namespace: -annotations: - argocd.argoproj.io/hook: PreSync -spec: -ttlSecondsAfterFinished: 3600 -template: - spec: - securityContext: - seccompProfile: - type: RuntimeDefault - containers: - - name: terrascan-argocd - image: - resources: - requests: - cpu: "1" - memory: "256Mi" - limits: - cpu: "1" - memory: "256Mi" - env: - - name: SERVICE_NAME - value: - - name: REMOTE_URL - value: - - name: IAC_TYPE - value: # If not provided default value is 'k8s' - - name: IAC_VERSION - value: # If not provided default value is 'v1' - - name: CLOUD_PROVIDER - value: #If not provided default value is 'all' - - name: REMOTE_TYPE - value: #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. diff --git a/docs/integrations/atlantis-integration.md b/docs/integrations/atlantis-integration.md deleted file mode 100644 index 1207a3008..000000000 --- a/docs/integrations/atlantis-integration.md +++ /dev/null @@ -1,140 +0,0 @@ -# Integration with Atlantis Pull Request Automation - -[Atlantis](https://www.runatlantis.io/) is a pull request automation system designed to control Terraform execution from Github commits. - -You can integrate Terrascan into an Atlantis setup using one of the two ways: - -* Method 1: Atlantis [Workflow-based](https://www.runatlantis.io/docs/custom-workflows.html) 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](https://www.runatlantis.io/docs/). - -## 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](https://hub.docker.com/r/runatlantis/atlantis/) 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. - -```yaml -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](https://github.com/accurics/terrascan/tree/master/scripts). 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](https://www.runatlantis.io/docs/server-side-repo-config.html). The command for this depends on how you choose to [deploy Atlantis](https://www.runatlantis.io/docs/deployment.html#deployment-2). -If running the Atlantis binary directly, use the following command: - -```bash -$ 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. - -[comment]: <> (Instructions/link to configure would be useful here) - -**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 accurics/terrascan_atlantis -``` - -##### To build your own container image: -``` -docker build ./integrations/atlantis -t -``` - -### Run the container: - -```bash -docker run \ ---env-file=<.env-file> \ --p 4141:4141 \ --v /config_data/:/etc/terrascan/ \ -accurics/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](https://www.runatlantis.io/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](https://hub.docker.com/r/accurics/terrascan_atlantis/tags) of the container image rather than the latest tag. - -[comment]: <> (Moved the workflow yaml note to above where its mentioned) - -### Running a scan - -With everything configured, a local Terrascan scan will be triggered as part of the Atlantis plan workflow. diff --git a/docs/integrations/cicd.md b/docs/integrations/cicd.md deleted file mode 100644 index c00c9188d..000000000 --- a/docs/integrations/cicd.md +++ /dev/null @@ -1,218 +0,0 @@ -# Integrating Terrascan into CI/CD - -Terrascan can be integrated into CI/CD pipelines to enforce security best practices as codified in the OPA rego policies included as part of Terrascan or any custom policies. This section contains examples on how to configure Terrascan in popular CI/CD tooling. - -## GitHub Action - -The [Terrascan GitHub Action](https://github.com/marketplace/actions/terrascan-iac-scanner) can be used as part of GitHub workflows to scan your repository for IaC issues as part of code pushes or pull requests. - -![Image of Terrascan action](../img/terrascan-action.png) - -Using Terrascan's SARIF output, the action can include issues found during the scan within [GitHub's code scanning](https://docs.github.com/en/rest/reference/code-scanning) results for the repository. - - -![Image of code scanning results](../img/code-scanning.png) - - 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. - - -``` YAML - -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: accurics/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](https://github.com/accurics/terrascan-action/) repository. - -## GitLab CI - -[GitLab CI](https://docs.gitlab.com/ee/ci/README.html) can use [Docker images](https://docs.gitlab.com/ee/ci/docker/using_docker_images.html) as part of a pipeline. We can take advantage of this functionality and use Terrascan's docker image as part of your [pipeline](https://docs.gitlab.com/ee/ci/pipelines/) 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](http://ubusvr:8000/getting-started/usage/#terrascan-commands) according to your needs. Here's an example .gitlab-ci.yml file: - -``` YAML -stages: - - scan - -terrascan: - image: - name: accurics/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](https://argoproj.github.io/argo-cd/user-guide/resource_hooks). The PreSync resource hook is the best way to evaluate the kubernetes deployment configuration and report any violations. - - -![picture](../img/terrascan-argo-cd-pipeline.png) - -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. - - -``` YAML -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: "/:" - 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 -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. - -``` CONSOLE - 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**. - -![picture](../img/terrascan-argo-cd-resource-hook-logs.png) - -### 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. - -``` SH -#!/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. - -``` SH -# Dockerfile - FROM accurics/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. diff --git a/docs/integrations/overview.md b/docs/integrations/overview.md deleted file mode 100644 index 025241440..000000000 --- a/docs/integrations/overview.md +++ /dev/null @@ -1,20 +0,0 @@ -# Overview - -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](../usage/command_line_mode.md#configuring-the-output-format-for-a-scan) page for more details. - -### Integration Guides: - -1. [Kubernetes (K8s) Admissions webhooks](admission-controller-webhooks-usage.md) -2. [ArgoCD](argocd-integration.md) -3. [Atlantis](atlantis-integration.md) -4. [Github and GitLab](cicd.md) - -### Community Guides and Blogs: -* [Azure DevOps](https://lgulliver.github.io/terrascan-in-azure-devops/) Credit to [@lrgulliver](https://twitter.com/lrgulliver) (Liam Gulliver) -* [Static Code Analyses - Terrascan, Terraform and Azure DevOps](https://jamescook.dev/codeanalyses-terrascan-terraform-azuredevops). Credit to [James Cook](https://twitter.com/OfficialCookJ) - diff --git a/docs/integrations/pre-commit-integration.md b/docs/integrations/pre-commit-integration.md deleted file mode 100644 index 6455a511d..000000000 --- a/docs/integrations/pre-commit-integration.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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: -```yaml -repos: - - repo: https://github.com/accurics/terrascan - rev: - hooks: - - id: terraform-pre-commit - args: [ '-i '] #optional -``` -**Note:** -The optional args line allows you to specify the IaC provider. For example, -```yaml -repos: - - repo: https://github.com/accurics/terrascan - rev: - hooks: - - id: terraform-pre-commit - args: [ '-i k8s'] -``` -will cause -```bash -'terrascan scan -i k8s' -``` -to run and thus scan kubernetes yaml files. You may exclude the args like so: -```yaml -repos: - - repo: https://github.com/accurics/terrascan - rev: - hooks: - - id: terraform-pre-commit -``` -which causes the default -```bash -'terrascan scan' -``` -to be run, scanning all IaC provider types. - -___ - -Once you have everything installed, and add the appropriate config file to your repo, -```bash -'terrascan scan -i ' -``` -everytime you attempt to commit your staged changes. You can also call the hook directly on all files using pre-commit run --all-files - - - diff --git a/docs/javascripts/tables.js b/docs/javascripts/tables.js deleted file mode 100644 index c84ad7981..000000000 --- a/docs/javascripts/tables.js +++ /dev/null @@ -1,6 +0,0 @@ -app.location$.subscribe(function () { - var tables = document.querySelectorAll("article table") - tables.forEach(function (table) { - new Tablesort(table) - }) -}) diff --git a/docs/learning.md b/docs/learning.md deleted file mode 100644 index 24665c008..000000000 --- a/docs/learning.md +++ /dev/null @@ -1,6 +0,0 @@ -# Educational Resources - -## Using Terrascan as a git pre-commit - -Terrascan can be used on pre-commit hooks to prevent accidental introduction of security weaknesses into your repository. -This requires having [pre-commit](https://pre-commit.com/) installed. An example configuration is provided in the comments of [.pre-commit-config.yaml](https://github.com/accurics/terrascan/blob/master/.pre-commit-config.yaml).yaml. diff --git a/docs/overrides/header.html b/docs/overrides/header.html deleted file mode 100644 index e98859ef5..000000000 --- a/docs/overrides/header.html +++ /dev/null @@ -1,83 +0,0 @@ - - - - - -
- - - -
diff --git a/docs/overrides/integrations/analytics.html b/docs/overrides/integrations/analytics.html deleted file mode 100644 index d4d92743d..000000000 --- a/docs/overrides/integrations/analytics.html +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - diff --git a/docs/overrides/partials/footer.html b/docs/overrides/partials/footer.html deleted file mode 100644 index 505a0fa8d..000000000 --- a/docs/overrides/partials/footer.html +++ /dev/null @@ -1,92 +0,0 @@ - - -{% import "partials/language.html" as lang with context %} - - - diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css deleted file mode 100644 index e7c1df970..000000000 --- a/docs/stylesheets/extra.css +++ /dev/null @@ -1,8 +0,0 @@ -.md-footer-copyright__highlight{ - text-align: center; -} - -.md-footer-copyright__policies{ - text-align: center; - margin-top: 1.75em; -} diff --git a/docs/usage/command_line_mode.md b/docs/usage/command_line_mode.md deleted file mode 100644 index d9c0eddf5..000000000 --- a/docs/usage/command_line_mode.md +++ /dev/null @@ -1,346 +0,0 @@ -# Using Terrascan in command line mode - -This section contains the following information: - -* [Terrascan commands](#terrascan-commands) -* [Scanning](#scanning) with examples -* [Configuring the output format for a scan](#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 - -``` Bash -$ 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](https://github.com/accurics/terrascan) 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: - -``` Bash -$ 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: - -``` Bash -$ 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: - -``` Bash -$ 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: - -```Bash -$ 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: - -``` Bash -$ terrascan scan -t aws -r git -u git@github.com:accurics/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](https://www.terraform.io/docs/modules/sources.html). - -#### Scanning private Terraform module repositories -When scanning Terraform code, Terrascan 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](https://www.terraform.io/docs/cli/config/config-file.html). - -## 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. -``` Bash -$ 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_` 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](https://github.com/accurics/terrascan/tree/master/scripts/install_kustomize.sh) - -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 Docker Image Vulnerabilities - -Terrascan can display vulnerabilities for Docker images present in the IaC files being scanned by specifying the `--find-vuln` flag along with the scan command as follows: - -``` -$ terrascan scan -i --find-vuln -``` - -This command looks for all the Docker images present in the IaC files being scanned and retrieves any vulnerabilities as reported by it's container registry. Supported container registries include: 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html). - -#### 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](https://cloud.google.com/docs/authentication/getting-started). - -#### 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: - - ``` Bash - 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](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authorization#use-file-based-authentication). - -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: - -``` Bash -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. - -Terrascan requires `HARBOR_REGISTRY_DOMAIN` environment variable to identify domain of harobor registry. - -In case using terrascan for development or testing purpose then to skip tls verification set `HARBOR_SKIP_TLS` environment variable to `true`. - - -### 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. - -``` Bash -$ terrascan scan -t aws --config-only -aws_ecr_repository: -- id: aws_ecr_repository.scanOnPushDisabled - name: scanOnPushDisabled - source: ecr.tf - line: 1 - type: aws_ecr_repository - config: - image_scanning_configuration: - - scan_on_push: - value: {} - image_tag_mutability: MUTABLE - name: test -- id: aws_ecr_repository.scanOnPushNoSet - name: scanOnPushNoSet - source: ecr.tf - line: 10 - type: aws_ecr_repository - config: - image_tag_mutability: MUTABLE - name: test -``` -## More details on scan command - -### List of options for scan command: - -| Flag | Description | Options (default highlighted ) -| ----------- | ----------- |------------| -| -h | Help for scan command | See list of all flags supported with descriptions, default options in all commands are highlighted in bold| -| -d | Use this to scan a specific directory. Use "." for current directory | AWS, GCP, Azure, and GitHub| -| -f | Use this command to scan a specific file | | -| -i type | Use this to change the IaC provider | arm, cft, docker, helm, k8s, kustomize, **terraform**| -| --iac-version version | Use this in conjunction with `- i type` to specify the version of IaC provider | Supported versions of each IaC are: `arm: v1, cft: v1, docker: v1, helm: v3, k8s: v1, kustomize: v2, v3, v4, terraform: v12, v13, v14, v15`| -| -p | Use this to specify directory path for policies | By default policies are installed here: | -| -t | Use this to specify individual cloud providers | **all**, aws, azure, gcp, github, k8s| -| -r | Use this to specify directory path for remote backend | git, s3, gcs, http | -| -u | Use this to specify directory URL for remote IaC repositories | see options below | -| |scan-rules|Specify rules to scan, example: --scan-rules="ruleID1,ruleID2"| -| |skip-rules|Specify one or more rules to skip while scanning. Example: --skip-rules="ruleID1,ruleID2"| -| |use-colors |Configure the color for output (**auto**, t, f) | -|--non-recursive |Use this for non recursive directories and modules scan | By default directory is scanned recursively, if this flag is used then only provided root directory will be scanned| -|--webhook-token string| Token used for sending authenticated requests to the notification webhook | This flag is optional when using the notification webhook| -|--webhook-url | A webhook URL where Terrascan will send JSON scan report and normalized IaC JSON | This overrides any notification webhook URLs configured in config TOML file specified with the `-c` flag| -|--use-terraform-cache |Use this to refer terraform remote modules from terraform init cache rather than downloading | By default remote module will be downloaded in temporary directory. If this flag is set then modules will be referred from terraform init cache if module is not present in terraform init cache it will be downloaded. Directory will be scanned non recursively if this flag is used.(applicable only with terraform IaC provider)| -| --find-vuln | find vulnerabilities | Use this to fetch vulnerabilities identified on the registry for docker images present in IaC the files scanned | -| --repo-url | repository url | This flag can be used to include the repository URL as part of scan results and notifications | -| --repo-ref | repository branch name | This flag can be used to include the repository branch name as part of scan results and notifications | -| -v | verbose | Displays violations with all details | - -| Global flags | Description | Options | -| ----------- | ----------- |------------| -| -c | Use this to specify config file settings | Format supported is `*.TOML` | -| -l | Use this to specify what log settings | debug, **info**, warn, error, panic, fatal | -| --log-output-dir | Use this to specify the directory path for writing scan logs and output files along with console output. In case the directory could not be resolved, the scan logs and results will be printed on console only. | -| -x | Use this to specify the log file format | **console**, json | -| -o | Use this to specify the scan output type | **human**, json, yaml, xml, junit-xml, sarif, github-sarif | -| --temp-dir | Use this to specify temporary directory path to download remote repository,module and templates | - - - -### Full help for scan command: - - -``` 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: - --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 -``` diff --git a/docs/usage/config_options.md b/docs/usage/config_options.md deleted file mode 100644 index b0e26f63a..000000000 --- a/docs/usage/config_options.md +++ /dev/null @@ -1,57 +0,0 @@ -# Configuration Terrascan - -You can provide a configuration file in [TOML format](https://toml.io/en/) to configure the Terrascan. - - -## Command to specify config File - -Use the `-c` or `--config-path` flag provide a TOML configuration file for Terrascan. - -``` Bash -$ terrascan scan -c -``` - - Here's an example config file: - -``` TOML -[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 - -``` - -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 `--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` - - -## 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`. diff --git a/docs/usage/in-file_instrumentation.md b/docs/usage/in-file_instrumentation.md deleted file mode 100644 index 9c7a321fd..000000000 --- a/docs/usage/in-file_instrumentation.md +++ /dev/null @@ -1,121 +0,0 @@ -# In-file Instrumentation - -Terrascan can be instrumented using special commands inside your IaC files (Terraform, K8s and dockerfile) - -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 -``` HCL -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 -``` YAML -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 -``` dockerfile -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 -``` HCL -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 -``` YAML -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 -``` dockerfile -#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"] -``` diff --git a/docs/usage/server_mode.md b/docs/usage/server_mode.md deleted file mode 100644 index d3c4ee522..000000000 --- a/docs/usage/server_mode.md +++ /dev/null @@ -1,119 +0,0 @@ -# Using Terrascan in Server mode - -[Server mode](#run-terrascan-in-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](command_line_mode.md#list-of-options-for-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: - -``` Bash -$ terrascan server -``` -Use this command to launch Terrascan server mode using Docker: - -``` Bash -$ docker run --rm --name terrascan -p 9010:9010 accurics/terrascan -``` - -### 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/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 - } - } -} -``` diff --git a/docs/usage/usage.md b/docs/usage/usage.md deleted file mode 100644 index 8617677ff..000000000 --- a/docs/usage/usage.md +++ /dev/null @@ -1,35 +0,0 @@ -# Usage Overview - -## Installing Terrascan - -For steps to install locally, or run Terrascan from docker, see [this section](../getting-started.md#installing-terrascan). - -## 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. - -``` Bash -$ git clone git@github.com:accurics/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](command_line_mode.md) provides list of Terrascan commands with descriptions. -2. [Server mode](server_mode.md) using Terrascan as API server - -See [Configuring Terrascan](config_options.md) to learn more about Terrascan's configuration file. - -See [In-File Instrumentation](in-file_instrumentation.md) 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](../integrations/admission-controller-webhooks-usage.md) -2. [ArgoCD](../integrations/argocd-integration.md) -3. [Atlantis](../integrations/atlantis-integration.md) -4. [Github and GitLab or CI/CD pipelines](../integrations/cicd.md) \ No newline at end of file diff --git a/release_checklist.md b/release_checklist.md index 859f6814f..becc06d31 100644 --- a/release_checklist.md +++ b/release_checklist.md @@ -17,7 +17,7 @@ Running the following command will generate new entries in `CHANGELOG.md` since Before running this command, you'll need to have a GitHub [personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) set in the `GITHUB_TOKEN` OS environment variable. ``` -docker run -it --rm -v "$(pwd)":/usr/local/src/your-app ferrarimarco/github-changelog-generator -u accurics -p terrascan -t $GITHUB_TOKEN -b CHANGELOG.md --since-tag v1.4.0 --future-release v1.5.0 +docker run -it --rm -v "$(pwd)":/usr/local/src/your-app ferrarimarco/github-changelog-generator -u tenable -p terrascan -t $GITHUB_TOKEN -b CHANGELOG.md --since-tag v1.4.0 --future-release v1.5.0 ``` Next, Review `CHANGELOG.md` to ensure there are notes for the new release @@ -43,7 +43,7 @@ Run the commands below to update Brew to the latest Terrascan version. If you ar ``` $ export TERRASCAN_VERSION= -$ brew bump-formula-pr --no-browse --url https://github.com/accurics/terrascan/archive/${TERRASCAN_VERSION}.tar.gz --sha256 $(curl -sL https://github.com/accurics/terrascan/archive/${TERRASCAN_VERSION}.tar.gz | sha256sum | awk '{print $1}') +$ brew bump-formula-pr --no-browse --url https://github.com/tenable/terrascan/archive/${TERRASCAN_VERSION}.tar.gz --sha256 $(curl -sL https://github.com/tenable/terrascan/archive/${TERRASCAN_VERSION}.tar.gz | sha256sum | awk '{print $1}') ``` ### Update helm chart and kustomize directory