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

# DevSecOps Metrics Dashboard — API Reference

## Prometheus Queries (PromQL)

```promql
# Total open vulnerabilities
devsecops_vulnerabilities_total

# Critical vulnerabilities
devsecops_vulnerabilities_total{severity="critical"}

# MTTR p50 in days
histogram_quantile(0.5, rate(devsecops_mttr_seconds_bucket[30d])) / 86400

# MTTR p95 in days
histogram_quantile(0.95, rate(devsecops_mttr_seconds_bucket[30d])) / 86400

# Findings resolved rate (30d)
increase(devsecops_findings_resolved_total[30d])

# Pipeline block rate
rate(devsecops_pipeline_blocks_total[7d])

# Security debt score
sum(devsecops_vulnerabilities_total{severity="critical"}) * 10
  + sum(devsecops_vulnerabilities_total{severity="high"}) * 5
  + sum(devsecops_vulnerabilities_total{severity="medium"}) * 2
```

## Prometheus Pushgateway

```bash
# Push metrics
cat <<EOF | curl --data-binary @- http://pushgw:9091/metrics/job/devsecops
devsecops_vulnerabilities_total{severity="critical",scanner="semgrep"} 3
devsecops_vulnerabilities_total{severity="high",scanner="semgrep"} 12
devsecops_scan_coverage_percent{scan_type="sast"} 95
devsecops_scan_coverage_percent{scan_type="sca"} 87
EOF
```

## Grafana API

```bash
# Create dashboard
curl -X POST http://grafana:3000/api/dashboards/db \
  -H "Authorization: Bearer $GRAFANA_TOKEN" \
  -H "Content-Type: application/json" \
  -d @dashboard.json

# Create alert rule
curl -X POST http://grafana:3000/api/v1/provisioning/alert-rules \
  -H "Authorization: Bearer $GRAFANA_TOKEN" \
  -d @alert-rule.json
```

## Key DevSecOps KPIs

| KPI | Target | Measurement |
|-----|--------|-------------|
| MTTD | < 24 hours | Time from introduction to detection |
| MTTR (Critical) | < 24 hours | Detection to deployed fix |
| MTTR (High) | < 7 days | Detection to deployed fix |
| Scan Coverage | > 95% | Repos with active scanning |
| Security Debt | < 50 | Weighted open findings score |
| Fix Rate | > 80% | Fixed vs. accepted risk |
| FP Rate | < 15% | False positives vs. total |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Metrics collected/calculated |
| 1 | KPI targets not met |
| 2 | Collection error |
