sqlguard-ninja 0.1.0__py3-none-any.whl

sqlguard_ninja/core/guard.py

@@ -0,0 +1,256 @@
+"""The :class:`Guard` validates one SQL string against a policy for one role."""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any
+
+from sqlguard_ninja.core.analysis import analyse
+from sqlguard_ninja.core.findings import (
+    Action,
+    Category,
+    Finding,
+    Severity,
+    ValidationResult,
+    combine,
+)
+from sqlguard_ninja.core.rules.access import ColumnAccessRule, TableAccessRule
+from sqlguard_ninja.core.rules.base import Rule, RuleContext
+from sqlguard_ninja.core.rules.catalog import SystemCatalogRule
+from sqlguard_ninja.core.rules.functions import FunctionPolicyRule
+from sqlguard_ninja.core.rules.statements import ReadOnlyStatementRule
+from sqlguard_ninja.core.rules.structure import StructureLimitsRule
+from sqlguard_ninja.core.rules.tenant import TenantIsolationRule
+from sqlguard_ninja.policy.model import Access, Policy, Role, TableGrant
+from sqlguard_ninja.privacy.rules import PrivacyPolicyRule
+from sqlguard_ninja.query_cost.static import StaticCostRule
+
+
+def default_rules() -> list[Rule]:
+    """The built-in rule pipeline, in evaluation order."""
+    return [
+        ReadOnlyStatementRule(),
+        SystemCatalogRule(),
+        FunctionPolicyRule(),
+        TableAccessRule(),
+        ColumnAccessRule(),
+        PrivacyPolicyRule(),
+        TenantIsolationRule(),
+        StructureLimitsRule(),
+        StaticCostRule(),
+    ]
+
+
+def sql_sha256(sql: str) -> str:
+    # surrogatepass: hashing must not fail on input that is itself rejected as invalid.
+    return hashlib.sha256(sql.encode("utf-8", errors="surrogatepass")).hexdigest()
+
+
+def _preflight(sql: str, policy: Policy, limits_len: int) -> Finding | None:
+    if not sql or not sql.strip():
+        return Finding(
+            rule_id="parse.empty",
+            category=Category.PARSE,
+            severity=Severity.LOW,
+            action=Action.DENY,
+            message="The query is empty.",
+        )
+    if len(sql) > limits_len:
+        return Finding(
+            rule_id="parse.too_long",
+            category=Category.PARSE,
+            severity=Severity.MEDIUM,
+            action=Action.DENY,
+            message=f"The query is longer than {limits_len} characters.",
+        )
+    try:
+        sql.encode("utf-8")
+    except UnicodeEncodeError:
+        return Finding(
+            rule_id="parse.invalid_characters",
+            category=Category.PARSE,
+            severity=Severity.HIGH,
+            action=Action.DENY,
+            message="The query is not valid UTF-8 text.",
+        )
+    if "\x00" in sql:
+        return Finding(
+            rule_id="parse.invalid_characters",
+            category=Category.PARSE,
+            severity=Severity.HIGH,
+            action=Action.DENY,
+            message="The query contains NUL characters.",
+        )
+    return None
+
+
+class Guard:
+    """Validate SQL against a :class:`~sqlguard_ninja.policy.Policy`.
+
+    The guard is stateless and thread-safe: create one per policy at start-up and reuse it.
+    It never executes SQL and never rewrites it — callers must execute exactly the string
+    they validated.
+
+    Example::
+
+        guard = Guard(Policy.from_file("policy.yaml"))
+        result = guard.validate("SELECT id FROM orders WHERE tenant_id = :tenant_id",
+                                role="support_analyst", context={"tenant_id": 42})
+        if not result.allowed:
+            print(result.explain())
+    """
+
+    def __init__(self, policy: Policy, rules: Sequence[Rule] | None = None) -> None:
+        self.policy = policy
+        self.rules: list[Rule] = list(rules) if rules is not None else default_rules()
+
+    def with_rules(self, extra: Iterable[Rule]) -> Guard:
+        """Return a new guard with additional custom rules appended."""
+        return Guard(self.policy, [*self.rules, *extra])
+
+    def _implicit_role(self) -> Role:
+        return Role(
+            description="implicit: policy defines no roles",
+            tables={name: TableGrant() for name in self.policy.catalog.tables},
+            unlisted_label_access=Access.DENY,
+        )
+
+    def validate(
+        self,
+        sql: str,
+        *,
+        role: str | None = None,
+        dialect: str | None = None,
+        context: Mapping[str, Any] | None = None,
+    ) -> ValidationResult:
+        """Validate ``sql`` and return a :class:`ValidationResult`. Never raises on bad SQL."""
+        started = time.perf_counter()
+        dialect = (dialect or self.policy.dialect).lower()
+        context = dict(context or {})
+        findings: list[Finding] = []
+
+        role_name, role_obj = self.policy.role(role)
+        if not self.policy.roles:
+            role_obj = self._implicit_role()
+        elif role_obj is None:
+            findings.append(
+                Finding(
+                    rule_id="role.unknown",
+                    category=Category.TABLE_ACCESS,
+                    severity=Severity.HIGH,
+                    action=Action.DENY,
+                    message="No valid role was supplied for this request.",
+                    detail=f"role {role!r} is not defined in policy {self.policy.name!r}",
+                )
+            )
+        limits = self.policy.effective_limits(role_obj)
+
+        pre = _preflight(sql, self.policy, limits.max_sql_length)
+        analysis = None
+        if pre is not None:
+            findings.append(pre)
+        else:
+            analysis = analyse(sql, dialect, self.policy.catalog, max_nodes=limits.max_ast_nodes)
+            findings.extend(self._structural_findings(analysis, limits.max_ast_nodes))
+
+        if analysis is not None and not findings_block_analysis(findings):
+            ctx = RuleContext(
+                analysis=analysis,
+                policy=self.policy,
+                role_name=role_name,
+                role=role_obj,
+                limits=limits,
+                context=context,
+            )
+            for rule in self.rules:
+                findings.extend(rule.check(ctx))
+
+        elapsed = (time.perf_counter() - started) * 1000
+        return ValidationResult(
+            decision=combine(findings),
+            findings=tuple(findings),
+            sql_sha256=sql_sha256(sql or ""),
+            dialect=dialect,
+            role=role_name,
+            policy_name=self.policy.name,
+            policy_version=self.policy.version,
+            tables=tuple(analysis.base_table_names) if analysis else (),
+            columns=tuple(sorted({f"{c.table}.{c.column}" for c in analysis.columns}))
+            if analysis
+            else (),
+            elapsed_ms=elapsed,
+        )
+
+    @staticmethod
+    def _structural_findings(analysis: Any, max_nodes: int) -> list[Finding]:
+        out: list[Finding] = []
+        if analysis.parse_error is not None:
+            out.append(
+                Finding(
+                    rule_id="parse.error",
+                    category=Category.PARSE,
+                    severity=Severity.MEDIUM,
+                    action=Action.DENY,
+                    message="The query could not be parsed in the configured SQL dialect.",
+                    detail=analysis.parse_error,
+                )
+            )
+        elif len(analysis.statements) == 0:
+            out.append(
+                Finding(
+                    rule_id="parse.empty",
+                    category=Category.PARSE,
+                    severity=Severity.LOW,
+                    action=Action.DENY,
+                    message="The query contains no statement.",
+                )
+            )
+        elif len(analysis.statements) > 1:
+            out.append(
+                Finding(
+                    rule_id="statement.multiple",
+                    category=Category.STATEMENT,
+                    severity=Severity.CRITICAL,
+                    action=Action.DENY,
+                    message="Only one statement may be executed at a time.",
+                    detail=f"{len(analysis.statements)} statements",
+                )
+            )
+        elif analysis.node_count > max_nodes:
+            out.append(
+                Finding(
+                    rule_id="parse.too_complex",
+                    category=Category.PARSE,
+                    severity=Severity.MEDIUM,
+                    action=Action.DENY,
+                    message="The query is too complex to analyse safely.",
+                    detail=f"{analysis.node_count} AST nodes > {max_nodes}",
+                )
+            )
+        elif analysis.qualify_error is not None:
+            out.append(
+                Finding(
+                    rule_id="parse.analysis_incomplete",
+                    category=Category.PARSE,
+                    severity=Severity.MEDIUM,
+                    action=Action.DENY,
+                    message="The query could not be fully analysed, so it is not permitted.",
+                    detail=analysis.qualify_error,
+                )
+            )
+        return out
+
+
+def findings_block_analysis(findings: list[Finding]) -> bool:
+    """Parse-level failures and multi-statements stop the rule pipeline.
+
+    An incomplete *qualification* does not: statement, catalog and function rules still
+    run on the parsed tree so the caller gets the most specific reason available.
+    """
+    return any(
+        (f.rule_id.startswith("parse.") and f.rule_id != "parse.analysis_incomplete")
+        or f.rule_id == "statement.multiple"
+        for f in findings
+    )

sqlguard_ninja/core/rules/__init__.py

@@ -0,0 +1 @@
+"""rules package."""

sqlguard_ninja/core/rules/access.py

@@ -0,0 +1,127 @@
+"""Table and column grants.
+
+Unknown and ungranted objects produce the *same* agent-facing message, so a caller cannot use
+the guard to discover which tables exist.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from sqlguard_ninja.core.findings import Action, Category, Finding, Severity
+from sqlguard_ninja.core.rules.base import RuleContext
+from sqlguard_ninja.core.rules.catalog import is_system_object
+
+
+class TableAccessRule:
+    rule_ids = ("table.not_permitted",)
+
+    def check(self, ctx: RuleContext) -> Iterator[Finding]:
+        catalog = ctx.policy.catalog
+        seen: set[str] = set()
+        for ref in ctx.analysis.tables:
+            if ref.is_function or is_system_object(ref.name, ref.schema):
+                continue  # handled by the function and catalog rules
+            if ref.qualified in seen:
+                continue
+            seen.add(ref.qualified)
+            message = f"The {ctx.name('table', ref.name)} is not available to this role."
+            schema_ok = ref.schema is None or ref.schema == catalog.default_schema
+            if ref.name not in catalog.tables or not schema_ok:
+                yield Finding(
+                    rule_id="table.not_permitted",
+                    category=Category.TABLE_ACCESS,
+                    severity=Severity.HIGH,
+                    action=ctx.policy.defaults.unknown_table_action,
+                    message=message,
+                    detail=f"table {ref.qualified} is not in the policy catalog",
+                    table=ref.qualified,
+                )
+                continue
+            if ctx.role is not None and ref.name not in ctx.role.tables:
+                yield Finding(
+                    rule_id="table.not_permitted",
+                    category=Category.TABLE_ACCESS,
+                    severity=Severity.HIGH,
+                    action=Action.DENY,
+                    message=message,
+                    detail=f"role {ctx.role_name!r} has no grant on {ref.name}",
+                    table=ref.name,
+                )
+
+
+class ColumnAccessRule:
+    """Column grants, unresolved columns and ``*`` that cannot be expanded."""
+
+    rule_ids = ("column.not_permitted", "column.unresolved", "column.star_unexpandable")
+
+    def check(self, ctx: RuleContext) -> Iterator[Finding]:
+        catalog = ctx.policy.catalog
+        defaults = ctx.policy.defaults
+        seen: set[tuple[str, str]] = set()
+        for ref in ctx.analysis.columns:
+            key = (ref.table, ref.column)
+            if key in seen:
+                continue
+            table = catalog.tables.get(ref.table)
+            if table is None:
+                continue  # the table rule already reported it
+            grant = ctx.role.tables.get(ref.table) if ctx.role is not None else None
+            if ctx.role is not None and grant is None:
+                continue  # ungranted table: reported once by the table rule
+            col_msg = ctx.name("column", f"{ref.table}.{ref.column}")
+            star_hint = (
+                " The query selects all columns; list only the columns you need."
+                if ref.whole_row
+                else ""
+            )
+            if ref.column not in table.columns:
+                seen.add(key)
+                yield Finding(
+                    rule_id="column.not_permitted",
+                    category=Category.COLUMN_ACCESS,
+                    severity=Severity.MEDIUM,
+                    action=defaults.unresolved_column_action,
+                    message=f"The {col_msg} is not available to this role.",
+                    detail="column not in catalog",
+                    table=ref.table,
+                    column=ref.column,
+                )
+                continue
+            if grant is None:
+                continue
+            listed = grant.columns == "*" or ref.column in grant.columns
+            if not listed or ref.column in grant.deny_columns:
+                seen.add(key)
+                yield Finding(
+                    rule_id="column.not_permitted",
+                    category=Category.COLUMN_ACCESS,
+                    severity=Severity.HIGH,
+                    action=Action.DENY,
+                    message=f"The {col_msg} is not available to this role.{star_hint}",
+                    detail=f"role {ctx.role_name!r} grant excludes this column",
+                    table=ref.table,
+                    column=ref.column,
+                )
+
+        for name in sorted(set(ctx.analysis.unresolved_columns)):
+            yield Finding(
+                rule_id="column.unresolved",
+                category=Category.COLUMN_ACCESS,
+                severity=Severity.MEDIUM,
+                action=defaults.unresolved_column_action,
+                message=(
+                    "A column reference could not be attributed to a permitted table; "
+                    "qualify columns with their table alias."
+                ),
+                detail=f"unresolved column {name}",
+            )
+        for star in sorted(set(ctx.analysis.unexpandable_stars)):
+            yield Finding(
+                rule_id="column.star_unexpandable",
+                category=Category.COLUMN_ACCESS,
+                severity=Severity.MEDIUM,
+                action=defaults.unexpandable_star_action,
+                message="SELECT * over a source without a known schema is not permitted.",
+                detail=f"cannot expand {star}",
+            )

sqlguard_ninja/core/rules/base.py

@@ -0,0 +1,40 @@
+"""Rule protocol and the context passed to every rule."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from sqlguard_ninja.core.analysis import QueryAnalysis
+from sqlguard_ninja.core.findings import Finding
+from sqlguard_ninja.policy.model import Disclosure, Limits, Policy, Role
+
+
+@dataclass(frozen=True)
+class RuleContext:
+    """Everything a rule may look at. Rules must not mutate it."""
+
+    analysis: QueryAnalysis
+    policy: Policy
+    role_name: str | None
+    role: Role | None
+    limits: Limits
+    context: Mapping[str, Any] = field(default_factory=dict)
+    """Trusted, server-side request values (e.g. ``tenant_id``). Never model output."""
+
+    def name(self, kind: str, value: str) -> str:
+        """Render a schema object name subject to the policy's disclosure setting."""
+        if self.policy.disclosure == Disclosure.GENERIC:
+            return f"requested {kind}"
+        return f"{kind} '{value}'"
+
+
+@runtime_checkable
+class Rule(Protocol):
+    """A policy rule. ``rule_ids`` documents every id the rule can emit."""
+
+    @property
+    def rule_ids(self) -> tuple[str, ...]: ...
+
+    def check(self, ctx: RuleContext) -> Iterable[Finding]: ...

sqlguard_ninja/core/rules/catalog.py

@@ -0,0 +1,61 @@
+"""System-catalog and metadata access."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from sqlguard_ninja.core.findings import Category, Finding, Severity
+from sqlguard_ninja.core.rules.base import RuleContext
+
+SYSTEM_SCHEMAS = frozenset(
+    {"information_schema", "pg_catalog", "pg_toast", "mysql", "performance_schema", "sys"}
+)
+SYSTEM_TABLES = frozenset(
+    {
+        "sqlite_master",
+        "sqlite_schema",
+        "sqlite_temp_master",
+        "sqlite_temp_schema",
+        "sqlite_sequence",
+        "sqlite_dbpage",
+        "sqlite_stmt",
+        "dbstat",
+    }
+)
+SYSTEM_PREFIXES = ("pg_", "sqlite_", "pragma_")
+
+
+def is_system_object(name: str, schema: str | None) -> bool:
+    """True for catalog tables, views and table-valued pragma functions."""
+    if schema and schema in SYSTEM_SCHEMAS:
+        return True
+    return name in SYSTEM_TABLES or name.startswith(SYSTEM_PREFIXES)
+
+
+class SystemCatalogRule:
+    """Deny reads of ``information_schema``, ``pg_catalog``, ``sqlite_master`` and similar.
+
+    Catalog reads let an agent enumerate tables and columns it was never granted, and some
+    catalog relations (``pg_shadow``, ``pg_authid``) expose credentials.
+    """
+
+    rule_ids = ("catalog.system_object",)
+
+    def check(self, ctx: RuleContext) -> Iterator[Finding]:
+        seen: set[str] = set()
+        for ref in ctx.analysis.tables:
+            name = ref.function_name if ref.is_function else ref.name
+            if name is None or not is_system_object(name, ref.schema):
+                continue
+            if ref.qualified in seen:
+                continue
+            seen.add(ref.qualified)
+            yield Finding(
+                rule_id="catalog.system_object",
+                category=Category.CATALOG,
+                severity=Severity.HIGH,
+                action=ctx.policy.defaults.catalog_access_action,
+                message="Access to database system catalogs and metadata is not permitted.",
+                detail=f"system object {ref.qualified}",
+                table=ref.qualified,
+            )

sqlguard_ninja/core/rules/functions.py

@@ -0,0 +1,197 @@
+"""Function-call policy: built-in deny list, optional allowlist mode, and UDF handling."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from sqlguard_ninja.core.findings import Action, Category, Finding, Severity
+from sqlguard_ninja.core.rules.base import RuleContext
+
+# Grouped so that a finding can say *why* a function is dangerous.
+DENIED_FUNCTIONS: dict[str, frozenset[str]] = {
+    "file_or_program_access": frozenset(
+        {
+            "pg_read_file",
+            "pg_read_binary_file",
+            "pg_ls_dir",
+            "pg_stat_file",
+            "pg_ls_logdir",
+            "pg_ls_waldir",
+            "pg_ls_tmpdir",
+            "pg_ls_archive_statusdir",
+            "lo_import",
+            "lo_export",
+            "lo_get",
+            "lo_put",
+            "lo_create",
+            "lo_unlink",
+            "lo_from_bytea",
+            "readfile",
+            "writefile",
+            "edit",
+            "load_extension",
+            "fts3_tokenizer",
+        }
+    ),
+    "remote_or_dynamic_sql": frozenset(
+        {
+            "dblink",
+            "dblink_exec",
+            "dblink_connect",
+            "dblink_connect_u",
+            "dblink_open",
+            "dblink_send_query",
+            "query_to_xml",
+            "query_to_xml_and_xmlschema",
+            "query_to_xmlschema",
+            "cursor_to_xml",
+            "table_to_xml",
+            "table_to_xml_and_xmlschema",
+            "schema_to_xml",
+            "database_to_xml",
+            "database_to_xml_and_xmlschema",
+        }
+    ),
+    "denial_of_service": frozenset(
+        {
+            "pg_sleep",
+            "pg_sleep_for",
+            "pg_sleep_until",
+            "pg_advisory_lock",
+            "pg_advisory_xact_lock",
+            "pg_advisory_lock_shared",
+            "pg_try_advisory_lock",
+            "randomblob",
+            "zeroblob",
+        }
+    ),
+    "administration_or_state_change": frozenset(
+        {
+            "pg_terminate_backend",
+            "pg_cancel_backend",
+            "pg_reload_conf",
+            "pg_rotate_logfile",
+            "set_config",
+            "pg_switch_wal",
+            "pg_create_restore_point",
+            "pg_promote",
+            "pg_logical_emit_message",
+            "pg_notify",
+            "nextval",
+            "setval",
+            "txid_current",
+            "pg_current_xact_id",
+        }
+    ),
+}
+
+RECONNAISSANCE_FUNCTIONS = frozenset(
+    {
+        "version",
+        "current_version",
+        "current_setting",
+        "inet_server_addr",
+        "inet_server_port",
+        "inet_client_addr",
+        "pg_postmaster_start_time",
+        "pg_backend_pid",
+        "pg_has_role",
+        "has_table_privilege",
+        "has_column_privilege",
+        "has_schema_privilege",
+        "has_database_privilege",
+        "has_function_privilege",
+        "sqlite_version",
+        "sqlite_source_id",
+        "sqlite_compileoption_used",
+        "sqlite_compileoption_get",
+    }
+)
+
+DENIED_PREFIXES = ("dblink", "lo_")
+REVIEW_PREFIXES = ("pg_",)
+
+_ALL_DENIED = frozenset().union(*DENIED_FUNCTIONS.values())
+
+
+def _deny_group(name: str) -> str | None:
+    for group, names in DENIED_FUNCTIONS.items():
+        if name in names:
+            return group
+    if name.startswith(DENIED_PREFIXES):
+        return "file_or_program_access"
+    return None
+
+
+class FunctionPolicyRule:
+    """Apply the policy's function rules to every function call in the query."""
+
+    rule_ids = (
+        "function.denied",
+        "function.not_allowlisted",
+        "function.review",
+        "function.unknown",
+    )
+
+    def check(self, ctx: RuleContext) -> Iterator[Finding]:
+        fp = ctx.policy.functions
+        extra_deny = set(fp.deny)
+        exceptions = set(fp.allow)
+        review = set(fp.review)
+        seen: set[str] = set()
+        for func in ctx.analysis.functions:
+            if func.display in seen:
+                continue
+            seen.add(func.display)
+            names = func.names
+            shown = ctx.name("function", func.display)
+
+            if fp.mode == "allowlist":
+                if not names & exceptions:
+                    yield Finding(
+                        rule_id="function.not_allowlisted",
+                        category=Category.FUNCTION,
+                        severity=Severity.MEDIUM,
+                        action=Action.DENY,
+                        message=f"The {shown} is not on the approved function list.",
+                    )
+                    continue
+            elif names & exceptions:
+                continue
+
+            group = next((g for n in names if (g := _deny_group(n))), None)
+            if names & extra_deny or (group is not None and fp.mode == "denylist"):
+                yield Finding(
+                    rule_id="function.denied",
+                    category=Category.FUNCTION,
+                    severity=Severity.CRITICAL,
+                    action=Action.DENY,
+                    message=f"The {shown} is not permitted.",
+                    detail=f"group={group or 'policy_deny'}",
+                    metadata={"group": group or "policy_deny"},
+                )
+                continue
+            if fp.mode == "allowlist":
+                continue
+            if names & review or names & RECONNAISSANCE_FUNCTIONS:
+                yield Finding(
+                    rule_id="function.review",
+                    category=Category.FUNCTION,
+                    severity=Severity.MEDIUM,
+                    action=Action.REVIEW,
+                    message=f"The {shown} reveals server or privilege details and needs review.",
+                )
+                continue
+            if not func.known:
+                if any(n.startswith(REVIEW_PREFIXES) for n in names):
+                    action = Action.REVIEW
+                else:
+                    action = fp.unknown_function_action
+                yield Finding(
+                    rule_id="function.unknown",
+                    category=Category.FUNCTION,
+                    severity=Severity.LOW,
+                    action=action,
+                    message=f"The {shown} is not a recognised built-in function.",
+                    detail="may be a user-defined function; consider functions.mode=allowlist",
+                )