sqlguard-ninja 0.2.0__tar.gz → 0.3.0__tar.gz

{sqlguard_ninja-0.2.0 → sqlguard_ninja-0.3.0}/CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes are documented here. The project follows
 [Semantic Versioning](https://semver.org/); before 1.0, minor versions may change the API.
 
+## [0.3.0] — 2026-10-24
+
+### Added
+* **Role inheritance** (`extends`): grants merge, explicit denies are sticky, and conflicts,
+  unknown parents and cycles are load errors.
+* **Policy metadata and identity:** `metadata.revision/owner/change_ticket`, a policy
+  fingerprint, and a per-decision `decision_id`. Audit events add `policy_revision`,
+  `policy_fingerprint`, `decision_id`, `correlation_id`, a literal-insensitive
+  `query_fingerprint`, and `tenant_filter_rewrite`.
+* **Policy CLI:** `policy template`, `policy diff` (effect classification,
+  `--fail-on-relaxation`), `policy simulate` (`--against`, `--fail-on-change`),
+  `policy explain` (decision or column access, with inheritance source).
+* **Templates:** `minimal`, `multi_tenant_saas`, `analytics_readonly`.
+* **Opt-in AST tenant-filter rewrite** (`sqlguard_ninja.tenancy`,
+  `SQLCheckpoint(rewrite_tenant_filters=True)`) with re-validation and refusal rules (ADR-011).
+* Docs: `docs/guides/POLICY_AS_CODE.md`; ADR-011, ADR-012; threat model T6a/T6b.
+
+### Compatibility
+* Policy files without the new fields behave exactly as before. `ValidationResult` gains
+  fields with defaults.
+
 ## [0.2.0] — 2026-10-24
 
 ### Added

{sqlguard_ninja-0.2.0 → sqlguard_ninja-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlguard-ninja
-Version: 0.2.0
+Version: 0.3.0
 Summary: Security testing, policy enforcement, agent integration, privacy analysis and CI benchmarking for LLM-generated SQL.
 Project-URL: Homepage, https://github.com/Pratik653/SQLGuard_Ninjapy
 Project-URL: Documentation, https://github.com/Pratik653/SQLGuard_Ninjapy/tree/main/docs
@@ -246,6 +246,23 @@ Labels also apply to paths inside JSON columns (`profile->'health'->>'allergies'
 suggestions are never enforced. This is a technical control, not a certification of GDPR
 compliance. Full semantics: [POLICY_REFERENCE.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_REFERENCE.md).
 
+## Policy as code
+
+Roles can inherit (`extends`), and explicit denies cannot be relaxed by a child. Every decision
+carries the policy revision, the policy fingerprint and a decision id. Review changes before
+activating them:
+
+```bash
+sqlninja policy template multi_tenant_saas --output policy.yaml
+sqlninja policy diff old.yaml policy.yaml --fail-on-relaxation
+sqlninja policy simulate --policy old.yaml --against policy.yaml --cases cases.yaml
+sqlninja policy explain --policy policy.yaml --role support --column customers.email
+```
+
+Optional: `SQLCheckpoint(..., rewrite_tenant_filters=True)` adds missing tenant filters
+through the AST and executes only the re-validated rewrite. See
+[POLICY_AS_CODE.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_AS_CODE.md).
+
 ## Query cost analysis
 
 Every validation includes an explainable static score that uses the catalog's
@@ -340,6 +357,7 @@ writes, more tested dialects, and SARIF output. Details in [ROADMAP.md](https://
 ## Documentation
 
 * [Policy reference](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_REFERENCE.md)
+* [Policy as code](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_AS_CODE.md)
 * [Agent integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/AGENT_INTEGRATION.md)
 * [Query cost](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/QUERY_COST.md)
 * [CI integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/CI_INTEGRATION.md)

{sqlguard_ninja-0.2.0 → sqlguard_ninja-0.3.0}/README.md

@@ -190,6 +190,23 @@ Labels also apply to paths inside JSON columns (`profile->'health'->>'allergies'
 suggestions are never enforced. This is a technical control, not a certification of GDPR
 compliance. Full semantics: [POLICY_REFERENCE.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_REFERENCE.md).
 
+## Policy as code
+
+Roles can inherit (`extends`), and explicit denies cannot be relaxed by a child. Every decision
+carries the policy revision, the policy fingerprint and a decision id. Review changes before
+activating them:
+
+```bash
+sqlninja policy template multi_tenant_saas --output policy.yaml
+sqlninja policy diff old.yaml policy.yaml --fail-on-relaxation
+sqlninja policy simulate --policy old.yaml --against policy.yaml --cases cases.yaml
+sqlninja policy explain --policy policy.yaml --role support --column customers.email
+```
+
+Optional: `SQLCheckpoint(..., rewrite_tenant_filters=True)` adds missing tenant filters
+through the AST and executes only the re-validated rewrite. See
+[POLICY_AS_CODE.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_AS_CODE.md).
+
 ## Query cost analysis
 
 Every validation includes an explainable static score that uses the catalog's
@@ -284,6 +301,7 @@ writes, more tested dialects, and SARIF output. Details in [ROADMAP.md](https://
 ## Documentation
 
 * [Policy reference](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_REFERENCE.md)
+* [Policy as code](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_AS_CODE.md)
 * [Agent integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/AGENT_INTEGRATION.md)
 * [Query cost](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/QUERY_COST.md)
 * [CI integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/CI_INTEGRATION.md)

{sqlguard_ninja-0.2.0 → sqlguard_ninja-0.3.0}/docs/architecture/ARCHITECTURE_DECISIONS.md

@@ -122,6 +122,25 @@ Extras: `langchain`, `langgraph`, `fastapi`, `postgres` (`psycopg`), `dev`.
 Apache-2.0 provides an explicit patent grant, which matters to enterprise adopters. It is
 compatible with all dependencies we use (MIT, BSD, Apache-2.0). No third-party code is vendored.
 
+## ADR-011 — Opt-in tenant-filter rewrite (refines ADR-005)
+
+**Context.** Enterprise users want missing tenant filters added rather than rejected.
+
+**Decision.** `sqlguard_ninja.tenancy.apply_tenant_filters` may add tenant predicates through
+the AST. It is opt-in (`rewrite_tenant_filters=True`), uses bind parameters only, refuses on any
+non-tenant problem or ambiguous ownership, and **re-validates** the rewritten SQL, which is the
+exact string executed. ADR-005's invariant still holds: the validated string and the executed
+string are identical.
+
+**Consequences.** The rewritten SQL is the qualified form produced by sqlglot. It is equivalent
+but may look different from the input. Database RLS remains the authoritative control.
+
+## ADR-012 — Role inheritance with sticky explicit denies
+
+**Decision.** `extends` merges grants. A child cannot relax an inherited explicit deny, and an
+attempt is a load error. `policy diff` works on the effective (inherited) policy and classifies
+relaxations so reviewers and CI can gate them.
+
 ## ADR-010 — Read-only scope for v0.1
 
 **Decision.** v0.1 validates read-only workloads only. All writes are denied. Supporting governed

sqlguard_ninja-0.3.0/docs/development/IMPLEMENTATION_PROGRESS.md

@@ -0,0 +1,11 @@
+# Implementation progress
+
+| Phase | Status | Commit | Tests | Notes |
+|---|---|---|---|---|
+| 0 Audit and checkpoint files | IMPLEMENTED | 375c52f^ | — | baseline v0.1.1 verified: clean tree, main@5206e96, PyPI 0.1.1 |
+| 1a Benchmark tiers, basis, F1, Wilson CIs, throughput, CSV, hashes | RELEASED v0.2.0 | 375c52f | focused + full gate | |
+| 1b Lineage: aggregate-only through CTEs, tenant push-down, small-cohort through derived scopes | RELEASED v0.2.0 | 8b59a38 | corpus 1.1.0 (21 boundary cases), 11 unit tests | LIN-012 found a real bypass of the small-cohort rule before release; fixed |
+| 2a Role inheritance (sticky denies), revision/fingerprint, decision ids, audit fields | VERIFIED (local) | 2f1919c | test_policy_inheritance (11) | |
+| 2b Policy diff/simulate/explain/templates CLI | VERIFIED (local) | e64859a | test_policy_tools (21) | |
+| 2c Opt-in AST tenant-filter rewrite + checkpoint | VERIFIED (local) | b0b5ade | test_tenant_rewrite (32, executes on SQLite, tenants 1-3) | |
+| 2d Docs, ADR-011/012, v0.3.0 bump | VERIFIED (local) | see PR | full gate 1,804 passed, 94% | |

sqlguard_ninja-0.3.0/docs/development/NEXT_ACTIONS.md

@@ -0,0 +1,5 @@
+# Next actions (development program)
+
+1. Merge the v0.3.0 PR, tag v0.3.0, release, verify PyPI and a fresh install.
+2. Phase 3 (v0.3.x or v0.4.0): MCP stdio server with validation-only tools (`validate_sql`, `explain_policy_decision`, `inspect_query_cost`, `get_policy_capabilities`), trusted role and tenant from server config, tested with a real MCP client (the official Python SDK client over stdio).
+3. Workstream 1 open items: independent dataset (#6), function/catalog cases (#5).

sqlguard_ninja-0.3.0/docs/development/TEST_EVIDENCE.md

@@ -0,0 +1,12 @@
+# Test evidence
+
+| Date | Scope | Command | Result |
+|---|---|---|---|
+| 2026-10-24 | Baseline (v0.1.1) | `pytest --cov` | 1,655 passed, 95% (local, Python 3.11) |
+| 2026-10-24 | v0.2.0 candidate | full gate (`ruff`, `mypy`, corpus `--check`, `pytest --cov`, build, `twine check`) | 1,738 passed, 94% branch coverage; twine PASSED |
+| 2026-10-24 | Benchmark, corpus 1.1.0 | `sqlninja benchmark run --dataset builtin:v1` (4 adapters) | see docs/benchmarks/RESULTS_v1.1.md |
+| 2026-10-24 | v0.2.0 PR #17 | CI run on PR | 12/12 jobs green; gate: baseline from main, 4 approved relabels, 0 regressions |
+| 2026-10-24 | v0.2.0 main | CI run 40107938223 on 8b59a38 | success |
+| 2026-10-24 | v0.2.0 publish | release.yml run 40108113801 | build + publish success; wheel and sdist with PEP 740 provenance; 0.1.0 and 0.1.1 unchanged |
+| 2026-10-24 | v0.2.0 fresh install | `pip install --no-cache-dir --index-url https://pypi.org/simple sqlguard-ninja==0.2.0` (Python 3.13, outside repo) | import from site-packages; lineage allow/deny and tenant push-down via CLI; bundled benchmark 1,044 evaluations with CSV, tiers, 14 file hashes |
+| 2026-10-24 | v0.3.0 candidate | full gate | 1,804 passed, 94%; build + twine PASSED; 3 templates in wheel |

{sqlguard_ninja-0.2.0 → sqlguard_ninja-0.3.0}/docs/development/progress.json

@@ -13,7 +13,8 @@
       ],
       "evidence": [
         "tiers, basis, F1, Wilson CIs, CSV, hashes: VERIFIED locally",
-        "no independent dataset yet (#6); function/catalog cases absent (#5)"
+        "no independent dataset yet (#6); function/catalog cases absent (#5)",
+        "v0.2.0 released: tiers/CIs/CSV/hashes; still no independent data"
       ],
       "blockers": [
         "external dataset needs licensed independent source (#6)"
@@ -22,24 +23,27 @@
     {
       "id": 2,
       "name": "Lineage-aware privacy",
-      "status": "VERIFIED",
+      "status": "RELEASED",
       "release": "v0.2.0",
       "issues": [
         8,
         9
       ],
       "evidence": [
-        "corpus 1.1.0 lineage cases + tests/unit/test_lineage.py; full gate 1,738 passed"
+        "corpus 1.1.0 lineage cases + tests/unit/test_lineage.py; full gate 1,738 passed",
+        "v0.2.0 on PyPI; fresh install verified"
       ],
       "blockers": []
     },
     {
       "id": 3,
       "name": "Policy-as-code and multitenancy",
-      "status": "NOT_STARTED",
+      "status": "VERIFIED",
       "release": "v0.3.0",
       "issues": [],
-      "evidence": [],
+      "evidence": [
+        "inheritance, diff/simulate/explain/templates, tenant rewrite, audit metadata; 1,804 tests pass locally"
+      ],
       "blockers": []
     },
     {
@@ -103,4 +107,4 @@
       ]
     }
   ]
-}
+}

{sqlguard_ninja-0.2.0 → sqlguard_ninja-0.3.0}/docs/guides/AGENT_INTEGRATION.md

@@ -19,6 +19,9 @@ LLM ──SQL──▶ SQLCheckpoint.evaluate(sql, RequestContext) ──▶ aut
 | `review` | not run | run only with an approval bound to the SQL hash, trace and principal (single use, TTL, no self-approval) | run |
 | `audit` | run, recorded `enforced=False` | run, recorded | run |
 
+`rewrite_tenant_filters=True` (off by default) adds missing tenant filters through the AST and
+executes the re-validated rewrite. See [POLICY_AS_CODE.md](POLICY_AS_CODE.md).
+
 `max_denied_attempts` (default 5) locks a trace after repeated denials, so a retry loop
 cannot grind through rephrasings.
 

sqlguard_ninja-0.3.0/docs/guides/POLICY_AS_CODE.md

@@ -0,0 +1,97 @@
+# Policy as code
+
+Policies are versioned files reviewed like code. This guide covers inheritance, metadata,
+templates and the review workflow. Field reference:
+[POLICY_REFERENCE.md](POLICY_REFERENCE.md).
+
+## Metadata and identity
+
+```yaml
+version: 1                      # schema version
+name: shop
+metadata:
+  revision: "2026.10.2"         # your revision; recorded in every decision and audit event
+  owner: data-governance
+  change_ticket: SEC-1234
+```
+
+Every `ValidationResult` and audit event records:
+- `decision_id`: unique per decision
+- `policy_revision`
+- `policy_fingerprint`: a 16-hex-character content hash that changes with any semantic change
+Audit events also record the `correlation_id` (the request trace id) and a `query_fingerprint`,
+which is the SHA-256 of the literal-redacted SQL. Queries that differ only in literal values
+share a fingerprint, and literal values themselves are never logged.
+
+## Role inheritance
+
+```yaml
+roles:
+  tenant_base:
+    tenant_scoped: true
+    labels: {payment_card: deny}
+  support:
+    extends: [tenant_base]
+    tables: {customers: "*", orders: [id, tenant_id, status]}
+    labels: {contact: allow}
+```
+
+* Grants are merged. Column lists are unioned, and `"*"` wins.
+* Label access and `column_access` override per key, and `limits` come from the nearest role
+  that sets them.
+* **Explicit denies are sticky.** A child cannot relax an inherited deny label, deny column
+  rule, `deny_columns` entry, or `tenant_scoped: true`. The attempt is a load error (a
+  *conflict*), not a silent override.
+* Unknown parents and cycles are load errors. Grants inherited from parents are validated
+  against the catalog just like direct grants.
+
+`sqlninja policy explain --policy P --role R --column table.column` shows the effective access
+and which role in the chain set each label.
+
+## Templates
+
+```bash
+sqlninja policy template                         # list: minimal, multi_tenant_saas, analytics_readonly
+sqlninja policy template multi_tenant_saas --output policies/policy.yaml
+```
+
+## Reviewing a change before activation
+
+```bash
+sqlninja policy diff policies/old.yaml policies/new.yaml            # every change, classified
+sqlninja policy diff old.yaml new.yaml --fail-on-relaxation         # CI: block silent relaxations
+sqlninja policy simulate --policy old.yaml --against new.yaml --cases examples.yaml
+sqlninja policy explain --policy new.yaml --role support --tenant 1 --sql "SELECT ..."
+```
+
+* `diff` compares the **effective** policies, after inheritance. It classifies each change as
+  `relaxes` (can only allow more), `restricts` or `neutral`. Covered areas: roles, table and
+  column grants, `deny_columns`, column rules, label access, `tenant_scoped`, catalog labels
+  and tenant columns, function policy, limits, defaults, cost thresholds and disclosure.
+* `simulate` evaluates example queries (`{id, sql, role, context, expect}`) under the current
+  policy and, optionally, a candidate. It reports decision changes and expectation mismatches,
+  and exits 1 on mismatch, or with `--fail-on-change` when any decision changes.
+* `explain` prints the structured decision: rule ids, messages, internal detail and lineage.
+  Use it for operators. Agent-facing messages remain the redacted `agent_message`.
+
+Suggested CI step for policy repositories:
+
+```yaml
+- run: sqlninja policy diff "$BASE_POLICY" policies/policy.yaml --fail-on-relaxation
+- run: sqlninja policy simulate --policy policies/policy.yaml --cases policies/cases.yaml
+```
+
+## Tenant isolation: inspection, rewrite, and the database
+
+1. **Inspection (default).** Every scope reading a tenant table must pin it to the context
+   tenant. Otherwise the query is denied (see the methodology for the exact semantics).
+2. **Opt-in rewrite.** `SQLCheckpoint(..., rewrite_tenant_filters=True)` or
+   `sqlguard_ninja.tenancy.apply_tenant_filters()` adds the missing
+   `alias.tenant_column = <bind parameter>` predicates through the AST, then **re-validates**.
+   The rewritten string is what gets executed. It refuses when the query has any other
+   problem (a forbidden column, another tenant's id, a write), when ownership is ambiguous
+   (the preserved side of a RIGHT/FULL join), or when the rewritten SQL fails validation. The
+   tenant value is always a bind parameter, never inlined.
+3. **The database (authoritative).** Use PostgreSQL row-level security, or per-tenant
+   credentials, as the real boundary. SQL inspection and rewriting are defence in depth. They
+   cannot see views, functions or data an attacker reaches by other means.

{sqlguard_ninja-0.2.0 → sqlguard_ninja-0.3.0}/docs/guides/POLICY_REFERENCE.md

@@ -9,6 +9,7 @@ start-up instead of silently changing behaviour. Run `sqlninja policy check --po
 ```yaml
 version: 1
 name: shop
+metadata: {revision: "2026.10.1", owner: data-governance}   # recorded in every decision
 dialect: postgres            # default dialect for validate()
 disclosure: names            # or "generic": agent messages never name tables/columns
 
@@ -35,6 +36,7 @@ catalog:
 
 roles:
   support:
+    # extends: [base_role]          # inherit grants; inherited explicit denies cannot be relaxed
     tables:
       customers: [id, tenant_id, email, email_domain]   # or "*", or {columns, deny_columns, column_access}
     labels: {contact: allow, health: deny}
@@ -83,6 +85,9 @@ cost: {enabled: true, review_score: 50, deny_score: 80, large_table_rows: 100000
 
 Without roles, an implicit role grants every catalog table and denies every labelled column.
 
+Inheritance, templates, `policy diff` / `simulate` / `explain` and the tenant-filter rewrite
+are described in [POLICY_AS_CODE.md](POLICY_AS_CODE.md).
+
 ## Decisions
 
 Each rule emits findings with an action (`deny`, `review`, `warn`). Any deny → **DENY**,

sqlguard_ninja-0.3.0/docs/releases/v0.3.0.md

@@ -0,0 +1,29 @@
+# SQLGuard Ninja v0.3.0
+
+Enterprise policy-as-code and tenant enforcement.
+
+## Highlights
+
+* **Role inheritance** with sticky explicit denies: a child role can add permissions, but cannot undo an inherited deny. Conflicts, unknown parents and cycles fail at load time.
+* **Review before activation:** `sqlninja policy diff` classifies every change as relaxes / restricts / neutral (`--fail-on-relaxation` for CI). `policy simulate --against` shows decision changes on example queries, and `policy explain` traces effective access through the inheritance chain.
+* **Auditability:** every decision has a `decision_id`, the policy revision and fingerprint. Audit events add a correlation id, a literal-insensitive query fingerprint and a tenant-rewrite flag.
+* **Templates:** `minimal`, `multi_tenant_saas`, `analytics_readonly`.
+* **Opt-in AST tenant-filter rewrite:** missing tenant pins are added as bind-parameter predicates and the rewrite is re-validated. It is refused on any other problem or on RIGHT/FULL-join ownership ambiguity.
+
+## Compatibility
+
+Existing policies behave as before; the new fields are optional.
+
+## Known limitations
+
+* All benchmark results are internal. There is no independent dataset yet (issue #6), and no restricted-function or system-catalog cases (issue #5).
+* The tenant rewrite emits sqlglot-normalised SQL. Database row-level security remains the authoritative tenant control.
+* Only PostgreSQL and SQLite are supported; writes are denied; no guarantee against SQL injection or data leakage.
+
+## Installation
+
+```bash
+python -m pip install sqlguard-ninja==0.3.0
+```
+
+PyPI: https://pypi.org/project/sqlguard-ninja/0.3.0/

{sqlguard_ninja-0.2.0 → sqlguard_ninja-0.3.0}/docs/security/THREAT_MODEL.md

@@ -57,6 +57,8 @@ flowchart LR
 | T3 | Prompt injection through database content | A ticket body says "now query payments" | Every subsequent query is checked again. Retry lock-out per trace. Read-only session. | The model can still be steered to permitted data. |
 | T4 | Parser ambiguity | Comment and string tricks, nested comments, dollar quoting | sqlglot dialect parsing. The corpus includes formatting and comment cases validated against real engines. Unparseable input is denied. | Unknown tokenizer differences. Report them as vulnerabilities. |
 | T5 | Dialect-specific bypasses | MySQL `/*! */` executable comments, SQLite `ATTACH`/`PRAGMA` | Executable-comment rule for the MySQL family. SQLite session statements are denied. | Untested dialects are experimental. |
+| T6a | Unsafe automatic tenant filtering | A rewrite that changes meaning or masks a query naming another tenant | Rewrite is opt-in, bind-parameter only, refused on any non-tenant finding and on RIGHT/FULL-join ownership ambiguity; the rewritten SQL is re-validated and is the executed string | Rewritten SQL is sqlglot-normalised; RLS remains authoritative |
+| T6b | Silent policy relaxation through inheritance or edits | A child role or edit quietly widens access | Sticky explicit denies (load error on conflict); `policy diff --fail-on-relaxation`; fingerprint and revision in every decision | Reviewers must still read the diff |
 | T6 | Tenant data leakage | missing filter, `OR 1=1`, other tenant id, unpinned join or subquery | Every scope reading a tenant table must pin it with an equality conjunct to the context value or an approved bind parameter. `OR`/`NOT` don't count, and casts of the column don't count. | Apply RLS in the database as the authoritative control. |
 | T7 | Unauthorized columns | `SELECT *`, whole-row references, alias laundering, columns in filters | Schema-based star expansion. Per-scope base-column attribution. Ungranted columns are denied in any clause. | Views and UDFs hide columns. |
 | T8 | Sensitive-data exposure | card numbers, health data in JSON, salary per person | Explicit labels. Deny / aggregate-only / review per role. JSON path labels. Window aggregates count as value-revealing. Small-cohort review. | Inference attacks across queries. |

sqlguard_ninja-0.3.0/src/sqlguard_ninja/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{sqlguard_ninja-0.2.0 → sqlguard_ninja-0.3.0}/src/sqlguard_ninja/cli/main.py

@@ -36,6 +36,15 @@ from sqlguard_ninja.cli.templates import FILES
 from sqlguard_ninja.core.findings import Decision
 from sqlguard_ninja.core.guard import Guard
 from sqlguard_ninja.policy.model import Policy, PolicyError
+from sqlguard_ninja.policy.tools import (
+    TEMPLATES,
+    diff_policies,
+    explain_column,
+    explain_result,
+    load_sim_cases,
+    simulate,
+    template_text,
+)
 from sqlguard_ninja.privacy.suggest import suggest_labels
 from sqlguard_ninja.reporting.markdown import benchmark_report, comparison_report
 
@@ -154,7 +163,9 @@ def cmd_policy_check(args: argparse.Namespace) -> int:
     warnings = []
     if policy.functions.mode == "denylist":
         warnings.append("functions.mode is 'denylist'; 'allowlist' is safer for production")
-    for name, role in policy.roles.items():
+    for name in policy.roles:
+        role = policy.effective_role(name)
+        assert role is not None
         if not role.tenant_scoped and tenant_tables:
             warnings.append(f"role '{name}' is not tenant-scoped")
     for w in warnings:
@@ -174,6 +185,94 @@ def cmd_policy_suggest(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
+def cmd_policy_template(args: argparse.Namespace) -> int:
+    if not args.kind:
+        _out("available templates: " + ", ".join(TEMPLATES))
+        return EXIT_OK
+    try:
+        text = template_text(args.kind)
+    except KeyError as exc:
+        raise CLIError(str(exc.args[0])) from exc
+    if args.output:
+        path = Path(args.output)
+        if path.exists() and not args.force:
+            raise CLIError(f"refusing to overwrite {path}; use --force")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+        _out(f"wrote {path}")
+    else:
+        _out(text)
+    return EXIT_OK
+
+
+def cmd_policy_diff(args: argparse.Namespace) -> int:
+    old, new = _load_policy(args.old), _load_policy(args.new)
+    diff = diff_policies(old, new)
+    if args.format == "json":
+        _out(json.dumps(diff.as_dict(), indent=2, default=str))
+    else:
+        _out(
+            f"policy diff {old.revision} ({old.fingerprint}) -> {new.revision} "
+            f"({new.fingerprint}): {len(diff.changes)} change(s), "
+            f"{len(diff.relaxations)} relaxation(s)"
+        )
+        for c in diff.changes:
+            _out(f"  [{c.effect.value:9}] {c.path}: {c.before!s} -> {c.after!s}")
+    if args.fail_on_relaxation and diff.relaxations:
+        return EXIT_FAIL
+    return EXIT_OK
+
+
+def cmd_policy_simulate(args: argparse.Namespace) -> int:
+    policy = _load_policy(args.policy)
+    against = _load_policy(args.against) if args.against else None
+    try:
+        cases = load_sim_cases(args.cases)
+    except (OSError, ValueError, yaml.YAMLError) as exc:
+        raise CLIError(f"cannot load cases {args.cases}: {exc}") from exc
+    rows = simulate(policy, cases, against)
+    if args.format == "json":
+        _out(json.dumps(rows, indent=2))
+    else:
+        for r in rows:
+            line = f"{r['id']:>6} {r['role'] or '-':18} {r['decision']:6}"
+            if against is not None:
+                marker = " CHANGED" if r["changed"] else ""
+                line += f" -> {r['candidate_decision']:6}{marker}"
+            if r["expect"] is not None:
+                line += f"  expect={r['expect']}"
+            _out(line)
+    key = "candidate_matches_expectation" if against is not None else "matches_expectation"
+    mismatches = sum(1 for r in rows if r.get(key) is False)
+    changed = sum(1 for r in rows if r.get("changed"))
+    _out(f"{len(rows)} case(s); {mismatches} expectation mismatch(es); {changed} changed")
+    if mismatches or (args.fail_on_change and changed):
+        return EXIT_FAIL
+    return EXIT_OK
+
+
+def cmd_policy_explain(args: argparse.Namespace) -> int:
+    policy = _load_policy(args.policy)
+    if bool(args.sql) == bool(args.column):
+        raise CLIError("give exactly one of --sql or --column TABLE.COLUMN")
+    if args.column:
+        table, _, column = args.column.partition(".")
+        try:
+            payload = explain_column(policy, args.role, table.lower(), column.lower())
+        except KeyError as exc:
+            raise CLIError(str(exc.args[0])) from exc
+    else:
+        context: dict[str, Any] = {}
+        if args.tenant is not None:
+            context[policy.tenant.context_key] = args.tenant
+        result = Guard(policy).validate(
+            args.sql, role=args.role, dialect=args.dialect, context=context
+        )
+        payload = explain_result(result)
+    _out(json.dumps(payload, indent=2, default=str))
+    return EXIT_OK
+
+
 def cmd_init(args: argparse.Namespace) -> int:
     root = Path(args.directory)
     existing = [name for name in FILES if (root / name).exists()]
@@ -390,6 +489,34 @@ def build_parser() -> argparse.ArgumentParser:
     common(ps)
     ps.add_argument("--policy")
     ps.set_defaults(func=cmd_policy_suggest)
+    pt = pol.add_parser("template", help="print or write a policy template")
+    pt.add_argument("kind", nargs="?", help="template name (omit to list)")
+    pt.add_argument("--output")
+    pt.add_argument("--force", action="store_true")
+    pt.set_defaults(func=cmd_policy_template)
+    pd = pol.add_parser("diff", help="semantic diff of two policies, flagging relaxations")
+    pd.add_argument("old")
+    pd.add_argument("new")
+    pd.add_argument("--format", choices=["text", "json"], default="text")
+    pd.add_argument("--fail-on-relaxation", action="store_true")
+    pd.set_defaults(func=cmd_policy_diff)
+    psim = pol.add_parser(
+        "simulate", help="evaluate example queries; optionally against a candidate"
+    )
+    psim.add_argument("--policy", required=True)
+    psim.add_argument("--cases", required=True, help="YAML list of {sql, role, context, expect}")
+    psim.add_argument("--against", help="candidate policy to compare with")
+    psim.add_argument("--format", choices=["text", "json"], default="text")
+    psim.add_argument("--fail-on-change", action="store_true")
+    psim.set_defaults(func=cmd_policy_simulate)
+    pe = pol.add_parser("explain", help="explain a decision or a column's effective access")
+    pe.add_argument("--policy", required=True)
+    pe.add_argument("--role", required=True)
+    pe.add_argument("--sql")
+    pe.add_argument("--column", help="TABLE.COLUMN")
+    pe.add_argument("--dialect")
+    pe.add_argument("--tenant")
+    pe.set_defaults(func=cmd_policy_explain)
 
     bench = sub.add_parser("benchmark", help="run and compare benchmarks").add_subparsers(
         dest="bench_cmd", required=True

{sqlguard_ninja-0.2.0 → sqlguard_ninja-0.3.0}/src/sqlguard_ninja/core/findings.py

@@ -97,6 +97,10 @@ class ValidationResult(BaseModel):
     role: str | None
     policy_name: str
     policy_version: int
+    policy_revision: str = "unversioned"
+    policy_fingerprint: str = ""
+    decision_id: str = ""
+    """Unique id of this decision (correlates the result, audit event and logs)."""
     tables: tuple[str, ...] = ()
     columns: tuple[str, ...] = ()
     elapsed_ms: float = 0.0

{sqlguard_ninja-0.2.0 → sqlguard_ninja-0.3.0}/src/sqlguard_ninja/core/guard.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import hashlib
 import time
+import uuid
 from collections.abc import Iterable, Mapping, Sequence
 from typing import Any
 
@@ -176,6 +177,9 @@ class Guard:
             role=role_name,
             policy_name=self.policy.name,
             policy_version=self.policy.version,
+            policy_revision=self.policy.revision,
+            policy_fingerprint=self.policy.fingerprint,
+            decision_id=uuid.uuid4().hex,
             tables=tuple(analysis.base_table_names) if analysis else (),
             columns=tuple(sorted({f"{c.table}.{c.column}" for c in analysis.columns}))
             if analysis

{sqlguard_ninja-0.2.0 → sqlguard_ninja-0.3.0}/src/sqlguard_ninja/integrations/audit.py

@@ -60,8 +60,16 @@ class AuditEvent(BaseModel):
     would_block: bool
     sql_sha256: str
     sql_redacted: str | None
+    query_fingerprint: str | None = None
+    """SHA-256 of the redacted SQL: equal for queries that differ only in literals."""
     dialect: str
     policy: str
+    policy_revision: str = "unversioned"
+    policy_fingerprint: str = ""
+    decision_id: str = ""
+    correlation_id: str | None = None
+    tenant_filter_rewrite: bool = False
+    """True when the executed SQL is the AST-rewritten form with tenant filters added."""
     findings: list[dict[str, Any]]
     approval: dict[str, Any] | None = None
     attempt: int = 1