@safegres/test 0.0.2 → 1.30.7

package/esm/cli/commands.js

@@ -0,0 +1,53 @@
+import { Logger } from '@pgpmjs/logger';
+import { extractFirst } from 'inquirerer';
+import audit from './audit';
+import baseline from './baseline';
+import doctor from './doctor';
+import evalCommand from './eval';
+import printConfig from './print-config';
+const log = new Logger('safegres');
+const usage = `
+safegres — Postgres security and performance auditor
+
+Usage:
+  safegres <command> [OPTIONS]
+
+Commands:
+  audit           Audit grants, RLS flags, policy coverage, and anti-patterns
+  lint            Alias for audit, for a package.json script
+  perf            Audit index hygiene and policy cost (audit --perf)
+  baseline        Choose the report a delta is measured against (CI)
+  doctor          Diagnose environment, connection, and configuration
+  eval            Grade the auditor against a corpus with known answers
+  print-config    Show the resolved effective configuration
+  help            Show this help message
+
+Run \`safegres <command> --help\` for command-specific options.
+`;
+const commandMap = {
+    audit,
+    lint: audit,
+    perf: (argv, prompter, options) => audit({ ...argv, perf: true }, prompter, options),
+    baseline,
+    doctor,
+    eval: evalCommand,
+    'print-config': printConfig
+};
+export const commands = async (argv, prompter, options) => {
+    const { first: command, newArgv } = extractFirst(argv);
+    if (!command && (argv.help || argv.h)) {
+        process.stdout.write(usage);
+        return;
+    }
+    if (!command || command === 'help') {
+        process.stdout.write(usage);
+        return;
+    }
+    const handler = commandMap[command];
+    if (!handler) {
+        log.error(`Unknown command: ${command}`);
+        process.stdout.write(usage);
+        process.exit(2);
+    }
+    await handler(newArgv, prompter, options);
+};

package/esm/cli/doctor.d.ts

@@ -0,0 +1,3 @@
+import { CLIOptions, Inquirerer, ParsedArgs } from 'inquirerer';
+declare const _default: (argv: ParsedArgs, _prompter: Inquirerer, _options: CLIOptions) => Promise<void>;
+export default _default;

package/esm/cli/doctor.js

@@ -0,0 +1,67 @@
+import yanse from 'yanse';
+import { doctor } from '../commands/doctor';
+import { buildClient, configParamsFromArgv } from './shared';
+const usage = `
+safegres doctor — diagnose the environment, connection, and configuration
+
+  safegres doctor [OPTIONS]
+
+Connection (same flags as \`safegres audit\`):
+  --connection <url>       Full PostgreSQL connection string
+  --host / --port / --user / --password / --database
+
+Configuration:
+  --config <path>          Explicit config file
+  --preset <name>          Apply a built-in preset
+  --rule <CODE=SETTING>    Retune a rule (repeatable)
+
+Options:
+  --no-color               Disable ANSI colors
+  --help, -h               Show this help message
+
+Checks: config discovery & rule validation, pgsql-parser availability,
+connection, catalog access (pg_policy), audit blind spots (BYPASSRLS),
+and whether any tables actually have RLS enabled.
+`;
+const STATUS_LABEL = {
+    ok: 'OK  ',
+    warn: 'WARN',
+    fail: 'FAIL'
+};
+export default async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        process.stdout.write(usage);
+        return;
+    }
+    const colorEnabled = argv.color !== false;
+    const paint = (status, s) => {
+        if (!colorEnabled)
+            return s;
+        if (status === 'ok')
+            return yanse.green(s);
+        if (status === 'warn')
+            return yanse.yellow(s);
+        return yanse.bold(yanse.red(s));
+    };
+    let client = buildClient(argv);
+    try {
+        await client.connect();
+    }
+    catch {
+        client = null;
+    }
+    try {
+        const report = await doctor(client, configParamsFromArgv(argv));
+        for (const check of report.checks) {
+            process.stdout.write(`[${paint(check.status, STATUS_LABEL[check.status])}] ${check.name.padEnd(12)} ${check.detail}\n`);
+        }
+        process.stdout.write('\n');
+        process.stdout.write(report.ok ? 'doctor: all checks passed\n' : 'doctor: some checks failed\n');
+        if (!report.ok)
+            process.exit(1);
+    }
+    finally {
+        if (client)
+            await client.end();
+    }
+};

package/esm/cli/eval.d.ts

@@ -0,0 +1,3 @@
+import { CLIOptions, Inquirerer, ParsedArgs } from 'inquirerer';
+declare const _default: (argv: ParsedArgs, _prompter: Inquirerer, _options: CLIOptions) => Promise<void>;
+export default _default;

package/esm/cli/eval.js

@@ -0,0 +1,115 @@
+import * as path from 'path';
+import yanse from 'yanse';
+import { runEval } from '../commands/eval';
+import { configPathBase, loadConfig } from '../config/loader';
+import { loadCorpus } from '../corpus';
+import { buildClient, csvList } from './shared';
+const usage = `
+safegres eval — grade the auditor against a corpus with known answers
+
+  safegres eval [OPTIONS]
+
+Deploys each corpus case into the connected database, audits it under a sealed
+preset, and grades the report against the case's answer key: every expected
+finding present (recall), nothing the case forbids (precision). Exits non-zero
+if any case fails. Each case's schemas are dropped afterwards.
+
+Connection (same flags as \`safegres audit\`):
+  --connection <url>       Full PostgreSQL connection string
+  --host / --port / --user / --password / --database
+
+Options:
+  --preset <name>          Preset every case is graded under (default: recommended)
+  --corpus <dir>           Corpus directory of <id>/{case.json,schema.sql}
+  --case <id>              Run only these cases; id or id prefix, comma-separated
+  --list                   List the corpus without connecting to a database
+  --keep                   Leave the case schemas in the database
+  --json                   Emit the machine-readable result instead of a table
+  --no-color               Disable ANSI colors
+  --help, -h               Show this help message
+
+Config: a discovered safegres config may set \`eval.corpus\`, \`eval.preset\` and
+\`eval.cases\` — what to run. It cannot retune the rules: cases are always
+graded by the named preset alone, or the corpus would be measuring itself.
+`;
+/**
+ * Discovery is used for *selection only* (which corpus, which preset, which
+ * cases). Grading always loads the preset sealed, so nothing in the working
+ * tree can change the answers.
+ */
+function evalDefaults(configFile) {
+    try {
+        const loaded = loadConfig({ configFile });
+        const config = loaded.config.eval ?? {};
+        if (config.corpus === undefined)
+            return config;
+        // Like every other configured path: relative to the file that declared it,
+        // so a corpus committed next to the config is found from any cwd.
+        return { ...config, corpus: path.resolve(configPathBase(loaded).dirFor('eval.corpus'), config.corpus) };
+    }
+    catch {
+        return {};
+    }
+}
+function line(r, color) {
+    const paint = (s) => (!color ? s : r.passed ? yanse.green(s) : yanse.bold(yanse.red(s)));
+    const detail = r.passed
+        ? r.found.map((e) => e.code).join(' ')
+        : [
+            ...r.missed.map((e) => `missed ${e.code}${e.relation ? `@${e.relation}` : ''}`),
+            ...r.falsePositives.map((code) => `false positive ${code}`)
+        ].join(', ');
+    return `  ${paint(r.passed ? 'PASS' : 'FAIL')}  ${r.id.padEnd(32)} ${r.dimension.padEnd(8)} `
+        + `${String(r.score).padStart(3)} (${r.grade.padEnd(2)})  ${detail}\n`;
+}
+function summary(report, color) {
+    const pct = (n) => `${Math.round(n * 100)}%`;
+    const ok = report.passed === report.total;
+    const headline = `${report.passed}/${report.total} cases passed`;
+    return `\n${color ? (ok ? yanse.green(headline) : yanse.bold(yanse.red(headline))) : headline}`
+        + ` · recall ${pct(report.recall)} · precision ${pct(report.precision)}\n`;
+}
+export default async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        process.stdout.write(usage);
+        return;
+    }
+    const defaults = evalDefaults(typeof argv.config === 'string' ? argv.config : undefined);
+    const corpus = typeof argv.corpus === 'string' ? argv.corpus : defaults.corpus;
+    const preset = typeof argv.preset === 'string' ? argv.preset : (defaults.preset ?? 'recommended');
+    const cases = csvList(argv.case) ?? defaults.cases;
+    const color = argv.color !== false && argv.json !== true;
+    if (argv.list === true) {
+        for (const c of loadCorpus(corpus)) {
+            process.stdout.write(`${c.id.padEnd(32)} ${c.dimension.padEnd(8)} ${c.title}\n`);
+        }
+        return;
+    }
+    const { config } = loadConfig({ sealed: true, preset });
+    const client = buildClient(argv);
+    await client.connect();
+    try {
+        const report = await runEval(client, {
+            config,
+            preset,
+            corpus,
+            cases,
+            keep: argv.keep === true,
+            onResult: argv.json === true ? undefined : (r) => process.stdout.write(line(r, color))
+        });
+        if (argv.json === true) {
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        }
+        else {
+            process.stdout.write(summary(report, color));
+            for (const r of report.results.filter((x) => !x.passed)) {
+                process.stdout.write(`\n${r.id}: ${r.title}\n  fix: ${r.fix}\n`);
+            }
+        }
+        if (report.passed !== report.total)
+            process.exit(1);
+    }
+    finally {
+        await client.end();
+    }
+};

package/esm/cli/print-config.d.ts

@@ -0,0 +1,3 @@
+import { CLIOptions, Inquirerer, ParsedArgs } from 'inquirerer';
+declare const _default: (argv: ParsedArgs, _prompter: Inquirerer, _options: CLIOptions) => Promise<void>;
+export default _default;

package/esm/cli/print-config.js

@@ -0,0 +1,52 @@
+import { loadConfig, safegresConfigLoader } from '../config/loader';
+import { resolveRules } from '../config/resolve';
+import { toJsonSchema } from '../config/schema';
+import { RULES } from '../rules/registry';
+import { configParamsFromArgv } from './shared';
+const usage = `
+safegres print-config — show the resolved effective configuration
+
+  safegres print-config [OPTIONS]
+
+Options:
+  --config <path>          Explicit config file
+  --preset <name>          Apply a built-in preset
+  --rule <CODE=SETTING>    Retune a rule (repeatable)
+  --explain                Show per-key provenance (which layer set each value)
+  --schema                 Print the config JSON Schema instead, for an editor
+  --help, -h               Show this help message
+`;
+export default async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        process.stdout.write(usage);
+        return;
+    }
+    if (argv.schema === true) {
+        process.stdout.write(`${JSON.stringify(toJsonSchema(), null, 2)}\n`);
+        return;
+    }
+    const params = configParamsFromArgv(argv);
+    if (argv.explain === true) {
+        const loader = safegresConfigLoader();
+        const explained = loader.explainSync({
+            configFile: params.configFile,
+            overrides: params.overrides
+        });
+        for (const e of explained) {
+            process.stdout.write(`${e.path} = ${JSON.stringify(e.value)}  (${e.source}: ${e.origin})\n`);
+        }
+        return;
+    }
+    const { config, filepath, isEmpty } = loadConfig(params);
+    const resolved = resolveRules(config);
+    const effectiveRules = {};
+    for (const rule of RULES) {
+        const r = resolved.rules.get(rule.code);
+        effectiveRules[rule.code] = r.enabled ? r.severity : 'off';
+    }
+    process.stdout.write(`${JSON.stringify({
+        source: filepath ?? (isEmpty ? '(no config file — defaults)' : undefined),
+        config,
+        effectiveRules
+    }, null, 2)}\n`);
+};

package/esm/cli/shared.d.ts

@@ -0,0 +1,43 @@
+import type { ParsedArgs } from 'inquirerer';
+import { Client } from 'pg';
+import type { ConfigPathBase, LoadConfigParams } from '../config/loader';
+import type { ExtensionsConfig, RulesConfig, SafegresConfig } from '../config/types';
+export declare function csvList(value: unknown): string[] | undefined;
+/**
+ * Merge `--ignore-extensions` / `--audit-extension-owned` over the config's
+ * `extensions` block. Returns `undefined` when neither side says anything, so
+ * the introspection defaults apply.
+ */
+export declare function extensionScopeFromArgv(argv: ParsedArgs, config: SafegresConfig): ExtensionsConfig | undefined;
+export declare function buildClient(argv: ParsedArgs): Client;
+/**
+ * Parse repeatable `--rule CODE=SETTING` flags into a RulesConfig, e.g.
+ * `--rule A3=off --rule A5=high --rule 'P*'=off`.
+ */
+export declare function parseRuleFlags(value: unknown): RulesConfig | undefined;
+/** Every file a run reads or writes, after flags and config have been merged. */
+export interface RunPaths {
+    /** The pgpm workspace to deploy, when `usePgpm`. Undefined means "nearest". */
+    pgpm?: string;
+    usePgpm: boolean;
+    perfBaseline?: string;
+    callGraphBaseline?: string;
+    outputs: {
+        json?: string;
+        markdown?: string;
+        sarif?: string;
+        sarifSources?: string;
+        snapshot?: string;
+        githubComment?: string;
+    };
+}
+/**
+ * Flags win over the config file. A path from a config file is resolved
+ * against *the file that declared it* — which is not always the discovered
+ * one, since a file can extend another — so a CI job can run from any
+ * directory; a path on the command line stays relative to cwd, like every
+ * other command's arguments.
+ */
+export declare function resolveRunPaths(argv: ParsedArgs, config: SafegresConfig, base: ConfigPathBase | string): RunPaths;
+/** Build config-loading params from shared CLI flags. */
+export declare function configParamsFromArgv(argv: ParsedArgs): LoadConfigParams;

package/esm/cli/shared.js

@@ -0,0 +1,112 @@
+import * as path from 'path';
+import { Client } from 'pg';
+import { getPgEnvOptions } from 'pg-env';
+export function csvList(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return undefined;
+    return value
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+}
+/**
+ * Merge `--ignore-extensions` / `--audit-extension-owned` over the config's
+ * `extensions` block. Returns `undefined` when neither side says anything, so
+ * the introspection defaults apply.
+ */
+export function extensionScopeFromArgv(argv, config) {
+    const ignore = csvList(argv['ignore-extensions']) ?? config.extensions?.ignore;
+    const skipOwned = argv['audit-extension-owned'] === true ? false : config.extensions?.skipOwned;
+    if (ignore === undefined && skipOwned === undefined)
+        return undefined;
+    return { ...(ignore !== undefined && { ignore }), ...(skipOwned !== undefined && { skipOwned }) };
+}
+export function buildClient(argv) {
+    if (typeof argv.connection === 'string' && argv.connection.length > 0) {
+        return new Client({ connectionString: argv.connection });
+    }
+    const overrides = {};
+    if (typeof argv.host === 'string')
+        overrides.host = argv.host;
+    if (typeof argv.port === 'number')
+        overrides.port = argv.port;
+    if (typeof argv.user === 'string')
+        overrides.user = argv.user;
+    if (typeof argv.password === 'string')
+        overrides.password = argv.password;
+    if (typeof argv.database === 'string')
+        overrides.database = argv.database;
+    return new Client(getPgEnvOptions(overrides));
+}
+/**
+ * Parse repeatable `--rule CODE=SETTING` flags into a RulesConfig, e.g.
+ * `--rule A3=off --rule A5=high --rule 'P*'=off`.
+ */
+export function parseRuleFlags(value) {
+    if (value == null)
+        return undefined;
+    const entries = Array.isArray(value) ? value : [value];
+    const rules = {};
+    for (const entry of entries) {
+        if (typeof entry !== 'string')
+            continue;
+        const eq = entry.indexOf('=');
+        if (eq <= 0) {
+            throw new Error(`Invalid --rule "${entry}": expected CODE=off|<severity>.`);
+        }
+        const code = entry.slice(0, eq).trim();
+        const setting = entry.slice(eq + 1).trim();
+        rules[code] = setting;
+    }
+    return Object.keys(rules).length > 0 ? rules : undefined;
+}
+/** Did the caller name a database on the command line, rather than in the environment? */
+function hasConnectionFlag(argv) {
+    return ['connection', 'database', 'host', 'port'].some((flag) => typeof argv[flag] === 'string' || typeof argv[flag] === 'number');
+}
+/**
+ * Flags win over the config file. A path from a config file is resolved
+ * against *the file that declared it* — which is not always the discovered
+ * one, since a file can extend another — so a CI job can run from any
+ * directory; a path on the command line stays relative to cwd, like every
+ * other command's arguments.
+ */
+export function resolveRunPaths(argv, config, base) {
+    const dirFor = typeof base === 'string' ? () => base : (key) => base.dirFor(key);
+    const pick = (flag, key, configured) => typeof flag === 'string' ? flag : configured && path.resolve(dirFor(key), configured);
+    // A directory is the common case: one path, conventional names, no remembering
+    // which extension goes with which renderer. A named file still wins.
+    const dir = pick(argv.out, 'outputs.dir', config.outputs?.dir);
+    const inDir = (name) => dir && path.join(dir, name);
+    return {
+        pgpm: pick(argv.pgpm, 'source.pgpm', config.source?.pgpm),
+        // An explicit connection on the command line beats a configured source:
+        // pointing the same config at a database you already have is the whole
+        // reason to type one, and deploying a throwaway copy instead would ignore it.
+        usePgpm: argv.pgpm !== undefined || (config.source?.pgpm !== undefined && !hasConnectionFlag(argv)),
+        perfBaseline: pick(argv['perf-baseline'], 'perf.baseline', config.perf?.baseline),
+        callGraphBaseline: pick(argv.baseline, 'callGraph.baseline', config.callGraph?.baseline),
+        outputs: {
+            json: pick(argv['write-json'], 'outputs.json', config.outputs?.json) ?? inDir('safegres.json'),
+            markdown: pick(argv['write-markdown'], 'outputs.markdown', config.outputs?.markdown)
+                ?? inDir('safegres.md'),
+            sarif: pick(argv['write-sarif'], 'outputs.sarif', config.outputs?.sarif) ?? inDir('safegres.sarif'),
+            sarifSources: pick(argv['sarif-sources'], 'outputs.sarifSources', config.outputs?.sarifSources),
+            snapshot: pick(argv['write-snapshot'], 'outputs.snapshot', config.outputs?.snapshot),
+            githubComment: pick(argv['write-github-comment'], 'outputs.githubComment', config.outputs?.githubComment)
+        }
+    };
+}
+/** Build config-loading params from shared CLI flags. */
+export function configParamsFromArgv(argv) {
+    const cliRules = parseRuleFlags(argv.rule);
+    const overrides = {};
+    if (cliRules)
+        overrides.rules = cliRules;
+    return {
+        configFile: typeof argv.config === 'string' ? argv.config : undefined,
+        preset: typeof argv.preset === 'string' ? argv.preset : undefined,
+        overrides: Object.keys(overrides).length > 0 ? overrides : undefined,
+        sealed: argv.sealed === true
+    };
+}

package/esm/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/esm/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { Logger } from '@pgpmjs/logger';
+import { CLI, getPackageJson } from 'inquirerer';
+import { commands } from './cli/commands';
+const log = new Logger('safegres');
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    const pkg = getPackageJson(__dirname);
+    process.stdout.write(`${pkg.version}\n`);
+    process.exit(0);
+}
+const options = {
+    minimistOpts: {
+        alias: { v: 'version', h: 'help', q: 'summary' },
+        boolean: [
+            'skip-ast',
+            'color',
+            'help',
+            'version',
+            'summary',
+            'verbose',
+            'call-graph',
+            'fail-on-new-boundaries',
+            'keep',
+            'list',
+            'json'
+        ],
+        string: [
+            'baseline',
+            'write-baseline',
+            'compare',
+            'compare-ref',
+            'compare-sha',
+            'compare-run-id',
+            'compare-run-url',
+            'compare-age',
+            'compare-skipped',
+            'write-snapshot',
+            'connection',
+            'host',
+            'user',
+            'password',
+            'database',
+            'schemas',
+            'exclude-schemas',
+            'ignore-extensions',
+            'roles',
+            'exclude-roles',
+            'format',
+            'fail-on',
+            'out',
+            'preset',
+            'corpus',
+            'case',
+            'provider',
+            'repo',
+            'base',
+            'head',
+            'workflow',
+            'artifact',
+            'dir'
+        ]
+    }
+};
+new CLI(commands, options).run().catch((error) => {
+    log.error(error);
+    process.exit(1);
+});

package/esm/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>;