Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -166,9 +166,9 @@ jobs:
runs-on: ${{ github.event.repository.private && fromJSON(vars.CI_RUNS_ON || '["self-hosted","linux","x64","vericto-spot"]') || fromJSON(vars.CI_RUNS_ON_PUBLIC || '"ubuntu-latest"') }}
timeout-minutes: 10
env:
VERICTO_CLI_VERSION: "2.1.0"
# sha256 of vericto-cli-x86_64-unknown-linux-musl.tar.xz in the v2.1.0 release.
VERICTO_CLI_SHA256: "8c041e05bc0f2260300f3e987d366f18e0b9fbefaacc089959d53c60f3f37f32"
VERICTO_CLI_VERSION: "2.3.0"
# sha256 of vericto-cli-x86_64-unknown-linux-musl.tar.xz in the v2.3.0 release.
VERICTO_CLI_SHA256: "edc257e9bbbf83cda194c324b3df112f54576bde54a3c8bbace405a19ff613fa"
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
Expand Down
46 changes: 46 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,52 @@ All notable changes to this package are documented here. The format follows

## [Unreleased]

Offline `ci` checks follow Vericto CLI 2.3.0 and engine 5.1.0: schema DDL blocks
unless the SQL is marked as a migration.

### Added

- **`offline_migration=True`** (`Vericto(...)`, `OfflineEvaluator(migration=...)`,
`OfflineEngine.check(..., migration=...)`): marks the checked SQL as a versioned
migration. The SDK sends `"migration": true` in the `vericto serve` request, so
the schema DDL rules (DROP TABLE, ALTER TABLE, DROP INDEX / TRIGGER, the
Snowflake and SQLite schema rules) are capped at `FLAGGED`, as for a file under
`migrations/` in `vericto check --offline`. It needs `offline_profile="ci"`
(with `"runtime"`, or a value that is not a bool, `VerictoConfigError`) and
offline mode. The field is sent only when set, so requests without it are
unchanged. `verdict.raw["migration"]` says what was sent.

### Changed

- **Behaviour change with Vericto CLI 2.3.0+: offline `ci` checks block schema
DDL unless the request is a migration.** CLI 2.3.0 caps schema DDL only for
migration inputs: `vericto check --offline --sql "DROP TABLE users"` and a
`vericto serve` `ci` request without `"migration": true` are now `BLOCKED`
(were `FLAGGED`). `Vericto(offline=True, offline_profile="ci")` therefore
blocks `DROP TABLE` with CLI 2.3.0+; pass `offline_migration=True` for SQL that
is a migration. CLI 2.1.0 and 2.2.0 ignore the marker and cap every `ci` check.
TRUNCATE (VERICTO-011) and DROP SCHEMA / DATABASE (VERICTO-012) are never
capped with engine 5.1.0 (CLI 2.3.0): they block even in a migration.
- **`vericto-dbt check --offline`**: dbt models and hooks are not migrations, so
with CLI 2.3.0+ schema DDL in them (a `DROP TABLE` / `ALTER TABLE … DROP
COLUMN` post-hook) is `BLOCKED` and exits `1`, and TRUNCATE / DROP SCHEMA
hooks block. vericto-dbt does not mark its SQL as a migration. Remedies:
`--no-hooks`, `--select`, or `--fail-on`. The offline note in the report says
so. Online, the CI-check API decides.
- README: the profile table, the offline example (now `offline_migration=True`),
the dbt section and the Spanish summary describe the migration scope.

### Tests

- The fake `vericto serve` follows CLI 2.3.0 (`DROP` flagged only for a `ci`
migration, `TRUNCATE` always blocks, a non-bool `migration` is
`INVALID_REQUEST`; `FAKE_SERVE_MODE=cap_all` is CLI 2.2.0). New tests: the
`ci` profile with and without the marker, the marker sent only when set, the
configuration errors, CLI 2.2.0 behaviour, and a dbt `DROP TABLE` post-hook
that blocks offline. `tests/test_offline_cli.py` adds a parity case per input:
`offline_migration=True` equals `vericto check --offline` of the same SQL as
`migrations/0001_case.sql` (passes with CLI 2.1.0, 2.2.0 and 2.3.0).

## [0.8.0] - 2026-11-15

Offline mode: check SQL with no account and no network, through the engine built
Expand Down
49 changes: 41 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,15 +197,31 @@ with vericto.Vericto(offline=True) as guard: # or VERICTO_OFFLINE=1
print(exc.verdict.rule_code, exc.suggested_fix) # VERICTO-001 and a safer statement
conn.close()

# Exactly what `vericto check --offline` answers (schema DDL is flagged, not blocked):
with vericto.Vericto(offline=True, offline_profile="ci") as guard:
# Exactly what `vericto check --offline` answers for a file under migrations/
# (schema DDL is flagged, not blocked):
with vericto.Vericto(offline=True, offline_profile="ci", offline_migration=True) as guard:
assert guard.check("DROP TABLE users", "postgres").decision is vericto.Decision.FLAGGED
```

| `offline_profile` | Matches | `DROP TABLE users` |
|---|---|---|
| `"runtime"` (default) | the Runtime API, MCP `check_sql` and the proxy's local mode, for a workspace with no overrides | `BLOCKED` (VERICTO-010) |
| `"ci"` | `vericto check --offline` and the CI-check API: the DDL rules VERICTO-010 to 019 are capped at `FLAGGED` | `FLAGGED` |
| `"ci"` | `vericto check --offline --sql` (CLI 2.3.0+): schema DDL blocks, as under `"runtime"` | `BLOCKED` (VERICTO-010) |
| `"ci"` + `offline_migration=True` | `vericto check --offline` of a migration file: the schema DDL rules (DROP TABLE, ALTER TABLE, DROP INDEX / TRIGGER: VERICTO-010, 013, 015 to 019, and the Snowflake / SQLite ones) are capped at `FLAGGED` | `FLAGGED` |

**Schema DDL in `ci` checks blocks unless the SQL is a migration** (Vericto CLI
2.3.0, engine 5.1.0). `vericto check --offline` caps schema DDL only for
migration files (a `migrations/`, `migration/` or `migrate/` directory, a Flyway
`V1__name.sql` or golang-migrate `1_name.up.sql` file, or a path in
`.vericto.toml`'s `migration_paths`), and `vericto serve` caps it only for a `ci`
request marked `"migration": true`. The SDK sends that marker when you pass
`offline_migration=True` (it needs `offline_profile="ci"`); pass it when the SQL
you check is a versioned migration, for example in a migration runner. Without it
a `DROP TABLE` is `BLOCKED` under both profiles. TRUNCATE (VERICTO-011) and DROP
SCHEMA / DATABASE (VERICTO-012) are never capped: they block even in a migration.
CLI 2.1.0 and 2.2.0 ignore the marker and cap every `ci` check, so with them
`DROP TABLE` is `FLAGGED` under `"ci"` either way; `verdict.raw["migration"]`
says what the SDK sent.

How it behaves:

Expand All @@ -232,6 +248,8 @@ How it behaves:
logged.
- `vericto-dbt check --offline` (or `VERICTO_OFFLINE=1`) checks a dbt project with
the `ci` profile, with no key; Airflow workers use it with `VERICTO_OFFLINE=1`.
dbt models and hooks are not migrations, so with CLI 2.3.0+ schema DDL in them
blocks (see [dbt](#dbt)).

Offline checks use the 42 standard rules at their default severities. A
workspace adds custom rules, severity overrides, sensitive-column masking, agent
Expand Down Expand Up @@ -513,7 +531,7 @@ All inherit from `VerictoError`.
and `supported_dialects()`. When the caller gives `context` or `end_user`, the
guard passes them as keyword arguments of the same names (an evaluator without
them raises `TypeError` then, rather than dropping them). This release ships
`RuntimeApiEvaluator` and `OfflineEvaluator(profile=..., cli_path=..., timeout=...)`,
`RuntimeApiEvaluator` and `OfflineEvaluator(profile=..., migration=..., cli_path=..., timeout=...)`,
what `Vericto(offline=True)` builds (see
[Offline mode](#offline-mode-no-account)). An evaluator with a `close()` method
is closed by `Vericto.close()`.
Expand Down Expand Up @@ -723,9 +741,16 @@ imported: only its artifacts are read.
tags. Runs carry GitHub/GitLab provenance and appear in the dashboard's CI reports.
- **Offline** (`--offline` or `VERICTO_OFFLINE=1`): each statement is checked by
the local `vericto` CLI (2.1.0+, see [Offline mode](#offline-mode-no-account))
with the `ci` profile, so the verdicts equal `vericto check --offline`. No key,
with the `ci` profile, so the verdicts equal `vericto check --offline` of the
same SQL outside a migration directory. No key,
no network, no allowance spent; workspace rules and sensitive-column tags do not
apply. Combined with `VERICTO_API_KEY`, `--api-url` or `--database-id` it exits
apply. **With CLI 2.3.0+ (engine 5.1.0), schema DDL in a model or hook is
`BLOCKED`, not `FLAGGED`:** dbt SQL is not a versioned migration, it runs on
every `dbt run`. A `post-hook` with `DROP TABLE` / `ALTER TABLE … DROP COLUMN`
now exits `1`, and `TRUNCATE` / `DROP SCHEMA` hooks block with any CLI on
engine 5.1.0. Remedies: `--no-hooks`, `--select` to leave the node out, or
`--fail-on` (exit code only). Online, the CI-check API decides; it applies the
same rules once the hosted evaluator runs engine 5.1.0. Combined with `VERICTO_API_KEY`, `--api-url` or `--database-id` it exits
`3` ("choose one"); a local engine failure exits `4`.
- SARIF points at the model file (line 1: compiled lines do not map to the Jinja
source; the message gives the compiled line). GitHub Actions example:
Expand Down Expand Up @@ -1016,10 +1041,18 @@ nada. Los wrappers e integraciones funcionan igual y el resultado es el mismo
`Verdict`, con `mode="offline"`, `engine_version` y `ruleset_version`
(`standard@engine-<versión>`). Perfiles: `offline_profile="runtime"` (por defecto,
como la Runtime API: `DROP TABLE` queda `BLOCKED`) o `"ci"` (igual que
`vericto check --offline`: el DDL de esquema queda `FLAGGED`). Combinarlo con una
`vericto check --offline`). Desde la CLI 2.3.0 (motor 5.1.0), el perfil `"ci"`
limita el DDL de esquema a `FLAGGED` solo en migraciones: sin marcar, `DROP TABLE`
queda `BLOCKED`, como con `--sql`; con `offline_migration=True` (requiere
`offline_profile="ci"`) el SDK envía `"migration": true` y el DDL de esquema queda
`FLAGGED`, como en un archivo de `migrations/`. TRUNCATE y DROP SCHEMA / DATABASE se
bloquean siempre. Las CLI 2.1.0 y 2.2.0 ignoran la marca y limitan todo chequeo
`ci`. Combinarlo con una
clave de API o con otro evaluador lanza `VerictoConfigError` ("choose one"). Si el
proceso muere, se reinicia una vez; si vuelve a fallar, se aplica `fail_mode` como
con la API. `vericto-dbt check --offline` usa el perfil `ci`. Sin conexión se usan
con la API. `vericto-dbt check --offline` usa el perfil `ci` sin marca de
migración: con la CLI 2.3.0+, el DDL de esquema en un modelo o hook de dbt queda
`BLOCKED`. Sin conexión se usan
las 42 reglas estándar: las reglas propias, el enmascarado de columnas sensibles,
las allowlists, las políticas de negocio y la auditoría requieren un workspace. El
motor corre en el proceso aparte de la CLI, con licencia AGPL-3.0-only; este
Expand Down
10 changes: 7 additions & 3 deletions src/vericto/dbt.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,11 @@
``--offline`` (or ``VERICTO_OFFLINE=1``) evaluates with the local engine of the
``vericto`` CLI instead (2.1.0+, ``vericto serve --stdio``): no key, no network, the
standard rules under the ``ci`` profile, so the verdicts equal ``vericto check
--offline``. Workspace rules, sensitive-column tags and the CI-check allowance do
not apply.
--offline`` of the same SQL outside a migration directory. Workspace rules,
sensitive-column tags and the CI-check allowance do not apply. dbt SQL is not a
versioned migration, so with CLI 2.3.0+ schema DDL in a model or hook (a
``DROP TABLE`` post-hook) is BLOCKED, not FLAGGED, and TRUNCATE / DROP SCHEMA /
DATABASE block with engine 5.1.0+.

Exit codes (as vericto-cli): 0 nothing at or above ``--fail-on``; 1 a finding at
or above it; 2 usage error (no manifest, unsupported adapter, nothing compiled);
Expand Down Expand Up @@ -722,7 +725,8 @@ def run_check(args: argparse.Namespace, out: IO[str], err: IO[str], client: Opti
if report.mode == "offline":
report.notes.append(
f"Offline: the standard rules of the local engine ({report.ruleset_version or 'vericto serve'}), "
"ci profile. Workspace rules and sensitive-column tags do not apply."
"ci profile, not a migration (schema DDL blocks with vericto CLI 2.3.0+). "
"Workspace rules and sensitive-column tags do not apply."
)

if args.format == "json":
Expand Down
17 changes: 14 additions & 3 deletions src/vericto/guard.py
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,12 @@ class Vericto:
an ``evaluator``, it raises :class:`~vericto.VerictoConfigError`.
offline_profile: ``"runtime"`` (default: ``DROP TABLE`` is ``BLOCKED``, as on
the Runtime API) or ``"ci"`` (exactly ``vericto check --offline``).
offline_migration: with ``offline_profile="ci"``, ``True`` checks the SQL as a
versioned migration: schema DDL (DROP TABLE, ALTER TABLE, ...) is capped
at ``FLAGGED``, as for a file under ``migrations/``. Default ``False``:
checked like ``vericto check --offline --sql``, so ``DROP TABLE`` is
``BLOCKED`` (Vericto CLI 2.3.0+; 2.1.0 and 2.2.0 cap every ``ci`` check).
TRUNCATE and DROP SCHEMA / DATABASE block either way.
offline_cli_path: the ``vericto`` binary (default ``VERICTO_CLI``, then PATH).

The guard owns its evaluator: :meth:`close` (or ``with Vericto(...) as guard:``)
Expand All @@ -96,6 +102,7 @@ def __init__(
offline: Optional[bool] = None,
offline_profile: Optional[str] = None,
offline_cli_path: Optional[str] = None,
offline_migration: Optional[bool] = None,
) -> None:
if offline_requested(offline):
online = [
Expand All @@ -118,11 +125,15 @@ def __init__(
"its own rules."
)
evaluator = OfflineEvaluator(
profile=offline_profile or DEFAULT_PROFILE, cli_path=offline_cli_path, timeout=timeout
profile=offline_profile or DEFAULT_PROFILE,
migration=False if offline_migration is None else offline_migration,
cli_path=offline_cli_path,
timeout=timeout,
)
elif offline_profile is not None or offline_cli_path is not None:
elif offline_profile is not None or offline_cli_path is not None or offline_migration is not None:
raise VerictoConfigError(
"offline_profile and offline_cli_path apply to offline mode only: pass offline=True too."
"offline_profile, offline_cli_path and offline_migration apply to offline mode only: "
"pass offline=True too."
)
if evaluator is None:
evaluator = RuntimeApiEvaluator(
Expand Down
Loading
Loading