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

## Grafana HTTP API

```python
import requests

GRAFANA_URL = "http://grafana:3000"
GRAFANA_TOKEN = "Bearer glsa_XXXXXXXXXXXX"

# Get dashboard by UID
resp = requests.get(f"{GRAFANA_URL}/api/dashboards/uid/soc-overview",
    headers={"Authorization": GRAFANA_TOKEN})

# Create snapshot
resp = requests.post(f"{GRAFANA_URL}/api/snapshots", headers={
    "Authorization": GRAFANA_TOKEN,
}, json={"dashboard": dashboard_json, "expires": 3600})

# Create annotation (mark incident on timeline)
requests.post(f"{GRAFANA_URL}/api/annotations", headers={
    "Authorization": GRAFANA_TOKEN,
}, json={"text": "INC-001 detected", "tags": ["incident"], "time": epoch_ms})
```

## Prometheus Pushgateway

```python
# Push metrics
requests.post("http://pushgateway:9091/metrics/job/soc_dashboard", data="""
soc_mttd_minutes 12.5
soc_mttr_minutes 45.2
soc_alerts_24h 342
soc_sla_compliance_pct 94.2
""", headers={"Content-Type": "text/plain"})

# Delete job metrics
requests.delete("http://pushgateway:9091/metrics/job/soc_dashboard")
```

## Elasticsearch Index API (Kibana Backend)

```python
from elasticsearch import Elasticsearch

es = Elasticsearch("https://elastic:9200", api_key="base64key")

es.index(index="soc-metrics-2026.03", document={
    "@timestamp": "2026-03-18T00:00:00Z",
    "mttd_minutes": 12.5,
    "mttr_minutes": 45.2,
    "alerts_24h": 342,
})
```

## SOC KPI Definitions

| Metric | Definition | Target |
|--------|-----------|--------|
| MTTD | Mean Time to Detect — alert creation to analyst awareness | < 15 min |
| MTTR | Mean Time to Respond — detection to containment | < 60 min |
| FP Rate | False positives / total alerts | < 25% |
| SLA Compliance | Incidents resolved within SLA / total incidents | > 95% |
| Automation Rate | Automated actions / total response actions | > 40% |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Metrics collected/pushed successfully |
| 1 | Partial metric collection |
| 2 | Dashboard push failed |
