Writing (Local)

How to write and test policies locally

When writing policies locally, you must construct two files. One is the python body, the other is the JSON or YAML policy specification file.

The body contain the logic to determine vulnerable resources. The specification file contains policy metadata and configuration settings.

Policy Body

Similar to within the web UI, the policy body only has only three requirements:

  1. The policy body must be valid python3 code

  2. The policy body must define a policy function that accepts one argument

  3. The policy function must return a bool type

Other than that, the policy body can contain anything you find useful to writing your policies. Helper functions, global variables, comments, etc. are all permitted. By convention, we name the argument to the policy function resource, so a minimal (and useless) policy body would be such:

def policy(resource):
return True

The argument resource will be a map, with keys of type str. For definitions of these maps, see the Resources documentation.

Specification File

The policy specification file must be valid JSON or YAML, with a .json or .yml / .yaml file extension as appropriate. The accepted fields for the policy specification file are detailed below.

Field Name

Required

Description

Expected Value

AnalysisType

Yes

Indicates whether this specification is defining a policy or a rule

The string policy or the string rule

Enabled

Yes

Whether this policy is enabled

Boolean

FileName

Yes

The name (with file extension) of the python policy body

String

PolicyID

Yes

The unique identifier of the policy

String

ResourceTypes

Yes

What resource types this policy will apply to

List of strings

Severity

Yes

What severity this policy is

One of the following strings: Info | Low | Medium | High | Critical

ActionDelaySeconds

No

How long (in seconds) to delay auto-remediations and alerts, if configured

Integer

AlertFormat

No

Not used at this time

NA

AutoRemediationID

No

The unique identifier of the auto-remediation to execute in case of policy failure

String

AutoRemediationParameters

No

What parameters to pass to the auto-remediation, if one is configured

Map

Description

No

A brief description of the policy

String

DisplayName

No

What name to display in the UI and alerts. The PolicyID will be displayed if this field is not set.

String

Reference

No

The reason this policy exists, often a link to documentation

String

Runbook

No

The actions to be carried out if this policy fails, often a link to documentation

String

Tags

No

Tags used to categorize this policy

List of strings

Tests

No

Unit tests for this policy. See Testing for details on how unit tests are formatted.

List of maps