From 000eb2be429be41e8acc55885942affe9db4479d Mon Sep 17 00:00:00 2001 From: Anders Eknert Date: Mon, 4 Apr 2022 15:02:15 +0200 Subject: [PATCH] docs: CloudFormation fixes (#4541) * Fix step headers to use h3 * Add warning about boolean values conversion Signed-off-by: Anders Eknert --- docs/content/aws-cloudformation-hooks.md | 30 ++++++++++++++++++++---- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/docs/content/aws-cloudformation-hooks.md b/docs/content/aws-cloudformation-hooks.md index e3fb292cbf..6602353e61 100644 --- a/docs/content/aws-cloudformation-hooks.md +++ b/docs/content/aws-cloudformation-hooks.md @@ -105,11 +105,11 @@ aws cloudformation --region "$AWS_REGION" set-type-configuration \ The hook is now installed, configured and activated! -## 3. Learn the Domain +### 3. Learn the Domain Before we proceed to write our first policy, let's take a closer look at the data we'll be working with. -### AWS CloudFormation Templates +#### AWS CloudFormation Templates A template file is commonly a YAML or JSON file, describing a set of AWS resources. While a template may describe multiple resources, the hook will send each resource for validation separately. Important to note here is that the @@ -127,7 +127,7 @@ Resources: For more information on templates, see the [AWS User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html) on that topic. -### Input and Response Format +#### Input and Response Format The OPA configured to receive requests from the CFN hook will have its input provided in this format: @@ -163,7 +163,7 @@ The hook expects the response to contain a boolean `allow` attribute, and a list Any request denied will be logged in [AWS CloudWatch](https://aws.amazon.com/cloudwatch/) for the same account. -## 4. Write a CloudFormation Hook Policy +### 4. Write a CloudFormation Hook Policy With knowledge of the domain and the data model, we're ready to write our first CloudFormation Hook policy. Since we'll have a single OPA endpoint servicing requests for all types of resources, we'll use the @@ -217,7 +217,27 @@ fail (i.e. not evaluate) as soon as the property was missing, leading to the res and negation is a good way to work with data that might or might not be present, and results in more readable policies, too. -## 5. Policy Enforcement Testing +{{< danger >}} +Surprisingly, boolean values from CloudFormation Templates are provided to the hook in the form of **strings** (i.e. +"true" and "false"). Policy authors must take this into account, and explicitly check for the value of these +attributes. An example S3 bucket policy might for example want to check that public ACLs are blocked: + +```live:example/boolean_fail:module:read_only +# Wrong: will allow both "true" and "false" values as both are considered "truthy" +block_public_acls { + input.resource.properties.PublicAccessBlockConfiguration.BlockPublicAcls +} +``` + +```live:example/boolean_correct:module:read_only +# Correct: will allow only when property set to "true" +block_public_acls { + input.resource.properties.PublicAccessBlockConfiguration.BlockPublicAcls == "true" +} +``` +{{< /danger >}} + +### 5. Policy Enforcement Testing With the above policy loaded into OPA, we may proceed to try it out. Let's deploy the minimal S3 Bucket from the previous template example. Save the below minimal template to a file called `s3bucket.yaml`: