snyk-docker-plugin/dist/analyzer/layer-attribution.d.ts

Snyk CLI docker plugin

import { ExtractedLayers, HistoryEntry } from "../extractor/types";
import { AnalysisType, ImagePackagesAnalysis, IntroducingLayerByPackage, OSRelease } from "./types";
/**
 * Checks whether the OCI "non-empty history entries map 1:1 to
 * `rootfs.diff_ids[]`" rule holds for this image. Returns a warning
 * string when it does not, otherwise `undefined`.
 *
 * The plugin's own per-package attribution path is keyed by diffID and
 * does not depend on `history` alignment — those labels are correct
 * either way. The backend performs the diffID -> `createdBy` join at
 * read time using the separately-emitted `rootFs` and `history` facts,
 * and it is the backend's responsibility to detect misalignment and
 * decide whether to surface instruction text. The plugin only emits a
 * warning so a human running a scan can see "instructions may not be
 * shown" without needing to dig into backend logs.
 *
 * Alignment failure is silent at the OCI level — there is no shared key
 * between `history` and `diff_ids[]`. Length equality is the only signal
 * available, and it is notoriously fragile across squash builds,
 * `docker save` round-trips, and some non-Docker builders (Jib, ko,
 * apko, Bazel `rules_docker`).
 *
 * @param history `null`/`undefined` is treated as "no history to align
 *   against," which is not an error — there is simply nothing
 *   to join. Only a length mismatch between non-empty history
 *   entries and rootfs layers produces a warning.
 */
export declare function checkHistoryAlignment(rootFsLayers: string[], history: HistoryEntry[] | null | undefined): string | undefined;
/**
 * Computes per-package layer attribution for a single OS package manager
 * (Apk, Apt, Rpm, or Chisel). Returns the `<fullName>@<version>` -> diffID
 * map for every package present in the *final* layer's DB.
 *
 * Earlier introductions whose copies were later removed do not appear in
 * the result. The OS package manager dedupes, so for OS ecosystems each
 * surviving key has exactly one introducing layer (the most recent layer
 * to install or reinstall the surviving copy).
 *
 * The image-wide orchestrator is `computeOsLayerAttribution`; call this
 * directly only when you already know the target ecosystem.
 */
export declare function computeOsPackageManagerLayerAttribution(orderedLayers: ExtractedLayers[], analysisType: AnalysisType, diffIDs: string[], targetImage: string, osRelease: OSRelease | undefined, redHatRepositories: string[]): Promise<IntroducingLayerByPackage>;
/**
 * Result of image-wide OS-package layer attribution.
 *
 * `warnings` are human-readable, non-fatal messages (currently only a
 * failure to attribute the image's OS package manager). They share the
 * string shape of `checkHistoryAlignment`'s return value so a caller can
 * collect both into one list (e.g. the `pluginWarnings` fact).
 * `introducingLayerByPackage` is always usable; warnings only flag that
 * coverage may be incomplete.
 */
export interface OsLayerAttribution {
    introducingLayerByPackage: IntroducingLayerByPackage;
    warnings: string[];
}
/**
 * Image-wide OS-package layer attribution. Produces the
 * `<fullName>@<version>` -> diffID map for the image's OS packages,
 * returning any non-fatal warnings alongside it (see `OsLayerAttribution`).
 *
 * Attribution must annotate the *same* package set the OS dep graph
 * contains, and that dep graph is built from a single `ImagePackagesAnalysis`
 * — `parseAnalysisResults` selects it via `selectPrimaryPackageAnalysis`
 * ("first non-empty result wins") and discards the rest. So we select the
 * primary analysis the exact same way here, attributing only that ecosystem.
 * Re-deriving our own ecosystem list (e.g. attributing every non-empty
 * analysis) would risk producing keys for an ecosystem the dep graph dropped,
 * or — if the selection rules ever diverged — silently mis-attributing;
 * routing both through `selectPrimaryPackageAnalysis` makes that drift
 * impossible by construction. Real images carry a single OS package manager,
 * so this also matches reality, not just the dep graph's bookkeeping.
 *
 * A scratch / unknown-PM image (no non-empty analysis) yields an empty map
 * and no warnings. A failure attributing the selected ecosystem (a per-PM
 * `await` that throws) is recorded as a warning rather than thrown, so the
 * rest of the scan still ships.
 */
export declare function computeOsLayerAttribution(analyses: ImagePackagesAnalysis[], orderedLayers: ExtractedLayers[], diffIDs: string[], targetImage: string, osRelease: OSRelease | undefined, redHatRepositories: string[]): Promise<OsLayerAttribution>;