Definition Structure

Introduction

Custom Policies created in code (in YAML) support more complex logic than those created with the Visual Editor. This includes the ability to define a policy based on a resource’s Connection-State and the use of more complex AND/OR logic.

📘

Note

See here for a walk-through of the Code Editor.

Custom Policy - Components

A Custom Policy in code consists of these components:

  • Metadata (e.g., name, severity, etc.)
  • Scope/Provider (e.g., AWS)
  • Policy Definition (e.g., minimum password length configured = >x).

📘

Reminder

  • A policy specifies the desired state of an aspect of the configuration of a specific type of cloud resource.
  • A resource that is not in the defined state is non-compliant with the policy and will appear in the Incident queue after a Brigecrew scan.

Example

The Custom Policy below is assigned to the category general with a severity level of critical and declares that an AWS resource is non-compliant if it does not have a tag whose value is env.

1058

See the full specifications of each policy component below.

Metadata Component - Specification

Overview

950

A Policy’s metadata component defines:

  • Name
  • Guidelines
  • Category - based on Bridgecrew category definitions
  • Severity - displayed with Errors (Incidents) found by Bridgecrew scans and can be used for filtering

Metadata - Keys and Values

KeyDescriptionValuesExample
metadata.namePolicy Nametextname: "Ensure all ALBs are connected only to HTTPS listeners"
metadata.guidelinesPolicy description and fix details in case of a policy errortextguidelines: "In case of non-compliant resource - change the definition of the listener/listener_rule protocol value to HTTPS"
metadata.categoryThe area of cloud functionality the Policy relates to, for example, IAM or StorageString
Legal values (one only):

general
elaticsearch
iam
kubernetes
logging
monitoring
networking
public
secrets
serverless
storage
metadata.severityPolicy SeverityString
Use one of these:

critical
high
medium
low
info
severity: "high"

Scope Component - Specification

Overview

954

The Scope component of a custom policy associates the policy with a cloud provider.

Scope - Keys and Values

Supported KeyDescriptionValuesExample
scope.providerCloud Service ProviderString
Legal values (one only):

aws
azure
gcp
kubernetes
oci
openstack
provider: "aws"

Policy Definition Component - Specification

Overview

936

A Policy Definition consists of:

  • Defintion Block(s)- either Attribute Block(s) or Connection State Block(s) or both
  • Logical Operator(s) (optional)
  • Filter (optional)

Types of Definition Block

  • Attribute - The policy describes resources with a certain configuration as defined by a configuration attribute and its value (per Terraform), or by the presence/absence of an attribute.
  • Connection State - The policy describes resources in a particular Connection State, in other words, connected, or not connected to another type of resource (for example, a security group).

👍

Using AND/OR Logic

A policy definition may include multiple blocks (Attribute, Connection State or both), associated by AND/OR logic.

Attribute Block

Overview

An Attribute Block in a policy's definition, indicates that a resource will be non-compliant if a certain configuration attribute does not have a specified value, or if it exists/doesn't exist.

📘

Note

Bridgecrew's Custom Policies support both Terraform and CloudFormation attribute libraries and syntaxes.

Policies written using Terraform attributes will apply for Terraform (.tf and plan files). These policies will also apply when evaluating runtime cloud resources on AWS, Azure and GCP.

Policies written using CloudFormation attributes will apply for the following IaC frameworks:

  • CloudFormation
  • Serverless
  • CDK

Attribute - Example

The Attribute Block in the Definition in the example below, is used to ensure that a proper backup policy is configured for Redshift clusters.

definition:
     cond_type: "attribute"
     resource_types:
     - "aws_redshift_cluster"
     attribute: "automated_snapshot_retention_period"
     operator: "not_equals"
     value: "0"

Attribute Condition: Operators

OperatorValue in YAML
Equalsequals
Not Equalsnot_equals
Existsexists
Not Existsnot_exists
Containscontains
Not Containsnot_contains
Starts Withstarting_with
Not Starts Withnot_starting_with
Ends Withending_with
Not Ends Withnot_ending_with
RegEx Matchregex_match
Not RegEx Matchnot_regex_match
Greater Thangreater_than
Greater Than or Equalgreater_than_or_equal
Less Thanless_than
Less Than or Equalless_than_or_equal
Json Path Equalsjsonpath_equals
Subsetsubset
Not Subsetnot_subset
Json Path Existsjsonpath_exists

Attribute Condition: Keys and Values

KeyTypeValue(s)
cond_typestringMust be:
attribute
resource_typecollection of stringsUse either:
1. all
2. resource types from list
attributestringAttribute of defined resource types
For example, automated_snapshot_retention_period
operatorstringequals
not_equals
exists
not exists
contains
not_contains
starting_with
not_starting_with
ending_with
not_ending_with
regex_match
not_regex_match
greater_than
greater_than_or_equal
less_than
less_than_or_equal
value (not relevant for operator: exists/not_exists)string / number / booleanUser input

👍

See Examples of Multiple Attribute Blocks using AND/OR Logic

For examples of Policy Definitions with multiple Attribute Blocks using AND/OR logic, see:

Two Attribute Blocks with OR at Top Level

Attribute Block with OR Logic

Multiple Attribute Blocks with OR Relationship

Connection State Block

Overview

A Connection State Block indicates a type of resource that has/doesn't have a connection to another type of resource.
In the example presented in the table below, in order to be compliant aws_lb and aws_elb must have connections to either aws_security_group or aws_default_security_group.

Group AGroup B
aws_lb
aws_elb
aws_security_group
aws_default_security_group

Connection State - Example

The Connection State Block below indicates that to be compliant with the policy, resources of type aws_lb or of type aws_elb must be connected to either a resource of type aws_security_group or a resource of type aws_default_security_group.

definition:
       cond_type: "connection"
       resource_types:
           - "aws_elb"
       connected_resource_types:
         - "aws_security_group"
         - "aws_default_security_group"
       operator: "exists"

Connection State: Operators

OperatorValue
Existsexists
Not Existsnot_exists

Connection State: Keys and Values

KeyTypeValues
cond_typeStringMust be:
connection
resource_typesUse either:
1. all
2.
connected_resource_typesCollection of stringsUse either:
1. all
2.
operatorStringexists/not exists

Filters

Overview

Filters can be used to limit the types of resources relevant to a condition. Filters are most commonly used for Connection Blocks. (For Attribute Blocks you can easily limit the resource type with the resource_type parameter.)
For example, you may want to enforce a policy only for specific resource type(s) from specific groups defined in the conditions. Filters are available only for AND logic, at the top level.

Filter - Example

The Custom Policy in this example ensures that all ELBs are attached to security groups as shown in the table below.
In line with best practices, connections of this nature should be defined using security_groups key.

Group AGroup B
aws_elbaws_security_group
aws_default_security_group
defintion:
 and:
      - cond_type: "filter"
        resource_types:
           - "aws_elb"
        attribute: “resource_type”
        operator: "within”
      - cond_type: "connection"
        resource_types:
           - "aws_elb"
        connected_resource_types:
         - "aws_security_group"
         - "aws_default_security_group"
        operator: "exists"

📘

Note

Note:
The condition above uses AND logic. See additional examples of complex logic in policy definitions.

👍

See Examples of Complex Definitions with Connection State Blocks and Filters

Simple Connection State Block and Filter and Attribute Blocks

Complex Definition - Connection State Block + Filter + Attribute Blocks - Example 1

Complex Definition - Connection State Block + Filter + Attribute Blocks - Example 2

Using AND/OR Logic

Bridgecrew Cloud allows combination of definition blocks using AND/OR operators.

📘

Notes

  1. The top-level logical operator is the first key below "definition" (and not an item in a collection). It defines the relationship of all of the definition blocks in the specific YAML policy definition.
  2. Filter blocks apply (only) to the top-level and constitute an AND condition. For example, if you'd like to indicate a requirement for a Connection State between types of resources, but only within a certain subset of all of those resources.
  3. Every other logical operator applies within a collection. For example, you can use AND/OR logic in a collection of key-value pairs.

Example

The logic in the policy definition shown below is
AND[block 1,block 2,OR[block 3,block 4]].

#....
defintion:
           and:
               - #filter block 1
               - #block 2
               - or:
                   - #block 3
                   - #block 4

👍

See All Examples

See all examples of Custom Policies in code