safegres 1.18.0 → 1.19.0

package/README.md

@@ -143,11 +143,19 @@ family, **not** the dimension: `P1`/`P1b` are performance, `P5` is security.
 | L4 | info | neutral | **Dead schema `USAGE`** — reaches no relation and no function |
 | L5 | info | fail-open | An untrusted role reaches an **RLS-off table** via PUBLIC/inheritance † |
 | L6 | info | neutral | **Unaddressable grant** — an API role holds privileges on a relation its API cannot name ‡ |
-| L8 | info | fail-open | **DEFINER view bypass** — an untrusted role reads a base relation as the view's owner † |
+| L8 | info | fail-open | **DEFINER view bypass** — an untrusted role reads a base relation, and named columns of it, as the view's owner † |
 | L9 | info | fail-open | **DEFINER view write** — an auto-updatable definer view writes a base relation as its owner † |
 | L10 | info | fail-open | **Rewrite-rule bypass** — a rule on a view writes a relation as the view's owner, `security_invoker` notwithstanding † |
 | L11 | info | fail-open | **Materialized-view snapshot** — stored rows serve an untrusted role what the base relation's grants and policies would not † |
 | L12 | info | fail-open | **Non-barrier filtering view** — a view is an untrusted role's only path to a relation, but its row filter is not a boundary † |
+| L13 | info | fail-open | **Column-level grant** — an untrusted role reaches a relation through `pg_attribute.attacl`, which no relation ACL shows † |
+| L14 | info | neutral | **Unaudited base relation** — a definer view reads a relation in a schema the audit never introspected † |
+| L15 | info | neutral | **Unreadable body** — an untrusted role reaches through a definer view or function whose body the analysis could not follow † |
+| L16 | info | fail-open | **Sequence privilege** — an untrusted role can advance or read a sequence, which no policy filters † |
+| L17 | info | fail-open | **Foreign-table grant** — an untrusted role reaches a relation that cannot carry RLS at all † |
+| L18 | info | fail-open | **Writable filtering view without `WITH CHECK OPTION`** — an untrusted role writes rows the view's own filter excludes † |
+| L19 | info | fail-open | **Definer-function reach** — an untrusted role touches a relation by executing a `SECURITY DEFINER` function, which runs as its owner † |
+| L20 | info | fail-open | **`INSTEAD OF` trigger write** — a write against a view becomes a trigger function's body, and a definer one lands it as the function's owner † |
 | W1 | medium | — | **No exposure surface configured** — whole database assumed reachable, score capped |
 
 † R1/R2/L5 are no-ops until you name the untrusted roles:
@@ -157,6 +165,13 @@ untrusted-role model; the `safegres:constructive` preset configures them for `an
 ‡ L6 needs an adapter that can compute [API reach](#api-reach--the-relations-the-api-can-actually-name);
 without one nothing is unaddressable and it never fires.
 
+**Exposure is asked per subject.** A relation finding is exposed when the API can address the
+relation. A *routine* finding — the convention rules, L19, L20 — is exposed when an untrusted role
+can **call the function**: `USAGE` on its schema and `EXECUTE` on the function, directly, by
+inheritance, or through Postgres's default `EXECUTE TO PUBLIC`. Grading a definer function by the
+schema it sits in is not conservative, it is wrong in the dangerous direction: the function is
+private precisely so that calling it is the only way in.
+
 **Direction is the load-bearing idea.** `fail-open` findings are exposure — the untrusted side
 reaches more than intended. `fail-closed` findings are *denied by Postgres at runtime*: an
 availability and hygiene concern, not a leak. They contribute **zero** to the score by default
@@ -416,6 +431,21 @@ deploys it into an ephemeral one:
       - run: npx safegres audit   # or: "audit": "safegres lint" in package.json
 ```
 
+Or the first-party action, which installs the CLI, runs that config, and turns the report into a
+job summary, annotations and a sticky PR comment:
+
+```yaml
+      - uses: constructive-io/constructive/packages/safegres@main
+        with:
+          out: safegres-reports
+          comment: true          # sticky PR comment (needs pull-requests: write)
+          upload-sarif: true     # code scanning (needs security-events: write)
+```
+
+It exposes `security-score`, `security-grade` and `perf-score` as step outputs — on a failing run
+too, which is when they get read. Everything else stays in the config file; see
+**[docs/reporting.md](https://github.com/constructive-io/constructive/blob/main/packages/safegres/docs/reporting.md#the-action)**.
+
 `outputs.dir` writes `safegres.json`, `safegres.md` and `safegres.sarif` into one directory — name
 an individual file (`outputs.json`) only when the name matters. Directories are created as needed,
 and a flag still wins over the file for a one-off run (`safegres audit --out reports`). Naming a
@@ -499,9 +529,11 @@ is simply the honest statement that local configuration participated.
 ## The evaluation corpus
 
 A sealed score says the ruler did not move. It does not say the ruler is right. That is what the
-corpus in [`corpus/`](corpus/README.md) is for: ~20 small schemas, each with one deliberate flaw
-and a written-down answer — the findings a correct audit must produce, the false positives it must
-not, and the one-sentence fix.
+corpus in [`corpus/`](corpus/README.md) is for: small schemas, each with one deliberate flaw and a
+written-down answer — the findings a correct audit must produce, the false positives it must not,
+and the one-sentence fix. Many come in pairs: 18 cases pin what must *not* fire, and six of those
+are the earlier case with its flaw fixed — an answer key consisting entirely of silence and a score
+of 100, because a rule that survives its own fix is worse than a rule that never existed.
 
 `safegres eval` is the whole loop in one command: it deploys each case into the connected
 database, audits it under a sealed preset, grades the report against the answer key, drops the
@@ -513,7 +545,7 @@ $ safegres eval --database scratch
   PASS  17-foreign-key-without-index     perf    71.2 (C )  X1
   FAIL  18-policy-column-unindexed       perf     100 (A+)  missed X2
 
-25/26 cases passed · recall 98% · precision 100%
+41/42 cases passed · recall 98% · precision 100%
 ```
 
 | Flag | |
@@ -569,7 +601,7 @@ Precedence: **CLI > project config > preset > built-in defaults**.
     { "tables": ["app_public.audit_*"], "rules": { "A2": "off" } }
   ],
   "perf": { "enabled": true, "ignore": ["app_public.audit_*"], "rules": { "X6": "off" } },
-  "scoring": { "densityK": 0.17, "unknownExposureCap": 80 },
+  "scoring": { "densityK": 0.17, "maxRuleDensity": 0.5, "unknownExposureCap": 80 },
   "failOn": { "grade": "B", "perfGrade": "B" }
 }
 ```
@@ -636,6 +668,36 @@ Presets **retune**, they don't delete: a rule that doesn't apply to a stack is d
 (zero weight, so the score is unchanged) rather than switched off, so it stays in the report and
 stays re-tunable. `minimal` is the deliberate exception — being a smoke check is its whole job.
 
+`extends` also takes a **path**, which is how a repository with more than one audit job keeps one
+copy of its rules. The gated PR job and the nightly advisory run against a deployed database
+differ by their gates and their baseline, not by their 19-entry `public.read` list:
+
+```jsonc
+// ci/nightly/.safegresrc.json
+{ "extends": "../../safegres.base.json",
+  "perf":    { "baseline": "ci/nightly/perf.json" },
+  "failOn":  { "grade": "D" } }
+```
+
+A path in an inherited file resolves against **the file that wrote it**, so a base file's
+`"baseline": "ci/perf.json"` keeps meaning the base file's `ci/`, whichever job inherits it —
+the same rule as a discovered config, applied per key. Objects merge per key and arrays replace,
+except `overrides`, which is a list of scoped exceptions and so unions across the chain:
+inheriting a config can't silently drop the exceptions that came with it. `--sealed` reaches none
+of this — it does no discovery at all, so there is no file to extend from.
+
+The file is **validated on load**, against a schema derived from the same declaration the editor
+completes against — an unknown key is an error naming the key it thinks you meant, not a silent
+no-op, because `"failon": { "grade": "B" }` otherwise reads as a passing build rather than as a
+typo. Point an editor at the schema for completion and inline documentation:
+
+```jsonc
+{ "$schema": "https://raw.githubusercontent.com/constructive-io/constructive/main/packages/safegres/schema/safegres.schema.json" }
+```
+
+It also ships in the package (`safegres/schema/safegres.schema.json`), and
+`safegres print-config --schema` writes it to stdout for an offline copy.
+
 CLI: `--config <path>`, `--preset <name>`, `--rule CODE=off|severity` (repeatable).
 
 ## Scoring
@@ -655,10 +717,62 @@ exposed tables lands at a C). Non-exposed findings score 0; fail-closed findings
 the grade at C (`scoring.floorOnCritical`). Grades: A+ 97 · A 90 · B 80 · C 65 · D 50 · F below.
 The legacy flat-deduction model is `scoring.model: "weighted"`.
 
+Two corrections keep a rule's **shape** out of the arithmetic, because a rule's fan-out is a
+property of how it reports, not of how much risk it found.
+
+- **Points are charged per unit of repair.** A rule that emits one finding per (relation ×
+  function) pair — L19 does, and on one real database that is 853 findings over 166 functions —
+  costs what fixing it costs: 166 revokes. The finding count is unchanged in the report; the
+  deduction reads `−664 (×853 → 166 fixes)`.
+- **No single rule can decide the grade.** Each rule's contribution is capped at
+  `scoring.maxRuleDensity` (default 0.5) of the points that would score an F alone, so one rule
+  at its ceiling costs two grade bands and an F still takes breadth. `false` disables it.
+
 Every report carries its own arithmetic: per-rule points, grade, and the **payoff** — how far the
 score would move if that rule's findings went away. Gate with `--fail-on <severity>`,
 `--fail-on-score <n>`, `--fail-on-grade <g>` and their `--fail-on-perf-*` counterparts.
 
+### Scorecards: one report, several questions
+
+"How secure is this database" is not one question, and a single grade answers it for at most one
+reader. A platform team gates on what an unauthenticated caller reaches; an application team gates
+on house style; a reviewer wants the number no preset softened. A **scorecard** is that question
+written down — a selector over the findings, plus the weighting to grade what it selects:
+
+```jsonc
+{
+  "scorecards": {
+    "anon-surface": {
+      "description": "What an unauthenticated caller reaches.",
+      "select": { "roles": ["anonymous"], "direction": "fail-open", "exposure": "all" },
+      "perRuleWeights": { "L19": 10 },
+      "floorOnCritical": "C"
+    },
+    "sql-conventions": {
+      "select": { "rules": ["C*"], "exposure": "all", "denominator": "all" }
+    }
+  },
+  "failOn": { "scorecards": { "anon-surface": { "grade": "A" } } }
+}
+```
+
+Selectors narrow on `rules` (with `C*` wildcards) and `exclude`, `dimension`, `roles`, `planes`,
+`schemas`, `direction`, `minSeverity`, `exposure`, `acknowledged`, `severities` and `denominator`.
+Every scoring key is available per card, and `failOn.scorecards` gates on the one that matters to
+you rather than on somebody else's headline.
+
+Two cards always run and cannot be redefined into something flattering:
+
+- **`default`** — the Safegres score: the headline, exposure-scoped and preset-tuned, i.e. graded
+  the way you actually use the database. Naming it in the config cannot move it.
+- **`raw`** — every finding at its *declared* (registry) severity, exposure ignored,
+  acknowledgements included, fail-closed findings weighted like anything else. Not flattering, and
+  not meant to be: it is the number that is comparable between two databases and that no
+  configuration talked down.
+
+A scorecard decides what a number is *about* — never what is reported. `report.findings` is always
+the complete set, so the JSON is the raw data and the scores are queries over it.
+
 ## Commands
 
 ```bash

package/callgraph/extract.d.ts

@@ -40,8 +40,29 @@ export interface ExtractedBody {
     opaque: boolean;
     /** Why the body is (partially) opaque, when it is. */
     opaqueReason?: string;
+    /**
+     * The body executes SQL this analysis cannot see, *alongside* references it
+     * could read: `calls`, `tables` and `settings` are correct but incomplete.
+     *
+     * This is the distinction {@link opaque} cannot make. `opaque` says the
+     * whole body is unknown and its references must be discarded; `tainted`
+     * says what was read is real and what was missed is unknowable, which is
+     * what a reach model needs in order to report the gap instead of the view
+     * disappearing from the analysis altogether.
+     */
+    tainted?: string;
 }
 export declare function extractBody(fn: FunctionSnapshot): Promise<ExtractedBody>;
+/**
+ * {@link extractAccess} asked of a whole function rather than one statement:
+ * every relation the body touches, with the privilege the touch exercises.
+ *
+ * This is what a SECURITY DEFINER function's reach is made of — the body runs
+ * as the owner, so each `INSERT INTO t` in it is an INSERT on `t` that the
+ * caller never needed a grant for. A body that cannot be read is `opaque`,
+ * and an opaque body's access list is a fragment its caller must discard.
+ */
+export declare function extractFunctionAccess(fn: FunctionSnapshot): Promise<ExtractedAccess>;
 /**
  * The same extraction over a standalone SQL statement — a view body, a policy
  * predicate, anything that is already plain SQL rather than a function.

package/callgraph/extract.js

@@ -12,6 +12,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractBody = extractBody;
+exports.extractFunctionAccess = extractFunctionAccess;
 exports.extractQuery = extractQuery;
 exports.extractAccess = extractAccess;
 exports.bodyFiltersRows = bodyFiltersRows;
@@ -19,6 +20,12 @@ 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 };
+/**
+ * Functions that run SQL of their own. The relations they touch are in a
+ * string argument, not in this AST, so a body calling one has a relation set
+ * that is a lower bound rather than an answer.
+ */
+const SQL_EXECUTING = new Set(['query_to_xml', 'dblink', 'dblink_exec', 'dblink_send_query']);
 /** Languages whose bodies we can statically analyze. */
 const ANALYZABLE = new Set(['sql', 'plpgsql']);
 async function extractBody(fn) {
@@ -34,19 +41,37 @@ async function extractBody(fn) {
     }
     // plpgsql: parse the full CREATE FUNCTION, then analyze every embedded
     // SQL expression/statement the PL/pgSQL parser hands back.
+    const embedded = await plpgsqlStatements(fn);
+    if ('opaqueReason' in embedded) {
+        return { ...EMPTY, opaque: true, opaqueReason: embedded.opaqueReason };
+    }
+    const out = { calls: [], tables: [], settings: [], opaque: false, ...embedded.flags };
+    for (const sql of embedded.statements)
+        mergeBody(out, await extractQuery(sql));
+    return finalize(out);
+}
+/**
+ * The SQL a PL/pgSQL body embeds, as statements ready to parse, plus whether
+ * the body also runs SQL nothing can see (`EXECUTE`).
+ *
+ * Both body walkers need this and they need it identically — the read/write
+ * one for the call graph, the per-privilege one for the reach model — so the
+ * PL/pgSQL half is factored out rather than written twice.
+ */
+async function plpgsqlStatements(fn) {
     if (!fn.definition)
-        return { ...EMPTY, opaque: true, opaqueReason: 'no function definition available' };
+        return { 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' };
+        return { opaqueReason: 'PL/pgSQL body failed to parse' };
     }
-    const out = { calls: [], tables: [], settings: [], opaque: false };
+    const flags = { calls: [], tables: [], settings: [], opaque: false };
     const exprs = [];
-    collectPlpgsql(parsed, exprs, out);
-    for (const e of exprs) {
+    collectPlpgsql(parsed, exprs, flags);
+    const statements = exprs.map((e) => {
         // 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
@@ -55,11 +80,60 @@ async function extractBody(fn) {
         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 extractQuery(sql);
-        mergeBody(out, part);
+        return e.parseMode === 0 ? q : `SELECT ${q}`;
+    });
+    return {
+        statements,
+        flags: { opaque: flags.opaque, ...(flags.opaqueReason ? { opaqueReason: flags.opaqueReason } : {}) }
+    };
+}
+/**
+ * {@link extractAccess} asked of a whole function rather than one statement:
+ * every relation the body touches, with the privilege the touch exercises.
+ *
+ * This is what a SECURITY DEFINER function's reach is made of — the body runs
+ * as the owner, so each `INSERT INTO t` in it is an INSERT on `t` that the
+ * caller never needed a grant for. A body that cannot be read is `opaque`,
+ * and an opaque body's access list is a fragment its caller must discard.
+ */
+async function extractFunctionAccess(fn) {
+    if (!ANALYZABLE.has(fn.language)) {
+        if (fn.language === 'internal' || fn.language === 'c')
+            return { accesses: [], opaque: false };
+        return {
+            accesses: [],
+            opaque: true,
+            opaqueReason: `language "${fn.language}" is not statically analyzable`
+        };
     }
-    return finalize(out);
+    if (fn.language === 'sql') {
+        if (!fn.source || fn.source.trim() === '')
+            return { accesses: [], opaque: false };
+        return extractAccess(fn.source);
+    }
+    const embedded = await plpgsqlStatements(fn);
+    if ('opaqueReason' in embedded) {
+        return { accesses: [], opaque: true, opaqueReason: embedded.opaqueReason };
+    }
+    const accesses = [];
+    const seen = new Set();
+    let opaque = embedded.flags.opaque;
+    let opaqueReason = embedded.flags.opaqueReason;
+    for (const sql of embedded.statements) {
+        const part = await extractAccess(sql);
+        if (part.opaque && !opaque) {
+            opaque = true;
+            opaqueReason = part.opaqueReason;
+        }
+        for (const a of part.accesses) {
+            const key = `${a.schema ?? ''}.${a.name}::${a.privilege}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            accesses.push(a);
+        }
+    }
+    return { accesses, opaque, ...(opaqueReason ? { opaqueReason } : {}) };
 }
 /** Walk the PL/pgSQL JSON tree: collect embedded SQL, flag dynamic EXECUTE. */
 function collectPlpgsql(node, exprs, out) {
@@ -108,6 +182,11 @@ async function extractQuery(sql) {
             if (setting)
                 out.settings.push(setting);
         }
+        // Not opaque: the rest of the body still reads correctly. Tainted: the
+        // relations this call reaches are in a string, and we do not follow it.
+        if (SQL_EXECUTING.has(ref.name)) {
+            out.tainted ??= `\`${ref.name}\` executes SQL this analysis cannot see`;
+        }
     }
     // Write targets: the relation of INSERT/UPDATE/DELETE statements.
     const writeOids = new Set();
@@ -230,6 +309,7 @@ function mergeBody(into, from) {
         into.opaque = true;
         into.opaqueReason = from.opaqueReason;
     }
+    into.tainted ??= from.tainted;
 }
 function finalize(body) {
     const callKeys = new Set();
@@ -254,6 +334,7 @@ function finalize(body) {
         tables: [...tableKeys.values()],
         settings: [...new Set(body.settings)],
         opaque: body.opaque,
-        ...(body.opaqueReason ? { opaqueReason: body.opaqueReason } : {})
+        ...(body.opaqueReason ? { opaqueReason: body.opaqueReason } : {}),
+        ...(body.tainted ? { tainted: body.tainted } : {})
     };
 }

package/checks/column-grants.d.ts

@@ -0,0 +1,20 @@
+/**
+ * L13: reach that exists only in `pg_attribute.attacl`.
+ *
+ * `GRANT SELECT (secret) ON t TO anonymous` writes nothing to the relation's
+ * ACL. Every grant query in this package read `relacl` alone, so a role whose
+ * entire access to a table is column-scoped was reported as reaching *nothing*
+ * — no A2, no R1, no L-series, and "0 relation(s) accessible" in the role
+ * access report. The privilege is real: the role selects those columns, and
+ * when the table has no RLS it selects every row of them.
+ *
+ * The finding is deliberately about the *invisibility* as much as the access.
+ * A column grant is a legitimate and often good way to expose a projection;
+ * what is not fine is that nothing else in the audit grades it. So L13 reports
+ * the reach, states whether RLS mediates it, and — as everywhere else — never
+ * recommends revoking the grant it cannot prove unused.
+ */
+import type { TableSnapshot } from '../pg/introspect';
+import type { Finding } from '../types';
+import { type LatticeRoleOptions, type RoleGraph } from './lattice';
+export declare function checkUntrustedColumnGrants(table: TableSnapshot, graph: RoleGraph, options?: LatticeRoleOptions): Finding[];

package/checks/column-grants.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * L13: reach that exists only in `pg_attribute.attacl`.
+ *
+ * `GRANT SELECT (secret) ON t TO anonymous` writes nothing to the relation's
+ * ACL. Every grant query in this package read `relacl` alone, so a role whose
+ * entire access to a table is column-scoped was reported as reaching *nothing*
+ * — no A2, no R1, no L-series, and "0 relation(s) accessible" in the role
+ * access report. The privilege is real: the role selects those columns, and
+ * when the table has no RLS it selects every row of them.
+ *
+ * The finding is deliberately about the *invisibility* as much as the access.
+ * A column grant is a legitimate and often good way to expose a projection;
+ * what is not fine is that nothing else in the audit grades it. So L13 reports
+ * the reach, states whether RLS mediates it, and — as everywhere else — never
+ * recommends revoking the grant it cannot prove unused.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkUntrustedColumnGrants = checkUntrustedColumnGrants;
+const lattice_1 = require("./lattice");
+/** SELECT/INSERT/UPDATE are the column privileges RLS has anything to say about. */
+const MEDIATED = ['SELECT', 'INSERT', 'UPDATE'];
+function checkUntrustedColumnGrants(table, graph, options = {}) {
+    const roles = options.roles ?? [];
+    if (roles.length === 0 || table.columnGrants.length === 0)
+        return [];
+    const out = [];
+    for (const role of roles) {
+        const grants = (0, lattice_1.effectiveColumnGrants)(table, role, graph).filter((g) => MEDIATED.includes(g.privilege));
+        if (grants.length === 0)
+            continue;
+        const attrs = graph.get(role);
+        // Same exemption test the rest of the lattice uses: a role RLS does not
+        // apply to reads every row of the columns it is granted.
+        const rlsApplies = table.rlsEnabled
+            && !attrs?.bypassRls
+            && !attrs?.isSuper
+            && !(role === table.owner && !table.rlsForced);
+        const columns = [...new Set(grants.flatMap((g) => g.columns))].sort();
+        const privileges = grants.map((g) => g.privilege).sort();
+        const via = grants[0].via;
+        out.push({
+            code: 'L13',
+            severity: 'info',
+            category: 'anti-pattern',
+            schema: table.schema,
+            table: table.name,
+            role,
+            privilege: privileges.join(', '),
+            message: `Untrusted role ${role} holds column-level ${privileges.join(', ')} on `
+                + `${table.schema}.${table.name} (${columns.join(', ')})`
+                + (via === 'direct' ? '' : ` via ${via}`)
+                + (rlsApplies
+                    ? ' — mediated by RLS, but invisible to every rule that reads the relation ACL'
+                    : ' — with no RLS to mediate it, so every row of those columns is readable'),
+            hint: `Column grants live in \`pg_attribute.attacl\`, not \`relacl\`: \`\\dp\` shows them in `
+                + `the "Column privileges" column and nothing else in this audit graded them until now. `
+                + (rlsApplies
+                    ? 'Confirm the policies that mediate this relation are the ones you would want applied '
+                        + 'to a projection of it.'
+                    : 'If the projection is meant to be public this is correct as written; if not, enable '
+                        + 'RLS on the relation — the column grant restricts *which columns*, never which rows.')
+                + ' Do not revoke the grant on the strength of this finding alone: nothing here proves it '
+                + 'unused.',
+            context: {
+                columns,
+                via,
+                rlsMediated: rlsApplies,
+                rlsEnabled: table.rlsEnabled
+            }
+        });
+    }
+    return out;
+}

package/checks/definer-function.d.ts

@@ -0,0 +1,91 @@
+/**
+ * L19 and L20: privilege that arrives through a *function body*.
+ *
+ * L8 modelled the view half of "SQL bodies confer privilege". This is the
+ * other half, and the larger one:
+ *
+ *   - **L19, SECURITY DEFINER functions.** A definer function executes as its
+ *     owner, so every relation its body touches is touched with the owner's
+ *     privileges — including tables the caller holds nothing on, and, when
+ *     the owner owns the table or bypasses RLS, without the row filter the
+ *     table's policies would have applied. EXECUTE on the function is the
+ *     only grant the caller needs, and no ACL on the base relation names it.
+ *     Verified on PostgreSQL 18: an anonymous role with EXECUTE read every
+ *     row of an RLS-protected table it had no grant on, while the invoker
+ *     twin of the same function was denied.
+ *
+ *   - **L20, `INSTEAD OF` triggers.** A write against a view carrying one
+ *     never reaches a base relation: it *becomes* the trigger function's
+ *     body. L9 suppressed those views because nothing followed that body —
+ *     this rule follows it. The body is permission-checked against the
+ *     function's effective user, so the escalation exists only when the
+ *     trigger function is SECURITY DEFINER; the view's own owner and its
+ *     `security_invoker` setting do not govern it. Both halves were probed on
+ *     PG 18: the invoker trigger function was denied on the relation its body
+ *     wrote, the definer one wrote it as its owner.
+ *
+ * The conservatism is L8's, unchanged. A body that cannot be read is unknown,
+ * not empty: its fragmentary access list is discarded and the function is
+ * reported as a coverage gap (L15) rather than scanned clean. And the fix is
+ * never a revoke — EXECUTE on the function is what the API serves; the defect
+ * is what the body does with the owner's rights.
+ */
+import { type SchemaAclInfo } from '../pg/acl';
+import type { FunctionSnapshot } from '../pg/functions';
+import type { ViewSnapshot } from '../pg/indexes';
+import type { TableSnapshot } from '../pg/introspect';
+import type { Finding } from '../types';
+import { type SuppressedView } from './definer-view';
+import { type LatticeRoleOptions, type RoleGraph } from './lattice';
+import { type FunctionReachInput, type TriggerWriteInput } from './role-reach';
+export interface FunctionBodyAnalysis {
+    /** Functions that execute as someone other than the caller, as reach inputs. */
+    functions: FunctionReachInput[];
+    /** `INSTEAD OF` triggers whose function re-owns the write. */
+    triggers: TriggerWriteInput[];
+    /** Bodies deliberately left out, with why — an unread body is not a clean bill. */
+    suppressed: SuppressedView[];
+}
+/**
+ * Read every SECURITY DEFINER function's body and resolve what it reaches.
+ *
+ * Calls are followed: an invoker function called from a definer still runs
+ * with the definer's owner in force, while an inner definer switches the
+ * executing role again — the same rule as nested views, because it is the
+ * same rule. Views read from a body are followed too, through the existing
+ * view walk, so a definer function selecting from a definer view reaches that
+ * view's bases as well.
+ */
+export declare function analyzeFunctionBodies(functions: FunctionSnapshot[], views: ViewSnapshot[], tables: TableSnapshot[], auditedSchemas?: Iterable<string>): Promise<FunctionBodyAnalysis>;
+/**
+ * L19: an untrusted role reaches a relation by executing a SECURITY DEFINER
+ * function.
+ *
+ * Fires once per (role, function, relation, privilege) where the role can
+ * EXECUTE the function, the body touches the relation as someone else, and
+ * the role holds no such privilege on the relation itself. The invoker twin
+ * of the same function produces nothing: its body runs as the caller, so the
+ * relation's own ACL and policies apply and there is no edge to report.
+ */
+export declare function checkDefinerFunctionReach(functions: FunctionReachInput[], tables: TableSnapshot[], graph: RoleGraph, schemaAcls: Map<string, SchemaAclInfo>, options?: LatticeRoleOptions): Finding[];
+/**
+ * L20: an untrusted role writes a relation through an `INSTEAD OF` trigger
+ * whose function is SECURITY DEFINER.
+ *
+ * This is the suppression L9 has carried since it shipped. A write against a
+ * view with `INSTEAD OF` triggers never reaches a base relation — Postgres
+ * runs the trigger function instead — and where that write lands is in the
+ * body. Following it makes the edge provable; where the body is unreadable,
+ * or the trigger function runs as the caller, the suppression stands.
+ */
+export declare function checkInsteadOfTriggerWrite(triggers: TriggerWriteInput[], tables: TableSnapshot[], graph: RoleGraph, options?: LatticeRoleOptions): Finding[];
+/**
+ * L15, asked of a function instead of a view: an untrusted role can execute a
+ * definer function whose body this analysis could not fully read.
+ *
+ * The same coverage statement the view producer makes, for the same reason —
+ * the execution is proven and the far end is unknown, so no grading rule saw
+ * it. Reporting the gap is the alternative to a silent clean bill; it is
+ * `info`, score-neutral, and recommends no revoke.
+ */
+export declare function checkUnreadableFunctionReach(functions: FunctionReachInput[], graph: RoleGraph, schemaAcls: Map<string, SchemaAclInfo>, options?: LatticeRoleOptions): Finding[];