Crear detectores personalizados con la CLI de Zeuslock

Diseñe, haga backtest y publique detectores específicos de su organización para IDs internos, claves API y marcadores de código fuente con la CLI de Zeuslock — con versionado y comprobaciones de CI.

Por qué existen los detectores personalizados

Cada organización tiene identificadores que ninguna regex prefabricada capturará jamás: números de referencia de cliente como CUS-12345, claves API internas emitidas por su equipo de plataforma, patrones de hostname para clusters de staging, marcadores de código fuente que solo aparecen en su monorepo, nombres en clave de objetivos de M&A. Los detectores integrados de Zeuslock cubren tarjetas de crédito, IBAN, JWT, claves AWS AKIA, tokens OpenAI sk- y el catálogo habitual — no capturarán lo que es propio de su empresa. Los detectores personalizados cierran esa brecha. Participan en el mismo modelo de severidad, las mismas acciones Monitor / Anonymize / Block y el mismo pipeline de incidentes que los integrados.

Instalar la CLI y autenticarse

La CLI de Zeuslock es la superficie de autoría para detectores personalizados. Se distribuye vía npm y Homebrew.

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

zeuslock --version
zeuslock auth login

zeuslock auth login abre el navegador, completa un flujo OAuth contra su tenant de Operator Console y guarda un refresh token de corta vida en el llavero del sistema operativo. El token hereda su rol en consola: solo los usuarios con rol Detector Author o Admin pueden desplegar. Los demás comandos funcionan para cualquier usuario autenticado.

El esquema YAML del detector

Un detector es un fichero YAML. Aquí tiene un ejemplo completo y realista para un identificador interno de cliente con forma CUS-XXXXX:

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

Campo	Función
`name`	Identificador único dentro de su tenant. Minúsculas, kebab-case. Se usa en políticas, paneles y comandos de rollback.
`description`	Legible por humanos. Aparece en la Operator Console junto a cada incidente que este detector levanta.
`severity`	`low`, `medium`, `high` o `critical`. Determina el enrutado por defecto en el panel de incidentes.
`action`	`monitor`, `anonymize` o `block`. Siempre puede sobrescribirse por grupo desde la consola.
`patterns[].regex`	Sintaxis RE2 — sin lookbehind, sin retro-referencias. Se recomiendan anclas y clases de caracteres.
`patterns[].flags`	`i` para ignorar mayúsculas, `m` para multilínea. Combinables como `im`.
`validators[]`	Filtros post-coincidencia que suprimen falsos positivos. Tipos detallados más abajo.
`replacement`	Plantilla de redacción que preserva el formato cuando `action: anonymize`. Debe seguir siendo sintácticamente válida frente a la misma regex.
`contexts.apply_to`	Superficies donde corre este detector: cualquier subconjunto de `browser`, `desktop`, `cli`, `api`.
`contexts.skip_destinations`	Hostnames o patrones de URL a excluir — normalmente sus herramientas de IA internas donde el valor es legítimo.

Tipos de validadores

luhn — aplica el checksum de Luhn. Úselo en cualquier cosa con forma de tarjeta o número de miembro.
mod97 — comprobación módulo 97 al estilo IBAN.
entropy — exige que la entropía de Shannon de la coincidencia supere un umbral (min: 3.5). Imprescindible para secretos de alta entropía como las claves API.
context_keyword_within — exige que aparezca alguna de las keywords dentro de window_chars alrededor de la coincidencia. Brutalmente eficaz contra falsos positivos.
post_regex — una segunda regex aplicada sobre la coincidencia completa para confirmación estructural.

El flujo de autoría

La CLI está diseñada en torno a un bucle de feedback corto: andamiar, probar, hacer backtest, desplegar, vigilar.

Andamiar. zeuslock detectors init customer-id crea customer-id.yaml en el directorio actual con valores por defecto sensatos y comentarios inline.
Escribir la regex. Abra el YAML, sustituya el patrón placeholder, añada validadores. Mantenga la regex estrecha — vea los anti-patrones más abajo.
Vista previa local. Pruebe una sola cadena inmediatamente:
```
zeuslock detectors test ./customer-id.yaml \
  --input "Devuelve el importe al cliente CUS-12345 hoy"
```
La CLI imprime cada coincidencia, los validadores que pasaron o fallaron y la acción resultante.
Backtest contra historial real. La función clave:
```
zeuslock detectors backtest ./customer-id.yaml \
  --since 30d --sample 1000
```
Zeuslock reproduce su detector contra los últimos 30 días de incidentes (ya redactados en la ingesta) e informa de los verdaderos positivos estimados, los falsos positivos estimados y una lista de previsualización de los fragmentos disparadores para evaluar el ruido a ojo.
Iterar. Apriete la regex o añada validadores hasta que la tasa de falsos positivos del backtest sea aceptable. Por encima del 5 % lo tratamos como bloqueo de release.
Despliegue en seco. zeuslock detectors deploy ./customer-id.yaml --group engineering --dry-run muestra el diff frente a la versión activa actual y qué cambiaría en las asignaciones de política — sin publicar.
Desplegar. Quite --dry-run. El detector está activo en segundos en cada extensión de navegador, agente de escritorio e instancia CLI conectados del grupo destino.

Ciclo de vida operativo

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

Cada despliegue crea una versión nueva e inmutable. disable pausa el detector sin borrarlo; rollback reactiva una versión anterior como la activa sin perder el historial. La consola expone las mismas versiones en una línea de tiempo, con el autor, la hora de despliegue y el diff de cada una.

Integración con CI

Los YAML de detectores viven en un repo Git, revisados como cualquier otro artefacto de producción. Ejecute zeuslock detectors test como check de pull request para que una regex rota jamás llegue al paso 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

Acompañe cada YAML con un directorio fixtures/ con should-match.txt y should-not-match.txt. El flag --fixtures afirma ambos sentidos: cada línea de should-match debe producir un hit, cada línea de should-not-match no debe producirlo. Las regresiones de detectores se convierten en comentarios de diff en la PR, no en avisos a las 3 de la madrugada.

Anti-patrones a rechazar en revisión

Regex demasiado amplia. Un patrón como \d+ o [A-Z]{5,} sin validadores capturará la mitad de su tráfico. Ancle sus patrones y exija un prefijo estructural (el CUS- del ejemplo está haciendo trabajo real).

Ningún validador sobre un candidato de alta entropía. Cualquier cosa que afirme ser un secreto necesita como mínimo un validador entropy. Sin él marcará miniaturas codificadas en base64, SHAs de commits de Git y UUIDs como credenciales.

action: block en un detector sin backtest. Nunca. Publique cada detector nuevo en monitor durante al menos una semana, revise los incidentes, escale a anonymize y solo pase a block cuando la tasa de falsos positivos sobre una muestra de 1000 incidentes baje del 1 %.

Por dónde seguir

Una vez su detector esté en producción, aparece en la misma matriz de políticas que los detectores integrados — puede acotarlo por grupo, por destino y por horario desde la Operator Console. Entregue los ficheros YAML a su equipo de ingeniería de detección como código; trate el repositorio Git, no la consola, como la fuente de verdad.