{"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":"python","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":[{"wrong":"from sigma import PySigmaCollection","symbol":"PySigmaCollection","correct":"import sigma"}],"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,"search_vec":"'1.3.2':55 'allow':20 'analyst':22 'bug':60 'convert':10 'core':36 'current':52 'describ':24 'detect':67 'edr':48,73 'engin':37,71 'event':27 'fix':61 'format':18 'frequent':63 'generic':14 'languag':50 'librari':6 'log':26 'manag':41 'minor':57 'occur':62 'open':16 'process':8 'pysigma':1,2 'python':5 'queri':49 'releas':58 'relev':25 'rule':12,40,70 'rule-engin':69 'secur':21,64 'serv':33 'siem':46,72 'sigma':11,39,68 'signatur':17 'structur':30 'threat':66 'threat-detect':65 'transform':43 'various':45 'version':53 'way':31","created_at":"2026-04-16T17:02:36.274528+00:00","updated_at":"2026-04-16T17:02:36.274528+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.3.3","cli_name":"","cli_version":null,"type":"library","homepage":"https://sigmahq.io","github":"https://github.com/SigmaHQ/pySigma","docs":null,"changelog":null,"pypi":"https://pypi.org/project/pysigma/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-08-02","install_tag":null}}