feat: add per-layer package attribution (opt-in)

Introduces `computeLayerAttribution` in `lib/analyzer/layer-attribution.ts`
and wires it through the full pipeline. Enabled with `--layer-attribution`.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ashokn1

lib/analyzer/layer-attribution.ts

@@ -0,0 +1,129 @@
+import { LayerAttributionEntry } from "../facts";
+import { getApkDbFileContent } from "../inputs/apk/static";
+import { getAptDbFileContent } from "../inputs/apt/static";
+import { getChiselManifestContent } from "../inputs/chisel/static";
+import { getRpmDbFileContent } from "../inputs/rpm/static";
+import { ExtractedLayers, HistoryEntry } from "../extractor/types";
+import { analyze as apkAnalyze } from "./package-managers/apk";
+import { analyze as aptAnalyze } from "./package-managers/apt";
+import { analyze as chiselAnalyze } from "./package-managers/chisel";
+import { analyze as rpmAnalyze } from "./package-managers/rpm";
+import { AnalysisType } from "./types";
+
+export interface LayerAttributionResult {
+  entries: LayerAttributionEntry[];
+  pkgLayerMap: Map<string, { layerIndex: number; diffID: string }>;
+}
+
+function buildHistoryInstructions(
+  history: HistoryEntry[] | null | undefined,
+): string[] {
+  if (!history) return [];
+  return history
+    .filter((h) => !h.empty_layer)
+    .map((h) => h.created_by ?? "");
+}
+
+function pkgKey(name: string, version: string): string {
+  return `${name}@${version}`;
+}
+
+async function parseLayerPackages(
+  layer: ExtractedLayers,
+  analysisType: AnalysisType,
+  targetImage: string,
+): Promise<Map<string, true>> {
+  const result = new Map<string, true>();
+
+  if (analysisType === AnalysisType.Apk) {
+    const content = getApkDbFileContent(layer);
+    if (!content) return result;
+    const analysis = await apkAnalyze(targetImage, content);
+    for (const pkg of analysis.Analysis) {
+      result.set(pkgKey(pkg.Name, pkg.Version), true);
+    }
+  } else if (analysisType === AnalysisType.Apt) {
+    const aptFiles = getAptDbFileContent(layer);
+    if (!aptFiles.dpkgFile) return result;
+    const analysis = await aptAnalyze(targetImage, aptFiles);
+    for (const pkg of analysis.Analysis) {
+      result.set(pkgKey(pkg.Name, pkg.Version), true);
+    }
+  } else if (analysisType === AnalysisType.Rpm) {
+    const pkgs = await getRpmDbFileContent(layer);
+    if (!pkgs.length) return result;
+    const analysis = await rpmAnalyze(targetImage, pkgs, []);
+    for (const pkg of analysis.Analysis) {
+      result.set(pkgKey(pkg.Name, pkg.Version), true);
+    }
+  } else if (analysisType === AnalysisType.Chisel) {
+    const pkgs = getChiselManifestContent(layer);
+    if (!pkgs.length) return result;
+    const analysis = await chiselAnalyze(targetImage, pkgs);
+    for (const pkg of analysis.Analysis) {
+      result.set(pkgKey(pkg.Name, pkg.Version), true);
+    }
+  }
+
+  return result;
+}
+
+export async function computeLayerAttribution(
+  orderedLayers: ExtractedLayers[],
+  analysisType: AnalysisType,
+  rootFsLayers: string[],
+  manifestLayers: string[],
+  history: HistoryEntry[] | null | undefined,
+  targetImage: string,
+): Promise<LayerAttributionResult> {
+  const instructions = buildHistoryInstructions(history);
+  const entries: LayerAttributionEntry[] = [];
+  const pkgLayerMap = new Map<string, { layerIndex: number; diffID: string }>();
+  const limit = Math.min(orderedLayers.length, rootFsLayers.length);
+
+  let previousPkgs = new Map<string, true>();
+
+  for (let i = 0; i < limit; i++) {
+    const diffID = rootFsLayers[i];
+    const digest = manifestLayers[i];
+    const instruction = instructions[i];
+
+    const currentPkgs = await parseLayerPackages(
+      orderedLayers[i],
+      analysisType,
+      targetImage,
+    );
+    if (currentPkgs.size === 0) continue;
+
+    const newPkgs: string[] = [];
+    for (const key of currentPkgs.keys()) {
+      if (!previousPkgs.has(key)) {
+        newPkgs.push(key);
+        pkgLayerMap.set(key, { layerIndex: i, diffID });
+      }
+    }
+
+    const removedPkgs: string[] = [];
+    for (const key of previousPkgs.keys()) {
+      if (!currentPkgs.has(key)) {
+        removedPkgs.push(key);
+      }
+    }
+
+    if (newPkgs.length > 0 || removedPkgs.length > 0) {
+      const entry: LayerAttributionEntry = {
+        layerIndex: i,
+        diffID,
+        packages: newPkgs,
+      };
+      if (digest) entry.digest = digest;
+      if (instruction) entry.instruction = instruction;
+      if (removedPkgs.length > 0) entry.removedPackages = removedPkgs;
+      entries.push(entry);
+    }
+
+    previousPkgs = currentPkgs;
+  }
+
+  return { entries, pkgLayerMap };
+}

lib/analyzer/static-analyzer.ts

@@ -81,11 +81,13 @@ import {
   analyze as rpmAnalyze,
   mapRpmSqlitePackages,
 } from "./package-managers/rpm";
+import { computeLayerAttribution } from "./layer-attribution";
 import {
   ImagePackagesAnalysis,
   OSRelease,
   StaticPackagesAnalysis,
 } from "./types";
+import { LayerAttributionEntry } from "../facts";
 
 const debug = Debug("snyk");
 
@@ -159,6 +161,7 @@ export async function analyze(
     imageId,
     manifestLayers,
     extractedLayers,
+    orderedLayers,
     rootFsLayers,
     autoDetectedUserInstructions,
     platform,
@@ -236,6 +239,34 @@ export async function analyze(
     throw new Error("Failed to detect installed OS packages");
   }
 
+  let layerPackageAttribution: LayerAttributionEntry[] | undefined;
+  if (isTrue(options["layer-attribution"]) && rootFsLayers && orderedLayers.length > 0) {
+    const winningResult = results.find((r) => r.Analysis.length > 0);
+    if (winningResult) {
+      try {
+        const { entries, pkgLayerMap } = await computeLayerAttribution(
+          orderedLayers,
+          winningResult.AnalyzeType,
+          rootFsLayers,
+          manifestLayers,
+          history,
+          targetImage,
+        );
+        layerPackageAttribution = entries;
+        for (const pkg of winningResult.Analysis) {
+          const key = `${pkg.Name}@${pkg.Version}`;
+          const attr = pkgLayerMap.get(key);
+          if (attr) {
+            pkg.layerIndex = attr.layerIndex;
+            pkg.layerDiffId = attr.diffID;
+          }
+        }
+      } catch (err) {
+        debug(`Could not compute layer attribution: ${getErrorMessage(err)}`);
+      }
+    }
+  }
+
   const binaries = getBinariesHashes(extractedLayers);
   const javaRuntime = detectJavaRuntime(extractedLayers);
   const baseRuntimes = javaRuntime ? [javaRuntime] : undefined;
@@ -318,6 +349,7 @@ export async function analyze(
     baseRuntimes,
     imageLayers: manifestLayers,
     rootFsLayers,
+    layerPackageAttribution,
     applicationDependenciesScanResults,
     manifestFiles,
     autoDetectedUserInstructions,

lib/analyzer/types.ts

@@ -1,5 +1,5 @@
 import { ImageName } from "../extractor/image";
-import { BaseRuntime } from "../facts";
+import { BaseRuntime, LayerAttributionEntry } from "../facts";
 import { AutoDetectedUserInstructions, ManifestFile } from "../types";
 import {
   AppDepsScanResultWithoutTarget,
@@ -17,6 +17,8 @@ export interface AnalyzedPackage {
   };
   Purl?: string;
   AutoInstalled?: boolean;
+  layerIndex?: number;
+  layerDiffId?: string;
 }
 export interface AnalyzedPackageWithVersion extends AnalyzedPackage {
   Version: string;
@@ -79,6 +81,7 @@ export interface StaticAnalysis {
   baseRuntimes?: BaseRuntime[];
   imageLayers: string[];
   rootFsLayers?: string[];
+  layerPackageAttribution?: LayerAttributionEntry[];
   autoDetectedUserInstructions?: AutoDetectedUserInstructions;
   applicationDependenciesScanResults: AppDepsScanResultWithoutTarget[];
   manifestFiles: ManifestFile[];

lib/dependency-tree/index.ts

@@ -121,11 +121,19 @@ export function buildTree(
     };
 
     for (const depInfo of tooFrequentDeps) {
+      const freqLabels: { [key: string]: string } = {};
+      if (depInfo.layerDiffId !== undefined) {
+        freqLabels.layerDiffId = depInfo.layerDiffId;
+      }
+      if (depInfo.layerIndex !== undefined) {
+        freqLabels.layerIndex = String(depInfo.layerIndex);
+      }
       const pkg: DepTreeDep = {
         name: depFullName(depInfo),
         version: depInfo.Version,
         sourceVersion: depInfo.SourceVersion,
         dependencies: {},
+        ...(Object.keys(freqLabels).length > 0 ? { labels: freqLabels } : {}),
       };
 
       // The existence of the "meta" package breaks upgrade
@@ -172,11 +180,20 @@ function buildTreeRecursive(
     return null;
   }
 
+  const labels: { [key: string]: string } = {};
+  if (depInfo.layerDiffId !== undefined) {
+    labels.layerDiffId = depInfo.layerDiffId;
+  }
+  if (depInfo.layerIndex !== undefined) {
+    labels.layerIndex = String(depInfo.layerIndex);
+  }
+
   const tree: DepTreeDep = {
     name: fullName,
     version: depInfo.Version,
     purl: depInfo.Purl,
     dependencies: {},
+    ...(Object.keys(labels).length > 0 ? { labels } : {}),
   };
   if (depInfo._visited) {
     return tree;

lib/extractor/index.ts

@@ -147,6 +147,7 @@ export async function extractImageContent(
     manifestLayers: extractor.getManifestLayers(archiveContent.manifest),
     imageCreationTime: archiveContent.imageConfig.created,
     extractedLayers: layersWithLatestFileModifications(archiveContent.layers),
+    orderedLayers: archiveContent.layers,
     rootFsLayers: getRootFsLayersFromConfig(archiveContent.imageConfig),
     autoDetectedUserInstructions: getDetectedLayersInfoFromConfig(
       archiveContent.imageConfig,

lib/extractor/types.ts

@@ -29,6 +29,7 @@ export interface ExtractionResult {
   imageId: string;
   manifestLayers: string[];
   extractedLayers: ExtractedLayers;
+  orderedLayers: ExtractedLayers[];
   rootFsLayers?: string[];
   autoDetectedUserInstructions?: AutoDetectedUserInstructions;
   platform?: string;

lib/facts.ts

@@ -162,3 +162,17 @@ export interface BaseRuntimesFact {
   type: "baseRuntimes";
   data: BaseRuntime[];
 }
+
+export interface LayerAttributionEntry {
+  layerIndex: number;
+  diffID: string;
+  digest?: string;
+  instruction?: string;
+  packages: string[];
+  removedPackages?: string[];
+}
+
+export interface LayerPackageAttributionFact {
+  type: "layerPackageAttribution";
+  data: LayerAttributionEntry[];
+}

lib/response-builder.ts

@@ -186,6 +186,17 @@ async function buildResponse(
     additionalFacts.push(rootFsFact);
   }
 
+  if (
+    depsAnalysis.layerPackageAttribution &&
+    depsAnalysis.layerPackageAttribution.length > 0
+  ) {
+    const layerPackageAttributionFact: facts.LayerPackageAttributionFact = {
+      type: "layerPackageAttribution",
+      data: depsAnalysis.layerPackageAttribution,
+    };
+    additionalFacts.push(layerPackageAttributionFact);
+  }
+
   if (depsAnalysis.depTree.targetOS.prettyName) {
     const imageOsReleasePrettyNameFact: facts.ImageOsReleasePrettyNameFact = {
       type: "imageOsReleasePrettyName",

lib/types.ts

@@ -82,7 +82,9 @@ export type FactType =
   // Used for application dependencies scanning; shows which files were used in the analysis of the dependencies.
   | "testedFiles"
   // Application files observed in the image
-  | "applicationFiles";
+  | "applicationFiles"
+  // Per-layer package attribution: which layer introduced each OS package
+  | "layerPackageAttribution";
 
 export interface PluginResponse {
   /** The first result is guaranteed to be the OS dependencies scan result. */
@@ -238,6 +240,9 @@ export interface PluginOptions {
   /** Include system-level JARs and WARs from /usr/lib in scan results. The default is "false". */
   "include-system-jars": boolean | string;
 
+  /** Compute and emit per-layer package attribution. The default is "false". */
+  "layer-attribution": boolean | string;
+
   "target-reference": string;
 
   parameterWarnings?: string[];