sigma-cli

Overview

sigma-cli is a command-line utility for converting Sigma detection rules into queries compatible with various SIEM platforms and log analysis tools. Sigma is a generic format for writing detection rules that can be translated to multiple backends, enabling security teams to maintain a single rule repository for multiple security tools without rewriting rules for each platform.

Key Features

Multi-backend Support: Splunk, ELK, Elastic, Kibana, Sumologic, ArcSight, Windows Defender, and more
Rule Validation: Syntax and schema validation for Sigma rules
Batch Conversion: Process multiple rules at once
Custom Pipelines: Apply transformations and filters
Flexible Output: Multiple output formats (queries, YAML, JSON)
Rule Generation: Create new Sigma rules from scratch
Cross-platform: Linux, macOS, Windows compatible

Installation

Prerequisites

# Python 3.8+ required
python3 --version

# Check pip
pip3 --version

Installation Methods

Via PyPI (Recommended)

# Install latest version
pip3 install sigma-cli

# Verify installation
sigma --version

# Check available backends
sigma list backends

From GitHub

git clone https://github.com/SigmaHQ/sigma-cli.git
cd sigma-cli

# Install in development mode
pip3 install -e .

# Verify installation
sigma --version

Docker

# Pull official image
docker pull sigmahq/sigma-cli:latest

# Run container
docker run --rm sigmahq/sigma-cli:latest sigma --version

# Run with volume mount
docker run --rm -v $(pwd):/rules sigmahq/sigma-cli:latest \
  sigma convert -t splunk /rules/rule.yml

macOS (Homebrew)

# If available
brew install sigma-cli

# Or install via pip
pip3 install sigma-cli --user

# Add to PATH if needed
export PATH=$PATH:$HOME/Library/Python/3.*/bin

Basic Usage

Help and Information

# Show main help
sigma --help

# Show version and info
sigma --version
sigma info

# List available backends
sigma list backends

# Get backend help
sigma convert --help
sigma convert -t splunk --help

Convert Sigma Rule

Simple Conversion

# Convert single rule to Splunk query
sigma convert -t splunk rule.yml

# Convert to ELK query
sigma convert -t elk rule.yml

# Convert to Elasticsearch
sigma convert -t elasticsearch rule.yml

# Save to file
sigma convert -t splunk rule.yml -o output.txt
sigma convert -t splunk rule.yml > query.spl

View Available Backends

# List all backends
sigma list backends

# Get specific backend info
sigma list backends | grep -i splunk
sigma list backends | grep -i elastic

# Show backend details
sigma convert --list-backends

Rule Concepts

Sigma Rule Structure

Section	Purpose	Required
`title`	Rule name	Yes
`description`	Rule description	No
`detection`	Detection logic	Yes
`fields`	Event fields to detect	Yes
`keywords`	Search keywords	No
`status`	Rule maturity (experimental, test, stable)	No
`logsource`	Log source (category, product, service)	Yes
`tags`	Classification tags	No
`falsepositives`	Known false positives	No
`references`	Reference URLs	No

Example Sigma Rule

title: Suspicious Process Creation - cmd.exe
description: Detects suspicious command shell processes
status: test
logsource:
  category: process_creation
  product: windows

detection:
  selection_parent:
    ParentImage|endswith: 
      - '\\explorer.exe'
      - '\\winword.exe'
    Image|endswith: '\\cmd.exe'
  
  selection_pipes:
    Image|endswith: '\\cmd.exe'
    CommandLine|contains: ' | '
  
  condition: selection_parent or selection_pipes

falsepositives:
  - System administration tasks
  
references:
  - https://attack.mitre.org/techniques/T1059/001/

tags:
  - attack.execution
  - attack.t1059
  - attack.t1059.001

Advanced Usage

Batch Rule Conversion

# Convert all rules in directory
sigma convert -t splunk -d rules/ -o output/

# Convert with specific pattern
sigma convert -t elk -d rules/ -p "*process*.yml" -o converted/

# Convert multiple formats
for backend in splunk elk elasticsearch; do
  sigma convert -t $backend -d rules/ -o output/$backend/
done

Custom Processing Pipelines

# Apply field mapping pipeline
sigma convert -t splunk rule.yml --pipeline field-mapping

# Chain multiple pipelines
sigma convert -t splunk rule.yml \
  --pipeline field-mapping \
  --pipeline windows-process-creation

# List available pipelines
sigma list pipelines

Output Formats

# Default backend-specific format
sigma convert -t splunk rule.yml

# JSON output
sigma convert -t splunk rule.yml --format json

# YAML output (rule format)
sigma convert -t splunk rule.yml --format yaml

# Pretty print output
sigma convert -t splunk rule.yml --format yaml | jq '.'

# Raw query only
sigma convert -t splunk rule.yml --query-only

Backend-Specific Conversion

Splunk

# Basic Splunk conversion
sigma convert -t splunk rule.yml

# Splunk with field mapping
sigma convert -t splunk rule.yml \
  --pipeline splunk-process-creation

# Splunk search format
sigma convert -t splunk rule.yml > splunk_search.spl

# Example output
# index=windows EventCode=4688 (Image="C:\\Windows\\System32\\cmd.exe" 
# OR (ParentImage="C:\\Windows\\explorer.exe" Image="C:\\Windows\\System32\\cmd.exe"))

Elasticsearch/ELK

# Basic ELK conversion
sigma convert -t elasticsearch rule.yml

# ELK with pipeline
sigma convert -t elk rule.yml --pipeline ecs-mapping

# Kibana query format
sigma convert -t kibana rule.yml

# ECS field mapping
sigma convert -t elasticsearch rule.yml --pipeline ecs-v1-0-0-normalized

Windows Defender

# Convert to Windows Defender Advanced Threat Protection (ATP)
sigma convert -t windows-defender rule.yml

# MDATP query format
sigma convert -t mdatp rule.yml

# Example output for DeviceProcessEvents
sigma convert -t windows-defender rule.yml > defender_query.kql

Sumo Logic

# Convert to Sumo Logic
sigma convert -t sumologic rule.yml

# Sumo Logic specific output
sigma convert -t sumologic rule.yml -o sumologic_query.txt

ArcSight

# Convert to ArcSight
sigma convert -t arcsight rule.yml

# ArcSight query format
sigma convert -t arcsight rule.yml > arcsight_query.cef

Rule Validation and Testing

Validate Rules

# Validate single rule syntax
sigma validate rule.yml

# Validate all rules in directory
sigma validate -d rules/

# Verbose validation output
sigma validate -d rules/ -v

# Check specific rule
sigma validate rules/windows/process_creation/*.yml

Test Rules

# Test rule conversion without saving
sigma convert -t splunk rule.yml --test

# Test with specific log file
sigma test rule.yml sample_logs.json -t splunk

# Simulate detection
sigma convert -t splunk rule.yml | \
  sigma simulate -f sample_logs.json

Lint Rules

# Check rule formatting
sigma lint rule.yml

# Lint entire directory
sigma lint -d rules/

# Fix common issues automatically
sigma lint -d rules/ --fix

# Generate report
sigma lint -d rules/ --report lint_report.txt

Rule Generation and Management

Create New Rule

# Interactive rule creation
sigma create

# From template
sigma create --template process_creation

# Specify output file
sigma create -o new_rule.yml

# Template listing
sigma list templates

Rule Repository Integration

# Clone official Sigma rules repository
git clone https://github.com/SigmaHQ/sigma.git
cd sigma

# Convert all rules
sigma convert -t splunk -d rules/ -o splunk_queries/

# Filter by ATT&CK technique
find rules/ -name "*t1086*" | xargs -I {} \
  sigma convert -t elk {} -o elk_queries/

Rule Searching and Filtering

# Find rules by title
sigma find --title "*process*"

# Find by ATT&CK tag
sigma find --tag "attack.t1059"

# Find by status
sigma find --status stable

# Find by logsource
sigma find --logsource "category:process_creation"

# Combine filters
sigma find --tag "attack.execution" --status stable --title "*cmd*"

Practical Examples

Process Creation Detection

# Rule file: process_creation.yml
cat > process_creation.yml << 'EOF'
title: Suspicious Process Creation
description: Detects suspicious process creation patterns
logsource:
  category: process_creation
  product: windows

detection:
  selection:
    Image|endswith:
      - '\powershell.exe'
      - '\cmd.exe'
    CommandLine|contains:
      - 'IEX '
      - 'Invoke-Expression'
      - 'wget '
      - 'curl '

  condition: selection

falsepositives:
  - System administration activities

references:
  - https://attack.mitre.org/techniques/T1086/

tags:
  - attack.execution
  - attack.t1086
EOF

# Convert to multiple backends
sigma convert -t splunk process_creation.yml
sigma convert -t elasticsearch process_creation.yml
sigma convert -t kibana process_creation.yml

Network Connection Detection

cat > network_detection.yml << 'EOF'
title: Suspicious Outbound Connection
description: Detects suspicious outbound network connections
logsource:
  category: network_connection
  product: windows

detection:
  selection:
    DestinationPort|in:
      - 4444
      - 5555
      - 6666
      - 7777
    Protocol: tcp
  
  filter_local:
    DestinationIp|startswith:
      - '192.168.'
      - '10.'
      - '172.16.'
  
  condition: selection and not filter_local

falsepositives:
  - Internal testing

tags:
  - attack.command_and_control
  - attack.t1071
EOF

# Convert for Splunk
sigma convert -t splunk network_detection.yml

File Creation Detection

cat > file_creation.yml << 'EOF'
title: Suspicious File Creation in System Directories
logsource:
  category: file_event
  product: windows

detection:
  selection:
    TargetFilename|contains:
      - 'C:\Windows\Temp'
      - 'C:\Windows\System32\drivers\etc'
    TargetFilename|endswith:
      - '.exe'
      - '.bat'
      - '.ps1'
    Image|endswith:
      - '\svchost.exe'
      - '\explorer.exe'

  condition: selection

falsepositives:
  - Windows updates
  - Software installation

tags:
  - attack.execution
EOF

sigma convert -t kibana file_creation.yml

Pipeline Management

Understanding Pipelines

# List available pipelines
sigma list pipelines

# Show pipeline details
sigma show-pipeline splunk-process-creation

# List pipeline requirements
sigma show-pipeline --requirements elk-ecs

Apply Custom Pipelines

# Apply single pipeline
sigma convert -t splunk rule.yml --pipeline custom-mapping

# Chain pipelines (order matters)
sigma convert -t splunk rule.yml \
  --pipeline field-mapping \
  --pipeline windows-process-creation \
  --pipeline values-transformation

# Create custom pipeline
cat > custom_pipeline.yml << 'EOF'
name: Custom Field Mapping
rules:
  - type: add_condition_osh
    osh: 'Image="test"'
  - type: replace
    regex: 'CommandLine'
    replacement: 'ProcessCommandLine'
EOF

sigma convert -t splunk rule.yml \
  --pipeline custom_pipeline.yml

Output Processing

Save and Organize Queries

#!/bin/bash
# Convert and organize by backend

BACKENDS=("splunk" "elasticsearch" "kibana")
RULE_DIR="rules/"

for backend in "${BACKENDS[@]}"; do
  OUTPUT_DIR="queries/$backend"
  mkdir -p "$OUTPUT_DIR"
  
  sigma convert -t $backend -d "$RULE_DIR" -o "$OUTPUT_DIR"
  
  echo "[*] Converted to $backend: $OUTPUT_DIR"
done

Format for Different Use Cases

# Export for Splunk dashboards
sigma convert -t splunk -d rules/ | \
  sed 's/^/search /' > splunk_searches.txt

# Export for ELK Stack
sigma convert -t elasticsearch -d rules/ | \
  jq '.' > elk_queries.json

# Export for SIEM integration
sigma convert -t sumologic -d rules/ > sumologic_import.txt

# Create CSV summary
for rule in rules/*.yml; do
  TITLE=$(grep "^title:" "$rule" | sed 's/title: //')
  BACKEND=$(sigma convert -t splunk "$rule" 2>/dev/null | head -1)
  echo "$TITLE,$BACKEND" >> rules_export.csv
done

Integration Examples

Splunk Integration

#!/bin/bash
# Generate Splunk saved searches

mkdir -p splunk_app/default/

# Convert all rules
sigma convert -t splunk -d sigma_rules/ | while read query; do
  NAME="sigma_detection_$(date +%s)"
  
  cat >> splunk_app/default/savedsearches.conf << EOF
[$NAME]
search = $query
dispatch.earliest_time = -24h@h
dispatch.latest_time = now
EOF
done

Elasticsearch Integration

#!/bin/bash
# Generate Kibana rules

sigma convert -t kibana -d rules/ | \
  jq '{
    name: .title,
    type: "rule",
    rule: {
      index: "logs-*",
      query: .,
      enabled: true
    }
  }' > kibana_rules.ndjson

# Import to Kibana
curl -X POST \
  "http://localhost:5601/api/alerting/rule" \
  -H "Content-Type: application/json" \
  -d @kibana_rules.ndjson

Windows Defender Integration

#!/bin/bash
# Generate Defender ATP hunting queries

sigma convert -t windows-defender -d rules/ | \
  while read query; do
    echo "DeviceProcessEvents"
    echo "| where $query"
    echo ""
  done > defender_hunting_queries.kql

Command Reference

Core Commands

Command	Purpose
`sigma convert`	Convert Sigma rules to backend format
`sigma validate`	Validate rule syntax
`sigma lint`	Check rule quality and formatting
`sigma create`	Create new Sigma rule
`sigma list`	List backends, pipelines, templates
`sigma show-pipeline`	Display pipeline details
`sigma find`	Search for rules
`sigma test`	Test rules against logs

Convert Options

Option	Description
`-t, --target`	Target backend (splunk, elk, kibana, etc.)
`-d, --directory`	Input directory with rules
`-o, --output`	Output directory
`-p, --pattern`	File pattern to match
`--pipeline`	Apply processing pipeline
`--format`	Output format (default, json, yaml)
`--query-only`	Output query only

Troubleshooting

Common Issues

# Rule validation fails
sigma validate rule.yml --verbose

# Check for missing required fields
grep -E "^title:|^logsource:" rule.yml

# Verify YAML syntax
python3 -c "import yaml; yaml.safe_load(open('rule.yml'))"

# Conversion errors
sigma convert -t splunk rule.yml 2>&1 | head -20

Dependency Issues

# Update sigma-cli
pip3 install sigma-cli --upgrade

# Check dependencies
pip3 show sigma-cli

# Reinstall with fresh dependencies
pip3 uninstall sigma-cli -y
pip3 install sigma-cli

Backend Support Issues

# Verify backend is available
sigma list backends | grep splunk

# Test backend conversion
sigma convert -t splunk --test

# Check backend-specific options
sigma convert -t splunk --help | grep -A 20 "options:"

Best Practices

Rule Writing

Maintain clear, descriptive titles and descriptions
Use established ATT&CK tags for consistency
Document known false positives
Test rules against real logs
Version control rules with git
Keep rules modular and focused

Organization

# Organize rules by category
rules/
  ├── windows/
  │   ├── process_creation/
  │   ├── file_event/
  │   └── network_connection/
  ├── linux/
  └── generic/

# Convert maintaining structure
sigma convert -t splunk -d rules/ -o splunk_queries/

Quick Reference

Task	Command
Convert rule to Splunk	`sigma convert -t splunk rule.yml`
Convert rule to Elasticsearch	`sigma convert -t elasticsearch rule.yml`
Validate rule	`sigma validate rule.yml`
List backends	`sigma list backends`
Convert directory	`sigma convert -t splunk -d rules/ -o output/`
Apply pipeline	`sigma convert -t splunk rule.yml --pipeline ecs-mapping`
Save to file	`sigma convert -t splunk rule.yml -o query.txt`
Create new rule	`sigma create`
Lint all rules	`sigma lint -d rules/`

Resources

Official Repository: https://github.com/SigmaHQ/sigma
Sigma CLI GitHub: https://github.com/SigmaHQ/sigma-cli
Rule Repository: https://github.com/SigmaHQ/sigma-rules
Documentation: https://sigma.readthedocs.io/
Community: https://github.com/SigmaHQ/
MITRE ATT&CK: https://attack.mitre.org/
Backend Support: https://sigma.readthedocs.io/en/latest/backends.html