PyPanther Detections

Configure detections fully in Python

Overview

PyPanther Detections are in closed beta starting with Panther version 1.108. Please share any bug reports and feature requests with your Panther support team.

PyPanther Detections are Panther’s evolved approach to detections-as-code. In this framework, detections are defined fully in Python, enabling component reusability and simple rule overrides. The foundation of PyPanther Detections is the Panther-managed pypanther Python library.

Key features

  • An entirely Python-native experience for importing, writing, modifying, testing, and uploading rules—eliminating the need to manage a fork or clone of panther-analysis.

    # Import the Panther-managed BoxNewLogin rule
    from pypanther.rules.box_rules.box_new_login import BoxNewLogin
  • The ability to apply custom configurations to Panther-managed rules through overrides, filters, and inheritance.

    from pypanther import Severity
    from pypanther.wrap import exclude
    
    # Set multiple attribute overrides
    BoxNewLogin.override(
        default_severity=Severity.MEDIUM,
        tags=['Initial Access'],
        default_runbook="Ask user in Slack if this login was actually from them.",
    )
    
    # Add a simple filter to exclude all logins from Alice
    exclude(lambda e: e.deep_get('created_by', 'name') != 'Alice')(BoxNewLogin)
  • The ability to selectively choose the set of rules you want to include in your Panther deployment package.

    from pypanther import register
    
    # Register a single rule to test and upload
    register(BoxNewLogin)

Benefits

PyPanther Detections have the following benefits:

  • No upstream merge conflicts: In the v1 model, merge conflicts can arise when syncing your customized fork of panther-analysis with the upstream repository. In this PyPanther model, Panther-managed rules exist separately from your rule configurations, eliminating the possibility of merge conflicts.

  • Full flexibility and composability: This feature offers complete flexibility in rule creation, enabling full modularity, composability, the ability to override any rule attribute, and full Python inheritance—all providing a customizable and user-centric experience.

  • First-class developer experience: Backed by a portable, open-source Python library called pypanther, this framework provides a superior local development experience by hooking into native applications and developer workflows. This library can also be loaded into any Python environment, such as Jupyter Notebooks.

PyPanther Detections vs. v1 detections

This PyPanther Detections documentation uses the term "v1 detections"—this refers to rules created in the format described in Writing Python Detections. PyPanther Detections are sometimes referred to as "v2 detections."

PyPanther Detections differ from v1 detections in the following areas:

  • File structure: A rule in the v1 framework requires two files: a Python file to define rule logic and dynamic alerting functions and a YAML file to set metadata. A PyPanther rule is written entirely in Python.

    • This singular rule definition in a Python class—which contains all functions, properties, and helpers—enables overrides and composability.

  • Process for retrieving Panther-managed detections: In v1 detections, you must periodically sync your copy of panther-analysis with upstream changes. With PyPanther Detections, however, no Git syncing is required—the latest Panther-managed content is always available in the pypanther Python library.

  • Packs: Panther-managed v1 detections are bundled in Detection Packs. With PyPanther Detections, you can choose which detections you want to include in your Panther instance using get_panther_rules() (or direct imports) with register().

Panther has developed a tool that translates detections from v1 to PyPanther format.

The same detection, Box.New.Login is defined below in both versions:

Limitations of PyPanther Detections

PyPanther Detections are currently designed for real-time rules developed in the CLI workflow.

While PyPanther Detections are evolving rapidly, they currently have the following limitations:

Getting started using PyPanther Detections

Panther has provided this pypanther-starter-kit repository, containing PyPanther Detection examples, which you can clone to quickly get up and running.

Get started by following the setup instructions in the repository's README.

Creating PyPanther Detections

Before writing PyPanther Detections, you’ll need to set up your environment. See Getting started using PyPanther Detections, above.

When working with PyPanther Detections:

  • A main.py file controls your entire detection configuration, outlining which rules to register, override configurations, and custom rule definitions. You can either:

    • (Recommended) Define your detections in various other files/folders, then import them into main.py

    • Define your detections in main.py

  • A PyPanther rule is defined in a single Python file. Within it, you can import Panther-managed (or your own custom) PyPanther rules and specify overrides. A single Python file can define multiple detections.

  • All PyPanther rules subclass the pypanther Rule class or a parent class of type Rule.

  • Rules must be registered to be tested and uploaded to your Panther instance.

  • All event object functions currently available in v1 detections are available in PyPanther Detections. These include: get(), deep_get(), deep_walk(), and udm().

  • All alert functions available in Python (v1) detections are available in PyPanther Detections, such as title() and severity(). See Rule auxiliary/alerting function reference.

Writing a custom PyPanther Detection

A "custom" PyPanther rule is one that you write completely from scratch—i.e., one that isn't built from a Panther-managed rule. Custom PyPanther rules are defined in a Python class that subclasses the pypanther Rule class. In this class, you must:

  • Define a rule() function

  • Define certain attributes, such as log_types

    • (Optional) Define additional attributes, such as threshold or dedup_period_minutes

The id attribute is only required for a rule if you plan to register it.

See the Rule property reference section for a full list of required and optional fields.

from pypanther import Rule, Severity, LogType

# Custom rule for a Panther-supported log type
class MyCloudTrailRule(Rule):
    id = "MyCloudTrailRule"
    tests = True
    log_types = [LogType.AWS_CLOUDTRAIL]
    default_severity = Severity.MEDIUM
    threshold = 50
    dedup_period_minutes = 1

    def rule(self, event) -> bool:
        return (
	    event.get("eventType") == "AssumeRole" and 
	        400 <= int(event.get("errorCode", 0)) <= 413
	)

Importing Panther-managed rules

Panther-managed rules can be imported directly or using the get_panther_rules() function.

Panther-managed rules currently all have a -prototype suffix (e.g., AWS.Root.Activity-prototype). This is temporary, and will be removed in the future.

You may want to import Panther-managed rules (into main.py or another file) to either register them individually as-is, set overrides on them, or subclass them. You can import Panther-managed rules directly (from the pypanther.rules module) or by using the get_panther_rules() function.

To import a Panther-managed rule directly using the rules module, you would use a statement like:

from pypanther.rules.github_rules.github_advanced_security_change import GitHubAdvancedSecurityChange

The get_panther_rules() function can filter on any Rule class attribute, such as default_severity, log_types, or tag. When filtering, keys use AND logic, and values use OR logic.

Get all Panther-managed rules using get_panther_rules():

from pypanther import get_panther_rules

all_rules = get_panther_rules()

Get Panther-managed rules with certain severities using get_panther_rules():

from pypanther import get_panther_rules, Severity

important_rules = get_panther_rules(
    default_severity=[
        Severity.HIGH,
        Severity.CRITICAL,
    ]
)

Get Panther-managed rules for certain log types using get_panther_rules():

from pypanther import get_panther_rules, LogType

cloudtrail_okta_rules = get_panther_rules(
    log_types=[
        LogType.AWS_CLOUDTRAIL,
        LogType.OKTA_SYSTEM_LOG
    ]
)

Get Panther-managed rules that meet multiple criteria using get_panther_rules():

from pypanther import get_panther_rules, Severity

rules_i_care_about = get_panther_rules(
    enabled=True,
    default_severity=[Severity.CRITICAL, Severity.HIGH],
    tags=["Configuration Required"],
)

See Using list comprehension for an example of how to use get_panther_rules() with advanced Python.

Once you’ve imported a Panther-managed rule, you can modify it using inheritance or overrides.

Creating include or exclude filters

PyPanther Detection filters let you exclude certain events from being evaluated by a rule. Filters are designed to be applied on top of existing rule logic (likely for Panther-managed PyPanther Detections you are importing).

Each filter defines logic that is run before the rule() function, and the outcome of the filter determines whether or not the event should go on to be evaluated by the rule.

Common use cases for filters include:

  • To target only certain environments, like prod

  • To exclude events that are known false positives, due to a misconfiguration or other non-malicious scenario

There are two types of filters:

  • include filters: If the filter returns True for an event, the event is evaluated by rule()

  • exclude filters: If the filter returns True for an event, the event is dismissed (i.e., not evaluated by rule())

include and exclude, which can be imported from the pypanther.wrap module, can run as standalone functions or as rule class decorators.

Examples as standalone functions:

from pypanther.wrap import include
from pypanther.rules.github_rules.github_advanced_security_change import GitHubAdvancedSecurityChange

# Include only repos that are production
prod_repos = ["prod_repo1", "prod_repo2"]
include(lambda e: e.get("repo") in prod_repos)(GitHubAdvancedSecurityChange)
from pypanther.wrap import exclude
from pypanther.rules.box_rules.box_policy_violation import BoxContentWorkflowPolicyViolation

# Exclude accounts that are for development
dev_repos = ["dev_repo1", "dev_repo2"]
exclude(lambda e: e.get("repo") in dev_repos)(GitHubAdvancedSecurityChange)

Example as rule class decorators:

from pypanther.wrap import include, exclude
from pypanther.rules.github_rules.github_advanced_security_change import GitHubAdvancedSecurityChange

# In a real-world scenario, likely only one of the below would be necessary
@include(lambda e: e.get("repo") in prod_repos)
@exclude(lambda e: e.get("repo") in dev_repos)
class GitHubAdvancedSecurityChangeOverride(GitHubAdvancedSecurityChange):
    id = "GitHubAdvancedSecurityChangeOverride"
    ...

Filters can also be reused with a for loop to decorate multiple rules:

from pypanther.wrap import include

rules = [
    # Panther-managed and custom rules
    ...
]

def prod_filter(event):
    return event.get("repo") in prod_repos
		
for rule in rules:
    include(prod_filter)(rule)

Applying overrides on existing rules

If your objective is to modify a rule's logic, it's recommended to use include/exclude filters instead of overriding the rule() function itself. Learn more in Use filters instead of overriding rule().

Overriding single attributes

You can override a rule’s attributes with a one-line statement:

from pypanther import Severity
from pypanther.rules.aws_cloudtrail_rules.aws_cloudtrail_created import AWSCloudTrailCreated

# Set rule severity to High
AWSCloudTrailCreated.Severity = Severity.HIGH

Overriding multiple attributes with the override function

It’s also possible to configure multi-line overrides with the override() function:

from pypanther import Severity
from pypanther.rules.box_rules.box_policy_violation import BoxContentWorkflowPolicyViolation

BoxContentWorkflowPolicyViolation.override(
    default_severity=Severity.HIGH,
    default_runbook="Check if other internal users hit this same violation"
)

Applying overrides on multiple PyPanther rules

To apply overrides on multiple rules at once, iterate over the collection using a for loop.

This could be useful, for example, when updating a certain attribute for all rules associated to a certain LogType.

from pypanther import get_panther_rules, Severity, LogType

rules = get_panther_rules(
    enabled=True,
    default_severity=[Severity.CRITICAL, Severity.HIGH],
    tags=["Configuration Required"],
)

# Define the destination [override](<https://docs.panther.com/detections/rules/python#destinations>)
def aws_cloudtrail_destinations(self, event):
    if event.get('recipientAccountId') == 112233445566:
        # Name or UUID of a configured Slack Destination
        return ['AWS Notifications']
    # Suppress the alert, doesn't deliver
    return ['SKIP']

# Appending to the Panther-managed rules' destinations and tags
for rule in rules:
    rule.default_destinations.append("Slack #security")
    rule.tags.append("Production")
		
    # Updating the destinations for CloudTrail rules
    if LogType.AWS_CLOUDTRAIL in rule.log_types:
        rule.destinations = aws_cloudtrail_destinations

Ensuring necessary fields are set on configuration-required rules

Panther-managed rules that require some customer configuration before they are uploaded into a Panther environment may include a validate_config() function, which defines one or more conditions that must be met for the rule to pass the test command (and function properly).

Most commonly, validate_config() verifies that some class variable, such as an allowlist or denylist, has been assigned a value. If the requirements included in validate_config() are not met, an exception will be raised when the pypanther test command is run (if the rule is registered).

Example:

class ValidateMyRule(Rule):
    id = "Validate.MyRule"
    log_types = [LogType.PANTHER_AUDIT]
    default_severity = Severity.HIGH

    allowed_domains: list[str] = []

    def rule(self, event):
        return event.get("domain") not in self.allowed_domains

    @classmethod 
    def validate_config(cls):
        assert (
            len(cls.allowed_domains) > 0
        ), "The allowed_domains field on your rule must be populated"

In this example, if allowed_domains is not assigned a non-empty list, an assertion error will be thrown during pypanther test.

To set this value, you can use a statement like:

ValidateMyRule.allowed_domains = ["example.com"]

Creating PyPanther rules with inheritance

You can use inheritance to create rules that are subclasses of other rules (that are Panther-managed or custom).

It’s recommended to use inheritance when you’re creating a collection of rules that all share a number of characteristics—for example, rule() function logic, property values, class variables, or helper functions. In this case, it’s useful to create a base rule that all related rules inherit from.

For example, it may be useful to create a base rule for each LogType, from which all rules for that LogType are extended.

Inheritance is commonly used with filters—i.e., subclassed rules can define additional criteria an event must meet in order to be processed by the rule.

If you don’t plan to register a base rule, it’s not required to provide it an id property.

Example:

# Custom rule for a custom log type — the parent rule
class HostIDSBaseRule(Rule):
    # id not necessary since we're not uploading this parent rule
    log_types = ['Custom.HostIDS']
    default_severity = Severity.HIGH
    threshold = 1
    dedup_period_minutes = 6 * 60 # 6 hours

    def rule(self, event) -> bool:
        return event.get('event_name') == 'confirmed_compromise'
    
    def host_user_lookup(self, hostname):
	return 'groot'
		
    def title(self, event): -> str:
	return f"Confirmed compromise from hostname {event.get('hostname')}"
		
    def alert_context(self, event):
	user = self.host_user_lookup(event.get('hostName') 
	return {
	    'hostname': event['hostName'],
	    'time': event['p_event_time'],
	    'user': user,
	}
# Inherited rule #1

# Filter on event_type (in addition to base rule function)
@include(lambda e: e.get('event_type') == 'c2')
class IDSCommandAndControl(HostIDSBaseRule):
    id = 'IDSCommandAndControl'
    threshold = 19
    
    def title(self, event):
	return f"Confirmed c2 on host {event.get('hostname')}"
	
    # From parent rule, inherits rule(), alert_context(), log_types, severity, and dedup_period_minutes
    # From PantherRule, inherits other fields (like Enabled)
# Inherited rule #2

# Filter on event_type (in addition to base rule function)
@include(lambda e: e.get('event_type') == 'malware')
class IDSCommandAndControl(HostIDSBaseRule):
    id = 'HostIDSMalware'
    threshold = 2
    default_severity = Severity.CRITICAL

    def title(self, event):
	return f"Confirmed malware on host {event.get('hostname')}"
    
    # From parent rule, inherits rule(), alert_context(), log_types, and dedup_period_minutes
    # From PantherRule, inherits other fields (like enabled)

Using advanced Python

Because PyPanther rules are fully defined in Python, you can use its full expressiveness when customizing your detections.

Calling super()

For more advanced use cases, you can supplement the logic in functions defined by the parent rule.

# Creating an inherited rule
class MyRule(AnExistingRule):
    def alert_context(self, event):
	# Preserve the parent rule's alert context and extend with a new field
	context = super().alert_context(event)
	context["new field"] = "new_value"
	return context
				
    def severity(self, event):
	# Conditionally increment the parent rule's severity
	if event.get("env") == "prod":
	    return Severity.CRITICAL
	return super().severity(event)

Using list comprehension

You can use Python’s list comprehension functionality to create a new list based on an existing list with condensed syntax. This may be particularly useful when you want to filter a list of detections fetched using get_panther_rules().

# Collection of rules that have more than one LogType
rules = [rule for rule in get_panther_rules() if len(rule.log_types) > 1]
					
# Collection of rules that do not require configuration
rules = [rule for rule in get_panther_rules() if "Configuration Required" not in rule.tags]

Registering PyPanther Detections

Registering a PyPanther rule means including it in your Panther deployment package.

To register a rule, pass it in to register() in your main.py file. When you run the pypanther upload or test commands, only rules passed in to register() will be uploaded to your Panther instance or tested.

If a previously uploaded rule is not passed in to register() on a subsequent invocation of upload, it will be deleted in your Panther instance.

Registering a single rule more than once (perhaps because it’s included in multiple collections, which are all passed into register()) will not result in an error.

It’s not required to register rules used as base rules with inheritance so long as you do not want the base rules themselves uploaded into your Panther instance.

# Sample main.py file

from pypanther import register, get_panther_rules

# Register a single rule (that was defined as a class called "BoxNewLogin")
register(BoxNewLogin)

# Register all Panther-managed rules
register(get_panther_rules())

Viewing registered rules

  • To see all rules that are registered given your currently configured repository, run the pypanther list rules CLI command.

Importing instances of Rule

You can use the get_rules() function to easily fetch rules you might want to register in main.py. get_rules() takes in an imported package (folder) or module (file) name, and returns all rules from that package or module that inherit the pypanther Rule class.

Each folder containing rules imported with get_rules() must contain an __init__.py file. Learn more about recommended repository structure in the PyPanther Detections Style Guide.

Example using get_rules():

# main.py
import custom_rules

all_my_rules = get_rules(custom_rules)

register(all_my_rules)

Registering vs. enabling a rule

All rules have an enabled property, which is different from being registered. See the table below for all possible outcomes:

Testing PyPanther Detections

Defining tests

Tests for PyPanther Detections are defined by creating instances of the pypanther RuleTest class.

Each instance of RuleTest must set a name, expected_result, and log. Each test can also optionally define:

  • Additional fields (prepended with expected_) that verify the output of alert functions. For example, expected_severity and expected_title.

  • A mocks field, which takes a list of RuleMocks.

See a full list of available fields in the RuleTest property reference.

my_rule_tests: List[RuleTest] = [
    RuleTest(
	name="RuleShouldReturnTrue"
	expected_result=True,
	log={
	    "name":"value"
	}
    ),
    RuleTest(
	name="RuleShouldReturnFalse"
	expected_result=False,
	log={
	    "name":"value"
	}
    )
]

Tests are associated with rules by assigning them to a rule’s tests field. Tests can be defined directly within a rule, or separately set to a variable (that is either local or imported).

Example

Note that this rule's tests (defined above the rule class) use mocks, expected_title, expected_dedup, and expected_alert_context.

Example: Rule with tests
from pypanther import LogType, Rule, RuleMock, RuleTest, Severity, panther_managed
from pypanther.helpers.panther_base_helpers import deep_get
from pypanther.helpers.panther_default import lookup_aws_account_name
from pypanther.helpers.panther_oss_helpers import geoinfo_from_ip_formatted

aws_console_root_login_tests: list[RuleTest] = [
    RuleTest(
        name="Successful Root Login",
        expected_result=True,
        expected_title="AWS root login detected from [111.111.111.111] (111.111.111.111 in SF, California in USA) in account [sample-account]",
        expected_dedup="123456789012-ConsoleLogin-2019-01-01T00:00:00Z",
        expected_alert_context={
            "sourceIPAddress": "111.111.111.111",
            "userIdentityAccountId": "123456789012",
            "userIdentityArn": "arn:aws:iam::123456789012:root",
            "eventTime": "2019-01-01T00:00:00Z",
            "mfaUsed": "No",
        },
        mocks=[
            RuleMock(object_name="geoinfo_from_ip_formatted", return_value="111.111.111.111 in SF, California in USA")
        ],
        log={
            "eventVersion": "1.05",
            "userIdentity": {
                "type": "Root",
                "principalId": "1111",
                "arn": "arn:aws:iam::123456789012:root",
                "accountId": "123456789012",
                "userName": "root",
            },
            "eventTime": "2019-01-01T00:00:00Z",
            "eventSource": "signin.amazonaws.com",
            "eventName": "ConsoleLogin",
            "awsRegion": "us-east-1",
            "sourceIPAddress": "111.111.111.111",
            "userAgent": "Mozilla",
            "requestParameters": None,
            "responseElements": {"ConsoleLogin": "Success"},
            "additionalEventData": {
                "LoginTo": "https://console.aws.amazon.com/console/",
                "MobileVersion": "No",
                "MFAUsed": "No",
            },
            "eventID": "1",
            "eventType": "AwsConsoleSignIn",
            "recipientAccountId": "123456789012",
        },
    ),
    RuleTest(
        name="Non-Login Event",
        expected_result=False,
        expected_title="AWS root login detected from [111.111.111.111] (111.111.111.111 in SF, California in USA) in account [sample-account]",
        expected_dedup="123456789012-DescribeTable-2019-01-01T00:00:00Z",
        expected_alert_context={
            "sourceIPAddress": "111.111.111.111",
            "userIdentityAccountId": "123456789012",
            "userIdentityArn": "arn:aws:sts::123456789012:user/tester",
            "eventTime": "2019-01-01T00:00:00Z",
            "mfaUsed": None,
        },
        mocks=[
            RuleMock(object_name="geoinfo_from_ip_formatted", return_value="111.111.111.111 in SF, California in USA")
        ],
        log={
            "eventVersion": "1.06",
            "userIdentity": {
                "type": "AssumedRole",
                "principalId": "1111:tester",
                "arn": "arn:aws:sts::123456789012:user/tester",
                "accountId": "123456789012",
                "accessKeyId": "1",
                "sessionContext": {
                    "sessionIssuer": {
                        "type": "Role",
                        "principalId": "1111",
                        "arn": "arn:aws:iam::123456789012:user/tester",
                        "accountId": "123456789012",
                        "userName": "tester",
                    },
                    "attributes": {"creationDate": "2019-01-01T00:00:00Z", "mfaAuthenticated": "true"},
                },
            },
            "eventTime": "2019-01-01T00:00:00Z",
            "eventSource": "dynamodb.amazonaws.com",
            "eventName": "DescribeTable",
            "awsRegion": "us-west-2",
            "sourceIPAddress": "111.111.111.111",
            "userAgent": "console.amazonaws.com",
            "requestParameters": {"tableName": "table"},
            "responseElements": None,
            "requestID": "1",
            "eventID": "1",
            "readOnly": True,
            "resources": [{"accountId": "123456789012", "type": "AWS::DynamoDB::Table", "ARN": "arn::::table/table"}],
            "eventType": "AwsApiCall",
            "apiVersion": "2012-08-10",
            "managementEvent": True,
            "recipientAccountId": "123456789012",
        },
    ),
]


@panther_managed
class AWSConsoleRootLogin(Rule):
    id = "AWS.Console.RootLogin-prototype"
    display_name = "Root Console Login"
    dedup_period_minutes = 15
    log_types = [LogType.AWS_CLOUDTRAIL]
    tags = [
        "AWS",
        "Identity & Access Management",
        "Authentication",
        "DemoThreatHunting",
        "Privilege Escalation:Valid Accounts",
    ]
    reports = {"CIS": ["3.6"], "MITRE ATT&CK": ["TA0004:T1078"]}
    default_severity = Severity.HIGH
    default_description = "The root account has been logged into."
    default_runbook = "Investigate the usage of the root account. If this root activity was not authorized, immediately change the root credentials and investigate what actions the root account took.\n"
    default_reference = "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html"
    summary_attributes = ["userAgent", "sourceIpAddress", "recipientAccountId", "p_any_aws_arns"]
    tests = aws_console_root_login_tests

    def rule(self, event):
        return (
            event.get("eventName") == "ConsoleLogin"
            and deep_get(event, "userIdentity", "type") == "Root"
            and (deep_get(event, "responseElements", "ConsoleLogin") == "Success")
        )

    def title(self, event):
        ip_address = event.get("sourceIPAddress")
        return f"AWS root login detected from [{ip_address}] ({geoinfo_from_ip_formatted(ip_address)}) in account [{lookup_aws_account_name(event.get('recipientAccountId'))}]"

    def dedup(self, event):
        # Each Root login should generate a unique alert
        return "-".join([event.get("recipientAccountId"), event.get("eventName"), event.get("eventTime")])

    def alert_context(self, event):
        return {
            "sourceIPAddress": event.get("sourceIPAddress"),
            "userIdentityAccountId": deep_get(event, "userIdentity", "accountId"),
            "userIdentityArn": deep_get(event, "userIdentity", "arn"),
            "eventTime": event.get("eventTime"),
            "mfaUsed": deep_get(event, "additionalEventData", "MFAUsed"),
        }

Running tests

To run all tests defined for your PyPanther Detections, run:

$ pypanther test

To run only a subset of tests, filter the detections for which tests are run by using a filter flag with test, such as --id or --log-types. See a full list of filter flags by running pypanther test --help.

The test command:

  • Only tests those detections passed into register()

  • Skips tests for Panther-managed rules

If any rules fail a test, the error will print next to the rule name that was tested:

MyRuleNameI:
   FAIL: my test name
     - Expected rule() to return 'True', but got 'False'

Testing custom helper functions and data fixtures

The pypanther test command tests all PyPanther Detection classes that have a tests attribute set. In addition to testing rule() and alert function output in this way, if you have created custom helper functions for use in rules, you may want to write targeted tests for these helper functions. To do this, it's recommended to use a common Python testing framework, such as pytest or unittest.

Currently, pypanther will not run these tests during pypanther test, but they can be run locally or as part of your CI/CD workflow.

Example: using pytest to test a custom function

Say you'd like to write a reusable function that reads a list of AWS account IDs from a file and filters it to include only the production ones. (This function could then be used in an include or exclude filter.) This function might look like the following:

import pandas as pd

# A sample list of account data you may use with your detections
_account_data = [
        {"account_id": "012345678901", "account_age_days": 1543, "environment": "prod"},
        {"account_id": "112345678901", "account_age_days": 1753, "environment": "staging"},
        ...
        {"account_id": "756239201432", "account_age_days": 32, "environment": "development"}
        ]

# Load account data into a pandas dataframe for easy access
AWS_ACCOUNTS = pd.DataFrame.from_dict(_account_data) 

def is_prod_aws_account(account_id: str) -> bool:
    """
    Checks the AWS_ACCOUNTS dataframe to see if an account_id is in production
    """
    return AWS_ACCOUNTS.loc[AWS_ACCOUNTS['account_id'] == account_id, "environment"] == "prod"

Given this function, there are a few ways in which you may want to test both the data fixture (AWS_ACCOUNTS) itself, as well as the function is_prod_aws_account(). For instance:

  • To verify that the AWS_ACCOUNTS data fixture:

    • Has a certain number of rows

    • Has a certain required field

  • To verify that certain account IDs are included in the prod list (and others are not)

To test these characteristics using pytest, you would add the following functions (all with the test_ prefix):

def test_accounts_metadata_is_correct_size():
    """
    Ensure that the account list has 100 rows.
    """
    assert AWS_ACCOUNTS.shape[0] == 100

def test_critical_list_is_marked_prod():
    """
    Ensure that specific accounts are marked as production while other ones are not
    """
    expected_prod_list = ["012345678901", "012345678902", "012345678903"]
    for account_id in expected_prod_list:
        assert is_prod_aws_account(account_id)
    
    expected_non_prod_list = ["012345678905", "012345678906", "012345678907"]
    for account_id in expected_non_prod_list:
        assert not is_prod_aws_account(account_id)

def test_accounts_metadata_has_account_age_field():
    """
    Ensure the metadata data fixture has a field we may require for another helper function
    """
    assert "account_age_days" in AWS_ACCOUNTS.columns

After you define these tests, you can invoke them by running pytest from your command line.

Uploading PyPanther Detections to Panther

In order to use the pypanther upload functionality, it must first be enabled for you. If you would like to upload detections, please reach out to your Panther Support team.

To upload all PyPanther Detections that are registered, run:

$ pypanther upload

You must authenticate when using upload—see Authenticating CLI commands.

You can see all upload options by running pypanther upload -h, but may find the following options particularly useful:

  • --verbose: Generates verbose output, which includes a list of tests by detection (and their pass/fail statuses), a list of registered detections, and a list of included files

  • --output {text, json}: Prints output in the provided format

    • text is the default value, but json can be useful if you plan to port the output into another workflow

Sample output for pypanther upload --verbose --output json
{
    "result": "UPLOAD_SUCCEEDED",
    "upload_statistics": {
      "rules": {
        "new": 0,
        "total": 569,
        "modified": 569,
        "deleted": 0
      }
    },
    "tests": {
      "test_results": {
        // Only a subset of rule tests are shown below, for conciseness
        "AWS.ECR.EVENTS": [
          {
            "test_name": "Authorized account, unauthorized region",
            "passed": true,
            "exceptions": [],
            "failed_results": []
          },
          {
            "test_name": "Unauthorized account",
            "passed": true,
            "exceptions": [],
            "failed_results": []
          },
          {
            "test_name": "Authorized account",
            "passed": true,
            "exceptions": [],
            "failed_results": []
          }
        ],
        "Osquery.Mac.OSXAttacksKeyboardEvents": [
          {
            "test_name": "App running on Desktop that is watching keyboard events",
            "passed": true,
            "exceptions": [],
            "failed_results": []
          },
          {
            "test_name": "App is running from approved path",
            "passed": true,
            "exceptions": [],
            "failed_results": []
          },
          {
            "test_name": "Unrelated query does not alert",
            "passed": true,
            "exceptions": [],
            "failed_results": []
          }
        ],
        "Dropbox.User.Disabled.2FA": [
          {
            "test_name": "2FA Disabled",
            "passed": true,
            "exceptions": [],
            "failed_results": []
          },
          {
            "test_name": "Other",
            "passed": true,
            "exceptions