glpi-neural-brain/DOCKER-CONTROLLER-V9.md

Docker Controller v9

Ziel

Ein explizit freigegebener Source Agent kann zusätzlich als Host-Docker-Controller arbeiten. Der Agent spricht lokal mit /var/run/docker.sock; das Brain bleibt Policy-, Queue-, Audit- und UI-Authority. Docker.sock ist eine hochprivilegierte Host-Schnittstelle. Deshalb ist die Controller-Schicht standardmäßig vollständig deaktiviert und verwendet keine freie Shell-/Exec-Schnittstelle für autonome Brain-Entscheidungen.

Sicherheitsmodell

Standardzustand:

• Controller-Hauptschalter: aus
• autonome Controller-Jobs: aus
• globaler Dry-Run: an
• destruktive Aktionen: aus
• maximale Parallelität: 1
• maximale zentrale Jobdauer: 10m
• erlaubtes Standardimage: curlimages/curl:
• Brain-/Source-Agent-Container sind standardmäßig geschützt

Der Agent prüft die zentrale Autorisierung während eines laufenden Jobs alle zwei Sekunden erneut. Das Abschalten des Hauptschalters beendet daher nicht nur neue Claims, sondern entzieht auch laufenden Jobs ihre Autorisierung. Dasselbe gilt für das Abschalten autonomer beziehungsweise destruktiver Freigaben, soweit der laufende Job davon abhängt.

Autonome Jobs dürfen ausschließlich aus vorher vom Operator angelegten und als autonomous freigegebenen Profilen stammen. Zulässige autonome Typen sind:

• evidence_http_probe
• health_recovery
• compute_capacity_compose
• compose_smoke_test

Beliebige docker exec-/Shell-Kommandos, privilegierte Container, Host-PID, Host-Network und autonome Bind-Mount-Erzeugung werden nicht angeboten.

Sinnvolle Einsatzzwecke

1. Unabhängige Evidence-Zweitprüfung

Nach Annahme einer hochwertigen Primär-/autoritativen Webquelle kann das Brain automatisch einen evidence_http_probe anfordern. Ein isolierter Curl-Container lädt die öffentliche URL nochmals über den Controller-Host. Er liefert HTTP-Status, effektive URL, Content-Type, Downloadgröße und SHA-256 des erfassten Bodys. Das Ergebnis wird im Activity-Audit erfasst und – wenn der externe Research-Node bereits existiert – als controller_probe_*-Provenienz in dessen Metadaten zurückgeschrieben.

Das ist kein semantischer Wahrheitsbeweis. Es ist ein unabhängiger technischer Beleg, dass die akzeptierte Quelle über einen zweiten Ausführungspfad erreichbar war und welchen Body-Hash dieser Pfad gesehen hat.

2. Health Recovery

Ein Profil health_recovery nennt einen konkreten Container und optional einen Cooldown. Meldet genau der Controller-Agent diesen Container als unhealthy, darf das Brain bei aktivierter Autonomie einen typisierten Restart-Job auf diesem Agenten einplanen. Geschützte Container sind ausgeschlossen.

Beispielkonfiguration:

{
  "container": "searxng",
  "cooldown": "30m"
}

3. Temporäre Compute-Kapazität

Wenn beim initialen Vector-Graph-Rebuild kein vector_graph-Compute-Agent verfügbar ist, kann das Brain vor dem lokalen Fallback ein freigegebenes compute_capacity_compose-Profil anfordern. Das Profil startet ein operatorgeprüftes Compose-Projekt oder einen Service und das Brain wartet anschließend innerhalb des bestehenden Agent-Startup-Grace auf dessen Registrierung.

{
  "compose_file": "/srv/brain-controller/compute.yml",
  "project": "brain-compute",
  "service": "source-agent"
}

4. Ephemere Compose-Smoke-Tests

compose_smoke_test startet ein freigegebenes Testprojekt mit docker compose up -d --wait, liest anschließend compose ps und kann es optional wieder abbauen. Cleanup benötigt zusätzlich die Freigabe destruktiver Aktionen.

{
  "compose_file": "/srv/brain-controller/tests.yml",
  "project": "brain-smoke",
  "service": "sut",
  "interval": "1h",
  "cleanup": true
}

Damit kann das Brain wiederkehrende Integrations-/Research-Sandboxes betreiben, ohne freie Host-Shell-Kommandos zu erhalten.

Manuelle Controller-Aktionen

Das zentrale Dashboard unterstützt typisierte Jobs für:

• Container: Start, Stop, Restart, Create, Remove
• Netzwerke: Create, Remove
• Volumes: Create, Remove
• Compose: Up, Down, Restart, Pull, PS
• Inventory Refresh
• Evidence HTTP Probe

Container-Erstellung ist zusätzlich gehärtet: kein Privileged, keine Host-/Container-Network-Modi, Read-only Rootfs, cap_drop=ALL, no-new-privileges, CPU-/RAM-Limits und nur benannte Docker-Volumes. Offensichtliche Inline-Secrets in env werden abgewiesen, weil Controller-Jobs vollständig auditierbar in SQLite gespeichert werden. Für Secrets sind operatorgeprüfte Compose-Secrets/Env-Dateien zu verwenden.

Images werden per zentraler Allowlist freigegeben. Präfixregeln sind nur mit einem expliziten Abschluss :, / oder @ zulässig; vendor/tool erlaubt also nicht implizit vendor/tool-malicious.

Compose-Dateien müssen unter einem zentral erlaubten Root liegen. Symlinks werden aufgelöst, bevor der Pfad freigegeben wird. Compose-Dateien werden im empfohlenen Deployment read-only in den Controller-Agent gemountet; v9 verändert daher keine beliebigen Hostdateien. Das Brain steuert die daraus entstehenden Compose-Projekte, nicht den Host-Dateibaum.

Deployment

Controller-Unterstützung wird im normalen Source-Agent-Compose nicht automatisch aktiviert und Docker.sock wird dort nicht gemountet.

Opt-in:

export DOCKER_GID=$(stat -c %g /var/run/docker.sock)
export BRAIN_CONTROLLER_COMPOSE_ROOT=/srv/brain-controller

docker compose \
  -f deployment/docker-compose.source-agent.yml \
  -f deployment/docker-compose.controller-agent.yml \
  up -d --build

Der Compose-Root wird unter demselben absoluten Pfad read-only in den Agent gemountet. Der Agent läuft weiterhin als unprivilegierter brain-User und erhält nur über die Docker-Socket-Gruppen-ID Zugriff auf den Socket.

Agent-ENV:

BRAIN_AGENT_DOCKER_CONTROLLER_ENABLED=true
BRAIN_AGENT_DOCKER_SOCKET=/var/run/docker.sock
BRAIN_AGENT_DOCKER_COMPOSE_BINARY=docker
BRAIN_AGENT_CONTROLLER_POLL_INTERVAL=5s
BRAIN_AGENT_CONTROLLER_MAX_DURATION=15m

Die zentrale Policy wird nicht per Agent-ENV freigeschaltet. Sie muss im Brain-Dashboard aktiviert werden.

Dashboard

/source-agents.html ist in v9 eine gemeinsame Agents & Controller-Konsole. Sie zeigt:

• Hauptschalter / Emergency Stop
• autonome Freigabe
• globalen Dry-Run
• destruktive Freigabe
• Parallelitäts- und Laufzeitlimits
• Image-Allowlist und Compose-Roots
• geschützte Container, Netzwerke und Volumes
• Docker Engine/API/Compose-Status pro Agent
• Container-, Netzwerk- und Volume-Inventar
• direkte Start/Stop/Restart-/Remove-Aktionen
• Controller-Profile
• Controller-Jobhistorie inklusive Resultat und Abbruch
• normale Source-Agent-/Polling-/Inbox-Funktionen

Controller-Entscheidungsgrenze

Das Brain entscheidet autonom nur an konkreten Workflow-Hooks:

• akzeptierte hochwertige Research-Evidenz → Evidence Probe
• unhealthy Container eines Recovery-Profils → Restart
• fehlende Vector-Compute-Kapazität beim Bootstrap → Compute-Compose
• fälliges Smoke-Test-Profil → Test-Compose

Ein LLM erzeugt dabei keinen Docker-Befehl. Das Modell kann weiterhin Research-/Article-Entscheidungen beeinflussen; die Host-Aktion selbst ist jedoch eine deterministische, typisierte und durch Operator-Policy freigegebene Folgeaktion.