Global Helper Functions

Overview
A common pattern in programming is to extract repeated code into helper functions, and Panther supports this pattern with the global analysis type.
Global helpers are not best suited to frequent changes. Lookup Tables support automatic syncing with S3, which means they don't require code changes within Panther for updates.
Built-in Globals
By default, Panther comes with built-in global helpers such as panther and panther_oss_helpers. panther is a default and already set up for you to define your custom logic, and panther_oss_helpers provides boilerplate helpers to common caching and other use cases.
Using Globals
Import global helpers in your detections by declared ID at the top of your analysis function body then call the global as if it were any other python library.
For example:
import panther_oss_helpers
​
​
def rule(event):
  return event['name'] == 'test-bucket'
​
​
def title(event):
  # Lookup the account name from an account Id
  account_name = panther_oss_helpers.lookup_aws_account_name(event['accountId'])
  return 'Suspicious request made to account ' + account_name
Adding New Globals
New globals can be created from the Panther Analysis Tool or in your Panther Console.
Panther Console
Panther Analysis Tool
To create a new global in the Panther Console:
1.Log in to your Panther Console and navigate to Build > Helpers.
2.In the upper right corner, click Create New.
​
3.Type your Python functions, then click Create. This global can now be imported in your rules or policies.
Global functions allow common logic to be shared across either rules or policies. To declare them as code, add them into the global_helpers folder with a similar pattern to rules and policies.
Globals defined outside of the global_helpers folder will not be loaded.
​
1.Create your Python file (global_helpers/acmecorp.py):
from fnmatch import fnmatch
​
RESOURCE_PATTERN = 'acme-corp-*-[0-9]'
​
​
def matches_internal_naming(resource_name):
  return fnmatch(resource_name, RESOURCE_PATTERN)
​
  2. Create your specification file:
AnalysisType: global
GlobalID: acmecorp
Filename: acmecorp.py
Description: A set of helpers internal to acme-corp
​
  3. Use this helper in a policy (or a rule):
import acmecorp
​
​
def policy(resource):
  return acmecorp.matches_internal_naming(resource['Name'])
Common Helpers
deep_get()
Located in panther_base_helpers.
deep_get() can be used to return keys that are nested within the python dictionaries.  This function is useful for safely returning nested keys and avoiding an AttributeError when a key is not present. 
def deep_get(dictionary: dict, *keys, default=None):
    """Safely return the value of an arbitrarily nested map
    Inspired by https://bit.ly/3a0hq9E
    """
    return reduce(
        lambda d, key: d.get(key, default) if isinstance(d, Mapping) else default, keys, dictionary
    )
Example:
With the following JSON, the deep_get function would return the value of result.
{ "outcome": { "reason": "VERIFICATION_ERROR", "result": "FAILURE" }}
deep_get(event, "outcome", "result") == "FAILURE"
An example of this can be found in the Geographically Improbable Okta Login detection.
is_ip_in_network()
Located in panther_base_helpers.
is_ip_in_network() is a function to check if an IP address is within a list of IP ranges.  This function can be used with a list of known internal networks for added context to the detection.
def is_ip_in_network(ip_addr, networks):
    """Check that a given IP is within a list of IP ranges"""
    return any(ip_address(ip_addr) in ip_network(network) for network in networks)
Example:
SHARED_IP_SPACE = [
    "192.168.0.0/16",
]
​
if is_ip_in_network(event.get("ipaddr"), SHARED_IP_SPACE):
    ...
An example can be found in the OneLogin Active Login Activity detection.
pattern_match()
Located in panther_base_helpers.
Wrapper around fnmatch for basic pattern globs. This can be used when simple pattern matching is needed without the requirement of using regex.
def pattern_match(string_to_match: str, pattern: str):
    """Wrapper around fnmatch for basic pattern globs"""
    return fnmatch(string_to_match, pattern)
Example:
With the following JSON the pattern_match() function would return true. 
{ "operation": "REST.PUT.OBJECT" }
pattern_match(event.get("operation", ""), "REST.*.OBJECT")
An example can be found in the AWS S3 Access Error detection.
pattern_match_list()
Located in panther_base_helpers.
Similar to pattern_match(), pattern_match_list() can check that a string matches any pattern in a given list.
def pattern_match_list(string_to_match: str, patterns: Sequence[str]):
    """Check that a string matches any pattern in a given list"""
    return any(fnmatch(string_to_match, p) for p in patterns)
Example:
With the following JSON the pattern_match_list() function would return true. 
{ "userAgent": "aws-sdk-go/1.29.7 (go1.13.7; darwin; amd64) APN/1.0 HashiCorp/1.0 Terraform/0.12.24 (+https://www.terraform.io)" }
ALLOWED_USER_AGENTS = {
    "* HashiCorp/?.0 Terraform/*",
    # 'console.ec2.amazonaws.com',
    # 'cloudformation.amazonaws.com',
}
​
pattern_match_list(event.get("userAgent"), ALLOWED_USER_AGENTS)
An example can be found in the AWS EC2 Manual Security Group Change detection.
aws_strip_role_session_id()
Located in panther_base_helpers.
aws_strip_role_session_id() strips the session ID our of the arn. 
def aws_strip_role_session_id(user_identity_arn):
    # The ARN structure is arn:aws:sts::123456789012:assumed-role/RoleName/<sessionId>
    arn_parts = user_identity_arn.split("/")
    if arn_parts:
        return "/".join(arn_parts[:2])
    return user_identity_arn
Example:
With the following value, aws_strip_role_session_id() would return arn:aws:sts::123456789012:assumed-role/demo
{ "arn": "arn:aws:sts::123456789012:assumed-role/demo/sessionName" }
aws_strip_role_session_id(user_identity.get("arn", ""))
An example can be found in the AWS Unauthorized API Call detection.
Data Models
Report Mapping
Last modified 2mo ago