Knowledge BaseCommunityRelease NotesRequest Demo

PyPanther Detections (Beta)

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.

Learn about PyPanther key features, benefits, and differences from the v1 detection format on this page—then, start creating PyPanther Detections.

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 import BoxNewLogin

  • The ability to apply custom configurations to Panther-managed rules through overrides, filters, and inheritance.

    from pypanther import Severity

# 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
BoxNewLogin.extend(
    exclude_filters=[lambda e: e.deep_get('created_by', 'name') == 'Alice'],
)

  • 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 documentation uses the term "v1 detections," which refers to rules created in the format described in Writing Python Detections. PyPanther Detections are sometimes referred to as "v2 detections."

Panther has developed a tool that translates detections from v1 to PyPanther format—see the convert command on Using the pypanther Command Line Tool.

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().

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

v1 Box New Login rule
PyPanther Box New Login rule

# box_new_login.py

from panther_base_helpers import deep_get

def rule(event):
    return event.get("event_type") == "ADD_LOGIN_ACTIVITY_DEVICE"

def title(event):
    return (
        f"User [{deep_get(event, 'created_by', 'name', default='<UNKNOWN_USER>')}] "
        f"logged in from a new device."
    )
# box_new_login.yml

AnalysisType: rule
Filename: box_new_login.py
RuleID: "Box.New.Login"
DisplayName: "Box New Login"
Enabled: true
LogTypes:
  - Box.Event
Tags:
  - Box
  - Initial Access:Valid Accounts
Reports:
  MITRE ATT&CK:
    - TA0001:T1078
Severity: Info
Description: A user logged in from a new device.
Reference: <https://support.box.com/hc/en-us/articles/360043691914-Controlling-Devices-Used-to-Access-Box>
Runbook: Investigate whether this is a valid user login.
SummaryAttributes:
  - ip_address
Tests:
	- ...

# box_new_login.py pypanther rule

from pypanther import Rule, Severity, LogType

class BoxNewLogin(Rule):
    id = "Box.New.Login"
    display_name = "Box New Login"
    log_types = [LogType.BOX_EVENT]
    tags = ["Box", "Initial Access:Valid Accounts"]
    reports = {"MITRE ATT&CK": ["TA0001:T1078"]}
    default_severity = Severity.INFO
    default_description = "A user logged in from a new device.\\n"
    default_reference = "<https://support.box.com/hc/en-us/articles/360043691914-Controlling-Devices-Used-to-Access-Box>"
    default_runbook = "Investigate whether this is a valid user login.\\n"
    summary_attributes = ["ip_address"]
    tests = box_new_login_tests # Not shown in the example

    def rule(self, event):
        return event.get("event_type") == "ADD_LOGIN_ACTIVITY_DEVICE"

    def title(self, event):
        return f"User [{event.deep_get('created_by', 'name', default='<UNKNOWN_USER>')}] logged in from a new device."

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

See the 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.

Learn more about how to modify Panther-managed PyPanther Detections and create your own on Creating PyPanther Detections.

PreviousCorrelation Rule ReferenceNextCreating PyPanther Detections

Last updated

Was this helpful?