Add component detectors for Docker Compose, Helm, and Kubernetes

.gitignore

@@ -54,3 +54,4 @@ launchSettings.json
 
 # Dev nupkgs
 dev-source
+.nuget/

docs/detectors/README.md

@@ -18,6 +18,12 @@
 | -------------------------- | ---------- |
 | CondaLockComponentDetector | DefaultOff |
 
+- [Docker Compose](dockercompose.md)
+
+| Detector                        | Status     |
+| ------------------------------- | ---------- |
+| DockerComposeComponentDetector  | DefaultOff |
+
 - [Dockerfile](dockerfile.md)
 
 | Detector                    | Status     |
@@ -42,12 +48,24 @@
 | ----------------------- | ------ |
 | GradleComponentDetector | Stable |
 
+- [Helm](helm.md)
+
+| Detector               | Status     |
+| ---------------------- | ---------- |
+| HelmComponentDetector  | DefaultOff |
+
 - [Ivy](ivy.md)
 
 | Detector    | Status       |
 | ----------- | ------------ |
 | IvyDetector | Experimental |
 
+- [Kubernetes](kubernetes.md)
+
+| Detector                       | Status     |
+| ------------------------------ | ---------- |
+| KubernetesComponentDetector    | DefaultOff |
+
 - [Linux](linux.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 `{{ .Values.tag }}`) 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

docs/detectors/helm.md

@@ -0,0 +1,50 @@
+# Helm Detection
+
+## Requirements
+
+Helm detection depends on the following to successfully run:
+
+- One or more Helm values files matching the patterns: `*values*.yaml`, `*values*.yml`
+- Chart metadata files (`Chart.yaml`, `Chart.yml`, `chart.yaml`, `chart.yml`) are matched for file discovery but only values files are parsed for image references
+
+The `HelmComponentDetector` is a **DefaultOff** detector and must be explicitly enabled via the `--DetectorArgs` parameter.
+
+## Detection strategy
+
+The Helm detector parses Helm values YAML files to extract Docker image references. It recursively walks the YAML tree looking for `image` keys.
+
+### Direct Image Strings
+
+The detector recognizes image references specified as simple strings:
+
+```yaml
+image: nginx:1.21
+```
+
+### Structured Image Objects
+
+The detector also supports the common Helm chart pattern of structured image definitions:
+
+```yaml
+image:
+  registry: ghcr.io
+  repository: org/myimage
+  tag: v1.0
+```
+
+The `registry` and `tag` fields are optional. When present, the detector reconstructs the full image reference. The `digest` field is also supported.
+
+### Recursive Search
+
+The detector recursively traverses all nested mappings and sequences in the values file, detecting image references at any depth in the YAML structure.
+
+### Variable Resolution
+
+Images containing unresolved variables (e.g., `{{ .Values.tag }}`) 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 Helm=EnableIfDefaultOff`
+- **Values Files Only**: Only files with `values` in the name are parsed for image references. Chart.yaml files are matched but not processed
+- **Variable Resolution**: Image references containing unresolved Helm template expressions are not reported
+- **No Dependency Graph**: All detected images are registered as independent components without parent-child relationships

docs/detectors/kubernetes.md

@@ -0,0 +1,58 @@
+# Kubernetes Detection
+
+## Requirements
+
+Kubernetes detection depends on the following to successfully run:
+
+- One or more Kubernetes manifest files matching the patterns: `*.yaml`, `*.yml`
+- Manifests must contain both `apiVersion` and `kind` fields to be recognized as Kubernetes resources
+
+The `KubernetesComponentDetector` is a **DefaultOff** detector and must be explicitly enabled via the `--DetectorArgs` parameter.
+
+## Detection strategy
+
+The Kubernetes detector parses Kubernetes manifest YAML files to extract Docker image references from container specifications.
+
+### Supported Resource Kinds
+
+The detector recognizes the following Kubernetes resource kinds:
+
+- `Pod`
+- `Deployment`
+- `StatefulSet`
+- `DaemonSet`
+- `ReplicaSet`
+- `Job`
+- `CronJob`
+- `ReplicationController`
+
+Files with an unrecognized `kind` or missing `apiVersion`/`kind` fields are skipped.
+
+### Container Image Detection
+
+The detector extracts image references from all container types within pod specifications:
+
+- **containers**: Main application containers
+- **initContainers**: Initialization containers that run before app containers
+- **ephemeralContainers**: Ephemeral debugging containers
+
+### Pod Spec Locations
+
+The detector handles different pod spec locations depending on the resource kind:
+
+- **Pod**: `spec.containers`
+- **Deployment, StatefulSet, DaemonSet, ReplicaSet, ReplicationController**: `spec.template.spec.containers`
+- **Job**: `spec.template.spec.containers`
+- **CronJob**: `spec.jobTemplate.spec.template.spec.containers`
+
+### Variable Resolution
+
+Images containing unresolved variables (e.g., `${TAG}`) 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 Kubernetes=EnableIfDefaultOff`
+- **Broad File Matching**: The `*.yaml` and `*.yml` search patterns match all YAML files, so the detector relies on content-based filtering (`apiVersion` and `kind` fields) to identify Kubernetes manifests
+- **Variable Resolution**: Image references containing unresolved template variables are not reported
+- **Limited Resource Kinds**: Only the eight resource kinds listed above are supported. Custom resources (CRDs) or other workload types are not detected
+- **No Dependency Graph**: All detected images are registered as independent components without parent-child relationships

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

@@ -38,6 +38,15 @@ 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;
+
     public static DockerReference ParseQualifiedName(string qualifiedName)
     {
         var regexp = DockerRegex.ReferenceRegexp;

src/Microsoft.ComponentDetection.Contracts/DetectorClass.cs

@@ -47,4 +47,13 @@ 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,
+
+    /// <summary>Indicates a detector applies to Helm chart image references.</summary>
+    Helm,
+
+    /// <summary>Indicates a detector applies to Kubernetes manifest image references.</summary>
+    Kubernetes,
 }

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

@@ -0,0 +1,145 @@
+#nullable disable
+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 => [Enum.GetName(typeof(DetectorClass), 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, file.Location);
+                }
+            }
+        }
+        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, string fileLocation)
+    {
+        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))
+                    {
+                        this.TryRegisterImageReference(imageRef, recorder, fileLocation);
+                    }
+                }
+            }
+        }
+    }
+
+    private void TryRegisterImageReference(string imageReference, ISingleFileComponentRecorder recorder, string fileLocation)
+    {
+        if (DockerReferenceUtility.HasUnresolvedVariables(imageReference))
+        {
+            return;
+        }
+
+        try
+        {
+            var dockerRef = DockerReferenceUtility.ParseFamiliarName(imageReference);
+            if (dockerRef != null)
+            {
+                recorder.RegisterUsage(new DetectedComponent(dockerRef.ToTypedDockerReferenceComponent()));
+            }
+        }
+        catch (Exception e)
+        {
+            this.Logger.LogWarning(e, "Failed to parse image reference '{ImageReference}' in {Location}", imageReference, fileLocation);
+        }
+    }
+}