# API-Dokumentation — barox SecPen

Die API ist **intern**: Sie wird ausschliesslich von der eigenen Oberfläche
verwendet, ist an die Session gebunden (Cookie + CSRF-Token) und kennt bewusst
**keine** dauerhaften API-Tokens. Die Anwendung soll nicht von aussen
automatisierbar sein — ein Scan setzt eine bewusste, protokollierte
Benutzerhandlung voraus.

## Authentifizierung

Alle Endpunkte laufen über die Middleware `web, auth`. Schreibende Anfragen
benötigen den CSRF-Token:

```
X-CSRF-TOKEN: <Inhalt von <meta name="csrf-token">>
Accept: application/json
```

Rate Limit: 120 Anfragen pro Minute und Benutzer.

---

## GET /api/status/overview

Aggregierter Zustand für das Dashboard.

```json
{
  "server_time": "2025-01-13T10:07:12+01:00",
  "emergency_stop": false,
  "pending_approvals": 1,
  "running": [
    {
      "id": 42,
      "uuid": "0f0a…",
      "name": "Vorabprüfung Ringsegment A",
      "status": "running",
      "status_label": "Läuft",
      "profile": "2 - Service Discovery",
      "progress": 60,
      "stage": null,
      "runtime_seconds": 432,
      "targets": [
        {
          "hostname": "switch-lab-01",
          "ip": "192.168.10.11",
          "status": "running",
          "cpu": 88.0,
          "rtt": 412.5,
          "loss": 0.0,
          "http": true,
          "snmp": true,
          "assessment": "warning",
          "measured_at": "2025-01-13T10:07:10+01:00"
        }
      ]
    }
  ]
}
```

Berechtigung: `scan.view`.

---

## GET /scans/{scan}/live

Live-Daten eines einzelnen Scans. Optionaler Parameter `since` (ISO-8601)
liefert nur neuere Ereignisse.

```json
{
  "status": "running",
  "status_label": "Läuft",
  "progress": 60,
  "current_stage": "medium",
  "targets_completed": 3,
  "targets_total": 5,
  "runtime_seconds": 432,
  "cancel_requested": false,
  "abort_reason": null,
  "events": [
    { "at": "2025-01-13T10:07:12+01:00", "time": "10:07:12",
      "type": "health.warning", "severity": "warning",
      "message": "CPU-Auslastung über Grenzwert (88 von 90)" }
  ],
  "metrics": [
    { "switch_id": 7, "hostname": "switch-lab-01",
      "points": [ { "t": "…", "phase": "scan", "cpu": 88.0, "rtt": 412.5,
                    "loss": 0.0, "http": true, "snmp": true,
                    "uptime": 86400, "tc": 3, "assessment": "warning" } ] }
  ],
  "server_time": "2025-01-13T10:07:15+01:00"
}
```

Berechtigung: `scan.view` (Policy `ScanJobPolicy::view`).

---

## POST /scans/preview

Prüft Ziele und Profil, bevor ein Auftrag angelegt wird. Führt **keinen** Scan
aus und legt nichts an.

Anfrage (Formulardaten):

```
project_id=3
scan_profile_id=2
switch_ids[]=7
switch_ids[]=8
```

Antwort:

```json
{
  "project_authorized": true,
  "project_problem": null,
  "blocked": 1,
  "targets": [
    { "id": 7, "hostname": "switch-lab-01", "ip": "192.168.10.11",
      "allowed": true, "entry": "192.168.10.0/24", "label": "Labornetz",
      "authorization_reference": "AUFTRAG-2025-001",
      "checked_at": "2025-01-13T10:00:00+01:00" },
    { "id": 8, "hostname": "switch-prod-04", "ip": "10.20.0.4",
      "allowed": false, "reason_code": "not_in_allowlist",
      "reason": "Die Adresse ist in keiner gültigen Allowlist enthalten. …" }
  ],
  "profile": {
    "name": "2 - Service Discovery", "intensity": 2,
    "intensity_label": "Schonend", "requires_approval": false,
    "requires_window": false, "estimated_duration_seconds": 420,
    "thresholds": { "cpu_percent": 85, "packet_loss_percent": 15 }
  }
}
```

Berechtigung: `scan.create`.

---

## Fehlerformat

```json
{ "message": "Der Not-Aus ist aktiv. Es können keine Scans gestartet werden." }
```

| Status | Bedeutung |
|---|---|
| 401 | nicht angemeldet |
| 403 | Berechtigung fehlt |
| 419 | CSRF-Token fehlt oder Session abgelaufen |
| 422 | Validierungsfehler (`errors` je Feld) |
| 423 | Not-Aus aktiv |
| 429 | Rate Limit erreicht |

Fehlermeldungen enthalten in Produktion **niemals** Stack Traces, Dateipfade
oder Zugangsdaten.

---

## Konsolenbefehle

Für Automatisierung auf dem Server (nicht über HTTP erreichbar):

| Befehl | Zweck |
|---|---|
| `barox:preflight [--strict]` | Installations- und Sicherheitsprüfung |
| `barox:health-tick [--loop] [--interval=5]` | Messung und automatischer Abbruch |
| `barox:reap-scans [--dry-run]` | verwaiste Prozesse und Aufträge |
| `barox:emergency-stop on|off [--reason=]` | Not-Aus |
| `barox:audit-verify [--from=ID]` | Hash-Kette des Audit-Logs prüfen |