erwinmagielda/kolektria

# Kolektria **Collects Windows update evidence, maps expected security Knowledge Base (KB) updates, and reports missing patch state for authorised host review.** Kolektria is a Windows patch-state collector built with Python and PowerShell. It collects local update evidence, checks expected Microsoft security updates through Microsoft Security Response Center (MSRC) advisory data, applies supersedence logic, and exports the result as JavaScript Object Notation (JSON) and Markdown. The project exists because Windows update review often sits between two views: installed KB packages on the host and Common Vulnerabilities and Exposures (CVE) advisory data from Microsoft. Kolektria does not install patches, score risk, or replace enterprise patch management. Its role is evidence collection for review, documentation, and downstream Remetria analysis. ## Skills Demonstrated • **Windows Update Review** Collects Windows version evidence, installed KBs, expected security KBs, and missing update state from an authorised host. • **Scripted Collection Workflow** Uses PowerShell for host collection, then Python for orchestration, data handling, reporting, cleanup, and executable packaging. • **Patch Evidence Handling** Preserves JSON output and Markdown reports so the result can be reviewed after the scan or passed into downstream analysis. • **Operational Safety Scope** Keeps collection focused on authorised hosts and avoids usernames, hostnames, serials, Internet Protocol (IP) addresses, domains, and user activity. ## Architecture Kolektria separates launch, collection, orchestration, reporting, cleanup, and generated evidence. kolektria.bat │ Starts Kolektria from the repository root. │ Launches the packaged executable when available. │ ├── dist/ │ └── kolektria.exe │ Packaged Python application used for normal review. │ ├── build/ │ ├── build_exe.bat │ │ Rebuilds the executable with PyInstaller. │ │ │ └── kolektria.spec │ PyInstaller build specification. │ ├── src/ │ ├── kolektria/ │ │ Runs the menu, scan workflow, MSRC mapping, │ │ supersedence logic, reporting, and cleanup. │ │ │ ├── powershell/ │ │ Collects Windows baseline evidence, installed KBs, │ │ and Microsoft advisory mappings. │ │ │ └── utils/ │ Handles console output, dependency checks, │ repository paths, and PowerShell execution. │ ├── data/ │ ├── runtime/ │ │ Stores the latest generated scan JSON. │ │ │ └── collected/ │ Preserves archived scan JSON copies. │ ├── results/ │ └── reports/ │ Stores generated Markdown reports. │ ├── samples/ │ ├── sample_scan.json │ └── sample_report.md │ Provides reviewable sample output. │ └── docs/ └── screenshots/ Stores README screenshots. The scan follows this evidence chain: Run Scan -> Baseline Collection -> Installed KB Inventory -> MSRC Mapping -> Supersedence Check -> JSON Export -> Markdown Report ## Screenshots The screenshots below show the main scan workflow, artefact cleanup, and report output. ### Run Scan  Kolektria checks required files, prepares the workspace, collects Windows baseline evidence, and records installed KB inventory.  Kolektria maps MSRC advisory data, resolves supersedence, and calculates missing update state.  Kolektria exports JSON, archives the scan result, and generates a Markdown report. ### Clear Artefacts  The cleanup workflow reviews generated artefacts before deletion.  Generated runtime files are cleared while preserved scan archives remain untouched. ### Report Output  The Markdown report shows expected, installed, superseded, and missing update state.  Missing KB evidence is shown with mapped CVE records and supersedence context. ## Demo Kolektria is intended to be reviewed from the Windows launcher. The launcher keeps the workflow in one place and starts the packaged executable when available. ### 1. Check Requirements | Requirement | Reason | |---|---| | Windows | Required for local update-state collection from the host. | | PowerShell | Runs the baseline, inventory, and MSRC adapter scripts. | | Administrator Prompt | Recommended for fuller Windows update visibility. | | Internet Access | Required for MSRC advisory lookup and module installation. | ### 2. Start Kolektria Run from the repository root: kolektria.bat ### 3. Run Scan Use the menu option: Run Scan The scan collects Windows baseline evidence, installed KBs, MSRC advisory mappings, supersedence relationships, and missing update state. ### 4. Review Output | Output | Content | Location | |---|---|---| | Runtime Scan | Latest generated scan file from the most recent collection run. | `data/runtime/` | | Scan Archive | Preserved scan copies kept for later review and comparison. | `data/collected/` | | Markdown Report | Human-readable report summarising patch state and missing KB evidence. | `results/reports/` | | Sample Output | Example scan and report files included for repository review. | `samples/` | ### 5. Clear Generated Artefacts Use the menu option: Clear Artefacts This removes generated runtime files and reports while preserving archived scan evidence. ## Limitations Kolektria reports collected patch-state evidence. It does not prove exploitability, decide remediation priority, or modify the host. • **Authorised Host Scope** The tool should only be run on systems the operator is allowed to assess. • **MSRC Data Dependency** Advisory mapping depends on MSRC data availability, internet access, MonthIds, product matching, and module behaviour. • **Windows Collection Scope** The current collector is Windows-focused and does not support Linux, macOS, or network appliances. • **No Remediation Action** Kolektria does not download, install, uninstall, approve, or roll back Windows updates. • **No Risk Ranking** The collector identifies missing KB evidence. Risk scoring belongs to the downstream Remetria project. • **Supersedence Review Needed** Supersedence helps explain coverage, but update applicability still needs review before remediation decisions. ## Licence MIT License. See `LICENSE`.