@pipeline-builder/pipeline-data 4.3.3 → 4.3.5

package/lib/api/reporting/plugin-exposure.d.ts

@@ -1,3 +1,5 @@
+import { type PluginScanFinding, type VulnAcceptance } from '@pipeline-builder/api-core';
+import { type SQL } from 'drizzle-orm';
 import type { ExposureSource } from '../../database/schema/reporting-analytics.js';
 /** How far behind a resolved version is from the newest one available. */
 export type VersionGap = 'major' | 'minor' | 'patch' | 'none';
@@ -11,8 +13,14 @@ export interface ResolvedStep {
     pluginName: string;
     declaredVersion?: string | null;
     resolvedVersion?: string | null;
+    /** The resolved record: a `plugins` row id or a listing version id. */
+    resolvedPluginId?: string | null;
+    /** The image digest the resolved version is pinned to (null = image-less). */
+    resolvedDigest?: string | null;
     latestVersion?: string | null;
     withinPolicy?: boolean;
+    /** The root org of a team's pipeline (see the column). */
+    rootOrgId?: string | null;
 }
 /**
  * How far `resolved` is behind `latest`.
@@ -39,8 +47,17 @@ export declare function replacePipelineResolution(pipelineId: string, steps: rea
  * the instance that declares the plugin, and re-resolving each of those pipelines
  * from scratch would make publishing cost O(pipelines) work — so only the two
  * columns a publish can change are touched.
+ *
+ * `owner` says whose plugin it is: a listing (`publisher` handle — every org's
+ * pipelines that declare it, so the caller must be elevated), or an org's own
+ * plugin (`orgId` — that org's pipelines only: an org plugin's name is unique
+ * only within its org, so another org's same-named plugin is a different one).
  */
-export declare function refreshLatestForPlugin(pluginName: string, pluginPublisher: string | null, latestVersion: string): Promise<number>;
+export declare function refreshLatestForPlugin(pluginName: string, owner: {
+    publisher: string;
+} | {
+    orgId: string;
+}, latestVersion: string): Promise<number>;
 /** One flagged version, as the rescan reports it. */
 export interface ExposureInput {
     orgId: string;
@@ -53,11 +70,55 @@ export interface ExposureInput {
     criticalCount: number;
     highCount: number;
     topFindings?: Array<Record<string, unknown>>;
+    /** Every Critical/High finding key of the version (see the column). */
+    findingKeys?: string[];
+}
+/**
+ * Whether an exposure row is LIVE: not fixed, not dismissed as a false positive,
+ * and not under an acceptance that is still in force.
+ *
+ * The ONE predicate every reader uses (the report section, needs-attention, the
+ * org's open list). Two readers that disagree about what "exposed" means produce
+ * a report whose vulnerability panel and needs-attention list contradict each
+ * other — which is how this predicate came to exist. An acceptance LAPSES at its
+ * deadline and the row is live again; one with no deadline (which
+ * `triageExposure` refuses to write) is treated as in force, as every reader
+ * already did.
+ *
+ * `alias` is the table name or alias the caller's query uses.
+ */
+export declare function liveExposurePredicate(now: Date, alias?: string): SQL;
+/** What a version's scan state contributes to an exposure (see {@link exposureFromScan}). */
+export interface ScanState {
+    /** The digest the step runs. A scan summary describing another image is ignored. */
+    imageDigest?: string | null;
+    scanSummary?: unknown;
+    scanFlag?: unknown;
+    scanFlaggedAt?: Date | string | null;
+}
+/** The counts an exposure row carries. */
+export interface ExposureCounts {
+    criticalCount: number;
+    highCount: number;
+    topFindings: PluginScanFinding[];
+    /** Keys of EVERY Critical/High finding itemized (fixable or not), sorted. */
+    findingKeys: string[];
 }
+/**
+ * The exposure a version's scan state amounts to, or null when it has none.
+ *
+ * Reads the rescan's `scan_summary` (fixable Critical AND High, whether or not the
+ * gate tripped) and falls back to `scan_flag` for a version flagged before any
+ * summary was written. A summary whose digest is not the step's is IGNORED: a
+ * version rebuilt on a patched base is a different artifact, and its findings say
+ * nothing about the image the pipeline runs. Only FIXABLE findings count — an
+ * exposure is something a rebuild or an upgrade can clear.
+ */
+export declare function exposureFromScan(state: ScanState): ExposureCounts | null;
 /**
  * Open or refresh exposures.
  *
- * Upserts on (pipeline, plugin, version, source) so a nightly rescan REFRESHES the
+ * Upserts on (pipeline, plugin, version, digest, source) so a nightly rescan REFRESHES the
  * counts rather than opening a new row every night — otherwise the report would
  * show one exposure per night of the same problem, which reads as an escalating
  * situation when nothing changed.
@@ -68,18 +129,117 @@ export interface ExposureInput {
  * acceptance, because that is what the deadline was for.
  */
 export declare function upsertExposures(inputs: readonly ExposureInput[], now?: Date): Promise<number>;
+/** One version a pipeline still declares / runs WITH open findings. */
+export interface LiveVersion {
+    pluginName: string;
+    pluginVersion: string;
+    imageDigest?: string | null;
+}
 /**
- * Close the exposures a pipeline has moved off.
+ * Close the exposures of one SOURCE a pipeline has moved off — `fixed` when the
+ * pipeline still uses the plugin at another version, `removed` when no live step
+ * uses the plugin at all (the triage fields stay, so a re-added step gets an
+ * unexpired acceptance back — see {@link upsertExposures}).
  *
- * Called when a deploy records a new step manifest: anything flagged for that
- * pipeline whose version is NOT in the set it now runs is fixed. Closing by
+ * Called when a deploy records a new step manifest (`deployed`) or a pipeline
+ * write re-resolves its config (`declared`): anything open for that pipeline and
+ * source whose (version, digest) is NOT in `liveVersions` is fixed. Closing by
  * absence rather than waiting for a rescan to notice is what makes "we fixed it"
  * show up in the report on the next deploy instead of the next night.
+ *
+ * Per source, because the two sides move independently: a config updated to the
+ * fixed version closes the DECLARED exposure while the old image keeps running,
+ * and its DEPLOYED exposure must stay open until the deploy lands.
+ */
+export declare function closeFixedExposures(pipelineId: string, source: ExposureSource, liveVersions: readonly LiveVersion[], now?: Date, opts?: {
+    livePlugins?: readonly string[];
+}): Promise<number>;
+/**
+ * Close every open exposure of a pipeline (or of one source) as `removed` — the
+ * pipeline was deleted, or deregistered (its deploy is gone). The triage fields
+ * stay: a restore re-records the pipeline's resolution, and
+ * {@link upsertExposures} reopens the rows (restoring an acceptance still in
+ * force). Returns the rows closed.
+ */
+export declare function closePipelineExposures(pipelineId: string, state: 'removed', opts?: {
+    source?: ExposureSource;
+}, now?: Date): Promise<number>;
+/** One step of a pipeline as {@link reconcilePipelineExposures} takes it. */
+export interface ExposureStep {
+    pluginPublisher?: string | null;
+    pluginName: string;
+    pluginVersion: string;
+    imageDigest?: string | null;
+    /** The resolved version's scan state, as stored on its row. */
+    scan: ScanState;
+}
+/**
+ * Bring one pipeline's exposures of one source in line with the steps it now
+ * declares (`declared`) or runs (`deployed`): open / refresh a row for every step
+ * whose version has open fixable findings, close the rest by absence.
+ *
+ * Never throws — exposure tracking is reporting, and a pipeline write or a deploy
+ * registration must not fail because the report table could not be written.
  */
-export declare function closeFixedExposures(pipelineId: string, liveVersions: ReadonlyArray<{
+export declare function reconcilePipelineExposures(input: {
+    orgId: string;
+    pipelineId: string;
+    source: ExposureSource;
+    steps: readonly ExposureStep[];
+}, now?: Date): Promise<{
+    opened: number;
+    closed: number;
+}>;
+/** A plugin version (optionally one image of it) whose pipelines are wanted. */
+export interface PluginVersionRef {
     pluginName: string;
     pluginVersion: string;
-}>, now?: Date): Promise<number>;
+    /** Listing publisher handle; null = an org's own plugin row; omitted = either. */
+    pluginPublisher?: string | null;
+    /** Narrow to pipelines on this image. Omitted = any image of the version. */
+    imageDigest?: string | null;
+    /** Narrow to these orgs. Omitted = every org the caller's scope can read. */
+    orgIds?: readonly string[];
+}
+/** A pipeline that declares or runs a given plugin version. */
+export interface PipelineOnVersion {
+    orgId: string;
+    pipelineId: string;
+    pipelineName: string | null;
+    /** `deployed` = its last deploy's step manifest; `declared` = its config resolves to it. */
+    source: ExposureSource;
+    pluginPublisher: string | null;
+    imageDigest: string | null;
+    /** The steps on it: `synth` or `<stage>/<step>` (declared) / `<stage>/<action>` (deployed). */
+    steps: string[];
+}
+/**
+ * Every LIVE pipeline declaring (`pipeline_plugin_resolution`) or running
+ * (`pipeline_step_manifests`) a plugin version, one entry per (pipeline, source)
+ * with the steps on it. A soft-deleted pipeline is NOT affected: counting it
+ * would put a pipeline nobody can open into a notice or a report. Reads under
+ * the CALLER's tenant scope: an org-scoped caller sees its own pipelines, the
+ * rescan (elevated) sees every org's.
+ */
+export declare function pipelinesOnVersion(ref: PluginVersionRef): Promise<PipelineOnVersion[]>;
+/**
+ * The rescan's entry point: one rescanned version's findings, fanned out to every
+ * pipeline that declares or runs it.
+ *
+ * A version with open fixable findings opens / refreshes one exposure per
+ * (pipeline, source); a version that came back CLEAN closes every open exposure
+ * on it (`fixed`), so a rebuild-in-place or an advisory withdrawn upstream shows
+ * as fixed on the next night rather than lingering until each pipeline redeploys.
+ *
+ * Must run with a scope that can read and write every org's rows (the rescan's
+ * elevated context). Never throws.
+ */
+export declare function syncVersionExposures(ref: PluginVersionRef, scan: ScanState, now?: Date): Promise<{
+    opened: number;
+    closed: number;
+}>;
+/** Close every open exposure on a version (optionally one image of it). */
+export declare function closeVersionExposures(ref: PluginVersionRef, now?: Date): Promise<number>;
 /**
  * The org's live exposures, for the report section.
  *
@@ -99,20 +259,106 @@ export declare function openExposures(orgId: string): Promise<Array<{
     triageState: string;
     flaggedAt: Date;
 }>>;
+/** One exposure row as the per-pipeline security views read it. */
+export interface PipelineExposure {
+    id: string;
+    orgId: string;
+    pipelineId: string;
+    pluginPublisher: string | null;
+    pluginName: string;
+    pluginVersion: string;
+    imageDigest: string | null;
+    source: ExposureSource;
+    criticalCount: number;
+    highCount: number;
+    topFindings: Array<Record<string, unknown>>;
+    findingKeys: string[];
+    /** As stored; an `accepted` row past its deadline reads `open` (see {@link liveExposurePredicate}). */
+    triageState: string;
+    /** An acceptance still in force right now. */
+    acceptanceActive: boolean;
+    acceptedUntil: Date | null;
+    acceptedFindingKeys: string[];
+    acceptedKev: boolean;
+    triageReason: string | null;
+    triagedBy: string | null;
+    triagedAt: Date | null;
+    flaggedAt: Date;
+    fixedAt: Date | null;
+}
 /**
- * Record a triage decision.
- *
- * `accepted` REQUIRES a deadline and a reason. A permanent, unexplained mute is
- * how a finding stops being anybody's problem, and there is no good reason to
- * support it — the caller gets an error rather than a silently unbounded
- * acceptance.
+ * One pipeline's exposures: the unfixed ones (open, accepted, false positive),
+ * plus the fixed ones when asked — most severe first. Reads under the CALLER's
+ * scope, narrowed to `orgId`.
  */
-export declare function triageExposure(orgId: string, id: string, decision: {
+export declare function pipelineExposures(orgId: string, pipelineId: string, opts?: {
+    includeFixed?: boolean;
+    now?: Date;
+}): Promise<PipelineExposure[]>;
+/** One exposure row of `orgId`, or null. */
+export declare function exposureById(orgId: string, id: string, now?: Date): Promise<PipelineExposure | null>;
+/** A triage decision. */
+export interface TriageDecision {
     state: 'open' | 'accepted' | 'false_positive';
     reason?: string;
     acceptedUntil?: Date;
+    /** Accept KEV-listed findings too. Never implied: an acceptance without it does not cover them. */
+    kev?: boolean;
     actor: string;
-}): Promise<boolean>;
+}
+/**
+ * Record a triage decision on one exposure — and on its SIBLINGS: the same
+ * pipeline's other open row for the same version and image (the declared and
+ * the deployed side). A risk decision is about what the pipeline runs, and
+ * leaving one side open would have the report and the lookup disagree.
+ *
+ * `accepted` REQUIRES a deadline and a reason. A permanent, unexplained mute is
+ * how a finding stops being anybody's problem, and there is no good reason to
+ * support it — the caller gets an error rather than a silently unbounded
+ * acceptance. The accepted finding keys are FROZEN at the decision: an
+ * acceptance covers what was there when it was made, never a finding since.
+ *
+ * Returns the updated rows (empty when `id` is not `orgId`'s unfixed exposure).
+ */
+export declare function triageExposure(orgId: string, id: string, decision: TriageDecision): Promise<PipelineExposure[]>;
+/** `name@version@digest` — the key {@link activeAcceptances} answers under. */
+export declare const acceptanceKey: (pluginName: string, pluginVersion: string, imageDigest?: string | null) => string;
+/** A pipeline's acceptances in force, keyed by {@link acceptanceKey}, plus the accepted versions per plugin. */
+export interface PipelineAcceptances {
+    byKey: Map<string, VulnAcceptance & {
+        exposureIds: string[];
+    }>;
+    /** `pluginName` → versions with an acceptance (the resolver's `acceptedVersions` hint). */
+    versionsByPlugin: Map<string, Set<string>>;
+}
+/**
+ * The acceptances IN FORCE for one pipeline (`accepted`, unfixed, deadline in the
+ * future), merged per version and image: the union of the finding keys the rows
+ * froze, KEV only when every merged row accepted it. Reads under the caller's
+ * scope narrowed to `orgId`; a failed read is "no acceptance" — the stricter answer.
+ */
+export declare function activeAcceptances(orgId: string, pipelineId: string, now?: Date): Promise<PipelineAcceptances>;
+/** An acceptance that lapsed, as {@link reopenLapsedAcceptances} returns it. */
+export interface LapsedAcceptance {
+    id: string;
+    orgId: string;
+    pipelineId: string;
+    pluginPublisher: string | null;
+    pluginName: string;
+    pluginVersion: string;
+    imageDigest: string | null;
+    triagedBy: string | null;
+    triageReason: string | null;
+    acceptedUntil: Date | null;
+}
+/**
+ * Reopen every acceptance whose deadline has passed, and return them so the
+ * pipeline owners can be told (N33). Readers already treat such a row as open;
+ * writing it makes the stored state the truth and gives the notice exactly one
+ * moment to fire. Must run with a scope that can write every org's rows (the
+ * nightly rescan's elevated context). Never throws.
+ */
+export declare function reopenLapsedAcceptances(now?: Date): Promise<LapsedAcceptance[]>;
 /**
  * Exposures whose acceptance has lapsed, for the org's security notifications.
  *