# sigmahq/pysigma architecture

> Architecture diagram of the GitHub repository sigmahq/pysigma, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sigmahq/pysigma
- Repository: https://github.com/sigmahq/pysigma

## Overview

pySigma is a vendor-agnostic Python library for parsing Sigma rules and converting them into backend queries. The principal workflow is rule input → rule and detection model → optional validation and processing transformations → backend conversion → query output. Correlation rules, reusable log-source pipelines, modifiers, and plugin-provided backends are distinct capabilities. The excerpts are partial, so connections are limited to the documented workflow and visible module responsibilities; no command-line consumer is shown in this repository tree.

Main entry points: [`sigma/processing/pipeline.py`](https://github.com/sigmahq/pysigma/blob/main/sigma/processing/pipeline.py) (Processing pipeline), [`sigma/conversion/base.py`](https://github.com/sigmahq/pysigma/blob/main/sigma/conversion/base.py) (Backend converter), [`sigma/collection.py`](https://github.com/sigmahq/pysigma/blob/main/sigma/collection.py) (Rule collection), [`sigma/rule/rule.py`](https://github.com/sigmahq/pysigma/blob/main/sigma/rule/rule.py) (Sigma rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rule_model["Rule model"]
  node_collection["Rule collection<br/>[collection.py]"]
  node_rule["Sigma rules<br/>[rule.py]"]
  node_detection["Detections<br/>[detection.py]"]
  node_conditions["Condition expressions<br/>[conditions.py]"]
  node_correlations["Correlation rules<br/>[correlations.py]"]
  node_modifiers["Value modifiers<br/>[modifiers.py]"]
end

subgraph group_processing["Processing"]
  node_processing_pipeline["Processing pipeline<br/>[pipeline.py]"]
  node_processing_conditions["Processing conditions<br/>[base.py]"]
  node_transformations["Transformations<br/>[base.py]"]
  node_common_pipelines["Common pipelines<br/>[common.py]"]
end

subgraph group_conversion["Conversion"]
  node_backend["Backend converter<br/>[base.py]"]
  node_conversion_state["Conversion state<br/>[state.py]"]
  node_deferred["Deferred queries<br/>[deferred.py]"]
  node_plugins["Plugin registry<br/>[plugins.py]"]
end

subgraph group_validation["Validation"]
  node_validator_api["Validation framework<br/>[base.py]"]
  node_core_validators["Core validators<br/>[condition.py]"]
  node_tag_validator["Tag validation<br/>[tags.py]"]
  node_attack_data["ATT&amp;CK data<br/>[mitre_attack.py]"]
  node_d3fend_data["D3FEND data<br/>[mitre_d3fend.py]"]
end

node_rule_author(("Rule provider"))
node_backend_projects["Backend extensions"]
node_query["Converted queries"]

node_rule_author -->|"provides rules"| node_collection
node_collection -->|"holds rules"| node_rule
node_rule -->|"contains detections"| node_detection
node_detection -->|"applies modifiers"| node_modifiers
node_rule -->|"defines conditions"| node_conditions
node_collection -->|"includes correlations"| node_correlations
node_collection -->|"can validate"| node_validator_api
node_validator_api -->|"runs checks"| node_core_validators
node_validator_api -->|"runs checks"| node_tag_validator
node_tag_validator -->|"checks tags"| node_attack_data
node_tag_validator -->|"checks tags"| node_d3fend_data
node_rule -->|"enters processing"| node_processing_pipeline
node_processing_pipeline -->|"evaluates conditions"| node_processing_conditions
node_processing_pipeline -->|"applies transformations"| node_transformations
node_common_pipelines -->|"provides items"| node_processing_pipeline
node_processing_pipeline -->|"prepares rules"| node_backend
node_backend -->|"tracks conversion"| node_conversion_state
node_backend -->|"handles deferred queries"| node_deferred
node_backend -->|"renders queries"| node_query
node_plugins -.->|"discovers extensions"| node_backend_projects
node_backend_projects -.->|"extends conversion"| node_backend

click node_collection "https://github.com/sigmahq/pysigma/blob/main/sigma/collection.py"
click node_rule "https://github.com/sigmahq/pysigma/blob/main/sigma/rule/rule.py"
click node_detection "https://github.com/sigmahq/pysigma/blob/main/sigma/rule/detection.py"
click node_conditions "https://github.com/sigmahq/pysigma/blob/main/sigma/conditions.py"
click node_correlations "https://github.com/sigmahq/pysigma/blob/main/sigma/correlations.py"
click node_modifiers "https://github.com/sigmahq/pysigma/blob/main/sigma/modifiers.py"
click node_validator_api "https://github.com/sigmahq/pysigma/blob/main/sigma/validators/base.py"
click node_core_validators "https://github.com/sigmahq/pysigma/blob/main/sigma/validators/core/condition.py"
click node_tag_validator "https://github.com/sigmahq/pysigma/blob/main/sigma/validators/core/tags.py"
click node_attack_data "https://github.com/sigmahq/pysigma/blob/main/sigma/data/mitre_attack.py"
click node_d3fend_data "https://github.com/sigmahq/pysigma/blob/main/sigma/data/mitre_d3fend.py"
click node_processing_pipeline "https://github.com/sigmahq/pysigma/blob/main/sigma/processing/pipeline.py"
click node_processing_conditions "https://github.com/sigmahq/pysigma/blob/main/sigma/processing/conditions/base.py"
click node_transformations "https://github.com/sigmahq/pysigma/blob/main/sigma/processing/transformations/base.py"
click node_common_pipelines "https://github.com/sigmahq/pysigma/blob/main/sigma/pipelines/common.py"
click node_backend "https://github.com/sigmahq/pysigma/blob/main/sigma/conversion/base.py"
click node_conversion_state "https://github.com/sigmahq/pysigma/blob/main/sigma/conversion/state.py"
click node_deferred "https://github.com/sigmahq/pysigma/blob/main/sigma/conversion/deferred.py"
click node_plugins "https://github.com/sigmahq/pysigma/blob/main/sigma/plugins.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_collection,node_rule,node_detection,node_conditions,node_correlations,node_modifiers toneBlue
class node_processing_pipeline,node_processing_conditions,node_transformations,node_common_pipelines toneAmber
class node_backend,node_conversion_state,node_deferred,node_plugins toneMint
class node_validator_api,node_core_validators,node_tag_validator,node_attack_data,node_d3fend_data toneRose
class node_rule_author,node_backend_projects,node_query toneIndigo
```

## Components

### Rule model

- [Rule collection](https://github.com/sigmahq/pysigma/blob/main/sigma/collection.py): `sigma/collection.py`
- [Sigma rules](https://github.com/sigmahq/pysigma/blob/main/sigma/rule/rule.py): `sigma/rule/rule.py`
- [Detections](https://github.com/sigmahq/pysigma/blob/main/sigma/rule/detection.py): `sigma/rule/detection.py`
- [Condition expressions](https://github.com/sigmahq/pysigma/blob/main/sigma/conditions.py): `sigma/conditions.py`
- [Correlation rules](https://github.com/sigmahq/pysigma/blob/main/sigma/correlations.py): `sigma/correlations.py`
- [Value modifiers](https://github.com/sigmahq/pysigma/blob/main/sigma/modifiers.py): `sigma/modifiers.py`

### Processing

- [Processing pipeline](https://github.com/sigmahq/pysigma/blob/main/sigma/processing/pipeline.py): `sigma/processing/pipeline.py`
- [Processing conditions](https://github.com/sigmahq/pysigma/blob/main/sigma/processing/conditions/base.py): `sigma/processing/conditions/base.py`
- [Transformations](https://github.com/sigmahq/pysigma/blob/main/sigma/processing/transformations/base.py): `sigma/processing/transformations/base.py`
- [Common pipelines](https://github.com/sigmahq/pysigma/blob/main/sigma/pipelines/common.py): `sigma/pipelines/common.py`

### Conversion

- [Backend converter](https://github.com/sigmahq/pysigma/blob/main/sigma/conversion/base.py): `sigma/conversion/base.py`
- [Conversion state](https://github.com/sigmahq/pysigma/blob/main/sigma/conversion/state.py): `sigma/conversion/state.py`
- [Deferred queries](https://github.com/sigmahq/pysigma/blob/main/sigma/conversion/deferred.py): `sigma/conversion/deferred.py`
- [Plugin registry](https://github.com/sigmahq/pysigma/blob/main/sigma/plugins.py): `sigma/plugins.py`

### Validation

- [Validation framework](https://github.com/sigmahq/pysigma/blob/main/sigma/validators/base.py): `sigma/validators/base.py`
- [Core validators](https://github.com/sigmahq/pysigma/blob/main/sigma/validators/core/condition.py): `sigma/validators/core/condition.py`
- [Tag validation](https://github.com/sigmahq/pysigma/blob/main/sigma/validators/core/tags.py): `sigma/validators/core/tags.py`
- [ATT&CK data](https://github.com/sigmahq/pysigma/blob/main/sigma/data/mitre_attack.py): `sigma/data/mitre_attack.py`
- [D3FEND data](https://github.com/sigmahq/pysigma/blob/main/sigma/data/mitre_d3fend.py): `sigma/data/mitre_d3fend.py`

### Other components

- **Rule provider**
- **Backend extensions**
- **Converted queries**

## Connections

- Rule provider → Rule collection: provides rules
- Rule collection → Sigma rules: holds rules
- Sigma rules → Detections: contains detections
- Detections → Value modifiers: applies modifiers
- Sigma rules → Condition expressions: defines conditions
- Rule collection → Correlation rules: includes correlations
- Rule collection → Validation framework: can validate
- Validation framework → Core validators: runs checks
- Validation framework → Tag validation: runs checks
- Tag validation → ATT&CK data: checks tags
- Tag validation → D3FEND data: checks tags
- Sigma rules → Processing pipeline: enters processing
- Processing pipeline → Processing conditions: evaluates conditions
- Processing pipeline → Transformations: applies transformations
- Common pipelines → Processing pipeline: provides items
- Processing pipeline → Backend converter: prepares rules
- Backend converter → Conversion state: tracks conversion
- Backend converter → Deferred queries: handles deferred queries
- Backend converter → Converted queries: renders queries
- Plugin registry → Backend extensions: discovers extensions
- Backend extensions → Backend converter: extends conversion