---
name: mhaggis/detection-yaml-engineer
source: https://app.decimal.ai/s/mhaggis-detection-yaml-engineer@1/SKILL.md
source_sha256: 7f05e67c4e97
---

# Detection YAML Engineer

You are an expert at creating high-quality detection rule files for security content repositories.

## Configuration

- `$SECURITY_CONTENT_PATH` - Path to detection content repo
- `$SIEM_PLATFORM` - Target: `splunk`, `sigma`, `elastic`, `sentinel`
- `$VALIDATION_TOOL` - Validation command (e.g., `contentctl validate`, `sigma check`)

## Multi-Platform Templates

### Splunk security_content YAML

```yaml
name: Platform_Technique_Description
id: <UUID>
version: 1
date: 'YYYY-MM-DD'
author: Detection Author
status: production
type: TTP
description: Clear description of what and why.
data_source:
- Sysmon EventID 1
search: |
  | tstats `security_content_summariesonly` count min(_time) as firstTime max(_time) as lastTime
    from datamodel=Endpoint.Processes
    where Processes.process_name="suspicious.exe"
    by Processes.dest Processes.user Processes.process_name
  | `drop_dm_object_name(Processes)`
  | `security_content_ctime(firstTime)`
  | `security_content_ctime(lastTime)`
  | `detection_name_filter`
how_to_implement: Data requirements.
known_false_positives: Expected benign triggers.
references:
- https://attack.mitre.org/techniques/TXXXX/
rba:
  message: $process_name$ executed on $dest$ by $user$
  risk_objects:
  - field: dest
    type: system
    score: 50
  - field: user
    type: user
    score: 50
tags:
  analytic_story:
  - Story Name
  asset_type: Endpoint
  mitre_attack_id:
  - T1234.001
  product:
  - Splunk Enterprise
  - Splunk Enterprise Security
  - Splunk Cloud
  security_domain: endpoint
tests:
- name: True Positive Test
  attack_data:
  - data: https://media.githubusercontent.com/media/splunk/attack_data/master/datasets/...
    sourcetype: XmlWinEventLog:Microsoft-Windows-Sysmon/Operational
    source: XmlWinEventLog:Microsoft-Windows-Sysmon/Operational
```

### Sigma Rule

```yaml
title: Suspicious Process Execution
id: <UUID>
status: stable
level: high
description: Detects suspicious process execution.
author: Detection Author
date: YYYY/MM/DD
references:
- https://attack.mitre.org/techniques/TXXXX/
tags:
- attack.execution
- attack.t1059.001
logsource:
  category: process_creation
  product: windows
detection:
  selection:
    Image|endswith: '\suspicious.exe'
  condition: selection
falsepositives:
- Legitimate administrative use
```

### KQL Analytics Rule (Sentinel)

KQL rules for Sentinel can be defined as YAML for programmatic deployment via Sentinel Solutions or the Analytics Rules API:

```yaml
id: <UUID>
name: Suspicious Process Execution
description: Detects suspicious process execution patterns.
severity: High
requiredDataConnectors:
  - connectorId: MicrosoftThreatProtection
    dataTypes:
      - DeviceProcessEvents
queryFrequency: 1h
queryPeriod: 1h
triggerOperator: gt
triggerThreshold: 0
tactics:
  - Execution
relevantTechniques:
  - T1059.001
query: |
  DeviceProcessEvents
  | where FileName == "suspicious.exe"
  | where ProcessCommandLine has_any ("encoded", "hidden", "-nop")
  | project TimeGenerated, DeviceName, AccountName, FileName, ProcessCommandLine
entityMappings:
  - entityType: Host
    fieldMappings:
      - identifier: HostName
        columnName: DeviceName
  - entityType: Account
    fieldMappings:
      - identifier: Name
        columnName: AccountName
```

Or as inline KQL with comment headers for simpler workflows:

```kql
// Title: Suspicious Process Execution
// MITRE: T1059.001
DeviceProcessEvents
| where FileName == "suspicious.exe"
| where ProcessCommandLine has_any ("encoded", "hidden", "-nop")
| project TimeGenerated, DeviceName, AccountName, FileName, ProcessCommandLine
```

### Elastic Security Rule (TOML)

Elastic detection rules use TOML format in the [detection-rules](https://github.com/elastic/detection-rules) repository:

```toml
[metadata]
creation_date = "YYYY/MM/DD"
integration = ["endpoint"]
maturity = "production"
updated_date = "YYYY/MM/DD"

[rule]
author = ["Detection Author"]
description = "Detects suspicious process execution."
name = "Suspicious Process Execution"
risk_score = 73
rule_id = "<UUID>"
severity = "high"
tags = ["Domain: Endpoint", "OS: Windows", "Use Case: Threat Detection", "Tactic: Execution"]
type = "eql"
query = '''
process where host.os.type == "windows"
  and process.name : "suspicious.exe"
  and process.args : ("*encoded*", "*hidden*", "*-nop*")
'''

[[rule.threat]]
framework = "MITRE ATT&CK"

[[rule.threat.technique]]
id = "T1059"
name = "Command and Scripting Interpreter"
reference = "https://attack.mitre.org/techniques/T1059/"

[[rule.threat.technique.subtechnique]]
id = "T1059.001"
name = "PowerShell"
reference = "https://attack.mitre.org/techniques/T1059/001/"

[rule.threat.tactic]
id = "TA0002"
name = "Execution"
reference = "https://attack.mitre.org/tactics/TA0002/"
```

## Naming Conventions

- File name: `snake_case` of the detection name
- Detection name: `Platform_Technique_Description`
- Filter macro (Splunk): `detection_name_filter`

## Validation

Always validate before committing:
- **Splunk:** `contentctl validate` (in security_content venv)
- **Sigma:** `sigma check rule.yml` or `sigma convert -t <backend> rule.yml`
- **Elastic:** `python -m detection_rules validate-rule path/to/rule.toml` (in detection-rules repo)
- **Sentinel:** Test KQL in Log Analytics query editor; use `az sentinel alert-rule create` for deployment validation

## Common Mistakes to Avoid

### All Platforms
1. Missing or incorrect MITRE technique IDs
2. Generic descriptions that don't explain the specific behavior
3. No false positive guidance

### Splunk-Specific
4. Filter macro name doesn't match detection name (must be `snake_case(name)_filter`)
5. Data source names don't match repository conventions
6. RBA section in wrong location (should be top-level, not in tags)
7. Test data URLs that don't exist

### Sigma-Specific
8. Invalid logsource category (use standard categories: `process_creation`, `network_connection`, etc.)
9. Unsupported field modifiers for target backend

### Elastic-Specific
10. Wrong `type` for query language (use `eql` for EQL, `query` for KQL/Lucene, `threshold` for count-based)
11. Missing `[[rule.threat]]` MITRE mapping block

### Sentinel-Specific
12. Wrong table name (e.g., `DeviceProcessEvents` for MDE vs `SecurityEvent` for legacy agents)
13. Missing `entityMappings` for incident creation