pgrls 0.0.1__tar.gz

pgrls-0.0.1/.gitignore

@@ -0,0 +1,20 @@
+.claude/
+.idea/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+.tox/
+.mypy_cache/
+.ruff_cache/

pgrls-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry Maranik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pgrls-0.0.1/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: pgrls
+Version: 0.0.1
+Summary: Framework-agnostic linter and testing toolkit for Postgres Row-Level Security.
+Project-URL: Homepage, https://github.com/pgrls/pgrls
+Project-URL: Issues, https://github.com/pgrls/pgrls/issues
+Author: Dmitry Maranik
+License: MIT License
+        
+        Copyright (c) 2026 Dmitry Maranik
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: linter,postgres,postgresql,rls,row-level-security,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: psycopg[binary]>=3.1
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hatchling>=1.21; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: testcontainers[postgres]>=4.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pgrls
+
+Framework-agnostic linter and testing toolkit for Postgres Row-Level Security.
+
+> **Status: 0.0.1** — first lint rule (SEC001) shipped. The full rule catalog and the `test` / `diff` commands are on the roadmap below.
+
+## Install
+
+```bash
+pip install pgrls
+```
+
+Requires Python 3.11+.
+
+## Usage
+
+Point `pgrls` at any Postgres database:
+
+```bash
+export DATABASE_URL="postgres://user:pass@host:5432/db"
+pgrls lint
+```
+
+Or pass the URL directly:
+
+```bash
+pgrls lint --database-url "postgres://user:pass@host:5432/db"
+```
+
+Limit the scan to specific schemas:
+
+```bash
+pgrls lint --schemas public,tenant
+```
+
+Point at a non-default config file, or pick an output format:
+
+```bash
+pgrls lint --config ./config/pgrls.toml --format text
+```
+
+### Example output
+
+```
+  ERROR  SEC001  public.users
+         Table public.users does not have row-level security enabled.
+         Add ENABLE ROW LEVEL SECURITY or include the table in
+         [lint.rules.SEC001].allowlist if it is a public reference table.
+
+pgrls: 1 error.
+```
+
+Exit code is `1` when any violation meets or exceeds `fail_on` (default `warning`).
+
+## Configuration
+
+Drop a `pgrls.toml` next to your project. See `pgrls.example.toml` in the repo for a fully commented version.
+
+```toml
+[database]
+url = "$DATABASE_URL"
+schemas = ["public"]
+
+[lint]
+disable = []
+fail_on = "warning"
+
+[lint.rules.SEC001]
+allowlist = ["countries", "currencies"]
+```
+
+## Roadmap
+
+- **More lint rules.** Full SEC / PERF / HYG catalog, including the marquee SEC004 (inverted auth check / Lovable CVE pattern). JSON, SARIF, and Markdown output. Polished error messages.
+- **`pgrls test`.** Code-first RLS test DSL for Python, TypeScript, and Go.
+- **`pgrls diff`.** Semantic policy diff between branches with DANGEROUS / BREAKING / SAFE classification.
+
+## License
+
+MIT — see `LICENSE`.

pgrls-0.0.1/README.md

@@ -0,0 +1,80 @@
+# pgrls
+
+Framework-agnostic linter and testing toolkit for Postgres Row-Level Security.
+
+> **Status: 0.0.1** — first lint rule (SEC001) shipped. The full rule catalog and the `test` / `diff` commands are on the roadmap below.
+
+## Install
+
+```bash
+pip install pgrls
+```
+
+Requires Python 3.11+.
+
+## Usage
+
+Point `pgrls` at any Postgres database:
+
+```bash
+export DATABASE_URL="postgres://user:pass@host:5432/db"
+pgrls lint
+```
+
+Or pass the URL directly:
+
+```bash
+pgrls lint --database-url "postgres://user:pass@host:5432/db"
+```
+
+Limit the scan to specific schemas:
+
+```bash
+pgrls lint --schemas public,tenant
+```
+
+Point at a non-default config file, or pick an output format:
+
+```bash
+pgrls lint --config ./config/pgrls.toml --format text
+```
+
+### Example output
+
+```
+  ERROR  SEC001  public.users
+         Table public.users does not have row-level security enabled.
+         Add ENABLE ROW LEVEL SECURITY or include the table in
+         [lint.rules.SEC001].allowlist if it is a public reference table.
+
+pgrls: 1 error.
+```
+
+Exit code is `1` when any violation meets or exceeds `fail_on` (default `warning`).
+
+## Configuration
+
+Drop a `pgrls.toml` next to your project. See `pgrls.example.toml` in the repo for a fully commented version.
+
+```toml
+[database]
+url = "$DATABASE_URL"
+schemas = ["public"]
+
+[lint]
+disable = []
+fail_on = "warning"
+
+[lint.rules.SEC001]
+allowlist = ["countries", "currencies"]
+```
+
+## Roadmap
+
+- **More lint rules.** Full SEC / PERF / HYG catalog, including the marquee SEC004 (inverted auth check / Lovable CVE pattern). JSON, SARIF, and Markdown output. Polished error messages.
+- **`pgrls test`.** Code-first RLS test DSL for Python, TypeScript, and Go.
+- **`pgrls diff`.** Semantic policy diff between branches with DANGEROUS / BREAKING / SAFE classification.
+
+## License
+
+MIT — see `LICENSE`.

pgrls-0.0.1/pgrls.example.toml

@@ -0,0 +1,17 @@
+# Copy this file to `pgrls.toml` and adjust.
+# Environment variables can be referenced as `$VAR` or `${VAR}`.
+
+[database]
+url = "$DATABASE_URL"
+schemas = ["public"]
+
+[lint]
+# Rule IDs to skip entirely.
+disable = []
+# Severity that triggers a nonzero exit code: "error" | "warning" | "info".
+fail_on = "warning"
+
+# Per-rule options.
+[lint.rules.SEC001]
+# Tables where missing RLS is acceptable. Entries can be unqualified (countries) or qualified (tenant.things).
+allowlist = []

pgrls-0.0.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pgrls"
+version = "0.0.1"
+description = "Framework-agnostic linter and testing toolkit for Postgres Row-Level Security."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [{ name = "Dmitry Maranik" }]
+keywords = ["postgres", "postgresql", "rls", "row-level-security", "linter", "security"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Security",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "click>=8.1",
+    "psycopg[binary]>=3.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "hatchling>=1.21",
+    "pytest>=8.0",
+    "testcontainers[postgres]>=4.0",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.scripts]
+pgrls = "pgrls.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/pgrls/pgrls"
+Issues = "https://github.com/pgrls/pgrls/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pgrls"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-markers", "--strict-config"]

pgrls-0.0.1/src/pgrls/__init__.py

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

pgrls-0.0.1/src/pgrls/cli.py

@@ -0,0 +1,139 @@
+"""Click entry point for the `pgrls` console script."""
+from __future__ import annotations
+
+import sys
+from typing import cast
+
+import click
+import psycopg
+
+from pgrls import __version__
+from pgrls.config import Config, ConfigError, load_config
+from pgrls.formatters import SUPPORTED_FORMATS, format_violations
+from pgrls.introspect import introspect
+from pgrls.model import Schema
+from pgrls.rules import default_registry
+from pgrls.violations import Severity, Violation, is_at_or_above
+
+
+@click.group()
+@click.version_option(__version__, prog_name="pgrls")
+def main() -> None:
+    """Framework-agnostic linter and testing toolkit for Postgres Row-Level Security."""
+
+
+@main.command()
+@click.option(
+    "--database-url",
+    envvar="DATABASE_URL",
+    help="Postgres connection string. Falls back to $DATABASE_URL.",
+)
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help="Path to pgrls.toml. Defaults to ./pgrls.toml if present.",
+)
+@click.option(
+    "--schemas",
+    default=None,
+    help="Comma-separated schemas to lint (overrides config).",
+)
+@click.option(
+    "--fail-on",
+    type=click.Choice(["error", "warning", "info"], case_sensitive=False),
+    default=None,
+    help="Severity threshold that triggers nonzero exit.",
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(SUPPORTED_FORMATS, case_sensitive=False),
+    default="text",
+    show_default=True,
+    help="Output format.",
+)
+def lint(
+    database_url: str | None,
+    config_path: str | None,
+    schemas: str | None,
+    fail_on: str | None,
+    output_format: str,
+) -> None:
+    """Lint Postgres RLS policies for security and hygiene issues."""
+    try:
+        config = load_config(config_path)
+    except ConfigError as exc:
+        raise click.ClickException(str(exc))
+
+    effective = _merge_overrides(
+        config,
+        database_url=database_url,
+        schemas_csv=schemas,
+        fail_on=fail_on,
+    )
+
+    if effective.database_url is None:
+        raise click.ClickException(
+            "No database connection: pass --database-url or set DATABASE_URL."
+        )
+
+    try:
+        with psycopg.connect(effective.database_url) as conn:
+            schema = introspect(conn, schemas=effective.schemas)
+    except psycopg.Error as exc:
+        raise click.ClickException(f"Database error: {exc}")
+    except ValueError as exc:
+        raise click.ClickException(str(exc))
+
+    try:
+        violations = _run_rules(schema, config=effective)
+    except (TypeError, ValueError) as exc:
+        raise click.ClickException(str(exc))
+
+    click.echo(format_violations(violations, format=output_format), nl=False)
+
+    if _should_fail(violations, threshold=effective.fail_on):
+        sys.exit(1)
+
+
+def _merge_overrides(
+    config: Config,
+    *,
+    database_url: str | None,
+    schemas_csv: str | None,
+    fail_on: str | None,
+) -> Config:
+    if schemas_csv:
+        schemas = [s.strip() for s in schemas_csv.split(",") if s.strip()]
+        if not schemas:
+            raise click.ClickException(
+                f"--schemas {schemas_csv!r} produced an empty schema list. "
+                "Check for trailing commas or whitespace-only values."
+            )
+    else:
+        schemas = config.schemas
+    effective_fail_on: Severity = (
+        cast(Severity, fail_on) if fail_on is not None else config.fail_on
+    )
+    return Config(
+        database_url=database_url or config.database_url,
+        schemas=schemas,
+        disable=list(config.disable),
+        fail_on=effective_fail_on,
+        rule_options=dict(config.rule_options),
+    )
+
+
+def _run_rules(schema: Schema, *, config: Config) -> list[Violation]:
+    registry = default_registry()
+    rules = registry.enabled(disabled_ids=config.disable)
+    out: list[Violation] = []
+    for rule in rules:
+        out.extend(rule.check(schema, config.rule_options.get(rule.id, {})))
+    return out
+
+
+def _should_fail(violations: list[Violation], *, threshold: Severity) -> bool:
+    return any(is_at_or_above(v.severity, threshold) for v in violations)

pgrls-0.0.1/src/pgrls/config.py

@@ -0,0 +1,128 @@
+"""Load `pgrls.toml`, interpolate environment variables, return a typed Config."""
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+Severity = Literal["error", "warning", "info"]
+_VALID_FAIL_ON: tuple[Severity, ...] = ("error", "warning", "info")
+_ENV_PATTERN = re.compile(r"\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))")
+
+
+class ConfigError(Exception):
+    """Raised when the user's config file is invalid or references missing env vars."""
+
+
+@dataclass(frozen=True)
+class Config:
+    """Loaded configuration.
+
+    `frozen=True` prevents field reassignment but does NOT freeze the list and
+    dict fields. Callers must treat `schemas`, `disable`, and `rule_options` as
+    read-only — do not mutate them in place.
+    """
+
+    database_url: str | None = None
+    schemas: list[str] = field(default_factory=lambda: ["public"])
+    disable: list[str] = field(default_factory=list)
+    fail_on: Severity = "warning"
+    rule_options: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+
+def load_config(path: Path | str | None) -> Config:
+    """Load config from `path`, or `./pgrls.toml` if `path` is None and the file exists.
+
+    Returns a default Config when no file is found.
+    """
+    resolved = _resolve_path(path)
+    if resolved is None:
+        return Config()
+
+    raw = _read_toml(resolved)
+    return _build_config(raw)
+
+
+def _resolve_path(path: Path | str | None) -> Path | None:
+    if path is not None:
+        p = Path(path)
+        if not p.is_file():
+            raise ConfigError(f"Config file not found: {p}")
+        return p
+    default = Path.cwd() / "pgrls.toml"
+    return default if default.is_file() else None
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    try:
+        with path.open("rb") as fh:
+            return tomllib.load(fh)
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"Invalid TOML in {path}: {exc}") from exc
+    except OSError as exc:
+        raise ConfigError(f"Cannot read config {path}: {exc}") from exc
+
+
+def _build_config(raw: dict[str, Any]) -> Config:
+    database = raw.get("database", {})
+    if not isinstance(database, dict):
+        raise ConfigError("[database] must be a table")
+    lint = raw.get("lint", {})
+    if not isinstance(lint, dict):
+        raise ConfigError("[lint] must be a table")
+
+    url_raw = database.get("url")
+    if url_raw is None:
+        database_url = None
+    elif isinstance(url_raw, str):
+        database_url = _interpolate_env(url_raw)
+    else:
+        raise ConfigError(
+            f"[database].url must be a string, got {type(url_raw).__name__}"
+        )
+
+    schemas = database.get("schemas", ["public"])
+    if not isinstance(schemas, list) or not all(isinstance(s, str) for s in schemas):
+        raise ConfigError("[database].schemas must be a list of strings")
+
+    disable = lint.get("disable", [])
+    if not isinstance(disable, list) or not all(isinstance(s, str) for s in disable):
+        raise ConfigError("[lint].disable must be a list of rule-id strings")
+
+    fail_on = lint.get("fail_on", "warning")
+    if fail_on not in _VALID_FAIL_ON:
+        raise ConfigError(
+            f"[lint].fail_on must be one of {_VALID_FAIL_ON}, got {fail_on!r}"
+        )
+
+    rules_raw = lint.get("rules", {})
+    if not isinstance(rules_raw, dict):
+        raise ConfigError("[lint.rules] must be a table")
+    rule_options: dict[str, dict[str, Any]] = {}
+    for rule_id, opts in rules_raw.items():
+        if not isinstance(opts, dict):
+            raise ConfigError(f"[lint.rules.{rule_id}] must be a table")
+        rule_options[rule_id] = dict(opts)
+
+    return Config(
+        database_url=database_url,
+        schemas=list(schemas),
+        disable=list(disable),
+        fail_on=fail_on,
+        rule_options=rule_options,
+    )
+
+
+def _interpolate_env(value: str) -> str:
+    """Replace `$VAR` and `${VAR}` with environment values. Missing vars raise."""
+
+    def replace(match: re.Match[str]) -> str:
+        name = match.group(1) or match.group(2)
+        if name not in os.environ:
+            raise ConfigError(f"Environment variable {name!r} is not set")
+        return os.environ[name]
+
+    return _ENV_PATTERN.sub(replace, value)

pgrls-0.0.1/src/pgrls/formatters/__init__.py

@@ -0,0 +1,26 @@
+"""Output formatters. Currently only `text` ships in v0.0.1.
+
+JSON, SARIF, and Markdown formats are planned for a future release. Adding a
+format = creating a sibling module and wiring it into `_FORMATTERS` here.
+"""
+from __future__ import annotations
+
+from typing import Callable
+
+from pgrls.formatters.text import format_text
+from pgrls.violations import Violation
+
+_FORMATTERS: dict[str, Callable[[list[Violation]], str]] = {
+    "text": format_text,
+}
+
+SUPPORTED_FORMATS: tuple[str, ...] = tuple(_FORMATTERS.keys())
+
+
+def format_violations(violations: list[Violation], *, format: str) -> str:
+    if format not in _FORMATTERS:
+        raise ValueError(
+            f"Unknown output format {format!r}. "
+            f"Supported: {', '.join(SUPPORTED_FORMATS)}"
+        )
+    return _FORMATTERS[format](violations)

pgrls-0.0.1/src/pgrls/formatters/text.py

@@ -0,0 +1,36 @@
+"""Human-readable text output."""
+from __future__ import annotations
+
+from collections import Counter
+
+from pgrls.violations import Severity, Violation
+
+_SEVERITY_LABEL: dict[Severity, str] = {
+    "error": "ERROR",
+    "warning": "WARN ",
+    "info": "INFO ",
+}
+
+
+def format_text(violations: list[Violation]) -> str:
+    if not violations:
+        return "pgrls: no issues found.\n"
+
+    lines: list[str] = []
+    for v in violations:
+        loc = v.location or "<schema>"
+        lines.append(
+            f"  {_SEVERITY_LABEL[v.severity]}  {v.rule_id}  {loc}\n"
+            f"         {v.message}"
+        )
+
+    counts: Counter[Severity] = Counter(v.severity for v in violations)
+    parts: list[str] = []
+    for sev in ("error", "warning", "info"):
+        n = counts.get(sev, 0)  # type: ignore[arg-type]
+        if n:
+            parts.append(f"{n} {sev}{'s' if n != 1 else ''}")
+    summary = ", ".join(parts) or "0 issues"
+
+    body = "\n\n".join(lines)
+    return f"{body}\n\npgrls: {summary}.\n"