git.stella-ops.org/docs/modules/policy/windows-package-readiness.md

Windows Package Coverage — Policy & Security Readiness Brief

Audience: Policy Guild, Security Guild, Offline Kit Guild
Related engineering backlog (proposed): SCANNER-ENG-0024..0027
Docs linkage: DOCS-SCANNER-BENCH-62-016

1. Goal

• Prepare policy and security guidance ahead of Windows analyzer implementation (MSI, WinSxS, Chocolatey, registry).
• Define evidence handling, predicates, waiver expectations, and offline prerequisites so engineering can align during spike execution.

2. Evidence pipeline snapshot (from design/windows-analyzer.md)

1. Collection
   • MSI database parsing → component records keyed by ProductCode/ComponentCode.
   • WinSxS manifests → assembly identities, catalog signatures.
   • Chocolatey packages → nuspec metadata, feed provenance, script hashes.
   • Registry exports → uninstall/service entries, legacy installers.
   • Driver/service mapper → capability overlays (kernel-mode, auto-start).
2. Storage
   • Results persisted as LayerComponentFragments plus capability overlays (ScanAnalysisKeys.capability.windows).
   • Provenance metadata includes signature thumbprint, catalog hash, feed URL, install context.
3. Downstream
   • Policy Engine consumes component + capability evidence; Export Center bundles MSI manifests, nuspec metadata, catalog hashes.

3. Policy predicate requirements

Predicate	Description	Initial default
windows.package.signed(thumbprint?)	True when Authenticode signature/cert matches allowlist.	Warn on missing signature, fail on mismatched thumbprint for kernel drivers.
windows.package.sourceAllowed(sourceId)	Validates Chocolatey/nuget feed against tenant allowlist.	Fail if feed not in tenant policy.
windows.driver.kernelMode()	Flags kernel-mode drivers for extra scrutiny.	Fail when unsigned; warn otherwise.
windows.driver.signedBy(publisher)	Checks driver publisher matches allowlist.	Warn on unknown publisher.
windows.service.autoStart(name)	Identifies auto-start services.	Warn if unsigned binary or service not in allowlist.
windows.package.legacyInstaller()	Legacy EXE-only installers detected via registry.	Warn by default; escalate if binary unsigned.

Additional considerations:

• Map KB references (from WinSxS/MSP metadata) to vulnerability posture once Policy Engine supports patch layering.
• Provide predicates to waive specific ProductCodes or AssemblyIdentities with expiration.

4. Waiver & governance model

• Waiver key: {productCode, version, signatureThumbprint} or for drivers {driverName, serviceName, signatureThumbprint}.
• Required metadata: remediation ticket, justification, expiry date.
• Automated re-evaluation when version or signature changes.
• Tenants maintain allow lists for Chocolatey feeds and driver publishers via policy configuration.

5. Masking & privacy

• Findings should not include raw script contents; provide SHA256 hash and limited excerpt (first/last 8 chars).
• Registry values (install paths, command lines) must be truncated if they contain secrets; rely on Surface.Secrets to manage environment variables referenced during install scripts.

6. Offline kit guidance

• Bundle:
  • MSI parser binary + schema definitions.
  • Chocolatey feed snapshot(s) (nupkg files) with hash manifest.
  • Microsoft root/intermediate certificate bundles; optional CRL/OCSP cache instructions.
• Operators must export registry hives (SOFTWARE, SYSTEM) during image extraction; document PowerShell script and required access.
• Provide checksum manifest to verify feed snapshot integrity.

7. Telemetry expectations

• Metrics:
  • scanner.windows.package_total{tenant,signed} — count packages per signature state.
  • scanner.windows.driver_unsigned_total{tenant}.
  • scanner.windows.choco_feed_total{tenant,feed}.
• Logs:
  • Include product code, version, signature thumbprint, feed ID (no file paths unless sanitized).
• Traces:
  • Annotate collector spans (collector.windows.msi, collector.windows.winsxs, etc.) with component counts and parsing duration.

8. Open questions

Topic	Question	Owner	Target decision
Signature verification locus	Scanner vs Policy: where to verify Authenticode signatures + revocation?	Security Guild	Sprint 133
Feed mirroring scope	Default set of Chocolatey feeds to mirror (official/community).	Product + Security Guild	Sprint 133
Legacy installers	Should we block unsigned EXE installers by default or allow warn-only posture?	Policy Guild	Sprint 134
Driver taxonomy	Define high-risk driver categories (kernel-mode, filter drivers) for policy severity.	Policy Guild	Sprint 134

Decision tracker

Decision	Owner(s)	Target date	Status
Authenticode verification locus (Scanner vs Policy)	Security Guild	2025-11-07	Pending — blocker for FinSecure
Chocolatey feed mirroring scope	Product + Security Guild	2025-11-07	Draft proposal circulating
Legacy installer posture (warn vs fail)	Policy Guild	2025-11-14	Not started
Driver risk taxonomy	Policy Guild	2025-11-14	Not started

9. Next steps

1. Policy Guild drafts predicate specs + policy templates; align with DOCS-SCANNER-BENCH-62-016.
2. Security Guild evaluates signature verification approach and revocation handling (online vs offline CRL cache).
3. Offline Kit Guild scopes snapshot size and update cadence for Chocolatey feeds and certificate bundles.
4. Docs Guild prepares policy/user guidance updates once predicates are finalised.
5. Security Guild to report decision for FinSecure Corp (POLICY-READINESS-0002) by 2025-11-07; feed outcome into dashboards.

Coordination

• Sync demand signals via docs/benchmarks/scanner/windows-macos-demand.md.
• Log policy readiness status in docs/api/scanner/windows-coverage.md.
• Update Windows/macOS metrics dashboard when decisions change (docs/api/scanner/windows-macos-summary.md).