Skip to content

Commit

Permalink
Updated README.md and terraform-compliance-demo.gif
Browse files Browse the repository at this point in the history
  • Loading branch information
@eerkunt
eerkunt committed Jun 20, 2019
1 parent c1159c2 commit 4025b4b
Show file tree
Hide file tree
Showing 2 changed files with 87 additions and 108 deletions.
195 changes: 87 additions & 108 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
<h1 align="center">terraform-compliance</h1>

<div align="center">
<strong>BDD Testing for Terraform Files</strong>
<strong>BDD Testing for Terraform</strong>
</div>
<div align="center">
A lightweight BDD-testing Compliance Framework
A lightweight, security and compliance focused, BDD test framework
</div>

<br />
Expand Down Expand Up @@ -46,11 +46,22 @@


## Quick Overview
- __compliance:__ Test your infrastructure as code before you deploy. Enforce your people to follow the policies.
- __compliance:__ Ensure the implemented code is following security standards, your own custom standards
- __behaviour driven development:__ We have BDD for nearly everything, why not for IaC ?
- __portable:__ just install it from `pip` or run it via `docker`
- __why ?:__ why not ?

## Support

`terraform-compliance` had a huge revamp/redesign following `terraform`'s huge change coming with 0.12 version.
Due to these breaking changes `terraform-compliance` `1.0.0+` versions only supports terraform `0.12+` versions.

Older `terraform` versions is supported with 0.6.4 with limited functionality.

## Changelog

All changes coming with 1.0.0 and further versions can be found in [CHANGELOG](https://github.com/eerkunt/terraform-compliance/blob/master/CHANGELOG.md).

## Usage

Recommended way to use `terraform-compliance` is using it's [Docker](https://hub.docker.com/r/eerkunt/terraform-compliance/) image.
Expand All @@ -59,32 +70,77 @@ Just define it as a function in your shell ;
```commandline
[~] $ function terraform-compliance { docker run --rm -v $(pwd):/target -i -t eerkunt/terraform-compliance "$@"; }
```
and use it whereever you want that has docker installed.
and use it wherever you want that has docker installed.

```commandline
[~] $ terraform-compliance --help
usage: terraform-compliance [-h] [--features feature_directory]
[--tfdir terraform_directory]
BDD Test Framework for Hashicorp terraform
optional arguments:
-h, --help show this help message and exit
--features feature_directory, -f feature_directory
Directory consists of BDD features
--tfdir terraform_directory, -t terraform_directory
Directory consists of Terraform Files
--identity ssh_private_key, -i ssh_private_key
SSH Private key file used for GIT authentication
[~] $ terraform-compliance -h
terraform-compliance v1.0.0 initiated
usage: terraform-compliance [-h] --features feature directory --planfile
plan_file [--identity [ssh private key]]
[--version]
BDD Test Framework for Hashicorp terraform
optional arguments:
-h, --help show this help message and exit
--features feature directory, -f feature directory
Directory (or git repository with 'git:' prefix)
consists of BDD features
--planfile plan_file, -p plan_file
Plan output file generated by Terraform
--identity [ssh private key], -i [ssh private key]
SSH Private key that will be use on git
authentication.
--version, -v show program's version number and exit
```

`terraform-compliance` is also available via `PyPi` package, so you can also install and use it via ;
```commandline
[~] $ pip install terraform-compliance
```

## How to use

```diff
-THIS IS ONLY APPLICABLE FOR 1.0.0+ VERSIONS
```
`terraform-compliance` requires a valid `terraform` plan file that is generated by terraform.

In order to do that you should add `-out=plan.out` to your `terraform plan` executions like ;

```
terraform plan -out=plan.out
```

This will create a propriety plan file that `terraform` can read also on `apply` operations.

After having your `plan.out` ( or any filename that is suitable for you ) created, you can run your `terraform-compliance` tests via ;

```
terraform-compliance -f /path/to/bdd/files -p /path/to/plan.out
```

#### Another Use Case: "I don't want to plan but want to scan my state file, current environment"

Just run ;

```
terraform show -json > state.out
```

which will generate a similar file to `plan.out` (as `state.out` in this example) that can be read by `terraform-compliance`

```
terraform-compliance -f /path/to/bdd/files -p /path/to/state.out
```

## Features

### Terraform Interpolations and Modules
`terraform-compliance` v1.0.0+ has full support for all terraform interpolations and modules, unlike to older versions.
]
### Compliance Tests

The idea of `terraform-compliance` is to define compliance-as-code in BDD fashion where compliance against infrastructure-as-code
Expand All @@ -94,70 +150,12 @@ Ideally, the tools needs to be integrated with a CI/CD tool and runs on every bu
* Company wide compliance-as-code
* Project wide compliance-as-code

`terraform-compliance` does not require and infrastructure or credentials to run. It runs against HCL code, thus it is a
**PRE** compliance tool. In CI/CD pipeline it is recommended to be placed before you create the environment.
`terraform-compliance` does not require any target environment to run. It runs against `terraform` plan outputs or state files,
depending on your use case. Thus it is a stage that needs to run before any deployment (**PRE-COMPLIANCE**).

Here is a quick DEMO about how does it look like when it runs to a sample `plan.out`

The demo shown below is a bit outdated, since lots of things change and tools has been improved substantially since 0.0.1 :)
The demo will be updated soon ;
![Example Run](terraform-compliance-demo.gif)
```bash
[~] $ terraform-compliance -f example/example_01 -t example/tf_files
terraform-compliance v0.2.0 initiated
Features : /Users/sharky/Repository/terraform-compliance/example/example_01
Steps : /Users/sharky/Repository/venv2/lib/python2.7/site-packages/terraform_compliance/steps
TF Files : /Users/sharky/Repository/terraform-compliance/example/tf_files
Validating terraform files.
All HCL files look good.
Running tests.
Feature: Security Groups should be used to protect services/instances # /path/to/example/example_01/aws/security_groups.feature
In order to improve security
As engineers
We'll use AWS Security Groups as a Perimeter Defence
Scenario Outline: Policy Structure
Given I define AWS Security Group
Then it must contain <policy_name>
Examples:
| policy_name |
| ingress |
| egress |
Scenario Outline: Well-known insecure protocol exposure on Public Network for ingress traffic
Given I define AWS Security Group
Then it must contain ingress
with <proto> protocol and not port <portNumber> for 0.0.0.0/0
Examples:
| ProtocolName | proto | portNumber |
| HTTP | tcp | 80 |
| Telnet | tcp | 23 |
| SSH | tcp | 22 |
| MySQL | tcp | 3306 |
| MSSQL | tcp | 1443 |
| NetBIOS | tcp | 139 |
| RDP | tcp | 3389 |
Feature: Subnets should be defined properly for network security # /path/to/example/example_01/aws/subnets.feature
In order to improve security
And decrease impact radius
As engineers
We'll use a layered architecture in our AWS Environment

Scenario: Subnet Count
Given I define AWS Subnet
When I count them
Then I expect the result is more than 2
AssertionError: 0 is not more than 2

2 features (1 passed, 1 failed)
10 scenarios (9 passed, 1 failed)
28 steps (27 passed, 1 failed)

[~] $ echo $?
1
[~] $
```

### BDD Directives
Every BDD feature file will have ;
Expand Down Expand Up @@ -206,7 +204,7 @@ Steps are the functional tests that is actually executing necessary task to vali
| ---------------| --------------| ---------- |
| GIVEN | I have `{name}` `{type}` configured | `name`: name of the key in terraform (e.g. `aws_security_group`, `aws` ) <br>`type`: The type of the key (e.g. `resource`, `provider` etc.) |
| GIVEN | I have `{resource_name}` defined | `name`: name of the resource ( e.g. `aws_security_group` ) |
| WHEN | I `{math_formula}` them | `math_formula`: `sum` or `count` |
| WHEN | I `{math_formula}` them | `math_formula`: `count` |
| THEN | I expect the result is `{operator}` than `{number}` | `operator`: `more`, `more and equal`, `less`, `less and equal`<br>`number`: an integer |
| WHEN<br>THEN | it contain `{something}`<br>it contains `{something}`<br>it must contain `{something}` | `something`: any property within terraform resoruce/provider/etc. (e.g. `access_key`, `ingress` ) |
| THEN | encryption is enabled<br>encryption must be enabled | |
Expand Down Expand Up @@ -305,28 +303,11 @@ These sample tests include ;

The tests can be easily extended with the current capabilities. For any new capability please raise [a new Issue](https://github.com/eerkunt/terraform-compliance/issues/new) and it will be implemented as soon as possible.

### Using git repositories
### Using git repositories for features
`terraform-compliance` also supports remote fetching if any of the feature or terraform files exist in a remote git repo. Sample usage is like ;

```commandline
[~] $ terraform-compliance -f git:https://some.git.repository/compliance-code.git -t /path/to/terraform_files
terraform-compliance v0.1.1 initiated
Using remote git repository: https://some.git.repository/compliance-code.git
Steps : /Users/sharky/Repository/terraform-compliance/terraform_compliance/steps
Features : /var/folders/1k/7vm1m4p12db2tqbd5jcn004m0000gn/T/tmpsrlnAG (https://some.git.repository/compliance-code.git)
TF Files : /Users/sharky/Repository/terraform-compliance/example/tf_files
Validating terraform files.
All HCL files look good.
Running tests.
Feature: Resources should be encrypted encryption_at_rest.feature
```

This is also applicable for terraform files ( `-t` argument ), too.

in case remote git repository is a private repo and requires authentication, you can invoke `-i` parameter to point
your private ssh-key to authenticate against target repository.
```commandline
[~] $ terraform-compliance -f /path/to/features -t git:ssh://fqdn/path/go/repo.git -i /path/to/private.key
[~] $ terraform-compliance -f git:https://some.git.repository/compliance-code.git -p /path/to/plan.out
```

If you already configured your `~/.ssh/config` and pointing remote host, and private key file, you don't even need to
Expand All @@ -340,16 +321,14 @@ You can also push additional arguments that is specific for `radish`. Just to ex
For e.g.
```bash
[~] $ terraform-compliance -f /path/to/features -t /path/to/terraform_files -v
terraform-compliance v0.2.0 initiated
Features : /Users/sharky/Repository/terraform-compliance/example/example_01
Steps : /Users/sharky/Repository/venv2/lib/python2.7/site-packages/terraform_compliance/steps
TF Files : /Users/sharky/Repository/terraform-compliance/example/tf_files
Validating terraform files.
All HCL files look good.
terraform-compliance v1.0.0 initiated
...
...
...
Running tests.
0.8.6
0.13.0 <--- This is coming from radish directly.
```
Please note that `0.8.6` is the `radish` version comes from `-v` parameter.
Please note that `0.13.0` is the `radish` version comes from `-v` parameter.

## FAQ

Expand Down
Binary file modified terraform-compliance-demo.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 4025b4b

Please sign in to comment.