316 lines
15 KiB
Markdown
316 lines
15 KiB
Markdown
# Diagnostics reports
|
||
|
||
`diagnostics.typ` generates a synthetic Windows health assessment from the structured JSON
|
||
report produced by `windiagnostics/WindowsMaintenanceReport.ps1`.
|
||
|
||
## Quick start
|
||
|
||
Collect a Full report on Windows, copy the resulting `.json` file into
|
||
`diagnostics/`, then run from this repository:
|
||
|
||
```bash
|
||
./render-diagnostics.sh diagnostics/windows_system_report_PC.json "Your Name"
|
||
```
|
||
|
||
The theme is optional and defaults to `default`.
|
||
|
||
Choose a theme with the optional third argument:
|
||
|
||
```bash
|
||
./render-diagnostics.sh diagnostics/windows_system_report_PC.json "Your Name" eridani
|
||
```
|
||
|
||
Render every `.json` dump under `diagnostics/` recursively:
|
||
|
||
```bash
|
||
./render-diagnostics.sh --all "Your Name"
|
||
```
|
||
|
||
Select a non-default theme for the complete batch:
|
||
|
||
```bash
|
||
./render-diagnostics.sh --all "Your Name" cic
|
||
```
|
||
|
||
Nested source directories are reproduced under `build/diagnostics/`, preventing
|
||
reports with identical filenames from overwriting one another.
|
||
|
||
The command creates:
|
||
|
||
```text
|
||
build/diagnostics/windows_system_report_PC.pdf
|
||
```
|
||
|
||
The author is mandatory. The diagnostic date comes from the report's `generated_at` field and is also mandatory. Missing values stop compilation with an explicit
|
||
message.
|
||
|
||
## Pipeline
|
||
|
||
1. `diagnostics-normalize.typ` reads WinDiagnostics schema version 1 JSON,
|
||
deduplicates event records, classifies signals, and builds normalized data
|
||
entirely inside Typst.
|
||
2. `diagnostics.typ` validates the inputs and selected YAML theme.
|
||
3. `diagnostics-model.typ` renders the final PDF and uses PrimaViz for the
|
||
summary visualization.
|
||
|
||
No Python conversion or external normalization step is required for native captures. Typst reads
|
||
the `.json` dump directly. It downloads `@preview/primaviz:0.10.0` on the first
|
||
build and caches it locally.
|
||
|
||
The normalizer also correlates CatRoot2 checksum errors with CryptSvc crashes
|
||
in ESENT.dll and Windows Update failures within two minutes of a checksum event.
|
||
When all three signals are present, the generated PDF includes a priority
|
||
finding and a shared investigation plan. Individual events remain visible;
|
||
the correlation adds no extra health-score penalty. This identifies a related
|
||
failure sequence, not a proven hardware root cause. Disabled display adapters
|
||
receive Code 22 guidance, and non-elevated captures receive a coverage warning.
|
||
|
||
Run the parser and correlation regression checks with:
|
||
|
||
```bash
|
||
typst compile --root . tools/check-diagnostics.typ /tmp/check-diagnostics.pdf
|
||
```
|
||
|
||
## Report structure
|
||
|
||
The document is divided into three purposeful parts:
|
||
|
||
1. **Executive overview** — the short first-page health assessment, capacity
|
||
metrics, heuristic health graph, priority findings, and signal chart.
|
||
2. **Findings requiring attention** — a resolution plan for every actionable
|
||
exception, followed by its correlated, deduplicated event evidence.
|
||
3. **Technical evidence** — system context, storage capacity, inventory counts,
|
||
selected source output, and collector-coverage audit.
|
||
|
||
The executive overview is deliberately short:
|
||
|
||
- overall assessment;
|
||
- critical and warning counts;
|
||
- a health score and aggregate analysis confidence;
|
||
- maximum installed memory and aggregate analysis confidence;
|
||
- the four highest-priority findings;
|
||
- a compact free-space chart for every captured volume.
|
||
|
||
The remaining two parts contain:
|
||
|
||
- system and storage profile;
|
||
- inventory counts instead of full healthy inventories;
|
||
- all actionable findings;
|
||
- deduplicated event-log evidence;
|
||
- selected source evidence for hardware, storage, security, networking, power,
|
||
DISM, and SFC;
|
||
- a collector-coverage table describing how every source section was used.
|
||
|
||
## Noise and privacy policy
|
||
|
||
The report favors exceptions over exhaustive reproduction:
|
||
|
||
- repeated identical event records are collapsed and counted;
|
||
- related event variants share one top-level finding;
|
||
- installed applications, Store packages, services, drivers, tasks, startup
|
||
entries, and listeners are counted rather than listed in full;
|
||
- SFC progress lines are removed while its final result is retained;
|
||
- raw IP configuration, user paths, and other noise-heavy or sensitive values
|
||
are reviewed but not reproduced;
|
||
- healthy status remains visible in relevant summaries but does not create an
|
||
individual finding.
|
||
|
||
Routine evidence is conditional:
|
||
|
||
- vanilla enabled firewall profiles are omitted;
|
||
- Defender details are omitted when all collected protection flags are true;
|
||
- component-store output is omitted when it contains no repairable, corruption,
|
||
or error signal;
|
||
- battery output is omitted when WMI reports `OK` and at least 20% charge;
|
||
- DNS servers, power-plan details, and stopped automatic-service snapshots are
|
||
omitted from evidence but remain accounted for in collector coverage;
|
||
- SFC integrity failures are retained and highlighted as critical.
|
||
|
||
## Upgradeable event heuristics
|
||
|
||
Event interpretation lives in `diagnostics-rules.yaml`, separate from the Typst
|
||
parser and layout. Each rule matches an exact provider and event ID and defines
|
||
its severity, rationale, and a heuristic confidence estimate:
|
||
|
||
```yaml
|
||
event_rules:
|
||
- provider: "Service Control Manager"
|
||
id: "7000"
|
||
severity: "warning"
|
||
confidence: 90
|
||
rationale: "A configured service or driver failed to start."
|
||
```
|
||
|
||
If no rule matches, the event is retained as `unanalysed` and visibly labelled
|
||
`FAIL TO ANALYSE`. Add or revise a rule, then rerun the same render command; no
|
||
Typst code change is required.
|
||
|
||
Rules can also provide `resolution_steps`, `reference_url`, and
|
||
`reference_label`. The **Resolution plan** prints numbered steps and an optional
|
||
clickable authoritative reference beside the corresponding problem. The older
|
||
`remediation` string remains a supported fallback. Built-in DISM, SFC, firewall,
|
||
and device findings provide the same guidance even though they do not originate
|
||
from an event rule.
|
||
|
||
Confidence percentages are review-priority estimates attached to each
|
||
classification, not measured failure probabilities. Unknown event rules receive
|
||
20% confidence and remain labelled `FAIL TO ANALYSE`. The overview confidence is
|
||
the arithmetic mean of displayed finding confidence values.
|
||
|
||
The health graph is deliberately simple and reproducible: it begins at 100,
|
||
subtracts 8 points per critical finding, 2 per warning, and 1 per unanalysed
|
||
signal, then clamps the result to 0–100. Change those weights in
|
||
`diagnostics-normalize.typ` if operational experience calls for different
|
||
priorities.
|
||
|
||
## Closing findings safely
|
||
|
||
“Clear” means proving that the underlying condition is resolved and producing a
|
||
new diagnostic capture. It does not mean deleting evidence from Event Viewer.
|
||
|
||
Use this workflow for each item in the PDF's **Resolution plan**:
|
||
|
||
1. Save the original PDF and JSON capture if the issue may need escalation or an
|
||
audit trail.
|
||
2. Follow the finding's numbered **Resolution path**. Use its linked vendor or
|
||
Microsoft guidance when one is provided.
|
||
3. Perform the stated verification before considering the issue closed. A
|
||
command completing without an error is not sufficient if the affected
|
||
service, application, update, backup, or device still fails.
|
||
4. Reboot when the repair changes system files, drivers, services, firmware, or
|
||
pending installer state.
|
||
5. Reproduce the original workload where practical, then run WinDiagnostics
|
||
again and compile the new dump.
|
||
6. Compare the new report with the saved report. Close a finding only when its
|
||
current-state check is healthy or the triggering behavior no longer recurs.
|
||
|
||
Typical closure checks:
|
||
|
||
| Finding | What proves it is cleared |
|
||
| --- | --- |
|
||
| DISM / component store | `/RestoreHealth` succeeds and a new health check reports no component-store corruption. |
|
||
| SFC integrity | `sfc /scannow` completes and reports no remaining integrity violations. |
|
||
| Firewall | Domain, Private, and Public profiles are enabled, unless a documented organization policy intentionally differs. |
|
||
| Service failure | The owning software or driver is repaired, the service starts or stops normally, and the event does not recur after a relevant reboot or test. |
|
||
| Application crash or hang | The repaired or updated application completes the previously failing workflow without a matching new event. |
|
||
| Windows Update / MSI | The named update or product installation completes successfully and is shown as installed. |
|
||
| VSS / Volsnap | `vssadmin list writers` shows stable writers and a new backup or shadow copy succeeds. |
|
||
| Device problem | Device Manager and the next diagnostic capture report the device as healthy. |
|
||
| Unexpected shutdown | Record the known cause if intentional; otherwise investigate correlated power, bug-check, thermal, driver, and hardware evidence before closure. |
|
||
| Unknown event | Review the raw provider, ID, and message; add a defensible rule and rerun the report. |
|
||
|
||
Historical events can remain visible after a successful repair because they
|
||
describe what happened during the collector's look-back window. Leave them
|
||
intact. A resolved event finding will age naturally and eventually leave future
|
||
captures; eligible findings may also receive the limited score fading described
|
||
below. If a clean post-repair capture is needed for handoff, wait until the
|
||
collector window has advanced rather than clearing the Windows logs.
|
||
|
||
### Age fading
|
||
|
||
Selected event rules may set `fading: true`. Their health-score penalty remains
|
||
at full value for seven days, then decreases linearly until it reaches 50% at
|
||
90 days. It never falls below 50%; the finding, severity, evidence, and
|
||
resolution path remain in the report. A faded finding shows its age-adjusted
|
||
weight beside the finding text.
|
||
|
||
Age is measured from the event timestamp to the diagnostic report date in the
|
||
report's `generated_at` field. It never uses the current date or the date on which
|
||
the PDF happens to be compiled. If either date cannot be parsed, full weight is
|
||
retained.
|
||
|
||
Fading is enabled only for events expected to re-log on recurrence or whose old
|
||
instance becomes less useful with time: service start/stop failures, application
|
||
crashes and hangs, Windows Update failures, and installer failures. It is
|
||
deliberately disabled for storage-controller errors, TPM attestation, firewall,
|
||
SFC/DISM, VSS/Volsnap, NDIS power transitions, unexpected shutdowns, devices,
|
||
and unknown events. Those signals may be persistent, intermittent, or unsafe to
|
||
treat as resolved merely because no newer event was captured.
|
||
|
||
The defaults can be overridden per safe rule with `fade_after_days` and
|
||
`fade_to_half_days` in `diagnostics-rules.yaml`.
|
||
|
||
A DISM result of `repairable` is classified as a warning, not a critical
|
||
finding. Microsoft distinguishes it from a non-repairable image and provides
|
||
`/RestoreHealth` as its normal repair path. System-file integrity violations,
|
||
TPM pre-attestation failures, and incomplete firewall protection retain their
|
||
higher operational priority.
|
||
|
||
Do not clear Windows event logs merely to make a diagnostic report look clean.
|
||
An event is historical evidence, not a live alarm. Resolve its cause, perform
|
||
the stated verification, and rerun WinDiagnostics; old entries naturally leave
|
||
the report once they fall outside its configured event-history window. Preserve
|
||
logs needed for incident investigation or audit.
|
||
|
||
The current rules use conservative interpretations of Windows collector data.
|
||
For example, Microsoft documents Event 7000 as a service-start failure,
|
||
`Get-MpComputerStatus` boolean fields as protection-state indicators, and
|
||
`Win32_Battery.EstimatedChargeRemaining` as remaining charge percentage. Links
|
||
to those references are kept here for future rule maintenance:
|
||
|
||
- [Service Control Manager Event 7000](https://learn.microsoft.com/en-us/troubleshoot/windows-client/setup-upgrade-and-drivers/system-log-event-id-7000-7026)
|
||
- [Microsoft Defender status fields](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/defender/msft-mpcomputerstatus)
|
||
- [Win32_Battery fields](https://learn.microsoft.com/en-us/windows/win32/cimwin32prov/win32-battery)
|
||
- [DISM and SFC repair sequence](https://support.microsoft.com/en-us/windows/experience/backup-recovery/using-system-file-checker-in-windows)
|
||
- [Enable Windows Firewall profiles](https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/configure-with-command-line)
|
||
|
||
The final coverage table prevents silent omission: every section emitted by the
|
||
collector is listed with its treatment. False positives remain possible because
|
||
classification is heuristic; the PDF says so explicitly.
|
||
|
||
## Direct Typst usage
|
||
|
||
The JSON capture is passed directly to Typst:
|
||
|
||
```bash
|
||
typst compile \
|
||
--input diagnostics=diagnostics/windows_system_report_PC.json \
|
||
--input author="Your Name" \
|
||
--input theme=cic \
|
||
diagnostics.typ \
|
||
build/diagnostics/report.pdf
|
||
```
|
||
|
||
Available themes are `default`, `cic`, and `eridani` and are defined in
|
||
`themes.yaml`.
|
||
|
||
## Input expectations
|
||
|
||
The parser is designed for Compact, Mid, and Full WinDiagnostics JSON captures,
|
||
but Full provides the evidence needed for meaningful fault synthesis. Unknown future sections remain listed in coverage as retained in the source without specific analysis.
|
||
|
||
## JSON migration and converted captures
|
||
|
||
The schema follows [WindowsMaintenanceReport.ps1](https://proxy.dandaedre.com/gitea/Beffroi/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1).
|
||
The renderer validates `report_type`, `schema_version`, and `generated_at`.
|
||
Full/Mid captures use section envelopes (`status`, `count`, `data`, `error`);
|
||
Compact captures use `summary`. Collector warnings and skipped/error sections
|
||
remain visible. Coverage counts are records, not transcript lines.
|
||
|
||
Native PowerShell dates may use `/Date(milliseconds)/`; ISO timestamps and their
|
||
offsets are also supported for event correlation. Firewall `Enabled` accepts
|
||
JSON `true` and the collector's numeric enum value `1`. DISM/SFC output remains
|
||
text inside JSON; progress lines are removed before displaying evidence.
|
||
|
||
The existing `hardware-*` captures were converted with a lossy converter. It
|
||
changed CIM keys to snake_case, split event-message fields, and mistook table
|
||
separators for section headings. Several inventories contain only headers,
|
||
storage volumes are missing, and an empty section name contains displaced data.
|
||
These source files are preserved. The renderer accepts recoverable field aliases,
|
||
retains extra event-message fields, and reads command conclusions from
|
||
`legacy_raw`. Header-only inventory counts display **Unavailable**; unparsed
|
||
device/firewall tables do not produce false device or disabled-firewall findings.
|
||
Every converted report receives an explicit incomplete-evidence finding.
|
||
Legacy local event timestamps are left unchanged without age fading or temporal
|
||
correlation because their date order/timezone is not established reliably.
|
||
Recollect native Full JSON to replace the missing evidence; the renderer cannot
|
||
reconstruct lost table rows reliably from these JSON files.
|
||
|
||
Native event timestamps display as `YYYY-MM-DD HH:MM:SS UTC`, with raw timestamps
|
||
preserved internally for correlation and fading. WER-SystemErrorReporting 1001
|
||
is a critical kernel-crash finding; code 0x133 is identified as
|
||
[DPC_WATCHDOG_VIOLATION](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/bug-check-0x133-dpc-watchdog-violation).
|
||
The saved dump must be analyzed to identify the responsible component.
|
||
`volmgr` 162 records successful dump generation and is informational, so it
|
||
adds no health-score penalty and is omitted from actionable event evidence.
|