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:
{
"description": "Allow all insert operations",
"let": {
"insertChange": { "change": {"type": "INSERT" } }
},
"effect": {
"target": "insertChange",
"risk": "low",
"action": "approve"
}
}
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".