114 lines
7.4 KiB
Markdown
114 lines
7.4 KiB
Markdown
# Diagnostic contract version 1
|
||
|
||
The implemented public interface is [diagnostic.schema.json](../schemas/diagnostic.schema.json),
|
||
a JSON Schema Draft 2020-12 document. This pass provides validation and synthetic
|
||
examples, not a migrated collector or analysis engine.
|
||
|
||
## Install and validate independently
|
||
|
||
Python 3.11 or newer is required. From a standalone component checkout:
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
.venv/bin/python -m pip install -r requirements.txt
|
||
.venv/bin/python tools/validate.py examples/diagnostic.json
|
||
.venv/bin/python tools/validate.py examples/diagnostic.json --evidence-root tests/fixtures/legacy
|
||
.venv/bin/python -m unittest discover -s tests -p 'test_*.py'
|
||
```
|
||
|
||
On Windows, use `.venv\Scripts\python.exe` in place of `.venv/bin/python`.
|
||
Alternatively, use `uv venv` and `uv pip sync --python .venv/bin/python requirements.txt`.
|
||
Dependencies, including transitive dependencies, are pinned in `requirements.txt`.
|
||
No Typst, Reportist, macro checkout, network service, or live Windows machine is
|
||
needed after dependencies are installed. Validation accepts an explicit JSON path,
|
||
writes no artifacts, and exits 0 for valid input, 1 for invalid/unreadable input or
|
||
missing dependencies, and 2 for incorrect CLI usage. Errors identify JSON paths.
|
||
|
||
## Envelope
|
||
|
||
| Field | Meaning |
|
||
| --- | --- |
|
||
| `schema_version` | Exactly integer `1`, the diagnostic artifact contract version. |
|
||
| `metadata.producer` | Tool name and version/revision; synthetic examples label their producer version accordingly. |
|
||
| `metadata.collected_at` | RFC 3339 collection timestamp with timezone. |
|
||
| `metadata.analysis_reference_time` | Explicit RFC 3339 reference for time-dependent analysis; never implicitly today's date. |
|
||
| `metadata.source` | Original capture artifact, its SHA-256, and its separate capture `schema_version` (1 or 2). |
|
||
| `system` | Sparse typed JSON system facts. Unknown facts should be omitted or null, not presentation strings. |
|
||
| `collection` | Capture mode, coverage status, and named section results. |
|
||
| `observations` | Identified raw JSON values with source pointers and section names. |
|
||
| `findings` | Identified technical conclusions with severity, confidence, description, and observation IDs. |
|
||
| `warnings` | Nonblank diagnostic/collection limitation strings. |
|
||
|
||
All envelope fields are required. Most objects reject unknown fields to catch
|
||
misspellings; `system` intentionally allows heterogeneous JSON facts. JSON object
|
||
keys must be unique and numbers finite. References are local to the schema;
|
||
validation performs no remote schema lookup.
|
||
|
||
## Collection semantics
|
||
|
||
Modes are `Compact`, `Mid`, and `Full`. Coverage status is `complete`, `partial`,
|
||
or `unknown`. Each declared section has `status` (`ok`, `skipped`, `unavailable`,
|
||
`missing`), `record_count` (nonnegative integer or null), and `truncated` (boolean).
|
||
A non-OK section requires a reason. Count is retained-record count, not a health
|
||
signal; failed native commands may still provide records worth preserving.
|
||
|
||
The validator rejects `complete` with no declared sections, unsuccessful sections,
|
||
or truncation. Complete means complete for the declared analysis scope, not proof
|
||
of Windows health or a claim that every possible collector section was evaluated.
|
||
A future analyzer must declare its actual scope honestly. Null counts and absent
|
||
facts cannot establish health; successful zero-count and missing zero-count checks
|
||
must remain distinguishable.
|
||
|
||
## Evidence and finding identity
|
||
|
||
An observation has `id`, `section`, `source_pointer`, and `value`; optional
|
||
`observed_at` is a timezone-qualified timestamp. Its value is the exact raw JSON
|
||
value at that pointer, not a rewritten prose excerpt. Derived/normalized facts
|
||
belong in `system` or a finding's technical description, supported by observations.
|
||
JSON Pointers escape `~` as `~0` and `/` as `~1`; the empty pointer names the root.
|
||
|
||
A finding has `id`, `severity` (`critical`, `warning`, `info`, `unanalysed`),
|
||
`confidence` (number 0–100), `title`, `description`, and a nonempty `evidence` list
|
||
of observation IDs. Confidence describes strength of the finding, not the chance
|
||
that the system is healthy. IDs are opaque tokens; producers must keep them stable
|
||
for repeated analysis of the same evidence/rule. The future analyzer must document
|
||
its ID derivation. The validator rejects duplicate IDs and dangling observation
|
||
or section references; JSON Schema alone cannot enforce those relationships.
|
||
|
||
Artifact paths use relative forward-slash paths without drive letters, parent/dot
|
||
segments, backslashes, or control characters. They are relative to the explicit
|
||
`--evidence-root`, not a hard-coded workspace. Without that option validation checks
|
||
structure and internal relationships only; it does not prove raw evidence exists.
|
||
With it, the validator checks the capture hash/version, resolves every observation
|
||
pointer, compares raw values, and rejects paths whose symlinks escape the root.
|
||
|
||
## Mapping legacy captures (contract, not yet an implemented converter)
|
||
|
||
| Legacy input | Version-1 artifact mapping |
|
||
| --- | --- |
|
||
| Capture `schema_version` 1 or 2 | Preserve under `metadata.source.schema_version`; artifact version remains 1. Other capture versions are unsupported. |
|
||
| `generated_at`, host/tool context | Collection/reference timestamps and typed system/provenance facts. Do not invent historical producer revisions. |
|
||
| `sections.*.status/count/data/error` | Section state/count/reason and observations referencing original records. Retain native command outputs and nested failures. |
|
||
| Unrecognized section status | `unavailable` with a reason recording the original state; preserve original evidence. |
|
||
| `limit`, `truncated`, diagnostic_collection | Coverage evidence; absence of an old field must not imply truncation or successful collection. |
|
||
| Compact `summary` | Observations can point into `/summary/...`; declare the associated section/scope. Summary zero counts do not override explicit unavailable states. |
|
||
| Schema-1 recent_*_errors vs schema-2 recent_*_events | Normalize observed event facts without duplicating the old/new representations; retain pointers to chosen source records. |
|
||
| `/Date(milliseconds)/` and ISO timestamps | Preserve raw values in observations; convert valid instants to timezone-qualified timestamps where used as normalized time. Unparseable required timestamps must produce an error, not today's date. |
|
||
| Unknown events | Preserve as observations and, when surfaced as findings, `unanalysed`; do not silently classify as healthy. |
|
||
| Human prose, executive summaries, remediation | Excluded from the engine contract; handled by the report adapter and human review. |
|
||
|
||
The legacy normalizer's health headline/score, display strings, inventory excerpts,
|
||
and report remediation are not mandatory diagnostic fields. Existing snapshots
|
||
remain migration comparisons, not new-schema examples.
|
||
|
||
## Compatibility
|
||
|
||
Consumers select by explicit artifact version and reject unsupported versions.
|
||
Breaking field or semantic changes require a new version and documented migration.
|
||
Do not relabel raw captures or silently reshape historical artifacts. Contract v1
|
||
is the initial implementation; no converter or production producer is claimed yet.
|
||
|
||
Schema and format behavior follow [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/json-schema-validation)
|
||
and the [jsonschema validator documentation](https://python-jsonschema.readthedocs.io/en/stable/validate/).
|
||
The validator enables format checking explicitly, including timezone-qualified dates.
|