@safegres/test 0.0.1 → 1.30.7

package/commands/audit.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Script A driver: pure-Postgres RLS audit.
+ *
+ * Ingests a catalog snapshot, runs every check, and returns a structured report.
+ */
+import type { ExposureConfig, SafegresConfig } from '../config/types';
+import { type IntrospectOptions, type QueryExecutor } from '../pg/introspect';
+import type { Report } from '../types';
+export interface AuditOptions extends IntrospectOptions {
+    /** If provided, bypass `pg_roles` enumeration. Otherwise enumerate roles dynamically. */
+    includeRoles?: string[];
+    /** Roles to drop after enumeration. */
+    excludeRoles?: string[];
+    /**
+     * Skip AST-level anti-pattern checks (P1, P5). Useful for very fast audits
+     * that only want grants + RLS-flag + coverage findings.
+     */
+    skipAstChecks?: boolean;
+    /**
+     * The exposed API surface. Overrides `config.exposure` when provided.
+     * Findings on non-exposed schemas contribute nothing to the score.
+     */
+    exposure?: ExposureConfig;
+    /**
+     * Build the unscored call-graph audit: trust boundaries (SECURITY DEFINER
+     * hops, RLS-bypass paths, auth-context mutations) reachable from the
+     * exposed entry points. Adds `report.callGraph`.
+     */
+    callGraph?: boolean;
+    /**
+     * Collect and score the performance dimension: index-hygiene rules (`X*`)
+     * on top of the policy-cost rules (P1/P1b) the audit already runs. Adds
+     * `report.perf` with its own score. Overrides `config.perf.enabled`.
+     */
+    perf?: boolean;
+    /**
+     * Collect runtime statistics (`pg_stat_user_tables`, `pg_stat_statements`)
+     * and run the `S*` rules. Implies `perf`. Overrides `config.perf.stats.enabled`.
+     */
+    stats?: boolean;
+    /**
+     * Probe perf findings with `EXPLAIN (GENERIC_PLAN)` and attach the plan as
+     * evidence, acknowledging findings the planner refutes. Implies `perf`.
+     * Overrides `config.perf.explain.enabled`.
+     */
+    explain?: boolean;
+    /**
+     * Merged safegres configuration (rules, overrides, scoring). Rule settings
+     * filter and retune findings; scoring settings drive the report score.
+     * Connection-independent option fields (`schemas`, `roles`, …) present on
+     * the config are used as fallbacks for the corresponding AuditOptions.
+     */
+    config?: SafegresConfig;
+    /**
+     * Record the run as sealed: produced under configuration the caller
+     * controls, with no local config file, rule overrides or baselines. The
+     * audit behaves identically — sealing is enforced by whoever assembles the
+     * config (the CLI's `--sealed`) — but the claim lands in
+     * `report.provenance` so a harness can require it.
+     */
+    sealed?: boolean;
+    /** The preset a sealed run was graded under, recorded in the provenance. */
+    preset?: string;
+}
+export declare function audit(client: QueryExecutor, options?: AuditOptions): Promise<Report>;