This repository has been archived on 2026-09-16. You can view files and clone it, but cannot push or open issues or pull requests.
win-diagnostics-analysis/docs/migration-inventory.md

12 KiB
Raw Blame History

Legacy diagnostics inventory and first contract decisions

Source and scope

Inspected 2026-09-15 at pinned revisions:

  • WinDiagnostics: 1de4d425ecca3a97bcbffd4c8b5ebec464810ac8.
  • typst_reporter: 1d381904fff3d378a7c0e04588e75310a9b7ed60.

This inventories the collector and normalization/analysis source for the initial offline migration slice. It records existing behavior, not an endorsement of medical, security, or vendor remediation advice. External advisory URLs have not been revalidated; advisory review remains required before rule publication.

Collection boundary

The collector requires PowerShell 5.1 or later and native Windows APIs. It uses CIM, registry, event logs, storage/Defender cmdlets, and native Windows commands. Some APIs may be unavailable; elevated checks include storage reliability, DISM /CheckHealth, and SFC /verifyonly. It writes JSON and temporary probe/SFC files; it does not run repair commands. Native behavior has not been executed on this Linux host (PowerShell is unavailable).

-Compact, -Mid, and -Full are mutually exclusive; omitted means Full. -OutputDirectory defaults to writable Documents, then TEMP. Output filenames contain hostname and collection timestamp; the script returns the saved path. -EventLogDays defaults to 7 (1–3650), -MaxEventErrors to 100 (1–5000), and -JsonDepth to 12 (3–100). Output is UTF-8 without BOM, capture schema 2.

The capture envelope is schema_version, report_type, mode, generated_at, completed_at, host, parameters, warnings, summary, and sections. Full adds diagnostic_collection. Section envelopes contain status, count, data, and error; event sections additionally record limit and truncated. Native command records retain executable, arguments, exit code, and output.

Collector function inventory

All functions below belong to win-diagnostics; retain implementation provenance and separate collection plumbing from normalization/analysis during extraction.

  • Test-IsAdministrator
  • Test-DirectoryWritable
  • Get-InstalledPrograms
  • Get-StartupRegistryEntries
  • Get-ProblemDevices
  • Invoke-ReportSection
  • New-SkippedSection
  • New-UnavailableSection
  • Get-StorageReport
  • Get-DefenderReport
  • Invoke-NativeCommand

Get-CompactData is nested in Compact mode. The top-level mode branches populate sections and summary; these are substantial collection logic, not just CLI glue.

Typst normalizer function inventory

  • get
  • value-text
  • enabled
  • legacy-incomplete
  • first
  • section
  • section-data
  • section-first
  • section-count
  • section-status
  • number
  • bool-text
  • is-leap-year
  • date-index
  • datetime-day
  • datetime-second
  • display-time
  • display-date
  • fade-weight
  • event-rule
  • capture
  • event-summary
  • event-sections
  • windows-level
  • raw-events
  • group-events
  • catalog-correlation
  • command-output
  • object-lines
  • watchlist-catalog
  • watch-matches
  • watchlist-findings
  • reliability-events
  • normalize

Classification:

  • Evidence access/conversion: get, first, section*, number, enabled, legacy-incomplete, command-output, raw-events, event-sections, reliability-events, and date parsing belong to win-diagnostics.
  • Rules: fade-weight, event-rule, group-events, catalog-correlation, watch-matches, and matching in watchlist-findings belong to win-diagnostics.
  • Presentation: value-text, bool-text, display-time, display-date, windows-level, event-summary, and object-lines must be split: retain typed facts in diagnostics; move report-facing formatting into the report adapter.
  • normalize combines all three concerns. Its technical findings and evidence coverage belong here; health headline prose, display inventory/excerpts, and report-ready remediation belong to beffroi-reports. Generic display widgets belong to Reportist. Do not port the entire function as the public interface.
  • Helpers capture, is-leap-year, date-index, and watchlist-catalog support their owning normalization/rule operation; no runtime Typst/YAML imports should remain in the diagnostic engine merely to reproduce legacy implementation.

Rule-by-rule ownership

All provider/ID matchers below describe generic technical events. Diagnostic matching, evidence, severity, confidence, and any fading stay in win-diagnostics. Report-ready remediation, resolution_steps, and recipient-facing recommendations move to the adapter/content layer. Preserve rationale/reference provenance for review; event IDs alone must not become unsupported root-cause claims.

Provider ID Existing severity Fading Owner
Microsoft-Windows-WER-SystemErrorReporting 1001 critical no win-diagnostics
volmgr 162 info no win-diagnostics
stornvme 11 critical no win-diagnostics
Microsoft-Windows-TPM-WMI 1040 critical no win-diagnostics
Service Control Manager 7000 warning yes win-diagnostics
Service Control Manager 7009 warning yes win-diagnostics
Microsoft-Windows-NDIS 10317 warning no win-diagnostics
Application Error 1000 warning yes win-diagnostics
Microsoft-Windows-WindowsUpdateClient 20 warning yes win-diagnostics
Application Hang 1002 warning yes win-diagnostics
MsiInstaller 1043 warning yes win-diagnostics
Volsnap 36 warning no win-diagnostics
Service Control Manager 7043 warning yes win-diagnostics
Microsoft-Windows-DistributedCOM 10010 info no win-diagnostics
EventLog 6008 warning no win-diagnostics
Service Control Manager 7023 warning yes win-diagnostics
MsiInstaller 11704 warning yes win-diagnostics
MsiInstaller 11722 warning yes win-diagnostics
VSS 12344 warning no win-diagnostics
.NET Runtime 1022 info no win-diagnostics
Waterfox Default Browser Agent 5 info no win-diagnostics
Microsoft-Windows-Kernel-Boot 29 warning no win-diagnostics
Service Control Manager 7031 warning no win-diagnostics
Microsoft-Windows-DeviceAssociationService 3505 warning no win-diagnostics
Microsoft-Windows-HAL 15 warning no win-diagnostics
Microsoft-Windows-HAL 21 warning no win-diagnostics
usbaudio2 38 warning no win-diagnostics
ESENT 419 critical no win-diagnostics
ESENT 474 critical no win-diagnostics
ESENT 907 critical no win-diagnostics
ESENT 908 critical no win-diagnostics
Microsoft-Windows-Defrag 264 warning no win-diagnostics
Microsoft-Windows-WLAN-AutoConfig 10002 info no win-diagnostics
Microsoft-Windows-DistributedCOM 10016 info no win-diagnostics
Netwtw10 6062 info no win-diagnostics
Microsoft-Windows-Hyper-V-Hypervisor 167 warning no win-diagnostics
volmgr 161 warning no win-diagnostics
Microsoft-Windows-WinRM 10149 info no win-diagnostics
winsrvext 100 info no win-diagnostics
Netwtw10 5005 warning no win-diagnostics
Netwtw10 5032 warning no win-diagnostics
Netwtw10 5002 warning no win-diagnostics
Netwtw10 5010 warning no win-diagnostics
Microsoft-Windows-Perflib 1008 warning no win-diagnostics
Microsoft-Windows-WMI 63 info no win-diagnostics
Microsoft-Windows-Winlogon 6004 warning no win-diagnostics
Microsoft-Windows-RestartManager 10010 info no win-diagnostics
Microsoft-Windows-Search 10024 warning no win-diagnostics
Microsoft-Windows-CodeIntegrity 3116 info no win-diagnostics
Microsoft-Windows-CodeIntegrity 3099 info no win-diagnostics
Microsoft-Windows-CodeIntegrity 3085 info no win-diagnostics
Microsoft-Windows-CodeIntegrity 3076 warning no win-diagnostics
Microsoft-Windows-CodeIntegrity 3077 warning no win-diagnostics

Unknown events remain unanalysed. The normalizer also implements device status, DISM/SFC text interpretation, disk headroom/health, firewall state, unsigned-driver signals, coverage gaps, and catalog event correlation outside the YAML catalog. These require individual regression cases before extraction is complete.

Watchlist entries

Entry Matcher owner Report content owner Caveat
winring0 win-diagnostics beffroi-reports Candidate/advisory; retain evidence and matching prerequisites.
dell-dbutil win-diagnostics beffroi-reports Candidate/advisory; retain evidence and matching prerequisites.
gigabyte-oc-guru win-diagnostics beffroi-reports Candidate/advisory; retain evidence and matching prerequisites.
intel-wifi-observed win-diagnostics beffroi-reports Separate capture-specific adapter context.
obs-overlay win-diagnostics beffroi-reports Candidate/advisory; retain evidence and matching prerequisites.
obs-audio-hooks win-diagnostics beffroi-reports Candidate/advisory; retain evidence and matching prerequisites.
smb1 win-diagnostics beffroi-reports Candidate/advisory; retain evidence and matching prerequisites.

The catalog has seven generic candidate matchers, not private incident IDs. Vendor-specific matching is not inherently organisation-specific. The intel-wifi-observed prose contains capture-specific AX200/AX210 context; retain that context in beffroi-reports rather than a generic diagnostic title. All matches need their limitations preserved; zero-weight advisories must not become confirmed failures or silently alter health scoring.

First diagnostic contract decisions (draft, not implemented)

  1. Keep the raw capture schema version distinct from the new diagnostic schema version. A schema-2 capture does not imply diagnostic contract version 2.
  2. Preserve the raw capture as an input artifact; observations reference its relative artifact path and JSON Pointer. Findings reference observation IDs.
  3. Use typed values and explicit collection state. Do not use "Unavailable", "Yes", or formatted prose as substitutes for typed values/status fields.
  4. Findings carry stable IDs, severity, confidence, title, technical description, and evidence references. Keep recommendations and executive summaries out.
  5. Retain unsupported/unknown events and partial collection. A missing section cannot establish health. Define how summary-only captures differ from records.
  6. Use collection time as the explicit analysis reference time; never use wall clock time implicitly for fading. Document rounding/timezone compatibility.

Next: implement the versioned schema and valid/invalid examples, then offline normalization for one fixture. Field names/CLI are still proposals, not a released interface. Full native collection support remains a later Windows validation gate.

Provenance and fixture review

The five files in tests/fixtures/legacy/ are copied unchanged from typst_reporter/tools/fixtures/ at the revision above. Their accompanying MIT notice is retained. All string values were reviewed: hostnames/users are explicit TEST/SYNTHETIC/CI placeholders, device identities are synthetic, paths are generic Windows/driver paths, and software names are intentional rule inputs. No real incident capture, hostname, serial number, account, IP, or network identifier was imported. This review applies to these five files only.

tests/legacy-baseline.json records observed legacy output for comparison; it is not the new diagnostic schema or proof that legacy conclusions are correct. The macro repository's scripts/check-legacy-baseline.py reproduces it using the pinned legacy source in a temporary directory. Fixtures remain independently usable by future component tests; this migration-only baseline runner is not a component runtime dependency.