Salta ai contenuti
1337skills 1337skills - Cheat Sheet

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

# 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

SectionPurposeRequired
titleRule nameYes
descriptionRule descriptionNo
detectionDetection logicYes
fieldsEvent fields to detectYes
keywordsSearch keywordsNo
statusRule maturity (experimental, test, stable)No
logsourceLog source (category, product, service)Yes
tagsClassification tagsNo
falsepositivesKnown false positivesNo
referencesReference URLsNo

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

CommandPurpose
sigma convertConvert Sigma rules to backend format
sigma validateValidate rule syntax
sigma lintCheck rule quality and formatting
sigma createCreate new Sigma rule
sigma listList backends, pipelines, templates
sigma show-pipelineDisplay pipeline details
sigma findSearch for rules
sigma testTest rules against logs

Convert Options

OptionDescription
-t, --targetTarget backend (splunk, elk, kibana, etc.)
-d, --directoryInput directory with rules
-o, --outputOutput directory
-p, --patternFile pattern to match
--pipelineApply processing pipeline
--formatOutput format (default, json, yaml)
--query-onlyOutput 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

TaskCommand
Convert rule to Splunksigma convert -t splunk rule.yml
Convert rule to Elasticsearchsigma convert -t elasticsearch rule.yml
Validate rulesigma validate rule.yml
List backendssigma list backends
Convert directorysigma convert -t splunk -d rules/ -o output/
Apply pipelinesigma convert -t splunk rule.yml --pipeline ecs-mapping
Save to filesigma convert -t splunk rule.yml -o query.txt
Create new rulesigma create
Lint all rulessigma lint -d rules/

Resources