linebreak-gate

Compuerta de CI con cierre ante fallos para código escrito por IA: bloquea CVEs conocidos y sirve criterios de aceptación aprobados por humanos a Claude Code/Cursor/Codex a través de MCP, de solo lectura para el agente.

GitHubPrueba este MCPPatrocinado

Documentación

linebreak-gate — la puerta de seguridad LineBreak en el límite git/CI

Véalo en acción

Una grabación real, sin simulaciones: el escaneo bloquea una CVE crítica con cierre ante fallo, el pin se corrige, la puerta se abre.

linebreak-gate scan blocking a critical CVE, then passing after the fix

El bucle de especificación: una persona nombrada aprueba los criterios, check bloquea hasta que el criterio manual lleva una aprobación firmada, y entonces todo pasa.

spec approve, check blocked until sign-off, then all criteria pass

Bloquea fusiones que contienen vulnerabilidades conocidas. Una herramienta, dos detectores — el escaneo de dependencias es gratuito; la revisión con IA es la mejora Pro:

Escaneo de CVE de dependencias — gratuito, sin clave — osv-scanner en todos los ecosistemas (npm, PyPI, Go, Cargo, Maven, …), con un respaldo npm audit para proyectos npm (cobertura solo npm y sin datos de versión instalada — la acción de GitHub falla con cierre si osv-scanner no se puede instalar en lugar de degradar a él).
SAST con IA — Pro — una revisión de seguridad con LLM del código fuente propio (inyección, autenticación rota, exposición de secretos, SSRF, deserialización insegura, mal uso criptográfico) con verificación adversarial, habilitada por LINEBREAK_LICENSE_KEY (alojado, usa créditos) o ANTHROPIC_API_KEY (su propia clave, tiene prioridad). Sin una clave, el escaneo de dependencias aún se ejecuta y esta pasada se omite con un aviso.

La puerta bloquea y puede proponer; nunca se auto-limpia por la palabra de un agente. Una persona aprueba la corrección o registra una excepción — con una razón y un aprobador — en un archivo de auditoría confirmado en git.

Este es el mismo núcleo de escaneo que impulsa el resto de la puerta de seguridad dentro del producto de LineBreak (el backend de escritorio importa este paquete), pero es totalmente independiente: un equipo que nunca ha tocado nada más de LineBreak puede añadir la puerta a su repositorio y obtener aplicación real.

Contribuciones y licencia. Este repositorio es la fuente publicada de linebreak-gate (Apache-2.0): cada versión llega aquí y a PyPI desde nuestro CI, y cada cambio pasó nuestra propia puerta primero — escaneo de CVE y criterios aprobados por humanos, la misma disciplina que vendemos. Informes de errores y solicitudes de funciones: abra un issue o discusión aquí; leemos todo. Los PR directos a este repositorio no se pueden fusionar (las versiones fluyen a través de nuestro pipeline de revisión), así que comience con un issue y nosotros lo tomamos desde ahí.

Inicio rápido — GitHub Actions

# .github/workflows/security-gate.yml
name: Security gate
on:
  pull_request:

permissions:
  contents: read
  pull-requests: write # for the summary comment

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: Baktun-Studio/linebreak-gate@v1
        with:
          # fail-on: high # blocking floor; default: critical
          # Optional today; required once license enforcement is enabled.
          license-key: ${{ secrets.LINEBREAK_LICENSE_KEY }}
          # Enables the AI code review; leave unset for dependency scan only.
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

La acción ejecuta linebreak-gate scan, siempre ejecuta report, publica un comentario de PR (actualizado en el lugar en cada push, nunca spam), sube el informe JSON

artefactos de auditoría como artefacto de workflow, y falla la verificación según el código de salida del escaneo.

Conviértalo en un límite real: exija la verificación

Un trabajo de CI que se puede ignorar es un panel, no una puerta. En su repositorio:

Configuración → Ramas → Reglas de protección de ramas → su rama predeterminada → "Exigir que las verificaciones de estado pasen antes de fusionar" → añada el trabajo gate (el nombre del trabajo que ejecuta esta acción). Desde entonces, un PR que contenga una CVE crítica no se puede fusionar a través de la interfaz de GitHub.

Inicio rápido — cualquier otro CI (ejemplo de GitLab)

El CLI es un paquete Python simple con códigos de salida estrictos — 0 pasa, 1 hallazgos bloqueantes, 2 error de herramienta/configuración (cierre ante fallo: un bloqueo del escáner falla el pipeline, nunca es un pase limpio). Cualquier CI que respete los códigos de salida obtiene la misma aplicación:

# .gitlab-ci.yml
security-gate:
  image: python:3.11
  script:
    - pip install linebreak-gate
    - curl -fsSL -o /usr/local/bin/osv-scanner
      "$(curl -fsSL https://api.github.com/repos/google/osv-scanner/releases/latest
      | python -c "import json,sys;print(next(a['browser_download_url'] for a in json.load(sys.stdin)['assets'] if a['name'].endswith('linux_amd64')))")"
    - chmod +x /usr/local/bin/osv-scanner
    - linebreak-gate scan
    - linebreak-gate report

Marque el trabajo como requerido (sin allow_failure) y proteja la rama.

El bucle de especificación — autor, apruebe, sirva sobre MCP, aplique

La puerta también aplica criterios de aceptación aprobados, y todo el bucle es agnóstico a la herramienta — sin cuenta de LineBreak, sin aplicación de escritorio, sin servidor:

linebreak-gate spec new        # scaffold a draft — fill it with any tool (your
                               # editor, Claude Code, ChatGPT), or distill it
                               # from the PRD you already have in Notion/Jira
linebreak-gate spec approve .linebreak/spec-draft.yml \
  --approver "Ana Lopez <ana@example.com>"   # a human on the record; commits
linebreak-gate mcp install --editor claude-code   # or: cursor · codex

linebreak-gate mcp sirve el paquete aprobado (.linebreak/spec/) sobre MCP (stdio) a Claude Code, Cursor, Codex, o cualquier cliente MCP. Seis herramientas: list_stories, get_story (criterios como contexto del agente ANTES de que se escriba código), next_story, set_story_status, check_story (el mismo motor de evaluación que ejecuta CI, limitado a una historia), y spec_status (aprobación + estado de firma sin conexión). Git es el transporte — sin red, sin cuenta, funciona en un clon simple — y nada en el puente puede escribir, editar o invalidar un criterio aprobado: los criterios cambian solo editando el borrador y re-aprobando, con una persona en el registro.

Luego linebreak-gate check aplica los mismos criterios en CI: las verificaciones de máquina se ejecutan de verdad, los criterios manual bloquean hasta que haya una aprobación registrada. Primera ejecución guiada con el porqué de cada paso: linebreakapp.com/en/start.

CLI

linebreak-gate init     [--path .] [--fail-on critical|high|medium|low] [--force] [--non-interactive]
linebreak-gate scan     [--path .] [--fail-on critical|high|medium|low] [--format summary|json]
linebreak-gate report   [--path .] [--format summary|json]
linebreak-gate override --finding <id> --reason "…" --approver <name/email> [--path .]
linebreak-gate override --criterion <id> --reason "…" --approver <name/email> [--path .]
linebreak-gate check    [--path .] [--format summary|json]
linebreak-gate signoff  --criterion <id> --approver <name/email> --note "…" [--path .]
linebreak-gate spec new     [--path .] [--out <file>] [--force]
linebreak-gate spec approve <draft> --approver <name/email> [--role architect] [--path .]
linebreak-gate spec list|next [--path .]
linebreak-gate spec show|check <story-id> [--path .]
linebreak-gate mcp      [--path .]            # serve the approved spec over stdio
linebreak-gate mcp install [--editor claude-code|cursor|codex] [--print]
linebreak-gate badge    [--format markdown|html|url]

init configura un repositorio en un comando: escribe el archivo de workflow (nunca sobrescribe uno existente sin --force), opcionalmente escribe .linebreak/gate.yml, ofrece almacenar los secretos a través del CLI de GitHub y exigir la verificación gate — e imprime los enlaces de configuración exactos para cualquier cosa que no pueda hacer por usted.
scan ejecuta ambos detectores, escribe artefactos de auditoría nativos de git bajo .linebreak/audit/, y sale con 0/1/2.
report renderiza el escaneo registrado: conteos por severidad y cada hallazgo con ID de CVE, CVSS, enlace de aviso y estado de excepción. --format json para máquinas.
override registra un reconocimiento aprobado por humanos de un hallazgo exacto — el paquete + versión instalada + tupla de CVE. Una CVE diferente, una versión actualizada o un nuevo hallazgo aún bloquean. --reason y --approver son requeridos; el registro aterriza en el rastro de aprobación del artefacto. Confirme el .linebreak/audit/*.json actualizado para que CI lo vea.
check evalúa los criterios de aceptación aprobados (.linebreak/spec/, aterrizado por spec approve) contra el árbol de trabajo: build/tests/command se ejecutan de verdad, manual requiere una aprobación registrada. Sale 0 si todo está satisfecho (o sin paquete — un no-op limpio), 1 bloqueante (fallo o requiere aprobación), 2 error de herramienta/configuración/paquete (cierre ante fallo). Escribe .linebreak/audit/criteria.json.
signoff registra una aprobación humana atribuida para un criterio manual bajo .linebreak/spec/signoffs/ (aditivo; --approver y --note requeridos). Se vincula al criterio como aprobado — editar el criterio y re-aprobar la especificación hace que las aprobaciones anteriores queden obsoletas. Confirme el registro.
override --criterion registra una excepción aprobada por humanos para un criterio de máquina fallido en .linebreak/audit/criteria.json — misma filosofía que las excepciones de CVE: posible, siempre atribuida, obsoleta una vez que el criterio se edita. Otros criterios bloqueantes aún bloquean.
spec new / spec approve — la ruta de autoría agnóstica a la herramienta (vea la sección del bucle de especificación arriba): cree un borrador, llénelo con cualquier herramienta, aterrícelo como el paquete aprobado con una aprobación humana atribuida, confirmado. Las aprobaciones locales sin firmar se marcan identity_source: client; las firmas criptográficas vienen del servicio de gobernanza (clave de licencia).
spec list imprime el paquete de criterios de aceptación aprobados: cada historia, sus criterios con tipos de verificación y la atribución del aprobador. Solo lectura. Sale 0 con un paquete válido o cuando no existe ninguno; sale 2 con un paquete malformado (cierre ante fallo en estructura). spec next / show / check son los gemelos CLI de las herramientas del puente MCP.

Insignia

Muestre a los visitantes que el repositorio está protegido. linebreak-gate badge imprime un fragmento de README listo para pegar (sin llamadas de red — la insignia estática de shields.io está completamente codificada en su URL); --format html|url para las variantes de etiqueta o URL simple:

[![gated by LineBreak](https://img.shields.io/badge/gated%20by-LineBreak-14120F?labelColor=FAF8F4)](https://www.linebreakapp.com/en/gate)

Configuración — `.linebreak/gate.yml`

La estrictez de la puerta es gobernanza, por lo que vive en el repositorio — cambiar el umbral es en sí mismo un PR: visible, revisable, atribuible en el historial de git.

# .linebreak/gate.yml
fail_on: critical # critical (default) | high | medium | low
exclude_paths: # optional: root-relative globs excluded from scanning
  - fixtures
  - "sandbox/*"
code_scan: auto # auto (run when model credentials are set) | on (required) | off
criteria:
  enforce: true # default: true whenever a spec bundle exists; false disables
  # criteria checking only (the security scan is unaffected)

Precedencia: bandera explícita --fail-on / entrada de Action → .linebreak/gate.yml → predeterminado integrado (critical). Una configuración inválida es un error de herramienta (salida 2) — un archivo de gobernanza roto nunca cae silenciosamente a un predeterminado.

Registros de auditoría

Cada escaneo y cada excepción se registran en .linebreak/audit/security.json (dependencias) y .linebreak/audit/code.json (SAST con IA) — el mismo formato de documento versionado que escriben las herramientas de LineBreak, con hallazgos (ID de CVE, CVSS, enlace de aviso), motor de escaneo, marca de tiempo, actor y el rastro de aprobación con la razón + aprobador de cada excepción. Quién relajó la puerta, y cuándo, es en sí mismo auditable.

Precios

Gratuito, para siempre: el escaneo de CVE de dependencias y todo el bucle de especificación — autoría, aprobación humana, servicio MCP y aplicación en CI. Sin clave, sin cuenta.

Pro — $99/mes por equipo (precios): aprobaciones firmadas criptográficamente y a prueba de manipulación (Ed25519, verificables sin conexión), modo de aplicación con clave requerida, y revisión de código con IA alojada sin clave de API que gestionar. Compre en la página de precios — su LINEBREAK_LICENSE_KEY llega por correo electrónico en segundos (es la entrada license-key de la Action). ¿Prefiere su propia clave de modelo? ANTHROPIC_API_KEY también habilita la revisión con IA; la revisión alojada de Pro es la ruta de configuración cero.

La puerta se ejecuta abierta por defecto: funciona sin clave e imprime un aviso cuando no se establece LINEBREAK_LICENSE_KEY (suprimido para usuarios BYOK). Eso es freemium — el escaneo de dependencias se ejecuta gratis. Los equipos que quieran exigir una clave Pro válida para que la puerta se ejecute en absoluto pueden optar por LINEBREAK_ENTITLEMENTS_PROVIDER=remote, que verifica el derecho antes de cualquier escaneo y falla con cierre ante una clave faltante/inválida/revocada, plan incorrecto o servicio inalcanzable — bloqueando toda la puerta, incluido el escaneo de dependencias.