feat: Update external package protection guidance and remediation steps for clarity

Author: aj-enns

docs/controls.html

@@ -951,15 +951,16 @@ <h3><span class="id-badge">FEED-02</span><span class="control-name">Feed Creatio
       <article class="control-card" id="external-package-protection" data-name="External Package Protection" data-id="FEED-03">
         <h3><span class="id-badge">FEED-03</span><span class="control-name">External Package Protection</span></h3>
         <div class="control-body">
-          <p class="description">Reviews Artifacts upstream sources to limit pulling from public registries and protect against dependency-confusion attacks.</p>
+          <p class="description">Advisory: flags feeds with active upstream sources. Upstreams are usually required; the real mitigation against dependency-confusion is to publish every internal package name to the feed at least once (save-to-feed) so the local copy always wins over public registries.</p>
           <details class="steps-details">
             <summary>Remediation steps</summary>
             <ol>
-              <li>Navigate to Artifacts &gt; select the feed.</li>
-              <li>Click the gear icon (Feed settings).</li>
-              <li>Review Upstream sources.</li>
-              <li>Disable unnecessary upstream sources.</li>
-              <li>Enable "Override packages from public sources" protection if available.</li>
+              <li>Decide whether each upstream (npmjs, nuget.org, Maven Central, etc.) is required. Disable any that aren't.</li>
+              <li>List every internal package name your org publishes.</li>
+              <li>Publish each internal name to the feed at least once so it's saved-to-feed.</li>
+              <li>For npm, use scoped package names (<code>@your-scope/...</code>).</li>
+              <li>Filter the feed view by <em>Saved</em> periodically to confirm internal names are present.</li>
+              <li>Document acceptance of FEED-03 in your remediation log once the mitigation is verified.</li>
             </ol>
             <a class="doc-link" href="https://learn.microsoft.com/en-us/azure/devops/artifacts/concepts/upstream-sources" target="_blank" rel="noopener">Microsoft Learn &rarr;</a>
           </details>

invoke-adoqr.ps1

@@ -3178,31 +3178,31 @@ function Test-OrgFeeds {
     # FEED-02: Feed creation permissions — not easily checked via API
     $results.Add((New-ControlResult -Id "FEED-02" -Status "NOT CHECKED" -Severity "High" -Control "Feed Creation Permissions" -Finding "Manual review required. Check who can create feeds in Organization Settings."))
 
-    # FEED-03: External package protection — check upstream source settings on each feed
+    # FEED-03: External package protection — upstreams can't be assessed reliably via API.
+    # The real mitigation (save-to-feed / package source protection) isn't surfaced in the
+    # feed payload, so flag feeds with active upstreams as advisory rather than FAIL.
     if ($feeds -and $feeds.value -and $feeds.value.Count -gt 0) {
-        $unprotectedFeeds = [System.Collections.Generic.List[string]]::new()
+        $feedsWithUpstreams = [System.Collections.Generic.List[string]]::new()
         foreach ($feed in $feeds.value) {
             $upstreamEnabled = Get-SafeProperty $feed 'upstreamEnabled'
             $upstreamSources = Get-SafeProperty $feed 'upstreamSources'
             if ($upstreamEnabled -eq $true -and $upstreamSources) {
-                # Check if any upstream source lacks upstream protection
                 foreach ($src in $upstreamSources) {
-                    $protocol = Get-SafeProperty $src 'protocol'
                     $status = Get-SafeProperty $src 'status'
                     if ($status -ne 'disabled') {
-                        $unprotectedFeeds.Add($feed.name)
+                        $feedsWithUpstreams.Add($feed.name)
                         break
                     }
                 }
             }
         }
-        if ($unprotectedFeeds.Count -eq 0) {
-            $results.Add((New-ControlResult -Id "FEED-03" -Status "PASS" -Severity "High" -Control "External Package Protection" -Finding "All org-level feeds have upstream sources disabled or protected."))
+        if ($feedsWithUpstreams.Count -eq 0) {
+            $results.Add((New-ControlResult -Id "FEED-03" -Status "PASS" -Severity "Medium" -Control "External Package Protection" -Finding "No org-scoped feeds have active upstream sources."))
         } else {
-            $results.Add((New-ControlResult -Id "FEED-03" -Status "FAIL" -Severity "High" -Control "External Package Protection" -Finding "Feeds with active upstream sources: $($unprotectedFeeds -join ', '). Review upstream source protection settings."))
+            $results.Add((New-ControlResult -Id "FEED-03" -Status "NOT CHECKED" -Severity "Medium" -Control "External Package Protection" -Finding "Feeds with active upstream sources: $($feedsWithUpstreams -join ', '). Upstreams are typically required for npm/NuGet/Maven; the dependency-confusion mitigation is to publish every internal package name to the feed at least once (save-to-feed makes the local copy win over upstream). Verify each internal package name is saved, and accept this control if the mitigation is in place."))
         }
     } else {
-        $results.Add((New-ControlResult -Id "FEED-03" -Status "PASS" -Severity "High" -Control "External Package Protection" -Finding "No org-level feeds found."))
+        $results.Add((New-ControlResult -Id "FEED-03" -Status "PASS" -Severity "Medium" -Control "External Package Protection" -Finding "No org-scoped feeds found."))
     }
 
     # BADGE-01: Anonymous Badge API — check org pipeline settings

remediation-steps.psd1

@@ -171,7 +171,7 @@
         DocUrl = 'https://learn.microsoft.com/en-us/azure/devops/artifacts/feeds/feed-permissions'
     }
     'External Package Protection' = @{
-        Steps = @('Navigate to Artifacts > select the feed.','Click the gear icon (Feed settings).','Review Upstream sources.','Disable unnecessary upstream sources.','Enable "Override packages from public sources" protection if available.')
+        Steps = @('Decide whether the upstreams (npmjs, nuget.org, Maven Central, etc.) are required. If not, disable them in feed Settings > Upstream sources.','If upstreams are required, apply the dependency-confusion mitigation: list every internal package name your org publishes (e.g., @contoso/utils, Contoso.Common).','Publish each internal package name to the feed at least once. Once a name is saved-to-feed, Azure Artifacts always serves the local copy and never pulls a same-named package from upstream.','For npm, use a scoped package name (@your-scope/...) so public-registry names cannot collide.','Periodically review the feed view filtered by Saved to confirm every internal name is present.','Document acceptance of FEED-03 in your remediation log once the save-to-feed mitigation is verified.','Reach the feed via any project: Artifacts > feed picker > switch to "All feeds in this organization" > select the feed > gear icon.')
         DocUrl = 'https://learn.microsoft.com/en-us/azure/devops/artifacts/concepts/upstream-sources'
     }
     'Maximum PAT Lifetime Policy' = @{