# OpsAgent — Benutzerhandbuch

Managed Windows-Admin-Agent mit revisionsfestem Protokoll. Dieses Handbuch beschreibt die
Bedienung der zwei sichtbaren Teile: die **Konsole** (Vorfaelle + Freigaben) und den
**AD-Configurator** (Verzeichnis verstehen). Der Agent selbst laeuft unsichtbar als Dienst
auf den ueberwachten Windows-Servern.

> **Stand:** Phase 1 (Selbstheilung) + Phase AD-1 (AD-Configurator, read-only). Netzwerk-,
> Firewall- und AD-Schreibfunktionen folgen in spaeteren Phasen.

---

## 1. Anmeldung

Die Konsole ist mit einem API-Key geschuetzt. Auf der Demo-Instanz
(`https://opsagent.c3po42.de`) gibt der Betreuer den Key aus; in der Kundeninstallation
vergibt ihn die IT beim Setup. Ohne gueltigen Key liefert jede Ansicht „API-Key ungueltig".

---

## 2. Vorfaelle (Incident-Konsole)

Startseite der Konsole. Jeder Vorfall zeigt in einer Karte:

- **Titel + Schweregrad** — z. B. „Dienst 'W3SVC' gestoppt" (hoch/kritisch rot markiert).
- **Zeitpunkt, Agent, Vorfall-ID** — welcher ueberwachte Server, wann.
- **Diagnose** — die vermutete Ursache samt Quelle (`llm` = KI-Analyse ueber das
  KI-Gateway, `rule` = regelbasierter Fallback) und Konfidenz.
- **Aktion** — was der Agent getan hat, mit Erfolg (✓) oder Fehlschlag (✗).
- **Evidenz** (aufklappbar) — Logs, Ressourcen und letzte Aenderungen, auf denen die
  Diagnose beruht.

### Status eines Vorfalls

| Status | Bedeutung |
|---|---|
| `resolved` | Der Agent hat den Vorfall im Rahmen eines Playbooks selbst behoben. |
| `awaiting_confirm` | Die vorgeschlagene Aktion wartet auf Ihre **Freigabe** (Button in der Karte). |
| `escalated` | Automatik nicht moeglich/erschoepft — ein Mensch muss eingreifen. |
| `confirmed` | Sie haben eine wartende Aktion freigegeben. |

### Eine Aktion freigeben

Bei `awaiting_confirm` erscheint der Button **„Aktion freigeben"**. Ein Klick bestaetigt die
vorgeschlagene Massnahme; der Status wechselt auf `confirmed`. Aktionen mit dem Modus
`confirm` laufen niemals automatisch — das ist die Sicherheitsschwelle fuer alles, was
nicht ohne Aufsicht passieren soll.

---

## 3. AD-Configurator

Erreichbar oben ueber den Link **„→ AD-Configurator"** oder direkt unter `/ad.html`.
Read-only: Der Configurator **zeigt** das Active Directory, er aendert (in dieser Phase)
nichts.

### 3.1 Verzeichnis durchsuchen

1. **API-Key** eingeben.
2. **Root-DN** eintragen (z. B. `DC=klinik,DC=local`) und **„Baum laden"**.
3. Links erscheint der OU-Baum (Domain 🌐, Organisationseinheiten 📁, Benutzer 👤,
   Gruppen 👥, Computer 💻). Alternativ oben ins Suchfeld tippen und **„Suchen"**.

### 3.2 Objekt ansehen

Klick auf ein Objekt zeigt in der Mitte seine Attribute (DN, Kontoname, Abteilung …) und
rechts die **effektive Mitgliedschaft**:

- bei **Benutzer/Computer**: in welchen Gruppen das Objekt effektiv ist,
- bei **Gruppe**: welche Objekte effektiv darin sind.

### 3.3 Verschachtelung verstehen (der Kern)

Die effektive Mitgliedschaft wird **transitiv** aufgeloest — also inklusive Gruppen in
Gruppen, die Standardwerkzeuge nicht sichtbar machen. Zwei Darstellungen, oben umschaltbar:

- **Baum** — schnelle, textliche Liste.
- **Graph** — Knoten-und-Kanten-Ansicht; gut fuer verschachtelte Netze.

Besonderheiten, die farblich hervorgehoben werden:

- **Primaergruppe** (orange, „(Primaergruppe)") — steht im AD nicht in der normalen
  Mitgliederliste und wird trotzdem korrekt mitgezeigt.
- **Zyklus-Warnung** (rot) — wenn Gruppen sich gegenseitig enthalten (im AD anlegbar); der
  Configurator faengt das ab, statt sich zu verrennen.

---

## 4. Sicherheitsprinzipien (warum das Tool vorsichtig ist)

- **Aktionen nur aus einer Freigabe-Liste.** Die KI **waehlt** eine vordefinierte Massnahme
  (Playbook), sie kann keine freien Befehle ausfuehren.
- **`confirm` vor riskanten Schritten.** Alles Kritische wartet auf menschliche Freigabe.
- **Revisionsfestes Protokoll.** Jeder Schritt (Erkennung → Diagnose → Aktion) wird in einer
  Hash-Kette festgehalten; nachtraegliche Manipulation faellt bei der Pruefung auf. Fuer
  Nachweispflichten ist genau das der Mehrwert.
- **Der Agent meldet nur nach aussen.** Von der Konsole gehen keine Verbindungen ins
  Kundennetz hinein.

---

## 5. Haeufige Fragen

**Warum startet der Agent einen Dienst nicht einfach neu?**
Wenn die Ursache nicht per Neustart behebbar ist (z. B. volle Festplatte) oder die
Wiederholungsgrenze erreicht wurde, eskaliert der Agent bewusst an einen Menschen, statt in
einer Neustart-Schleife zu haengen.

**Die Demo zeigt Klinik-Daten — sind die echt?**
Nein. Die Demo-Instanz laeuft gegen ein erfundenes Beispiel-Verzeichnis. In der
Kundeninstallation verbindet sich derselbe Configurator ueber LDAP mit dem echten
Verzeichnis.

**Kann der AD-Configurator schon Konten anlegen/aendern?**
In dieser Phase nicht — er ist read-only. Schreibfunktionen (mit Vorschau der Auswirkung +
Freigabe + Protokoll) kommen in den naechsten Phasen.