Créer des détecteurs personnalisés avec la CLI Zeuslock

Concevoir, backtester et livrer des détecteurs propres à votre organisation pour les identifiants internes, clés API et marqueurs de code, avec versioning et garde-fous CI.

Pourquoi des détecteurs personnalisés

Chaque organisation possède des identifiants qu'aucune regex prête à l'emploi ne capturera jamais : numéros de référence client comme CUS-12345, clés API internes émises par votre équipe plateforme, motifs de noms d'hôtes pour vos clusters de staging, marqueurs de code source qui n'existent que dans votre monorepo, noms de code de cibles M&A. Les détecteurs intégrés de Zeuslock couvrent les cartes bancaires, IBAN, JWT, clés AWS AKIA, jetons OpenAI sk- et le catalogue habituel — ils ne capturent pas ce qui est propre à votre entreprise. Les détecteurs personnalisés comblent cet écart. Ils participent au même modèle de sévérité, aux mêmes actions Monitor / Anonymize / Block et au même pipeline d'incidents que les détecteurs intégrés.

Installer la CLI et s'authentifier

La CLI Zeuslock est la surface d'écriture des détecteurs personnalisés. Elle est distribuée via npm et Homebrew.

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

zeuslock --version
zeuslock auth login

zeuslock auth login ouvre votre navigateur, effectue un flux OAuth contre votre tenant Operator Console et stocke un jeton de rafraîchissement à courte durée dans le trousseau de l'OS. Le jeton hérite de votre rôle console : seuls les utilisateurs ayant le rôle Detector Author ou Admin peuvent déployer. Les autres commandes fonctionnent pour tout utilisateur authentifié.

Le schéma YAML d'un détecteur

Un détecteur est un fichier YAML. Voici un exemple complet et réaliste pour un identifiant client interne au format CUS-XXXXX :

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

Champ	Rôle
`name`	Identifiant unique au sein de votre tenant. Minuscules, kebab-case. Utilisé dans les politiques, les tableaux de bord et les commandes de rollback.
`description`	Lisible par un humain. Affichée dans l'Operator Console à côté de chaque incident levé par ce détecteur.
`severity`	`low`, `medium`, `high` ou `critical`. Détermine le routage par défaut dans le tableau de bord d'incidents.
`action`	`monitor`, `anonymize` ou `block`. Peut toujours être surchargé par groupe depuis la console.
`patterns[].regex`	Syntaxe RE2 — pas de lookbehind, pas de rétro-références. Ancres et classes de caractères encouragées.
`patterns[].flags`	`i` pour insensible à la casse, `m` pour multiligne. À combiner sous la forme `im`.
`validators[]`	Filtres post-correspondance qui suppriment les faux positifs. Types détaillés ci-dessous.
`replacement`	Modèle de rédaction préservant le format utilisé quand `action: anonymize`. Doit rester syntaxiquement valide vis-à-vis de la même regex.
`contexts.apply_to`	Surfaces où ce détecteur s'exécute : sous-ensemble parmi `browser`, `desktop`, `cli`, `api`.
`contexts.skip_destinations`	Noms d'hôtes ou motifs d'URL à exclure — typiquement vos outils IA internes où la valeur est légitime.

Types de validateurs

luhn — applique la somme de contrôle Luhn. À utiliser sur tout ce qui ressemble à une carte ou un numéro d'adhérent.
mod97 — contrôle modulo 97 façon IBAN.
entropy — exige que l'entropie de Shannon de la correspondance dépasse un seuil (min: 3.5). Indispensable pour les secrets à haute entropie comme les clés API.
context_keyword_within — exige qu'un des keywords apparaisse dans une fenêtre de window_chars autour de la correspondance. Brutalement efficace contre les faux positifs.
post_regex — une seconde regex appliquée à la correspondance complète pour confirmation structurelle.

Le workflow de création

La CLI est conçue autour d'une boucle de feedback courte : scaffolder, tester, backtester, déployer, surveiller.

Scaffolder. zeuslock detectors init customer-id crée customer-id.yaml dans le répertoire courant avec des valeurs par défaut raisonnables et des commentaires inline.
Écrire la regex. Ouvrez le YAML, remplacez le motif de remplacement, ajoutez des validateurs. Gardez la regex étroite — voir les anti-patterns plus bas.
Aperçu local. Testez immédiatement une chaîne :
```
zeuslock detectors test ./customer-id.yaml \
  --input "Merci de rembourser le client CUS-12345 aujourd'hui"
```
La CLI affiche chaque correspondance, les validateurs passés ou échoués et l'action résultante.
Backtester sur l'historique réel. La fonction clé :
```
zeuslock detectors backtest ./customer-id.yaml \
  --since 30d --sample 1000
```
Zeuslock rejoue votre détecteur sur les 30 derniers jours d'incidents (déjà rédigés à l'ingestion) et rapporte les vrais positifs estimés, les faux positifs estimés et une liste d'aperçu des extraits déclencheurs pour évaluer le bruit à l'œil.
Itérer. Resserrez la regex ou ajoutez des validateurs jusqu'à ce que le taux de faux positifs du backtest soit acceptable. Au-delà de 5 %, nous traitons cela comme un blocage de release.
Déploiement à blanc. zeuslock detectors deploy ./customer-id.yaml --group engineering --dry-run montre le diff avec la version actuellement active et ce qui changerait dans les attributions de politique — sans publier.
Déployer. Enlevez --dry-run. Le détecteur est actif en quelques secondes sur chaque extension navigateur, agent desktop et instance CLI connectés dans le groupe ciblé.

Cycle de vie opérationnel

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

Chaque déploiement crée une nouvelle version immuable. disable met en pause le détecteur sans le supprimer ; rollback réactive une version antérieure comme version active sans perdre l'historique. La console expose les mêmes versions en timeline, avec l'auteur, l'heure de déploiement et le diff de chacune.

Intégration CI

Les YAML de détecteurs ont leur place dans un dépôt Git, revus par les pairs comme tout artefact de production. Lancez zeuslock detectors test comme contrôle de pull request pour qu'une regex cassée n'atteigne jamais l'étape Deploy.

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

Associez à chaque YAML un dossier fixtures/ contenant should-match.txt et should-not-match.txt. Le drapeau --fixtures vérifie les deux sens : chaque ligne de should-match doit produire un hit, chaque ligne de should-not-match ne doit pas. Les régressions de détecteurs deviennent des commentaires de diff sur la PR, pas des appels à 3 h du matin.

Anti-patterns à refuser en revue

Regex trop large. Un motif comme \d+ ou [A-Z]{5,} sans validateurs capturera la moitié de votre trafic. Ancrez vos motifs et exigez un préfixe structurel (le CUS- de l'exemple fait un vrai travail).

Aucun validateur sur un candidat à haute entropie. Tout ce qui prétend être un secret doit au minimum porter un validateur entropy. Sans cela, vous signalerez des miniatures encodées en base64, des SHA de commits Git et des UUID comme identifiants.

action: block sur un détecteur non backtesté. Jamais. Livrez tout nouveau détecteur en monitor pendant au moins une semaine, examinez les incidents, passez en anonymize, et ne basculez en block que lorsque le taux de faux positifs sur un échantillon de 1000 incidents passe sous 1 %.

Pour aller plus loin

Une fois votre détecteur en production, il apparaît dans la même matrice de politiques que les détecteurs intégrés — vous pouvez l'attribuer par groupe, par destination et par horaire depuis l'Operator Console. Confiez les fichiers YAML à votre équipe d'ingénierie de détection comme du code ; traitez le dépôt Git, pas la console, comme la source de vérité.