Eigene Detektoren mit der Zeuslock-CLI bauen

Warum eigene Detektoren existieren

Jede Organisation hat Kennungen, die keine Standard-Regex jemals erfassen wird: Kundenreferenznummern wie CUS-12345, interne API-Keys, die Ihr Plattformteam ausstellt, Hostname-Muster für Staging-Cluster, Quellcode-Marker, die nur in Ihrem Monorepo vorkommen, M&A-Codenamen. Die eingebauten Detektoren von Zeuslock decken Kreditkarten, IBAN, JWT, AWS-AKIA-Keys, OpenAI-sk--Tokens und den üblichen Katalog ab — sie erfassen nicht das, was für Ihr Unternehmen einzigartig ist. Eigene Detektoren schließen diese Lücke. Sie nehmen am selben Schweregradmodell, denselben Aktionen Monitor / Anonymize / Block und derselben Incident-Pipeline teil wie die eingebauten.

CLI installieren und authentifizieren

Die Zeuslock-CLI ist die Autorenoberfläche für eigene Detektoren. Sie wird über npm und Homebrew verteilt.

npm i -g @zeuslock/cli
# oder
brew install zeuslock/tap/cli

zeuslock --version
zeuslock auth login

zeuslock auth login öffnet Ihren Browser, führt einen OAuth-Flow gegen Ihren Operator-Console-Tenant aus und legt ein kurzlebiges Refresh-Token im Schlüsselbund des Betriebssystems ab. Das Token erbt Ihre Konsolenrolle: Nur Nutzer mit der Rolle Detector Author oder Admin dürfen deployen. Alle anderen Befehle funktionieren für jeden authentifizierten Nutzer.

Das YAML-Schema eines Detektors

Ein Detektor ist eine YAML-Datei. Hier ein vollständiges, realistisches Beispiel für eine interne Kundenkennung der Form CUS-XXXXX:

name: customer-id
description: Interne Acme-Kundennummer CUS-XXXXX
severity: medium
action: anonymize
patterns:
  - regex: 'CUS-[0-9]{5}'
    flags: i
validators:
  - type: context_keyword_within
    keywords: [kunde, customer, konto]
    window_chars: 50
replacement: 'CUS-XXXXX'
contexts:
  apply_to: [browser, desktop, cli]
  skip_destinations: [chat.internal.acme.com]

Validator-Typen

• luhn — wendet die Luhn-Prüfsumme an. Für alles, was wie eine Karten- oder Mitgliedsnummer aussieht.
• mod97 — IBAN-artige Modulo-97-Prüfung.
• entropy — verlangt, dass die Shannon-Entropie der Übereinstimmung einen Schwellwert überschreitet (min: 3.5). Kritisch für hochentropische Geheimnisse wie API-Keys.
• context_keyword_within — verlangt, dass eines der keywords innerhalb von window_chars um die Übereinstimmung herum vorkommt. Brutal wirksam gegen Falsch-Positive.
• post_regex — eine zweite Regex auf die vollständige Übereinstimmung zur strukturellen Bestätigung.

Der Autoren-Workflow

Die CLI ist um eine enge Feedback-Schleife gebaut: scaffolden, testen, backtesten, deployen, beobachten.

1. Scaffolden. zeuslock detectors init customer-id erzeugt customer-id.yaml im aktuellen Verzeichnis mit sinnvollen Defaults und Inline-Kommentaren.
2. Regex schreiben. Öffnen Sie die YAML, ersetzen Sie das Platzhalter-Pattern, fügen Sie Validatoren hinzu. Halten Sie die Regex eng — siehe die Anti-Patterns unten.
3. Lokale Vorschau. Testen Sie sofort eine einzelne Zeichenkette:

   zeuslock detectors test ./customer-id.yaml \
     --input "Bitte Kunde CUS-12345 heute erstatten"

   Die CLI gibt jede Übereinstimmung, die bestandenen oder gescheiterten Validatoren und die resultierende Aktion aus.
4. Backtest gegen echte Historie. Das Killer-Feature:

   zeuslock detectors backtest ./customer-id.yaml \
     --since 30d --sample 1000

   Zeuslock spielt Ihren Detektor gegen die letzten 30 Tage Incidents ab (bereits beim Ingest geschwärzt) und meldet geschätzte True Positives, geschätzte False Positives und eine Vorschauliste auslösender Snippets, sodass Sie das Rauschen mit dem Auge prüfen können.
5. Iterieren. Verschärfen Sie die Regex oder fügen Sie Validatoren hinzu, bis die Falsch-Positiv-Rate im Backtest akzeptabel ist. Alles über 5 % behandeln wir als Release-Blocker.
6. Trockenlauf-Deploy. zeuslock detectors deploy ./customer-id.yaml --group engineering --dry-run zeigt das Diff gegenüber der aktuell aktiven Version und was sich in den Richtlinien-Zuweisungen ändern würde — ohne zu veröffentlichen.
7. Deployen. Entfernen Sie --dry-run. Der Detektor ist innerhalb von Sekunden auf jeder verbundenen Browser-Erweiterung, jedem Desktop-Agent und jeder CLI-Instanz der Zielgruppe aktiv.

Operativer Lebenszyklus

zeuslock detectors list
zeuslock detectors show customer-id
zeuslock detectors disable customer-id
zeuslock detectors rollback customer-id --version 3

Jeder Deploy erzeugt eine neue unveränderliche Version. disable pausiert den Detektor, ohne ihn zu löschen; rollback reaktiviert eine frühere Version als aktive, ohne Historie zu verlieren. Die Konsole zeigt dieselben Versionen als Zeitleiste, mit Autor, Deploy-Zeit und Diff jeder Version.

CI-Integration

Detektor-YAMLs gehören in ein Git-Repository und werden wie jedes andere Produktionsartefakt im Code-Review geprüft. Lassen Sie zeuslock detectors test als Pull-Request-Check laufen, damit eine kaputte Regex nie den Deploy-Schritt erreicht.

name: detector-ci
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm i -g @zeuslock/cli
      - run: zeuslock auth token --from-env
        env:
          ZEUSLOCK_CI_TOKEN: ${{ secrets.ZEUSLOCK_CI_TOKEN }}
      - run: |
          for f in detectors/*.yaml; do
            zeuslock detectors test "$f" --fixtures fixtures/
          done
      - run: zeuslock detectors backtest detectors/ --since 7d --sample 500

Legen Sie zu jeder Detektor-YAML ein Verzeichnis fixtures/ mit should-match.txt und should-not-match.txt an. Das Flag --fixtures prüft beide Richtungen: jede Zeile in should-match muss einen Treffer erzeugen, jede Zeile in should-not-match darf das nicht. Detektor-Regressionen werden zu Diff-Kommentaren auf dem PR, nicht zu Anrufen um 3 Uhr morgens.

Anti-Patterns, die im Review abzulehnen sind

Wie es weitergeht

Sobald Ihr Detektor live ist, erscheint er in derselben Richtlinienmatrix wie die eingebauten Detektoren — Sie können ihn pro Gruppe, pro Ziel und pro Zeitplan in der Operator-Console eingrenzen. Übergeben Sie die YAML-Dateien Ihrem Detection-Engineering-Team als Code; behandeln Sie das Git-Repository, nicht die Konsole, als Source of Truth.