From 13d8504881b566bd6ccdbf5dd09a235863cfad68 Mon Sep 17 00:00:00 2001 From: bowenyin Date: Mon, 9 Nov 2026 19:50:16 +0800 Subject: [PATCH] Reject out-of-range inspect limits and scans --- CHANGELOG.md | 1 + README.md | 2 +- src/gulliver/cli.py | 4 +-- src/gulliver/core.py | 4 ++- src/gulliver/guard.py | 11 +++++-- tests/test_inspect_bounds.py | 64 ++++++++++++++++++++++++++++++++++++ 6 files changed, 79 insertions(+), 7 deletions(-) create mode 100644 tests/test_inspect_bounds.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 48c58ce..bb5d756 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ ## Unreleased ### Added +- Refuse inspect limits outside 1-200 and sensitive value scans outside 0-1000 instead of silently clamping them (#97). A named table still ignores the listing limit. - `gulliver rules --format markdown|json` prints a generated rule table (markdown) or the same JSON as `--json`; the README Scale lint rules table is generated from it (#18). - `gulliver spend -o/--output PATH` and `gulliver top -o/--output PATH` write the report as UTF-8 and print a one-line confirmation (#19). - Opt-in `check --samples N` / MCP `samples` (0-20) reports guarded offending values and row counts for failed unique, accepted-values and range checks. Each extra query is budget-gated and logged; blocked or failed samples leave the check result intact (#48, #49). diff --git a/README.md b/README.md index c8304db..fe84b7c 100644 --- a/README.md +++ b/README.md @@ -767,7 +767,7 @@ The read-only gate uses its own codes. A `GS` finding is always a `block` with t ``` gulliver status connections, budget, spend today (and your own, under caller) -gulliver inspect [TABLE] [--sensitive] [--scan N] biggest tables, one table's columns, or sensitive columns +gulliver inspect [TABLE] [--limit 25] [--sensitive] [--scan N] limit: 1-200 (ignored with TABLE); scan: 0-1000, 0 disables scanning gulliver lint SQL [--dialect D] scale lint of one query gulliver lint PATH... [--format text|json|sarif|github|gitlab|junit] [--fail-on error|warn|info|never] [--exclude GLOB] [--warn-unused-ignores] [--metadata] [-o PATH] files and folders (CI) diff --git a/src/gulliver/cli.py b/src/gulliver/cli.py index 11ab5ce..35bfbf5 100644 --- a/src/gulliver/cli.py +++ b/src/gulliver/cli.py @@ -194,11 +194,11 @@ def add_parser(name: str, **kwargs: Any) -> argparse.ArgumentParser: p = sub.add_parser("inspect", help="Biggest tables, or one table's columns") p.add_argument("table", nargs="?") - p.add_argument("--limit", type=int, default=25) + p.add_argument("--limit", type=int, default=25, help="Tables to list (1-200); ignored with a table name") p.add_argument("--sensitive", action="store_true", help="List columns that look like personal data or secrets (by name and earlier values)") p.add_argument("--scan", type=int, default=0, metavar="ROWS", - help="With --sensitive: also check this many rows of text values (one budget-gated query)") + help="With --sensitive: check 0-1000 rows of text values (0 disables the budget-gated scan)") p = sub.add_parser("lint", help="Scale lint only (no database needed): one SQL string, or files and folders") p.add_argument("sql", nargs="*", help="SQL text, '-' to read stdin, or .sql files and folders (CI mode)") diff --git a/src/gulliver/core.py b/src/gulliver/core.py index 116fb92..caed2cf 100644 --- a/src/gulliver/core.py +++ b/src/gulliver/core.py @@ -114,6 +114,8 @@ def status(settings: Settings) -> dict[str, Any]: # -- inspect --------------------------------------------------------------------------- def inspect(settings: Settings, connection: str | None = None, table: str | None = None, limit: int = 25) -> dict[str, Any]: + if not table and not 1 <= limit <= 200: + return _error("--limit must be between 1 and 200.", "Use a limit from 1 to 200, for example --limit 25.") try: with _engine(settings, connection) as (conn, engine): if table: @@ -127,7 +129,7 @@ def inspect(settings: Settings, connection: str | None = None, table: str | None return {"status": "ok", "connection": conn.name, "engine": conn.engine, "table": table_dict, "next_step": "Write your SQL using only the columns you need, then call gulliver_preflight."} - tables = engine.list_tables(limit=max(1, min(int(limit), 200))) + tables = engine.list_tables(limit=limit) return {"status": "ok", "connection": conn.name, "engine": conn.engine, "tables": [t.as_dict() for t in tables], "next_step": "Inspect one table for its columns, or call gulliver_preflight with your SQL."} diff --git a/src/gulliver/guard.py b/src/gulliver/guard.py index 40fd334..bf52fa6 100644 --- a/src/gulliver/guard.py +++ b/src/gulliver/guard.py @@ -1174,6 +1174,11 @@ def inspect_sensitive(settings: Settings, connection: str | None = None, table: from .engines import EngineError, dialect_for from .features import Blocked, _gated_run + if not table and not 1 <= limit <= 200: + return _error("--limit must be between 1 and 200.", "Use a limit from 1 to 200, for example --limit 25.") + if not 0 <= scan_rows <= 1000: + return _error("--scan must be between 0 and 1000.", "Use --scan 0 for no value scan, or up to --scan 1000.") + try: with _engine(settings, connection) as (conn, engine): if table: @@ -1184,7 +1189,7 @@ def inspect_sensitive(settings: Settings, connection: str | None = None, table: infos = [info] else: infos = [] - for t in engine.list_tables(limit=max(1, min(int(limit), 200))): + for t in engine.list_tables(limit=limit): infos.append(t if t.columns else (engine.table_info(t.name) or t)) dialect = dialect_for(conn.engine) tables_out: list[dict[str, Any]] = [] @@ -1197,10 +1202,10 @@ def inspect_sensitive(settings: Settings, connection: str | None = None, table: if text_cols: sql = (exp.select(*[exp.column(c, quoted=True) for c in text_cols]) .from_(exp.to_table(info.name, dialect=dialect)) - .limit(max(1, min(int(scan_rows), 1000))).sql(dialect=dialect)) + .limit(scan_rows).sql(dialect=dialect)) try: res = _gated_run(settings, conn.name, engine, sql, "sensitive-scan", - preview_rows=max(1, min(int(scan_rows), 1000))) + preview_rows=scan_rows) except Blocked as blocked: notes.append(f"{info.name}: value scan not run: {blocked.result.get('next_step')}") res = None diff --git a/tests/test_inspect_bounds.py b/tests/test_inspect_bounds.py new file mode 100644 index 0000000..0a75777 --- /dev/null +++ b/tests/test_inspect_bounds.py @@ -0,0 +1,64 @@ +import json + +import pytest + +from gulliver import core, guard +from gulliver.cli import main + + +@pytest.mark.parametrize("limit", [-1, 0, 201, 500]) +@pytest.mark.parametrize("sensitive", [False, True]) +def test_invalid_inspect_limit_is_refused(settings, monkeypatch, capsys, limit, sensitive): + def unexpected_engine(*args, **kwargs): + pytest.fail("invalid bounds must be refused before opening an engine") + + monkeypatch.setattr(core, "_engine", unexpected_engine) + inspect = guard.inspect_sensitive if sensitive else core.inspect + result = inspect(settings, limit=limit) + assert result["status"] == "error" + assert "--limit" in result["error"] + assert result["next_step"] + + args = ["inspect", "--limit", str(limit), "--json"] + if sensitive: + args.append("--sensitive") + assert main(args) == 1 + assert json.loads(capsys.readouterr().out)["status"] == "error" + + +@pytest.mark.parametrize("scan", [-5, -1, 1001, 5000]) +def test_invalid_inspect_scan_is_refused(settings, monkeypatch, capsys, scan): + def unexpected_engine(*args, **kwargs): + pytest.fail("invalid scan must be refused before opening an engine") + + monkeypatch.setattr(core, "_engine", unexpected_engine) + result = guard.inspect_sensitive(settings, scan_rows=scan) + assert result["status"] == "error" + assert "--scan" in result["error"] + assert result["next_step"] + assert main(["inspect", "--sensitive", "--scan", str(scan), "--json"]) == 1 + assert json.loads(capsys.readouterr().out)["status"] == "error" + + +@pytest.mark.parametrize("limit", [1, 200]) +def test_inspect_accepts_limit_boundaries(settings, limit): + assert core.inspect(settings, limit=limit)["status"] == "ok" + assert guard.inspect_sensitive(settings, limit=limit)["status"] == "ok" + + +@pytest.mark.parametrize("scan", [0, 1000]) +def test_inspect_accepts_scan_boundaries(settings, scan): + result = guard.inspect_sensitive(settings, table="users", scan_rows=scan) + assert result["status"] == "ok" + assert result["scanned_rows"] == scan + + +@pytest.mark.parametrize("sensitive", [False, True]) +def test_inspect_ignores_limit_for_named_table(settings, demo_db, capsys, sensitive): + inspect = guard.inspect_sensitive if sensitive else core.inspect + assert inspect(settings, table="users", limit=-1)["status"] == "ok" + args = ["--dsn", demo_db, "inspect", "users", "--limit", "-1", "--json"] + if sensitive: + args.append("--sensitive") + assert main(args) == 0 + assert json.loads(capsys.readouterr().out)["status"] == "ok"