Policies
Scan and evaluate cloud infrastructure configurations
Policies are Python functions used to identify misconfigured cloud infrastructure and generate alerts for your team. Panther provides a number of already written and continuously updated Panther-managed policies.
Before you start writing a new policy, remember to check to see if there's an existing Panther-managed policy that meets your needs.
The policy body must:
- Be valid Python3.
- Define a
policy()
function that accepts oneresource
argument. - Return a
bool
from the policy function.
def policy(resource):
return True
The Python body should name the argument to the
policy()
function resource
and also may do the following:- Import standard Python3 libraries
- Import from the user defined
aws_globals
module - Import from the Panther defined
panther
module - Define additional helper functions as needed
- Define variables and classes outside the scope of the rule function
Using the schemas in supported resources provides details on all available fields in resources. Top level keys are always present, although they may contain
NoneType
values.You can write and deploy policies in the Panther Console or you can write them locally and upload them to Panther via Panther Analysis Tool (PAT). For detailed instructions on configuring PAT, see Panther Developer Workflows.
Panther Console
Write policies locally
- 1.Log in to the Panther Console.
- 2.In the left sidebar, click Build > Detections.
- 3.In the upper right, click Create New.
- 4.At the top of the page, choose Policy as the detection type.
- 5.Fill out the Basic Info form:
- Name: Enter a descriptive name.
- Resource Types: Select the resource you want to apply this policy to. Leave empty to apply to all resources.
- 6.Scroll down to Policy Settings. Optionally add a Description, Runbook, Reference, Ignore Patterns, Custom Tags, and Destination Overrides.
- 7.Click the Functions & Tests tab. Write a Python function to define your policy in the Policy Function text editor.
- 8.Click {} Create Test to run a test against the Policy you defined in the previous step.
- 9.In the upper right corner of the page, click Save.
We recommend managing your local detection files in a version control system like GitHub or GitLab.
It's best practice to create a fork of Panther's open-source analysis repository, but you can also create your own repo from scratch.
Each detection consists of:
- A Python file (a file with a
.py
extension) containing your detection/audit logic - A YAML or JSON specification file (a file with a
.yml
or.json
extension) containing metadata attributes of the detection.- By convention, we give this file the same name as the Python file.
If you group your policies into folders, each folder name must contain
policies
in order for them to be found during upload (using either PAT or the bulk uploader in the Console).We recommend grouping policies into folders based on log/resource type, e.g.,
suricata_rules
or aws_s3_policies
. You can use the open source Panther Analysis repo as a reference.- 1.Write your policy and save it (in your folder of choice) as
my_new_policy.py
: def polcy(resource):def policy(resource):return resource['Region'] != 'us-east-1' - 2.Create a specification file using the template below:AnalysisType: policyEnabled: trueFilename: my_new_policy.pyPolicyID: Category.Type.MoreInfoResourceType:- Resource.Type.HereSeverity: Info|Low|Medium|High|CriticalDisplayName: Example Policy to Check the Format of the SpecTags:- Tags- Go- HereRunbook: Find out who changed the spec format.Reference: https://www.link-to-info.io
Manually building test cases can be prone to human error. We suggest one of the following methods:
- Option 1: In the Panther Console, navigate to Investigate > Cloud Resources. Apply a filter of the resource type you intend to emulate in your test. Select a resource in your environment, and on the
Attributes
card you can copy the full JSON representation of that resource by selecting copy button next to the wordroot
. - Option 2: Open the Panther Resources documentation, and navigate to the section for the resource you are trying to emulate. Copy the provided example resource. Paste this in to the resource editor if you're working in the web UI, or into the
Resource
field if you are working locally. Now you can manually modify the fields relevant to your policy and the specific test case you are trying to emulate.
Option 1 is best when it is practical, as this can provide real test data for your policies. Additionally, it is often the case that you are writing/modifying a policy specifically because of an offending resource in your account. Using that exact resource's JSON representation as your test case can guarantee that similar resources will be caught by your policy in the future.
Debugging exceptions can be difficult, as you do not have direct access to the Python environment running the policies.
When you see a policy that is showing the state
Error
on a given resource, that means that the policy threw an exception. The best method for troubleshooting these errors is to use option 1 in the Constructing test resources section above and create a test case from the resource causing the exception.Running this test case either locally or in the Panther Console should provide more context for the issue, and allow you to modify the policy to debug the exception without having to run the policy against all resources in your environment.
Note: Anything printed to
stdout
or stderr
by your Python code will end up in CloudWatch. For SaaS/CPaaS customers, Panther engineers can see these CloudWatch logs during routine application monitoring.In the example below, the policy checks if an S3 bucket allows public read access:
# A list of grantees that represent public access
GRANTEES = {
'http://acs.amazonaws.com/groups/global/AuthenticatedUsers',
'http://acs.amazonaws.com/groups/global/AllUsers'
}
PERMISSIONS = {'READ'}
def policy(resource):
for grant in resource['Grants']:
if grant['Grantee']['URI'] in GRANTEES and grant[
'Permission'] in PERMISSIONS:
return False
return True
This example policy alerts when the password policy does not enforce a maximum password age:
def policy(resource):
if resource['MaxPasswordAge'] is None:
return False
return resource['MaxPasswordAge'] <= 90
In the
policy()
body, returning a value of True
indicates the resource is compliant and no alert should be sent. Returning a value of False
indicates the resource is non-compliant.{
"AccountId": "123456789012",
"AllowUsersToChangePassword": true,
"AnyExist": true,
"ExpirePasswords": true,
"HardExpiry": null,
"MaxPasswordAge": 90,
"MinimumPasswordLength": 14,
"Name": "AWS.PasswordPolicy",
"PasswordReusePrevention": 24,
"Region": "global",
"RequireLowercaseCharacters": true,
"RequireNumbers": true,
"RequireSymbols": true,
"RequireUppercaseCharacters": true,
"ResourceId": "123456789012::AWS.PasswordPolicy",
"ResourceType": "AWS.PasswordPolicy",
"Tags": null,
"TimeCreated": null
}
Required fields are in bold.
A complete list of policy specification fields:
Field Name | Description | Expected Value |
AnalysisType | Indicates whether this specification is defining a policy or a rule | policy |
Enabled | Whether this policy is enabled | Boolean |
FileName | The path (with file extension) to the python policy body | String |
PolicyID | The unique identifier of the policy | String |
ResourceTypes | What resource types this policy will apply to | List of strings |
Severity | What severity this policy is | One of the following strings: Info , Low , Medium , High , or Critical |
Description | A brief description of the policy | String |
DisplayName | What name to display in the UI and alerts. The PolicyID will be displayed if this field is not set. | String |
Reference | The reason this policy exists, often a link to documentation | String |
| | |
Reports | A mapping of framework or report names to values this policy covers for that framework | Map of strings to list of strings |
Runbook | The actions to be carried out if this policy fails, often a link to documentation | String |
Tags | Tags used to categorize this policy | List of strings |
Tests | Unit tests for this policy. | List of maps |
Last modified 30d ago