# Troubleshooting — barox SecPen

Erste Anlaufstelle bei jedem Problem:

```bash
sudo -u barox php /var/www/html/barox-secpen/artisan barox:preflight
```

---

## 1 Scans starten nicht

**Auftrag bleibt in „In Warteschlange“**

```bash
systemctl status barox-secpen-worker
journalctl -u barox-secpen-worker -n 100 --no-pager
php artisan queue:failed
```

Häufige Ursachen:

| Ursache | Prüfung | Abhilfe |
|---|---|---|
| Worker läuft nicht | `systemctl status barox-secpen-worker` | `systemctl start barox-secpen-worker` |
| Falsche Queue | Unit verarbeitet `scans,default`? | Unit prüfen |
| `QUEUE_CONNECTION=sync` | `php artisan tinker --execute="echo config('queue.default');"` | auf `database` oder `redis` stellen, `config:cache` |
| Alter Code im Worker | nach Deploy | `php artisan queue:restart` und Dienst neu starten |
| Not-Aus aktiv | Banner in der Oberfläche | `barox:emergency-stop off` |

**„Es laufen bereits N Scans“** — Limit `NMAP_MAX_PARALLEL_JOBS` erreicht.
Hängende Aufträge finden: `php artisan barox:reap-scans --dry-run`.

---

## 2 Nmap-Probleme

**„Nmap wurde unter … nicht gefunden“ / „liegt ausserhalb der freigegebenen Verzeichnisse“**

```bash
which nmap                      # Pfad in NMAP_BINARY eintragen
ls -l /usr/bin/nmap
```

Der Pfad muss nach `realpath()` in einem Verzeichnis aus
`config/scanner.binary_allowed_dirs` liegen (`/usr/bin`, `/bin`,
`/usr/local/bin`, `/usr/sbin`, `/sbin`).

**SYN- oder UDP-Scan schlägt fehl**

```bash
getcap /usr/bin/nmap
systemctl show barox-secpen-worker -p AmbientCapabilities
```

Siehe `deploy/nmap-capabilities.md`. `www-data` bekommt **keine** Rechte.

**Scan läuft, liefert aber keine XML-Datei**

```bash
ls -la /var/lib/barox-secpen/scans/<scan-uuid>/
cat /var/lib/barox-secpen/scans/<scan-uuid>/*.stderr.log
```

Meist fehlende Schreibrechte: `chown -R barox:barox /var/lib/barox-secpen`.

**„Das Argument … ist gesperrt“** — Das Scanprofil enthält eine unzulässige
Option. Das ist eine gewollte Schutzreaktion. Profil unter *Scanprofile*
prüfen; die erzeugte Argumentliste steht auf der Profilseite.

---

## 3 Health-Monitoring liefert keine Werte

**CPU, Speicher und Temperatur bleiben leer**

1. Ist dem Gerät ein **Geräteprofil** zugewiesen?
2. Sind **Zugangsdaten** und **SNMP-Version** hinterlegt?
3. Manuell prüfen:

```bash
snmpget -v2c -c <community> -On <ip> 1.3.6.1.2.1.1.3.0
snmpwalk -v2c -c <community> <ip> 1.3.6.1.4.1 | head -40
```

Antwortet der Switch, stimmen die OIDs im Profil nicht — im Geräteprofil
anpassen. Antwortet er nicht, prüfen: SNMP aktiviert? Community korrekt?
ACL auf dem Switch? Firewall auf 161/UDP?

**Latenz und Paketverlust fehlen**

```bash
sudo -u barox /bin/ping -n -c 3 -W 2 <ip>
getcap /bin/ping
```

**HTTPS meldet dauerhaft „nicht erreichbar“**

Prüfpfad und Port am Gerät kontrollieren; erwartete Statuscodes stehen in
`config/barox.health.http.expected_status` (Standard 200, 301, 302, 401, 403).
Selbstsignierte Zertifikate sind zugelassen (`HEALTH_HTTP_VERIFY_TLS=false`).

---

## 4 Scan wird sofort abgebrochen

Die Zeitachse auf der Scan-Detailseite nennt den Grund. Typisch:

| Grund | Bedeutung | Vorgehen |
|---|---|---|
| `snmp_unreachable` | SNMP nicht erreichbar — oft Konfigurationsfehler, nicht Überlast | Zugangsdaten prüfen; ggf. Grenzwert im Profil anheben |
| `reboot_detected` | Uptime zurückgesprungen | Gerät prüfen; das ist ein echtes Ergebnis |
| `packet_loss` | Verlust über Grenzwert | Zwischenstrecke prüfen, dann Rate senken |
| `cpu_sustained_high` | CPU dauerhaft über Grenzwert | erwartetes Ergebnis bei Belastungstests |
| `maintenance_window_closed` | Fenster abgelaufen | Fenster verlängern |
| `orphaned_process` | Worker hat kein Lebenszeichen gesendet | Worker-Log prüfen |

**Fehlalarm bei SNMP:** Wird ein Gerät ohne SNMP geprüft, sollte im Profil oder
am Gerät `snmp_consecutive_failures` hoch gesetzt oder auf die SNMP-Zuordnung
verzichtet werden.

---

## 5 Nessus

| Meldung | Ursache | Abhilfe |
|---|---|---|
| „Der Nessus-Server ist nicht erreichbar“ | Netz, Port, TLS | `curl -k https://<host>:8834/server/status` |
| „Anmeldung fehlgeschlagen“ | Schlüssel falsch oder rotiert | Schlüssel neu eintragen (leeres Feld = unverändert) |
| „Die Policy ist nicht freigegeben …“ | Guard beanstandet oder Freigabe fehlt | Policies abgleichen, prüfen, freigeben |
| „Export wurde nicht rechtzeitig bereitgestellt“ | Server ausgelastet | später erneut; `NESSUS_MAX_POLL_MINUTES` erhöhen |
| TLS-Fehler | selbstsigniertes Zertifikat | CA-Bundle hinterlegen oder TLS-Prüfung bewusst abschalten |

---

## 6 Anmeldung

**Entra ID: „Der Aussteller des Tokens stimmt nicht …“** — falsche
`AUTH_OIDC_TENANT_ID`.

**„Konten der Domain … sind nicht freigegeben“** — `AUTH_OIDC_ALLOWED_DOMAINS`.

**„Der Anmeldevorgang konnte nicht zugeordnet werden (state)“** — Session
verloren: Cookie-Domain, `SESSION_SECURE_COOKIE` und Uhrzeit des Servers prüfen.

**Konto gesperrt** — nach `AUTH_MAX_LOGIN_ATTEMPTS` Fehlversuchen. Entsperren
unter *Benutzer* oder abwarten (`AUTH_LOCKOUT_MINUTES`).

**Alle Administratoren ausgesperrt:**

```bash
php artisan tinker
>>> $u = App\Models\User::where('email','…')->first();
>>> $u->forceFill(['is_active'=>true,'locked_until'=>null,'password'=>bcrypt('NeuesLangesPasswort!2025')])->save();
>>> $u->roles()->syncWithoutDetaching([App\Models\Role::where('key','administrator')->value('id')]);
```

---

## 7 Oberfläche

**Fehler 500 nach Deploy**

```bash
tail -50 storage/logs/barox-secpen-*.log
php artisan config:clear && php artisan config:cache
php artisan route:clear && php artisan route:cache
php artisan view:clear && php artisan view:cache
chown -R barox:barox storage bootstrap/cache
```

**Stile oder Schriften fehlen** — liegen die Dateien unter `public/assets/`?
Prüfen, ob die CSP in der Browser-Konsole blockiert (dann fehlt vermutlich eine
lokale Kopie und es wird eine externe Quelle angefordert).

**Live-Aktualisierung steht** — `/api/status/overview` im Browser-Netzwerktab
prüfen: 419 bedeutet abgelaufene Session, 429 Rate Limit.

---

## 8 Datenbank und Audit

**„Audit-Eintrag konnte nicht geschrieben werden“** — sichtbar in
`storage/logs/audit-*.log`. Meist fehlende Rechte, wenn `UPDATE`/`DELETE`
korrekt entzogen, `INSERT` aber ebenfalls fehlt.

**Hash-Kette meldet Abweichung**

```bash
php artisan barox:audit-verify
```

Ursachen: direkte Änderung in der Datenbank, Teil-Restore oder Löschung. Der
Zeitpunkt lässt sich über die gemeldete ID eingrenzen. Nach einem vollständigen,
konsistenten Restore ist die Kette wieder stimmig.

**Migration schlägt fehl (Foreign Key)** — Reihenfolge einhalten; im Zweifel
mit leerer Datenbank und `php artisan migrate:fresh --seed` in einer Testumgebung
prüfen (niemals produktiv).

---

## 9 Diagnosepaket für den Support

```bash
{
  php artisan --version
  php artisan barox:preflight
  systemctl status barox-secpen-worker barox-secpen-health --no-pager
  tail -100 storage/logs/barox-secpen-*.log
  tail -50 storage/logs/scanner-*.log
} > /tmp/secpen-diagnose.txt 2>&1
```

Die Ausgabe enthält keine Zugangsdaten — der `LogRedactor` entfernt sie bereits
beim Schreiben. Vor dem Versand trotzdem kurz durchsehen.