Add the Docker Compose Detector (#1785)

* Add the DockerComposeComponentDetector and tests
* Address copilot PR comments. And add new tests for DockerReferenceUtility
* Add logging to some of the utils in DockerReferenceUtility for parse failures

Author: jpinz

docs/detectors/README.md

@@ -18,6 +18,12 @@
 | -------------------------- | ---------- |
 | CondaLockComponentDetector | DefaultOff |
 
+- [Docker Compose](dockercompose.md)
+
+| Detector                       | Status     |
+| ------------------------------ | ---------- |
+| DockerComposeComponentDetector | DefaultOff |
+
 - [Dockerfile](dockerfile.md)
 
 | Detector                    | Status     |

docs/detectors/dockercompose.md

@@ -0,0 +1,48 @@
+# Docker Compose Detection
+
+## Requirements
+
+Docker Compose detection depends on the following to successfully run:
+
+- One or more Docker Compose files matching the patterns: `docker-compose.yml`, `docker-compose.yaml`, `docker-compose.*.yml`, `docker-compose.*.yaml`, `compose.yml`, `compose.yaml`, `compose.*.yml`, `compose.*.yaml`
+
+The `DockerComposeComponentDetector` is a **DefaultOff** detector and must be explicitly enabled via the `--DetectorArgs` parameter.
+
+## Detection strategy
+
+The Docker Compose detector parses YAML compose files to extract Docker image references from service definitions.
+
+### Service Image Detection
+
+The detector looks for the `services` section and extracts the `image` field from each service:
+
+```yaml
+services:
+  web:
+    image: nginx:1.21
+  db:
+    image: postgres:14
+```
+
+Services that only define a `build` directive without an `image` field are skipped, as they do not reference external Docker images.
+
+### Full Registry References
+
+The detector supports full registry image references:
+
+```yaml
+services:
+  app:
+    image: ghcr.io/myorg/myapp:v2.0
+```
+
+### Variable Resolution
+
+Images containing unresolved variables (e.g., `${TAG}` or `${REGISTRY:-docker.io}`) are skipped to avoid reporting incomplete or incorrect references. The detector checks for `$`, `{`, or `}` characters in image references.
+
+## Known limitations
+
+- **DefaultOff Status**: This detector must be explicitly enabled using `--DetectorArgs DockerCompose=EnableIfDefaultOff`
+- **Variable Resolution**: Image references containing unresolved environment variables or template expressions are not reported, which may lead to under-reporting in compose files that heavily use variable substitution
+- **Build-Only Services**: Services that only specify a `build` directive without an `image` field are not reported
+- **No Dependency Graph**: All detected images are registered as independent components without parent-child relationships

src/Microsoft.ComponentDetection.Common/DockerReference/DockerReferenceUtility.cs

@@ -29,6 +29,7 @@ namespace Microsoft.ComponentDetection.Common;
 using System;
 using System.Diagnostics.CodeAnalysis;
 using Microsoft.ComponentDetection.Contracts;
+using Microsoft.Extensions.Logging;
 
 public static class DockerReferenceUtility
 {
@@ -38,6 +39,67 @@ public static class DockerReferenceUtility
     private const string LEGACYDEFAULTDOMAIN = "index.docker.io";
     private const string OFFICIALREPOSITORYNAME = "library";
 
+    /// <summary>
+    /// Returns true if the reference contains unresolved variable placeholders (e.g., ${VAR}, {{ .Values.tag }}).
+    /// Such references should be skipped before calling <see cref="ParseFamiliarName"/> or <see cref="ParseQualifiedName"/>.
+    /// </summary>
+    /// <param name="reference">The image reference string to check.</param>
+    /// <returns><c>true</c> if the reference contains variable placeholder characters; otherwise <c>false</c>.</returns>
+    public static bool HasUnresolvedVariables(string reference) =>
+        reference.IndexOfAny(['$', '{', '}']) >= 0;
+
+    /// <summary>
+    /// Attempts to parse an image reference string into a <see cref="DockerReference"/>.
+    /// Returns <c>null</c> if the reference contains unresolved variables or cannot be parsed.
+    /// </summary>
+    /// <param name="imageReference">The image reference string to parse.</param>
+    /// <param name="logger">Optional logger for recording parse failures.</param>
+    /// <returns>A <see cref="DockerReference"/> if parsing succeeds; otherwise <c>null</c>.</returns>
+    public static DockerReference? TryParseImageReference(string imageReference, ILogger? logger = null)
+    {
+        if (HasUnresolvedVariables(imageReference))
+        {
+            return null;
+        }
+
+        try
+        {
+            return ParseFamiliarName(imageReference);
+        }
+        catch (DockerReferenceException ex)
+        {
+            logger?.LogWarning(ex, "Failed to parse image reference '{ImageReference}'.", imageReference);
+            return null;
+        }
+    }
+
+    /// <summary>
+    /// Parses an image reference and registers it with the recorder if valid.
+    /// Skips references with unresolved variables or that cannot be parsed,
+    /// logging a warning for parse failures so that remaining entries continue to be processed.
+    /// </summary>
+    /// <param name="imageReference">The image reference string to parse.</param>
+    /// <param name="recorder">The component recorder to register the image with.</param>
+    /// <param name="logger">Optional logger for recording parse failures.</param>
+    public static void TryRegisterImageReference(string imageReference, ISingleFileComponentRecorder recorder, ILogger? logger = null)
+    {
+        var dockerRef = TryParseImageReference(imageReference, logger);
+        TryRegisterImageReference(dockerRef, recorder);
+    }
+
+    /// <summary>
+    /// Registers a pre-parsed <see cref="DockerReference"/> with the recorder if non-null.
+    /// </summary>
+    /// <param name="dockerReference">The parsed docker reference, or <c>null</c> to skip.</param>
+    /// <param name="recorder">The component recorder to register the image with.</param>
+    public static void TryRegisterImageReference(DockerReference? dockerReference, ISingleFileComponentRecorder recorder)
+    {
+        if (dockerReference != null)
+        {
+            recorder.RegisterUsage(new DetectedComponent(dockerReference.ToTypedDockerReferenceComponent()));
+        }
+    }
+
     public static DockerReference ParseQualifiedName(string qualifiedName)
     {
         var regexp = DockerRegex.ReferenceRegexp;

src/Microsoft.ComponentDetection.Contracts/DetectorClass.cs

@@ -47,4 +47,7 @@ public enum DetectorClass
 
     /// <summary> Indicates a detector applies to Swift packages.</summary>
     Swift,
+
+    /// <summary>Indicates a detector applies to Docker Compose image references.</summary>
+    DockerCompose,
 }

src/Microsoft.ComponentDetection.Detectors/dockercompose/DockerComposeComponentDetector.cs

@@ -0,0 +1,123 @@
+namespace Microsoft.ComponentDetection.Detectors.DockerCompose;
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.ComponentDetection.Common;
+using Microsoft.ComponentDetection.Contracts;
+using Microsoft.ComponentDetection.Contracts.Internal;
+using Microsoft.ComponentDetection.Contracts.TypedComponent;
+using Microsoft.Extensions.Logging;
+using YamlDotNet.RepresentationModel;
+
+public class DockerComposeComponentDetector : FileComponentDetector, IDefaultOffComponentDetector
+{
+    public DockerComposeComponentDetector(
+        IComponentStreamEnumerableFactory componentStreamEnumerableFactory,
+        IObservableDirectoryWalkerFactory walkerFactory,
+        ILogger<DockerComposeComponentDetector> logger)
+    {
+        this.ComponentStreamEnumerableFactory = componentStreamEnumerableFactory;
+        this.Scanner = walkerFactory;
+        this.Logger = logger;
+    }
+
+    public override string Id => "DockerCompose";
+
+    public override IList<string> SearchPatterns { get; } =
+    [
+        "docker-compose.yml", "docker-compose.yaml",
+        "docker-compose.*.yml", "docker-compose.*.yaml",
+        "compose.yml", "compose.yaml",
+        "compose.*.yml", "compose.*.yaml",
+    ];
+
+    public override IEnumerable<ComponentType> SupportedComponentTypes => [ComponentType.DockerReference];
+
+    public override int Version => 1;
+
+    public override IEnumerable<string> Categories => [nameof(DetectorClass.DockerCompose)];
+
+    protected override async Task OnFileFoundAsync(ProcessRequest processRequest, IDictionary<string, string> detectorArgs, CancellationToken cancellationToken = default)
+    {
+        var singleFileComponentRecorder = processRequest.SingleFileComponentRecorder;
+        var file = processRequest.ComponentStream;
+
+        try
+        {
+            this.Logger.LogInformation("Discovered Docker Compose file: {Location}", file.Location);
+
+            string contents;
+            using (var reader = new StreamReader(file.Stream))
+            {
+                contents = await reader.ReadToEndAsync(cancellationToken);
+            }
+
+            var yaml = new YamlStream();
+            yaml.Load(new StringReader(contents));
+
+            if (yaml.Documents.Count == 0)
+            {
+                return;
+            }
+
+            foreach (var document in yaml.Documents)
+            {
+                if (document.RootNode is YamlMappingNode rootMapping)
+                {
+                    this.ExtractImageReferences(rootMapping, singleFileComponentRecorder);
+                }
+            }
+        }
+        catch (Exception e)
+        {
+            this.Logger.LogError(e, "Failed to parse Docker Compose file: {Location}", file.Location);
+        }
+    }
+
+    private static YamlMappingNode? GetMappingChild(YamlMappingNode parent, string key)
+    {
+        foreach (var entry in parent.Children)
+        {
+            if (entry.Key is YamlScalarNode scalarKey && string.Equals(scalarKey.Value, key, StringComparison.OrdinalIgnoreCase))
+            {
+                return entry.Value as YamlMappingNode;
+            }
+        }
+
+        return null;
+    }
+
+    private void ExtractImageReferences(YamlMappingNode rootMapping, ISingleFileComponentRecorder recorder)
+    {
+        var services = GetMappingChild(rootMapping, "services");
+        if (services == null)
+        {
+            return;
+        }
+
+        foreach (var serviceEntry in services.Children)
+        {
+            if (serviceEntry.Value is not YamlMappingNode serviceMapping)
+            {
+                continue;
+            }
+
+            // Extract direct image: references
+            foreach (var entry in serviceMapping.Children)
+            {
+                var key = (entry.Key as YamlScalarNode)?.Value;
+                if (string.Equals(key, "image", StringComparison.OrdinalIgnoreCase))
+                {
+                    var imageRef = (entry.Value as YamlScalarNode)?.Value;
+                    if (!string.IsNullOrWhiteSpace(imageRef))
+                    {
+                        DockerReferenceUtility.TryRegisterImageReference(imageRef, recorder, this.Logger);
+                    }
+                }
+            }
+        }
+    }
+}