fix(security): gate source extraction on deep_scan + wire deep-scan report banner

Address adversarial review findings on Spec 077 US3 (PR #789):

- #1 (MUST): published-package-source extraction is now part of the opt-in
  deep-scan layer. server.go computes the effective fetch as
  IsDeepScanEnabled() && fetch_package_source (default true), and
  SetDeepScan(false) force-disables the resolver's fetch fallback as
  defense-in-depth. Deep scan OFF (default) => no npx/uvx source-fetch
  network egress. Added TestServiceDeepScanGatesPackageSourceFetch and
  updated the doc comments to match.

- #2 (MUST): the deep-scan report banner was dead code — AggregatedReport
  had no DeepScan field, so /scan/report and /scans/{jobId}/report never
  emitted deep_scan. Added DeepScan *DeepScanDescriptor (json deep_scan,
  omitempty) to AggregatedReport and populate it in GetScanReport and
  GetScanReportByJobID (the live report-page path).

- #3 (LOW): buildDeepScanDescriptor now inspects Pass-1 AND Pass-2 scanner
  statuses (variadic jobs, deduped) so heavy trivy/supply-chain scanner
  failures are reflected in scanners_failed/availability.

Baseline verdict logic and the quarantine state machine are unchanged.

Related: Spec 077

Author: Dumbris

internal/security/scanner/service.go

@@ -222,6 +222,15 @@ func (s *Service) SetDeepScan(enabled bool, scanners []string) {
 	} else {
 		s.engine.deepScanScanners = nil
 	}
+	// Spec 077 US3: published-package-source extraction is part of the opt-in
+	// deep-scan layer, so it must never run (and never cause network egress)
+	// while deep scan is off. Force the resolver's fetch fallback off here as
+	// defense-in-depth. When deep scan is ENABLED the server layer decides the
+	// concrete value from deep_scan.fetch_package_source (default true) via
+	// SetFetchPackageSource, so we deliberately do not flip it back on here.
+	if !enabled && s.sourceResolver != nil {
+		s.sourceResolver.SetFetchPackageSource(false)
+	}
 	if enabled {
 		s.logger.Info("Deep scan enabled (security.deep_scan.enabled=true): Docker scanner " +
 			"plugins + published-package-source extraction may run as an opt-in enrichment " +
@@ -248,30 +257,47 @@ func (s *Service) isBaselineScanner(scannerID string) bool {
 }
 
 // buildDeepScanDescriptor assembles the informational deep-scan availability
-// descriptor (Spec 077 FR-008) from a job's per-scanner statuses. It reports the
-// opt-in layer's state SEPARATELY from the baseline verdict and MUST NOT
-// influence ScanSummary.Status. Returns nil when deep scan is disabled, so the
-// descriptor is omitted entirely and the invariant (Enabled=false ⇒ everything
-// empty) holds.
-func (s *Service) buildDeepScanDescriptor(job *ScanJob) *DeepScanDescriptor {
-	if job == nil || !s.deepScanEnabled() {
+// descriptor (Spec 077 FR-008) from the per-scanner statuses of one or more
+// jobs. It reports the opt-in layer's state SEPARATELY from the baseline verdict
+// and MUST NOT influence ScanSummary.Status. Both passes are considered: Pass 1
+// (security scan) and Pass 2 (supply-chain audit, where the heavy trivy /
+// supply-chain scanners run), so a Pass-2 scanner failure is reflected too.
+// Returns nil when deep scan is disabled, so the descriptor is omitted entirely
+// and the invariant (Enabled=false ⇒ everything empty) holds.
+func (s *Service) buildDeepScanDescriptor(jobs ...*ScanJob) *DeepScanDescriptor {
+	if !s.deepScanEnabled() {
 		return nil
 	}
+	haveJob := false
 	desc := &DeepScanDescriptor{Enabled: true}
-	for _, ss := range job.ScannerStatuses {
-		if s.isBaselineScanner(ss.ScannerID) {
-			continue // baseline coverage drives Status, not the descriptor
-		}
-		switch ss.Status {
-		case ScanJobStatusCompleted:
-			desc.Ran = true
-			desc.Available = true
-		case ScanJobStatusFailed:
-			desc.ScannersFailed = append(desc.ScannersFailed, DeepScanScannerFailure{
-				ID:     ss.ScannerID,
-				Reason: ss.Error,
-			})
+	seenFailed := make(map[string]bool)
+	for _, job := range jobs {
+		if job == nil {
+			continue
 		}
+		haveJob = true
+		for _, ss := range job.ScannerStatuses {
+			if s.isBaselineScanner(ss.ScannerID) {
+				continue // baseline coverage drives Status, not the descriptor
+			}
+			switch ss.Status {
+			case ScanJobStatusCompleted:
+				desc.Ran = true
+				desc.Available = true
+			case ScanJobStatusFailed:
+				if seenFailed[ss.ScannerID] {
+					continue // dedupe the same deep scanner across passes
+				}
+				seenFailed[ss.ScannerID] = true
+				desc.ScannersFailed = append(desc.ScannersFailed, DeepScanScannerFailure{
+					ID:     ss.ScannerID,
+					Reason: ss.Error,
+				})
+			}
+		}
+	}
+	if !haveJob {
+		return nil
 	}
 	return desc
 }
@@ -303,8 +329,14 @@ func (s *Service) resolveIsolationMode(serverName string) string {
 }
 
 // SetFetchPackageSource toggles whether the source resolver may fetch the
-// published source of package-runner servers (npx/uvx) for scanning. See
-// SecurityConfig.ScannerFetchPackageSource (MCP-2206). Default is enabled.
+// published source of package-runner servers (npx/uvx) for scanning. This is a
+// facet of the opt-in deep-scan layer (Spec 077 US3): the server layer only
+// enables it when security.deep_scan.enabled is true AND
+// security.deep_scan.fetch_package_source is not explicitly false (the
+// deprecated top-level ScannerFetchPackageSource, MCP-2206, is still honored as
+// a fallback). With deep scan off the effective value is always false, so
+// scanning an npx/uvx server performs no published-package-source network
+// egress by default.
 func (s *Service) SetFetchPackageSource(enabled bool) {
 	if s.sourceResolver == nil {
 		return
@@ -1219,6 +1251,12 @@ func (s *Service) GetScanReport(ctx context.Context, serverName string) (*Aggreg
 	agg.ScanContext = primaryJob.ScanContext
 	agg.ScannerStatuses = primaryJob.ScannerStatuses
 
+	// Spec 077 US3 (FR-008): mirror the opt-in deep-scan availability descriptor
+	// onto the report so the report page renders the informational banner. Both
+	// passes are considered. Informational only — never changes the verdict; nil
+	// (omitted) when deep scan is off.
+	agg.DeepScan = s.buildDeepScanDescriptor(pass1Job, pass2Job)
+
 	return agg, nil
 }
 
@@ -1315,6 +1353,7 @@ func (s *Service) GetScanReportByJobID(ctx context.Context, jobID string) (*Aggr
 	// If this is a Pass 1 job, try to find and merge companion Pass 2 results.
 	// The companion is resolved via the lightweight scan-job index, so this does
 	// NOT deserialize the full per-server scan history (MCP-2205).
+	var companionPass2 *ScanJob
 	if job.ScanPass == ScanPassSecurityScan || job.ScanPass == 0 {
 		if companionID := s.findCompanionPass2JobID(job); companionID != "" {
 			pass2Reports, err := s.storage.ListScanReportsByJob(companionID)
@@ -1330,6 +1369,12 @@ func (s *Service) GetScanReportByJobID(ctx context.Context, jobID string) (*Aggr
 				agg.Pass1Complete = true
 				agg.Pass2Complete = true
 			}
+			// Load the companion Pass-2 job so its per-scanner statuses feed the
+			// deep-scan descriptor (Spec 077 FR-008) — the heavy trivy /
+			// supply-chain scanners run in Pass 2.
+			if cj, cerr := s.storage.GetScanJob(companionID); cerr == nil {
+				companionPass2 = cj
+			}
 		}
 
 		// Check if Pass 2 is running
@@ -1342,6 +1387,13 @@ func (s *Service) GetScanReportByJobID(ctx context.Context, jobID string) (*Aggr
 	agg.ScanContext = job.ScanContext
 	agg.ScannerStatuses = job.ScannerStatuses
 
+	// Spec 077 US3 (FR-008): mirror the opt-in deep-scan availability descriptor
+	// so the report page renders the informational banner. Considers this job and
+	// its companion Pass-2 job (when the requested job is a Pass-1 job).
+	// Informational only — never changes the verdict; nil (omitted) when deep
+	// scan is off.
+	agg.DeepScan = s.buildDeepScanDescriptor(job, companionPass2)
+
 	return agg, nil
 }
 
@@ -1782,7 +1834,7 @@ func (s *Service) GetScanSummary(ctx context.Context, serverName string) *ScanSu
 	// informational dimension. This never influences Status — a failed or
 	// unavailable deep scanner leaves the baseline verdict untouched. Nil (and
 	// thus omitted) when deep scan is off.
-	summary.DeepScan = s.buildDeepScanDescriptor(primaryJob)
+	summary.DeepScan = s.buildDeepScanDescriptor(pass1Job, pass2Job)
 
 	// Check if the primary job failed
 	if primaryJob.Status == ScanJobStatusFailed {

internal/security/scanner/service_test.go

@@ -2234,3 +2234,45 @@ func TestServiceDeepScanOffByDefault(t *testing.T) {
 		t.Errorf("non-allow-listed deep scanner must be dropped; got %v", ids)
 	}
 }
+
+// TestServiceDeepScanGatesPackageSourceFetch verifies Spec 077 US3: published-
+// package-source extraction is a facet of the opt-in deep-scan layer, so it must
+// not run (no network egress) while deep scan is off. Turning the deep-scan
+// layer off must force the source resolver's fetch fallback off; the server
+// layer re-enables it (honoring fetch_package_source) only when deep scan is on.
+func TestServiceDeepScanGatesPackageSourceFetch(t *testing.T) {
+	dir := t.TempDir()
+	logger := zap.NewNop()
+	store := newMockStorage()
+	docker := NewDockerRunner(logger)
+	registry := NewRegistry(dir, logger)
+
+	svc := NewService(store, registry, docker, dir, logger)
+
+	// Simulate an operator who had opted into source fetch previously.
+	svc.SetFetchPackageSource(true)
+	if !svc.sourceResolver.fetchPackageSource {
+		t.Fatalf("precondition: fetch should be enabled after SetFetchPackageSource(true)")
+	}
+
+	// Deep scan OFF (the default) must forbid the published-package-source fetch
+	// so scanning an npx/uvx server performs no network egress.
+	svc.SetDeepScan(false, nil)
+	if svc.sourceResolver.fetchPackageSource {
+		t.Errorf("deep scan off must force source fetch off (no egress by default)")
+	}
+
+	// The server layer is the authority when deep scan is on: it calls
+	// SetFetchPackageSource with deep_scan.fetch_package_source (default true).
+	svc.SetDeepScan(true, nil)
+	svc.SetFetchPackageSource(true)
+	if !svc.sourceResolver.fetchPackageSource {
+		t.Errorf("deep scan on with fetch_package_source=true must allow source fetch")
+	}
+
+	// An explicit fetch_package_source=false still wins while deep scan is on.
+	svc.SetFetchPackageSource(false)
+	if svc.sourceResolver.fetchPackageSource {
+		t.Errorf("explicit fetch_package_source=false must disable source fetch")
+	}
+}

internal/security/scanner/source_resolver.go

@@ -23,11 +23,14 @@ import (
 type SourceResolver struct {
 	logger *zap.Logger
 
-	// fetchPackageSource, when true (the default), allows the resolver to fetch
-	// the PUBLISHED source of a package-runner server (npx/uvx) — without
-	// executing it — as a last resort before falling back to a
-	// tool-definitions-only scan. Air-gapped deployments can disable this via
-	// security.deep_scan.fetch_package_source=false to forbid network egress.
+	// fetchPackageSource, when true, allows the resolver to fetch the PUBLISHED
+	// source of a package-runner server (npx/uvx) — without executing it — as a
+	// last resort before falling back to a tool-definitions-only scan. This is a
+	// facet of the opt-in deep-scan layer (Spec 077 US3): the server layer keeps
+	// it false unless security.deep_scan.enabled is true, and even then honors
+	// security.deep_scan.fetch_package_source (default true) so air-gapped
+	// deployments can forbid the network egress. With deep scan off it is always
+	// false, so no published-package-source fetch happens by default.
 	fetchPackageSource bool
 }
 

internal/security/scanner/types.go

@@ -300,6 +300,11 @@ type AggregatedReport struct {
 	// Scan context from the primary job (for report page display)
 	ScanContext     *ScanContext       `json:"scan_context,omitempty"`
 	ScannerStatuses []ScannerJobStatus `json:"scanner_statuses,omitempty"` // Per-scanner execution logs
+	// DeepScan is the opt-in heavy-layer availability descriptor (Spec 077 US3),
+	// mirrored from ScanSummary so the report page can render the informational
+	// deep-scan banner. Informational only — a failed or unavailable deep scanner
+	// never changes the baseline verdict. nil/omitted when deep scan is disabled.
+	DeepScan *DeepScanDescriptor `json:"deep_scan,omitempty"`
 }
 
 // ReportSummary provides counts by severity and threat level

internal/server/server.go

@@ -2000,12 +2000,18 @@ func (s *Server) startCustomHTTPServer(ctx context.Context, streamableServer *se
 			im := core.NewIsolationManager(liveCfg.DockerIsolation)
 			return string(im.ResolveMode(sc))
 		})
-		// Published-package-source fetch is enabled by default; only an explicit
-		// false in config disables it (MCP-2206).
+		// Spec 077 US3: published-package-source extraction is part of the opt-in
+		// deep-scan layer, so it only runs when deep scan is enabled. When enabled
+		// it honors deep_scan.fetch_package_source (default true; an explicit
+		// false — or the deprecated top-level ScannerFetchPackageSource, MCP-2206 —
+		// forbids the network egress for air-gapped hosts). Deep scan OFF (the
+		// default) ⇒ no source fetch/egress at all.
 		if cfg != nil && cfg.Security != nil {
-			if fetch := cfg.Security.EffectiveFetchPackageSource(); fetch != nil && !*fetch {
-				secService.SetFetchPackageSource(false)
+			fetchPref := true
+			if fetch := cfg.Security.EffectiveFetchPackageSource(); fetch != nil {
+				fetchPref = *fetch
 			}
+			secService.SetFetchPackageSource(cfg.Security.IsDeepScanEnabled() && fetchPref)
 		}
 		secService.SetEmitter(s.runtime)
 		secService.SetServerInfoProvider(&configServerInfoProvider{