sqlguard-ninja 0.5.0__tar.gz → 0.6.0__tar.gz

{sqlguard_ninja-0.5.0 → sqlguard_ninja-0.6.0}/CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes are documented here. The project follows
 [Semantic Versioning](https://semver.org/); before 1.0, minor versions may change the API.
 
+## [0.6.0] — 2026-10-24
+
+### Added
+* **Observability** (`sqlguard_ninja.observability`, extras `[otel]` and `[prometheus]`):
+  * `Telemetry` and `InstrumentedGuard` emit OpenTelemetry spans `sqlguard.checkpoint` and
+    `sqlguard.validate`.
+  * `GuardMetrics` exports Prometheus counters and histograms for decisions, findings,
+    latency, errors, resource-limit rejections, checkpoint outcomes and policy identity.
+  * `SQLCheckpoint(telemetry=...)` instruments its guard automatically.
+* **SARIF 2.1.0**: `sqlninja scan PATH... --format sarif|json|text --fail-on deny|review|never`.
+  It validates every statement in SQL files, with stable fingerprints. Tests and CI validate the
+  output against the OASIS schema.
+* **Grafana dashboard** `deploy/grafana/sqlguard-ninja.json`, and a Prometheus + Grafana +
+  synthetic-traffic stack (`examples/observability/`). A new CI job runs that stack.
+* Audit events gain `schema_version` and `rate_limited`. New
+  `SQLCheckpoint(principal_hmac_key=...)` option to pseudonymise principals.
+
+### Security
+* `redact_sql` now redacts hex, bit, byte (`E''`), dollar-quoted, Unicode (`U&''`) and
+  national (`N''`) strings and whole `INTERVAL` expressions. Previously these could reach
+  `sql_redacted` in audit logs. Comments are dropped, and if any literal token survives,
+  redacted SQL is withheld. See threat model T19.
+
 ## [0.5.0] — 2026-10-24
 
 ### Added

{sqlguard_ninja-0.5.0 → sqlguard_ninja-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlguard-ninja
-Version: 0.5.0
+Version: 0.6.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
@@ -30,6 +30,8 @@ Requires-Dist: fastapi>=0.110; extra == 'all'
 Requires-Dist: langchain-core>=0.3; extra == 'all'
 Requires-Dist: langgraph>=0.2; extra == 'all'
 Requires-Dist: mcp<3,>=2.3; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.25; extra == 'all'
+Requires-Dist: prometheus-client>=0.20; extra == 'all'
 Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
 Requires-Dist: pymysql>=1.1; extra == 'all'
 Provides-Extra: dev
@@ -37,10 +39,14 @@ Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: fastapi>=0.110; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: jsonschema>=4.20; extra == 'dev'
 Requires-Dist: langchain-core>=0.3; extra == 'dev'
 Requires-Dist: langgraph>=0.2; extra == 'dev'
 Requires-Dist: mcp<3,>=2.3; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: opentelemetry-api>=1.25; extra == 'dev'
+Requires-Dist: opentelemetry-sdk>=1.25; extra == 'dev'
+Requires-Dist: prometheus-client>=0.20; extra == 'dev'
 Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
 Requires-Dist: pymysql>=1.1; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
@@ -58,8 +64,12 @@ Provides-Extra: mcp
 Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
 Provides-Extra: mysql
 Requires-Dist: pymysql>=1.1; extra == 'mysql'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.20; extra == 'prometheus'
 Description-Content-Type: text/markdown
 
 # SQLGuard Ninja
@@ -290,6 +300,20 @@ The four tools are `validate_sql`, `explain_policy_decision`, `inspect_query_cos
 to a database, and it exposes no execution tool. Tested with the official MCP Python SDK
 client over stdio. See [MCP_INTEGRATION.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/MCP_INTEGRATION.md).
 
+## Observability and SARIF
+
+```bash
+python -m pip install "sqlguard-ninja[otel,prometheus]"
+sqlninja scan sql/ --policy policy.yaml --role reporting --tenant 1 --format sarif --output sqlninja.sarif
+```
+
+`Telemetry(tracer=..., metrics=GuardMetrics())` adds OpenTelemetry spans and Prometheus metrics
+to the checkpoint: decisions, findings by rule, latency, errors, resource-limit rejections and
+checkpoint outcomes. By default no signal contains SQL text, literals, request-context values,
+tenant ids or principals, and tests check this with canary values. A Grafana dashboard
+(`deploy/grafana/`) and a synthetic-traffic Prometheus/Grafana stack are included. SARIF output
+validates against the OASIS 2.1.0 schema. See [OBSERVABILITY.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/OBSERVABILITY.md).
+
 ## Query cost analysis
 
 Every validation includes an explainable static score that uses the catalog's
@@ -371,9 +395,9 @@ the [benchmark bias review](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/m
 
 ## Roadmap
 
-Next: restricted-function and system-catalog benchmark cases, an independent held-out
-corpus, lineage-aware aggregate checks, and tenant predicate push-down. Later: governed
-writes, more tested dialects, and SARIF output. Details in [ROADMAP.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/ROADMAP.md).
+Next: restricted-function and system-catalog benchmark cases (issue #5), an independent
+held-out corpus (issue #6), an interactive demo and a hardened deployment reference. Later:
+governed writes, and database-verified SQL Server and Oracle support. Details in [ROADMAP.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/ROADMAP.md).
 
 ## Links
 
@@ -391,6 +415,8 @@ writes, more tested dialects, and SARIF output. Details in [ROADMAP.md](https://
 * [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)
+* [Observability and SARIF](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/OBSERVABILITY.md)
+* [Database compatibility](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/DATABASE_COMPATIBILITY.md)
 * [Benchmark methodology](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/BENCHMARK_METHODOLOGY.md)
 * [Threat model](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/security/THREAT_MODEL.md)
 * [Limits of static SQL analysis and dialect support](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/security/STATIC_ANALYSIS_LIMITS.md)

{sqlguard_ninja-0.5.0 → sqlguard_ninja-0.6.0}/README.md

@@ -226,6 +226,20 @@ The four tools are `validate_sql`, `explain_policy_decision`, `inspect_query_cos
 to a database, and it exposes no execution tool. Tested with the official MCP Python SDK
 client over stdio. See [MCP_INTEGRATION.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/MCP_INTEGRATION.md).
 
+## Observability and SARIF
+
+```bash
+python -m pip install "sqlguard-ninja[otel,prometheus]"
+sqlninja scan sql/ --policy policy.yaml --role reporting --tenant 1 --format sarif --output sqlninja.sarif
+```
+
+`Telemetry(tracer=..., metrics=GuardMetrics())` adds OpenTelemetry spans and Prometheus metrics
+to the checkpoint: decisions, findings by rule, latency, errors, resource-limit rejections and
+checkpoint outcomes. By default no signal contains SQL text, literals, request-context values,
+tenant ids or principals, and tests check this with canary values. A Grafana dashboard
+(`deploy/grafana/`) and a synthetic-traffic Prometheus/Grafana stack are included. SARIF output
+validates against the OASIS 2.1.0 schema. See [OBSERVABILITY.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/OBSERVABILITY.md).
+
 ## Query cost analysis
 
 Every validation includes an explainable static score that uses the catalog's
@@ -307,9 +321,9 @@ the [benchmark bias review](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/m
 
 ## Roadmap
 
-Next: restricted-function and system-catalog benchmark cases, an independent held-out
-corpus, lineage-aware aggregate checks, and tenant predicate push-down. Later: governed
-writes, more tested dialects, and SARIF output. Details in [ROADMAP.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/ROADMAP.md).
+Next: restricted-function and system-catalog benchmark cases (issue #5), an independent
+held-out corpus (issue #6), an interactive demo and a hardened deployment reference. Later:
+governed writes, and database-verified SQL Server and Oracle support. Details in [ROADMAP.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/ROADMAP.md).
 
 ## Links
 
@@ -327,6 +341,8 @@ writes, more tested dialects, and SARIF output. Details in [ROADMAP.md](https://
 * [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)
+* [Observability and SARIF](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/OBSERVABILITY.md)
+* [Database compatibility](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/DATABASE_COMPATIBILITY.md)
 * [Benchmark methodology](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/BENCHMARK_METHODOLOGY.md)
 * [Threat model](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/security/THREAT_MODEL.md)
 * [Limits of static SQL analysis and dialect support](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/security/STATIC_ANALYSIS_LIMITS.md)

{sqlguard_ninja-0.5.0 → sqlguard_ninja-0.6.0}/THIRD_PARTY_NOTICES.md

@@ -1,7 +1,8 @@
 # Third-party notices
 
 SQLGuard Ninja is licensed under Apache-2.0. **It does not vendor or copy third-party source
-code.** The projects below are used as ordinary dependencies, installed by the package
+code.** The only third-party file in the repository is a test fixture, the SARIF schema
+(below). The projects below are used as ordinary dependencies, installed by the package
 manager under their own licences. Licences were read from installed package metadata on
 2026-10-24. Always check the version you install.
 
@@ -21,6 +22,10 @@ manager under their own licences. Licences were read from installed package meta
 | `langgraph` | langgraph | 1.2.17 | MIT |
 | `fastapi` | fastapi / starlette | 0.162.0 / 1.9.0 | MIT / BSD-3-Clause |
 | `postgres` | psycopg (+ psycopg-binary) | 3.3.6 | LGPL-3.0-only |
+| `mcp` | mcp (official MCP Python SDK) | 2.3.0 | MIT |
+| `mysql` | PyMySQL | 1.2.3 | MIT |
+| `otel` | opentelemetry-api | 1.45.1 | Apache-2.0 |
+| `prometheus` | prometheus-client | 0.26.0 | Apache-2.0 AND BSD-2-Clause |
 
 psycopg is LGPL-3.0. SQLGuard Ninja only imports it at runtime when the `postgres` extra is
 installed. It is not modified or bundled, which is compatible with distributing SQLGuard Ninja
@@ -33,6 +38,23 @@ mypy (MIT), build (MIT). `pgserver` is optionally used for local PostgreSQL test
 declared dependency, and its package metadata on PyPI does not declare a licence. It bundles
 PostgreSQL binaries (PostgreSQL License).
 
+Tests also use jsonschema (MIT) and opentelemetry-sdk (Apache-2.0).
+
+## Test fixture: SARIF 2.1.0 JSON schema
+
+`tests/data/sarif-schema-2.1.0.json` is the unmodified OASIS SARIF 2.1.0 (Errata 01) schema,
+downloaded from
+https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json
+(SHA-256 `c3b4bb2d6093897483348925aaa73af03b3e3f4bd4ca38cef26dcb4212a2682e`). It is used only to
+validate SARIF output in tests and is not part of the wheel.
+
+> Copyright © OASIS Open 2020. All Rights Reserved. This document and translations of it may be
+> copied and furnished to others, and derivative works that comment on or otherwise explain it
+> or assist in its implementation may be prepared, copied, published, and distributed, in whole
+> or in part, without restriction of any kind, provided that the above copyright notice and this
+> section are included on all such copies and derivative works. (OASIS IPR Policy notice; see
+> https://www.oasis-open.org/policies-guidelines/ipr/)
+
 ## External validators used for benchmarking only
 
 Installed into isolated virtual environments by `scripts/setup_external_adapters.py`, never

{sqlguard_ninja-0.5.0 → sqlguard_ninja-0.6.0}/docs/development/IMPLEMENTATION_PROGRESS.md

@@ -10,4 +10,5 @@
 | 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 | RELEASED v0.3.0 | 198a308 | full gate 1,804 passed, 94% | |
 | 3 MCP server (stdio, validation-only) | RELEASED v0.4.0 | ecec4da | 9 tests incl. real SDK client; published-package stdio smoke test | version targets adapted |
-| 4 MySQL tested dialect; SQL Server/Oracle experimental; compatibility matrix | VERIFIED (local, CI pending) | see PR | full gate 1,881 passed, 94%; 15 MySQL server tests run in CI | sql_mode parser differential found and closed (T18) |
+| 4 MySQL tested dialect; SQL Server/Oracle experimental; compatibility matrix | RELEASED v0.5.0 | de4d03f | full gate 1,881 passed, 94%; CI MySQL 8.4: 15 passed, 0 skipped | sql_mode parser differential found and closed (T18) |
+| 5 Observability: OTel spans, Prometheus metrics, audit schema, SARIF scan, Grafana + synthetic stack | VERIFIED (local, CI pending) | see PR | full gate 1,916 passed, 94% | redaction leak (hex/E''/$$/U&/N''/INTERVAL) found and fixed (T19) |

sqlguard_ninja-0.6.0/docs/development/NEXT_ACTIONS.md

@@ -0,0 +1,6 @@
+# Next actions (development program)
+
+1. SQL Server/Oracle real-database tests need vendor licence acceptance (maintainer decision); MySQL function/catalog cases stay under #5.
+2. Merge the v0.6.0 (observability) PR after CI incl. the new observability job; add that job to required checks; release; verify PyPI + fresh `[otel,prometheus]` install.
+3. Phase 6: interactive demo on the FastAPI backend (three roles, editor, explanations, lineage, benchmark dashboard, browser e2e tests).
+4. Phases 7-8: Docker/Kubernetes reference, public demo (hosting needs maintainer authorization).

{sqlguard_ninja-0.5.0 → sqlguard_ninja-0.6.0}/docs/development/TEST_EVIDENCE.md

@@ -16,3 +16,6 @@
 | 2026-10-24 | v0.4.0 release | PR #20 12/12; main CI on ecec4da success; release.yml run 40117676554 success | wheel and sdist on PyPI, both provenance endpoints 200; 0.1.0-0.3.0 unchanged |
 | 2026-10-24 | v0.4.0 fresh install + MCP stdio | `pip install --no-cache-dir "sqlguard-ninja[mcp]==0.4.0"` (Python 3.13, outside repo, 4th attempt; CDN lag), then SDK `stdio_client`/`ClientSession` against installed `sqlninja mcp` | 4 tools; allow/deny/cross-tenant deny; 100,001-char input `invalid_input`; forged `role` argument has no effect (deny); capabilities hide denied tables, `read_only: true`; no finding detail leaked |
 | 2026-10-24 | v0.5.0 candidate (MySQL) | full gate (`ruff`, `mypy`, corpus `--check`, `pytest --cov -m "not mysql"` incl. embedded PostgreSQL, build, `twine check --strict`) | 1,881 passed, 94%; twine PASSED; corpus 1.2.0: 1,070 evaluations, 4 adapters regenerated |
+| 2026-10-24 | v0.5.0 release | PR #22 13/13 (MySQL job: 15 passed, 0 skipped); MySQL job added to required checks; main CI 40119298660 on de4d03f success; release.yml 40119480081 success | wheel and sdist on PyPI, both provenance endpoints 200; 0.1.0-0.4.0 unchanged |
+| 2026-10-24 | v0.5.0 fresh install | `pip install --no-cache-dir "sqlguard-ninja[mysql]==0.5.0"` (Python 3.13, outside repo, `-I`; 2nd attempt) | PyMySQL 1.2.3; dialects include mysql; bundled corpus 1.2.0, 26 MySQL cases 0 mismatches; binding and sql_mode refusals; `o.ID` and card column denied. No MySQL server locally, so execution is evidenced by CI only |
+| 2026-10-24 | v0.6.0 candidate (observability) | full gate (`ruff`, `mypy`, corpus `--check`, `pytest --cov -m "not mysql"`, build, `twine check --strict`) | 1,916 passed, 94%; twine PASSED; SARIF schema-valid; canary privacy tests over 13 literal forms |

{sqlguard_ninja-0.5.0 → sqlguard_ninja-0.6.0}/docs/development/progress.json

@@ -62,25 +62,28 @@
     {
       "id": 5,
       "name": "Database dialects",
-      "status": "VERIFIED",
+      "status": "RELEASED",
       "release": "v0.5.0",
       "issues": [
         11
       ],
       "evidence": [
-        "MySQL executor/binding/sql_mode guard, 26 corpus cases; 1,881 local tests; CI MySQL job pending"
+        "MySQL executor/binding/sql_mode guard, 26 corpus cases; 1,881 local tests; CI MySQL job pending",
+        "v0.5.0 on PyPI with provenance; CI MySQL 8.4 15/15; fresh [mysql] install verified"
       ],
       "blockers": []
     },
     {
       "id": 6,
       "name": "Observability and SARIF",
-      "status": "NOT_STARTED",
-      "release": "v0.4.0",
+      "status": "VERIFIED",
+      "release": "v0.6.0",
       "issues": [
         14
       ],
-      "evidence": [],
+      "evidence": [
+        "OTel/Prometheus/SARIF/Grafana + canary privacy tests; 1,916 local tests; CI pending"
+      ],
       "blockers": []
     },
     {

{sqlguard_ninja-0.5.0 → sqlguard_ninja-0.6.0}/docs/guides/CI_INTEGRATION.md

@@ -11,6 +11,28 @@ git add benchmarks/baseline.json  # baselines change only through reviewed commi
 
 `sqlninja benchmark baseline` refuses to run when `CI` is set. CI never updates baselines.
 
+## SARIF and GitHub code scanning
+
+`sqlninja scan` writes SARIF 2.1.0. Upload it with GitHub's own action, pinned to a commit SHA
+you have reviewed. Uploading needs `security-events: write`, and code scanning must be available
+for the repository.
+
+```yaml
+permissions:
+  contents: read
+  security-events: write
+steps:
+  - uses: actions/checkout@<sha>
+  - run: pip install sqlguard-ninja
+  - run: sqlninja scan sql/ --policy policy.yaml --role reporting --tenant 1 --format sarif --output sqlninja.sarif --fail-on never
+  - uses: github/codeql-action/upload-sarif@<sha>
+    with:
+      sarif_file: sqlninja.sarif
+```
+
+Results are fingerprinted per file, rule and literal-insensitive query, so changing only a
+literal does not open a new alert. The log contains rule messages but no SQL snippet.
+
 ## GitHub Action
 
 See [`examples/github-actions/sql-security.yml`](../../examples/github-actions/sql-security.yml).

sqlguard_ninja-0.6.0/docs/guides/OBSERVABILITY.md

@@ -0,0 +1,133 @@
+# Observability
+
+SQLGuard Ninja can emit OpenTelemetry traces, Prometheus metrics, structured JSON audit
+events and SARIF reports. All of these are optional, and none are imported by the core.
+
+```bash
+python -m pip install "sqlguard-ninja[otel,prometheus]"
+```
+
+## Privacy contract
+
+By default, **no signal contains**:
+
+* SQL text, literal values or comments
+* request context values (for example API keys or other attributes)
+* the tenant id (in traces and metrics)
+* the principal (in traces and metrics)
+* internal finding `detail`
+
+Signals carry the decision, rule ids, bounded labels and correlation identifiers. The
+correlation identifiers are the decision id, the policy fingerprint and revision, the
+literal-insensitive query fingerprint and the correlation (trace) id. Exception messages are
+never recorded, because they can quote SQL; spans record only the exception type.
+
+`tests/unit/test_observability.py` checks this. It sends queries containing a canary value
+through the checkpoint in many literal forms and checks the canary appears in none of the
+signals. The forms include:
+
+* strings, comments, dollar-quoted, `E''`, `U&''`, `N''` and hex strings
+* `INTERVAL` text and MySQL double-quoted strings
+* unterminated and multi-statement input
+
+The signals checked are audit JSON, logging output, exported spans and the Prometheus
+exposition. The test also puts the canary in request-context secrets.
+
+## Tracing (OpenTelemetry)
+
+```python
+from opentelemetry import trace
+from sqlguard_ninja import Guard, Policy
+from sqlguard_ninja.integrations import SQLCheckpoint
+from sqlguard_ninja.observability import GuardMetrics, Telemetry
+
+telemetry = Telemetry(tracer=trace.get_tracer("my-app"), metrics=GuardMetrics())
+checkpoint = SQLCheckpoint(Guard(Policy.from_file("policy.yaml")), telemetry=telemetry)
+```
+
+The checkpoint instruments its guard automatically. To instrument a guard used on its own,
+call `telemetry.instrument(guard)`. Configure exporters and sampling with the OpenTelemetry
+SDK as usual.
+
+| Span | Attributes |
+|---|---|
+| `sqlguard.checkpoint` | `sqlguard.mode`, `.decision`, `.decision_id`, `.authorized`, `.enforced`, `.rate_limited`, `.tenant_filter_rewrite`, `.correlation_id`, `.attempt` |
+| `sqlguard.validate` (child) | `sqlguard.decision`, `.decision_id`, `.role`, `.dialect`, `.policy.name`, `.policy.revision`, `.policy.fingerprint`, `.findings.count`, `.findings.rule_ids`, `.query_fingerprint`; on exceptions `error.type` and an ERROR status |
+
+## Metrics (Prometheus)
+
+`GuardMetrics()` uses a private `CollectorRegistry`. To use your own, pass
+`GuardMetrics(registry=...)`. Expose the metrics with `metrics.render()` (returns the body and
+content type) or with `prometheus_client.start_http_server(port, registry=metrics.registry)`.
+
+| Metric | Labels | Meaning |
+|---|---|---|
+| `sqlguard_decisions_total` | `decision`, `role`, `dialect`, `policy` | validations |
+| `sqlguard_findings_total` | `rule_id`, `action` | findings per rule |
+| `sqlguard_validation_duration_seconds` | `decision` | histogram |
+| `sqlguard_validation_errors_total` | `error` (exception type) | exceptions during validation |
+| `sqlguard_limit_rejections_total` | `rule_id` | length, AST size, structure and cost limits |
+| `sqlguard_checkpoint_outcomes_total` | `mode`, `outcome` | `allowed`, `blocked`, `approved`, `rejected`, `audit_only`, `rate_limited` |
+| `sqlguard_policy_info` | `policy`, `revision`, `fingerprint` | always 1 |
+
+Label cardinality is bounded. A role not defined in the policy is reported as `unknown`.
+
+## Audit events
+
+`SQLCheckpoint(audit_sink=...)` writes one `AuditEvent` per decision. It works with
+`JsonlAuditSink`, `LoggingAuditSink`, or your own sink. Each event carries:
+
+* `schema_version` (`sqlninja.audit/1`), `decision_id`, `correlation_id`
+* `policy_revision`, `policy_fingerprint`
+* `sql_sha256`, `query_fingerprint`
+* `sql_redacted`: literals become `?` and comments are dropped. It is withheld (`null`) if the
+  SQL cannot be parsed, or if any literal token survives redaction.
+* `rate_limited`, plus the rule ids and actions of the findings
+
+Audit events do record the principal and tenant, because that is their purpose. Pass
+`principal_hmac_key=` to store an HMAC-SHA256 pseudonym of the principal instead. Treat audit
+logs as sensitive. If a short query embeds a guessable secret, its `sql_sha256` can be
+brute-forced. Use `query_fingerprint` where an identifier is enough.
+
+## SARIF
+
+```bash
+sqlninja scan sql/ --policy policy.yaml --role reporting --tenant 1 --format sarif --output sqlninja.sarif
+```
+
+`scan` validates every statement in `*.sql` files and splits them with the dialect tokenizer.
+Each finding becomes a SARIF result:
+
+* located at its statement
+* level by action: `error` for deny, `warning` for review, `note` for warn
+* carrying a `partialFingerprints` entry that is stable when only literals change
+
+No code snippet is copied into the log. The output validates against the official OASIS SARIF
+2.1.0 schema, both in the tests and in CI. To upload to GitHub code scanning, see
+[CI_INTEGRATION.md](CI_INTEGRATION.md).
+
+## Grafana dashboard and synthetic telemetry
+
+`deploy/grafana/sqlguard-ninja.json` is a Grafana dashboard. It shows:
+
+* decisions per second
+* deny ratio and errors
+* p50/p95/p99 latency
+* top rules
+* checkpoint outcomes
+* resource-limit rejections
+* decisions by role
+* loaded policies
+
+To see it with synthetic traffic:
+
+```bash
+docker compose -f examples/observability/docker-compose.yml up -d --wait
+# Grafana (read-only, anonymous): http://127.0.0.1:3000/d/sqlguard-ninja
+# Prometheus:                     http://127.0.0.1:9090
+```
+
+The traffic generator replays the bundled synthetic corpus through an instrumented
+checkpoint. It executes nothing. CI starts this stack and checks two things: Prometheus has
+scraped `sqlguard_decisions_total`, and Grafana has provisioned the dashboard and can query
+Prometheus.

sqlguard_ninja-0.6.0/docs/releases/v0.6.0.md

@@ -0,0 +1,24 @@
+# SQLGuard Ninja v0.6.0
+
+## Highlights
+
+* **OpenTelemetry tracing and Prometheus metrics.** Install the optional extras `[otel]` and `[prometheus]`. Pass `SQLCheckpoint(telemetry=Telemetry(tracer=..., metrics=GuardMetrics()))` to get spans for checkpoint and validation decisions. Metrics cover decisions, findings by rule, latency, errors, resource-limit rejections and checkpoint outcomes, all with bounded labels.
+* **Privacy by default.** Spans, metrics and audit events contain no SQL text, literals, comments, request-context values or internal detail. Traces and metrics also omit tenant ids and principals. Canary tests check this across many literal forms.
+* **SARIF 2.1.0.** `sqlninja scan` validates every statement in SQL files and writes SARIF for code scanning. The output validates against the OASIS schema in the tests and in CI.
+* **Grafana dashboard.** It ships with a local Prometheus + Grafana stack fed by synthetic traffic, which CI starts and checks.
+
+## Security fix
+
+* Audit redaction previously let hex, bit, `E''`, dollar-quoted, `U&''` and `N''` strings, and `INTERVAL` text, through into `sql_redacted`. All are now redacted, and redacted SQL is withheld if any literal token survives. If you keep audit logs from earlier versions, review them for inlined secrets.
+
+## Notes
+
+* All benchmark results are still internal (issues #5 and #6). SQL Server and Oracle remain parser-level experimental.
+
+## Installation
+
+```bash
+python -m pip install "sqlguard-ninja[otel,prometheus]==0.6.0"
+```
+
+PyPI: https://pypi.org/project/sqlguard-ninja/0.6.0/

{sqlguard_ninja-0.5.0 → sqlguard_ninja-0.6.0}/docs/security/THREAT_MODEL.md

@@ -58,6 +58,7 @@ flowchart LR
 | 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. |
 | T17 | MCP client or model escalating privileges | A model passes `role` or `tenant` arguments, or probes `get_policy_capabilities` for hidden tables | Identity fixed at server start from operator config; tool schemas have no identity arguments; capabilities list only granted, non-denied columns; no execution or credentials in the server | Anyone who can edit the MCP client configuration chooses the identity |
+| T19 | Secrets leaking through logs, traces, metrics or SARIF | A model inlines a credential or customer value as a literal or comment, or an exception message quotes SQL | Redaction of every literal form, with comments dropped; output is re-tokenized and withheld if any literal survives; telemetry carries ids and bounded labels only; spans record exception types only; SARIF copies no snippet; canary tests | `sql_sha256` is brute-forceable for short secrets; custom sinks and rules can add their own leaks |
 | T18 | MySQL parser differential through `sql_mode` | Under `ANSI_QUOTES` or `NO_BACKSLASH_ESCAPES` the server reads a validated string differently (e.g. `"card_number"` as a column, not a string) | `mysql_executor` checks `@@SESSION.sql_mode` and refuses those flags; placeholder values with backslashes are refused | Custom executors must call `check_sql_mode` themselves; global `sql_mode` changes between the check and the statement are not detected |
 | 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 |

sqlguard_ninja-0.6.0/examples/observability/docker-compose.yml

@@ -0,0 +1,47 @@
+# Local observability stack with synthetic traffic: Prometheus + Grafana + traffic generator.
+# Synthetic data only; nothing is executed against a database. Ports bind to 127.0.0.1.
+#
+#   docker compose -f examples/observability/docker-compose.yml up -d --wait
+#   open http://127.0.0.1:3000/d/sqlguard-ninja   (anonymous read-only viewer)
+services:
+  traffic:
+    image: python:3.12-slim
+    working_dir: /src
+    volumes: ["../..:/src:ro"]
+    command: >-
+      sh -c "pip install --no-cache-dir --target /tmp/deps '/src[prometheus]' >/dev/null &&
+      PYTHONPATH=/tmp/deps python /src/examples/observability/synthetic_traffic.py --host 0.0.0.0 --port 9464"
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:9464/metrics')"]
+      interval: 5s
+      retries: 60
+    read_only: true
+    tmpfs: ["/tmp:exec,mode=1777"]  # pip installs compiled wheels here
+    user: "65534:65534"
+    environment: {HOME: /tmp, PIP_CACHE_DIR: /tmp/pip}
+  prometheus:
+    image: prom/prometheus:v3.13.5@sha256:aafa9d694e6a883c02db516d9f6e5b84e14195f49a2a6456a4cca815edda72b9
+    volumes: ["./prometheus.yml:/etc/prometheus/prometheus.yml:ro"]
+    ports: ["127.0.0.1:9090:9090"]
+    depends_on: {traffic: {condition: service_healthy}}
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:9090/-/ready"]
+      interval: 5s
+      retries: 30
+  grafana:
+    image: grafana/grafana:13.0.11@sha256:2abd2114bb65e4d6f0614206b7c882c1e7c6a992827ba08396aa5afc23ca07f5
+    environment:
+      GF_AUTH_ANONYMOUS_ENABLED: "true"
+      GF_AUTH_ANONYMOUS_ORG_ROLE: Viewer
+      GF_AUTH_DISABLE_LOGIN_FORM: "true"
+      GF_USERS_ALLOW_SIGN_UP: "false"
+      GF_ANALYTICS_REPORTING_ENABLED: "false"
+    volumes:
+      - ./grafana/provisioning:/etc/grafana/provisioning:ro
+      - ../../deploy/grafana:/var/lib/grafana/dashboards:ro
+    ports: ["127.0.0.1:3000:3000"]
+    depends_on: {prometheus: {condition: service_healthy}}
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/api/health"]
+      interval: 5s
+      retries: 30

sqlguard_ninja-0.6.0/examples/observability/grafana/provisioning/dashboards/sqlguard.yml

@@ -0,0 +1,9 @@
+apiVersion: 1
+providers:
+  - name: sqlguard-ninja
+    folder: SQLGuard Ninja
+    type: file
+    disableDeletion: true
+    allowUiUpdates: false
+    options:
+      path: /var/lib/grafana/dashboards

sqlguard_ninja-0.6.0/examples/observability/grafana/provisioning/datasources/prometheus.yml

@@ -0,0 +1,9 @@
+apiVersion: 1
+datasources:
+  - name: Prometheus
+    uid: prometheus
+    type: prometheus
+    access: proxy
+    url: http://prometheus:9090
+    isDefault: true
+    editable: false

sqlguard_ninja-0.6.0/examples/observability/prometheus.yml

@@ -0,0 +1,6 @@
+global:
+  scrape_interval: 5s
+scrape_configs:
+  - job_name: sqlguard-synthetic
+    static_configs:
+      - targets: ["traffic:9464"]

sqlguard_ninja-0.6.0/examples/observability/smoke_check.py

@@ -0,0 +1,42 @@
+"""CI smoke check for the observability stack: Prometheus scraped the synthetic metrics
+and Grafana provisioned the dashboard with a working Prometheus datasource."""
+
+import json
+import sys
+import time
+import urllib.parse
+import urllib.request
+
+
+def get(url: str) -> dict:
+    with urllib.request.urlopen(url, timeout=10) as r:
+        return json.load(r)
+
+
+def main() -> int:
+    q = urllib.parse.quote("sum(sqlguard_decisions_total)")
+    for _ in range(40):
+        data = get(f"http://127.0.0.1:9090/api/v1/query?query={q}")["data"]["result"]
+        if data and float(data[0]["value"][1]) > 0:
+            break
+        time.sleep(3)
+    else:
+        print("Prometheus has no sqlguard_decisions_total samples")
+        return 1
+    dash = get("http://127.0.0.1:3000/api/dashboards/uid/sqlguard-ninja")["dashboard"]
+    exprs = [t["expr"] for p in dash["panels"] for t in p["targets"]]
+    ds = urllib.parse.quote(
+        exprs[0].replace("$__rate_interval", "1m").replace('{policy=~"$policy"}', "")
+    )
+    proxied = get(
+        f"http://127.0.0.1:3000/api/datasources/proxy/uid/prometheus/api/v1/query?query={ds}"
+    )
+    print(
+        f"decisions={data[0]['value'][1]} panels={len(dash['panels'])}",
+        f"grafana_query={proxied['status']}",
+    )
+    return 0 if proxied["status"] == "success" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())