234 lines
12 KiB
Markdown
234 lines
12 KiB
Markdown
# 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
|
||
|
||
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.
|
||
|
||
The version-1 schema and standalone validator are now implemented; see
|
||
[diagnostic contract](diagnostic-contract.md). Offline normalization and native
|
||
collection remain unimplemented; full Windows support is a later 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.
|