Skip to content

Latest commit

 

History

History
146 lines (130 loc) · 3.14 KB

RULE_DEVELOPMENT.md

File metadata and controls

146 lines (130 loc) · 3.14 KB
Raw

CloudFormation - Resource Schema Guard Rail

Common Requirements:

  1. Both types of rules MUST follow cloudformation-guard DSL

  2. Rule name MUST start with ensure*

  3. Rule might have multiple checks in it

  4. Rule Check MUST emit error message of the following format:

    {
    "result": "...",
    "check_id": "...",
    "message": "..."
}

  5. Result MUST be either NON_COMPLIANT or WARNING

  6. Check_id MUST be a unique check code

  7. Message MUST be a short description why the check is failing

Basic Linting Rules

Rule Mechanics

Stateless rules are run over the resource schemas. There is no concept of previous state. Assumption - it evaluates live state of the schema. Rules are supposed to cover json semantics.

Sample Schema Snippet
{
    "properties": {
        "Arn": {
            "type": "string"
        }
    },
    ...
}
Sample Rule
let props = properties[ keys == /(Arn|arn|ARN)/ ]
rule ensure_arn_properties_type_string when %props !empty {
    %props.type == 'string'
    <<
    {
        "result": "NON_COMPLIANT",
        "check_id": "ARN_1",
        "message": "arn related property MUST have pattern specified"
    }
    >>
}

Stateful Rules

Rule Mechanics

Stateful rules are run over the difference between two schemas - previous & current version. Stateful module creates a metadiff object, which is following listed below structure:

{
    "keyword": {
        "added": [],
        "removed": [],
        "changed": []
    }
}

It currently supports two types of keywords - CloudFormation built and Json native:

CloudFormation Built
  • primaryIdentifier
  • readOnlyProperties
  • writeOnlyProperties
  • createOnlyProperties
  • additionalIdentifiers
JSON Native
  • type
  • description
  • enum
  • maximum
  • minimum
  • maxLength
  • minLength
  • required
  • pattern
  • maxItems
  • minItems
  • contains
  • items
  • additionalProperties
Sample MetaDiff
{
    "properties": {
        "added": ["/properties/Arn"]
    },
    "minimum": {
        "changed": [
            {
                "property": "/properties/NumberOfDays",
                "old_value": 7,
                "new_value": 8
            }
        ]
    },
    "minLength": {
        "changed": [
            {
                "property": "/properties/Tags/*/Value",
                "old_value": 0,
                "new_value": 1
            }
        ]
    },
    "readOnlyProperties": {
        "added": ["/properties/Arn"]
    }
}
Sample Rule
rule ensure_min_length_new_value_is_positive when minLength exists
{
    minLength.changed[*] {
        this.new_value > 0
        <<
        {
            "result": "NON_COMPLIANT",
            "check_id": "POSVAL",
            "message": "new value for minLength MUST be positive"
        }
        >>
    }
}
Limitations
Combiners

Currently, Stateful module can only process resource schemas without combiners. Combiners support is planned to be implemented later.

  • allOf
  • anyOf
  • oneOf