@rebasepro/rls-check 0.24.0 → 0.24.1-canary.g19596ef

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -16,7 +16,7 @@ It also takes the connection string as an argument, but prefer not to: npm echoe
16
16
 
17
17
  It works against Supabase, Neon, RDS, Cloud SQL, Postgres in a container on your laptop, or anything else that speaks the wire protocol. It knows nothing about your framework and asks nothing of your codebase.
18
18
 
19
- **It is read-only.** It issues `SELECT`s against the system catalogs — `pg_class`, `pg_policies`, `pg_proc`, `information_schema` — and nothing else. It writes nothing, changes no setting, and sends nothing anywhere. There is no telemetry, no upload, and no network access beyond the connection you give it.
19
+ **It is read-only.** It sets two options for its own session, `statement_timeout` and `default_transaction_read_only = on`, and then issues `SELECT`s against the system catalogs (`pg_class` and its ACLs, `pg_policies`, `pg_proc`, `pg_roles` …) and nothing else. It writes nothing, changes nothing beyond its own session, and sends nothing anywhere. There is no telemetry, no upload, and no network access beyond the connection you give it.
20
20
 
21
21
  ---
22
22
 
@@ -144,7 +144,7 @@ rls-check is free and maintained by the team behind Rebase — https://rebase.pr
144
144
 
145
145
  That run found nothing heuristic. When it does, the heuristic findings go in a `WORTH CHECKING` section of their own, after the confident ones — mixing "this table is public" with "this might be a join table" is how a scanner teaches people to ignore it.
146
146
 
147
- The `Exposed` line is worth reading before the findings: a check that calls a table exposed does so only when one of those roles can reach it — holds a privilege on it, and `USAGE` on its schema — so if the role your application connects as is not listed, name it with `--role` and run again.
147
+ The `Exposed` line is worth reading before the findings: a check that calls a table exposed does so only when one of those roles can reach it — holds a privilege on it, and `USAGE` on its schema (an unconditional policy one `GRANT` short of that is reported as latent `info`, not as an exposure) — so if the role your application connects as is not listed, name it with `--role` and run again.
148
148
 
149
149
  ## The checks
150
150
 
@@ -153,11 +153,11 @@ Run `npx @rebasepro/rls-check --list-checks` for the catalog on your installed v
153
153
  | id | typical severity | confidence | what it looks for |
154
154
  | --- | --- | --- | --- |
155
155
  | `rls-disabled` | critical | certain | A table with RLS off that grants SELECT/INSERT/UPDATE/DELETE to a role an untrusted caller can reach, or a foreign table (which cannot have RLS) with such a grant. |
156
- | `policy-always-true` | critical | certain | A permissive policy whose `USING` or `WITH CHECK` expression is always true. High when only an UPDATE policy's `WITH CHECK` is constant: `USING` still scopes which rows it touches, and the check lets them become anything. Downgraded to medium, and to heuristic, when `RESTRICTIVE` policies on the same command apply to every role it reaches. |
157
- | `view-bypasses-rls` | critical | certain | A view granted to an untrusted role that selects from an RLS-protected table and runs with its owner's privileges. Heuristic on servers before PG15, where `security_invoker` does not exist. |
156
+ | `policy-always-true` | critical | certain | A permissive policy whose `USING` or `WITH CHECK` expression is always true. High when only an UPDATE policy's `WITH CHECK` is constant: `USING` still scopes which rows it touches, and the check lets them become anything. Downgraded to medium, and to heuristic, when `RESTRICTIVE` policies on the same command apply to every role it reaches. Info, titled *latent*, when the roles it names cannot reach the table yet (no privilege for the command, or no `USAGE` on the schema): one `GRANT` away from critical. |
157
+ | `view-bypasses-rls` | critical | certain | A view granted to an untrusted role that selects from an RLS-protected table and runs with its owner's privileges. Heuristic on servers before PG15, where `security_invoker` does not exist, and when the view's owner is itself subject to the base table's policies. |
158
158
  | `policy-anonymous-tautology` | varies | heuristic | An `auth.uid() IS NOT NULL`-shaped policy: it separates signed-in from signed-out callers and scopes no rows. Critical when a signed-out caller still has a value there — Rebase's and PostgREST's sentinel id, or `auth.role()` / `auth.jwt()` on Supabase, which the anon key fills; low for `auth.uid()` on Supabase, which is NULL for a signed-out caller; medium where the scan cannot tell. |
159
- | `policy-authenticated-tautology` | high | heuristic | The corrected form of the above — `auth.uid() IS NOT NULL AND auth.uid() <> 'anonymous'` — which excludes signed-out callers and still scopes no rows. Every account reads every row; with open registration that is everybody. |
160
- | `anonymous-write-allowed` | high | certain | A permissive INSERT/UPDATE/DELETE policy reachable without authentication whose check expression accepts any row, backed by a matching grant. |
159
+ | `policy-authenticated-tautology` | high | heuristic | The corrected form of the above — `auth.uid() IS NOT NULL AND auth.uid() <> 'anonymous'` — which excludes signed-out callers and still scopes no rows. Every account reads every row; with open registration that is everybody. Rebase's `policy.registered()` alone (which also excludes guests) is this shape too. So is a role test alone — `auth.role() = 'authenticated'`, or the `role` claim of `auth.jwt()` — reported at `policy-always-true`'s severity (critical), since it is `TO authenticated USING (true)` written as an expression. |
160
+ | `anonymous-write-allowed` | high | certain | A permissive INSERT/UPDATE/DELETE policy reachable without authentication whose check expression accepts any row, backed by a matching grant. A policy for a role that `anon` inherits counts. Heuristic on Rebase when only `rebase_user` reaches it: whether a signed-out caller runs as that role is the API's `AUTH_REQUIRE` setting, which the database cannot see. |
161
161
  | `matview-bypasses-rls` | high | certain | A materialized view granted to an untrusted role whose defining query reads an RLS-protected table. Materialized views have no `security_invoker`. |
162
162
  | `unqualified-column-in-subquery` | high | heuristic | A bare column name in an `EXISTS`/`IN` subquery that exists on both the inner relation and the policy's own table, so Postgres binds it to the inner one. Postgres stores it with every column qualified, so on a live database it is found as the inner column compared with itself (`m.org_id = m.org_id`). |
163
163
  | `junction-table-unprotected` | high | heuristic | A table that is essentially two foreign keys pointing at RLS-protected tables, with no row-level security of its own. |
@@ -216,7 +216,7 @@ If your password contains `/`, `?` or `#`, percent-encode it. Those three end th
216
216
  | --- | --- |
217
217
  | `0` | Clean, or nothing at or above `--fail-on`. |
218
218
  | `1` | Findings at or above `--fail-on`. |
219
- | `2` | The scan did not run: bad arguments, connection refused, authentication failed, timeout. |
219
+ | `2` | The scan did not run: bad arguments, connection refused, authentication failed, timeout. Or it was incomplete: a catalogue read failed or a check crashed (`diagnostics.degraded`). This holds even with `--fail-on none`, since an incomplete scan has no verdict. |
220
220
 
221
221
  `1` and `2` are never conflated. A pipeline that reads a DNS failure as a clean bill of health is worse than no tool at all.
222
222
 
@@ -13,3 +13,9 @@ import type { Check } from "../types.js";
13
13
  * the check cannot see the session that will run the query.
14
14
  */
15
15
  export declare const currentSettingThrows: Check;
16
+ /**
17
+ * The expression with every one-argument `current_setting(...)` given
18
+ * `missing_ok`. The text is `pg_policies`' deparse, which spells the argument
19
+ * as a literal, usually cast: `current_setting('app.tenant'::text)`.
20
+ */
21
+ export declare function withMissingOk(expr: string): string;
@@ -13,6 +13,11 @@ export interface RunOptions {
13
13
  only?: string[];
14
14
  /** Skip these check ids. */
15
15
  skip?: string[];
16
+ /**
17
+ * Told about every check that threw. Its findings are missing, which looks
18
+ * exactly like a clean result unless the caller says so.
19
+ */
20
+ onCheckError?: (checkId: string, error: unknown) => void;
16
21
  }
17
22
  /**
18
23
  * Run every selected check and return the findings, worst first.
@@ -1,4 +1,4 @@
1
- import type { Check } from "../types.js";
1
+ import type { Check, DbPolicy, DbSnapshot, Severity } from "../types.js";
2
2
  /**
3
3
  * A PERMISSIVE policy whose expression is a constant truth, targeted at a role
4
4
  * an untrusted caller reaches.
@@ -15,3 +15,20 @@ import type { Check } from "../types.js";
15
15
  * cover the same rows).
16
16
  */
17
17
  export declare const policyAlwaysTrue: Check;
18
+ /**
19
+ * How bad an unconditional clause on `policy` is, by the command it governs and
20
+ * the RESTRICTIVE policies that gate it.
21
+ *
22
+ * Exported because `USING (true)` is not the only way to write it:
23
+ * `policy-authenticated-tautology` grades `auth.role() = 'authenticated'` —
24
+ * the same grant, spelled as an expression — by this same rule, so the two
25
+ * spellings cannot drift apart.
26
+ */
27
+ export declare function unconditionalReading(snapshot: DbSnapshot, policy: DbPolicy, clauses: string[]): {
28
+ severity: Severity;
29
+ gate: {
30
+ name: string;
31
+ verb: string;
32
+ } | null;
33
+ checkOnly: boolean;
34
+ };
@@ -71,6 +71,13 @@ export interface TautologyMatch {
71
71
  * here, which is why the policy that actually shipped passed silently.
72
72
  */
73
73
  guardsSentinel: boolean;
74
+ /**
75
+ * Whether the clause also keeps guests out — `NOT rebase.is_anonymous()`,
76
+ * the conjunct `policy.registered()` adds to `authenticated()`. It scopes
77
+ * no rows, so it does not change which finding this is; only the sentence
78
+ * that describes who is admitted.
79
+ */
80
+ excludesGuests: boolean;
74
81
  }
75
82
  /**
76
83
  * Recognise "the policy tests that a caller id exists, and nothing that narrows
@@ -97,3 +104,19 @@ export interface TautologyMatch {
97
104
  * because it is the one that survives code review.
98
105
  */
99
106
  export declare function callerIdOnlyClause(clause: string | null | undefined): TautologyMatch | null;
107
+ /**
108
+ * `auth.role() = 'authenticated'` — and nothing that narrows which rows.
109
+ *
110
+ * That is `TO authenticated USING (true)` written as an expression: every
111
+ * signed-in caller passes it, for every row. The policy-level spelling was
112
+ * graded critical by `policy-always-true` while this one gave no finding at
113
+ * all, which is the gap a scanner must not have. The same two rules as
114
+ * {@link callerIdOnlyClause}: every conjunct must be accounted for (the role
115
+ * test, or the guest exclusion, which scopes nothing either), and any `OR`
116
+ * means the shape no longer describes what the policy admits.
117
+ *
118
+ * Returns how to name the role read in prose, or `null`.
119
+ */
120
+ export declare function signedInRoleOnlyClause(clause: string | null | undefined): {
121
+ shape: string;
122
+ } | null;
@@ -23,5 +23,11 @@ import type { Check } from "../types.js";
23
23
  * different fixes and different severities have to be two ids. Someone who has
24
24
  * decided their `countries` table really is world-readable should be able to
25
25
  * silence that without also silencing "signed-out callers can read it".
26
+ *
27
+ * The same id also covers `auth.role() = 'authenticated'` (and the `role`
28
+ * claim of `auth.jwt()`, either way round): a role test that says "signed in"
29
+ * and nothing about rows. That one is graded by `policy-always-true`'s rule,
30
+ * not `high`, because it is `TO authenticated USING (true)` spelled as an
31
+ * expression, and the two spellings must not get different answers.
26
32
  */
27
33
  export declare const policyAuthenticatedTautology: Check;
@@ -45,10 +45,16 @@ export declare function qualifiedNameEndingAt(tokens: SqlToken[], i: number): st
45
45
  /**
46
46
  * Does this expression normalize to an unconditional truth?
47
47
  *
48
- * Strictly structural: parens and boolean casts are dropped and the *whole*
49
- * remainder has to be the constant. A substring match on `true` would flag
50
- * `(is_public = true AND owner = auth.uid())`, which is exactly the kind of
51
- * false positive this tool cannot afford.
48
+ * Strictly structural: parens and casts are dropped, and the expression is
49
+ * folded only where every part is a constant. A substring match on `true`
50
+ * would flag `(is_public = true AND owner = auth.uid())`, which is exactly the
51
+ * kind of false positive this tool cannot afford.
52
+ *
53
+ * Folded: `true`, `NOT false`, a constant compared with a constant (`1 = 1`,
54
+ * `1 > 0`, `'a'::character varying = 'a'::character varying`), and `AND` /
55
+ * `OR` over those — `true OR x` is true whatever `x` is. Only `true`, `1 = 1`
56
+ * and a one-word cast were, so `NOT false`, `1 > 0` and `true OR …` passed as
57
+ * scoped policies.
52
58
  */
53
59
  export declare function isUnconditionalTrue(expr: string | null | undefined): boolean;
54
60
  /** Words that are never a column reference in a policy predicate. */
@@ -6,7 +6,7 @@
6
6
  * noise, and noise is what gets a tool like this uninstalled — so the helpers
7
7
  * below err towards "no" whenever the catalog is ambiguous.
8
8
  */
9
- import type { DbForeignKey, DbGrant, DbPolicy, DbRelation, DbRole, DbSnapshot, Finding, Severity } from "../types.js";
9
+ import type { DbForeignKey, DbGrant, DbPolicy, DbRelation, DbRole, DbSnapshot, Finding, PolicyCommand, Severity } from "../types.js";
10
10
  export declare const SEVERITY_ORDER: Severity[];
11
11
  export declare const docsFor: (id: string) => string;
12
12
  export type Privilege = DbGrant["privileges"][number];
@@ -58,6 +58,8 @@ export declare function exposedGrantees(snapshot: DbSnapshot, schema: string, ta
58
58
  }[];
59
59
  /** Does this policy's TO list name a role an untrusted caller arrives as? */
60
60
  export declare function policyTargetsExposedRole(snapshot: DbSnapshot, policy: DbPolicy): string[];
61
+ /** The privileges a policy's command is exercised with. */
62
+ export declare const COMMAND_PRIVILEGES: Record<PolicyCommand, Privilege[]>;
61
63
  /**
62
64
  * The exposed callers a policy applies to *and* that can reach its table for
63
65
  * its command: {@link policyTargetsExposedRole}, kept to the roles holding a
@@ -83,14 +85,11 @@ export declare const hasColumn: (r: DbRelation, name: string) => boolean;
83
85
  /** `≈ 12,000 rows` — only ever used to convey blast radius, never severity. */
84
86
  export declare function rowsPhrase(rel: DbRelation | undefined): string;
85
87
  /**
86
- * A quoted identifier that is one printable token wherever a fix puts it.
87
- *
88
- * Every name here comes out of the catalog, which means out of whoever could
89
- * create a table, a role or a policy, and every fix is printed to be pasted
90
- * into psql. Doubling `"` keeps a name inside its quotes; a name with a line
91
- * break in it is written as a Unicode-escape identifier (`U&"a\000Ab"`), which
92
- * names the same object and has no line break to escape a comment with.
88
+ * The column a printed fix should scope rows by, when the table has one that
89
+ * looks like the owner's id. Fixes named `user_id` on every table, and a table
90
+ * without one rejected the pasted SQL.
93
91
  */
92
+ export declare function ownerColumnOf(rel: DbRelation | undefined): string | undefined;
94
93
  export declare function qi(ident: string): string;
95
94
  export declare const qrel: (schema: string, name: string) => string;
96
95
  /** PUBLIC is a keyword, not an identifier — quoting it changes what it means. */
@@ -1,6 +1,14 @@
1
1
  import type { Check, DbRelation, DbSnapshot, DbView } from "../types.js";
2
2
  /** Base relations of `view` that have RLS turned on. */
3
3
  export declare function protectedBaseTables(snapshot: DbSnapshot, view: DbView): DbRelation[];
4
+ /**
5
+ * Whether `owner` reads `base` past its policies: as a superuser, with
6
+ * BYPASSRLS, or as the table's owner (a member of the owning role counts, as
7
+ * Postgres counts it) while FORCE ROW LEVEL SECURITY is off. A role the
8
+ * catalog read did not return is assumed to — the scan must not go quiet on
9
+ * what it could not see.
10
+ */
11
+ export declare function ownerReadsPast(snapshot: DbSnapshot, owner: string, base: DbRelation): boolean;
4
12
  /**
5
13
  * A view granted to an untrusted role that reads an RLS-protected table without
6
14
  * `security_invoker`.
@@ -14,5 +22,11 @@ export declare function protectedBaseTables(snapshot: DbSnapshot, view: DbView):
14
22
  * Before PG 15 the option does not exist, which means every view behaves this
15
23
  * way. That is worth saying, but it is not evidence that *this* view is a
16
24
  * mistake, so those findings are marked heuristic.
25
+ *
26
+ * The owner is *normally* exempt, not always. A view owned by a role the base
27
+ * tables' policies do apply to returns what those policies give that role —
28
+ * to every caller alike, which may be nothing at all. Still reported, because
29
+ * the rows do not depend on who asks, but heuristic: whether it hands out more
30
+ * than a caller should see depends on the owner's policies.
17
31
  */
18
32
  export declare const viewBypassesRls: Check;