How panther-labs/pypanther-starter-kit works
Project Type and Purpose
• pypanther-starter-kit is a Python-based detection framework and rule management system for security teams.
• It blends a Python library with a CLI tool to develop, test, and manage detection rules as code.
• The framework is used to create, customize, and deploy detection rules to a security platform (Panther), meaning its design must capture both development workflows and runtime/delivery components.
Analyzing the File Structure
• Top-Level Files/Directories:
• main.py: Acts as the primary configuration/orchestration file for the framework.
• content/: This directory is divided into subdirectories:
▸ rules/: Contains individual detection rules defined for various log types (each file represents a rule module).
▸ helpers/: Offers auxiliary functions that support the rule logic.
▸ (The README also mentions an “overrides” folder for configuration customizations, although not present in the file tree, it may be expected or added in extended versions.)
• pyproject.toml: Manages dependencies via Poetry.
• Makefile: Provides automated development workflows.
• .github/: Contains CI/CD configuration (workflows for linting, testing, and uploading) to automate quality checks and deployment.
Components and Their Interactions
• Developer Environment:
• Local environment is set up using tools like Python, Poetry, and Make.
• Developers write rules (in the content/rules module) and helper functions (content/helpers) that get combined in main.py.
• CI/CD pipelines in the .github/workflows ensure code quality (linting, testing) and facilitate deployments (pypanther upload command).
• Core Framework:
• main.py would act as the gateway for loading rules and helpers.
• The pypanther library (implied in the README) registers rules and handles rule customization via override or inheritance.
• The CLI (pypanther commands) wraps around library functions for listing, testing, and uploading rules.
• External Systems:
• CI/CD systems (GitHub Actions as defined in the workflows) interface with source control and trigger rule deployments.
Architectural Patterns and Design Principles
• Modularity: The separation between detection rules, helper functions, and configuration illustrates a modular design.
• Extensibility: Support for rule inheritance and overrides indicates that the architecture encourages extensibility.
• CI/CD Integration: The presence of several GitHub workflows represents a key continuous integration and deployment pattern.
• CLI-Driven Development: The system is built around a CLI that interacts with local rule definitions and external Panther services.