pySigma

1.3.2 · active · verified Thu Apr 16

pySigma is a Python library for processing and converting Sigma rules, a generic and open signature format that allows security analysts to describe relevant log events in a structured way. It serves as the core engine for Sigma rule management and transformation into various SIEM or EDR query languages. The current version is 1.3.2, with minor releases and bug fixes occurring frequently.

Common errors

```
ModuleNotFoundError: No module named 'pysigma.collection'
```
cause Attempting to import `SigmaCollection` from the old `pysigma.collection` path, which was changed in v1.0.0.

fix The main collection class is now `PySigmaCollection` and should be imported directly from the top-level `pysigma` package: `from pysigma import PySigmaCollection`.
```
AttributeError: 'SigmaRule' object has no attribute 'to_s'
```
cause Using a deprecated method `to_s` to get a string representation of a rule, which was renamed in v1.0.0.

fix The method `to_s` has been renamed to `to_plain_text` as part of the v1.0.0 API changes. Use `rule.to_plain_text()` instead.
```
pysigma.exceptions.SigmaError: Failed to parse Sigma rule: unexpected indent
```
cause The YAML content of a Sigma rule file is syntactically incorrect, often due to improper indentation or other YAML parsing issues.

fix Carefully review the Sigma rule file for YAML syntax errors. Use a YAML linter or the `sigmac validate` command (from `pysigma-cli`) to identify and fix issues. Ensure fields like `logsource` and `detection` are correctly structured.
```
ValueError: Template variable file not found: /path/to/missing_vars.yml
```
cause A processing pipeline or backend configuration specifies a template variables file that does not exist at the given path.

fix Verify that the template variables file (e.g., `vars.yml`) exists at the specified absolute path or a path relative to the pipeline configuration file. Correct the path or ensure the file is present.

Warnings

breaking pySigma v1.0.0 introduced significant breaking changes, including a redesigned API, new package structure, and changes to pipeline configuration. Key changes include `SigmaCollection` being replaced by `PySigmaCollection` for loading, movement of `SigmaRule` class, and a new structure for `Rule` objects.
Fix: Review the official 'Breaking Changes' documentation for pySigma v1.0.0 on GitHub. Update import paths and API calls to align with the new structure. Specifically, use `from pysigma import PySigmaCollection` and refer to updated backend initialization patterns.
breaking A security vulnerability was identified in v1.3.0 related to custom template variables. Untrusted processing pipelines utilizing the template vars feature could lead to unintended arbitrary code execution. Users should be aware that pipelines can imply execution of arbitrary code.
Fix: Upgrade to pySigma v1.3.0 or later. Exercise extreme caution when using custom template variables and processing pipelines from untrusted sources, as they may contain malicious code. Only use pipelines from trusted origins.
gotcha Prior to v1.3.2, MITRE data loading in tag validators was not deferred. This could cause timeouts or errors when pySigma was used in offline environments or without proper internet access for MITRE ATT&CK data validation.
Fix: Upgrade to pySigma v1.3.2 or later to benefit from deferred MITRE data loading, which resolves offline environment issues. If unable to upgrade, ensure internet connectivity for initial tag validation or disable MITRE tag validation if not critical.
gotcha As of v1.0.1, pySigma uses PyPI dependency information for plugin compatibility checks. Custom or locally developed plugins might require explicit `pysigma_compatibility` entries in their `setup.py` or equivalent to ensure they are recognized as compatible.
Fix: For custom plugins, ensure their packaging metadata explicitly declares compatibility with `pysigma` using `pysigma_compatibility` to avoid unexpected compatibility errors when `pysigma` performs its checks. Consult plugin development guidelines for details.

Install

pip install pysigma Install pySigma core library
pip install pysigma[splunk,elasticsearch] Install with specific backend dependencies (e.g., Splunk, Elasticsearch)

Imports

PySigmaCollection
wrong:
```
from pysigma.collection import SigmaCollection
```
correct:
```
from pysigma import PySigmaCollection
```
Pre-v1.0.0, the primary collection class was `SigmaCollection` from `pysigma.collection`. As of v1.0.0, `PySigmaCollection` from the top-level `pysigma` package is the main entry point for loading rules. `SigmaCollection` still exists but is an internal representation.
SigmaDetectionsBackend
wrong:
```
from pysigma.backends.splunk import SplunkBackend # if plugin not installed
```
correct:
```
from pysigma.backends.sigma import SigmaDetectionsBackend
```
Backend classes for specific SIEM/EDR systems are located in `pysigma.backends.<backend_name>`. Using a backend without its corresponding plugin installed will result in a `ModuleNotFoundError` or `pysigma.exceptions.SigmaTransformationError`.
SigmaRule
wrong:
```
from sigma.rule import SigmaRule
```
correct:
```
from pysigma.parser.rule import SigmaRule
```
The `SigmaRule` class, representing a parsed Sigma rule, has moved. Its canonical location is now `pysigma.parser.rule.SigmaRule` as of v1.0.0.

Quickstart

This quickstart demonstrates how to load Sigma rules from a local directory, initialize a generic Sigma detection backend, and convert the rules into a textual representation suitable for a SIEM/EDR system. To convert to specific SIEM formats (e.g., Splunk, Elasticsearch), you need to install the corresponding `pysigma-plugin-<backend>` package and import the specific backend class.

import os
from pysigma import PySigmaCollection
from pysigma.backends.sigma import SigmaDetectionsBackend

# Create a dummy Sigma rule file for demonstration
rule_content = """
title: Detect PowerShell Encoded Command
id: 03f57279-7928-4e89-a5e2-6320573e6a4b
status: stable
description: Detects PowerShell usage with encoded commands, often used in malicious activity.
logsource:
  category: process_creation
  product: windows
detection:
  selection:
    Image|endswith: 
      - '\\powershell.exe'
      - '\\pwsh.exe'
    CommandLine|contains: 
      - '-EncodedCommand'
      - '-eNcoDedCOmmaNd'
  condition: selection
fields:
  - CommandLine
  - ParentCommandLine
  - Image
tags:
  - attack.execution
  - attack.t1059.001
"""

# Save the rule to a temporary directory
if not os.path.exists('sigma_rules'):
    os.makedirs('sigma_rules')
with open('sigma_rules/powershell_encoded_command.yml', 'w') as f:
    f.write(rule_content)

# 1. Load Sigma rules from a directory
collection = PySigmaCollection.from_directory('sigma_rules')
print(f"Loaded {len(collection.rules)} Sigma rule(s).")

# 2. Instantiate a backend (e.g., generic Sigma detection backend)
# For Splunk, use: from pysigma.backends.splunk import SplunkBackend; backend = SplunkBackend()
backend = SigmaDetectionsBackend()

# 3. Process the collection using the backend
# This generates a list of Backend_Rule objects
detection_rules = backend.convert(collection)

# 4. Print the converted query for each rule
for rule in detection_rules:
    print(f"\nRule ID: {rule.id}")
    print(f"Query: {rule.text}")

# Clean up the dummy rule file and directory
os.remove('sigma_rules/powershell_encoded_command.yml')
os.rmdir('sigma_rules')

view raw JSON →