safegres 1.8.0 → 1.11.0

package/README.md

@@ -26,6 +26,15 @@ safegres audit
 
 Per-field overrides (`--host`, `--port`, `--user`, `--password`, `--database`) and a full `--connection <url>` flag are also supported. See `safegres audit --help`.
 
+### Output & verbosity
+
+Pretty output prints the exposure line, score, and the exposed findings. Internal (non-exposed) advisories are collapsed to a one-line count by default so a large database's report stays readable.
+
+- `--summary`, `-q` — print only the exposure line, score/grade, and severity counts (no per-finding lines). Ideal for CI job summaries.
+- `--verbose` — expand the internal advisories instead of collapsing them to a count.
+- `--exposed-only` — drop internal findings entirely.
+- `--format json` / `--format json-pretty` — machine-readable output (always carries every finding).
+
 ## What it checks
 
 | Code | Severity | Direction | Category | Check |
@@ -91,6 +100,54 @@ Some open reads are deliberate — pricing tables, reference data, a public user
 - An open read on any *undeclared* table stays a scored finding — even in a `*_public`-named schema. Naming is never treated as intent; the config declaration is.
 - `safegres doctor` warns about stale `public.read` patterns that no longer match any table.
 
+## Call graph (`--call-graph`)
+
+RLS findings tell you what the *tables* allow. The call graph tells you what the *functions* reach: starting from the exposed entry points (functions the API roles can `EXECUTE`), safegres statically walks each body and lists every **trust boundary** on the way — unscored, because a public `SECURITY DEFINER` calling private functions is the intended pattern (that's how `sign_in` works). The output is a deterministic checklist for human review:
+
+| Code | Boundary |
+|------|----------|
+| CF1 | `SECURITY DEFINER` without a pinned `search_path` (CWE-426) — provable misconfiguration, fix these |
+| CF2 | `SECURITY DEFINER` executable by `anonymous`/PUBLIC — widest blast radius, confirm intent |
+| CG2 | RLS-bypass path — a DEFINER's owner owns (or bypasses RLS on) a table it touches, so RLS does not protect that table on this path |
+| CG3 | Auth-context mutation — a reachable function writes `jwt.claims.*` / `role` |
+| CG1 | Trust hop — execution crosses into a `SECURITY DEFINER` (you are trusting its author's authorization logic) |
+| CG4 | Internal reach — a non-exposed table is reached from a public entry via a DEFINER path |
+| CG5 | Opaque node — dynamic SQL (`EXECUTE`) or an unparseable body; static analysis ends here, audit manually |
+
+```bash
+safegres audit --database mydb --call-graph
+```
+
+```
+call graph — trust boundaries reachable from the exposed surface (unscored; human review)
+  2 entry point(s) → 4 reachable function(s)  |  3 trust hop(s)  1 RLS-bypass  1 auth-context  1 internal-reach  1 opaque
+
+CG2 — RLS-bypass paths (RLS does not protect the table on this path) (1)
+  • fx_cg_private.verify_password → fx_cg_private.users
+      RLS on fx_cg_private.users does not apply on this path — fx_cg_private.verify_password is SECURITY DEFINER running as postgres (BYPASSRLS/superuser)
+      via: fx_cg_public.sign_in → fx_cg_private.verify_password
+```
+
+Bodies are analyzed for `sql` and `plpgsql` functions (via the PL/pgSQL parser); overloads collapse into one node per `schema.name`; unqualified calls resolve to every user function with that name (a conservative over-approximation). JSON output (`--format json`) carries the full graph — nodes, edges, and checklist — sorted stably so it can be snapshotted and diffed in CI.
+
+### Baseline diffing (CI gate for new trust boundaries)
+
+Snapshot the checklist once, commit it, and let CI report anything **new**:
+
+```bash
+safegres audit --write-baseline .safegres-callgraph.json   # snapshot (implies --call-graph)
+safegres audit --baseline .safegres-callgraph.json         # diff: report new/resolved boundaries
+safegres audit --baseline .safegres-callgraph.json --fail-on-new-boundaries   # gate: exit 1 on new
+```
+
+```
+baseline: 1 NEW trust boundary — review and re-baseline to accept:
+  + [CF2] app_public.new_fn
+        SECURITY DEFINER executable by PUBLIC, anonymous — widest blast radius; confirm this is intended
+```
+
+The baseline stores only boundary *identity* (`code` + entry + function + table), so message rewording and path changes between safegres versions never invalidate it. A boundary that disappears is reported as resolved; re-run `--write-baseline` to accept either direction. The diff is also carried in JSON output (`callGraphDiff`).
+
 ## Configuration
 
 safegres is configurable like a linter. Config is discovered by walking up from the current directory: `safegres.config.{ts,js,mjs,cjs}`, `.safegresrc{,.json,.yaml,.yml,.js}`, `safegres.json`, or a `"safegres"` key in package.json (via [confstash](https://github.com/constructive-io/dev-utils/tree/main/packages/confstash)).

package/callgraph/baseline.d.ts

@@ -0,0 +1,28 @@
+import type { CallGraphReport, ChecklistCode, ChecklistItem } from './graph';
+/**
+ * A committed snapshot of the call-graph checklist, used by CI to detect
+ * *new* trust boundaries introduced by a change. Only the identity of each
+ * boundary is stored (code + entry + fn + table) — messages and paths may
+ * be reworded between versions without invalidating the baseline.
+ */
+export interface CallGraphBaseline {
+    version: 1;
+    boundaries: BaselineBoundary[];
+}
+export interface BaselineBoundary {
+    code: ChecklistCode;
+    entry: string;
+    fn: string;
+    table?: string;
+}
+export interface CallGraphDiff {
+    /** Checklist items present now but not in the baseline — require sign-off. */
+    added: ChecklistItem[];
+    /** Baseline boundaries no longer present — resolved or removed. */
+    removed: BaselineBoundary[];
+}
+export declare function boundaryKey(b: BaselineBoundary): string;
+export declare function toBaseline(report: CallGraphReport): CallGraphBaseline;
+export declare function diffCallGraph(report: CallGraphReport, baseline: CallGraphBaseline): CallGraphDiff;
+export declare function parseBaseline(raw: string): CallGraphBaseline;
+export declare function serializeBaseline(baseline: CallGraphBaseline): string;

package/callgraph/baseline.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.boundaryKey = boundaryKey;
+exports.toBaseline = toBaseline;
+exports.diffCallGraph = diffCallGraph;
+exports.parseBaseline = parseBaseline;
+exports.serializeBaseline = serializeBaseline;
+function boundaryKey(b) {
+    return [b.code, b.entry, b.fn, b.table ?? ''].join('|');
+}
+function toBaseline(report) {
+    const seen = new Set();
+    const boundaries = [];
+    for (const item of report.checklist) {
+        const b = {
+            code: item.code,
+            entry: item.entry,
+            fn: item.fn,
+            ...(item.table ? { table: item.table } : {})
+        };
+        const key = boundaryKey(b);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        boundaries.push(b);
+    }
+    boundaries.sort((a, b) => boundaryKey(a).localeCompare(boundaryKey(b)));
+    return { version: 1, boundaries };
+}
+function diffCallGraph(report, baseline) {
+    const baseKeys = new Set(baseline.boundaries.map(boundaryKey));
+    const current = toBaseline(report);
+    const currentKeys = new Set(current.boundaries.map(boundaryKey));
+    const addedKeys = new Set();
+    const added = [];
+    for (const item of report.checklist) {
+        const key = boundaryKey({ code: item.code, entry: item.entry, fn: item.fn, table: item.table });
+        if (baseKeys.has(key) || addedKeys.has(key))
+            continue;
+        addedKeys.add(key);
+        added.push(item);
+    }
+    const removed = baseline.boundaries.filter((b) => !currentKeys.has(boundaryKey(b)));
+    return { added, removed };
+}
+function parseBaseline(raw) {
+    const data = JSON.parse(raw);
+    if (data.version !== 1 || !Array.isArray(data.boundaries)) {
+        throw new Error('invalid call-graph baseline: expected { version: 1, boundaries: [...] }');
+    }
+    return { version: 1, boundaries: data.boundaries };
+}
+function serializeBaseline(baseline) {
+    return JSON.stringify(baseline, null, 2) + '\n';
+}

package/callgraph/extract.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Static body extraction for the call graph.
+ *
+ * Given a function's source, extract the function calls, table references
+ * (read vs write), and auth-context mutations it contains. Dynamic SQL
+ * (`EXECUTE format(...)`) and unparseable bodies are surfaced as `opaque`
+ * rather than silently dropped — static analysis ends there.
+ */
+import type { FunctionSnapshot } from '../pg/functions';
+export interface NameRef {
+    schema?: string;
+    name: string;
+}
+export interface TableRef extends NameRef {
+    write: boolean;
+}
+export interface ExtractedBody {
+    calls: NameRef[];
+    tables: TableRef[];
+    /** GUC names written via `set_config(...)` / `SET`, plus `role` for SET ROLE. */
+    settings: string[];
+    /** True when the body contains dynamic SQL we cannot follow statically. */
+    opaque: boolean;
+    /** Why the body is (partially) opaque, when it is. */
+    opaqueReason?: string;
+}
+export declare function extractBody(fn: FunctionSnapshot): Promise<ExtractedBody>;

package/callgraph/extract.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * Static body extraction for the call graph.
+ *
+ * Given a function's source, extract the function calls, table references
+ * (read vs write), and auth-context mutations it contains. Dynamic SQL
+ * (`EXECUTE format(...)`) and unparseable bodies are surfaced as `opaque`
+ * rather than silently dropped — static analysis ends there.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractBody = extractBody;
+const libpg_query_1 = require("libpg-query");
+const pgsql_parser_1 = require("pgsql-parser");
+const walk_1 = require("../ast/walk");
+const EMPTY = { calls: [], tables: [], settings: [], opaque: false };
+/** Languages whose bodies we can statically analyze. */
+const ANALYZABLE = new Set(['sql', 'plpgsql']);
+async function extractBody(fn) {
+    if (!ANALYZABLE.has(fn.language)) {
+        if (fn.language === 'internal' || fn.language === 'c')
+            return EMPTY;
+        return { ...EMPTY, opaque: true, opaqueReason: `language "${fn.language}" is not statically analyzable` };
+    }
+    if (fn.language === 'sql') {
+        if (!fn.source || fn.source.trim() === '')
+            return EMPTY;
+        return extractFromSql(fn.source, 'statement');
+    }
+    // plpgsql: parse the full CREATE FUNCTION, then analyze every embedded
+    // SQL expression/statement the PL/pgSQL parser hands back.
+    if (!fn.definition)
+        return { ...EMPTY, opaque: true, opaqueReason: 'no function definition available' };
+    let parsed;
+    try {
+        parsed = await (0, libpg_query_1.parsePlPgSQL)(fn.definition);
+    }
+    catch {
+        return { ...EMPTY, opaque: true, opaqueReason: 'PL/pgSQL body failed to parse' };
+    }
+    const out = { calls: [], tables: [], settings: [], opaque: false };
+    const exprs = [];
+    collectPlpgsql(parsed, exprs, out);
+    for (const e of exprs) {
+        // parseMode 0 = full statement; 3 = assignment (`target := expr` or
+        // `target = expr`) — strip the anchored target so the RHS parses. The
+        // RHS may itself contain `:=` (named arguments), so only the leading
+        // target is removed. Anything else is a bare expression.
+        let q = e.query;
+        if (e.parseMode === 3) {
+            q = q.replace(/^\s*[a-zA-Z_"][\w$".]*(\[[^\]]*\])*\s*:?=\s*/, '');
+        }
+        const sql = e.parseMode === 0 ? q : `SELECT ${q}`;
+        const part = await extractFromSql(sql, 'statement');
+        mergeBody(out, part);
+    }
+    return finalize(out);
+}
+/** Walk the PL/pgSQL JSON tree: collect embedded SQL, flag dynamic EXECUTE. */
+function collectPlpgsql(node, exprs, out) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectPlpgsql(item, exprs, out);
+        return;
+    }
+    if (!node || typeof node !== 'object')
+        return;
+    const rec = node;
+    if (rec.PLpgSQL_stmt_dynexecute) {
+        out.opaque = true;
+        out.opaqueReason = 'dynamic SQL (EXECUTE) — cannot follow statically';
+        // Still walk it: the format() expression itself may call functions.
+    }
+    const expr = rec.PLpgSQL_expr;
+    if (expr && typeof expr.query === 'string') {
+        exprs.push({ query: expr.query, parseMode: typeof expr.parseMode === 'number' ? expr.parseMode : 2 });
+    }
+    for (const value of Object.values(rec))
+        collectPlpgsql(value, exprs, out);
+}
+async function extractFromSql(sql, _mode) {
+    let ast;
+    try {
+        ast = await (0, pgsql_parser_1.parse)(sql);
+    }
+    catch {
+        // Individual fragments can legitimately fail (PL/pgSQL variables in
+        // type positions, etc.) — treat as opaque rather than erroring out.
+        return { ...EMPTY, opaque: true, opaqueReason: 'SQL fragment failed to parse' };
+    }
+    const out = { calls: [], tables: [], settings: [], opaque: false };
+    for (const call of (0, walk_1.findAll)(ast, 'FuncCall')) {
+        const ref = (0, walk_1.funcNameParts)(call);
+        if (ref.name === '<unknown>')
+            continue;
+        out.calls.push(ref);
+        if (ref.name === 'set_config' && (!ref.schema || ref.schema === 'pg_catalog')) {
+            const setting = firstStringArg(call);
+            if (setting)
+                out.settings.push(setting);
+        }
+    }
+    // Write targets: the relation of INSERT/UPDATE/DELETE statements.
+    const writeOids = new Set();
+    for (const tag of ['InsertStmt', 'UpdateStmt', 'DeleteStmt']) {
+        for (const stmt of (0, walk_1.findAll)(ast, tag)) {
+            const rel = stmt.relation;
+            if (rel)
+                writeOids.add(rel);
+        }
+    }
+    for (const rv of (0, walk_1.findAll)(ast, 'RangeVar')) {
+        const name = typeof rv.relname === 'string' ? rv.relname : undefined;
+        if (!name)
+            continue;
+        const schema = typeof rv.schemaname === 'string' ? rv.schemaname : undefined;
+        out.tables.push({ schema, name, write: writeOids.has(rv) });
+    }
+    // SET role / SET session_authorization / SET request.jwt… inside SQL bodies.
+    for (const set of (0, walk_1.findAll)(ast, 'VariableSetStmt')) {
+        const name = typeof set.name === 'string' ? set.name : undefined;
+        if (name)
+            out.settings.push(name.toLowerCase());
+    }
+    return finalize(out);
+}
+function firstStringArg(call) {
+    const args = call.args;
+    if (!Array.isArray(args) || args.length === 0)
+        return null;
+    const first = args[0];
+    const aconst = first.A_Const;
+    const sval = aconst?.sval;
+    const v = sval?.sval;
+    return typeof v === 'string' ? v : null;
+}
+function mergeBody(into, from) {
+    into.calls.push(...from.calls);
+    into.tables.push(...from.tables);
+    into.settings.push(...from.settings);
+    if (from.opaque && !into.opaque) {
+        into.opaque = true;
+        into.opaqueReason = from.opaqueReason;
+    }
+}
+function finalize(body) {
+    const callKeys = new Set();
+    const calls = body.calls.filter((c) => {
+        const k = `${c.schema ?? ''}.${c.name}`;
+        if (callKeys.has(k))
+            return false;
+        callKeys.add(k);
+        return true;
+    });
+    const tableKeys = new Map();
+    for (const t of body.tables) {
+        const k = `${t.schema ?? ''}.${t.name}`;
+        const existing = tableKeys.get(k);
+        if (existing)
+            existing.write = existing.write || t.write;
+        else
+            tableKeys.set(k, { ...t });
+    }
+    return {
+        calls,
+        tables: [...tableKeys.values()],
+        settings: [...new Set(body.settings)],
+        opaque: body.opaque,
+        ...(body.opaqueReason ? { opaqueReason: body.opaqueReason } : {})
+    };
+}

package/callgraph/graph.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Call-graph construction and trust-boundary classification.
+ *
+ * Starting from the exposed entry points (functions the API roles can
+ * EXECUTE), walk what those functions transitively call and touch, and emit
+ * an unscored audit checklist of trust boundaries for human review:
+ *
+ *   CG1  trust hop           — execution crosses into a SECURITY DEFINER
+ *   CG2  RLS-bypass path     — a DEFINER touches a table whose RLS its owner bypasses
+ *   CG3  auth-context change — a reachable function mutates jwt claims / role
+ *   CG4  internal reach      — a non-exposed table is reached via a DEFINER hop
+ *   CG5  opaque node         — dynamic SQL / unparseable body; audit manually
+ *
+ * Plus two provable misconfigurations:
+ *
+ *   CF1  SECURITY DEFINER without a pinned search_path (CWE-426)
+ *   CF2  SECURITY DEFINER executable by anonymous / PUBLIC
+ */
+import type { FunctionSnapshot } from '../pg/functions';
+import type { TableSnapshot } from '../pg/introspect';
+export interface CallGraphOptions {
+    functions: FunctionSnapshot[];
+    tables: TableSnapshot[];
+    /** Exposed schemas; when undefined the exposure surface is unknown. */
+    exposedSchemas?: string[];
+    /** Roles the API connects as. EXECUTE for any of these (or PUBLIC) marks an entry point. */
+    apiRoles: string[];
+}
+export interface CallGraphNode {
+    id: string;
+    schema: string;
+    name: string;
+    securityDefiner: boolean;
+    owner: string;
+    ownerBypassesRls: boolean;
+    searchPathPinned: boolean;
+    language: string;
+    opaque: boolean;
+    opaqueReason?: string;
+    /** Auth-context settings this function writes (jwt claims, role, …). */
+    authSettings: string[];
+    /** Entry-point roles when this node is an entry (EXECUTE-granted API roles). */
+    entryRoles?: string[];
+}
+export interface CallGraphEdge {
+    from: string;
+    to: string;
+    kind: 'call' | 'read' | 'write';
+}
+export type ChecklistCode = 'CG1' | 'CG2' | 'CG3' | 'CG4' | 'CG5' | 'CF1' | 'CF2';
+export interface ChecklistItem {
+    code: ChecklistCode;
+    /** Entry point this boundary is reachable from. */
+    entry: string;
+    /** Call path from the entry to the flagged node, entry first. */
+    path: string[];
+    /** The flagged function. */
+    fn: string;
+    /** The touched table, for CG2/CG4. */
+    table?: string;
+    message: string;
+}
+export interface CallGraphReport {
+    entries: Array<{
+        fn: string;
+        roles: string[];
+        securityDefiner: boolean;
+    }>;
+    nodes: CallGraphNode[];
+    edges: CallGraphEdge[];
+    checklist: ChecklistItem[];
+    stats: {
+        entryPoints: number;
+        reachableFunctions: number;
+        trustHops: number;
+        rlsBypassPaths: number;
+        authContextMutations: number;
+        internalReach: number;
+        opaqueNodes: number;
+    };
+}
+export declare function buildCallGraph(options: CallGraphOptions): Promise<CallGraphReport>;