@aws-c2a/rules

Rules - CDK Change Analyzer (C2A)

The C2A rules language lets you classify infrastructure changes according to risk profile. These classifications will then be applied when you run aws-c2a diff or use the CDK Pipelines step.

Changes can be classified along to 2 different axes:

• Risk: changes can be classified as high, low or unknown risk. This helps human reviewers concentrate effort on the most important types of changes when making a determination on whether or not to proceed with the deployment.
• Effect: changes can be automatically approved, or always rejected. In the former case, if all changes in a deployment are automatically classified as approved, the human review is skipped. Otherwise, if any of the changes in a deployment are rejected the deployment will fail and not proceed.

Rule Definition

Rules operate on a [graph](https://en.wikipedia.org/wiki/Graph_(discrete_mathematics) that represent the difference between two CloudFormation templates, and contains a representation of all the changes introduced by the difference between the two templates.

Each rule is written in a custom JSON syntax, and performs a graph query, looking up vertices and and traversing edges in the graph, to find the appropriate change vertices and attach a desired classification to them.

Here's an example of a very simple rule:

{
  // Give the rule a useful description
  "description": "Allow all insert operations",

  // Bind identifiers. In this case, let the identifier 'insertChange' go over
  // 'change' nodes that represent an INSERT.
  "let": {
    "insertChange": { "change": {"type": "INSERT" } }
  },

  // Classify the change vertices found by 'insertChange' as 'low risk'
  // and 'automatically approved'.
  "effect": {
    "target": "insertChange",
    "risk": "low", // or "high"
    "action": "approve" // or "reject"
  }
}

This is a very simple rule that approves and marks all component operations of type INSERT as a low risk change. It is broken down below:

let The let field defines the bindings for a given rule. In this case, the identifier, insertChange, is bound to the query that matches all change objects of type INSERT. The let field acts as a scope for the rule, where each binding is executed in order, allowing you to chain bindings in a sequential manner.

effect The effect field defines the outcome of any objects, identified as target, returned from the queries. In this case, the target is insertChange, which corresponds to all insert operations. The risk and automatic approval behavior for these changes are specified in the fields risk and action respectively.

Nested Rules

Every rule has a scope; defined by the bindings that are declared in the let field. You can utilize the notion of scope to chain rules together in a nested style.

{
  "description": "CLOUDFRONT",
  "let": { "cf": { "Resource": "AWS::CloudFront::Distribution" } },
  "then": [
    {
      "description": "Cloudfront Distributions origin changes are risky",
      "let": {
        "change": { "change": {}, "where": "change appliesTo cf.Properties.DistributionConfig.Origins" }
      },
      "effect": {
        "risk": "high"
      }
    },
    {
      "description": "Cloudfront Distributions origin protocol security can increase",
      "let": {
        "change": { "change": {}, "where": [
          "change appliesTo cf.Properties.DistributionConfig.Origins.*.OriginProtocolPolicy",
          "change.old == 'http-only'",
          "change.new == 'https-only'"
          ]
        }
      },
      "effect": {
        "risk": "low",
        "action": "approve"
      }
    }
  ]
}

then In this rule, the then field is used to apply sub-rules that have access to the bindings declared in their parent scope.

where The where field defines conditions that the query must satisfy. These conditions include, but are not limited to, checking if a change applies to a given object (Component or Property) with the operator appliesTo; comparing old and new values of changes to properties with the .old accessor and == operator.

Component and Property objects allow accessing their inner properties by using the dot (".") notation. For example component.someArray.*.property will correspond to all values of key "property" in elements of array "someArray" inside "component".