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

# API Reference — Measuring Detection Engineering Metrics

## Core Metrics

| Metric | Type | Formula |
|---|---|---|
| MTTD | Duration | `avg(alert_timestamp - attack_timestamp)` |
| Coverage ratio | Percentage | `techniques_covered / techniques_relevant × 100` |
| Rule fidelity | Percentage | `true_positives / (true_positives + false_positives) × 100` |
| FP rate | Percentage | `false_positives / total_alerts × 100` |
| Gap closure rate | Percentage | `gaps_closed / gaps_found × 100` per quarter |
| Rule velocity | Count/time | New rules deployed per sprint/month |

## Maturity Model Dimensions

| Dimension | Level 1 | Level 3 | Level 5 |
|---|---|---|---|
| Coverage | < 30% | 50–70% | > 80% |
| Speed (MTTD) | > 30 min | < 10 min | < 2 min |
| Fidelity | > 20% FP | < 5% FP | < 1% FP |
| Automation | Manual | Semi-automated | Full CI/CD |
| Validation | Never tested | Quarterly atomic tests | Continuous |

## Agent Script

```bash
# Calculate metrics from alert data
node agent.js calculate --alerts alerts.json --coverage layer.json --period 30

# Calculate MTTD from exercise
node agent.js mttd --exercise-results exercise.json

# Calculate per-rule fidelity
node agent.js fidelity --alerts alerts.json --verified-incidents incidents.json

# Assess maturity level
node agent.js maturity --coverage-ratio 0.65 --avg-mttd 180 --fp-rate 0.03 --has-validation
```
