{"id":8519,"library":"pysigma","title":"pySigma","description":"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.","status":"active","version":"1.3.2","language":"en","source_language":"en","source_url":"https://github.com/SigmaHQ/pySigma","tags":["security","threat-detection","sigma","rule-engine","siem","edr"],"install":[{"cmd":"pip install pysigma","lang":"bash","label":"Install pySigma core library"},{"cmd":"pip install pysigma[splunk,elasticsearch]","lang":"bash","label":"Install with specific backend dependencies (e.g., Splunk, Elasticsearch)"}],"dependencies":[{"reason":"Required for parsing Sigma rule syntax.","package":"pyparsing","optional":false},{"reason":"Required for loading YAML-based Sigma rules and configurations.","package":"PyYAML","optional":false},{"reason":"Provides command-line interface, often used with pysigma for rule validation and conversion. Not a direct library dependency but common complement.","package":"pysigma-cli","optional":true},{"reason":"Specific backend plugins (e.g., pysigma-plugin-splunk, pysigma-plugin-elasticsearch) are required to convert Sigma rules to target SIEM/EDR query languages. These are installed separately or via extras.","package":"pysigma-plugin-<backend>","optional":true}],"imports":[{"note":"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.","wrong":"from pysigma.collection import SigmaCollection","symbol":"PySigmaCollection","correct":"from pysigma import PySigmaCollection"},{"note":"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`.","wrong":"from pysigma.backends.splunk import SplunkBackend # if plugin not installed","symbol":"SigmaDetectionsBackend","correct":"from pysigma.backends.sigma import SigmaDetectionsBackend"},{"note":"The `SigmaRule` class, representing a parsed Sigma rule, has moved. Its canonical location is now `pysigma.parser.rule.SigmaRule` as of v1.0.0.","wrong":"from sigma.rule import SigmaRule","symbol":"SigmaRule","correct":"from pysigma.parser.rule import SigmaRule"}],"quickstart":{"code":"import os\nfrom pysigma import PySigmaCollection\nfrom pysigma.backends.sigma import SigmaDetectionsBackend\n\n# Create a dummy Sigma rule file for demonstration\nrule_content = \"\"\"\ntitle: Detect PowerShell Encoded Command\nid: 03f57279-7928-4e89-a5e2-6320573e6a4b\nstatus: stable\ndescription: Detects PowerShell usage with encoded commands, often used in malicious activity.\nlogsource:\n  category: process_creation\n  product: windows\ndetection:\n  selection:\n    Image|endswith: \n      - '\\\\powershell.exe'\n      - '\\\\pwsh.exe'\n    CommandLine|contains: \n      - '-EncodedCommand'\n      - '-eNcoDedCOmmaNd'\n  condition: selection\nfields:\n  - CommandLine\n  - ParentCommandLine\n  - Image\ntags:\n  - attack.execution\n  - attack.t1059.001\n\"\"\"\n\n# Save the rule to a temporary directory\nif not os.path.exists('sigma_rules'):\n    os.makedirs('sigma_rules')\nwith open('sigma_rules/powershell_encoded_command.yml', 'w') as f:\n    f.write(rule_content)\n\n# 1. Load Sigma rules from a directory\ncollection = PySigmaCollection.from_directory('sigma_rules')\nprint(f\"Loaded {len(collection.rules)} Sigma rule(s).\")\n\n# 2. Instantiate a backend (e.g., generic Sigma detection backend)\n# For Splunk, use: from pysigma.backends.splunk import SplunkBackend; backend = SplunkBackend()\nbackend = SigmaDetectionsBackend()\n\n# 3. Process the collection using the backend\n# This generates a list of Backend_Rule objects\ndetection_rules = backend.convert(collection)\n\n# 4. Print the converted query for each rule\nfor rule in detection_rules:\n    print(f\"\\nRule ID: {rule.id}\")\n    print(f\"Query: {rule.text}\")\n\n# Clean up the dummy rule file and directory\nos.remove('sigma_rules/powershell_encoded_command.yml')\nos.rmdir('sigma_rules')\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.3.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"The main collection class is now `PySigmaCollection` and should be imported directly from the top-level `pysigma` package: `from pysigma import PySigmaCollection`.","cause":"Attempting to import `SigmaCollection` from the old `pysigma.collection` path, which was changed in v1.0.0.","error":"ModuleNotFoundError: No module named 'pysigma.collection'"},{"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.","cause":"Using a deprecated method `to_s` to get a string representation of a rule, which was renamed in v1.0.0.","error":"AttributeError: 'SigmaRule' object has no attribute 'to_s'"},{"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.","cause":"The YAML content of a Sigma rule file is syntactically incorrect, often due to improper indentation or other YAML parsing issues.","error":"pysigma.exceptions.SigmaError: Failed to parse Sigma rule: unexpected indent"},{"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.","cause":"A processing pipeline or backend configuration specifies a template variables file that does not exist at the given path.","error":"ValueError: Template variable file not found: /path/to/missing_vars.yml"}]}