PyPanther Detections Style Guide
Repository structure recommendations
In your code repository where your PyPanther Detections are stored, it's recommended to:
Maintain a top-level module,
content, in which all of your custom Python code is stored (except for themain.pyfile).The top-level directory we are calling
content/can be named anything exceptsrc/, which is a reserved repository name in Panther.Within this folder, it's recommended to:
Store custom rule definitions in a
rulesdirectory.Store logic that makes overrides on Panther-managed rules in an
overridesdirectory.Define an
apply_overridesfunction in each file inoverrides.
Store custom helpers in a
helpersdirectory.
# Recommended repository structure
.
├── README.md
├── content
│ ├── __init__.py
│ ├── helpers
│ │ ├── __init__.py
│ │ ├── cloud.py
│ │ └── custom_log_types.py
│ ├── overrides
│ │ ├── __init__.py
│ │ ├── aws_cloudtrail.py└
│ │ └── aws_guardduty.py
│ ├── rules
│ │ ├── __init__.py
│ │ ├── my_custom_rule.py
│ │ └── my_inherited_rule.py
│ └── schemas
│ └── schema1.yml
└── main.pymain.py content recommendations
main.py content recommendationsIt's recommended for your main.py file to:
Import Panther-managed rules (which you do or don't want to make overrides on) using
get_panther_rulesIf you defined
apply_overridesfunctions, callpypanther'sapply_overrides()to apply all of your changes. Learn more in Callapply_overrides(), below.
Import custom rules using
get_rules
# Example main.py file
from pypanther import get_panther_rules, get_rules, register, apply_overrides
from content import rules, overrides
from content.helpers.custom_log_types import CustomLogType
# Load base rules
base_rules = get_panther_rules(
# log_types=[
# LogType.AWS_CLOUDTRAIL,
# LogType.AWS_GUARDDUTY,
# LogType.PANTHER_AUDIT,
# ],
# default_severity=[
# Severity.CRITICAL,
# Severity.HIGH,
# ],
)
# Load all local custom rules
custom_rules = get_rules(module=rules)
# Omit rules with custom log types, since they must be present in the Panther instance for upload to work
custom_rules = [rule for rule in custom_rules if not any(custom in rule.log_types for custom in CustomLogType)]
# Apply overrides
apply_overrides(module=overrides, rules=base_rules)
# Register all rules
register(base_rules + custom_rules)Call apply_overrides()
apply_overrides()The pypanther apply_overrides() convenience function lets you, in main.py, efficiently apply all detection overrides made in a separate file or folder.
apply_overrides() takes an imported package (folder) or module (file) name and an optional list of rules, and runs all functions named apply_overrides() from that package or module against the list of rules. (This is similar to how get_rules() works.) It's recommended to name this package or module overrides.
In the following example, the apply_overrides() functions in general.py and aws_cloudtrail.py are applied when apply_overrides(overrides, all_rules) is called in main.py:
# main.py
import overrides
all_rules = get_panther_rules()
apply_overrides(overrides, all_rules)
register(all_rules)# general.py in /overrides
def apply_overrides(rules):
for rule in rules:
rule.override(enabled=True)# aws_cloudtrail.py in /overrides
from pypanther import Severity
from pypanther.rules.aws_cloudtrail import AWSCloudTrailStopped
def apply_overrides(rules):
AWSCloudTrailStopped.override(
default_severity=Severity.LOW,
default_runbook=(
"If the account is in production, investigate why CloudTrail was stopped. "
"If it was intentional, ensure that the account is monitored by another CloudTrail. "
"If it was not intentional, investigate the account for unauthorized access."
),
)Best practices for PyPanther Detection writing
Use filters instead of overriding rule()
rule() If you would like to alter the logic of a Panther-managed PyPanther Detection, it's recommended to use include/exclude filters instead of overriding the rule's rule() function. Filters are designed for this purpose—to be applied on top of existing rule logic. They are executed against each incoming event before the rule() logic, in order to determine if the rule should indeed process the event.
If you are significantly altering the rule logic, you might also consider writing a custom rule instead.
Use upgrade() or downgrade() in severity()
upgrade() or downgrade() in severity()While each PyPanther rule must define a default_severity, it can also define a severity() function, whose value overrides default_severity to set the severity level of resulting alerts.
Within severity(), it's common practice to dynamically set the severity based on an event field value. One way to do this is to add some condition, which, if satisfied, returns a hard-coded Severity value. In the example below, if the actor associated to the event has an admin role, Severity.MEDIUM is returned, regardless of the value of self.default_severity:
# Example NOT using upgrade() or downgrade()
class MyRule(Rule):
...
default_severity = Severity.LOW
...
def severity(self, event):
if event.deep_get("actor", "role") == "admin":
return Severity.MEDIUM # returns MEDIUM
return self.default_severity # returns LOWIn the example above, if MyRule's default_severity was ever changed from Severity.LOW to, say, Severity.MEDIUM, you would also need to remember to update the Severity.MEDIUM in severity() (presumably to Severity.HIGH), to preserve the escalation.
Using upgrade() instead of hard-coding a Severity
upgrade() instead of hard-coding a SeverityInstead of setting the return value of severity() as a hard-coded Severity value (as is shown in the example above), it's recommended to call the Severity class's upgrade() and downgrade() functions on self.default_severity.
In this model, if your detection's default_severity value ever changes, you won't also need to make changes in the severity() function. In the example below, default_severity has been changed to Severity.MEDIUM, and the return value within the condition automatically adjusts to returning Severity.HIGH because it uses upgrade():
# Example using upgrade()
class MyRule(Rule):
...
default_severity = Severity.MEDIUM
...
def severity(self, event):
if event.deep_get("actor", "role") == "admin":
return self.default_severity.upgrade() # returns HIGH
return self.default_severity # returns MEDIUMIn order to use self.default_severity.upgrade() or self.default_severity.downgrade(), the detection's default_severity value must be a Severity object, not a string literal.
There may be rare instances when using a static value within severity() is preferable—for example, you may always want to return Severity.INFO when an event originates in a dev account, even if the default_severity later changes. This might look like:
def severity(self, event):
if is_dev_env(event.get("accountId")):
return Severity.INFO
return self.default_severityOptionally use explicit typing
The pypanther base Rule class is typed, so when you create a custom detection (i.e., inherit from Rule), explicit typing is optional. Still, if you prefer to use explicit types, you can do so.
Last updated
Was this helpful?