Reapply "Add OCI image support to Linux scanner (#1708)" (#1716) (#1717)

* Reapply "Add OCI image support to Linux scanner (#1708)" (#1716)

This reverts commit db58407.

* Reapply "Add Docker archive support to Linux scanner (#1711)" (#1715) (#1718)

This reverts commit 69a2057.

* Handle parse failures gracefully

* Fix merge error

Author: jasonpaulos

docs/detectors/linux.md

@@ -11,6 +11,31 @@ Linux detection depends on the following:
 Linux package detection is performed by running [Syft](https://github.com/anchore/syft) and parsing the output.
 The output contains the package name, version, and the layer of the container in which it was found.
 
+### Supported Input Types
+
+The Linux detector runs on container images passed under the `--DockerImagesToScan` flag.
+
+Supported image reference formats are:
+
+#### Name and Tag/Digest
+
+Images in the local Docker daemon or a remote registry can be referenced by name and tag or digest. For example, `ubuntu:16.04`. Remote images will be pulled if they are not present locally.
+
+#### Digest Only
+
+Images already present in the local Docker daemon can be referenced by just a digest. For example, `sha256:56bab49eef2ef07505f6a1b0d5bd3a601dfc3c76ad4460f24c91d6fa298369ab`.
+
+#### OCI Images
+
+Images present on the filesystem as either an [OCI layout directory](https://specs.opencontainers.org/image-spec/image-layout/) or an OCI image archive (tarball) can be referenced by file path.
+
+- For OCI image layout directories, use the prefix `oci-dir:` followed by the path to the directory, e.g. `oci-dir:/path/to/image`
+- For OCI image archives (tarballs), use the prefix `oci-archive:` followed by the path to the archive file, e.g. `oci-archive:/path/to/image.tar`
+
+#### Docker Archives
+
+Images saved to disk via `docker save` can be referenced using the `docker-archive:` prefix followed by the path to the tarball, e.g. `docker-archive:/path/to/image.tar`.
+
 ### Scanner Scope
 
 By default, this detector invokes Syft with the `all-layers` scanning scope (i.e. the Syft argument `--scope all-layers`).
@@ -28,3 +53,4 @@ For example:
 ## Known limitations
 
 - Windows container scanning is not supported
+- Multiplatform images are not supported

src/Microsoft.ComponentDetection.Common/DockerService.cs

@@ -183,6 +183,11 @@ public async Task<ContainerDetails> InspectImageAsync(string image, Cancellation
     }
 
     public async Task<(string Stdout, string Stderr)> CreateAndRunContainerAsync(string image, IList<string> command, CancellationToken cancellationToken = default)
+    {
+        return await this.CreateAndRunContainerAsync(image, command, additionalBinds: null, cancellationToken);
+    }
+
+    public async Task<(string Stdout, string Stderr)> CreateAndRunContainerAsync(string image, IList<string> command, IList<string> additionalBinds, CancellationToken cancellationToken = default)
     {
         var commandJson = JsonSerializer.Serialize(command);
 
@@ -194,7 +199,7 @@ public async Task<ContainerDetails> InspectImageAsync(string image, Cancellation
         };
 
         await this.TryPullImageAsync(image, cancellationToken);
-        var container = await CreateContainerAsync(image, command, cancellationToken);
+        var container = await CreateContainerAsync(image, command, additionalBinds, cancellationToken);
         record.Container = JsonSerializer.Serialize(container);
 
         try
@@ -272,6 +277,7 @@ public async Task<ContainerDetails> InspectImageAsync(string image, Cancellation
     private static async Task<CreateContainerResponse> CreateContainerAsync(
         string image,
         IList<string> command,
+        IList<string> additionalBinds,
         CancellationToken cancellationToken = default)
     {
         using var record = new DockerServiceStepTelemetryRecord
@@ -283,6 +289,17 @@ private static async Task<CreateContainerResponse> CreateContainerAsync(
 
         try
         {
+            var binds = new List<string>
+            {
+                $"{Path.GetTempPath()}:/tmp",
+                "/var/run/docker.sock:/var/run/docker.sock",
+            };
+
+            if (additionalBinds != null)
+            {
+                binds.AddRange(additionalBinds);
+            }
+
             var parameters = new CreateContainerParameters
             {
                 Image = image,
@@ -298,11 +315,7 @@ private static async Task<CreateContainerResponse> CreateContainerAsync(
                     [
                         "no-new-privileges",
                     ],
-                    Binds =
-                    [
-                        $"{Path.GetTempPath()}:/tmp",
-                        "/var/run/docker.sock:/var/run/docker.sock",
-                    ],
+                    Binds = binds,
                 },
             };
 
@@ -394,4 +407,10 @@ private static int GetContainerId()
     {
         return Interlocked.Increment(ref incrementingContainerId);
     }
+
+    /// <inheritdoc/>
+    public ContainerDetails GetEmptyContainerDetails()
+    {
+        return new ContainerDetails { Id = GetContainerId() };
+    }
 }

src/Microsoft.ComponentDetection.Contracts/IDockerService.cs

@@ -52,9 +52,26 @@ public interface IDockerService
     /// <summary>
     /// Creates and runs a container with the given image and command.
     /// </summary>
-    /// <param name="image">The image to inspect.</param>
+    /// <param name="image">The image to run.</param>
     /// <param name="command">The command to run in the container.</param>
     /// <param name="cancellationToken">The cancellation token.</param>
     /// <returns>A tuple of stdout and stderr from the container.</returns>
     Task<(string Stdout, string Stderr)> CreateAndRunContainerAsync(string image, IList<string> command, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Creates and runs a container with the given image, command, and additional volume binds.
+    /// </summary>
+    /// <param name="image">The image to run.</param>
+    /// <param name="command">The command to run in the container.</param>
+    /// <param name="additionalBinds">Additional volume bind mounts to add to the container (e.g., "/host/path:/container/path:ro").</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A tuple of stdout and stderr from the container.</returns>
+    Task<(string Stdout, string Stderr)> CreateAndRunContainerAsync(string image, IList<string> command, IList<string> additionalBinds, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Creates an empty <see cref="ContainerDetails"/> with a unique ID assigned.
+    /// Used for image types where details are not obtained from Docker inspect (e.g., OCI layout images).
+    /// </summary>
+    /// <returns>A <see cref="ContainerDetails"/> with only the <see cref="ContainerDetails.Id"/> populated.</returns>
+    ContainerDetails GetEmptyContainerDetails();
 }

src/Microsoft.ComponentDetection.Detectors/linux/Contracts/SourceClassExtensions.cs

@@ -0,0 +1,26 @@
+namespace Microsoft.ComponentDetection.Detectors.Linux.Contracts;
+
+using System.Text.Json;
+
+/// <summary>
+/// Extends the auto-generated <see cref="SourceClass"/> with a method to
+/// deserialize its untyped <see cref="Metadata"/> into a
+/// strongly-typed <see cref="SyftSourceMetadata"/>.
+/// </summary>
+public partial class SourceClass
+{
+    /// <summary>
+    /// Deserializes the <see cref="Metadata"/> property into a <see cref="SyftSourceMetadata"/>.
+    /// Returns null if <see cref="Metadata"/> is null or not a <see cref="JsonElement"/>.
+    /// </summary>
+    /// <returns>A deserialized <see cref="SyftSourceMetadata"/> instance, or null.</returns>
+    internal SyftSourceMetadata? GetSyftSourceMetadata()
+    {
+        if (this.Metadata is JsonElement element)
+        {
+            return JsonSerializer.Deserialize<SyftSourceMetadata>(element.GetRawText());
+        }
+
+        return null;
+    }
+}

src/Microsoft.ComponentDetection.Detectors/linux/Contracts/SyftSourceLayer.cs

@@ -0,0 +1,18 @@
+namespace Microsoft.ComponentDetection.Detectors.Linux.Contracts;
+
+using System.Text.Json.Serialization;
+
+/// <summary>
+/// Represents a single layer in the image source metadata from Syft output.
+/// </summary>
+internal class SyftSourceLayer
+{
+    [JsonPropertyName("mediaType")]
+    public string? MediaType { get; set; }
+
+    [JsonPropertyName("digest")]
+    public string? Digest { get; set; }
+
+    [JsonPropertyName("size")]
+    public long? Size { get; set; }
+}

src/Microsoft.ComponentDetection.Detectors/linux/Contracts/SyftSourceMetadata.cs

@@ -0,0 +1,46 @@
+namespace Microsoft.ComponentDetection.Detectors.Linux.Contracts;
+
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+
+/// <summary>
+/// Represents the metadata from a Syft scan source of type "image".
+/// Contains image details such as layers, labels, tags, and image ID.
+/// Deserialized from the <c>source.metadata</c> field in Syft JSON output,
+/// which is typed as <c>object</c> in the auto-generated <see cref="SourceClass"/>.
+/// </summary>
+internal class SyftSourceMetadata
+{
+    [JsonPropertyName("userInput")]
+    public string? UserInput { get; set; }
+
+    [JsonPropertyName("imageID")]
+    public string? ImageId { get; set; }
+
+    [JsonPropertyName("manifestDigest")]
+    public string? ManifestDigest { get; set; }
+
+    [JsonPropertyName("mediaType")]
+    public string? MediaType { get; set; }
+
+    [JsonPropertyName("tags")]
+    public string[]? Tags { get; set; }
+
+    [JsonPropertyName("imageSize")]
+    public long? ImageSize { get; set; }
+
+    [JsonPropertyName("layers")]
+    public SyftSourceLayer[]? Layers { get; set; }
+
+    [JsonPropertyName("repoDigests")]
+    public string[]? RepoDigests { get; set; }
+
+    [JsonPropertyName("architecture")]
+    public string? Architecture { get; set; }
+
+    [JsonPropertyName("os")]
+    public string? Os { get; set; }
+
+    [JsonPropertyName("labels")]
+    public Dictionary<string, string>? Labels { get; set; }
+}

src/Microsoft.ComponentDetection.Detectors/linux/ILinuxScanner.cs

@@ -5,6 +5,7 @@ namespace Microsoft.ComponentDetection.Detectors.Linux;
 using System.Threading.Tasks;
 using Microsoft.ComponentDetection.Contracts.BcdeModels;
 using Microsoft.ComponentDetection.Contracts.TypedComponent;
+using Microsoft.ComponentDetection.Detectors.Linux.Contracts;
 
 /// <summary>
 /// Interface for scanning Linux container layers to identify components.
@@ -13,6 +14,7 @@ public interface ILinuxScanner
 {
     /// <summary>
     /// Scans a Linux container image for components and maps them to their respective layers.
+    /// Runs Syft and processes the output in a single step.
     /// </summary>
     /// <param name="imageHash">The hash identifier of the container image to scan.</param>
     /// <param name="containerLayers">The collection of Docker layers that make up the container image.</param>
@@ -29,4 +31,33 @@ public Task<IEnumerable<LayerMappedLinuxComponents>> ScanLinuxAsync(
         LinuxScannerScope scope,
         CancellationToken cancellationToken = default
     );
+
+    /// <summary>
+    /// Runs the Syft scanner and returns the raw parsed output without processing components.
+    /// Use this when the caller needs access to the full Syft output (e.g., to extract source metadata for OCI images).
+    /// </summary>
+    /// <param name="syftSource">The source argument passed to Syft (e.g., an image hash or "oci-dir:/oci-image").</param>
+    /// <param name="additionalBinds">Additional volume bind mounts for the Syft container (e.g., for mounting OCI directories).</param>
+    /// <param name="scope">The scope for scanning the image.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the parsed <see cref="SyftOutput"/>.</returns>
+    public Task<SyftOutput> GetSyftOutputAsync(
+        string syftSource,
+        IList<string> additionalBinds,
+        LinuxScannerScope scope,
+        CancellationToken cancellationToken = default
+    );
+
+    /// <summary>
+    /// Processes parsed Syft output into layer-mapped components.
+    /// </summary>
+    /// <param name="syftOutput">The parsed Syft output.</param>
+    /// <param name="containerLayers">The layers to map components to.</param>
+    /// <param name="enabledComponentTypes">The set of component types to include in the results.</param>
+    /// <returns>A collection of <see cref="LayerMappedLinuxComponents"/> representing the components found and their associated layers.</returns>
+    public IEnumerable<LayerMappedLinuxComponents> ProcessSyftOutput(
+        SyftOutput syftOutput,
+        IEnumerable<DockerLayer> containerLayers,
+        ISet<ComponentType> enabledComponentTypes
+    );
 }

src/Microsoft.ComponentDetection.Detectors/linux/ImageReference.cs

@@ -0,0 +1,120 @@
+namespace Microsoft.ComponentDetection.Detectors.Linux;
+
+using System;
+
+/// <summary>
+/// Specifies the type of image reference.
+/// </summary>
+internal enum ImageReferenceKind
+{
+    /// <summary>
+    /// A Docker image reference (e.g., "node:latest", "sha256:abc123").
+    /// </summary>
+    DockerImage,
+
+    /// <summary>
+    /// An OCI Image Layout directory on disk (e.g., "oci-dir:/path/to/image").
+    /// </summary>
+    OciLayout,
+
+    /// <summary>
+    /// An OCI archive (tarball) file on disk (e.g., "oci-archive:/path/to/image.tar").
+    /// </summary>
+    OciArchive,
+
+    /// <summary>
+    /// A Docker archive (tarball) file on disk created by "docker save" (e.g., "docker-archive:/path/to/image.tar").
+    /// </summary>
+    DockerArchive,
+}
+
+/// <summary>
+/// Represents a parsed image reference from the scan input, with its type and cleaned reference string.
+/// </summary>
+internal class ImageReference
+{
+    private const string OciDirPrefix = "oci-dir:";
+    private const string OciArchivePrefix = "oci-archive:";
+    private const string DockerArchivePrefix = "docker-archive:";
+
+    /// <summary>
+    /// Gets the original input string as provided by the user.
+    /// </summary>
+    public required string OriginalInput { get; init; }
+
+    /// <summary>
+    /// Gets the cleaned reference string with any scheme prefix removed.
+    /// For Docker images, this is lowercased. For file paths, case is preserved.
+    /// </summary>
+    public required string Reference { get; init; }
+
+    /// <summary>
+    /// Gets the kind of image reference.
+    /// </summary>
+    public required ImageReferenceKind Kind { get; init; }
+
+    /// <summary>
+    /// Parses an input image string into an <see cref="ImageReference"/>.
+    /// </summary>
+    /// <param name="input">The raw image input string.</param>
+    /// <returns>A parsed <see cref="ImageReference"/>.</returns>
+    public static ImageReference Parse(string input)
+    {
+        if (input.StartsWith(OciDirPrefix, StringComparison.OrdinalIgnoreCase))
+        {
+            var path = input[OciDirPrefix.Length..];
+            if (string.IsNullOrWhiteSpace(path))
+            {
+                throw new ArgumentException($"Input with '{OciDirPrefix}' prefix must include a path.", nameof(input));
+            }
+
+            return new ImageReference
+            {
+                OriginalInput = input,
+                Reference = path,
+                Kind = ImageReferenceKind.OciLayout,
+            };
+        }
+
+        if (input.StartsWith(OciArchivePrefix, StringComparison.OrdinalIgnoreCase))
+        {
+            var path = input[OciArchivePrefix.Length..];
+            if (string.IsNullOrWhiteSpace(path))
+            {
+                throw new ArgumentException($"Input with '{OciArchivePrefix}' prefix must include a path.", nameof(input));
+            }
+
+            return new ImageReference
+            {
+                OriginalInput = input,
+                Reference = path,
+                Kind = ImageReferenceKind.OciArchive,
+            };
+        }
+
+        if (input.StartsWith(DockerArchivePrefix, StringComparison.OrdinalIgnoreCase))
+        {
+            var path = input[DockerArchivePrefix.Length..];
+            if (string.IsNullOrWhiteSpace(path))
+            {
+                throw new ArgumentException($"Input with '{DockerArchivePrefix}' prefix must include a path.", nameof(input));
+            }
+
+            return new ImageReference
+            {
+                OriginalInput = input,
+                Reference = path,
+                Kind = ImageReferenceKind.DockerArchive,
+            };
+        }
+
+#pragma warning disable CA1308
+        return new ImageReference
+        {
+            OriginalInput = input,
+            Reference = input.ToLowerInvariant(),
+            Kind = ImageReferenceKind.DockerImage,
+        };
+#pragma warning restore CA1308
+    }
+}