<!-- AUTO-GENERATED by export-skills.py — DO NOT EDIT -->
---
applyTo: '**/*.{yaml,yml,tf,Dockerfile}'
---

# sigma-rules-guide

> Sigma detection rule writing guide for threat detection across SIEM platforms

# Sigma Detection Rules Guide

## Overview

Sigma is an open, vendor-agnostic signature format for describing log events and detection rules. Sigma rules can be converted into queries for virtually any SIEM platform (Splunk, Elastic, Microsoft Sentinel, Google Chronicle, Sumo Logic) using sigma converters (pySigma). This makes Sigma the de facto standard for shareable threat detection logic.

A Sigma rule describes **what** to detect in logs, not **how** a specific SIEM should query for it. This abstraction allows security teams to:

- Write detection logic once and deploy across multiple SIEM platforms
- Share detection rules with the community via SigmaHQ
- Map detections directly to MITRE ATT&CK techniques
- Version control detection rules alongside infrastructure code

The SigmaHQ repository contains over 3,000 community-maintained rules covering Windows, Linux, macOS, cloud, and network log sources.

## When to Use This Skill

- You are building detection rules for a new threat or attack technique
- You need to convert existing SIEM queries into a portable format
- You are mapping your detection coverage to the MITRE ATT&CK framework
- You want to share detection logic across teams using different SIEM platforms
- You are reviewing Sigma rules for quality, false positive rates, or completeness
- You are setting up a detection engineering pipeline with CI/CD for rules

## How It Works

### Step 1: Identify the Threat Behavior

Start by defining what adversary behavior you want to detect. Use threat intelligence reports, incident post-mortems, or MITRE ATT&CK techniques as inputs:

- What actions does the adversary take? (e.g., creates a new user, modifies a cron job)
- What log source records this activity? (e.g., auditd, syslog, cloud audit logs)
- What fields differentiate malicious from legitimate activity?

### Step 2: Map to MITRE ATT&CK

Associate the detection with one or more ATT&CK techniques to track coverage:

```yaml
tags:
  - attack.persistence        # Tactic
  - attack.t1053.003          # Technique: Scheduled Task/Job: Cron
  - attack.t1136.001          # Technique: Create Account: Local Account
```

Use the ATT&CK Navigator to visualize which techniques your rule set covers and identify gaps.

### Step 3: Write the Detection Logic

A Sigma rule is a YAML document with these key sections:

```yaml
title: Short descriptive title
id: unique-uuid-v4
status: experimental | test | stable
description: What this rule detects and why it matters
references:
  - https://link-to-threat-report
  - https://attack.mitre.org/techniques/T1053/003/
author: Your Name
date: 2026/02/24
modified: 2026/02/24
tags:
  - attack.persistence
  - attack.t1053.003

logsource:
  category: process_creation    # Generic category
  product: linux                # OS or platform

detection:
  selection:                    # What to look for
    CommandLine|contains:
      - 'crontab -e'
      - '/etc/cron.d/'
    User|not: 'root'

  filter_known:                 # What to exclude (false positives)
    ParentImage|endswith:
      - '/ansible'
      - '/puppet'

  condition: selection and not filter_known

falsepositives:
  - System administrators modifying cron jobs
  - Configuration management tools (Ansible, Puppet)

level: medium                   # informational | low | medium | high | critical
```

### Step 4: Test with Sample Logs

Validate your rule against real or synthetic log data before deployment:

```bash
# Install pySigma and a backend
pip install pysigma pysigma-backend-elasticsearch

# Convert Sigma rule to Elasticsearch query
sigma convert -t elasticsearch -p ecs_windows rule.yml

# Test against sample logs using sigmac
sigma convert -t splunk rule.yml | xargs -I {} \
  curl -s "https://splunk:8089/services/search/jobs" \
  -d "search={}" -d "exec_mode=oneshot"
```

Use the `sigma check` command to validate rule syntax:

```bash
sigma check rule.yml
```

### Step 5: Deploy to SIEM

Once validated, deploy the rule to your SIEM platform:

1. Convert the Sigma rule to the target SIEM query language
2. Create a scheduled search or detection rule in the SIEM
3. Configure alert severity and notification channels
4. Set up a feedback loop for tuning false positives

## Examples

### Example 1: Detecting Suspicious Process Creation on Linux

```yaml
title: Suspicious Reverse Shell via Bash
id: 8a3c5e7f-2d1b-4c9a-b6e8-3f7a2d1c4b5e
status: experimental
description: "sigma-rules-guide"
  Detects attempts to create reverse shells using bash, which is a common
  technique used by attackers after initial access to establish a persistent
  command and control channel.
references:
  - https://attack.mitre.org/techniques/T1059/004/
  - https://gtfobins.github.io/gtfobins/bash/
author: FAOS Security Team
date: 2026/02/24
tags:
  - attack.execution
  - attack.t1059.004

logsource:
  category: process_creation
  product: linux

detection:
  selection_bash:
    Image|endswith: '/bash'
    CommandLine|contains:
      - '/dev/tcp/'
      - '/dev/udp/'

  selection_redirect:
    CommandLine|contains:
      - '>&'
      - '0>&1'
      - '1>&0'

  condition: selection_bash and selection_redirect

falsepositives:
  - Legitimate network health check scripts using /dev/tcp
  - Developer testing scripts

level: high
```

### Example 2: Detecting Cloud API Abuse in GCP Audit Logs

```yaml
title: GCP Service Account Key Creation
id: 3b2a1c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
status: experimental
description: "sigma-rules-guide"
  Detects the creation of service account keys in GCP. Service account key
  creation is a persistence technique that allows long-lived credentials
  to be used outside of GCP. Organizations should prefer Workload Identity
  over service account keys.
references:
  - https://attack.mitre.org/techniques/T1098/001/
  - https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys
author: FAOS Security Team
date: 2026/02/24
tags:
  - attack.persistence
  - attack.t1098.001
  - attack.t1078.004

logsource:
  product: gcp
  service: gcp.audit

detection:
  selection:
    gcp.audit.method_name:
      - 'google.iam.admin.v1.CreateServiceAccountKey'
      - 'CreateServiceAccountKey'

  filter_automation:
    gcp.audit.authentication_info.principal_email|endswith:
      - '.gserviceaccount.com'
      - '@iam.gserviceaccount.com'

  condition: selection and not filter_automation

falsepositives:
  - Terraform or Pulumi provisioning service account keys
  - Legitimate administrative key rotation

level: high
```

### Example 3: Aggregation-Based Detection for Brute Force

```yaml
title: SSH Brute Force Attempt
id: 7d8e9f0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a
status: test
description: "sigma-rules-guide"
  Detects multiple failed SSH authentication attempts from a single source IP
  within a short time window, indicating a potential brute force attack.
references:
  - https://attack.mitre.org/techniques/T1110/001/
author: FAOS Security Team
date: 2026/02/24
tags:
  - attack.credential_access
  - attack.t1110.001

logsource:
  product: linux
  service: sshd

detection:
  selection:
    EventType: 'failed'
    Service: 'sshd'

  timeframe: 5m
  condition: selection | count(SourceIP) > 10

falsepositives:
  - Misconfigured SSH clients with wrong credentials
  - Scanning from authorized vulnerability assessment tools

level: high
```

## Best Practices

### Do This

- Use UUIDv4 for rule IDs to ensure global uniqueness
- Include at least one reference URL (threat report, ATT&CK technique)
- Write descriptive `falsepositives` entries to help analysts tune the rule
- Start rules at `experimental` status and promote to `test` then `stable` after validation
- Use field modifiers (`|contains`, `|endswith`, `|re`) for flexible matching
- Include filter conditions to reduce false positives from known-good behavior
- Tag every rule with ATT&CK tactics and techniques
- Version control your rules alongside your detection engineering pipeline
- Test rules against both true-positive and true-negative sample logs

### Don't Do This

- Do not skip the `falsepositives` field -- even "none known" is better than omitting it
- Do not use `status: stable` for untested rules
- Do not write overly broad selections without filters (e.g., matching all process creation)
- Do not hardcode SIEM-specific query syntax in Sigma rules
- Do not forget the `level` field -- it drives alert prioritization
- Do not use regexes when simpler field modifiers (`|contains`, `|startswith`) suffice
- Do not ignore the `logsource` section -- incorrect log source mapping causes silent failures

## Security Checklist

- [ ] Rule has a unique UUIDv4 `id` field
- [ ] Rule is tagged with relevant MITRE ATT&CK tactics and techniques
- [ ] Rule includes a meaningful `description` explaining the threat context
- [ ] Detection logic has both `selection` and `filter` conditions where appropriate
- [ ] `falsepositives` field lists known benign triggers
- [ ] Rule has been tested against sample logs (true positive and true negative)
- [ ] `level` is set appropriately (not everything is `critical`)
- [ ] Rule passes `sigma check` syntax validation
- [ ] Rule converts successfully to target SIEM query language
- [ ] Rule is tracked in version control with change history
- [ ] Rule performance impact has been evaluated (avoid expensive regex on high-volume logs)
- [ ] Rule has a designated owner for ongoing tuning and maintenance

## Related Skills

- @mitre-attck-reference -- ATT&CK technique IDs and tactic mappings for detection rules
- @ir-playbook-templates -- incident response playbooks triggered by Sigma detections
- @cve-epss-guide -- correlating vulnerability data with detection coverage

## Additional Resources

- [SigmaHQ GitHub Repository](https://github.com/SigmaHQ/sigma) -- 3000+ community detection rules
- [Sigma Specification](https://sigmahq.io/docs/guide/getting-started.html) -- official rule format documentation
- [pySigma](https://github.com/SigmaHQ/pySigma) -- Python library for Sigma rule processing and conversion
- [MITRE ATT&CK Navigator](https://mitre-attack.github.io/attack-navigator/) -- visualize detection coverage
- [Sigma Rule Creation Guide](https://sigmahq.io/docs/guide/rules.html) -- detailed field-by-field guide
- [Uncoder.IO](https://uncoder.io/) -- online Sigma rule converter for multiple SIEM platforms
