Merge pull request #273 from accurics/terrascan-v1.0-docs

Terrascan v1.0 docs
tenable · Aug 14, 2020 · 7b214c1 · 7b214c1
2 parents b6496eb + e822fad
commit 7b214c1
Show file tree

Hide file tree

Showing 14 changed files with 192 additions and 35 deletions.
diff --git a/README.md b/README.md
@@ -19,7 +19,7 @@ Detect compliance and security violations across Infrastructure as Code to mitig
 * Support for AWS, Azure, and GCP
 
 ## Installing
-Terrascan's binary for your architecture can be found on the releases page. Here's an example of how to install it:
+Terrascan's binary for your architecture can be found on the [releases](/~https://github.com/accurics/terrascan/releases) page. Here's an example of how to install it:
 
 ```
 $ curl --location /~https://github.com/accurics/terrascan/releases/download/v1.0.0/terrascan_darwin_amd64.zip --output terrascan_darwin_amd64.zip
@@ -37,21 +37,16 @@ Terrascan can be installed using Homebrew on macOS:
 brew install terrascan
 ```
 
-### Chocolatey
-Terrascan can be installed on Windows using Chocolatey:
-
-```
-choco install terrascan
-```
-
 ### Docker
 Terrascan is also available as a Docker image and can be used as follows
 
-	$ docker run accurics/terrascan
+```
+$ docker run accurics/terrascan
+```
 
 ## Getting started
 
-To scan your code for security weaknesses you can run the following
+To scan your code for security issues you can run the following
 
 ```
 $ terrascan --iac terraform --iac-version v12 --cloud aws -d pkg/iac-providers/terraform/v12/testdata/moduleconfigs
@@ -60,24 +55,38 @@ $ terrascan --iac terraform --iac-version v12 --cloud aws -d pkg/iac-providers/t
 The following flags are available:
 
 ```
-$ terrascan --help
-Usage of ./bin/terrascan:
-  -cloud string
-        cloud provider (supported values: aws)
-  -d string
-        IaC directory path
-  -f string
-        IaC file path
-  -iac string
-        IaC provider (supported values: terraform)
-  -iac-version string
-        IaC version (supported values: 'v12' for terraform) (default "default")
-  -log-level string
-        logging level (debug, info, warn, error, panic, fatal) (default "info")
-  -log-type string
-        log type (json, console) (default "console")
-  -server
-        run terrascan in server mode
+$ terrascan -h
+
+Terrascan
+
+Scan IaC files for security violations
+
+Usage
+
+    terrascan -cloud [aws|azure|gcp] [options...]
+
+Options
+
+Cloud
+    -cloud                Required. Cloud provider (supported values: aws, azure, gcp)
+
+IaC (Infrastructure as Code)
+    -d                    IaC directory path (default: current working directory)
+    -f                    IaC file path
+    -iac                  IaC provider (supported values: terraform, default: terraform)
+    -iac-version          IaC version (supported values: 'v12' for Terraform, default: v12)
+    -p                    Policy directory path
+
+Mode
+    -server               Run Terrascan in server mode
+
+Logging
+    -log-level            Logging level (supported values: debug, info, warn, error, panic, fatal)
+    -log-type             Logging type (supported values: json, yaml, console, default: console)
+
+Miscellaneous
+    -config               Configuration file path
+    -version              Print the Terrascan version
 ```
 
 ## Documentation

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1 +1 @@
-{!CHANGELOG.md!}
+--8<-- "CHANGELOG.md"
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1 +1 @@
-{!CONTRIBUTING.md!}
+--8<-- "CONTRIBUTING.md"
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,7 +1,99 @@
 # Getting Started
+Terrascan is a static code analyzer for Infrastructure as Code tooling. It can executed with the native binary/executable or by using the [`docker`](#using-docker) container.
 
 ## Installation
+Terrascan's binary can be found on the package for each [release](/~https://github.com/accurics/terrascan/releases). Here's an example of how to install it:
+
+``` Bash linenums="1"
+$ curl --location /~https://github.com/accurics/terrascan/releases/download/v1.0.0/terrascan_darwin_amd64.zip --output terrascan_darwin_amd64.zip
+$ unzip terrascan_darwin_amd64.zip
+Archive:  terrascan_darwin_amd64.zip
+  inflating: terrascan
+$ install terrascan /usr/local/bin
+$ terrascan --help
+```
+
+### Installing on macOS
+For Mac users, Terrascan can be installed using Homebrew:
+
+``` Bash linenums="1"
+brew install terrascan
+```
+
+### Using Docker
+Terrascan is also available as a Docker image and can used as follows:
+
+``` Bash linenums="1"
+$ docker run accurics/terrascan
+```
+
+### Building Terrascan
+Terrascan can be built locally. This is helpful if you want to be on the latest version or when developing Terrascan.
+
+``` Bash linenums="1"
+$ git clone git@github.com:accurics/terrascan.git
+$ cd terrascan
+$ make build
+$ ./bin/terrascan
+```
 
 ## Scanning
 
-## Terrascan CLI
+By typing `terrascan` without flags or other arguments, you can display the usage information.
+
+``` Bash linenums="1"
+$ terrascan -h
+
+Terrascan
+
+Scan IaC files for security violations
+
+Usage
+
+    terrascan -cloud [aws|azure|gcp] [options...]
+
+Options
+
+Cloud
+    -cloud                Required. Cloud provider (supported values: aws, azure, gcp)
+
+IaC (Infrastructure as Code)
+    -d                    IaC directory path (default: current working directory)
+    -f                    IaC file path
+    -iac                  IaC provider (supported values: terraform, default: terraform)
+    -iac-version          IaC version (supported values: 'v12' for Terraform, default: v12)
+    -p                    Policy directory path
+
+Mode
+    -server               Run Terrascan in server mode
+
+Logging
+    -log-level            Logging level (supported values: debug, info, warn, error, panic, fatal)
+    -log-type             Logging type (supported values: json, yaml, console, default: console)
+
+Miscellaneous
+    -config               Configuration file path
+    -version              Print the Terrascan version
+```
+
+
+``` Bash linenums="1"
+$ terrascan -cloud aws -iac terraform -iac-version v12 -p $REGO_POLICIES -d . --output json
+```
+
+### Example scanning Terraform (HCL2)
+
+Here's an example of scanning Terraform HCL2 files containing AWS resources:
+
+``` Bash linenums="1"
+terrascan -cloud aws -d ~/iac_folder
+```
+In the example above, the `-cloud` flag is used to specify AWS as the cloud provider and the `-d` flag is used to specify the directory to scan.
+
+### Launch Terrascan in server mode
+
+To launch Terrascan in server mode you can execute the following:
+
+``` Bash linenums="1"
+terrascan -server
+```
diff --git a/docs/img/favicon.ico b/docs/img/favicon.ico
diff --git a/docs/img/terrascan-icon-white.png b/docs/img/terrascan-icon-white.png
diff --git a/docs/img/terrascan_favicon_16px.ico b/docs/img/terrascan_favicon_16px.ico
diff --git a/docs/img/terrascan_favicon_32px-16px.ico b/docs/img/terrascan_favicon_32px-16px.ico
diff --git a/docs/img/terrascan_favicon_32px.ico b/docs/img/terrascan_favicon_32px.ico
diff --git a/docs/overrides/partials/footer.html b/docs/overrides/partials/footer.html
@@ -80,6 +80,11 @@
                 <div class="md-footer-copyright__highlight">
                     {{ config.copyright }}
                 </div>
+                <div class="md-footer-copyright__policies">
+                    <a style="color: #2bbed6;" href="https://www.accurics.com/terms/">Terms of Use</a>
+                    |
+                    <a style="color: #2bbed6;" href="https://www.accurics.com/privacy/">Privacy Policy</a>
+                </div>
                 {% endif %}
             </div>
         </div>

diff --git a/docs/policies.md b/docs/policies.md
@@ -1,3 +1,40 @@
 # Policies
 
+Terrascan policies are written using the [Rego policy language](https://www.openpolicyagent.org/docs/latest/policy-language/). With each rego policy a JSON "rule" file is included which defines metadata for the policy. Policies included within Terrascan are stored in the [pkg/policies/opa/rego](/~https://github.com/accurics/terrascan/tree/master/pkg/policies/opa/rego) directory.
+
+## Rule JSON file
+
+The rule files follow this naming convention: `<cloud-provider>.<resource-type>.<rule-category>.<next-available-rule-number>.json`
+
+Here's an example of the contents of a rule file:
+
+``` json linenums="1"
+{
+    "ruleName": "unrestrictedIngressAccess",
+    "rule": "unrestrictedIngressAccess.rego",
+    "ruleTemplate": "unrestrictedIngressAccess",
+    "ruleArgument": {
+      "prefix": ""
+    },
+    "severity": "HIGH",
+    "description": "Ensure no security groups allow ingress from 0.0.0.0/0 to ALL ports and protocols",
+    "ruleReferenceId": "AWS.SecurityGroup.NetworkPortsSecurity.High.0094",
+    "category": "Network Ports Security",
+    "version" : "1"
+}
+```
+
+| Key                 | Value                                         |
+| ------------------- | --------------------------------------------- |
+| ruleName            | Short name for the rule                       |
+| rule                | File name of the rego policy                  |
+| ruleTemplate        | Rego policy template Used for the rule        |
+| ruleArgument        | Argument passed to the template               |
+| ruleArgument.prefix | Used for making rego policies unique          |
+| severity            | Likelihood x impact of issue                  |
+| description         | Description of the issue found with this rule |
+| ruleReferenceId     | Unique ID of the rule in the format `<cloud-provider>.<resource-type>.<rule-category>.<next-available-rule-number>` |
+| category            | Descriptive category for this rule    |
+| version             | Version number for the rule/rego      |
+
 ## AWS
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,2 @@
 mkdocs==1.1.2
 mkdocs-material==5.5.3
-markdown-include==0.5.1
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -0,0 +1,8 @@
+.md-footer-copyright__highlight{
+  text-align: center;
+}
+
+.md-footer-copyright__policies{
+  text-align: center;
+  margin-top: 1.75em;
+}
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -12,13 +12,17 @@ repo_url: /~https://github.com/accurics/terrascan/
 # Configuration
 theme:
   name: material
-  favicon: img/Terrascan_STACK_Logo_F2F2F2.svg
-  logo: img/Terrascan_STACK_Logo_F2F2F2.svg
+  favicon: img/favicon.ico
+  logo: img/terrascan-icon-white.png
   custom_dir: docs/overrides
   palette:
     primary: green
   language: en
 
+# Custom CSS
+extra_css:
+  - stylesheets/extra.css
+
 # Social Icons
 extra:
   social:
@@ -44,6 +48,9 @@ nav:
   - About: about.md
 
 markdown_extensions:
-  - markdown_include.include
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
+  - pymdownx.snippets
   - toc:
       permalink: true