Today, we are thrilled to announce pypanther, a Python library for scaling SIEM rule management and generating the most contextualized alerts for your organization:
“Pypanther is a revolutionary change to detection as code; A simple solution enabling you to make fast pin-point accurate changes to individual rules along with platform-wide rollouts in one go.”
– Paul Harrison, Mattermost
The pypanther framework offers a practical shift in Detection as Code. Unlike traditional methods that depend on declarative languages like YAML or TOML, pypanther uses Python to express detection rules and their configuration. This approach allows for seamless overrides on top of hundreds of pre-built rules, eliminating the hassle of merge conflicts and applying manual changes.
The result is a more agile and efficient SecOps program, freeing you from the cumbersome task of managing bespoke scripts that attempt to stitch together a detection pipeline. By leveraging Python, teams can accomplish huge feats with simple code, achieving a streamlined, scalable, highly customizable rule management process that keeps your security operations lean and effective.
The pypanther framework was created to help customize built-in SIEM rules while keeping up with the latest updates to Panther-managed detections. SIEMs come with hundreds of built-in rules, but they are typically not specific enough to add value without organizational details like IdP mappings to understand who is performing monitored actions. Users must customize rules themselves, but historically, SIEMs have not made this easy, resulting in lower alert quality or mismatched risk levels.
Most SIEMs supporting Detection as Code use declarative languages like YAML or TOML, but they suffer from GitHub merge conflicts. Customers must create forks of large repositories, and when upstream rules are updated, configurations have to be repeatedly re-applied. Nobody enjoys dealing with large git rebases, not even seasoned developers! pypanther solves these problems by treating SIEM rules like software: programmatic overrides, imports, and simple Python logic for applying mass configurations.
pypanther‘s key features are Pythonic detection management of customizations like overrides, filters, alert routing, streamlined creation of rules, and smooth CI/CD workflows for end-to-end deployment automation.
Previously, Panther used a combination of YAML and Python files to declare a rule. Now, a rule is expressed within a single Python class, enabling robust customization, overrides, and inheritance. Rules encapsulate all metadata, logic, and tests:
Our initial Rule implementation represents real-time streaming analysis. In this particular example, AWS ALB logs would be analyzed for 4xx errors on web ports. Alerts generated would be a Medium severity, which would route to specific destinations by default.
Panther, like many SIEMs, ships with hundreds of these rules. But what if you wanted to change a rule’s severity to HIGH? It’s as simple as just setting it to the new value. With pypanther, you do not need to make a copy of the pre-built rule, and instead, can update it through imports and assignments:
When this code runs, it will apply on top of whatever exists upstream, saving time and management overhead. This logic could also be applied to rules fitting particular criteria, such as tags or log types. Using simple for loops, we can apply this change to as many rules as we want:
Filters are small reusable snippets of analysis that can tune multiple rules simultaneously and greatly reduce alert volumes. Common use cases include filtering out expected behaviors from operations teams with privileged access or ignoring lower-priority behaviors that do not surpass our risk appetite.
With pypanther, reusable filters can be defined and applied as simple Python functions. Events matching these patterns can either be included or excluded and easily be layered on top of rules:
In this example, we exclude any GuardDuty findings tagged as a Discovery tactic, which are typically low priority and can distract teams.
Rules can also be inherited to create multiple variations with additional refined analysis quickly. For example, the code snippet below demonstrates how the AWSALBHighVol400s rule is inherited and extended by AWSALBBots, using a reusable include filter for more specific analysis:
Panther’s alert routing is typically set with default_severity, but this can be more dynamic by attaching a destinations function that routes based on log values. In the example below, if a GuardDuty finding is from the MITRE Discovery tactic, we set a specific alert destination of #slack-low-sev-alerts:
This override calls back to the prior filter we wrote before, reusing our logic and preventing copy/paste. To apply it to our GuardDuty rules, we add one more line to the for loop above:
Using built-in Python primitives, you can mass-apply alert routing to dozens of rules simultaneously!
Keeping track of SIEM rule configurations usually requires a vast collection of YAML files in a large code repository. With pypanther, your local repository only comprises a main.py, custom rules, and overrides.
main.py is the central configuration that specifies which pre-built rules are loaded, which eliminates the need for maintaining copies of rules:
The rules are then added to the register, a function for adding upstream rules to a deployment package. To see what’s in the register, you can run a list command:
% pypanther list rules --registered --attributes id default_severity log_types
+----------------------------------------------------------------+------------------+-------------------------------------+
| id | default_severity | log_types |
+----------------------------------------------------------------+------------------+-------------------------------------+
| AWS.ALB.HighVol400s | MEDIUM | AWS.ALB |
| AWS.CloudTrail.AMIModifiedForPublicAccess | MEDIUM | AWS.CloudTrail |
| AWS.CloudTrail.Account.Discovery | LOW | AWS.CloudTrail |
| AWS.CloudTrail.CodebuildProjectMadePublic | HIGH | AWS.CloudTrail |Code language: SQL (Structured Query Language) (sql)And to see the details of a panther-managed rule, you can run a get command:
% pypanther get rule --id AWS.CloudTrail.AMIModifiedForPublicAccess
class AWSCloudTrailAMIModifiedForPublicAccess(Rule):
log_types = [LogType.AWS_CLOUDTRAIL]
default_severity = Severity.MEDIUM
reports = {"MITRE ATT&CK": ["TA0010:T1537"]}
default_description = "An Amazon Machine Image (AMI) was modified to allow it to be launched by anyone. Any sensitive configuration or application data stored in the AMI's block devices is at risk.\n"
default_runbook = "Determine if the AMI is intended to be publicly accessible. If not, first modify the AMI to not be publicly accessible then change any sensitive data stored in the block devices associated to the AMI (as they may be compromised).\n"
default_reference = "https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/sharingamis-intro.html"
def rule(self, event):
if not aws_cloudtrail_success(event) or event.get("eventName") != "ModifyImageAttribute":
return False
added_perms = deep_get(event, "requestParameters", "launchPermission", "add", "items", default=[])
for item in added_perms:
if item.get("group") == "all":
return True
return False
Code language: Python (python)pypanther is our new CLI tool that replaces the legacy panther_analysis_tool.
Finally, having confidence in your SIEM rules is crucial, and pypanther has a robust test suite to ensure rules behave as expected. Since Python is the basis of this library, sample logs can easily be overwritten or shared across multiple rules. Various rule functions can also be tested to ensure alert titles are properly formatted, in addition to basic tests for triggering alerts:
pypanther provides a powerful, Pythonic approach to SIEM rule management that transforms how SecOps teams work. With programmatic overrides and filters, class-based Python detections, and centralized mass configuration, SecOps teams can fully embrace detection engineering practices for their SIEM rules. This leads to greatly reduced overhead of managing and tuning rules, ultimately enhancing alert quality.
We encourage Panther customers to try out pypanther by visiting our GitHub and following the setup instructions. We will soon be rolling out access to your instance in the coming weeks! Your feedback is crucial to us, so please do not hesitate to reach out on our Community Slack channel.
Our vision is to continue pushing the boundaries of code-driven detection and response so that an everything-as-code approach to security is not just an aspiration, but a reality that reframes how teams operate. This initial milestone is just the beginning: soon pypanther will extend to Correlation Rules, Scheduled Rules, ingestion pipelines, and more to achieve maximum efficiency and accuracy in threat detection and response.
We’re honored to have the Panther community help drive our mission to revolutionize security operations. If you’re interested in joining us on this journey, request a demo to see how Panther can level up your threat detection.
