PyPanther Detections (Beta)
Configure detections fully in Python
Overview
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 open-source pypanther
Python library.
Learn about PyPanther key features, benefits, and differences from the v1 detection format on this page—then, start creating PyPanther Detections in the CLI workflow or the Panther Console.
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: Working in the CLI workflow in the v1 model, merge conflicts can arise when syncing your customized fork of
panther-analysis
with the upstream repository. In PyPanther, Panther-managed rules exist separately from your rule configurations, eliminating the possibility of merge conflicts.Full flexibility and composability: PyPanther 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,
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
PyPanther Detections differ from v1 detections in the following areas:
File structure: Working in the CLI workflow, 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 a single Python class containing all functions, properties, and helpers.
Process for retrieving Panther-managed detections: In v1 detections, you must periodically sync your copy of
panther-analysis
with upstream changes. With PyPanther Detections, no Git syncing is required—the latest Panther-managed content is always available in thepypanther
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) withregister()
.
The same detection, Box.New.Login
is defined below in both versions:
# 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
While PyPanther Detections are evolving rapidly, they currently have the following limitations:
(Planned) It’s not possible to define new custom Lookup Tables.
It is possible to reference data from existing custom Lookup Tables, as well as Panther-managed Enrichment Providers.
(Planned) No support for Policies, Scheduled Rules, Simple Rules, Correlation Rules.
Only rules (or “real-time rules”) are supported in the PyPanther framework.
(Planned) It’s not possible to use Data Replay in the CLI or Console workflows.
(Planned) It’s not possible to define your own data models.
It is possible to reference Panther-managed data models in the
pypanther
library, usingevent.udm()
.
Library version pinning and declaring custom dependencies from the repository are not supported.
The CLI tool used with PyPanther Detections,
pypanther
, does not have all of the commandspanther_analysis_tool
does.See a list of available
pypanther
commands on Using the pypanther CLI Tool.
There are additional limitations on the functionality of the
upload
command. See theupload
limitations section.There are additional limitations when managing PyPanther Detections in the Panther Console. See the Console limitations section.
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 in the CLI workflow on Creating PyPanther Detections or in the Panther Console on Managing PyPanther Detections in the Panther Console.
Contribute to pypanther
The pypanther
library is open source, and welcomes contributions. Please see CONTRIBUTING.md for contribution guidelines.
Last updated
Was this helpful?