# panther-labs/pypanther-starter-kit architecture

> Architecture diagram of the GitHub repository panther-labs/pypanther-starter-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/panther-labs/pypanther-starter-kit
- Repository: https://github.com/panther-labs/pypanther-starter-kit

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment Subgraph
    subgraph "Developer Environment"
        M("Makefile"):::developer
        P("pyproject.toml"):::developer
    end

    %% Content Modules Subgraph
    subgraph "Content Modules"
        DRM("Detection Rules Module"):::module
        HFM("Helper Functions Module"):::module
    end

    %% Core Framework and CLI
    CF("Core Framework/Orchestration & CLI (main.py)"):::core

    %% CI/CD Pipeline
    CP("CI/CD Pipeline"):::pipeline

    %% External Panther API
    PA("Panther API"):::external

    %% Relationships
    M -->|"configure"| CF
    P -->|"manage-deps"| CF
    M --- DRM
    P --- HFM
    DRM -->|"loadedBy"| CF
    HFM -->|"usedBy"| CF
    CP -->|"test-upload"| CF
    CF -->|"CLI-upload"| PA
    CP -->|"automated-upload"| PA

    %% Click Events
    click M "https://github.com/panther-labs/pypanther-starter-kit/tree/main/Makefile"
    click P "https://github.com/panther-labs/pypanther-starter-kit/blob/main/pyproject.toml"
    click DRM "https://github.com/panther-labs/pypanther-starter-kit/tree/main/content/rules/"
    click HFM "https://github.com/panther-labs/pypanther-starter-kit/tree/main/content/helpers/"
    click CF "https://github.com/panther-labs/pypanther-starter-kit/blob/main/main.py"
    click CP "https://github.com/panther-labs/pypanther-starter-kit/tree/main/.github/workflows/"

    %% Class Definitions for styling
    classDef developer fill:#F4A261,stroke:#E76F51,stroke-width:2px;
    classDef module fill:#2A9D8F,stroke:#256D7B,stroke-width:2px;
    classDef core fill:#E76F51,stroke:#F4A261,stroke-width:2px;
    classDef pipeline fill:#E9C46A,stroke:#F4A261,stroke-width:2px;
    classDef external fill:#264653,stroke:#2A9D8F,stroke-width:2px;
```
