Rename flag to ExcludeBaseImageComponents and add docs

Author: jasonpaulos

docs/detectors/linux.md

@@ -54,3 +54,15 @@ For example:
 
 - Windows container scanning is not supported
 - Multiplatform images are not supported
+
+## Excluding Base Image Components
+
+When scanning container images, many detected components may originate from the base image rather than from layers added by the user's Dockerfile. The `--ExcludeBaseImageComponents` flag filters out components that exist exclusively in base image layers, so only components introduced by the user's own layers are reported.
+
+```sh
+--ExcludeBaseImageComponents
+```
+
+A component is excluded only if **all** of its associated container layers are marked as base image layers. If a component appears in at least one non-base-image layer, it is retained.
+
+This flag has no effect on non-container scans (i.e., directory-based detection).

src/Microsoft.ComponentDetection.Orchestrator/Commands/ScanSettings.cs

@@ -86,9 +86,9 @@ public class ScanSettings : BaseSettings
     [Description("Whether or not to cleanup files that are created during detection, based on the rules provided in each detector. Defaults to 'true'.")]
     public bool? CleanupCreatedFiles { get; set; }
 
-    [CommandOption("--FilterBaseImageComponents")]
+    [CommandOption("--ExcludeBaseImageComponents")]
     [Description("When enabled, filters out components that originate exclusively from base image layers when scanning containers.")]
-    public bool FilterBaseImageComponents { get; set; }
+    public bool ExcludeBaseImageComponents { get; set; }
 
     /// <inheritdoc />
     public override ValidationResult Validate()

src/Microsoft.ComponentDetection.Orchestrator/Services/GraphTranslation/DefaultGraphTranslationService.cs

@@ -42,7 +42,7 @@ public ScanResult GenerateScanResultFromProcessingResult(
         ReconcileDependencyGraphIds(dependencyGraphs, mergedComponents);
 
         var componentsToOutput = mergedComponents;
-        if (settings.FilterBaseImageComponents)
+        if (settings.ExcludeBaseImageComponents)
         {
             var originalCount = mergedComponents.Count;
             componentsToOutput = this.FilterOutBaseImageComponents(componentsToOutput, detectorProcessingResult.ContainersDetailsMap);

test/Microsoft.ComponentDetection.Orchestrator.Tests/Services/DefaultGraphTranslationServiceTests.cs

@@ -566,7 +566,7 @@ public void GenerateScanResult_MultipleRichAndBare_BareGraphDataAbsorbedByAllRic
     }
 
     [TestMethod]
-    public void FilterBaseImageComponents_RemovesComponentsExclusivelyFromBaseImageLayers()
+    public void ExcludeBaseImageComponents_RemovesComponentsExclusivelyFromBaseImageLayers()
     {
         var singleFileRecorder = this.componentRecorder.CreateSingleFileComponentRecorder(Path.Join(this.sourceDirectory.FullName, "file1"));
 
@@ -590,13 +590,13 @@ public void FilterBaseImageComponents_RemovesComponentsExclusivelyFromBaseImageL
         };
 
         var result = this.serviceUnderTest.GenerateScanResultFromProcessingResult(
-            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, FilterBaseImageComponents = true });
+            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, ExcludeBaseImageComponents = true });
 
         result.ComponentsFound.Should().BeEmpty();
     }
 
     [TestMethod]
-    public void FilterBaseImageComponents_RetainsComponentsWithMixedLayers()
+    public void ExcludeBaseImageComponents_RetainsComponentsWithMixedLayers()
     {
         var singleFileRecorder = this.componentRecorder.CreateSingleFileComponentRecorder(Path.Join(this.sourceDirectory.FullName, "file1"));
 
@@ -621,14 +621,14 @@ public void FilterBaseImageComponents_RetainsComponentsWithMixedLayers()
         };
 
         var result = this.serviceUnderTest.GenerateScanResultFromProcessingResult(
-            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, FilterBaseImageComponents = true });
+            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, ExcludeBaseImageComponents = true });
 
         result.ComponentsFound.Should().HaveCount(1);
         ((NpmComponent)result.ComponentsFound.Single().Component).Name.Should().Be("mixed-pkg");
     }
 
     [TestMethod]
-    public void FilterBaseImageComponents_RetainsComponentsWithNoContainerReferences()
+    public void ExcludeBaseImageComponents_RetainsComponentsWithNoContainerReferences()
     {
         var singleFileRecorder = this.componentRecorder.CreateSingleFileComponentRecorder(Path.Join(this.sourceDirectory.FullName, "file1"));
 
@@ -652,14 +652,14 @@ public void FilterBaseImageComponents_RetainsComponentsWithNoContainerReferences
         };
 
         var result = this.serviceUnderTest.GenerateScanResultFromProcessingResult(
-            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, FilterBaseImageComponents = true });
+            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, ExcludeBaseImageComponents = true });
 
         result.ComponentsFound.Should().HaveCount(1);
         ((NpmComponent)result.ComponentsFound.Single().Component).Name.Should().Be("fs-pkg");
     }
 
     [TestMethod]
-    public void FilterBaseImageComponents_NoOpWhenFlagIsDisabled()
+    public void ExcludeBaseImageComponents_NoOpWhenFlagIsDisabled()
     {
         var singleFileRecorder = this.componentRecorder.CreateSingleFileComponentRecorder(Path.Join(this.sourceDirectory.FullName, "file1"));
 
@@ -683,14 +683,14 @@ public void FilterBaseImageComponents_NoOpWhenFlagIsDisabled()
         };
 
         var result = this.serviceUnderTest.GenerateScanResultFromProcessingResult(
-            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, FilterBaseImageComponents = false });
+            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, ExcludeBaseImageComponents = false });
 
         result.ComponentsFound.Should().HaveCount(1);
         ((NpmComponent)result.ComponentsFound.Single().Component).Name.Should().Be("base-pkg");
     }
 
     [TestMethod]
-    public void FilterBaseImageComponents_PrunesFilteredComponentsFromDependencyGraphs()
+    public void ExcludeBaseImageComponents_PrunesFilteredComponentsFromDependencyGraphs()
     {
         var filePath = Path.Join(this.sourceDirectory.FullName, "file1");
         var singleFileRecorder = this.componentRecorder.CreateSingleFileComponentRecorder(filePath);
@@ -719,7 +719,7 @@ public void FilterBaseImageComponents_PrunesFilteredComponentsFromDependencyGrap
         };
 
         var result = (DefaultGraphScanResult)this.serviceUnderTest.GenerateScanResultFromProcessingResult(
-            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, FilterBaseImageComponents = true });
+            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, ExcludeBaseImageComponents = true });
 
         // Only the non-base-image component should remain.
         result.ComponentsFound.Should().HaveCount(1);
@@ -740,7 +740,7 @@ public void FilterBaseImageComponents_PrunesFilteredComponentsFromDependencyGrap
     }
 
     [TestMethod]
-    public void FilterBaseImageComponents_DependencyGraphsUnchangedWhenFlagDisabled()
+    public void ExcludeBaseImageComponents_DependencyGraphsUnchangedWhenFlagDisabled()
     {
         var filePath = Path.Join(this.sourceDirectory.FullName, "file1");
         var singleFileRecorder = this.componentRecorder.CreateSingleFileComponentRecorder(filePath);
@@ -768,7 +768,7 @@ public void FilterBaseImageComponents_DependencyGraphsUnchangedWhenFlagDisabled(
         };
 
         var result = (DefaultGraphScanResult)this.serviceUnderTest.GenerateScanResultFromProcessingResult(
-            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, FilterBaseImageComponents = false });
+            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, ExcludeBaseImageComponents = false });
 
         // Both components should be present.
         result.ComponentsFound.Should().HaveCount(2);
@@ -780,7 +780,7 @@ public void FilterBaseImageComponents_DependencyGraphsUnchangedWhenFlagDisabled(
     }
 
     [TestMethod]
-    public void FilterBaseImageComponents_PrunesReferrersToFilteredComponents()
+    public void ExcludeBaseImageComponents_PrunesReferrersToFilteredComponents()
     {
         var filePath = Path.Join(this.sourceDirectory.FullName, "file1");
         var singleFileRecorder = this.componentRecorder.CreateSingleFileComponentRecorder(filePath);
@@ -809,7 +809,7 @@ public void FilterBaseImageComponents_PrunesReferrersToFilteredComponents()
         };
 
         var result = this.serviceUnderTest.GenerateScanResultFromProcessingResult(
-            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, FilterBaseImageComponents = true });
+            processingResult, new ScanSettings { SourceDirectory = this.sourceDirectory, ExcludeBaseImageComponents = true });
 
         // Only child-pkg should remain (base-pkg is exclusively from base image layer).
         result.ComponentsFound.Should().HaveCount(1);