From 9f70c7215a6bf4f315815e771ea167b35797bd4c Mon Sep 17 00:00:00 2001 From: lhitchon Date: Sat, 10 Mar 2018 16:59:46 -0800 Subject: [PATCH] more examples for README --- README.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 162 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3931a72..561fa91 100644 --- a/README.md +++ b/README.md @@ -25,18 +25,28 @@ The program currently supports Terraform and Kubernetes files. ``` -# Rules +# Rules File -The rules file includes a list of objects with the following attributes: +The rules file specifies what files to process, and what validations to perform. + +## Attributes for the Rule Set + +* Version: current ignored +* Description: text description for the file, not currently used +* Type: should be 'Terraform' or 'Kubernetes' +* Files: filenames must match one of these patterns to be processed by this set of rules +* Rules: a list of rules, see next section + +## Attributes for each Rule * id: unique identifier for the rule * message: string to be printed when a validation error is detected * resource: the resource type to which the rule will be applied * severity: whether the validation generates a WARNING or a FAILURE -* filters: a list of filters used to detect validation errors +* filters: a list of filters used to detect validation errors, see next section * tags: optional list of tags, command line has option to limit scans to a subset of tags -# Filters +## Attributes for each Filter Each filter contains the following attributes: @@ -45,7 +55,9 @@ Each filter contains the following attributes: * op: the operation to be performed on the data returned by searching for the JMES path * value: needed for most operations -For example, to test that an AWS instance type has one of two values: +## Examples + +To test that an AWS instance type has one of two values: ``` Version: 1 Description: Example rules @@ -91,6 +103,147 @@ Rules: The filters and operations are modeled after those used by CloudCustodian: http://capitalone.github.io/cloud-custodian/docs/ + +## Operations supported for a Filter + +* eq - Equals + +Example: +``` +... + - id: VOLUME1 + resource: aws_ebs_volume + message: EBS Volumes must be encrypted + severity: FAILURE + filters: + - type: value + key: encrypted + op: eq + value: true +... +``` + +* ne - Not equals + +Example: +``` +... + - id: R1 + message: Instance type should not be c4.large + resource: aws_instance + filters: + - type: value + key: instance_type + op: ne + value: c4.large + severity: WARNING +... +``` + +* in - In list of values + +Example: +``` +... + - id: R1 + message: Instance type should be t2.micro or m3.medium + resource: aws_instance + filters: + - type: value + key: instance_type + op: in + value: t2.micro,m3.medium + severity: WARNING +... +``` + +* notin - Not in list of values + +* present - Attribute is present + +Example: +``` +... + - id: R6 + message: Department tag is required + resource: aws_instance + filters: + - type: value + key: "tags[].Department | [0]" + op: present + severity: FAILURE +... +``` + +* absent - Attribute is not present + +* contains - Attribute contains a substring + +* regex - Attribute matches a regular expression + +* not - Logical not of another filter + +Example: +``` +... + - id: NOTTEST + resource: aws_instance + message: Should not have instance type of c4.large + severity: WARNING + filters: + - not: + - type: value + key: instance_type + op: eq + value: c4.large +... +``` + +* and - Logical and of a list of filters + +Exmaple: +``` +... + - id: ANDTEST + resource: aws_instance + message: Should have both Project and Department tags + severity: WARNING + filters: + - and: + - type: value + key: "tags[].Department | [0]" + op: present + - type: value + key: "tags[].Project | [0]" + op: present + tags: + - and-test +... +``` + +* or - Logical or of a list of filters + +Example: + +``` +... + - id: ORTEST + resource: aws_instance + message: Should have instance_type of t2.micro or m3.medium + severity: WARNING + filters: + - or: + - type: value + key: instance_type + op: eq + value: t2.micro + - type: value + key: instance_type + op: eq + value: m3.medium +... +``` + # Output The program outputs a JSON string with the results. The JSON object has the following attributes: @@ -100,6 +253,8 @@ The program outputs a JSON string with the results. The JSON object has the foll * Failures - a list of rules with severity FAILURE that were triggered * AllViolations - a list of rules with any severity that were triggered (in case you use something other than WARNING or FAILURE) +## Using --query to limit the output + You can limit the output by specifying a JMESPath expression for the --query command line option. For example, if you just wanted to see the RecordIds for failed checks, you can do the following: ``` @@ -138,3 +293,5 @@ Lots to do. This is just a proof-of-concept. * Instead of iterating through rules, filters, then resources, make resources the outer loop, so results are reports by resource id * Add examples to this file for Kubernetes files * Support multiple rules files, or a rules directory +* Add a --table option which uses tablewriter for more readable report +* Not operator takes a list (to match the way Cloud Custodian works), should make sure size == 1