From 1bb2c320abcc8eeff373ec6c5989d3880e701c50 Mon Sep 17 00:00:00 2001 From: Micha Date: Fri, 26 Jun 2026 11:27:39 +0200 Subject: [PATCH] Document AI host API access rules --- AGENTS.md | 3 +++ CLAUDE.md | 6 ++++++ docs/AI_CONTEXT.md | 8 ++++++++ docs/WORKFLOW.md | 31 +++++++++++++++++++++++++++++++ 4 files changed, 48 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index c1115dd..3170223 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,6 +15,9 @@ Einstiegspunkt fuer KI-Agenten (Codex, Gemini u. a.; Claude nutzt zusaetzlich ## Nicht verhandelbar - Keine Secret-Werte lesen, zitieren oder schreiben - nur Namen und Pfade. +- Codex/Claude-Hostzugriffe fuer Komodo/Unraid sind in `docs/SECRETS_MAP.md` + als Secret-Pfade dokumentiert. Werte niemals ausgeben, loggen oder in Git + schreiben; Nutzung nur fuer ausdruecklich angeforderte Host-/Live-Checks. - Keine Deployments, Host-Hotfixes oder Docker-Schreibbefehle ohne ausdrueckliche Anweisung. - Doku-Regeln aus `docs/REPO_MAP.md` einhalten: ein Fakt, ein Zuhause. Status nur in `docs/MASTER_TODO.md`, Entscheidungen nur in `docs/DECISIONS.md`. - Bei Drift oder zwei fehlgeschlagenen Reparaturversuchen: stoppen, `docs/GITOPS_DRIFT_RUNBOOK.md`. diff --git a/CLAUDE.md b/CLAUDE.md index 0649299..43102d7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -48,6 +48,10 @@ Zusaetzlich je nach Thema: - Direkte Host-Ports sind nur mit dokumentierter Ausnahme erlaubt. - Komodo bleibt bewusst ohne pauschale zentrale Authelia-ForwardAuth-Middleware. - Secrets gehoeren niemals ins Git-Repository. +- Codex/Claude-API-Secrets fuer Komodo/Unraid liegen auf `kallilabcore` unter + den in `docs/SECRETS_MAP.md` dokumentierten Pfaden. Werte niemals lesen, + ausgeben, loggen oder committen; nur Pfade/Env-Namen verwenden und nur fuer + ausdruecklich angeforderte Host-/Live-Checks. - Produktive Container sollen als Compose/Git-Stack verwaltet werden. ## GitOps-Regeln @@ -80,6 +84,8 @@ Wenn Drift vermutet wird, nicht raten. Erst die Pflichtmatrix in `docs/GITOPS_DR - Secret-Werte niemals ausgeben. Wenn Werte auftauchen: redakten. - Nur Secret-Namen, Env-Key-Namen und Pfade dokumentieren. - Keine produktiven `.env`- oder Stack-Env-Werte zitieren. +- Komodo-CLI auf dem Host nur mit xtrace aus und ohne Echo der Env ausfuehren: + `set -a; . /mnt/user/appdata/secrets/codex_komodo_api.env; set +a; docker exec -e KOMODO_CLI_HOST -e KOMODO_CLI_KEY -e KOMODO_CLI_SECRET komodo-core km core-info`. - Keine Compose-Aenderung ohne vorherigen Architektur-/Workflow-Abgleich. - Keine Deployments, Host-Hotfixes oder Docker-Schreibbefehle ohne ausdrueckliche Anweisung. - Keine direkten Host-Ports fuer Web-UIs, ausser dokumentierte Ausnahmen. diff --git a/docs/AI_CONTEXT.md b/docs/AI_CONTEXT.md index f3bffb1..83a9c86 100644 --- a/docs/AI_CONTEXT.md +++ b/docs/AI_CONTEXT.md @@ -14,6 +14,10 @@ Diese Datei enthaelt bewusst **keinen** Arbeitsstand mehr — Status nur in - Ingress: Traefik; WAN-seitig bewusst nur `443/tcp` - Secrets: nie im Repo, meist unter `/mnt/user/appdata/secrets/` - Backup: Borg plus host-seitige Dumps; Hetzner ist Offsite, H:/ ist lokale Nearline-Kopie +- Agenten-Hostzugriff: Codex/Claude-API-Secrets fuer Komodo/Unraid liegen auf + `kallilabcore` unter den in `docs/SECRETS_MAP.md` dokumentierten Pfaden. + Werte niemals lesen, ausgeben, loggen oder committen; nur fuer ausdruecklich + angeforderte Host-/Live-Checks nutzen. ## Vor jeder Aenderung lesen @@ -28,6 +32,10 @@ Diese Datei enthaelt bewusst **keinen** Arbeitsstand mehr — Status nur in ## Harte Regeln - Keine Secrets zitieren oder ins Repo schreiben. +- Codex/Claude duerfen dokumentierte Host-API-Secrets nur als Pfade/Env-Namen + behandeln; Secret-Werte werden nie angezeigt. Vor Host-Befehlen sicherstellen, + dass der Shell-Kontext wirklich auf `kallilabcore` liegt oder ein expliziter + Remote-Ausfuehrungsweg genutzt wird. - Keine produktiven Host-Hotfixes ohne Repo-Abgleich. - Datenbanken nie ins `frontend_net`. - Direkte Host-Ports sind Ausnahme. diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md index 70e1cae..cf31a22 100644 --- a/docs/WORKFLOW.md +++ b/docs/WORKFLOW.md @@ -325,6 +325,37 @@ Pflicht-Setup auf dem Host: Repo-Spiegel unter `/mnt/user/services/homelab-infra - Rechte: `chmod 600` - Secret-Namen und Pfade werden in `docs/SECRETS_MAP.md` dokumentiert +### Codex/Claude Host-API-Zugriffe + +Fuer ausdruecklich angeforderte Live-/Host-Checks duerfen Codex/Claude die in +`docs/SECRETS_MAP.md` dokumentierten Host-API-Secretpfade verwenden: + +- Komodo CLI/API: `/mnt/user/appdata/secrets/codex_komodo_api.env` +- Unraid API: `/mnt/user/appdata/secrets/codex_unraid_api_key.txt` + +Regeln: + +- Secret-Werte niemals ausgeben, loggen, kopieren oder ins Repo schreiben. +- Keine `set -x`/Shell-Traces beim Laden der Env-Datei. +- Vor Nutzung klaeren, ob die Shell wirklich auf `kallilabcore` laeuft; eine + Windows-Arbeitskopie ohne `/mnt/user/...` ist kein Host-Kontext. +- Standard ist read-only Inventarisierung. Schreibende API-/Docker-/Komodo- + Aktionen brauchen eine ausdrueckliche Operator-Anweisung. + +Read-only Komodo-Smoke auf dem Host: + +```bash +set -a +. /mnt/user/appdata/secrets/codex_komodo_api.env +set +a + +docker exec \ + -e KOMODO_CLI_HOST \ + -e KOMODO_CLI_KEY \ + -e KOMODO_CLI_SECRET \ + komodo-core km core-info +``` + --- ## Image-Versionierung