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/AGENT.md

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.