@safegres/test 0.0.1 → 1.30.7

package/score/score.d.ts

@@ -0,0 +1,84 @@
+import type { Grade, ScoringConfig } from '../config/types';
+import type { Finding, Severity } from '../types';
+export interface ScoreDeduction {
+    code: string;
+    count: number;
+    points: number;
+    /**
+     * What the audit would score if this rule were its only problem — the same
+     * curve applied to this rule's points alone. Grades the rule rather than
+     * the database.
+     */
+    score: number;
+    grade: Grade;
+    /**
+     * Score the audit would *gain* by taking this rule to zero. Not
+     * interchangeable with `score`: because the curve is exponential a rule's
+     * payoff depends on how much other debt exists, so the same fix is worth
+     * more once the rest is clean.
+     */
+    potential: number;
+    /**
+     * The rule contributes no points by construction — every finding is
+     * `info`-weighted or fail-closed. Reported so a run cannot imply that
+     * fixing them would move the score; it cannot.
+     */
+    unscored?: boolean;
+    /**
+     * The rule's raw points exceeded `maxRuleDensity` and were cut to it. The
+     * finding count is unchanged: what is capped is the rule's influence on the
+     * score, not the size of the problem it reports.
+     */
+    capped?: boolean;
+    /**
+     * Distinct units of repair behind `count`, when a rule declares one
+     * (`RuleMeta.dedupBy`). Points are charged per unit, so a rule that emits
+     * one finding per (relation × function) pair costs what fixing it costs.
+     */
+    units?: number;
+}
+export interface Score {
+    /** 0-100. */
+    value: number;
+    grade: Grade;
+    /** Scoring model identifier ('density' or 'weighted'). */
+    model: string;
+    /**
+     * Every rule that produced a scorable finding, largest deduction first,
+     * with its own score, grade and payoff-to-fix. Rules that contribute no
+     * points (info-weighted, fail-closed) are listed last and flagged
+     * `unscored` rather than omitted — a report that silently drops them
+     * implies that fixing them would help, and it would not.
+     */
+    deductions: ScoreDeduction[];
+    /** Density model: risk points per exposed table. */
+    density?: number;
+    /** Density model: the exposed-table denominator. */
+    exposedTables?: number;
+    /** True when the score was capped because no exposure surface was known. */
+    cappedByUnknownExposure?: boolean;
+}
+/** Context the audit supplies for exposure-aware scoring. */
+export interface ScoreContext {
+    /** Number of tables on the exposed surface (the density denominator). */
+    exposedTables?: number;
+    /** Whether an exposure surface was configured/resolved. */
+    exposureKnown?: boolean;
+    /**
+     * The caller has already decided which findings count (a scorecard's
+     * selector). Skips the built-in exposure/acknowledgement/meta filtering,
+     * which would otherwise silently overrule a selector that asked for
+     * unexposed findings.
+     */
+    prefiltered?: boolean;
+}
+export declare const DEFAULT_WEIGHTS: Record<Severity, number>;
+export declare const DEFAULT_GRADE_BANDS: Record<Exclude<Grade, 'F'>, number>;
+/**
+ * Compute the audit score. The score is config-driven by design: disabling
+ * or retuning rules changes the findings and therefore the score, and only
+ * findings on the exposed surface count (see `Finding.exposed`).
+ */
+export declare function computeScore(findings: Finding[], config?: ScoringConfig, context?: ScoreContext): Score;
+/** True when `grade` is at least as good as `minimum`. */
+export declare function meetsGrade(grade: Grade, minimum: Grade): boolean;

package/score/score.js

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GRADE_BANDS = exports.DEFAULT_WEIGHTS = void 0;
+exports.computeScore = computeScore;
+exports.meetsGrade = meetsGrade;
+const registry_1 = require("../rules/registry");
+const types_1 = require("../types");
+exports.DEFAULT_WEIGHTS = {
+    critical: 25,
+    high: 10,
+    medium: 4,
+    low: 1,
+    info: 0
+};
+exports.DEFAULT_GRADE_BANDS = {
+    'A+': 97,
+    A: 90,
+    B: 80,
+    C: 65,
+    D: 50
+};
+const DEFAULT_MAX_DEDUCTION_PER_RULE = 40;
+const DEFAULT_MAX_RULE_DENSITY = 0.5;
+const DEFAULT_DENSITY_K = 0.17;
+const DEFAULT_UNKNOWN_EXPOSURE_CAP = 80;
+const DEFAULT_FAIL_CLOSED_WEIGHT = 0;
+/**
+ * Compute the audit score. The score is config-driven by design: disabling
+ * or retuning rules changes the findings and therefore the score, and only
+ * findings on the exposed surface count (see `Finding.exposed`).
+ */
+function computeScore(findings, config = {}, context = {}) {
+    const model = config.model ?? 'density';
+    return model === 'weighted'
+        ? computeWeightedScore(findings, config, context)
+        : computeDensityScore(findings, config, context);
+}
+/**
+ * Density scoring: severity-weighted *scorable* findings per exposed table
+ * with exponential falloff — does not saturate on large schemas.
+ *
+ *   score = 100 · exp(−k · riskPoints / exposedTables)
+ *
+ * Scorable findings are those on the exposed surface (`exposed !== false`)
+ * that are not fail-closed (fail-closed weights are multiplied by
+ * `failClosedWeight`, default 0 — denied-at-runtime hygiene doesn't reduce
+ * the score). With the default k, one critical per ~10 exposed tables lands
+ * around a C; one critical per table is an F.
+ *
+ * Two things keep a rule's *shape* out of the arithmetic. Points are charged
+ * per unit of repair, not per finding, for rules that declare one — a rule
+ * emitting a row per (relation × function) pair costs what fixing it costs.
+ * And each rule's total is capped at a fraction of the points that would fail
+ * an audit alone (`maxRuleDensity`), so no single rule can decide the grade.
+ */
+function computeDensityScore(findings, config, context) {
+    const weights = { ...exports.DEFAULT_WEIGHTS, ...(config.weights ?? {}) };
+    const perRule = config.perRuleWeights ?? {};
+    const bands = { ...exports.DEFAULT_GRADE_BANDS, ...(config.gradeBands ?? {}) };
+    const floor = config.floorOnCritical === undefined ? 'C' : config.floorOnCritical;
+    const k = config.densityK ?? DEFAULT_DENSITY_K;
+    const failClosedWeight = config.failClosedWeight ?? DEFAULT_FAIL_CLOSED_WEIGHT;
+    // Meta findings (e.g. W1) are advisories about the audit itself — the
+    // unknown-exposure cap is their penalty, not weighted points.
+    const scorable = context.prefiltered
+        ? findings
+        : findings.filter((f) => f.exposed !== false && !f.acknowledged && f.category !== 'meta');
+    const exposedTables = Math.max(1, context.exposedTables ?? 1);
+    const byRule = new Map();
+    for (const f of scorable) {
+        let weight = perRule[f.code] ?? weights[f.severity] ?? 0;
+        if (f.direction === 'fail-closed')
+            weight *= failClosedWeight;
+        const entry = byRule.get(f.code) ?? { count: 0, points: 0, units: new Set() };
+        entry.count += 1;
+        // A rule with a declared unit of repair is charged once per unit: the
+        // second finding against the same function is the same fix, and letting
+        // it charge again grades fan-out rather than risk.
+        const unit = repairUnit(f);
+        if (unit === undefined || !entry.units.has(unit)) {
+            entry.points += Math.max(0, weight);
+            if (unit !== undefined)
+                entry.units.add(unit);
+        }
+        byRule.set(f.code, entry);
+    }
+    // No single rule may contribute more than `maxRuleDensity` of the points
+    // that would take the score to F alone — at the default half, one rule can
+    // cost two grade bands but an F still takes breadth. Solved from the curve
+    // rather than fixed, so retuning `k` or the bands moves the cap with them.
+    const maxRuleDensity = config.maxRuleDensity ?? DEFAULT_MAX_RULE_DENSITY;
+    const pointsToF = (Math.log(100 / (bands.D || 50)) / k) * exposedTables;
+    const ruleCap = maxRuleDensity === false ? Infinity : maxRuleDensity * pointsToF;
+    const capped = new Map();
+    for (const [code, tally] of byRule) {
+        capped.set(code, {
+            count: tally.count,
+            points: Math.min(tally.points, ruleCap),
+            raw: tally.points,
+            ...(tally.units.size > 0 ? { units: tally.units.size } : {})
+        });
+    }
+    const riskPoints = [...capped.values()].reduce((sum, r) => sum + r.points, 0);
+    const density = riskPoints / exposedTables;
+    const curve = (points) => round1(100 * Math.exp((-k * points) / exposedTables));
+    let value = round1(100 * Math.exp(-k * density));
+    const deductions = [...capped.entries()]
+        .map(([code, { count, points, raw, units }]) => ({
+        code,
+        count,
+        points,
+        score: curve(points),
+        grade: gradeFor(curve(points), bands),
+        potential: round1(curve(riskPoints - points) - value),
+        ...(units !== undefined && units !== count ? { units } : {}),
+        ...(raw > points ? { capped: true } : {}),
+        ...(points === 0 ? { unscored: true } : {})
+    }))
+        .sort(byPayoff);
+    const unknownCap = config.unknownExposureCap ?? DEFAULT_UNKNOWN_EXPOSURE_CAP;
+    const cappedByUnknown = context.exposureKnown === false && unknownCap !== false && value > unknownCap;
+    if (cappedByUnknown)
+        value = unknownCap;
+    let grade = gradeFor(value, bands);
+    if (floor
+        && scorable.some((f) => f.direction !== 'fail-closed' && (0, types_1.meetsThreshold)(f.severity, 'critical'))) {
+        grade = worseOf(grade, floor);
+    }
+    return {
+        value,
+        grade,
+        model: 'density',
+        deductions,
+        density: Math.round(density * 1000) / 1000,
+        exposedTables,
+        ...(cappedByUnknown ? { cappedByUnknownExposure: true } : {})
+    };
+}
+/**
+ * The finding's unit of repair, from the rule's declared `dedupBy` path.
+ * `undefined` when the rule declares none — one finding, one unit.
+ */
+function repairUnit(finding) {
+    const path = registry_1.RULES_BY_CODE.get(finding.code)?.dedupBy;
+    if (!path)
+        return undefined;
+    let value = finding;
+    for (const key of path.split('.')) {
+        if (value === null || typeof value !== 'object')
+            return undefined;
+        value = value[key];
+    }
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Legacy weighted-deduction scoring (Lighthouse-style): each finding deducts
+ * points by severity (or per-rule override), capped per rule so one noisy
+ * rule can't zero the score alone. Any critical finding floors the grade
+ * (default 'C'). Saturates on large schemas — prefer the density model.
+ */
+function computeWeightedScore(findings, config, context) {
+    const weights = { ...exports.DEFAULT_WEIGHTS, ...(config.weights ?? {}) };
+    const perRule = config.perRuleWeights ?? {};
+    const cap = config.maxDeductionPerRule ?? DEFAULT_MAX_DEDUCTION_PER_RULE;
+    const bands = { ...exports.DEFAULT_GRADE_BANDS, ...(config.gradeBands ?? {}) };
+    const floor = config.floorOnCritical === undefined ? 'C' : config.floorOnCritical;
+    const scorable = context.prefiltered
+        ? findings
+        : findings.filter((f) => f.exposed !== false && !f.acknowledged && f.category !== 'meta');
+    const byRule = new Map();
+    for (const f of scorable) {
+        const weight = perRule[f.code] ?? weights[f.severity] ?? 0;
+        const entry = byRule.get(f.code) ?? { count: 0, points: 0 };
+        entry.count += 1;
+        entry.points += weight;
+        byRule.set(f.code, entry);
+    }
+    const byRuleCapped = [...byRule.entries()].map(([code, { count, points }]) => [code, { count, points: Math.min(points, cap) }]);
+    const total = byRuleCapped.reduce((sum, [, r]) => sum + r.points, 0);
+    let value = Math.max(0, round1(100 - total));
+    const remainder = (points) => Math.max(0, round1(100 - (total - points)));
+    const deductions = byRuleCapped
+        .map(([code, { count, points }]) => ({
+        code,
+        count,
+        points,
+        score: Math.max(0, round1(100 - points)),
+        grade: gradeFor(Math.max(0, round1(100 - points)), bands),
+        potential: round1(remainder(points) - value),
+        ...(points === 0 ? { unscored: true } : {})
+    }))
+        .sort(byPayoff);
+    const unknownCap = config.unknownExposureCap ?? DEFAULT_UNKNOWN_EXPOSURE_CAP;
+    const capped = context.exposureKnown === false && unknownCap !== false && value > unknownCap;
+    if (capped)
+        value = unknownCap;
+    let grade = gradeFor(value, bands);
+    if (floor && scorable.some((f) => (0, types_1.meetsThreshold)(f.severity, 'critical'))) {
+        grade = worseOf(grade, floor);
+    }
+    return {
+        value,
+        grade,
+        model: 'weighted',
+        deductions,
+        ...(capped ? { cappedByUnknownExposure: true } : {})
+    };
+}
+function round1(n) {
+    return Math.round(n * 10) / 10;
+}
+/**
+ * Scored rules first, largest deduction at the top; unscored rules last, in
+ * code order. Points and payoff rank identically under a monotone curve, so
+ * this keeps the existing "top deductions" output stable.
+ */
+function byPayoff(a, b) {
+    if (!!a.unscored !== !!b.unscored)
+        return a.unscored ? 1 : -1;
+    return b.points - a.points || a.code.localeCompare(b.code);
+}
+const GRADE_ORDER = ['A+', 'A', 'B', 'C', 'D', 'F'];
+function gradeFor(value, bands) {
+    for (const grade of GRADE_ORDER) {
+        if (grade === 'F')
+            break;
+        if (value >= bands[grade])
+            return grade;
+    }
+    return 'F';
+}
+function worseOf(a, b) {
+    return GRADE_ORDER.indexOf(a) >= GRADE_ORDER.indexOf(b) ? a : b;
+}
+/** True when `grade` is at least as good as `minimum`. */
+function meetsGrade(grade, minimum) {
+    return GRADE_ORDER.indexOf(grade) <= GRADE_ORDER.indexOf(minimum);
+}

package/score/scorecards.d.ts

@@ -0,0 +1,68 @@
+import type { ScorecardConfig, ScorecardSelector } from '../config/types';
+import { type Finding, type Summary } from '../types';
+import { type Score, type ScoreContext } from './score';
+/**
+ * One named score over a selected slice of the findings.
+ *
+ * The headline score answers one question well and every other question
+ * badly: a platform team gating on what `anonymous` reaches and an
+ * application team gating on house style are not arguing about the same
+ * number, and forcing them to is how a single number becomes something
+ * nobody trusts. A scorecard is that question, written down — a selector
+ * over the findings plus the weighting to grade them with.
+ */
+export interface ScorecardReport {
+    /** Config key, e.g. `anon-surface`. */
+    name: string;
+    /** Human-readable heading for reports. */
+    title?: string;
+    /**
+     * Why this scorecard exists — what decision it informs. Rendered with the
+     * score, because a number whose question is unstated invites the reader to
+     * supply their own.
+     */
+    description?: string;
+    /** The findings it selected, graded by its own weighting. */
+    score: Score;
+    /** How many findings the selector matched. */
+    findings: number;
+    /** Severity counts over the selected findings. */
+    summary: Summary;
+    /** The resolved selector, so a report explains its own arithmetic. */
+    select: ScorecardSelector;
+    /**
+     * Reserved scorecards safegres computes itself: `default` is the headline
+     * (`report.score`, verbatim) and `raw` is every finding at its declared
+     * severity with no exposure filter. Neither can be redefined into
+     * something flattering.
+     */
+    reserved?: boolean;
+}
+export interface ScorecardContext extends ScoreContext {
+    /** Relations on the exposed surface — the default density denominator. */
+    exposedTables?: number;
+    /** Every relation in the audited schemas — the `all` denominator. */
+    totalTables?: number;
+}
+/**
+ * The two scorecards every run carries, whatever the config says.
+ *
+ * `raw` is the honest one: no exposure filter, no acknowledgements, no
+ * preset severity retuning, fail-closed findings weighted like anything
+ * else. It is not flattering and it is not meant to be — it is the number
+ * that is comparable between two databases, and the one a preset cannot
+ * talk down.
+ */
+export declare const RESERVED_SCORECARDS: Record<string, ScorecardConfig>;
+/**
+ * Grade each configured scorecard. `default` is not recomputed — it is the
+ * headline score passed in, so a scorecard block can never move the number
+ * on the badge by redefining what `default` means.
+ */
+export declare function computeScorecards(findings: Finding[], headline: Score, cards: Record<string, ScorecardConfig>, context: ScorecardContext): ScorecardReport[];
+/**
+ * The findings a scorecard grades. Every clause is a narrowing filter, so an
+ * empty selector selects what the headline does: exposed, non-acknowledged,
+ * security findings.
+ */
+export declare function selectFindings(findings: Finding[], select: ScorecardSelector): Finding[];

package/score/scorecards.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESERVED_SCORECARDS = void 0;
+exports.computeScorecards = computeScorecards;
+exports.selectFindings = selectFindings;
+const registry_1 = require("../rules/registry");
+const types_1 = require("../types");
+const score_1 = require("./score");
+/**
+ * The two scorecards every run carries, whatever the config says.
+ *
+ * `raw` is the honest one: no exposure filter, no acknowledgements, no
+ * preset severity retuning, fail-closed findings weighted like anything
+ * else. It is not flattering and it is not meant to be — it is the number
+ * that is comparable between two databases, and the one a preset cannot
+ * talk down.
+ */
+exports.RESERVED_SCORECARDS = {
+    default: {
+        title: 'Safegres score',
+        description: 'The headline: exposed, fail-open findings at their configured severities.'
+    },
+    raw: {
+        title: 'Raw score',
+        description: 'Every finding at its declared severity, exposure ignored — comparable across databases.',
+        select: {
+            severities: 'declared',
+            exposure: 'all',
+            acknowledged: 'include',
+            denominator: 'all'
+        },
+        failClosedWeight: 1,
+        maxRuleDensity: false
+    }
+};
+/**
+ * Grade each configured scorecard. `default` is not recomputed — it is the
+ * headline score passed in, so a scorecard block can never move the number
+ * on the badge by redefining what `default` means.
+ */
+function computeScorecards(findings, headline, cards, context) {
+    const out = [];
+    for (const [name, card] of Object.entries(cards)) {
+        const reserved = name in exports.RESERVED_SCORECARDS;
+        const select = { ...(exports.RESERVED_SCORECARDS[name]?.select ?? {}), ...(card.select ?? {}) };
+        if (name === 'default') {
+            out.push({
+                name,
+                ...titleOf(name, card),
+                score: headline,
+                findings: findings.filter((f) => f.exposed !== false && !f.acknowledged).length,
+                summary: (0, types_1.summarize)(findings.filter((f) => f.exposed !== false && !f.acknowledged)),
+                select,
+                reserved: true
+            });
+            continue;
+        }
+        const selected = selectFindings(findings, select);
+        const denominator = select.denominator === 'all'
+            ? (context.totalTables ?? context.exposedTables)
+            : context.exposedTables;
+        out.push({
+            name,
+            ...titleOf(name, card),
+            score: (0, score_1.computeScore)(selected, card, {
+                ...context,
+                exposedTables: denominator,
+                // The selector has already decided what counts; scoring must not
+                // filter again, or `exposure: 'all'` would be silently overruled.
+                prefiltered: true
+            }),
+            findings: selected.length,
+            summary: (0, types_1.summarize)(selected),
+            select,
+            ...(reserved ? { reserved: true } : {})
+        });
+    }
+    return out;
+}
+function titleOf(name, card) {
+    const base = exports.RESERVED_SCORECARDS[name] ?? {};
+    const title = card.title ?? base.title;
+    const description = card.description ?? base.description;
+    return { ...(title ? { title } : {}), ...(description ? { description } : {}) };
+}
+/**
+ * The findings a scorecard grades. Every clause is a narrowing filter, so an
+ * empty selector selects what the headline does: exposed, non-acknowledged,
+ * security findings.
+ */
+function selectFindings(findings, select) {
+    const dimension = select.dimension ?? 'security';
+    const rules = select.rules?.map(matcher);
+    const exclude = select.exclude?.map(matcher);
+    const roles = select.roles ? new Set(select.roles) : undefined;
+    const planes = select.planes ? new Set(select.planes) : undefined;
+    const schemas = select.schemas ? new Set(select.schemas) : undefined;
+    const severity = select.minSeverity ? SEVERITY_RANK[select.minSeverity] : undefined;
+    const selected = findings.filter((f) => {
+        if (f.category === 'meta')
+            return false;
+        if (dimension !== 'all' && (f.dimension ?? 'security') !== dimension)
+            return false;
+        if (select.exposure !== 'all' && f.exposed === false)
+            return false;
+        if (select.acknowledged !== 'include' && f.acknowledged)
+            return false;
+        if (select.direction && select.direction !== 'any' && f.direction !== select.direction) {
+            return false;
+        }
+        if (rules && !rules.some((m) => m(f.code)))
+            return false;
+        if (exclude?.some((m) => m(f.code)))
+            return false;
+        if (schemas && (f.schema === undefined || !schemas.has(f.schema)))
+            return false;
+        if (roles && !touchesRole(f, roles))
+            return false;
+        if (planes && !f.planes?.some((p) => planes.has(p)))
+            return false;
+        if (severity !== undefined && SEVERITY_RANK[f.severity] < severity)
+            return false;
+        return true;
+    });
+    // Declared severities answer "how bad is this really", independent of what
+    // a preset chose to quiet down. Copies, never mutation: the findings in
+    // the report keep the severity the config resolved.
+    return select.severities === 'declared'
+        ? selected.map((f) => {
+            const declared = registry_1.RULES_BY_CODE.get(f.code)?.defaultSeverity;
+            return declared === undefined || declared === f.severity ? f : { ...f, severity: declared };
+        })
+        : selected;
+}
+const SEVERITY_RANK = {
+    info: 0,
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4
+};
+/**
+ * A role clause asks "is this finding about one of these roles" — which the
+ * finding answers in one of three places: the graded `role` column, a
+ * grantee list, or the reachability context a lattice rule attached.
+ */
+function touchesRole(finding, roles) {
+    if (finding.role && roles.has(finding.role))
+        return true;
+    const context = finding.context;
+    if (context?.role && roles.has(context.role))
+        return true;
+    return Array.isArray(context?.roles)
+        && context.roles.some((r) => typeof r === 'string' && roles.has(r));
+}
+/** Rule code matcher: exact, or a `C*` prefix wildcard. */
+function matcher(pattern) {
+    if (!pattern.endsWith('*'))
+        return (code) => code === pattern;
+    const prefix = pattern.slice(0, -1);
+    return (code) => code.startsWith(prefix);
+}