Skip to content

Releases: aws-cloudformation/cloudformation-guard

v3.1.2

25 Nov 17:23
de26750
Compare
Choose a tag to compare

What's Changed

New Contributors

NOTE

Please note the new time api introduced in this release is considered experimental. Please report any bugs to our GitHub repository, we intend to stabilize it in an upcoming 3.2.0 release.

Full Changelog: 3.1.1...3.1.12

v3.1.1

12 Apr 17:30
b120e1e
Compare
Choose a tag to compare

What's Changed

  • [BugFix]: fix for regression regarding delimiters for show summary by @joshfried-aws in #494

Full Changelog: 3.1.0...3.1.1

v3.1.0

27 Mar 15:27
e44fc14
Compare
Choose a tag to compare

What's Changed

New Contributors

Full Changelog: 3.0.3...3.1.0

Table of Contents

  1. New Validate reporters
  2. New Test Flag to Specify an Output
  3. Cfn-Guard as a Library
  4. Stabilized Converter Functions

New Validate Reporters

  1. JUnit - users can now use the -o or --output-format flag to request a JUnit report -o junit
  2. Sarif - users can now use the -o or --output-format flag to request a Sarif report -o sarif

NOTE: If either junit, or sarif output-format is set, this requires the user to also pass --structured, and -S none otherwise cfn-guard will return an error

New Test Flag to Specify an Output

  1. The output format flag has been added to the test command. This means users can now take advantage of 4 different reporting mechanisms; single-line-summary, json, yaml, or junit

Cfn-Guard as a Library

  1. Users can now leverage cfn-guard as a library. We now have added builders for users to construct commands, and call them as needed. This will allow users to more easily build solutions with cfn-guard for specific needs

Stabilized Converter Functions

NOTE: This feature was previously introduced in version 3.0.1, it is now stabilized as of version 3.1.0
To improve the user experience for validating templates when schemas use types that might be easier evaluated as a different type (i.e. a string thats actually a number) the 3.0.1 release adds support to convert between specific types.

The conversions allowed are the following
strings/floats-> ints
strings/ints -> floats
strings -> bools
bools/floats/ints -> strings

The following is an example of parsing a string into an int.

Given the following template:

Resources:
  asg:
    Type: AWS::AutoScaling::AutoScalingGroup
    Properties:
      MinSize: "1"

We can write the following rule

let asg = Resources.*[ Type == 'AWS::AutoScaling::AutoScalingGroup' ]

rule test_parse_int when %asg !empty {
   let min = parse_int(%asg.Properties.MinSize)

   %min == 1
}

3.1.0-beta

01 Mar 19:13
a2f441f
Compare
Choose a tag to compare
3.1.0-beta Pre-release
Pre-release

What's Changed

New Contributors

Full Changelog: 3.0.3...3.1.0-beta

Table of Contents

  1. New Validate reporters
  2. New Test Flag to Specify an Output
  3. Cfn-Guard as a Library

New Validate Reporters

  1. JUnit - users can now use the -o or --output-format flag to request a JUnit report -o junit
  2. Sarif - users can now use the -o or --output-format flag to request a Sarif report -o sarif

NOTE: If either junit, or sarif output-format is set, this requires the user to also pass --structured, and -S none otherwise cfn-guard will return an error

New Test Flag to Specify an Output

  1. The output format flag has been added to the test command. This means users can now take advantage of 4 different reporting mechanisms; single-line-summary, json, yaml, or junit

Cfn-Guard as a Library

  1. Users can now leverage cfn-guard as a library. We now have added builders for users to construct commands, and call them as needed. This will allow users to more easily build solutions with cfn-guard for specific needs

v3.0.3

11 Jan 19:37
d397d8d
Compare
Choose a tag to compare

What's Changed

New Contributors

Full Changelog: 3.0.2...3.0.3

v3.0.2

17 Nov 15:51
88faf08
Compare
Choose a tag to compare

What's Changed

Full Changelog: 3.0.1...3.0.2

v3.0.1

08 Sep 15:00
e0a6602
Compare
Choose a tag to compare

What's Changed

Details

Added support for conversion functions

To improve the user experience for validating templates when schemas use types that might be easier evaluated as a different type (i.e. a string thats actually a number) the 3.0.1 release adds support to convert between specific types.

The conversions allowed are the following
strings/floats-> ints
strings/ints -> floats
strings -> bools
bools/floats/ints -> strings

The following is an example of parsing a string into an int.

Given the following template:

Resources:
  asg:
    Type: AWS::AutoScaling::AutoScalingGroup
    Properties:
      MinSize: "1"

We can write the following rule

let asg = Resources.*[ Type == 'AWS::AutoScaling::AutoScalingGroup' ]

rule test_parse_int when %asg !empty {
   let min = parse_int(%asg.Properties.MinSize)

   %min == 1
}

Full Changelog: 3.0.0...3.0.1

v3.0.0

29 Jun 19:32
c7bcce2
Compare
Choose a tag to compare

What's Changed

  • Populated filename in the output by @akshayrane in #358
  • Support for some function expressions / stateful rules by @joshfried-aws in #361
  • Combined structured output and updated default rule clause name to include file name by @akshayrane in #360
  • Clap Autocompletions by @joshfried-aws in #340
  • Adding documentation for functions by @joshfried-aws in #362
  • Deprecated migrate and previous engine by @akshayrane in #364
  • Removing unnecessary print statement for failure in parse-tree command by @joshfried-aws in #368
  • Improve error message for templates that cause an error by @joshfried-aws in #370
  • Clippy lints + ci by @joshfried-aws in #371
  • [Bugfix]: Fixed bug where cfn template fails validate rule check and when failing node isnt a child of resources by @joshfried-aws in #372
  • Updating reporters to all use serde for both json and yaml + misc improvements by @joshfried-aws in #373
  • [Bugfix] Fixing improper console output when using single line summary by @joshfried-aws in #378
  • [Enhancement] Creating a new error code for rule failures by @joshfried-aws in #379
  • Refined documentation for functions, join path bugfix & version bump by @akshayrane in #381
  • Changes to CI actions by @akshayrane & @joshfried-aws in #366 & #383
    • Updates to README.md for 3.0.0
    • Added latest configuration for aws-guard-rules-registry integration tests
    • Added new deployment method for cfn-guard-lambda through AWS SAM-CLI
    • Deprecated -j as short flag for print-json
    • Updated names for artifacts to have v3 in them
    • Added rogue_one branch to docker workflow, this will publish an ECR image for all updates to this remote branch as well
  • Added OS-specific cargo targets to release workflow by @akshayrane in #310
  • [Code Quality]: Rust-fmt action + formatting project by @joshfried-aws in #315
  • [Code Quality]: Implementing custom writer, bug fixes, new integration test framework, and adding initial tests for all commands by @joshfried-aws in #325
  • Bump tokio from 1.21.2 to 1.24.2 by @dependabot in #327
  • Improved documentation for new Guard version and keeping version up to date for GitHub runner OS by @razcloud in #365
  • +[fancy-regex] Added support for advanced regular expressions by @akshayrane in #326
  • improved safety of serde_yaml::Value -> value conversion by @joshfried-aws in #328
  • Improve handling of function references for test command by @joshfried-aws in #331
  • PR to add Thiserror to cfn-guard by @joshfried-aws in #329
  • Redirected verbose output from stdout to custom writer and added unit… by @akshayrane in #332
  • Addit cargo-audit to CI + bump up clap to 3.0 by @joshfried-aws in #330
  • Implemented custom reader, increasing test coverage for validate command. by @joshfried-aws in #334
  • Update CONTRIBUTING.md by @swiercek in #335
  • Clap4 by @joshfried-aws in #336
  • Added integration tests against aws-guard-rules-registry on Ubuntu by @akshayrane in #337
  • Update check-tags-present.guard by @Aishwarya4400 in #313
  • Adding structured evaluator by @joshfried-aws in #339

Breaking changes in 3.0.0

  1. Error codes - We emit a different exit code (19) now for validation failure if the data template(s) passed are non-compliant against the rules. This will make it easy to distinguish between the two. Previously, we emitted the same code as for parse errors (5). (PR #379)
  2. Intrinsic function resolution with test command. We now handle the intrinsic functions like Fn::ImportValue, Fn::Sub, etc in unit tests in an improved way. Read more about this change here.
  3. Standardized the output format for generic JSON/YAML templates to be inline with CFN-specific one. (PR #373)

Table of Contents

  1. Built-in Functions and Stateful Rules
  2. Added alternative deployment method using SAM-CLI for cfn-guard-lambda
  3. Updated the output to contain filename
  4. Updated combined structured output & default anonymous rule name
  5. Command auto-completions
  6. Added support for advanced regular expressions
  7. Improved handling for intrinsic functions in test command
  8. Added --structured flag to validate command to emit JSON/YAML parseable output

Details

1. Built-in Functions and Stateful Rules

As of version 3.0.0 guard now supplies some builtin functions, allowing for stateful rules.

Built-in functions are supported only through assignment to a variable at the moment, and not inline.

NOTE: all examples are operating off the following YAML template

Data

(click to expand)
Resources:
  newServer:
    Type: AWS::New::Service
    Properties:
      Policy: |
        {
           "Principal": "*",
           "Actions": ["s3*", "ec2*"]
        }
      Arn: arn:aws:newservice:us-west-2:123456789012:Table/extracted
      Encoded: This%20string%20will%20be%20URL%20encoded
    Collection:
      - a
      - b
      - c
    BucketPolicy:
      PolicyText: '{"Version":"2012-10-17","Statement":[{"Sid":"DenyReducedReliabilityStorage","Effect":"Deny","Principal":"*","Action":"s3:*","Resource":"arn:aws:s3:::s3-test-123/*","Condition":{"StringEquals":{"s3:x-amz-storage-class-123":["ONEZONE_IA","REDUCED_REDUNDANCY"]}}}]}'

  s3:
    Type: AWS::S3::Bucket
    Properties:
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true
  bucket:
    Type: AWS::S3::Bucket
    Properties:
      PublicAccessBlockConfiguration:
        BlockPublicAcls: false
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true

String Manipulation Functions

The following functions all operate on queries that resolve to string values

1. json_parse()

The json_parse function adds support for parsing inline JSON strings from a given template. After parsing the string into an object,
you can now evaluate certain properties of this struct just like with a normal JSON/YAML object

Rule

(click to expand)
let template = Resources.*[ Type == 'AWS::New::Service']
let expected = {
        "Principal": "*",
        "Actions": ["s3*", "ec2*"]
    }
rule TEST_JSON_PARSE when %template !empty {
    let policy = %template.Properties.Policy

    let res = json_parse(%policy)

    %res !empty
    %res == %expected
    <<
        Violation: the IAM policy does not match with the recommended policy
    >>
}    

2. regex_replace()

The regex_replace function adds support for replacing one regular expression with another

In this simple example, we will re-format an ARN by moving around some sections in it.
We will start with a normal ARN that has the following pattern: arn:<Partition>:<Service>:<Region>:<AccountID>:<ResourceType>/<ResourceID>
and we will try to convert it to: <Partition>/<AccountID>/<Region>/<Service>-<ResourceType>/<ResourceID>

Rule

(click to expand)
let template = Resources.*[ Type == 'AWS::New::Service']

rule TEST_REGEX_REPLACE when %template !empty {
    %template.Properties.Arn exists
    let arn = %template.Properties.Arn

    let arn_partition_regex = "^arn:(\w+):(\w+):([\w0-9-]+):(\d+):(.+)$"
    let capture_group_reordering = "${1}/${4}/${3}/${2}-${5}"
    let res = regex_replace(%arn, %arn_partition_regex, %capture_group_reordering)

    %res == "aws/123456789012/us-west-2/newservice-Table/extracted"
    << Violation: Resulting reformatted ARN does not match the expected format >>
}

3. join()

The join function adds support to collect a query, and the...

Read more

v3.0.0-beta

09 Jun 20:05
a3992ca
Compare
Choose a tag to compare
v3.0.0-beta Pre-release
Pre-release

What's Changed

  • Populated filename in the output by @akshayrane in #358
  • Support for some function expressions / stateful rules by @joshfried-aws in #361
  • Combined structured output and updated default rule clause name to include file name by @akshayrane in #360
  • Clap auto-completions by @joshfried-aws in #340
  • Added documentation for functions by @joshfried-aws in #362
  • Deprecated migrate and previous engine by @akshayrane in #364
  • 3.0.0-beta release changes by @akshayrane in #366
    • Bumped up version to 3.0.0-beta
    • Updates to README.md for 3.0.0
    • Added latest configuration for aws-guard-rules-registry integration tests
    • Added new deployment method for cfn-guard-lambda through AWS SAM-CLI
    • Deprecated -j as short flag for print-json
    • Updated names for artifacts to have v3 in them
    • Added rogue_one branch to docker workflow, this will publish an ECR image for all updates to this remote branch as well

Full Changelog: 3.0.0-alpha...3.0.0-beta

Table of Contents

  1. Built-in Functions and Stateful Rules
  2. Added alternative deployment method using SAM-CLI for cfn-guard-lambda
  3. Updated the output to contain filename
  4. Updated combined structured output & default anonymous rule name
  5. Command auto-completions

Details

1. Built-in Functions and Stateful Rules

As of version 3.0.0 guard now supplies some builtin functions, allowing for stateful rules

NOTE: all examples are operating off the following yaml template

Data

(click to expand)
Resources:
  newServer:
    Type: AWS::New::Service
    Properties:
      Policy: |
        {
           "Principal": "*",
           "Actions": ["s3*", "ec2*"]
        }
      Arn: arn:aws:newservice:us-west-2:123456789012:Table/extracted
      Encoded: This%20string%20will%20be%20URL%20encoded
    Collection:
      - a
      - b
      - c
    BucketPolicy:
      PolicyText: '{"Version":"2012-10-17","Statement":[{"Sid":"DenyReducedReliabilityStorage","Effect":"Deny","Principal":"*","Action":"s3:*","Resource":"arn:aws:s3:::s3-test-123/*","Condition":{"StringEquals":{"s3:x-amz-storage-class-123":["ONEZONE_IA","REDUCED_REDUNDANCY"]}}}]}'

  s3:
    Type: AWS::S3::Bucket
    Properties:
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true
  bucket:
    Type: AWS::S3::Bucket
    Properties:
      PublicAccessBlockConfiguration:
        BlockPublicAcls: false
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true

String Manipulation Functions

The following functions all operate on queries that resolve to string values

1. json_parse()

The json_parse function adds support for parsing inline json strings from a given template. After parsing the string into an object,
you can now evaluate certain properties of this struct just like with a normal json/yaml object

This function accepts a single argument:

  • this argument can either be a query that resolves to a string or a string literal.

The return value for this function is a query where each string that was resolved from the input is parsed into its json value

The following example shows how you could parse 2 fields on the above template and then write clauses on the results

Rule

(click to expand)
let template = Resources.*[ Type == 'AWS::New::Service']
rule TEST_JSON_PARSE when %template !empty {
    let policy = %template.Properties.Policy

    let res = json_parse(%policy)

    %res !empty
    %res == %expected

    let policy_text = %template.BucketPolicy.PolicyText
    let res2 = json_parse(%policy_text)

    %res2.Statement[*]
    {
            Effect == "Deny"
            Resource == "arn:aws:s3:::s3-test-123/*"
    }
}

2. regex_replace()

The regex_replace function adds support for replacing one regular expression with another

This function accepts 3 arguments:

  • The first argument is a query, each string that is resolved from this query will be operated on
  • The second argument is either a query that resolves to a string or a string literal, this is the expression we are looking for to extract
    • Note: if this string does not resolve to a valid regular expression an error will occur
  • The third argument is either a query that resolves to a string or a string literal, this is the expression we are going to use replace the extracted part of the string

The return value for this function is a query where each string that was resolved from the input that contains the the regex from our 2nd argument is replaced with the regex in the 3rd argument

In this simple example, we will re-format an ARN by moving around some sections in it.
We will start with a normal ARN that has the following pattern: arn:<Partition>:<Service>:<Region>:<AccountID>:<ResourceType>/<ResourceID>
and we will try to convert it to: <Partition>/<AccountID>/<Region>/<Service>-<ResourceType>/<ResourceID>

Rule

(click to expand)
let template = Resources.*[ Type == 'AWS::New::Service']

rule TEST_REGEX_REPLACE when %template !empty {
    %template.Properties.Arn exists
    let arn = %template.Properties.Arn

    let arn_partition_regex = "^arn:(\w+):(\w+):([\w0-9-]+):(\d+):(.+)$"
    let capture_group_reordering = "${1}/${4}/${3}/${2}-${5}"
    let res = regex_replace(%arn, %arn_partition_regex, %capture_group_reordering)

    %res == "aws/123456789012/us-west-2/newservice-Table/extracted"
}

3. join()

The join function adds support to collect a query, and then join their values using the provided delimiter.

This function accepts 2 arguments:

  • The first argument is a query, all string values resolved from this query will then be joined using the delimter argument
  • The second argument is either a query that resolves to a string/character, or a literal value that is either a string or character

The return value for this function is query where each string that was resolved from the input is joined with the provided delimiter

The following example queries the template for a Collection field on a given resource, it then provides a join on ONLY the string values that this query resolves to with a , delimiter

Rule

(click to expand)
let template = Resources.*[ Type == 'AWS::New::Service']

rule TEST_COLLECTION when %template !empty {
    let collection = %template.Collection.*

    let res = join(%collection, ",")
    %res == "a,b,c"
}

4. to_lower() & 5. to_upper()

Both functions accept a single argument:

  • This argument is a query that resolves to a string(s) - all strings resolved will have the operation applied on them

Both these functions are very similar, one manipulates all resolved strings from a query to lower case, and the other to upper case

Rule

(click to expand)
let type = Resources.newServer.Type

rule STRING_MANIPULATION when %type !empty {
    let lower = to_lower(%type)
    %lower == "aws::new::service"
    %lower == /aws::new::service/

    let upper = to_upper(%type)
    %upper == "AWS::NEW::SERVICE"
    %upper == /AWS::NEW::SERVICE/
}

6. substring()

The substring function adds support to collect a part of all strings resolved from a query

This function accepts 3 arguments:

  • The first argument is a query, each string that is resolved from this query will be operated on
  • The second argument is either a query that resolves to an int or a literal int, this is the starting index for the substring (inclusive)
  • The third argument is either a query that resolves to an int or a literal int, this is the ending index for the substring (exclusive)

The return value for this function takes the strings resolved from the first argument, and returns a result of substrings for each one of them:
Note: Any string that would result in an index out of bounds from the 2nd or 3rd argument is skipped

Rule

(click to expand)
let template = Resources.*[ Type == 'AWS::New::Service']

rule TEST_SUBSTRING when %template !empty {
    %template.Properties.Arn exists
    let arn = %template.Properties.Arn

    let res = substring(%arn, 0, 3)

    %res == "arn"
}

7. url_decode()

This function accepts a single argument:

  • this argument can either be a query that resolves to a string or a string literal.

The return value for this function is a query that contains each url decoded version of every string value from the input

The following rule shows how you could url_decode the string This%20string%20will%20be%20URL%20encoded

Rule

(click to expand)
let template = Resources.*[ Type == 'AWS::New::Service']

rule SOME_RULE when %template !empty {
    %template.Properties.Encoded exists
    let ...
Read more

v2.1.4

09 Jun 17:16
Compare
Choose a tag to compare

What's Changed

New Contributors

Full Changelog: 2.1.3...2.1.4

Details

Added support for advanced regular expressions

Supports usage of advanced regular expressions such as lookaround and backreferences.

Rules file (advanced_regex_negative_lookbehind_rule.guard)

NotAwsAccessKey != /(?<![A-Z0-9])[A-Z0-9]{20}(?![A-Z0-9])/
NotSecretAccessKey != /(?<![A-Za-z0-9\\/+=])[A-Za-z0-9\\/+=]{40}(?![A-Za-z0-9\\/+=])/
Data file (advanced_regex_negative_lookbehind_non_compliant.yaml) (click to expand)
NotAwsAccessKey: AKIAIOSFODNN7EXAMPLE
NotSecretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Command (click to expand)
cfn-guard validate \
	-d guard/resources/validate/data-dir/advanced_regex_negative_lookbehind_non_compliant.yaml \
	-r guard/resources/validate/rules-dir/advanced_regex_negative_lookbehind_rule.guard \
	--show-summary all
Output with non-compliant template (click to expand)
advanced_regex_negative_lookbehind_non_compliant.yaml Status = FAIL
FAILED rules
advanced_regex_negative_lookbehind_rule.guard/default    FAIL
---
Evaluation of rules advanced_regex_negative_lookbehind_rule.guard against data advanced_regex_negative_lookbehind_non_compliant.yaml
--
Property [/NotAwsAccessKey] in data [advanced_regex_negative_lookbehind_non_compliant.yaml] is not compliant with [advanced_regex_negative_lookbehind_rule.guard/default] because provided value ["AKIAIOSFODNN7EXAMPLE"] did match expected value ["/(?<![A-Z0-9])[A-Z0-9]{20}(?![A-Z0-9])/"]. Error Message []
Property [/NotSecretAccessKey] in data [advanced_regex_negative_lookbehind_non_compliant.yaml] is not compliant with [advanced_regex_negative_lookbehind_rule.guard/default] because provided value ["wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"] did match expected value ["/(?<![A-Za-z0-9\\/+=])[A-Za-z0-9\\/+=]{40}(?![A-Za-z0-9\\/+=])/"]. Error Message []