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@v1conoffline: true. - El proxy:
vericto-proxy mcpen 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
--offlineoVERICTO_OFFLINE=1: offline siempre, también en CI y aunque haya una key.- Fuera de CI, sin API key, sin
vericto loginy sin token OIDC: offline por sí sola, y lo dice en stderr. - En CI (
CI,GITHUB_ACTIONS,GITLAB_CI,BUILDKITE,JENKINS_URLy otras variables de CI), una credencial que falta sigue siendo exit3: un pipeline cuyo secreto desapareció no pasa en silencio a menos reglas. Pasa--offlinepara elegirlo. - Una key presente pero inválida es exit
3y un backend inalcanzable es exit4: ninguno de los dos pasa a offline..vericto.tomlno puede elegir el modo: una claveofflinecommiteada se rechaza (exit2).
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ódigo | Significado |
|---|---|
0 | Nada igual o superior a --fail-on (por defecto block) |
1 | Un hallazgo igual o superior a --fail-on |
2 | Error de uso: argumentos inválidos, un archivo ilegible o una opción que necesita un workspace |
3 | Error de autenticación o configuración: online, o en CI sin credencial y sin --offline |
4 | Error 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 hayapi-key, unVERICTO_API_KEYen el job uoidc; 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, exit3. Una credencial rechazada o una API inalcanzable nunca se reemplaza por un check offline.- El output
modeesonlineuoffline, y el resumen del job tiene una filaMode.
@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:
| Offline | Con un workspace | |
|---|---|---|
| Reglas | las 42 reglas estándar, con sus severidades por defecto | las 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 agentes | no | sí |
| Historial | no queda registro en ningún lado | cada 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 |
| Dashboard | no | reglas, historial y auditoría; para el proxy y el MCP, también el kill switch |
| Resultado de la CLI | uno por archivo, con su hallazgo más fuerte | uno por sentencia, en su línea |
Recibos firmados (--receipt) | no (exit 2) | sí |
| Red | ninguna: el SQL no sale de la máquina | el 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=1oDO_NOT_TRACK=1en 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
--formatdistinto detexto 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"