216 lines
4.2 KiB
Markdown
216 lines
4.2 KiB
Markdown
# AGENT.md — Win Diagnostics
|
|
|
|
## Mission
|
|
|
|
Win Diagnostics collects and analyses Windows diagnostic information.
|
|
|
|
Its pipeline is:
|
|
|
|
Windows system
|
|
↓
|
|
collect
|
|
↓
|
|
normalize
|
|
↓
|
|
analyse
|
|
↓
|
|
diagnostic.json
|
|
|
|
The structured diagnostic result is the primary output.
|
|
|
|
This project does NOT generate corporate reports or PDFs.
|
|
|
|
---
|
|
|
|
## Migration source
|
|
|
|
The existing `WinDiagnostics` repository is the primary migration source.
|
|
|
|
Migrate progressively rather than copying the entire repository.
|
|
|
|
Before migrating a component, determine whether it is:
|
|
|
|
- collection logic;
|
|
- normalization logic;
|
|
- generic diagnostic analysis;
|
|
- historical evidence;
|
|
- investigation-specific analysis;
|
|
- report-generation logic.
|
|
|
|
Only the first three belong here.
|
|
|
|
Historical evidence and investigation-specific material will eventually
|
|
move to `beffroi-reports`.
|
|
|
|
---
|
|
|
|
## Responsibilities
|
|
|
|
Win Diagnostics owns:
|
|
|
|
- Windows evidence collection;
|
|
- event extraction;
|
|
- normalization;
|
|
- diagnostic rules;
|
|
- technical analysis;
|
|
- evidence correlation;
|
|
- confidence/severity classification;
|
|
- machine-readable diagnostic output.
|
|
|
|
---
|
|
|
|
## Non-goals
|
|
|
|
Win Diagnostics does NOT own:
|
|
|
|
- PDF generation;
|
|
- Typst;
|
|
- corporate branding;
|
|
- report layout;
|
|
- historical incident management;
|
|
- executive summaries;
|
|
- organisational recommendations.
|
|
|
|
Do not add dependencies on Reportist.
|
|
|
|
---
|
|
|
|
## Diagnostic format
|
|
|
|
Define a versioned structured diagnostic format.
|
|
|
|
Prefer JSON for machine-generated output.
|
|
|
|
Conceptually:
|
|
|
|
{
|
|
"schema_version": 1,
|
|
"metadata": {},
|
|
"system": {},
|
|
"collection": {},
|
|
"observations": [],
|
|
"findings": [],
|
|
"warnings": []
|
|
}
|
|
|
|
Findings should preferably contain:
|
|
|
|
id
|
|
severity
|
|
confidence
|
|
title
|
|
description
|
|
evidence
|
|
|
|
Adapt this structure where existing diagnostic data requires it.
|
|
|
|
---
|
|
|
|
## Evidence
|
|
|
|
Preserve raw evidence wherever practical.
|
|
|
|
A diagnostic conclusion must be traceable back to observations.
|
|
|
|
Do not replace precise machine evidence with prose summaries when the
|
|
underlying structured information can reasonably be retained.
|
|
|
|
---
|
|
|
|
## Schemas
|
|
|
|
Prefer:
|
|
|
|
schemas/diagnostic.schema.json
|
|
|
|
Treat the diagnostic schema as an interface consumed by other tools.
|
|
|
|
Changes to internal collectors should not require downstream changes when
|
|
the schema remains compatible.
|
|
|
|
---
|
|
|
|
## Privacy
|
|
|
|
Example and test fixtures must be sanitized.
|
|
|
|
Avoid committing unnecessarily identifying:
|
|
|
|
- usernames;
|
|
- hostnames;
|
|
- serial numbers;
|
|
- account identifiers;
|
|
- network identifiers.
|
|
|
|
Real investigation evidence belongs in the appropriate private reporting
|
|
repository rather than generic fixtures.
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
Prefer conceptual separation between:
|
|
|
|
collection
|
|
normalization
|
|
analysis
|
|
schemas
|
|
|
|
Do not force directory boundaries where they make implementation worse.
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
Maintain sanitized fixtures representing known diagnostic situations.
|
|
|
|
Analysis should be testable against stored fixtures without requiring
|
|
access to the original machine.
|
|
|
|
Regression tests are particularly valuable for diagnostic rules.
|
|
|
|
---
|
|
|
|
## Output
|
|
|
|
The end of a successful diagnostic run should be a documented structured
|
|
artifact such as:
|
|
|
|
diagnostic.json
|
|
|
|
Human-readable console summaries are useful but are not the canonical
|
|
integration interface.
|
|
|
|
---
|
|
|
|
## Development principles
|
|
|
|
Production collection and analysis must not require Python. Use PowerShell for
|
|
native Windows collection, shell and jq for portable offline processing, and
|
|
Make for the public interface. Python may exist only in `tests/`, must run
|
|
through a uv-managed virtual environment, and must not be called by production.
|
|
|
|
Prefer:
|
|
|
|
- PowerShell for native Windows collection where appropriate;
|
|
- structured output;
|
|
- deterministic analysis;
|
|
- explicit evidence references;
|
|
- testable rules;
|
|
- minimal dependencies.
|
|
|
|
Avoid:
|
|
|
|
- parsing presentation-oriented output when structured APIs exist;
|
|
- report-specific prose;
|
|
- renderer dependencies;
|
|
- absolute machine-specific paths.
|
|
|
|
---
|
|
|
|
## Definition of success
|
|
|
|
A fresh clone can collect/analyse supported Windows diagnostic information
|
|
and produce a valid structured diagnostic result without Reportist or any
|
|
Beffroi reporting repository installed.
|