PyPanther

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.

Features

• 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

Installation

From PyPI

To install pypanther from PyPI, use pip:

pip install pypanther

From Source

To install from source:

git clone https://github.com/panther-labs/pypanther.git
cd pypanther
pip install -e .

Development Setup

For development, we recommend using Poetry:

1. Install Poetry: Follow the instructions on the Poetry website to install Poetry.

2. Clone and Install:

   git clone [email protected]:panther-labs/pypanther.git
   cd pypanther
   poetry install

3. Activate the Environment:

   poetry shell

Prerequisites

• Python 3.11 or higher
• Panther instance with API access
• Poetry (for development)

Quick Start

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.

Documentation

• User Guide
• Library Reference
• CLI Guide
• Rule Development Guide

Development

Running Tests

poetry run pytest

Code Style

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

Development Guidelines

• 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

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

Architecture

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

License

pypanther is released under Apache License 2.0.

Acknowledgments

• Thanks to all our contributors
• Built with ❤️ by Panther Labs