<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->

# Detection Development Reference

Deep reference for detection-as-code pipelines, Sigma rule authoring, and CI/CD deployment.
Parent skill: [../SKILL.md](../SKILL.md)

---

## Detection-as-Code Pipeline Architecture

Detection-as-code treats detection rules as software artifacts: version-controlled, peer-reviewed, tested, and deployed through CI/CD.

### Pipeline Stages

```
Author → Lint → Test → Review → Deploy → Monitor
  │        │      │       │        │         │
  │        │      │       │        │         └─ Track FP rate, hit rate, latency
  │        │      │       │        └─ Push to SIEM (Splunk/Elastic/Sentinel)
  │        │      │       └─ Peer review (2 approvers minimum)
  │        │      └─ Validate against sample logs + adversary emulation
  │        └─ sigma check (syntax), custom linters (field coverage)
  └─ Write Sigma YAML in feature branch
```

### Repository Structure

```
detections/
├── rules/
│   ├── process_creation/
│   │   ├── proc_creation_win_suspicious_net_user.yml
│   │   └── proc_creation_win_mimikatz_execution.yml
│   ├── network_connection/
│   │   └── net_connection_c2_beacon_interval.yml
│   └── authentication/
│       └── auth_brute_force_single_source.yml
├── tests/
│   ├── fixtures/           # Sample log events (JSON/EVTX)
│   └── validation/         # Automated test scripts
├── pipelines/
│   ├── splunk_cim.yml      # Sigma pipeline for Splunk CIM
│   └── ecs_windows.yml     # Sigma pipeline for ECS
├── .github/workflows/
│   └── detection-ci.yml    # CI pipeline definition
└── docs/
    └── playbooks/          # Response playbooks per rule
```

---

## Sigma Rule Authoring Best Practices

### Rule Structure Checklist

| Element | Requirement | Example |
|---------|------------|---------|
| `title` | Verb + noun, describes behavior | "Suspicious LSASS Access via Process Injection" |
| `id` | UUID v4, globally unique | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |
| `status` | Start at `experimental`, promote to `test` → `stable` | `experimental` |
| `description` | One sentence: what + why it matters | "Detects process injection into LSASS..." |
| `logsource` | Category + product, no hardcoded index names | `category: process_access`, `product: windows` |
| `detection` | Named selections, readable condition | `selection_target` AND `selection_method` |
| `falsepositives` | Specific scenarios, never "legitimate activity" | "AV real-time scanning of LSASS" |
| `level` | Based on confidence × impact | `high` |
| `tags` | MITRE ATT&CK technique IDs | `attack.t1003.001` |

### Detection Logic Patterns

**Simple selection:**
```yaml
detection:
  selection:
    Image|endswith: '\rundll32.exe'
    CommandLine|contains|all:
      - 'javascript:'
      - 'http'
  condition: selection
```

**Exclusion pattern (reduce FPs):**
```yaml
detection:
  selection:
    ParentImage|endswith: '\explorer.exe'
    Image|endswith: '\cmd.exe'
  filter_legitimate:
    CommandLine|contains:
      - 'C:\Program Files'
      - 'C:\Windows\System32'
  condition: selection and not filter_legitimate
```

**Aggregation (threshold detection):**
```yaml
detection:
  selection:
    EventID: 4625
  timeframe: 5m
  condition: selection | count(TargetUserName) by SourceIP > 10
```

### Naming Conventions

```
{logsource_category}_{product}_{description}.yml

Examples:
  proc_creation_win_suspicious_certutil_download.yml
  net_connection_dns_tunneling_high_entropy.yml
  file_event_linux_cron_modification.yml
```

---

## CI/CD Integration for Detection Deployment

### GitHub Actions Pipeline

```yaml
name: Detection CI/CD
on:
  pull_request:
    paths: ['rules/**']
  push:
    branches: [main]
    paths: ['rules/**']

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install sigma-cli
        run: pip install sigma-cli pysigma-backend-splunk pysigma-backend-elasticsearch

      - name: Lint rules
        run: |
          sigma check rules/ --fail-on-error
          # Custom field coverage check
          python scripts/check_required_fields.py rules/

      - name: Convert to Splunk SPL
        run: sigma convert -t splunk -p splunk_cim rules/ -o output/splunk/

      - name: Convert to Elastic EQL
        run: sigma convert -t elasticsearch -p ecs_windows rules/ -o output/elastic/

  deploy:
    needs: validate
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Splunk
        run: python scripts/deploy_splunk.py --input output/splunk/
        env:
          SPLUNK_URL: ${{ secrets.SPLUNK_URL }}
          SPLUNK_TOKEN: ${{ secrets.SPLUNK_TOKEN }}
```

### Deployment Targets

| SIEM | Method | Command |
|------|--------|---------|
| Splunk | REST API (saved searches) | `sigma convert -t splunk -p splunk_cim rule.yml` |
| Elastic | Kibana Detection Rules API | `sigma convert -t elasticsearch -p ecs_windows rule.yml` |
| Sentinel | KQL Analytics Rules | `sigma convert -t microsoft365defender rule.yml` |
| Chronicle | YARA-L | `sigma convert -t chronicle rule.yml` |
| QRadar | AQL | `sigma convert -t qradar rule.yml` |

---

## Rule Quality Scoring and Review Checklist

### Quality Score (0–10)

| Criteria | Points | Description |
|----------|--------|-------------|
| ATT&CK mapping | 2 | Valid technique ID(s) in tags |
| Specific false positives | 2 | Named scenarios, not generic |
| Test coverage | 2 | Sample logs that trigger + don't trigger |
| Log source availability | 2 | Confirmed the required logs are collected |
| Playbook linked | 1 | Response playbook exists for the alert |
| Performance validated | 1 | Query runs under latency threshold in prod |

### Peer Review Checklist

```markdown
- [ ] Title clearly describes detected behavior
- [ ] Description explains attacker intent/goal
- [ ] Detection logic is correct (no logic errors in condition)
- [ ] At least one exclusion filter for known legitimate use
- [ ] False positives list is specific and actionable
- [ ] Level matches confidence × impact matrix
- [ ] ATT&CK tags are accurate (correct technique, not just tactic)
- [ ] Test logs provided (true positive + true negative)
- [ ] No hardcoded environment-specific values (index names, hostnames)
- [ ] Performance: no unbounded wildcards, reasonable timeframes
```

### Maturity Promotion Criteria

| Stage | Criteria |
|-------|----------|
| `experimental` | Written, linted, basic test | 
| `test` | Deployed to staging, 7-day FP observation |
| `stable` | < 5% FP rate over 30 days, playbook attached, tuned |
