Add component detectors for Docker Compose, Helm, and Kubernetes

.github/workflows/snapshot-publish.yml

@@ -69,7 +69,7 @@ jobs:
         run:
           dotnet run scan --Verbosity Verbose --SourceDirectory ${{ github.workspace }}/test/Microsoft.ComponentDetection.VerificationTests/resources --Output ${{ github.workspace }}/output
           --DockerImagesToScan "docker.io/library/debian@sha256:9b0e3056b8cd8630271825665a0613cc27829d6a24906dc0122b3b4834312f7d,mcr.microsoft.com/cbl-mariner/base/core@sha256:c1bc83a3d385eccbb2f7f7da43a726c697e22a996f693a407c35ac7b4387cd59,docker.io/library/alpine@sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870"
-          --DetectorArgs DockerReference=EnableIfDefaultOff,SPDX22SBOM=EnableIfDefaultOff --DirectoryExclusionList "**/pip/parallel/**;**/pip/roots/**;**/pip/pre-generated/**;**/pip/fallback/**;**/pip/index-removal/**;**/pip/simple-extras/**;**/pip/pytestresultpkg/**"
+          --DetectorArgs DockerReference=EnableIfDefaultOff,SPDX22SBOM=EnableIfDefaultOff,DockerCompose=EnableIfDefaultOff,Helm=EnableIfDefaultOff,Kubernetes=EnableIfDefaultOff --DirectoryExclusionList "**/pip/parallel/**;**/pip/roots/**;**/pip/pre-generated/**;**/pip/fallback/**;**/pip/index-removal/**;**/pip/simple-extras/**;**/pip/pytestresultpkg/**"
 
       - name: Upload output folder
         uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0

.github/workflows/snapshot-verify.yml

@@ -101,7 +101,7 @@ jobs:
         run:
           dotnet run scan --Verbosity Verbose --SourceDirectory ${{ github.workspace }}/test/Microsoft.ComponentDetection.VerificationTests/resources --Output ${{ github.workspace }}/output
           --DockerImagesToScan "docker.io/library/debian@sha256:9b0e3056b8cd8630271825665a0613cc27829d6a24906dc0122b3b4834312f7d,mcr.microsoft.com/cbl-mariner/base/core@sha256:c1bc83a3d385eccbb2f7f7da43a726c697e22a996f693a407c35ac7b4387cd59,docker.io/library/alpine@sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870"
-          --DetectorArgs DockerReference=EnableIfDefaultOff,SPDX22SBOM=EnableIfDefaultOff --MaxDetectionThreads 5 --DirectoryExclusionList "**/pip/parallel/**;**/pip/roots/**;**/pip/pre-generated/**;**/pip/fallback/**;**/pip/index-removal/**;**/pip/simple-extras/**;**/pip/pytestresultpkg/**"
+          --DetectorArgs DockerReference=EnableIfDefaultOff,SPDX22SBOM=EnableIfDefaultOff,DockerCompose=EnableIfDefaultOff,Helm=EnableIfDefaultOff,Kubernetes=EnableIfDefaultOff --MaxDetectionThreads 5 --DirectoryExclusionList "**/pip/parallel/**;**/pip/roots/**;**/pip/pre-generated/**;**/pip/fallback/**;**/pip/index-removal/**;**/pip/simple-extras/**;**/pip/pytestresultpkg/**"
 
       - name: Run Verification Tests
         working-directory: test/Microsoft.ComponentDetection.VerificationTests

.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,51 @@
+# 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
+- **Same-Directory Co-location**: Values files are only processed when a `Chart.yaml` (or `Chart.yml`) exists in the **same directory**. Values files in subdirectories of a chart root (e.g., `mychart/subdir/values.yaml`) will not be detected, even if a `Chart.yaml` exists in the parent directory
+- **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,59 @@
+# 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`
+- `PodTemplate`
+- `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,53 @@ 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>
+    /// <returns>A <see cref="DockerReference"/> if parsing succeeds; otherwise <c>null</c>.</returns>
+    public static DockerReference? TryParseImageReference(string imageReference)
+    {
+        if (HasUnresolvedVariables(imageReference))
+        {
+            return null;
+        }
+
+        try
+        {
+            return ParseFamiliarName(imageReference);
+        }
+        catch
+        {
+            return null;
+        }
+    }
+
+    /// <summary>
+    /// Parses an image reference and registers it with the recorder if valid.
+    /// Silently skips references with unresolved variables or that cannot be parsed.
+    /// </summary>
+    /// <param name="imageReference">The image reference string to parse.</param>
+    /// <param name="recorder">The component recorder to register the image with.</param>
+    public static void TryRegisterImageReference(string imageReference, ISingleFileComponentRecorder recorder)
+    {
+        var dockerRef = TryParseImageReference(imageReference);
+        if (dockerRef != null)
+        {
+            recorder.RegisterUsage(new DetectedComponent(dockerRef.ToTypedDockerReferenceComponent()));
+        }
+    }
+
     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,
 }