Modo offline: Vericto sin cuenta

Revisa SQL con las reglas estándar de Vericto en tu máquina o en tu runner de CI: sin cuenta, sin API key y sin red. La CLI, la GitHub Action y el proxy, con la salida real de la CLI 2.3.0.

Qué es

En modo offline, Vericto evalúa el SQL en tu máquina con el motor que viene dentro del binario. No hace falta cuenta ni API key, no se hace ninguna solicitud de red, ni a Vericto ni a nadie, y el SQL nunca sale de la máquina. La CLI 2.3.0 trae vericto-engine 5.1.0 y sus 42 reglas estándar con sus severidades por defecto: Critical y High bloquean, Medium marca (FLAGGED) y Low queda en monitoreo (MONITORED).

Es una barrera base: responde «¿este SQL es obviamente peligroso?». No es la política de tu workspace ni deja constancia de que el check ocurrió; para eso está el modo online (ver Qué agrega un workspace). Está en tres lugares:

  • La CLI: vericto check --offline, en tu terminal, en un hook de pre-commit o en cualquier CI. Linux, macOS y Windows (x64 y ARM64).
  • La GitHub Action: vericto/check-sql@v1 con offline: true.
  • El proxy: vericto-proxy mcp en modo local y el proxy TCP sin workspace, con las reglas integradas.

La CLI: vericto check --offline

Instala la CLI (Homebrew, npm, Scoop, el instalador de shell o de PowerShell, Docker o el binario de la release: ver Instalar y autenticar) y pasa --offline, o define VERICTO_OFFLINE=1:

# No account, no network: the standard rules at their default severities
vericto check --offline migrations/*.sql
vericto check --offline db/migrate/        # every *.sql under it, recursively
git show :db/schema.sql | vericto check --offline - --dialect mysql
VERICTO_OFFLINE=1 vericto check db/migrate/

# Zero-install, with Node 18+
npx @vericto/vericto-cli check --offline migrations/*.sql

Las opciones de vericto check funcionan igual que online: --dialect (postgres por defecto, mysql, oracle, mssql, snowflake y sqlite), --fail-on, --format, --output, --quiet, --monitor, --baseline, los comentarios -- vericto:ignore[...], --changed y --since (un diff de git local). Los comentarios vericto:ignore cuentan en archivos; en --sql y stdin solo con --allow-inline-ignore (CLI 2.3.0), porque ese texto nadie lo revisa y puede escribirlo el mismo agente que se revisa. --receipt, --oidc, --allow-degraded y --allow-unsanitized necesitan un workspace: en offline se rechazan con exit 2 en lugar de ignorarse.

Cuándo es automático

  • --offline o VERICTO_OFFLINE=1: offline siempre, también en CI y aunque haya una key.
  • Fuera de CI, sin API key, sin vericto login y sin token OIDC: offline por sí sola, y lo dice en stderr.
  • En CI (CI, GITHUB_ACTIONS, GITLAB_CI, BUILDKITE, JENKINS_URL y otras variables de CI), una credencial que falta sigue siendo exit 3: un pipeline cuyo secreto desapareció no pasa en silencio a menos reglas. Pasa --offline para elegirlo.
  • Una key presente pero inválida es exit 3 y un backend inalcanzable es exit 4: ninguno de los dos pasa a offline. .vericto.toml no puede elegir el modo: una clave offline commiteada se rechaza (exit 2).

El perfil de CI: el DDL de una migración sale FLAGGED

Desde la CLI 2.3.0, las reglas de cambios de esquema (VERICTO-010, 013, 015 a 019, 094 y 099: DROP TABLE, ALTER…) salen como máximo FLAGGED solo en archivos de migración, porque una migración en un PR la revisan personas. Un archivo es una migración si está bajo un directorio migrations/, migration/ o migrate/, si se llama como en Flyway (V2__nombre.sql) o golang-migrate (1_nombre.up.sql), o si su ruta está en migration_paths de .vericto.toml. --sql, stdin y los demás archivos se revisan como SQL de runtime: el DDL bloquea, y la CLI explica en stderr cómo reconoce las migraciones. TRUNCATE (VERICTO-011) y DROP SCHEMA / DATABASE (VERICTO-012) bloquean siempre, también en una migración. Con --fail-on block, el valor por defecto, una migración que solo tiene DDL sale con exit 0 y muestra el hallazgo; para que falle, usa --fail-on flag. Online el tope todavía cubre todos los archivos, y TRUNCATE y DROP SCHEMA / DATABASE hasta que se despliegue vericto-eval 2.12.0.

Un archivo con varias sentencias reporta el hallazgo con la acción más fuerte: en una migración con DROP TABLE a; DELETE FROM sessions; el DROP queda marcado, pero el DELETE sin WHERE bloquea, así que el archivo es BLOCKED y la ejecución falla. Si un agente de IA decide con el resultado si ejecuta un SQL, pásale el SQL con --sql (o por stdin), nunca como archivo de migración; o usa el servidor MCP local, que bloquea el DDL según la severidad de la regla (ver El proxy sin cuenta).

Formatos y códigos de salida

--format acepta text (por defecto), json, sarif, gitlab-codequality y gitlab-sast. Cada resultado offline dice de dónde viene: mode: offline y la versión del motor en el resumen de texto, "mode": "offline" y "engine_version" en JSON, un bloque properties (modo, motor y versión del ruleset) en SARIF, una nota en cada hallazgo de los reportes de GitLab y Vericto (offline) como título de las anotaciones de GitHub. El ruleset es standard@engine-5.1.0.

CódigoSignificado
0Nada igual o superior a --fail-on (por defecto block)
1Un hallazgo igual o superior a --fail-on
2Error de uso: argumentos inválidos, un archivo ilegible o una opción que necesita un workspace
3Error de autenticación o configuración: online, o en CI sin credencial y sin --offline
4Error de backend o de red, solo online (nunca pasa a offline)

En offline, cada archivo da un resultado con su hallazgo más fuerte, en la línea 1. Online, cada sentencia se reporta en su propia línea.

Hook de pre-commit

Con pre-commit, el hook vericto-check ejecuta vericto check --offline sobre los *.sql que cambia cada commit, sin cuenta, API key ni red. pre-commit instala @vericto/vericto-cli una vez, y esa instalación verifica el SHA-256 del binario. Un statement BLOCKED hace fallar el commit; FLAGGED y MONITORED se muestran y el commit pasa.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/vericto/vericto-cli
    rev: v2.3.0
    hooks:
      - id: vericto-check
        # args: [--fail-on, flag]   # also fail on FLAGGED (schema changes)

Salida real

Esto imprimió la CLI publicada, npx @vericto/vericto-cli@2.3.0, en macOS el 15 de noviembre de 2026, con dos migraciones de ejemplo:

-- migrations/0001_create_users.sql
CREATE TABLE users (id bigint PRIMARY KEY, email text NOT NULL);

-- migrations/0002_cleanup.sql
-- Remove the legacy table and old sessions
DROP TABLE legacy_users;
DELETE FROM sessions;

vericto check --offline migrations/ sale con exit 1: el DELETE sin WHERE bloquea el archivo, que reporta su hallazgo más fuerte.

$ vericto check --offline migrations/
note: offline mode: 42 standard rules at default severities, engine 5.1.0. Custom rules, overrides, sensitive columns, allowlists and the audit trail apply online only.
✖ migrations/0002_cleanup.sql  BLOCKED  VERICTO-001 critical
    DeleteStmt > WhereClause = NULL
    fix: DELETE FROM sessions WHERE id = $1
1 blocked · 1 allowed · 0 flagged · 0 monitored   (ruleset standard@engine-5.1.0 · mode: offline (engine 5.1.0, 42 standard rules, no workspace policy))

✖ Vericto blocked 1 statement  (ruleset standard@engine-5.1.0 · mode: offline (engine 5.1.0, 42 standard rules, no workspace policy))
  ✖ migrations/0002_cleanup.sql  BLOCKED  VERICTO-001 critical
      DeleteStmt > WhereClause = NULL
      fix: DELETE FROM sessions WHERE id = $1

This is Vericto enforcing a rule — the exit code is intentional, not a crash.
To allow a finding on purpose, add an inline comment on the statement:
    -- vericto:ignore[VERICTO-001] <reason>   (a reason is required)
$ echo $?
1

Una migración que solo tiene DROP TABLE legacy_users; queda FLAGGED y sale con 0; con --fail-on flag, sale con 1:

$ vericto check --offline migrations/0003_drop_legacy.sql
note: offline mode: 42 standard rules at default severities, engine 5.1.0. Custom rules, overrides, sensitive columns, allowlists and the audit trail apply online only.
! migrations/0003_drop_legacy.sql  FLAGGED  VERICTO-010 critical
    DropStmt
    fix: Use a versioned migration tool (Flyway, Prisma Migrate, Alembic, Rails migrations)
0 blocked · 0 allowed · 1 flagged · 0 monitored   (ruleset standard@engine-5.1.0 · mode: offline (engine 5.1.0, 42 standard rules, no workspace policy))
$ echo $?
0

$ vericto check --offline migrations/0003_drop_legacy.sql --fail-on flag
…
✖ Vericto: 1 statement flagged; failing because --fail-on flag  (ruleset standard@engine-5.1.0 · mode: offline (engine 5.1.0, 42 standard rules, no workspace policy))
  ! migrations/0003_drop_legacy.sql  FLAGGED  VERICTO-010 critical
…
$ echo $?
1

La misma sentencia con --sql no es una migración: se bloquea, sale con 1 y la CLI explica en stderr cómo reconoce las migraciones (y que un vericto:ignore en --sql necesita --allow-inline-ignore):

$ vericto check --offline --sql "DROP TABLE legacy_users;"
note: offline mode: 42 standard rules at default severities, engine 5.1.0. Custom rules, overrides, sensitive columns, allowlists and the audit trail apply online only.
✖ <inline>  BLOCKED  VERICTO-010 critical
    DropStmt
    fix: Use a versioned migration tool (Flyway, Prisma Migrate, Alembic, Rails migrations)
1 blocked · 0 allowed · 0 flagged · 0 monitored   (ruleset standard@engine-5.1.0 · mode: offline (engine 5.1.0, 42 standard rules, no workspace policy))
…
Inline ignores are not honoured for --sql/stdin input. To allow a finding on purpose, put the SQL in a reviewed file with an inline comment on the statement:
    -- vericto:ignore[VERICTO-010] <reason>   (a reason is required)
or pass --allow-inline-ignore to honour that comment in --sql/stdin input.
note: VERICTO-010 is schema DDL. It is reported as FLAGGED only in a migration file (under a migrations/, migration/ or migrate/ directory, a Flyway V1__name.sql or a golang-migrate 1_name.up.sql file, or a path in .vericto.toml's migration_paths); --sql, stdin and other files are checked like SQL run against the database.
$ echo $?
1

El primer archivo en JSON (--format json, en stdout):

{
  "engine_version": "5.1.0",
  "exit_code": 1,
  "mode": "offline",
  "queries": [
    {
      "action": "block",
      "ast_node_path": "DeleteStmt > WhereClause = NULL",
      "file_index": null,
      "line": 1,
      "rule_code": "VERICTO-001",
      "severity": "critical",
      "sql_preview": "-- Remove the legacy table and old sessions\nDROP TABLE legacy_users;\nDELETE FROM sessions;\n",
      "status": "BLOCKED",
      "suggested_fix": "DELETE FROM sessions WHERE id = $1"
    }
  ],
  "summary": {
    "allowed": 0,
    "blocked": 1,
    "flagged": 0,
    "monitored": 0,
    "parse_errors": 0,
    "ruleset_version": "standard@engine-5.1.0",
    "total": 1
  }
}

Sin --offline, sin credencial y fuera de CI, la CLI avisa en stderr antes de evaluar:

note: no API key or login found: checking offline with the 42 standard rules (engine 5.1.0). Run `vericto login` to check against your workspace's rules and record the run.

La GitHub Action

vericto/check-sql@v1 (Apache-2.0) envuelve vericto check: descarga una release fijada de la CLI, verifica su SHA-256 antes de extraerla, revisa los *.sql que cambia el pull request y muestra los hallazgos en el log, en el resumen del job y como anotaciones. Con offline: true revisa en el runner, sin cuenta ni secreto. Funciona en runners Linux, macOS y Windows (x64 y arm64). Guarda esto como .github/workflows/vericto.yml:

on: pull_request
jobs:
  vericto:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with: { fetch-depth: 0 }
      - uses: vericto/check-sql@v1
        with: { offline: true, upload-sarif: false }

Para enviar también los hallazgos a Code Scanning, quita upload-sarif: false y da al job security-events: write (y actions: read en repositorios privados), como en la configuración completa.

  • offline: auto (por defecto): online si hay api-key, un VERICTO_API_KEY en el job u oidc; offline, con una anotación de aviso, si no hay ninguno. Un pull request desde un fork no recibe secretos, así que también revisa offline.
  • offline: false: siempre online; sin credencial, exit 3. Una credencial rechazada o una API inalcanzable nunca se reemplaza por un check offline.
  • El output mode es online u offline, y el resumen del job tiene una fila Mode.

@v1 apunta a la 1.4.0, que instala la CLI 2.0.0 por defecto, con el motor 5.0.0. Para usar otra release de la CLI, fíjala con cli-version, por ejemplo cli-version: "2.3.0" para el motor 5.1.0 y el tope de DDL solo en migraciones (latest no se acepta).

El proxy sin cuenta

El mismo binario, vericto-proxy (AGPL-3.0-only), tiene dos modos que funcionan sin workspace: usan las reglas integradas y no reportan nada, porque ningún evento, heartbeat ni sync de reglas sale de la máquina. La versión 5.0.1 usa vericto-engine 5.0.0 y trae binarios nativos para Linux, macOS y Windows (instalación).

vericto-proxy mcp en modo local

Un servidor MCP que deja a un agente de IA (Claude Code, Cursor, Codex o cualquier cliente MCP) leer una base PostgreSQL a través de Vericto: el agente recibe execute_sql, describe_schema, check_sql y whoami, y nunca la credencial de la base. Es de solo lectura: execute_sql solo ejecuta lecturas, en una transacción que siempre se revierte, con límites de filas, tamaño y tiempo. Sin VERICTO_API_KEY, VERICTO_DATABASE_ID ni VERICTO_API_URL corre en modo local, y whoami lo dice: control_plane.mode: "none" y control_plane.ruleset: "built-in".

# A read-only role's connection URL, in a file the agent does not read
mkdir -p ~/.config/vericto && chmod 700 ~/.config/vericto
printf '%s' 'postgres://vericto_agent_ro:…@db.example.com:5432/shop?sslmode=verify-full' > ~/.config/vericto/db.url
chmod 600 ~/.config/vericto/db.url

# The native binary (Linux, macOS), then register it in Claude Code
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/vericto/vericto-proxy/releases/download/v5.0.1/vericto-proxy-installer.sh | sh
claude mcp add vericto-db -- ~/.cargo/bin/vericto-proxy \
  mcp --database-url-file ~/.config/vericto/db.url

check_sql evalúa con las mismas reglas y, a diferencia de la CLI, bloquea el DDL según la severidad de la regla. En modo local no hay máscaras, allowlists de agentes, políticas de negocio ni kill switch: para frenar al agente, quita el servidor del cliente o detén el proceso. Por HTTP (--transport http) no arranca sin al menos un token en VERICTO_MCP_AUTH_TOKENS_FILE: nunca se sirve sin autenticación. Cursor, Codex, Windows y Docker: ver Servidor local.

El proxy TCP sin workspace

Sin las tres variables del control plane (VERICTO_API_URL, VERICTO_API_KEY y VERICTO_DATABASE_ID), el proxy TCP protege PostgreSQL o MySQL con las reglas integradas y no reporta nada. Solo necesita UPSTREAM_HOST:

# PostgreSQL on localhost:5432; the proxy listens on 5433
UPSTREAM_HOST=localhost vericto-proxy

# MySQL on localhost:3306; the proxy listens on 3307
VERICTO_WIRE_PROTOCOL=mysql UPSTREAM_HOST=localhost vericto-proxy

Tu aplicación se conecta al proxy con las mismas credenciales. Un DELETE sin WHERE no llega a la base: el cliente recibe un error SQL normal (SQLSTATE 42501 en PostgreSQL). Docker, Kubernetes, ECS y la configuración completa: Proxy TCP.

Qué agrega un workspace

Offline te da las reglas estándar sin nada que configurar. Conectar un workspace gratis agrega lo que depende de una cuenta:

OfflineCon un workspace
Reglaslas 42 reglas estándar, con sus severidades por defectolas reglas de tu workspace: las estándar con tus ajustes, más tus reglas personalizadas
Políticas de negocio, columnas sensibles y máscaras, allowlists de agentesnosí
Historialno queda registro en ningún ladocada check de la CLI queda registrado, con el commit, la ejecución y quién la lanzó; el proxy y el MCP registran cada consulta
Dashboardnoreglas, historial y auditoría; para el proxy y el MCP, también el kill switch
Resultado de la CLIuno por archivo, con su hallazgo más fuerteuno por sentencia, en su línea
Recibos firmados (--receipt)no (exit 2)sí
Redninguna: el SQL no sale de la máquinael SQL va a tu workspace, sanitizado si el workspace lo pide

Los checks online cuentan contra la cuota mensual de checks de la CLI; los offline no cuentan. Empieza gratis y luego ejecuta vericto login: abre el navegador y emite una key con alcance limitado para el workspace que elijas.

El aviso de una sola vez (CLI 2.2.0)

Desde la 2.2.0, después de un vericto check interactivo que corrió offline sin credencial y dio un resultado, la CLI imprime una línea en stderr, una sola vez por usuario en la máquina. Esta es la línea real (en inglés, como toda la salida de la CLI):

Tip: connect a free Vericto workspace to keep a history of checks and share rules with your team: https://app.vericto.com/register?utm_source=cli&utm_medium=nudge&utm_campaign=first-check&v=2.2.0

No es telemetría: la CLI no hace ninguna solicitud para mostrarlo y no envía nada. El enlace solo lleva la versión de la CLI y parámetros de campaña, que el sitio ve si lo abres. Para recordar que ya lo mostró, la CLI deja un pequeño archivo marcador junto a su configuración, ~/.config/vericto/connect-nudge-shown ($XDG_CONFIG_HOME/vericto/ si está definida; en Windows, %APPDATA%\vericto\). Si lo borras, el aviso puede salir una vez más. stdout y el código de salida son los mismos con o sin el aviso.

Nunca aparece:

  • con VERICTO_NO_NUDGE=1 o DO_NOT_TRACK=1 en el entorno;
  • en CI (cualquiera de las variables de CI que la CLI reconoce), así que nunca hace falta apagarlo en un pipeline;
  • si stderr no es una terminal, con un --format distinto de text o con --quiet;
  • si hay una credencial: una API key, vericto login, OIDC o un workspace id;
  • en otros comandos, incluido vericto serve --stdio (el modo offline de los SDK).

Para apagarlo en tu máquina:

# bash / zsh (in your shell profile)
export VERICTO_NO_NUDGE=1      # or DO_NOT_TRACK=1

# PowerShell
$env:VERICTO_NO_NUDGE = "1"