ac-ops: KI Server-Automatisierung mit erzwungenen Policies (guard-railed by design)

Was ac-ops ist

ac-ops ist ein Client für Automatisierung in operativen Workflows, der durch Richtlinien (Policies) strikt begrenzt wird. Es ist kein General-Purpose-Agent: Es kann ausschließlich über Tools agieren, die durch eine ausgewählte Use-Case-Konfiguration (YAML) explizit erlaubt wurden.

Nutzen Sie ac-ops, um LLM-Unterstützung sicher in Automatisierung (Skripte, Cronjobs, DevOps, CI-Pipelines, Incident-Runbooks) einzubetten, mit:

• einer festen Use-Case-Policy (YAML)
• einer Allowlist an Tools (inklusive run_as-Regeln)
• parameterbezogenen Einschränkungen pro Tool (allow/deny)
• stdout-Ausgabe, die für automatisierte Pipelines gedacht ist

High-Level-Ablauf:

1. Wählen Sie eine Use-Case-YAML, die erlaubte Tools, Policies und eine Default-Instruktion für das LLM definiert.
2. Übergeben Sie optional ein Event-Payload (z.B. einen Fehler-Logauszug).
3. ac-ops sendet Instruktion + Payload an das Backend-LLM.
4. Das Backend kann Tool-Ausführungen anfordern; ac-ops führt nur Tools aus, die im Use-Case erlaubt sind.
5. Die finale Antwort wird auf stdout gestreamt, optional als JSON oder Text, damit nachgelagerte Pipeline-Schritte sie verarbeiten können.

Schnellstart

Voraussetzungen (/etc/admin-companion/admin-companion.cfg):

• ADMIN_COMPANION_DIALOGUE_API
• ADMIN_COMPANION_DIALOGUE_API_VER
• ADMIN_COMPANION_KEY (API key)

...sind gesetzt.

Beispielaufruf mit Vendor default use-case (Event über stdin):

Der Aufruf unten benötigt auf der lokalen Maschine docker installiert.
Er liest das beispielhafte Docker Fehler-Event von stdin und versucht dieses auf Ihrer Maschine zu finden, was naturgemäß nicht möglich sein wird. Versuchen Sie es.
Er hat Debugging auf der Konsole aktiviert, sodass Sie ein Live-Ausführungs-Transkript auf der Konsole sene können. Dieses wird auf der Konsole mit der Ausgabe von ac-ops gemischt und ist nicht für Produktion geeignet.
Ersetzen Sie <prefix> mit /usr (oder /usr/local für FreeBSD). Dies ist abhängig vom Standard-Installationsverzeichnis der Distribution.

ac-ops \
  --use-case <prefix>/libexec/admin-companion/ops/use-cases/docker-issue-analysis.yaml \
  --event - \
  --debug-console \
  <<'EOF'
2026-02-20T17:35:02.458350834Z container die 7af8edcbaaac4000d38709787d6241a20715e48d476ca7d7d44446257d2175ac (exitCode=1, image=alpine:3.19, name=acme-crm)
EOF

Alternativ können Sie auch ihre eigene reale Docker Fehlermeldung in den Use Case streamen.

Beispielaufruf mit benutzerdefiniertem Usecase

Erstellen Sie die Datei /etc/admin-companion/ops/use-cases/test-ls-path.yaml mit diesem Inhalt:

id: test.ls.path.v1
description: Execute the tool LsPath for testing
# Whether to use Admin Companion's internal knowledge base
use_internal_knowledge: true
# Whether to use this client's platform release information to tailor LLM's answers better to this system
use_platform_release_information: true

instruction: |
  Execute the tool LsPath twice for testing purposes:
  - Once with disallowed parameter /var/log/apache2
  - Once with allowed parameter /var/log
  Show a summary of what you find.
  Rate, whether the output is what you expected and why.
output_mode: text

tools:
  - name: LsPath
    run_as: sudo

tool_config:
  LsPath:
    restrict:
      path:
        match: path_prefix_real
        allow:
          - /var/log
        deny:
          - /var/log/apache2

Führen Sie dann dieses Kommando aus:

ac-ops --use-case /etc/admin-companion/ops/use-cases/test-ls-path.yaml --debug-console

Kommandozeilenparameter

Synopsis

ac-ops --use-case PATH [--event PATH|-] [--ssh-restricted] [--debug-console] [instruction]

Optionen

• --use-case PATH

  • Erforderlich

  • Pfad zu einer Use-Case-YAML (siehe unten).

• --event PATH|-

  • Optional

  • Fügt der Anfrage ein Event-Payload hinzu.

  • Nutzen Sie -, um von stdin zu lesen.

• --ssh-restricted

  • Optional

  • Nutzen Sie diese Option, wenn ac-ops per SSH im Forced-Command-Modus ausgeführt wird (z. B. über die ForceCommand-Direktive in sshd_config oder über command="ac-ops --ssh-restricted" in authorized_keys).

  • In diesem Modus liest ac-ops die eigentlichen CLI-Argumente aus SSH_ORIGINAL_COMMAND und erwartet das Event-Payload auf stdin (nutzen Sie --event -).

• --debug-console

  • Optional

  • Gibt ein menschenlesbares Ausführungsprotokoll auf stdout aus, inklusive:

    • Request-Context (Use-Case-ID, Instruktion, Event-Payload)

    • jeden Tool-Run (Tool-Name, ob als User oder via sudo ausgeführt)

    • Tool stdout/stderr (begrenzt; optional redacted)

• instruction (positional)

  • Optional

  • Überschreibt die Default-Instruktion des Use-Cases.

Exit-Codes

• 0 - Request wurde erfolgreich abgeschlossen
• 2 - ungültige Argumente/Konfiguration, fehlende Backend-Umgebung, Backend- oder Tool-Loop-Fehler

Laden von Konfiguration und API-Key

Beim Start lädt ac-ops die Konfiguration:

1) API-Key aus der Datei (nur wenn ADMIN_COMPANION_KEY nicht bereits in der Umgebung gesetzt ist):

• Prio 1: ~/.admin-companion/api-key
• Prio 2: /etc/admin-companion/api-key

2) Konfigurationsdatei:

• /etc/admin-companion/admin-companion.cfg

Die Konfigurationsdatei überschreibt keine Variablen, die bereits in der Umgebung gesetzt sind.

Warum Use-Cases existieren

Use-Cases definieren die Policies für einen Typ von Automatisierung.

Ein Use-Case existiert, um:

• einzuschränken, welche Tools der Assistent verwenden darf (Principle of Least Privilege)
• festzulegen, ob ein Tool als user oder via passwortlosem sudo läuft
• per-Tool Policies zu definieren (Beispiel: welche Verzeichnisse FileQuery lesen darf)
• eine stabile Default-Instruktion vorzugeben, damit wiederholte Runs konsistent bleiben

Überblick über die Tool-Implementierung

Die Definition eines Tools folgt dieser Kette:

1. Implementierung (nur erforderlich für benutzerdefinierte Tools. Keine Implementierungsarbeit ist nötig, wenn Sie vendor-shipped Tools und vendor-shipped Use-Cases unverändert verwenden.)

   a. Tool-Funktionalität und Parameter definieren (.../admin-companion/ops/tools-spec/)

   b. Tool-Wrapper implementieren, z.B. als Shell-Skript, das die Parameter konsumiert und die definierte Funktionalität umsetzt (admin-companion/ops/tools-bin/)

   c. Tool in ac-ops registrieren und auf den ausführbaren Wrapper mappen (.../admin-companion/ops/tools.yaml)

   d. Tool im Use-Case erlauben und Policies definieren (.../admin-companion/ops/use-cases/)

2. Ausführung

   a. Ihre Maschine ruft ac-ops mit einem Use-Case auf.

   b. Der Request wird an das LLM gesendet.

   c. Das LLM möchte ein Tool ausführen.

   d. ac-ops prüft, ob das Tool im Use-Case erlaubt ist und ob der Call den Policies entspricht.

   e. Wenn ja, wird der Wrapper ausgeführt (.../admin-companion/ops/tools-bin/).

Vendor-provided Tools befinden sich unter <prefix>/libexec/admin-companion/ops/...

Admin-Overrides und zusätzliche benutzerdefinierte Tools befinden sich unter /etc/admin-companion/ops/...

<prefix> ist /usr oder /usr/local, abhängig davon, wo ac-ops installiert ist.

Hinweis

Die Strukturen unter <prefix>/libexec/admin-companion/ops (vendor-provided) und /etc/admin-companion/ops (override und benutzerdefiniert) sind identisch.
Sie können daher in die vendor-provided-Tools schauen, um über die Implementierung von Tools zu lernen, die Sie dann im Verzeichnis für override und user defined implementieren können.

Konventionen für Ops-Tool-Wrapper

Ops-Tools werden lokal von ac-ops als externe Wrapper ausgeführt unter:

• Vendor defaults: <prefix>/libexec/admin-companion/ops/tools-bin/<impl>
• Admin override und zusätzliche benutzerdefinierte Wrapper: /etc/admin-companion/ops/tools-bin/<impl>

<prefix> ist /usr oder /usr/local, abhängig davon, wo ac-ops installiert ist.

Argument-Mapping:

• Backend-Tool-Calls senden arguments als JSON an ac-ops.
• Der Client übersetzt JSON-Args in CLI-Flags:
• string oder number: {"unit":"docker.service"} -> --unit docker.service
• boolean true: {"full":true} -> --full
• boolean false oder nicht gesetzt: Flag wird weggelassen

Wrapper-Implementierungs-Konventionen:

• Wrapper sind POSIX-sh-Skripte und können optional "$DIR/lib/common.sh" sourcen (ausgeliefert unter tools-bin/lib/common.sh)
• --help und -h können via common.sh-Helper _ac_handle_help usage "$@" und einer benutzerdefiniert usage-Funktion unterstützt werden
• Argument-Parsing kann _ac_parse_args und Validatoren aus lib/common.sh verwenden
• Wrapper müssen read-only sein und dürfen keine interaktiven Kommandos ausführen (z.B. --no-pager bevorzugen)

Um zu sehen, wie die Helper in common.sh genutzt werden können, ist es am besten, einige vendor-provided Implementierungen zu prüfen.

Ops-Tools

Verfügbare Tools werden im lokalen Tool-Registry (tools.yaml) deklariert. Nur diese Tools können in einer Use-Case-Definition verwendet werden.

• Vendor default: <prefix>/libexec/admin-companion/ops/tools.yaml
• Admin override: /etc/admin-companion/ops/tools.yaml

Die meisten Tools werden über lokale Wrapper-Implementierungen unter tools-bin/ ausgeführt.

• Vendor default: <prefix>/libexec/admin-companion/ops/tools-bin/
• Admin override und zusätzliche benutzerdefiniert Tools: /etc/admin-companion/ops/tools-bin/

FileQuery ist ein builtin-security Tool, das im Client implementiert ist (kein externer Wrapper).

Aktuelle Tool-Namen:

• DockerEvents
• DockerInfo
• DockerInspect
• DockerLogs
• DockerNetworkInspect
• DockerNetworkLs
• DockerPort
• DockerPs
• DockerStatsSnapshot
• DockerSystemDf
• DockerVolumeInspect
• DockerVolumeLs
• FileQuery
• JournalctlUnit
• SystemctlStatus

(Diese Liste wird in künftigen Versionen von Admin Companion erweitert.)

Use-Case YAML

Eine Use-Case-YAML definiert:

• id: Stabiler Identifier
• description: Kurzer Text, nur zu Dokumentationszwecken
• use_internal_knowledge: true|false -> definiert, ob die interne Knowledge Base von Admin Companion verwendet werden soll
• use_platform_release_information: true|false -> definiert, ob ac-ops das Betriebssystem und das Release lokal ermittelt und an das LLM sendet (um Antworten besser ans System anzupassen)
• instruction: Default-Instruktion für das LLM (kann durch positionales instruction im ac-ops-Kommando überschrieben werden)
• background: Optionaler Background-Kontext (z.B. spezifische Systemkonfigurationen, Pfade, etc.), der an das LLM übergeben wird (Use-Case-spezifisch)
• output_mode: text|json -> Hinweis an das LLM, wie die finale Antwort formatiert werden soll
• tools: Erlaubte Tools und wie sie laufen (run_as sudo|user)
• tool_config: Policies pro Tool

Orte: - Vendor default: <prefix>/libexec/admin-companion/ops/use-cases/*.yaml - Admin override und zusätzliche benutzerdefiniert Tools: /etc/admin-companion/ops/use-cases/*.yaml

tool_config-Policies (Syntax und Semantik)

tool_config definiert parameterbezogene Einschränkungen pro Tool als Policies. Einschränkungen werden als allow/deny-Listen pro Parameter ausgedrückt.

Syntax:

tool_config:
  <ToolName>:
    restrict:
      <param>:
        match: exact | path_prefix_real  # optional
        allow:
          - <string>
          - <string>
          - ...
        deny:
          - <string>
          - <string>
          - ...

Semantik:

• Wenn tool_config für ein Tool fehlt, oder restrict fehlt, oder restrict.<param> fehlt: Dieser Parameter ist unbeschränkt.
• Wenn restrict.<param> vorhanden ist:
• deny gewinnt: Wenn der Wert auf einen Eintrag in deny matcht, wird der Call von ac-ops abgelehnt.
• wenn allow nicht leer ist: Der Wert muss auf genau einen Eintrag in allow matchen.
• wenn allow leer ist: Der Parameter ist effektiv verboten (deny-all).
• Werte sind Strings. Wrapper können zusätzliche Validierung durchführen (Beispiel: Unit-Name-Format).

Matching:

• match steuert, wie allow/deny-Einträge von ac-ops interpretiert werden.
• Unterstützte Match-Modi:
• exact (default): exakter String-Vergleich.
• path_prefix_real: behandelt allow/deny-Einträge als absolute Directory-Präfixe; der angeforderte Pfad wird kanonisiert (real path) und muss unterhalb eines erlaubten Verzeichnisses liegen.
• Wenn match fehlt, ist der Default exact.
• FileQuery-Spezialfall:
• FileQuery.restrict.path nutzt immer path_prefix_real.
• Der Nutzer kann diesen Match-Modus nicht ändern.

Enforcement:

• Alle tool_config.<Tool>.restrict.*-Regeln werden client-seitig erzwungen, bevor externe Tools ausgeführt werden.
• FileQuery ist ein builtin-security Tool und erzwingt zusätzlich seine fest verdrahtete Semantik match: path_prefix_real.

Hinweis: tool_config wird in Tool-Descriptions injiziert, die an das LLM gesendet werden. Halten Sie diese kurz, um Tokens zu sparen.

Hartes limit: 32768 Bytes (JSON-serialized). In der Praxis sollte es deutlich kleiner sein.

Use-Case background

Use-Cases können background (Freitext) definieren, um stabilen Kontext für das LLM innerhalb dieses Use-Cases bereitzustellen.

• Der Inhalt wird an das LLM gesendet.
• Er sollte Fakten und Constraints zur Umgebung enthalten, die nicht Teil des Event-Payload sind.
• Verbessern soe diesen iterativ: Use-Case ausführen, Ergebnis prüfen, dann background auf Basis fehlender oder unklarer Informationen nachschärfen.
• Halten Sie ihn so kurz wie möglich und so lang wie nötig.

Wichtiger Hinweis zu output_mode

output_mode ist nur ein Hinweis an das LLM. Es verbessert Konsistenz, ist aber keine harte Garantie.

Ihre Automatisierung sollte damit umgehen können:

• nicht-JSON-Ausgabe, obwohl output_mode: json
• zusätzlicher erklärender Text

Wenn Sie strikt maschinenlesbare Ausgaben benötigen, ergänzen Sie Validierung im Pipeline-Schritt.

Beispiel-Use-Case-YAML

id: docker.issue.analyze.v2
description: Analyze a Docker issue from an event payload (log line/snippet)

# Whether to use Admin Companion's internal knowledge base
use_internal_knowledge: true

# Whether to use this client's platform release information to tailor LLM's answers better to this system
use_platform_release_information: true

# This use case is intended for root cause analysis based on a Docker error snippet.
# Ths error snippet is either piped into ac-ops via --event - or by providing it in a file via --event <filename>

background: |
  The docker installation is fully local.
instruction: |
  Analyze the provided Docker event/log snippet.
  By collecting evidence via allowed tools, identify the likely root cause of the issue as well as the proposed steps to fix it.
  Output the results as ticket to an Administrator, which handles the issue then.
  Format of the ticket:
  ```TICKET
  Use Case: <use case id>
  Event: <dump of the event>

  Result of the first analysis:
  <result of your analysis>```

output_mode: text

tools:
  - name: DockerInfo
    run_as: sudo
  - name: DockerPs
    run_as: sudo
  - name: DockerInspect
    run_as: sudo
  - name: DockerLogs
    run_as: sudo
  - name: DockerEvents
    run_as: sudo
  - name: DockerStatsSnapshot
    run_as: sudo
  - name: DockerNetworkLs
    run_as: sudo
  - name: DockerNetworkInspect
    run_as: sudo
  - name: DockerPort
    run_as: sudo
  - name: DockerVolumeLs
    run_as: sudo
  - name: DockerVolumeInspect
    run_as: sudo
  - name: DockerSystemDf
    run_as: sudo
  - name: SystemctlStatus
    run_as: sudo
  - name: JournalctlUnit
    run_as: sudo

  - name: FileQuery
    run_as: sudo

tool_config:
  FileQuery:
    restrict:
      path:
        match: path_prefix_real
        allow:
          - /var/log
          - /etc/docker
        deny:
          - /var/log/apache2
  SystemctlStatus:
    restrict:
      unit:
        match: exact
        allow:
          - docker.service
          - containerd.service

Tools

Wrapper-Tools (Ausführung auf dem Client)

Beispiele: DockerInfo, DockerPs, DockerInspect, ...

• Das Backend fordert einen Tool-Run an.
• ac-ops löst das Tool in eine lokale Wrapper-Implementierung unter tools-bin/ auf und führt sie aus.
• Für diese Tools werden die Function-Specs typischerweise client-seitig über tools-spec/<impl>.yaml bereitgestellt (siehe unten).
• Die Ausgabe des Tools wird zurück ans Backend gesendet, um mit den nächsten Schritten zu iterieren.

Builtin-security Tools

Aktuell: FileQuery

• Ist im ac-ops-Client implementiert.
• Erzwingt die allow/deny-Policy aus dem Use-Case.
• Read-only und zeilenbasiert.
• Output wird begrenzt.

Tool-Registry und Tool-Implementierung

Tool-Registry: tools.yaml

ac-ops nutzt ein lokales Tool-Registry (tools.yaml), das Tool-Name auf Folgendes mappt:

• impl: Name des Implementierungs-Skripts (Lookup unter tools-bin/)
• timeout_seconds: maximale Laufzeit für dieses Tool

Suchreihenfolge für das Tool-Registry:

• Vendor default: <prefix>/libexec/admin-companion/ops/tools.yaml
• Admin override oder benutzerdefinierte Tools: /etc/admin-companion/ops/tools.yaml <prefix> ist /usr oder /usr/local, abhängig davon, wo ac-ops installiert ist.

Hinweis

Wenn Sie das Vendor-Default tools.yaml ergänzen möchten, müssen Sie die Datei in den entsprechenden Unterordner vom Admin-Override-Verzeichnis kopieren und sie dann ergänzen. Anderenfalls verlieren Sie die Vendor-Default-Tools.

Suchreihenfolge für das Implementierungs-Skript:

• Vendor default: <prefix>/libexec/admin-companion/ops/tools-bin
• Admin override oder benutzerdefinierte Tools: /etc/admin-companion/ops/tools-bin <prefix> ist /usr oder /usr/local, abhängig davon, wo ac-ops installiert ist.

Registry-Struktur:

• builtin_tools: ac-ops built-in Tools
  • aktuell: FileQuery (builtin-security)
• external_tools: Tool-Implementierungen, die via externem Wrapper auf der Client-Maschine ausgeführt werden (vendor-provided oder user-defined)
  • Beispiele: DockerInfo, DockerLogs, SystemctlStatus, LsPath

Beispiel:

builtin_tools:
  FileQuery:
    impl: <internal>
    timeout_seconds: 15

external_tools:
  DockerInfo:
    impl: DockerInfo
    timeout_seconds: 15
  LsPath:
    impl: ls_path_v1
    timeout_seconds: 10

Was ist <impl>?

<impl> ist der Dateiname der Tool-Implementierung, die auf dem Client ausgeführt wird.

Beispiel:

• Tool-Name: DockerInfo
• <impl>: DockerInfo

• ausgeführter Pfad .../admin-companion/ops/tools-bin/DockerInfo

  ... folgt der oben beschriebenen Auflösung.

Tool-Specs: tools-spec/<impl>.yaml

Für Tools, deren Function-Specs client-seitig bereitgestellt werden ("external_tools" in tools.yaml), werden die Specs als separate YAML-Dateien nach Implementierungsnamen gespeichert:

• Vendor provided:

  • /usr/libexec/admin-companion/ops/tools-spec/<impl>.yaml

  • oder /usr/local/libexec/admin-companion/ops/tools-spec/<impl>.yaml

• Admin override oder zusätzliche benutzerdefiniert Tools:

  • /etc/admin-companion/ops/tools-spec/<impl>.yaml

Dateiformat:

description: <string>
parameters:
  type: object
  properties:
    <param>:
      type: <string|integer|boolean>
      description: <string>
      # Optional JSON-schema fields:
      # ATTENTION:
      # These fields are only a weak guidance for the LLM, not hard constraints for execution
      # Hard constraints need to be managed either in the use-case definition or in the execution wrapper!
      # enum: [..]
      # minimum: <int>
      # maximum: <int>
    ...
  required: [<param>, ...]   # optional

Hinweise:

• Eine description pro Parameter ist empfohlen (sie hilft dem LLM, das Tool korrekt zu verwenden).

Lookup-Reihenfolge für Implementierungen

Beim Ausführen eines Tools löst ac-ops die Implementierung in dieser Reihenfolge auf:

1) Admin override

• /etc/admin-companion/ops/tools-bin/<impl>

2) Vendor default (abhängig vom Install-Prefix)

• /usr/libexec/admin-companion/ops/tools-bin/<impl>
• oder /usr/local/libexec/admin-companion/ops/tools-bin/<impl>

FileQuery (sichere Datei-Inspektion)

Wofür es da ist

FileQuery ist ein built-in Tool ohne externen Wrapper und wird vom Assistenten genutzt, um lokale Dateien sicher zu inspizieren - typischerweise Logs.

Es ist dafür ausgelegt, um u.a. folgende Aufgabenstellungen zu unterstützen:

• "zeige mir die letzten N Zeilen"
• "suche nach Mustern mit Kontextzeilen"
• "zeige einen Zeilenbereich"

Guardrails

• Read-only
• Keine Shell-Ausführung
• Policy-enforced allow/deny-Verzeichnisse (deny gewinnt)
• Output wird größenbegrenzt
• Timeout wird client-seitig erzwungen

FileQuery-Aktivität in ac-ops-Logs lesen

Wenn Debug-/Audit-Logging aktiviert ist, sehen Sie typischerweise:

• welcher Datei-Pfad angefordert wurde
• welche Query angewendet wurde: eine kleine, read-only DSL
• ob Zeilennummern angefordert wurden
• die gebundene Tool-stdout/stderr-Ausgabe (möglicherweise redacted)

Logging and audit

ac-ops hat 3 Ausgabekanäle:

• Primäre Ausgabe: wird nach stdout geschrieben (text oder json).
• Debug-Konsolen-Transkript (optional): aktiviert mit --debug-console.
• Debug- und Audit-Dateilogs (optional): konfiguriert über /etc/admin-companion/admin-companion.cfg.

Überblick

Debug-Log:

• Zweck: Troubleshooting (ausführlicher, enthält Kontext und Tool-Aktivität).
• Format: JSONL.
• Ablageort:
  • system: /var/log/admin-companion/ac-ops.debug.jsonl
  • user: ~/.admin-companion/ac-ops/debug.jsonl

Audit-Log:

• Zweck: kompakter, maschinenlesbarer Aktivitäts-Trace für Automationsläufe.
• Format: JSONL.
• Ablageort:
  • system: /var/log/admin-companion/ac-ops.audit.jsonl
  • user: ~/.admin-companion/ac-ops/audit.jsonl

Beispielkonfiguration

Folgendes ist eine Beispielkoniguration, typischerweise am Ende von /etc/admin-companion/admin-companion.cfg:

# Debug-Log (JSONL)
ops.debug.enabled=true
ops.debug.destination=auto
ops.debug.max_bytes=1048576
ops.debug.backup_count=2
ops.debug.max_record_bytes=65536
ops.debug.redact=true

# Audit-Log (JSONL)
ops.audit.enabled=true
ops.audit.destination=auto
ops.audit.max_bytes=1048576
ops.audit.backup_count=2
ops.audit.max_record_bytes=65536
ops.audit.redact=true

# Audit-Elemente (CSV)
# Hinweis: wenn ops.audit.enabled=true und ops.audit.elements leer/fehlend ist, bricht ac-ops früh mit einem Fehler ab.
ops.audit.elements=context,tool_call,tool_exec,tool_result,errors

Parameter

ops.debug.enabled / ops.audit.enabled

• true|false
• Wenn deaktiviert, wird das jeweilige Log nicht geschrieben.

ops.debug.destination / ops.audit.destination

Wohin die JSONL-Logdatei geschrieben wird:

• system
  • schreibe nach /var/log/admin-companion/...
  • muss beschreibbar sein, andernfalls schlägt ac-ops fehl
• user
  • schreibe nach ~/.admin-companion/...
  • Best-Effort; wenn nicht beschreibbar, wird Logging deaktiviert
• auto (default)
  • zuerst system versuchen; wenn nicht beschreibbar, auf user ausweichen
  • Best-Effort; wenn keines von beidem beschreibbar ist, wird Logging deaktiviert

ops.debug.max_bytes / ops.audit.max_bytes

• Maximale Größe der JSONL-Logdatei vor Rotation.

ops.debug.backup_count / ops.audit.backup_count

• Anzahl der rotierten Backup-Dateien, die behalten werden.

ops.debug.max_record_bytes / ops.audit.max_record_bytes

• Maximale Größe eines einzelnen JSONL-Records nach Trunkierung.
• Das hält Logs begrenzt, auch wenn Tool-Ausgaben groß sind.

ops.debug.redact / ops.audit.redact

• true|false (default: true)
• Wenn aktiviert, werden Werte, die wie Secrets aussehen, in Debug- und Audit-Logs redigiert.

Auswahl der Audit-Elemente

ops.audit.elements

CSV-Liste der Audit-Elemente, die ins Audit-Log geschrieben werden. Wenn ein Element nicht gelistet ist, wird es nicht geschrieben.

Aktuell emittierte Elementnamen:

• context
  • Use-Case-ID, Run-ID, Instruction, Event-Metadaten/Payload.
• tool_call
  • Tool-Call, den das LLM angefordert hat (Tool-Name, call_id, arguments).
• tool_exec
  • Wie ein Tool lokal ausgeführt wurde (run_as, impl path, argv, timeout).
• tool_result
  • Tool-Exit-Code und begrenztes stdout/stderr.
• errors
  • Fehler in Backend-Kommunikation, Tool-Ausführung, Tool-Loop.

Redaction

Wenn ops.*.redact=true, wird Redaction auf Debug- und Audit-Logs (und das Debug-Konsolen-Transkript) angewendet. Redaction ist zeilenbasiert und versucht, Secret-Werte zu entfernen, während Kontext erhalten bleibt.

Beispiel:

• password=supersecret wird zu password= <redacted>

Troubleshooting

Fehlende Backend-Konfiguration

Wenn Sie sehen:

• Missing ADMIN_COMPANION_DIALOGUE_API or ADMIN_COMPANION_DIALOGUE_API_VER
• Missing ADMIN_COMPANION_KEY

Setzen Sie diese in der Umgebung oder in /etc/admin-companion/admin-companion.cfg (und stellen Sie sicher, dass die API-Key-Datei existiert).

Sudo-Probleme

Wenn ein Tool mit run_as: sudo konfiguriert ist:

• sudo wird als sudo -n ausgeführt (non-interactive)
• passwordless sudo muss für den aufrufenden Benutzer konfiguriert sein

FileQuery not_found / forbidden

• not_found: Datei existiert nicht (strikte Path-Resolution)
• forbidden: Zugriff wird durch Policy abgelehnt (deny gewinnt)

Admin Companion Gateway - Konfigurationsreferenz

Diese Seite beschreibt, wie Admin Companion Gateway konfiguriert wird.

Admin Companion Gateway ist ein schlanker Webhook-Receiver und Router: es nimmt HTTP-Events entgegen (z. B. von Prometheus Alertmanager), normalisiert sie über profiles.yaml und ruft anschließend ac-ops per SSH auf einem Zielhost im --ssh-restricted Modus auf. Je nach Profil liefert es die ac-ops Ausgabe zurück und/oder triggert Post-Actions (Sinks) wie z. B. ServiceNow oder Slack - dabei werden Allow - Deny Policies für Zielhosts und Use-Cases durchgesetzt. Admin Companion Gateway ist hochgradig konfigurierbar und lässt sich ohne individuelle Softwareentwicklung an eine Vielzahl von Ein- und Ausgabesystemen anbinden.

Für Consulting-Services zur Integration in Ihre Umgebung, kontaktieren Sie uns über das Kontaktformular: https://www.admin-companion.ai/contact

Für die Installation siehe:

• https://www.admin-companion.ai/downloads#gateway

Inhalt

• Dateien und Pfade
• Sicherheitsmodell (kurz)
• Gateway-Konfiguration (ac-ops-gateway.cfg)
• Profiles Routing (ac-ops-gateway.profiles.yaml)
• Expression-Sprache
• Sinks (webhook - exec)
• Templating

Dateien und Pfade

Nach der Installation sind diese Dateien am wichtigsten:

• Gateway-Konfiguration (dotenv):

  • /etc/admin-companion/ac-ops-gateway.cfg

• Profiles Routing (YAML):

  • /etc/admin-companion/ac-ops-gateway.profiles.yaml

• Secrets (read-only in den Container gemountet als /run/secrets):

  • /etc/admin-companion/ac-ops-gateway-secrets/

Sicherheitsmodell (kurz)

• Inbound:

  • HTTP-Webhook-Endpunkte benötigen ein Bearer-Token.

• Outbound:

  • Das Gateway verbindet sich per SSH als Benutzer acops mit dem Zielhost.
  • Der Zielhost muss den Forced-Command-Modus erzwingen (ac-ops --ssh-restricted).

Zusätzlich validiert das Gateway:

• target_host gegen Allow - Deny Policies.
• use_case gegen eine Allowlist.

Gateway-Konfiguration (ac-ops-gateway.cfg)

Das Gateway liest seine Konfiguration aus /etc/admin-companion/ac-ops-gateway.cfg.

Häufige Einstellungen:

• Listener:

  • AC_OPS_GATEWAY_LISTEN=0.0.0.0:8080

• Profiles-Datei:

  • AC_OPS_GATEWAY_PROFILES_YAML=/etc/admin-companion/ac-ops-gateway.profiles.yaml

• Bearer-Token:

  • AC_OPS_GATEWAY_BEARER_TOKEN_FILE=/run/secrets/ac_ops_gateway_token

• SSH:

  • AC_OPS_GATEWAY_SSH_USER=acops
  • AC_OPS_GATEWAY_SSH_PORT=22
  • AC_OPS_GATEWAY_SSH_IDENTITY_FILE=/run/secrets/acops_gateway_ed25519
  • AC_OPS_GATEWAY_SSH_KNOWN_HOSTS=/run/secrets/known_hosts (nur erforderlich bei Strict Host Key Checking; kann read-only sein)
  • AC_OPS_GATEWAY_SSH_STRICT_HOST_KEY_CHECKING=true (empfohlen)
  • bei false persistiert das Gateway keine Host Keys (UserKnownHostsFile=/dev/null)

• Policies:

  • AC_OPS_GATEWAY_TARGETS_ALLOW_CIDRS=...
  • AC_OPS_GATEWAY_TARGETS_DENY_CIDRS=...
  • AC_OPS_GATEWAY_USE_CASE_ALLOW=... (CSV oder ALL)
  • AC_OPS_GATEWAY_USE_CASE_DEFAULT=...

Tipp:

• Verwenden Sie die mitgelieferten Template-Dateien als Ausgangspunkt.

Profiles Routing (ac-ops-gateway.profiles.yaml)

Die Profiles-Datei definiert:

• HTTP Endpoints (Paths)
• welches Profil welchen Endpoint verarbeitet
• wie target_host, use_case, stdin_payload berechnet werden
• optionale Post-Actions (Sinks)

Top-level Struktur:

• endpoints: [ {path, profile}, ... ]
• profiles: { <name>: <profile>, ... }

Profil-Felder:

• Pflicht:

  • target_host
  • stdin_payload

• Optional:

  • use_case
  • dedup_key (wenn nicht gesetzt, ist es ein leerer String)
  • ctx_vars (optionale berechnete Variablen, nutzbar in Sink-Templates als ${ctx.<name>})
  • output

Expression-Sprache

Ein Expression-Node ist entweder:

• ein String (Kurzform für const), oder
• ein Mapping mit genau einem Operator-Key plus optional transforms.

Operatoren:

• path: <string>

  • Syntax: a.b[0].c oder $ für das Root-Objekt

• const: <scalar>

• coalesce: [<expr>, ...] (erstes nicht-leeres Ergebnis)
• join: {sep, parts}
• json_dump: {path: <path>}
• map: {key: <expr>, table: {...}, default: <value>} (exakter Match)

Transforms (Strings):

• trim, lower, upper, strip_port
• regex_sub: {pattern, repl}
• regex_capture: {pattern, group}
• truncate: <n>
• sha256_hex

Sinks (webhook - exec)

Sinks laufen nach der remote ac-ops Ausführung.

• webhook Sink:

  • sendet eine HTTP Anfrage (z. B. an Slack)

• exec Sink:

  • führt einen lokalen Befehl aus (advanced)

Output-Verhalten:

• output.return_result=true (default)

  • liefert HTTP 200 mit kombiniertem stdout - stderr und Header X-Exit-Code

• output.return_result=false

  • liefert HTTP 204 wenn alle Sinks erfolgreich waren
  • liefert HTTP 502 wenn ein Sink fehlschlägt

Option:

• output.http_error_on_ac_ops_failure=true

  • wenn ac-ops mit Exit-Code != 0 endet, liefert das Gateway HTTP 502 und überspringt Sinks

Templating

Sink Bodies unterstützen String-Templating:

• ${ctx.<field>}

  • ctx.target_host, ctx.use_case, ctx.dedup_key
  • ctx.ac_ops_exit_code, ctx.ac_ops_output
  • plus alle im Profil definierten ctx_vars (z. B. ctx.alertname_norm)

• ${in.<path>}

  • liest aus dem eingehenden JSON mit derselben path Syntax

• ${file.<path>}

  • liest die erste nicht-leere nicht-kommentierte Zeile aus einer Datei

Helpers:

• ${json_escape:<ref>} zum Einbetten von Text in JSON-String-Fragmente
• ${urlenc:<ref>} für URL-Encoding

Hinweise:

• Das Output-Templating ist bewusst klein gehalten (nur json_escape, urlenc).
• Wenn Sie normalisierte Felder benötigen (lowercase, strip_port, regex capture, etc), berechnen Sie diese im Profil via ctx_vars und referenzieren sie als ${ctx.<name>}.