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.

See the full specifications of each policy component below.

Metadata Component - Specification

Overview

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

Key

Description

Values

Example

metadata.name

Policy Name

text

name: "Ensure all ALBs are connected only to HTTPS listeners"

metadata.guidelines

Policy description and fix details in case of a policy error

text

guidelines: "In case of non-compliant resource - change the definition of the listener/listener_rule protocol value to HTTPS"

metadata.category

The area of cloud functionality the Policy relates to, for example, IAM or Storage

String
Legal values (one only):

general
elaticsearch
iam
kubernetes
logging
monitoring
networking
public
secrets
serverless
storage

metadata.severity

Policy Severity

String
Use one of these:

critical
high
medium
low
info

severity: "high"

Scope Component - Specification

Overview

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

Scope - Keys and Values

Supported Key

Description

Values

Example

scope.provider

Cloud Service Provider

String
Legal values (one only):

aws
azure
gcp

provider: "aws"

Policy Definition Component - Specification

Overview

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

Operator

Value in YAML

Equals

equals

Not Equals

not_equals

Exists

exists

Not Exists

not_exists

Contains

contains

Not Contains

not_contains

Starts With

starting_with

Not Starts With

not_starting_with

Ends With

ending_with

Not Ends With

not_ending_with

RegEx Match

regex_match

Not RegEx Match

not_regex_match

Attribute Condition: Keys and Values

Key

Type

Value(s)

cond_type

string

Must be:
attribute

resource_type

collection of strings

Use either:

  1. all
  2. resource types from list

attribute

string

Attribute of defined resource types
For example, automated_snapshot_retention_period

operator

string

equals
not_equals
exists
not exists
contains
not_contains
starting_with
not_starting_with
ending_with
not_ending_with
regex_match
not_regex_match

value (not relevant for operator: exists/not_exists)

string / number / boolean

User 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 A

Group 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

Operator

Value

Exists

exists

Not Exists

not_exists

Connection State: Keys and Values

Key

Type

Values

cond_type

String

Must be:
connection

resource_types

Use either:

  1. all

connected_resource_types

Collection of strings

Use either:

  1. all

operator

String

exists/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 A

Group B

aws_elb

aws_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


Did this page help you?