pypanther is a Python framework for writing detection rules with Panther. It provides an intuitive interface for creating, managing, and deploying detections to enhance your security operations. Included is a pypanther
CLI tool to interact with your content and upload it to a Panther instance.
- Rule Creation: Easily create rules using Python classes and inheritance
- Type Safety: Built with type hints for better IDE support and code quality
- Testing Framework: Built-in testing utilities for rule validation
- CLI Tool: Command-line interface for managing and deploying rules
- Helper Functions: Common security detection patterns and utilities
- Log Type Support: Native support for major cloud and security log types
To install pypanther from PyPI, use pip:
pip install pypanther
To install from source:
git clone https://github.com/panther-labs/pypanther.git
cd pypanther
pip install -e .
For development, we recommend using Poetry:
-
Install Poetry: Follow the instructions on the Poetry website to install Poetry.
-
Clone and Install:
git clone [email protected]:panther-labs/pypanther.git cd pypanther poetry install
-
Activate the Environment:
poetry shell
- Python 3.11 or higher
- Panther instance with API access
- Poetry (for development)
Here is a simple main.py
to get you started with development. Place this in the base directory:
from pypanther import get_panther_rules, register
register(get_panther_rules())
$ poetry run pypanther list rules --log-types Panther.Audit
+-------------------------------------+---------------+------------------+---------+
| id | log_types | default_severity | enabled |
+-------------------------------------+---------------+------------------+---------+
| Panther.Detection.Deleted-prototype | Panther.Audit | INFO | True |
| Panther.SAML.Modified-prototype | Panther.Audit | HIGH | True |
| Panther.Sensitive.Role-prototype | Panther.Audit | HIGH | True |
| Panther.User.Modified-prototype | Panther.Audit | HIGH | True |
+-------------------------------------+---------------+------------------+---------+
For more detailed examples and implementation patterns, check out the pypanther-starter-kit.
poetry run pytest
We use ruff
for code formatting and linting, and mypy
for type checking. To format and lint your code:
# Format code
poetry run ruff format .
# Check and fix imports
poetry run ruff check --select I --fix .
# Run all linting checks
poetry run ruff check --fix .
# Run type checking
poetry run mypy .
You can also use the provided Makefile commands:
# Format code and fix imports
make fmt
# Run all linting and type checking
make lint
- Follow PEP 8 style guide
- Use
ruff
for code formatting and linting - Use
mypy
for type checking - Add tests for new features
- Update documentation as needed
- Keep commits clean and well-documented
- Add type hints to all new code
This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.
PyPanther is built with the following design principles:
- Modularity: Rules are self-contained and easily composable
- Type Safety: Comprehensive type hints for better development experience
- Extensibility: Easy to add new rule types and log sources
- Testability: Built-in testing framework for rule validation
pypanther is released under Apache License 2.0.
- Thanks to all our contributors
- Built with ❤️ by Panther Labs