---
name: sigma-rule-development
description: Write, test, and share Sigma detection rules from observed malware behaviors. Convert rules to SIEM-specific formats with sigmac/pySigma and apply false positive reduction techniques.
---

# Sigma Rule Development

Write Sigma detection rules from observed malware behaviors, convert them to SIEM-specific query languages, and validate rule quality for sharing via SigmaHQ.

## Prerequisites

- **Python 3.10+** for running the rule writer and validation scripts
- **pySigma**: Sigma rule conversion framework (`pip install pySigma`)
- **pySigma backend plugins**: SIEM-specific converters (e.g., `pySigma-backend-splunk`, `pySigma-backend-elasticsearch`, `pySigma-backend-microsoft365defender`, `pySigma-backend-qradar`)
- **pySigma pipeline plugins**: Log source mappings (e.g., `pySigma-pipeline-sysmon`, `pySigma-pipeline-windows`)
- **sigma CLI**: For rule validation and conversion (`sigma check`, `sigma convert`)

## Steps

### 1. Understand Sigma Rule Structure

A Sigma rule is a YAML document with these required fields:

```yaml
title: Suspicious PowerShell Download Cradle
id: 3b6ab547-1298-4a74-b260-4c1e9f7b7a01   # UUIDv4
status: experimental    # test | experimental | stable | deprecated | unsupported
level: high             # informational | low | medium | high | critical
description: Detects PowerShell download cradles commonly used by malware droppers
author: Analyst Name
date: 2026/03/21
modified: 2026/03/21
references:
    - https://attack.mitre.org/techniques/T1059/001/
tags:
    - attack.execution
    - attack.t1059.001
logsource:
    category: process_creation
    product: windows
detection:
    selection:
        CommandLine|contains|all:
            - 'powershell'
            - 'downloadstring'
    condition: selection
falsepositives:
    - Legitimate admin scripts using download cradles
fields:
    - CommandLine
    - ParentCommandLine
    - User
```

### 2. Identify Log Sources for Detection

Match behaviors to the appropriate log source:

| Behavior | Log Source | Category |
|----------|-----------|----------|
| Process execution | `product: windows` | `process_creation` |
| Sysmon events | `product: windows, service: sysmon` | varies by EventID |
| File creation | `product: windows, service: sysmon` | `file_event` |
| Registry modification | `product: windows, service: sysmon` | `registry_event` |
| Network connections | `product: windows, service: sysmon` | `network_connection` |
| DNS queries | `product: windows, service: sysmon` | `dns_query` |
| Windows Security log | `product: windows, service: security` | varies |
| Linux audit | `product: linux, service: auditd` | `process_creation` |
| Web proxy logs | `category: proxy` | — |
| Firewall logs | `category: firewall` | — |

### 3. Write Detection Logic

Use Sigma detection fields with modifiers:

```yaml
detection:
    # Selection: what to match
    selection_process:
        Image|endswith:
            - '\rundll32.exe'
            - '\regsvr32.exe'
    selection_cmdline:
        CommandLine|contains:
            - 'javascript:'
            - 'vbscript:'
    # Filter: what to exclude (false positives)
    filter_legitimate:
        ParentImage|endswith: '\msiexec.exe'
        CommandLine|contains: 'legitimate_dll.dll'
    # Condition: combine selections and filters
    condition: (selection_process and selection_cmdline) and not filter_legitimate
```

**Key modifiers:**
- `contains` — substring match
- `endswith` / `startswith` — suffix/prefix match
- `re` — regular expression match
- `all` — all values must appear (AND logic within a field)
- `base64` / `base64offset` — match base64-encoded strings
- `cidr` — match IP ranges
- `windash` — match both `-` and `/` in command-line switches

### 4. Generate Rules from Behavioral Observations

Use the rule writer script to generate Sigma YAML from observed behaviors:

```bash
# Generate from a behavioral description
python3 scripts/sigma_rule_writer.py \
    --title "Malware X Registry Persistence" \
    --description "Detects Malware X setting Run key persistence" \
    --logsource-product windows --logsource-service sysmon \
    --logsource-category registry_event \
    --detection-field TargetObject \
    --detection-modifier contains \
    --detection-values 'Software\Microsoft\Windows\CurrentVersion\Run,MalwareX_Persist' \
    --level high \
    --attack-tags attack.persistence,attack.t1547.001 \
    --output rules/malwarex_persistence.yml
```

For process-creation rules:

```bash
python3 scripts/sigma_rule_writer.py \
    --title "Suspicious certutil Download" \
    --logsource-product windows \
    --logsource-category process_creation \
    --detection-field CommandLine \
    --detection-modifier 'contains|all' \
    --detection-values 'certutil,-urlcache,-split' \
    --level high \
    --attack-tags attack.command_and_control,attack.t1105 \
    --falsepositives "Legitimate certificate operations" \
    --output rules/certutil_download.yml
```

### 5. Test and Convert Rules with pySigma

Convert Sigma rules to SIEM-specific query languages:

```bash
# Install pySigma and backend plugins
pip install pySigma pySigma-backend-splunk pySigma-backend-elasticsearch \
    pySigma-backend-microsoft365defender pySigma-backend-qradar \
    pySigma-pipeline-sysmon pySigma-pipeline-windows

# Convert to Splunk SPL
sigma convert -t splunk -p sysmon rules/malwarex_persistence.yml

# Convert to Elastic Query DSL
sigma convert -t elasticsearch -p ecs_windows rules/malwarex_persistence.yml

# Convert to Microsoft Sentinel KQL
sigma convert -t microsoft365defender rules/malwarex_persistence.yml

# Convert to QRadar AQL
sigma convert -t qradar rules/malwarex_persistence.yml

# Batch convert all rules in a directory
sigma convert -t splunk -p sysmon rules/ --output splunk_queries/
```

Legacy sigmac conversion (deprecated but still in use):

```bash
sigmac -t splunk -c sysmon rules/malwarex_persistence.yml
sigmac -t es-qs -c winlogbeat rules/malwarex_persistence.yml
```

### 6. Validate Rule Quality

Check rules against SigmaHQ quality standards:

```bash
# Validate YAML syntax and required fields
sigma check rules/malwarex_persistence.yml

# Validate all rules in a directory
sigma check rules/

# Run the rule writer in validation mode
python3 scripts/sigma_rule_writer.py --validate rules/malwarex_persistence.yml
```

Quality checklist:
- Unique UUIDv4 `id` field
- Descriptive `title` (max 100 characters)
- Accurate `level` assignment matching the detection specificity
- At least one `tag` with ATT&CK mapping
- `falsepositives` section documenting known FPs
- `fields` listing useful context fields for analysts
- `status` set to `experimental` for new rules

### 7. Reduce False Positives

Techniques for FP reduction:

```yaml
detection:
    selection:
        CommandLine|contains|all:
            - 'powershell'
            - '-encodedcommand'
    # Stack multiple filters for known legitimate use
    filter_sccm:
        ParentImage|endswith: '\ccmexec.exe'
    filter_azure:
        CommandLine|contains: 'AzureConnectedMachineAgent'
    filter_admin_scripts:
        User|endswith: '$'   # Machine accounts
    condition: selection and not 1 of filter_*
```

Best practices:
- Test rules against baseline logs before deploying to production
- Use `near` temporal correlation for multi-event detections
- Combine multiple weak indicators with `and` logic for stronger signals
- Maintain a filter library for your environment's known-good patterns
- Start with `status: experimental` and promote to `stable` after tuning

### 8. Share via SigmaHQ

To contribute rules to the SigmaHQ repository:

```bash
# Fork and clone the SigmaHQ repository
git clone https://github.com/SigmaHQ/sigma.git
cd sigma

# Place rule in the correct directory structure
# rules/windows/process_creation/proc_creation_win_malwarex.yml

# Run the test suite
python3 -m pytest tests/

# Submit a pull request with the rule
```

Follow the SigmaHQ naming convention: `<category>_<product>_<short_description>.yml`

## Output Format

```json
{
  "rule_file": "rules/malwarex_persistence.yml",
  "title": "Malware X Registry Persistence",
  "id": "3b6ab547-1298-4a74-b260-4c1e9f7b7a01",
  "status": "experimental",
  "level": "high",
  "logsource": {
    "product": "windows",
    "service": "sysmon",
    "category": "registry_event"
  },
  "attack_tags": ["attack.persistence", "attack.t1547.001"],
  "detection_fields": ["TargetObject"],
  "conversions": {
    "splunk": "index=sysmon EventCode=13 TargetObject=\"*\\\\Run*\" TargetObject=\"*MalwareX_Persist*\"",
    "elasticsearch": "{\"query\":{\"bool\":{\"must\":[{\"wildcard\":{\"registry.path\":\"*\\\\Run*\"}}]}}}",
    "sentinel": "SysmonEvent | where EventID == 13 | where RegistryKey contains \"Run\""
  },
  "validation": {
    "valid_yaml": true,
    "has_required_fields": true,
    "has_uuid": true,
    "has_attack_tags": true,
    "quality_score": "high"
  }
}
```

## Tips

- Start with high-fidelity rules targeting specific malware family behaviors before writing broader behavioral rules
- Use the `1 of selection_*` syntax to match any of several alternative detection patterns
- The `all of selection_*` syntax requires all named selections to match, useful for reducing FPs
- Test rules against at least one week of baseline logs to estimate FP volume before production deployment
- Use Sigma's `timeframe` field in `detection` for time-windowed correlations (e.g., brute force detection)
- Keep rule descriptions specific and actionable so SOC analysts know what to investigate when the rule fires
- Sigma rules detect log events, not raw malware — always map behaviors to the log source that captures them
- When in doubt about `level`, use `medium` for behavioral detections and `high` only when the detection is specific to malicious activity
- Maintain a local `sigmac` conversion test for each SIEM backend you support to catch conversion regressions