Docs: v2.2.0 (#275)

* Docs: Add Scalr integration

* Docs: How to build from source

* Docs: Add ARM support

* Docs: Update list of ARM rules

README.md

@@ -7,6 +7,7 @@
   - [Homebrew](#homebrew-macos--linux)
   - [Prebuilt binary (all platforms)](#prebuilt-binary-all-platforms)
   - [Docker (all platforms)](#docker-all-platforms)
+  - [From source](#from-source)
 - [Usage](#usage)
 - [For more information](#for-more-information)
 
@@ -20,8 +21,9 @@ Regula supports the following file types:
 - Terraform HCL code
 - Terraform JSON plans
 - Kubernetes YAML manifests
+- Azure Resource Manager (ARM) JSON templates _(in preview)_
 
-Regula includes a library of rules written in Rego, the policy language used by the [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) project. Regula works with your favorite CI/CD tools such as Jenkins, Circle CI, and AWS CodePipeline; we’ve included a [GitHub Actions example](https://github.com/fugue/regula-action) so you can get started quickly. Where relevant, we’ve mapped Regula policies to the CIS AWS, Azure, and Google Cloud Foundations Benchmarks so you can assess compliance posture. Regula is maintained by engineers at [Fugue](https://fugue.co).
+Regula includes a library of rules written in Rego, the policy language used by the [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) project. Regula works with your favorite CI/CD tools such as Jenkins, Circle CI, and AWS CodePipeline; we’ve included a [GitHub Actions example](https://github.com/fugue/regula-action) so you can get started quickly. Where relevant, we’ve mapped Regula policies to the CIS AWS, Azure, Google Cloud, and Kubernetes Foundations Benchmarks so you can assess compliance posture. Regula is maintained by engineers at [Fugue](https://fugue.co).
 
 Regula is also available as a Docker image on DockerHub [here](https://hub.docker.com/r/fugue/regula).
 
@@ -89,6 +91,26 @@ Regula is available as a Docker image on DockerHub [here](https://hub.docker.com
 
 For usage, see [Running Regula with Docker](https://regula.dev/usage.html#running-regula-with-docker).
 
+### From source
+
+_macOS, Linux, and [WSL](https://docs.microsoft.com/en-us/windows/wsl/install) only_
+
+1. [Install Go (v1.16+)](https://go.dev/doc/install)
+
+2. Build binary and move to `/usr/local/bin/regula`:
+
+    ```bash
+    make # this builds ./bin/regula
+    make install # this builds ./bin/regula and installs it to /usr/local/bin/regula
+    ```
+
+Once you've built the binary, execute the following to run tests:
+
+```
+git submodule update --init --recursive
+make test
+```
+
 ## Usage
 
 **For a tutorial on using Regula with example IaC, see [Getting Started](https://regula.dev/getting-started.html#tutorial-run-regula-locally-on-terraform-iac).**

docs/src/about.md

@@ -10,7 +10,7 @@ Regula is the policy engine that powers [Fugue](https://www.fugue.co), a SaaS pl
 
 Regula has the following advantages:
 
-- Support for the IaC tools and templates that you use: AWS CloudFormation YAML and JSON templates, including SAM templates and those generated by the AWS Cloud SDK; Terraform HCL files and plan files, including support for modules; Kubernetes YAML manifests
+- Support for the IaC tools and templates that you use: AWS CloudFormation YAML and JSON templates, including SAM templates and those generated by the AWS Cloud SDK; Terraform HCL files and plan files, including support for modules; Kubernetes YAML manifests; Azure Resource Manager (ARM) templates (_preview_)
 - Easy installation and deployment with Homebrew, Docker, and pre-built binaries for all platforms
 - Out-of-the-box libraries of rules that inspect AWS, Azure, Google Cloud, and Kubernetes resources for potential misconfigurations and compliance issues, including CIS Foundations Benchmarks checks
 - Configurable settings, including waivers for designating exceptions on resources or even an entire IaC file, and enabling/disabling rules based on your team’s needs

docs/src/development/testing-rules.md

@@ -2,7 +2,7 @@
 
 You can run rule tests using [`regula test`](../usage.md#test) or evaluate them interactively using [`regula repl`](../usage.md#repl). For each rule to be tested, you'll need three files:
 
-- The test Terraform or CloudFormation IaC file (aka test input)
+- The test IaC file (aka test input)
 - The Rego rule file
 - The Rego tests file, where each test is prepended with `test_`
 

docs/src/development/writing-rules.md

@@ -179,6 +179,7 @@ Regula supports the following metadata properties:
 - `description`: Longer description of the rule
 - `controls`: An object where the key is the compliance family name and the value is an array of controls
 - `severity`: One of `Critical`, `High`, `Medium`, `Low`, `Informational`
+- `rule_remediation_doc`: A URL with instructions for remediating the rule
 
 Here's an example rule result to show how this metadata looks in the report:
 
@@ -197,6 +198,7 @@ Here's an example rule result to show how this metadata looks in the report:
       "rule_message": "",
       "rule_name": "long_description",
       "rule_raw_result": false,
+      "rule_remediation_doc": "https://example.com",
       "rule_result": "FAIL",
       "rule_severity": "Low",
       "rule_summary": "IAM policies must have a description of at least 25 characters",
@@ -210,7 +212,7 @@ Here's an example rule result to show how this metadata looks in the report:
     }
 ```
 
-## CloudFormation vs. Terraform vs. Kubernetes rules
+## CloudFormation vs. Terraform vs. Kubernetes vs. ARM rules
 
 CloudFormation rules are written the same way Terraform rules are, but require the line `input_type := "cfn"`, as shown in the simple rule below:
 
@@ -250,10 +252,33 @@ deny {
 }
 ```
 
+ARM rules (_in preview_) require the line `input_type := "arm"`, as shown in the simple rule below:
+
+```ruby hl_lines="9"
+package rules.arm_postgresql_tags
+
+__rego__metadoc__ := {
+	"id": "ARM_POSTGRESQL_001",
+	"custom": {"severity": "Low"},
+	"title": "Azure PostgreSQL servers should be tagged 'application:db'",
+}
+
+input_type := "arm"
+
+resource_type = "Microsoft.DBforPostgreSQL/servers"
+
+default allow = false
+
+allow {
+    input.tags.application == "db"
+}
+```
+
 Terraform rules do not require `input_type` to be explicitly set.
 
 Additionally, the `resource_type` is specified differently depending on the input type:
 
 - [CloudFormation resource types](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html) (e.g., `AWS::EC2::Instance`)
 - Terraform [AWS](https://registry.terraform.io/providers/hashicorp/aws/latest/docs), [Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs), [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs) resource types (e.g., `aws_instance`)
-- [Kubernetes resource types](https://kubernetes.io/docs/reference/kubectl/overview/#resource-types) (see the `KIND` column) (e.g., `Job`)
+- [Kubernetes resource types](https://kubernetes.io/docs/reference/kubectl/overview/#resource-types) (see the `KIND` column) (e.g., `Job`)
+- [ARM templates](https://docs.microsoft.com/en-us/azure/templates/) (_in preview_) (e.g., `Microsoft.Network/virtualNetworks`)

docs/src/getting-started.md

@@ -79,6 +79,27 @@ Regula is available as a Docker image on DockerHub [here](https://hub.docker.com
 
 For usage, see [Running Regula with Docker](usage.md#running-regula-with-docker).
 
+### From source
+
+!!! note
+    macOS, Linux, and [WSL](https://docs.microsoft.com/en-us/windows/wsl/install) only
+
+1. [Install Go (v1.16+)](https://go.dev/doc/install)
+
+2. Build binary and move to `/usr/local/bin/regula`:
+
+    ```bash
+    make # this builds ./bin/regula
+    make install # this builds ./bin/regula and installs it to /usr/local/bin/regula
+    ```
+
+Once you've built the binary, execute the following to run tests:
+
+```
+git submodule update --init --recursive
+make test
+```
+
 ## Tutorial: Run Regula locally on Terraform IaC
 
 !!! tip

docs/src/index.md

@@ -10,8 +10,9 @@ Regula supports the following file types:
 - Terraform HCL code
 - Terraform JSON plans
 - Kubernetes YAML manifests
+- Azure Resource Manager (ARM) JSON templates _(in preview)_
 
-Regula includes a library of rules written in Rego, the policy language used by the [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) project. Regula works with your favorite CI/CD tools such as Jenkins, Circle CI, and AWS CodePipeline; we’ve included a [GitHub Actions example](https://github.com/fugue/regula-action) so you can get started quickly. Where relevant, we’ve mapped Regula policies to the CIS AWS, Azure, and Google Cloud Foundations Benchmarks so you can assess compliance posture. Regula is maintained by engineers at [Fugue](https://fugue.co).
+Regula includes a library of rules written in Rego, the policy language used by the [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) project. Regula works with your favorite CI/CD tools such as Jenkins, Circle CI, and AWS CodePipeline; we’ve included a [GitHub Actions example](https://github.com/fugue/regula-action) so you can get started quickly. Where relevant, we’ve mapped Regula policies to the CIS AWS, Azure, Google Cloud, and Kubernetes Foundations Benchmarks so you can assess compliance posture. Regula is maintained by engineers at [Fugue](https://fugue.co).
 
 Regula is also available as a Docker image on DockerHub [here](https://hub.docker.com/r/fugue/regula).
 

docs/src/integrations/scalr.md

@@ -0,0 +1,3 @@
+# Regula + Scalr
+
+We've provided an example for integrating Regula and [Scalr](https://www.scalr.com/) in a CI/CD pipeline. See the [fugue-scalr-integration](https://github.com/fugue/fugue-scalr-integration) repository for the integration, and see the [README](https://github.com/fugue/fugue-scalr-integration/blob/main/README.md) for a walkthrough.

docs/src/report.md

@@ -130,17 +130,17 @@ The `summary` block contains a breakdown of the `filepaths` (CloudFormation temp
 Each rule result in the JSON report lists the following attributes:
 
 - `controls`: Compliance controls mapped to the rule
-- `filepath`: Filepath of the evaluated Terraform HCL file, Terraform JSON plan, or CloudFormation template
-- `input_type`: `tf` (Terraform HCL), `tf_plan` (Terraform JSON plan), `cfn` (CloudFormation), `k8s` (Kubernetes)
-- `provider`: `aws`, `azurerm`, `google`, `kubernetes`
+- `filepath`: Filepath of the evaluated Terraform HCL file, Terraform JSON plan, CloudFormation template, Kubernetes manifest, or ARM template (_in preview_)
+- `input_type`: `tf` (Terraform HCL), `tf_plan` (Terraform JSON plan), `cfn` (CloudFormation), `k8s` (Kubernetes), `arm` (Azure Resource Manager JSON; _in preview_)
+- `provider`: `aws`, `azurerm`, `google`, `kubernetes`, `arm`
 - `resource_id`: ID of the evaluated resource
 - `resource_type`: Type of the evaluated resource
 - `rule_description`: A detailed description of the rule
 - `rule_id`: ID of the rule; built-in rules start with `FG_R`
 - `rule_message`: Optional error message associated with the rule; see how to create custom error messages in [simple](development/writing-rules.md#custom-error-messages-and-attributes-simple-rules) and [advanced](development/writing-rules.md#custom-error-messages-advanced-rules) custom rules
 - `rule_name`: Name of the rule (filepath minus extension)
 - `rule_raw_result`: `true` if the rule result was `PASS` before any waivers were applied, `false` if it was `FAIL`
-- `rule_remediation_doc`: A URL with instructions for remediating the rule (built-in rules only)
+- `rule_remediation_doc`: A URL with instructions for remediating the rule
 - `rule_result`: `PASS`, `FAIL`, or `WAIVED`
 - `rule_severity`: `Critical`, `High`, `Medium`, `Low`, `Informational`, or `Unknown`
 - `rule_summary`: A short summary of the rule