CLI-Werkzeug freigeben, pinnen & Lizenz prüfen

Admin

Das CLI-Befehlswerkzeug führt in der Desktop-Variante externe Kommandozeilen-Programme aus. Dieses Howto richtet sich an Betreiber: Es erklärt den Freigabe-Flow im laufenden Betrieb, das Versions-Pinning (Binary-Allowlist) und das Lizenz-/Redistribution-Review-Gate, das jede gebündelte CLI vor dem Ausliefern durchlaufen muss. Den Endnutzer-Überblick und das kundenlesbare Garantie-Statement beschreibt → Befehlszeilen-Werkzeuge (CLI) im Assistenten — Überblick & Grenzen. Zur Einordnung der konfigurierbaren Werkzeuge siehe Konfigurierbare Werkzeuge — Überblick.

Der Freigabe-Flow im Betrieb

Ein zustandsänderndes oder netzendes Kommando startet nie automatisch:

Der Assistent legt ein Manifest an — Programm plus Argumente als feste Liste (argv), nie als freie Shell-Zeile.
Vor der Ausführung erscheint der HITL-Freigabe-Dialog: Er zeigt das exakte argv und einen Trockenlauf (was würde passieren), bevor irgendetwas läuft.
Erst nach menschlicher Freigabe wird ausgeführt. Lesende Aufrufe sind davon ausgenommen; alles Schreibende oder Netzende braucht die Freigabe.
Jede Ausführung erzeugt einen Audit-Eintrag — der Lauf ist nachvollziehbar protokolliert.

Diese menschliche Freigabe ist zusammen mit dem Credential-Scoping die tragende Sicherheitsgrenze (siehe Garantie-Grenze unten), nicht die OS-Sandbox.

Versions-Pinning aktivieren

Roh-Ausgabe von CLIs ist versionsabhängig. Damit nur eine geprüfte, exakte Version startet, gibt es eine Binary-Allowlist mit Prüfsummen-Verifikation.

Voreinstellung ohne Registry = unpinned. Ist keine Registry konfiguriert, startet das Binary ungeprüft (weiterhin unter Sandbox, Egress-Default-Deny, Credential-Scoping und HITL). Das wird einmalig geloggt. So bleibt das Verhalten bestehender Installationen erhalten.
Pinning einschalten: Cli:BinaryRegistryPath auf eine cli-binaries.json setzen. Dann lädt die strikte Registry beim Start.
Fail-loud: Eine konfigurierte, aber fehlende oder defekte Registry-Datei lässt die Anwendung beim Start hart fehlschlagen — eine Allowlist darf nicht stillschweigend zu „alles erlauben” degradieren.

Format der `cli-binaries.json`

Pro Binary: Name → Version → je Plattform Pfad + SHA-256.

{
  "binaries": [
    {
      "name": "git",
      "version": "2.45.1",
      "platforms": {
        "osx-arm64": { "path": "/Applications/CompanyWizard.app/Contents/Resources/bin/git", "sha256": "ab12…" },
        "win-x64":   { "path": "C:\\Program Files\\CompanyWizard\\bin\\git.exe",              "sha256": "ef56…" }
      }
    }
  ]
}

name entspricht exakt manifest.binary (Groß-/Kleinschreibung zählt).
Plattform-Schlüssel sind .NET-RID-Kurzformen: osx-arm64, osx-x64, win-x64, win-arm64, linux-x64, …
sha256 als Hex erzeugen: macOS/Linux shasum -a 256 <Datei>, Windows Get-FileHash <Datei> -Algorithm SHA256.

Vor dem Start prüft der Executor manifest.binary + manifest.version gegen die Registry und verifiziert die Datei für das aktuelle OS/die aktuelle Architektur. Nur ein registriertes, auf die Version gepinntes, für die Plattform vorhandenes und Hash-gleiches Binary startet — und zwar über den von der Registry aufgelösten absoluten Pfad, nie über den rohen Manifest-Wert. Jede Abweichung (nicht registriert, fehlende/abweichende Version, keine Plattform-Entsprechung, Datei fehlt, Hash-Mismatch) ist ein fail-closed Reject — bevor Sandbox, Freigabe-Dialog oder Credential-Auflösung erreicht werden.

Bündelung je OS

Die gepinnten Binaries werden im Photino-Paket mitgeliefert, damit Pfade und Hashes zur Build-Zeit feststehen; die Registry-Datei entsteht als Build-Schritt, der die gebündelten Binaries hasht.

macOS (.pkg/.app): Binaries unter CompanyWizard.app/Contents/Resources/bin/. cli-binaries.json in macos/build-macos.sh nach dem Stagen von Resources/bin/ und vor dem Signieren erzeugen.
Windows (Velopack/vpk): Binaries unter bin\ im Paket-Root; im vpk-Pack-Schritt erzeugen.
Cross-OS-Verfügbarkeit: Nicht jede CLI gibt es für jede Plattform. Eine Registrierung ohne die aktuelle Plattform ist ein fail-closed Reject (kein Fallback) — entscheiden Sie je Binary, welche Plattformen Sie bündeln, und dokumentieren Sie die Lücken.

Lizenz- & Redistribution-Gate

Eine fremde CLI im Paket mitzuliefern ist Redistribution — jede braucht vor dem Ausliefern eine Lizenz- und Patent-Klärung. Aktuell gebündelt: keine. Der unpinned-Default liefert null Binaries; die konkrete CLI-Auswahl ist eine Produkt-/Vertriebsentscheidung. Bevor ein Binary in die Registry und in die Inventar-Tabelle aufgenommen wird, gilt dieses Sign-off:

Lizenz identifizieren aus dem Upstream-Release (nicht raten); SPDX-ID festhalten.
Redistribution für unsere Bündelform geklärt (Binary, in signiertem Installer):
- Permissiv (MIT, BSD-2/3, Apache-2.0, ISC) → geringes Risiko; Apache-2.0 gewährt zusätzlich eine Patent-Lizenz → bevorzugt, wo es eine Wahl gibt.
- Schwaches Copyleft (MPL-2.0, LGPL) → erlaubt, aber datei-/bibliotheksbezogene Pflichten; Binary unverändert lassen und Upstream-Notices mitführen.
- Starkes Copyleft (GPL-2.0/3.0, AGPL) → flaggen. Bündeln löst Quelltext-Angebotspflichten aus, AGPL zusätzlich Netznutzungspflichten. Erfordert ausdrückliches Rechts-Sign-off oder ein anderes Werkzeug — nicht auf Zuruf bündeln.
Patent-Exposition prüfen — permissive/Apache-2.0 mit explizitem Patent-Grant bevorzugen; bekannte Belastungen (Codecs, Krypto-Export) notieren.
Notices mitliefern — Upstream-LICENSE/NOTICE im Paket.
Sign-off eintragen (✅ + wer/wann), bevor der Registry-Pin landet.

Ein Binary, das ohne ✅-Zeile in cli-binaries.json gelangt, ist ein Release-Blocker.

Garantie-Grenze (kurz)

Das Containment ist best-effort plus Egress-Kontrolle, nicht VM-Isolation; die Kern-Grenze ist Credential-Scoping + HITL-Freigabe. Das vollständige, kundenlesbare Statement steht im Endnutzer-Überblick → Befehlszeilen-Werkzeuge (CLI) im Assistenten — Überblick & Grenzen.

Verwandt

Konfigurierbare Werkzeuge — Überblick — Einordnung der selbst konfigurierten Werkzeuge.
Ordner als Werkzeug einrichten (Desktop) — dieselbe Sandbox-/Containment-Story.
Befehlszeilen-Werkzeuge (CLI) — Überblick & Grenzen — Endnutzer-Sicht und Garantie-Statement.