From a55baafa06796b15478d9c62eefb94e0909a2016 Mon Sep 17 00:00:00 2001 From: spydisec <9101327+spydisec@users.noreply.github.com> Date: Fri, 4 Sep 2026 17:11:20 +1000 Subject: [PATCH 1/4] Docs cut: one-screen README, 13 pages to 10, Sentinel KQL to extras Step 1 of the v1.0 restructure (ADR-001). No script changes. - README reduced to one screen and reused as the site home page through a pymdownx.snippets include; landing-page hero and cards removed - WEC Collector becomes Collect and absorbs the WEF section of Deployment; Architecture merges into Coverage; FAQ merges into Safety & FAQ - Sentinel KQL moves to docs/extras/ outside the nav (kit is SIEM-agnostic) - ROADMAP.md removed; planned work goes to issues; release zip, CONTRIBUTING and the feature-request template updated - FAQ Sysmon answer updated for built-in Sysmon on Windows 11 / Server 2025 - Accuracy fixes: coverage joins the native ATT&CK snapshot (not OSSEM); .coderabbit.yaml pointed at a README section that no longer exists; behaviour-category rows now list the Security log where their events land Co-Authored-By: Claude Fable 5.1 --- .coderabbit.yaml | 2 +- .github/ISSUE_TEMPLATE/feature_request.yml | 4 +- .github/workflows/release.yml | 2 +- CHANGELOG.md | 17 ++ CONTRIBUTING.md | 2 +- README.md | 204 ++++++++------------- ROADMAP.md | 97 ---------- docs/addons.md | 6 +- docs/architecture.md | 130 ------------- docs/baselines.md | 4 +- docs/commands.md | 13 +- docs/deployment.md | 72 +------- docs/{kql.md => extras/sentinel-kql.md} | 16 +- docs/faq.md | 111 ----------- docs/index.md | 102 +---------- docs/mapping.md | 146 ++++++++++++++- docs/safety.md | 121 +++++++++++- docs/stylesheets/extra.css | 59 +----- docs/wec.md | 104 +++++++---- mkdocs.yml | 18 +- 20 files changed, 470 insertions(+), 760 deletions(-) delete mode 100644 ROADMAP.md delete mode 100644 docs/architecture.md rename docs/{kql.md => extras/sentinel-kql.md} (96%) delete mode 100644 docs/faq.md diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 18eccce..196b11b 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -38,7 +38,7 @@ reviews: path_instructions: - path: "**/*.ps1" instructions: | - House rules for this repo (see README "Contributing and SDLC"): + House rules for this repo (see CONTRIBUTING.md): - Must run on stock Windows PowerShell 5.1: no ternary operator, no null-coalescing (??), no null-conditional (?.), no pwsh-only cmdlets or parameters. Flag anything 7-only. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 7d3a3a2..a302e23 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -14,8 +14,8 @@ body: attributes: label: Proposed behaviour description: >- - What should happen instead. Check ROADMAP.md first - it may already - be planned. + What should happen instead. Check the open issues first - it may + already be planned. validations: required: true - type: checkboxes diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c27035d..99a9f47 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -28,7 +28,7 @@ jobs: $tag = '${{ github.ref_name }}' $stage = "WinLogKit-$tag" New-Item -ItemType Directory -Path $stage | Out-Null - Copy-Item *.ps1, PSScriptAnalyzerSettings.psd1, README.md, ROADMAP.md, CHANGELOG.md, LICENSE $stage + Copy-Item *.ps1, PSScriptAnalyzerSettings.psd1, README.md, CHANGELOG.md, LICENSE $stage # Data-dependent scripts (coverage mapping, presets) must work from # the zip, not only from a git clone. Copy-Item data, presets, tools, tests, addons $stage -Recurse diff --git a/CHANGELOG.md b/CHANGELOG.md index 4db994c..f873d47 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,23 @@ All notable changes to WinLogKit. Versions follow [SemVer](https://semver.org/); releases are tagged `vX.Y.Z` and published with a zip + SHA256 checksum. +## Unreleased + +### Changed +- **Docs cut.** README reduced to one screen and reused as the site home + page (MkDocs snippet include, one copy of the text). The site goes from + 13 pages to 10: the WEC Collector page absorbs the WEF section of + Deployment and becomes **Collect**, Architecture merges into + **Coverage**, FAQ merges into **Safety & FAQ**, and the Sentinel KQL + page moves to `docs/extras/` outside the navigation (the kit is + SIEM-agnostic; that page is one worked example of the last hop). + Landing-page hero and card styling removed. +- `ROADMAP.md` removed; planned work is tracked in GitHub issues. The + release zip no longer ships it. +- FAQ: the Sysmon answer now covers built-in Sysmon on Windows 11 and + Windows Server 2025 (an optional Windows feature since February 2026, + per [Microsoft's Sysmon overview](https://learn.microsoft.com/windows/security/operating-system-security/sysmon/overview)). + ## v0.11.0 - 2026-09-04 ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 57e19a0..fdb535a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ is what tunes the presets. Open an issue with the *Field report* template. Use the *Bug report* template and include the transcript from `.\Logs\` or the Results CSVs where relevant. - **Docs** - unclear wording, missing steps, broken links. -- **Code** - fixes and roadmap items ([ROADMAP.md](ROADMAP.md)). For +- **Code** - fixes and planned work (open issues labelled `enhancement`). For anything non-trivial, open an issue first so the approach is agreed before you spend time on it. diff --git a/README.md b/README.md index 7eea227..061d14f 100644 --- a/README.md +++ b/README.md @@ -3,152 +3,104 @@ [![CI](https://github.com/spydisec/WinLogKit/actions/workflows/ci.yml/badge.svg)](https://github.com/spydisec/WinLogKit/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/spydisec/WinLogKit?include_prereleases)](https://github.com/spydisec/WinLogKit/releases) [![Docs](https://img.shields.io/badge/docs-spydisec.github.io%2FWinLogKit-1b3a4b)](https://spydisec.github.io/WinLogKit/) -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) - -**An easy, auditable way to implement the -[Yamato Security](https://github.com/Yamato-Security) Windows event logging -baselines with native PowerShell.** Enable the right event channels, advanced -audit policy subcategories and registry settings; verify them repeatably; and -get an independent second opinion from -[WELA](https://github.com/Yamato-Security/WELA) - all with plain -PowerShell: PowerShell 7 or the built-in Windows PowerShell 5.1, no -modules, no agents, no Sysmon. - -Targets **Windows Server 2019 / 2022 / 2025 and Windows 10 / 11**, standalone -or domain joined. Version-specific items (Server 2025 / Win11 24H2 SMB -auditing) and role-specific items (domain controller subcategories) are -detected at runtime and reported NOT APPLICABLE where they don't apply. -Fleet delivery via **Intune remediations**, **WEF/WEC subscriptions** and -**GPO artefacts** is built in, and the kit reports which **MITRE ATT&CK** -techniques a selection makes observable. - -## 📖 Documentation - -**** - getting started, baseline -guide, per-command reference, deployment (Intune / WEF / GPO), ATT&CK -coverage, the full [per-setting reference -table](https://spydisec.github.io/WinLogKit/reference/) (every event ID, -size, volume weight and baseline membership), safety notes and FAQ. - -## Credits - -The settings themselves come from Yamato Security's excellent work: - -- [EnableWindowsLogSettings](https://github.com/Yamato-Security/EnableWindowsLogSettings) - - the configuration guide and batch script this kit operationalises -- [WELA](https://github.com/Yamato-Security/WELA) - used here as an - independent verification tool -- [EventLog-Baseline-Guide](https://github.com/Yamato-Security/EventLog-Baseline-Guide) - - the source of the ASD / Microsoft Client / Microsoft Server reference - baselines shipped as presets - -This project is not affiliated with or endorsed by Yamato Security. A handful -of deliberate deviations from their scripts are -[documented with reasons](https://spydisec.github.io/WinLogKit/baselines/#deviations-from-the-yamato-sources). - -## ⚠️ Warning - -Same warning as the upstream guide: understand and **test every setting on a -non-production machine that mirrors your environment for at least a week** -before rolling out. Logging volume is real money and real disk. Use at your -own risk. - -## Files - -| File | What it does | -|---|---| -| `LoggingBaseline.Settings.ps1` | Single source of truth: every channel, subcategory and registry value with tier, scope, purpose and risk notes. Everything else derives from it. | -| `New-LoggingBaseline.ps1` | Interactive baseline builder: walk every setting, see the recommendation and risk, write selections to CSV. No admin, changes nothing. | -| `Enable-LoggingBaseline.ps1` | Applies a baseline. Idempotent, `-WhatIf` diff, `-Rollback` to first-run state, pre-change snapshots, never reboots or shrinks logs. | -| `Test-LoggingBaseline.ps1` | Verification only: PASS / FAIL / NOT APPLICABLE per category, CSVs to `.\Results\`, non-zero exit on failure for pipelines. | -| `Invoke-WELACheck.ps1` | Runs WELA as an independent second opinion, parses deviations, archives evidence per run. | -| `New-IntuneRemediationPack.ps1` | Compiles a selection into a self-contained Intune detect + remediate script pair. | -| `New-WefSubscription.ps1` | Generates a source-initiated WEF subscription XML plus collector/source setup steps. `-Filter Baseline` narrows Security to the event IDs the baseline's subcategories produce; `-Validate` parses every query locally. | -| `Test-WefFilter.ps1` | On the collector: proves the subscription filter is in effect from ForwardedEvents evidence, and that the deployed query is the generated one. | -| `New-GpoPack.ps1` | Generates GPO delivery artefacts: `audit.csv` (GUID-driven) and LGPO-format `registry.txt`. | -| `Export-AttackCoverage.ps1` | Reports which ATT&CK techniques a selection makes observable, and why the rest are not. | -| `presets/` | Ready-made selection CSVs: ASD / Microsoft reference baselines, per-role starting points, and the blended **spydi** baselines (role x volume). | -| `addons/AutorunsToWinEventLog/` | **Optional add-on** (needs Sysinternals autorunsc): daily task writing every autostart entry to an `Autoruns` event log, a daily inventory over the native Persistence gap. Inspired by Palantir's tool (MIT, credited). | -| `tests/Invoke-KitChecks.ps1` | Self-checks CI runs on PowerShell 5.1 and 7; run locally before a PR. | +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/spydisec/WinLogKit/blob/main/LICENSE) + +Turn on the Windows event logging that security monitoring needs, prove it +is being recorded, and roll it back if you change your mind. Plain +PowerShell (7 or the built-in 5.1), no modules, no agents. + +The baselines are built from the [Yamato Security](https://github.com/Yamato-Security) +logging guides, the Australian Signals Directorate and Microsoft's own +recommendations, with every setting's purpose, volume risk and source +recorded in one table. Targets Windows Server 2019 / 2022 / 2025 and +Windows 10 / 11, standalone or domain joined; version- and role-specific +items are detected at runtime and reported NOT APPLICABLE where they do not +apply. + +## What it does + +- **Enable** event channels, advanced audit policy subcategories and + registry settings from one settings table. Idempotent, `-WhatIf` diff, + `-Rollback` to first-run state. +- **Verify** the live state per behaviour category (PASS / FAIL / NOT + APPLICABLE) with evidence CSVs, plus Yamato's WELA as an independent + second opinion. +- **Collect** centrally: a Windows Event Forwarding subscription generated + from the same selection, filtered to the event IDs the baseline actually + produces. The kit ends at the collector's ForwardedEvents log; any SIEM + picks up from there. +- **Deploy** at fleet scale as an Intune remediation pack or GPO artefacts, + compiled from the same table so deployed config cannot drift from the + tested baseline. +- **Measure** which MITRE ATT&CK techniques a selection makes observable, + offline, from data shipped in the kit. ## Quick start -All commands from an elevated PowerShell prompt in the kit folder - -PowerShell 7 or the built-in Windows PowerShell 5.1 both work -(`New-LoggingBaseline.ps1` alone needs no elevation). If scripts are blocked, -`Set-ExecutionPolicy -Scope Process RemoteSigned` unblocks the current window -without persisting anything -([details](https://spydisec.github.io/WinLogKit/getting-started/#if-scripts-are-blocked-running-scripts-is-disabled-on-this-system)). - -**Path A - tier switches** (fastest route to the recommended baseline): +From an elevated PowerShell prompt in the kit folder. Test on a +non-production machine that mirrors your environment for at least a week +before rolling out: logging volume is real disk and real money. ```powershell -.\Enable-LoggingBaseline.ps1 -WhatIf # 1. full diff, nothing changed -.\Enable-LoggingBaseline.ps1 # 2. apply Core (first run captures rollback state) -.\Enable-LoggingBaseline.ps1 -IncludeHighVolume # 3. after reviewing the volume notes -.\Test-LoggingBaseline.ps1 -IncludeHighVolume # 4. verify what you applied -.\Invoke-WELACheck.ps1 -Download # 5. independent second opinion -.\Enable-LoggingBaseline.ps1 -Rollback # if needed: put everything back +.\Enable-LoggingBaseline.ps1 -WhatIf # 1. full diff, nothing changes +.\Enable-LoggingBaseline.ps1 # 2. apply Core (first run captures rollback state) +.\Test-LoggingBaseline.ps1 # 3. verify +.\Enable-LoggingBaseline.ps1 -IncludeHighVolume # 4. add the high-volume tier after reading its notes +.\Enable-LoggingBaseline.ps1 -Rollback # undo everything captured at step 2 ``` -**Path B - build your own baseline** (decide setting-by-setting, or start -from a preset): +Want your own selection? `.\New-LoggingBaseline.ps1` walks every setting +and writes a CSV that Enable, Test, the coverage report and every fleet +generator accept through `-BaselineFile`; `presets\` ships ready-made +ones (ASD, Microsoft, and the kit's own `spydi_*` Minimal / Heavy pairs +per role). -```powershell -.\New-LoggingBaseline.ps1 # interactive walk-through -> MyBaseline.csv -.\Enable-LoggingBaseline.ps1 -BaselineFile .\MyBaseline.csv -WhatIf -.\Enable-LoggingBaseline.ps1 -BaselineFile .\MyBaseline.csv -.\Test-LoggingBaseline.ps1 -BaselineFile .\MyBaseline.csv -``` +If scripts are blocked, `Set-ExecutionPolicy -Scope Process RemoteSigned` +unblocks the current window without persisting anything; downloaded zips +also need `Unblock-File`, and a Group Policy-enforced policy needs the +per-invocation form. Details in +[Getting Started](https://spydisec.github.io/WinLogKit/getting-started/#if-scripts-are-blocked-running-scripts-is-disabled-on-this-system). -Press `t` during the walk-through (or use `-Show`) for a tree view of the -selection with per-category coverage. The CSV is plain text: commit one per -server role and you get reviewable, versioned logging baselines for free. -Presets work anywhere a `-BaselineFile` is accepted: +## Documentation -```powershell -.\Enable-LoggingBaseline.ps1 -BaselineFile .\presets\spydi_Workstation_Minimal.csv -WhatIf -``` +Full documentation: -## Tiers - -| Tier | Applied when | Contents | -|---|---|---| -| Core | always | Everything with low or justified volume | -| HighVolume | `-IncludeHighVolume` | Process Creation + command line, PowerShell script block + module logging, Filtering Platform Connection, Sensitive Privilege Use | -| Optional | `-IncludeOptional` | PowerShell transcription, Crypto-DPAPI debug channel, IPsec Driver auditing | +| Page | Covers | +|---|---| +| [Getting Started](https://spydisec.github.io/WinLogKit/getting-started/) | Install, first run, execution policy, where output lands | +| [Baselines](https://spydisec.github.io/WinLogKit/baselines/) | Tiers, presets, deviations from the sources | +| [Commands](https://spydisec.github.io/WinLogKit/commands/) | Every script and its switches | +| [Collect](https://spydisec.github.io/WinLogKit/wec/) | WEF / WEC: subscription, collector and source setup, XPath filtering | +| [Deploy](https://spydisec.github.io/WinLogKit/deployment/) | Intune and GPO rollout | +| [Coverage](https://spydisec.github.io/WinLogKit/mapping/) | How the pieces fit, behaviour categories, ATT&CK technique coverage | +| [Reference](https://spydisec.github.io/WinLogKit/reference/) | Every setting: event IDs, sizes, volume, preset membership | +| [Safety & FAQ](https://spydisec.github.io/WinLogKit/safety/) | Never-do list, volume impact, known limits, common questions | +| [Add-ons](https://spydisec.github.io/WinLogKit/addons/) | AutorunsToWinEventLog (optional, needs Sysinternals autorunsc) | ## Safety The kit never touches the settings that can hang or lock out a host (`CrashOnAuditFail`, "do not overwrite" retention, global object access auditing, blanket SACLs) and never reboots, restarts services or shrinks -logs. Merely *heavy* settings carry a risk note the builder shows before you -select them. Full rationale, the volume-impact table and known limits: -[Safety](https://spydisec.github.io/WinLogKit/safety/). - -## Where everything else lives - -| Topic | Docs page | -|---|---| -| Install, first run, execution policy | [Getting Started](https://spydisec.github.io/WinLogKit/getting-started/) | -| Tiers, presets, spydi blended baselines | [Baselines](https://spydisec.github.io/WinLogKit/baselines/) | -| Every switch of every script, WELA reference | [Commands](https://spydisec.github.io/WinLogKit/commands/) | -| Intune, WEF/WEC, GPO rollout | [Deployment](https://spydisec.github.io/WinLogKit/deployment/) | -| ATT&CK technique coverage and method | [Coverage](https://spydisec.github.io/WinLogKit/mapping/) | -| Per-setting table: event IDs, sizes, volume, baseline membership | [Reference](https://spydisec.github.io/WinLogKit/reference/) | -| How the pieces fit, behaviour category mapping | [Architecture](https://spydisec.github.io/WinLogKit/architecture/) | -| Never-do list, volume impact, known limits | [Safety](https://spydisec.github.io/WinLogKit/safety/) | -| Workstations, Home edition, common questions | [FAQ](https://spydisec.github.io/WinLogKit/faq/) | +logs. Heavy settings carry a risk note the builder shows before you select +them. Use at your own risk. ## Contributing -Issues and PRs welcome - especially field reports on real event volumes per -setting. See [CONTRIBUTING.md](CONTRIBUTING.md) for how changes land -(branch + PR, CI gates, release process), [SECURITY.md](SECURITY.md) for -reporting vulnerabilities, and [ROADMAP.md](ROADMAP.md) for what's planned. -Changes are tracked in [CHANGELOG.md](CHANGELOG.md). +Issues and PRs welcome, field reports on real event volumes per setting +especially. See +[CONTRIBUTING.md](https://github.com/spydisec/WinLogKit/blob/main/CONTRIBUTING.md) +for how changes land, +[SECURITY.md](https://github.com/spydisec/WinLogKit/blob/main/SECURITY.md) +for reporting vulnerabilities, and +[CHANGELOG.md](https://github.com/spydisec/WinLogKit/blob/main/CHANGELOG.md) +for what changed. Planned work is tracked in +[issues](https://github.com/spydisec/WinLogKit/issues). ## License -[MIT](LICENSE). The upstream Yamato Security projects are also MIT licensed. +[MIT](https://github.com/spydisec/WinLogKit/blob/main/LICENSE). Not +affiliated with or endorsed by Yamato Security, the ASD or Microsoft; the +Yamato projects the settings derive from are also MIT licensed, and the +kit's deliberate deviations from them are +[documented with reasons](https://spydisec.github.io/WinLogKit/baselines/#deviations-from-the-yamato-sources). diff --git a/ROADMAP.md b/ROADMAP.md deleted file mode 100644 index dec4187..0000000 --- a/ROADMAP.md +++ /dev/null @@ -1,97 +0,0 @@ -# Roadmap - -## v0.2.0 (current) - -- Windows Server 2019 / 2022 / 2025, standalone and domain joined (Server 2025 - SMB signing/encryption auditing included, OS-gated) -- Enable / test / rollback via local PowerShell 5.1, tiered (Core, HighVolume, Optional) -- Interactive baseline builder (`New-LoggingBaseline.ps1`): per-setting selection - with the kit recommendation and risk notes shown, Excel-editable CSV output - consumed by enable and test via `-BaselineFile` -- Independent verification via WELA with archived evidence -- SDLC: branch + PR flow, CI (lint on PSScriptAnalyzer, self-checks on PS 5.1 - and PS 7, DevSkim security scan), Dependabot, tagged zip releases with - SHA256 checksums - -## v0.3 - Workstation profile and Intune delivery (in progress) - -- [x] Kit verified applicable to client Windows: host profile detection - (workstation / server / DC), runtime NOT APPLICABLE gating, README guidance -- [x] **Intune delivery**: `New-IntuneRemediationPack.ps1` compiles the - settings table (or a baseline CSV) into a self-contained detection + - remediation pair (SYSTEM, 64-bit, exit-code contract) -- [x] IPsec Driver subcategory added (Optional) from - [Microsoft's baseline recommendation](https://learn.microsoft.com/windows-server/identity/ad-ds/plan/security-best-practices/audit-policy-recommendations) - via Yamato's [EventLog-Baseline-Guide](https://github.com/Yamato-Security/EventLog-Baseline-Guide) - comparison -- [ ] Field-test the pack in a real Intune tenant (assignment, schedule, - reporting) and fold back findings -- [ ] Settings-catalog / CSP mappings where they exist (PowerShell logging and - command line capture are ADMX-backed, and audit subcategories are exposed via - the [Policy CSP - Audit](https://learn.microsoft.com/windows/client-management/mdm/policy-csp-audit); - the kit does not map these yet - the shipped route today is the remediation - pack, which also covers channel sizing that has no CSP) -- [x] Per-role recommended CSVs shipped in the repo (workstation / member - server / DC) as documented starting points derived from the settings - table's Risk metadata; to be refined when pilot volume data lands - -## v0.4 - Fleet collection and reference baselines (in progress) - -- [x] **WEF/WEC**: `New-WefSubscription.ps1` generates a source-initiated - subscription XML from the settings table or any baseline CSV, with - collector/source setup guidance (generate -> transport -> ingest boundary - documented; SIEM ingestion stays out of scope) -- [x] **Reference presets**: `presets/` ships ASD, Microsoft_Client and - Microsoft_Server as selection CSVs, faithful to Yamato's - EventLog-Baseline-Guide scripts, drift-checked in CI against - `tools/New-PresetBaselines.ps1` -- [x] Collector/source-side WEF checks in Test-LoggingBaseline (`-WefRole`) -- [x] GPO pack: `New-GpoPack.ps1` generates the audit policy `audit.csv` - and LGPO-format `registry.txt` from any selection -- [x] ATT&CK coverage reporting via a vendored OSSEM-DM snapshot - (`Export-AttackCoverage.ps1`) -- [x] Documentation site (MkDocs Material on GitHub Pages) -- [ ] Remaining GPO refinements below - -### GPO delivery for fleet scale - -- Generate a GPO-importable advanced audit policy `audit.csv` directly from - the settings table, so the GPO can never drift from the tested baseline -- Mapping table: every subcategory and registry value to its Group Policy - path (Advanced Audit Policy Configuration / Administrative Templates) -- LGPO.exe backup/import artefacts for air-gapped estates -- Channel sizing at scale (the awkward one: non-classic channel sizes have no - clean ADMX, so document the startup-script and registry `MaxSize` options - with their caveats) -- Domain controller profile notes (volume expectations for DS Access, SAM, - Kerberos subcategories on real DCs) - -## v0.6 - Native ATT&CK mapping (in progress) - -- [x] Coverage mapping rebuilt on current MITRE ATT&CK data (v19.2 - detection strategies/analytics) joined through a kit-curated, per-row - sourced event map; OSSEM-DM retained as `-UseOssem` cross-check with - credit -- [x] Release zip packaging fixed to include data/presets/tools/tests -- [x] Docs architecture page with mermaid diagram -- [ ] Work the Unmapped curation list down (4 sources at snapshot time) -- [ ] Define a refresh cadence for the ATT&CK snapshot (procedure documented - in data/attack/README.md) - -## Later / help wanted - -- Locale-independent verification: parse numeric setting values from - `auditpol /backup` output instead of localised `auditpol /get /r` text -- Pester-based test suite (CI with PSScriptAnalyzer + self-checks on 5.1 and 7 - shipped in v0.2.0; migrating the harness to Pester remains) -- Event volume telemetry: a companion script that measures events/hour per - setting after the pilot week, to make the HighVolume decision evidence-based -- [x] WEF subscription XPath filtering matched to the baseline - (`New-WefSubscription.ps1 -Filter Baseline`, vendored Microsoft - per-subcategory event lists) with local `-Validate` and collector-side - proof (`Test-WefFilter.ps1`). Next: measured Suppress defaults from pilot - volume, and per-channel filters for the non-Security channels -- AutorunsToWinEventLog add-on, next steps: a diff mode that writes only - new or changed entries since the last run (the full daily snapshot is - simple and SIEM-diffable, but ~1,600 events/host/day adds up at fleet - scale), and an Intune / GPO deployment recipe for the installer diff --git a/docs/addons.md b/docs/addons.md index dd01ddf..e6b85f1 100644 --- a/docs/addons.md +++ b/docs/addons.md @@ -17,7 +17,7 @@ yesterday's, alert on an unsigned binary in a Run key, pivot on a hash. **Why it is an add-on and not a baseline setting:** the kit's core is native configuration only. Registry autostart locations are the one -[Persistence gap](architecture.md#behaviour-category-mapping) native +[Persistence gap](mapping.md#behaviour-category-mapping) native auditing cannot cover without per-key SACLs (the [Audit Registry](https://learn.microsoft.com/windows/security/threat-protection/auditing/audit-registry) subcategory only records access to keys that carry one), and Autoruns is @@ -81,8 +81,8 @@ Volume, observed on one Windows 11 24H2 workstation with autorunsc 14.3 seconds, **4.1 MB of event log per run** (event records carry overhead well beyond the ~1 MB CSV). Servers and hosts with many installed products will differ; measure your own with `-Status`. Multiply by fleet size -before pointing it at a billable table; the roadmap has a diff mode for -exactly that reason. +before pointing it at a billable table; a diff mode that writes only new +or changed entries is planned for exactly that reason. ### Collecting it centrally diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index 32e27ff..0000000 --- a/docs/architecture.md +++ /dev/null @@ -1,130 +0,0 @@ -# Architecture - -How the kit works under the hood, in one picture. The claim it makes: -**all configuration derives from a single settings table (coverage -additionally reads the shipped ATT&CK snapshot), snapshots come in once -with their dates recorded, and events flow out to your collector - the kit -never talks to the internet at runtime.** - -
- - - - - - - - - - - - - - - - - - - - Vendored snapshots - Yamato baselines · MITRE ATT&CK - copied once, dated, credited - Settings table - the single source of truth - Windows host - audit policy · channels · registry - SMB auditing - Windows Event Log - Event Collector - ForwardedEvents log - SIEM - Coverage report - Export-AttackCoverage - Fleet artefacts - Intune pack · WEF XML - GPO pack - - - - - - - - - - - - - - - - - - Yamato: extracted once, drift-checked - ATT&CK snapshot - Enable applies · Test verifies - events - WEF push (WinRM) - handoff — out of kit scope - generators compile - apply - WEF subscription - - -
One settings table feeds the host, the fleet artefacts and the verification; events leave through the Windows Event Log to your collector.
-
- -Reading it top to bottom: - -- **Snapshots in**: the Yamato baselines were extracted once into the - settings table, and the MITRE ATT&CK data into the coverage mapping - (`data/attack/`) - two separate destinations, each with source, version - and date recorded (`data/*/README.md`); CI drift-checks everything - generated from them. -- **One table**: every script - the builder, Enable, Test, the coverage - report and all three fleet generators - dot-sources - `LoggingBaseline.Settings.ps1`, so applied config, deployed artefacts and - verification can never disagree. -- **Events out**: hosts write to the Windows Event Log service; - [Windows Event Forwarding](https://learn.microsoft.com/windows/security/operating-system-security/device-management/use-windows-event-forwarding-to-assist-in-intrusion-detection) - carries selected channels over WinRM to a collector's ForwardedEvents - log; your SIEM picks up there, deliberately outside the kit. - -Which application each piece touches: Enable/Test drive `auditpol.exe`, -`wevtutil.exe`, the registry and the SMB configuration cmdlets; the Intune -pack is consumed by **Microsoft Intune** (Scripts and remediations); the -subscription XML by the **Windows Event Collector** (`wecutil`); the GPO -pack by **GPMC / LGPO.exe**; and WELA runs as an independent checker -alongside Test. - -## Behaviour category mapping - -The kit organises settings by **behaviour category** rather than by channel, -so a monitoring requirement ("we must see scheduled task abuse") traces to -the exact settings that satisfy it. "Subcategory" = advanced audit policy -subcategory (Security log). DC = generated on domain controllers only. -HV = HighVolume tier. - -| Category | Audit subcategories | Channels | Registry | Coverage | -|---|---|---|---|---| -| Authentication | Credential Validation; Logon; Logoff; Account Lockout; Other Logon/Logoff; Special Logon; Kerberos Authentication Service (DC); Kerberos Service Ticket Operations (DC) | Security; Microsoft-Windows-NTLM/Operational | MSV1_0 `RestrictSendingNTLMTraffic=1` (audit), `AuditReceivingNTLMTraffic=2`; Netlogon `AuditNTLMInDomain=7` (DC) | Full | -| Execution | Process Creation (HV) | Security; WMI-Activity/Operational; Bits-Client/Operational; AppLocker x4; Diagnosis-Scripted/Operational | `ProcessCreationIncludeCmdLine_Enabled=1` (HV) | Full via 4688+cmdline; no file hashes or DLL loads natively (accepted gap) | -| Account and access change | User Account Management; Security Group Management; Other Account Management; Computer Account Management (DC); Distribution Group Management (DC); Authentication Policy Change | Security | - | Full | -| Privilege use | Special Logon (4672); Sensitive Privilege Use (HV) | Security | - | Full | -| Logging tampered with | Audit Policy Change (4719); Security State Change; System Integrity; Other System Events (failure) | Security (1100/1102/1104 default); System (104); Defender/Operational (tamper) | - | Full | -| Software and service install | Security System Extension (4697) | System (7045); Application (MsiInstaller); CodeIntegrity/Operational; PrintService Admin + Operational | - | Full | -| Remote access | Logon (types 3/10); Other Logon/Logoff (4778/4779); RPC Events | TerminalServices-LocalSessionManager/Operational; SmbClient/Security | - | Full | -| Scheduled and automated tasks | Other Object Access (4698-4702) | TaskScheduler/Operational; WMI-Activity/Operational | - | Full | -| Scripting and command line | Process Creation (HV) | PowerShell/Operational (4103/4104); Windows PowerShell; PowerShellCore/Operational; Diagnosis-Scripted | Script block + module logging (HV); cmdline (HV); transcription (Optional) | Full for PowerShell; other interpreters visible only via 4688 command lines | -| Persistence | Security System Extension; Other Object Access; Directory Service Changes (DC) | System (7045); TaskScheduler/Operational; WMI-Activity/Operational; Bits-Client/Operational | - | **Partial**: registry autoruns (Run keys, IFEO) need the Registry subcategory + per-key SACLs, not in this baseline. The optional [Autoruns add-on](addons.md) partially mitigates it with a daily autostart inventory (not real-time SACL auditing) | -| Removable and external devices | Plug and Play (6416); Removable Storage (4663) | DriverFrameworks-UserMode/Operational | - | Full | -| Blocked and denied activity | Account Lockout; Filtering Platform Connection blocks (HV) | Defender/Operational; AppLocker x4; CodeIntegrity; Security-Mitigations x2; Firewall | - | Full (AppLocker channels populate only if AppLocker policy deployed) | -| Directory and identity store | Directory Service Access (DC); Directory Service Changes (DC); SAM; Kerberos Authentication Service (DC) | Security | - | Full on DCs; standalone = local SAM only (by design) | -| File and object access | File Share (5140/5142-5144); Removable Storage | Security | - | **Partial**: per-file auditing (4663) needs File System subcategory + SACLs on chosen paths, a per-asset design decision, deliberately not blanket-enabled | -| Certificates and keys | Certification Services (4898/4899); Other Policy Change (CNG) | Security; Crypto-DPAPI/Debug (Optional) | AD CS `AuditFilter=127` (only when AD CS installed; CertSvc restart) | Full where AD CS present; limited elsewhere (accepted) | -| Network flow and sessions | Filtering Platform Connection 5156/5157 (HV); RPC Events | Firewall channel; SmbClient/Security | - | **Partial**: no byte counts / flow aggregation natively; true flow telemetry needs network-layer sources, outside host scope | - -The partial rows are the recognised gaps of agentless native logging -(registry autoruns, per-file SACLs, flow statistics, execution depth beyond -4688 command lines) - do not expect a native setting to close them; see -[Safety - known limits](safety.md#known-limits-stated-plainly). diff --git a/docs/baselines.md b/docs/baselines.md index c4a73a1..ad3e629 100644 --- a/docs/baselines.md +++ b/docs/baselines.md @@ -35,7 +35,7 @@ same `-BaselineFile`. The split exists so volume decisions are made by a human with the impact in front of them - `Export-AttackCoverage.ps1` quantifies what the HighVolume tier buys (117 additional ATT&CK techniques over Core: 162 -> 279 of the -284-technique native ceiling; see [the mapping page](mapping.md)). +284-technique native ceiling; see [Coverage](mapping.md)). ## Building a baseline @@ -223,7 +223,7 @@ Notes, stated plainly: validates this set at the practice level (PowerShell logging, command line capture, centralised collection); NIST SP 800-92 / CSF and CIS Benchmarks are governance or licence-restricted comparisons, cited rather - than vendored; a DISA STIG preset is a roadmap candidate (public domain, + than vendored; a DISA STIG preset is a candidate for a later release (public domain, subcategory-level). ## Deviations from the Yamato sources diff --git a/docs/commands.md b/docs/commands.md index fb1e572..3340b4e 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -58,10 +58,9 @@ No elevation needed; changes nothing. ## Export-AttackCoverage.ps1 -Joins a selection against the vendored OSSEM-DM snapshot and reports which -ATT&CK techniques it makes observable - and why the rest are not -(NotSelected / NotInKit / RequiresSysmon). See -[ATT&CK Coverage Mapping](mapping.md). +Joins a selection against the vendored MITRE ATT&CK snapshot and reports +which techniques it makes observable - and why the rest are not +(NotSelected / NotInKit / RequiresSysmon). See [Coverage](mapping.md). ```powershell .\Export-AttackCoverage.ps1 [-IncludeHighVolume] [-IncludeOptional] [-BaselineFile ] @@ -107,7 +106,7 @@ always kit drift): ## New-IntuneRemediationPack.ps1 Compiles the selection into a self-contained Intune detection + remediation -script pair. See [Fleet Deployment](deployment.md). +script pair. See [Deploy](deployment.md). ## New-WefSubscription.ps1 @@ -119,7 +118,7 @@ Two filter modes: `Channel` (default) forwards each selected channel whole; subcategories can produce (vendored Microsoft lists in `data\wef\`) plus the always-on log-tamper events. `-Validate` parses every query in the local event engine first. See -[filtering with XPath](wec.md#filtering-with-xpath-matching-the-subscription-to-the-baseline). +[Collect - filtering with XPath](wec.md#filtering-with-xpath-matching-the-subscription-to-the-baseline). ```powershell .\New-WefSubscription.ps1 [-BaselineFile ] [-Filter Channel|Baseline] [-Validate] [-SubscriptionId ] [-OutDir ] @@ -141,7 +140,7 @@ on any unexpected ID or mismatch. ## New-GpoPack.ps1 Generates the advanced audit policy `audit.csv` and an LGPO-format -`registry.txt` from the selection. See [Fleet Deployment](deployment.md). +`registry.txt` from the selection. See [Deploy](deployment.md). ## tests\Invoke-KitChecks.ps1 diff --git a/docs/deployment.md b/docs/deployment.md index a876c50..9ef0151 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,23 +1,13 @@ -# Fleet Deployment +# Deploy -How to roll a baseline out to many machines - through Intune, Windows -Event Forwarding, or Group Policy - all generated from the same tested -selection (tier switches, or optionally a baseline CSV). One mental model -for everything on this page: - -```text -generate (this kit, on each host) -> transport (WEF/WEC) -> ingest (your SIEM) -``` - -The kit owns *generate* and helps you set up *transport*. *Ingest* - -agents, connectors, SIEM-side filtering - is deliberately out of scope: the -handoff point is the ForwardedEvents log on your collector. - -All three generators below compile from the settings table (or the same -`-BaselineFile` selection CSV used everywhere else), so deployed artefacts +How to roll a baseline out to many machines through Intune or Group Policy. +Both generators compile from the settings table, or from the same +`-BaselineFile` selection CSV used everywhere else, so deployed artefacts cannot drift from the tested baseline. Regenerate after any settings change; the generated files say not to edit them by hand. +Central collection (WEF / WEC) has its own page: [Collect](wec.md). + ## Intune (workstations and cloud-managed servers) ```powershell @@ -38,56 +28,6 @@ role- and version-gating happens at runtime on each host. The AD CS AuditFilter is excluded from packs by design (it needs a CertSvc restart, which does not belong in unattended remediation). -## WEF/WEC (central collection, agentless) - -```powershell -.\New-WefSubscription.ps1 [-BaselineFile ] [-SubscriptionId ] -``` - -Generates a source-initiated subscription XML - one query per selected -channel. Transport defaults (`Events` format, 30s/500-item batching, 1h -heartbeat, source SDDL) live in the settings table and are overridable per -run. The script prints the full setup: - -```text -Collector: winrm qc -q (WinRM listener first) - wecutil qc /q (then the collector service) - wecutil cs .\WEF\WinLogKit-Baseline.xml - wevtutil sl ForwardedEvents /ms:1073741824 -Sources: winrm qc -q (WinRM must be configured on each source too - or - enable the WinRM service via GPO fleet-wide) - GPO > Event Forwarding > Configure target Subscription Manager - Server=http://:5985/wsman/SubscriptionManager/WEC,Refresh=60 -``` - -Per [Microsoft's source-initiated subscription procedure](https://learn.microsoft.com/windows/win32/wec/setting-up-a-source-initiated-subscription), -both ends need WinRM: the collector to listen, the sources to forward. - -The classic trap: for the Security log, add NETWORK SERVICE to **Event Log -Readers** on sources, or Security forwarding silently fails. Verify either -side with: - -```powershell -.\Test-LoggingBaseline.ps1 -WefRole Source # on a forwarding host -.\Test-LoggingBaseline.ps1 -WefRole Collector # on the WEC -``` - -Two filter modes. `-Filter Channel` (default) forwards every event of each -selected channel - the baseline's channel selection is the coarse filter and -the right first deployment. `-Filter Baseline` narrows the Security channel -to exactly the event IDs the baseline's enabled audit subcategories can -produce (Microsoft's documented per-subcategory lists, vendored in -`data\wef\`) plus the always-on log-tamper events, and leaves every other -channel whole. Add `-Validate` to parse each query in the local event engine -before deploying, then prove the filter on the collector with -`Test-WefFilter.ps1`. How the XPath works and how to confirm it: -[WEC Collector - filtering with XPath](wec.md#filtering-with-xpath-matching-the-subscription-to-the-baseline). - -Beyond generating the subscription: the [WEC Collector](wec.md) page covers -reading and verifying an existing collector (subscription anatomy, runtime -status, the silent failures), and [Sentinel KQL](kql.md) covers the onward -hop to a SIEM workspace and the queries that prove the chain end-to-end. - ## GPO (domain-joined fleets) ```powershell diff --git a/docs/kql.md b/docs/extras/sentinel-kql.md similarity index 96% rename from docs/kql.md rename to docs/extras/sentinel-kql.md index 6d6cb46..9868339 100644 --- a/docs/kql.md +++ b/docs/extras/sentinel-kql.md @@ -1,10 +1,15 @@ # Sentinel KQL +!!! note "Kept as an extra" + WinLogKit is SIEM-agnostic and ends at the collector's ForwardedEvents + log. This page is one worked example of verifying the last hop, for + Microsoft Sentinel. It is outside the main navigation on purpose. + Verifying the last hop: a collector (or any host) shipping events to a Log Analytics workspace with the Azure Monitor Agent (AMA), and the KQL that proves the whole chain works. Generic Microsoft Sentinel / Azure Monitor material - nothing here is specific to this kit, but every query assumes -the [WEC page's](wec.md) architecture: sources push to a collector's +the [WEC page's](../wec.md) architecture: sources push to a collector's ForwardedEvents log, AMA collects that log. ## Which table the events land in @@ -275,16 +280,17 @@ it is evidence, not proof, of a machine's state): the local config cache for `ForwardedEvents` as in the four-layer check above. - **ForwardedEvents is empty or stale** -> the WEF half is broken: - run `wecutil es` / `wecutil gr` on that collector. No subscriptions + run `wecutil es` on that collector, then `wecutil gr ` for each + subscription it lists. No subscriptions = it was never set up; subscriptions with zero or Inactive sources - = work the [WEC page's](wec.md) reconciliation and silent-failures + = work the [WEC page's](../wec.md) reconciliation and silent-failures table (GPO scope, WinRM, the Security-log permission). It is entirely possible for some collectors in an estate to have subscriptions and others none - each collector's subscription store is local to it. **Channel and event mix** - compare against the subscription query and the -source baseline (the [Reference page](reference.md) lists what each kit +source baseline (the [Reference page](../reference.md) lists what each kit setting emits): ```kusto @@ -361,7 +367,7 @@ WindowsEvent **Payload spot check** - pulling fields from the dynamic bag (4688 with command line, assuming the source enables the kit's -[HighVolume tier](baselines.md#tiers)): +[HighVolume tier](../baselines.md#tiers)): ```kusto WindowsEvent diff --git a/docs/faq.md b/docs/faq.md deleted file mode 100644 index 457aaf9..0000000 --- a/docs/faq.md +++ /dev/null @@ -1,111 +0,0 @@ -# FAQ - -## Does the kit send anything anywhere, or fetch live data? - -No. The kit is a static snapshot: the Yamato baselines and the OSSEM-DM -ATT&CK mappings are vendored with recorded provenance (source, commit, -date). Nothing is fetched at runtime, and nothing about your hosts, -results or baselines leaves them. The baseline has one optional network -action, `Invoke-WELACheck.ps1 -Download`, which fetches WELA from GitHub -when you explicitly ask; the optional [Autoruns add-on](addons.md) adds a -second, `Install-AutorunsToWinEventLog.ps1 -Download`, which fetches -`autorunsc` from live.sysinternals.com. Both have an offline alternative -(bring the files yourself), so air-gapped estates need no network at all. - -## How is this different from just running Yamato's batch script? - -Same settings, operationalised: idempotent apply with `-WhatIf` and -rollback, tiered volume decisions, read-only verification with evidence -CSVs, per-role baseline files, fleet delivery (Intune/WEF/GPO) compiled -from one settings table, and ATT&CK coverage numbers for the selection. -Plus a handful of documented fixes to upstream quirks (e.g. the batch -sizes PrintService/Operational but never enables it; WELA's `configure` -sets an NTLM value that *blocks* rather than audits). - -## Why isn't Sysmon included? - -Kit scope is native Windows configuration only - environments where agents -are unwelcome (change-restricted servers, OT-adjacent estates). Sysmon is -excellent; if you can run it, run it (the coverage report even tells you -which techniques are Sysmon-only). The kit covers the ground available -without it. - -The one deliberate exception is the optional -[AutorunsToWinEventLog add-on](addons.md), which depends on Sysinternals -`autorunsc` (a command-line tool, not a resident agent) to add a daily -inventory over the registry-autorun Persistence gap - partial mitigation, -not SACL-grade change auditing. It lives in its own folder, is never -installed by the baseline scripts, and is documented as the exception it -is. - -## Something broke / I want out. How do I undo everything? - -```powershell -.\Enable-LoggingBaseline.ps1 -Rollback -``` - -restores the audit policy, channel sizes/state and registry values captured -on the first real run. Nothing in the kit requires a reboot. - -Backups are automatic, and always taken **before** any change: the first -real apply captures the complete pre-kit state to `.\Baseline\` (that is -what `-Rollback` restores), and every later apply saves a timestamped -pre-change snapshot to `.\Baseline\snapshots\\` - so stepping -from, say, Minimal to Heavy leaves a point-in-time record. To return to an -intermediate state rather than the very beginning: -`auditpol /restore /file:\auditpol-backup.csv`, plus the channel, -registry and SMB audit values recorded in that snapshot's `State.json` -(restore each `SmbAudit` entry with `Set-SmbServerConfiguration` or -`Set-SmbClientConfiguration` per its `Side`). - -## Can I run this on a domain controller? - -Yes - DC-only items (Kerberos, Directory Service subcategories, and more) -activate automatically on DCs and report NOT APPLICABLE elsewhere. Mind the -volume notes for DCs (SAM, File Share, Kerberos are busy there) and pilot -on one DC first. - -## Windows Home edition? - -Works - the kit's mechanisms (`auditpol`, `wevtutil`, registry) do not -depend on Group Policy tooling, which Home lacks. The kit's own workstation -field testing was done on Windows 11 Home: full apply, verify (all 16 -categories PASS) and rollback. - -## What's special on Server 2025 and Windows 11 24H2? - -Both can audit which SMB peers cannot do signing or encryption (events -3021/3022 server-side, 31998/31999 client-side; availability per -Microsoft's -[SMB feature descriptions](https://learn.microsoft.com/windows-server/storage/file-server/smb-feature-descriptions)). -The kit enables these audit-only settings and sizes both Audit channels; -on earlier versions the properties do not exist and the items report -NOT APPLICABLE. Two related notes: - -- **NTLM**: NTLMv1 is removed in Server 2025 and the SMB client supports - NTLM blocking. The kit's NTLM values stay audit-only - (`RestrictSendingNTLMTraffic = 1`), safe on all supported versions, and - feed the evidence you need before turning any blocking on. -- **Alignment**: Microsoft's own Server 2025 security baseline - ([OSConfig](https://learn.microsoft.com/windows-server/security/osconfig/osconfig-overview)) - audits Success and Failure on nearly all subcategories, captures 4688 - command lines, and requires the Security log at 192 MB minimum. This kit - meets or exceeds all of that (Security at 1 GB). - -On workstations generally, volume calibration differs from servers: far -fewer logons and connections make the HighVolume tier more affordable per -host, while the 1 GB Security log matters more on small SSDs. - -## Does a "PASS" mean I'm detecting attacks? - -No - it means the configured events are being generated and retained. -Detection needs rules on top (Sigma, SIEM analytics). WELA's rule counts -and the [coverage mapping](mapping.md) tell you what your events *support*. - -## How do I update the kit without losing my baselines? - -Your selection CSVs and per-host output folders are separate from the kit -scripts. Pull the new release, keep your CSVs, rerun -`Test-LoggingBaseline.ps1 -BaselineFile ` - the settings table may -have new items, which show as unlisted/excluded until you re-run the -builder and re-select. diff --git a/docs/index.md b/docs/index.md index 061fd96..6e244f6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,106 +1,6 @@ --- hide: - - navigation - toc --- -
- -# :material-shield-search: WinLogKit - -

-**WinLogKit** turns the Yamato Security -logging baselines into something you can actually deploy: enable the right -Windows events, prove they're being recorded, and roll back if you change -your mind - plain PowerShell, no agents. -

- -
-[:material-rocket-launch: Get started in 10 minutes](getting-started.md){ .md-button .md-button--primary } -[:material-radar: See your ATT&CK coverage](mapping.md){ .md-button } -[:fontawesome-brands-github: View on GitHub](https://github.com/spydisec/WinLogKit){ .md-button } -
- -

-CI -Release -MIT License -

- -

-Out of the box, Windows supports only 10-20% of Sigma detection rules, and -default log sizes of 1-20 MB mean evidence is quickly overwritten -(Yamato's guide). -

- -
- ---- - -## Why WinLogKit - -
- -- :material-backup-restore:{ .lg .middle } __Deploy with an exit ramp__ - - --- - - Preview everything with `-WhatIf`; an automatic pre-change backup means - one command rolls it all back. - -- :material-check-decagram:{ .lg .middle } __Prove it, don't assume it__ - - --- - - Per-category PASS/FAIL with evidence CSVs, plus Yamato's - [WELA](https://github.com/Yamato-Security/WELA) as an independent - second opinion. - -- :material-chart-box:{ .lg .middle } __Decide volume with numbers__ - - --- - - The [ATT&CK coverage report](mapping.md) (current MITRE v19.2 data) - measures each tier - Heavy buys 98% of the native ceiling. - -- :material-table-sync:{ .lg .middle } __One table, every target__ - - --- - - Intune packs, WEF subscriptions and GPO artefacts all compile from one - settings table - deployed config can't drift from the tested baseline. - -
- -## What it targets - -Windows Server 2019 / 2022 / 2025 and Windows 10 / 11 workstations, -standalone or domain-joined. Version- and role-specific items are detected -at runtime and reported NOT APPLICABLE where they don't apply. Baselines -ship as reviewable CSVs: reference sets (ASD, Microsoft), per-role starting -points, and the blended `spydi_*` Minimal/Heavy pairs - -[all documented with sources and event IDs](baselines.md). - -## Privacy - -The kit is a **static snapshot**: the Yamato baselines and the MITRE ATT&CK -mapping data are vendored with recorded provenance. Nothing is fetched at -runtime, and nothing about your hosts, results or baselines ever leaves -them. The single optional network action is `Invoke-WELACheck.ps1 -Download`, -which fetches WELA from GitHub to your machine when you explicitly ask. - -## Credits - -Settings and baselines come from Yamato Security's -[EnableWindowsLogSettings](https://github.com/Yamato-Security/EnableWindowsLogSettings), -[WELA](https://github.com/Yamato-Security/WELA) and -[EventLog-Baseline-Guide](https://github.com/Yamato-Security/EventLog-Baseline-Guide); -ATT&CK mapping data from [MITRE ATT&CK](https://github.com/mitre-attack/attack-stix-data) -with approach credit to OTRF's [OSSEM-DM](https://github.com/OTRF/OSSEM-DM). -This project is affiliated with none of them. MIT licensed; deviations from -upstream are documented with reasons. - -!!! warning "Test before you trust" - Logging volume costs disk and money. Run any baseline on a mirror of - production for a week, then use the coverage and volume numbers to - decide what stays. +--8<-- "README.md" diff --git a/docs/mapping.md b/docs/mapping.md index 57d60a1..e4b74a8 100644 --- a/docs/mapping.md +++ b/docs/mapping.md @@ -1,9 +1,143 @@ -# ATT&CK Coverage Mapping - -One question, answered with numbers: **if I turn these settings on, which -attack techniques could my logs actually see - and for the rest, why not?** -`Export-AttackCoverage.ps1` computes it locally for any baseline, offline, -from data shipped in the kit. +# Coverage + +Two questions, answered from data shipped in the kit: **how do the pieces +fit together**, and **if I turn these settings on, which attack techniques +could my logs actually see, and for the rest, why not?** +`Export-AttackCoverage.ps1` computes the second one locally for any +baseline, offline. + +## How the pieces fit + +How the kit works under the hood, in one picture. The claim it makes: +**all configuration derives from a single settings table (coverage +additionally reads the shipped ATT&CK snapshot), snapshots come in once +with their dates recorded, and events flow out to your collector - the kit +never talks to the internet at runtime.** The two opt-in exceptions fetch +a tool only when you ask: `Invoke-WELACheck.ps1 -Download` and the +[Autoruns add-on](addons.md) installer's `-Download`. + +
+ + + + + + + + + + + + + + + + + + + + Vendored snapshots + Yamato baselines · MITRE ATT&CK + copied once, dated, credited + Settings table + the single source of truth + Windows host + audit policy · channels · registry + SMB auditing + Windows Event Log + Event Collector + ForwardedEvents log + SIEM + Coverage report + Export-AttackCoverage + Fleet artefacts + Intune pack · WEF XML + GPO pack + + + + + + + + + + + + + + + + + + Yamato: extracted once, drift-checked + ATT&CK snapshot + Enable applies · Test verifies + events + WEF push (WinRM) + handoff — out of kit scope + generators compile + apply + WEF subscription + + +
One settings table feeds the host, the fleet artefacts and the verification; events leave through the Windows Event Log to your collector.
+
+ +Reading it top to bottom: + +- **Snapshots in**: the Yamato baselines were extracted once into the + settings table, and the MITRE ATT&CK data into the coverage mapping + (`data/attack/`) - two separate destinations, each with source, version + and date recorded (`data/*/README.md`); CI drift-checks everything + generated from them. +- **One table**: every script - the builder, Enable, Test, the coverage + report and all three fleet generators - dot-sources + `LoggingBaseline.Settings.ps1`, so applied config, deployed artefacts and + verification can never disagree. +- **Events out**: hosts write to the Windows Event Log service; + [Windows Event Forwarding](https://learn.microsoft.com/windows/security/operating-system-security/device-management/use-windows-event-forwarding-to-assist-in-intrusion-detection) + carries selected channels over WinRM to a collector's ForwardedEvents + log; your SIEM picks up there, deliberately outside the kit. + +Which application each piece touches: Enable/Test drive `auditpol.exe`, +`wevtutil.exe`, the registry and the SMB configuration cmdlets; the Intune +pack is consumed by **Microsoft Intune** (Scripts and remediations); the +subscription XML by the **Windows Event Collector** (`wecutil`); the GPO +pack by **GPMC / LGPO.exe**; and WELA runs as an independent checker +alongside Test. + +## Behaviour category mapping + +The kit organises settings by **behaviour category** rather than by channel, +so a monitoring requirement ("we must see scheduled task abuse") traces to +the exact settings that satisfy it. "Subcategory" = advanced audit policy +subcategory (Security log). DC = generated on domain controllers only. +HV = HighVolume tier. + +| Category | Audit subcategories | Channels | Registry | Coverage | +|---|---|---|---|---| +| Authentication | Credential Validation; Logon; Logoff; Account Lockout; Other Logon/Logoff; Special Logon; Kerberos Authentication Service (DC); Kerberos Service Ticket Operations (DC) | Security; Microsoft-Windows-NTLM/Operational | MSV1_0 `RestrictSendingNTLMTraffic=1` (audit), `AuditReceivingNTLMTraffic=2`; Netlogon `AuditNTLMInDomain=7` (DC) | Full | +| Execution | Process Creation (HV) | Security; WMI-Activity/Operational; Bits-Client/Operational; AppLocker x4; Diagnosis-Scripted/Operational | `ProcessCreationIncludeCmdLine_Enabled=1` (HV) | Full via 4688+cmdline; no file hashes or DLL loads natively (accepted gap) | +| Account and access change | User Account Management; Security Group Management; Other Account Management; Computer Account Management (DC); Distribution Group Management (DC); Authentication Policy Change | Security | - | Full | +| Privilege use | Special Logon (4672); Sensitive Privilege Use (HV) | Security | - | Full | +| Logging tampered with | Audit Policy Change (4719); Security State Change; System Integrity; Other System Events (failure) | Security (1100/1102/1104 default); System (104); Defender/Operational (tamper) | - | Full | +| Software and service install | Security System Extension (4697) | System (7045); Application (MsiInstaller); CodeIntegrity/Operational; PrintService Admin + Operational | - | Full | +| Remote access | Logon (types 3/10); Other Logon/Logoff (4778/4779); RPC Events | TerminalServices-LocalSessionManager/Operational; SmbClient/Security | - | Full | +| Scheduled and automated tasks | Other Object Access (4698-4702) | TaskScheduler/Operational; WMI-Activity/Operational | - | Full | +| Scripting and command line | Process Creation (HV) | PowerShell/Operational (4103/4104); Windows PowerShell; PowerShellCore/Operational; Diagnosis-Scripted | Script block + module logging (HV); cmdline (HV); transcription (Optional) | Full for PowerShell; other interpreters visible only via 4688 command lines | +| Persistence | Security System Extension; Other Object Access; Directory Service Changes (DC) | System (7045); TaskScheduler/Operational; WMI-Activity/Operational; Bits-Client/Operational | - | **Partial**: registry autoruns (Run keys, IFEO) need the Registry subcategory + per-key SACLs, not in this baseline. The optional [Autoruns add-on](addons.md) partially mitigates it with a daily autostart inventory (not real-time SACL auditing) | +| Removable and external devices | Plug and Play (6416); Removable Storage (4663) | Security; DriverFrameworks-UserMode/Operational | - | Full | +| Blocked and denied activity | Account Lockout; Filtering Platform Connection blocks (HV) | Security; Defender/Operational; AppLocker x4; CodeIntegrity; Security-Mitigations x2; Firewall | - | Full (AppLocker channels populate only if AppLocker policy deployed) | +| Directory and identity store | Directory Service Access (DC); Directory Service Changes (DC); SAM; Kerberos Authentication Service (DC) | Security | - | Full on DCs; standalone = local SAM only (by design) | +| File and object access | File Share (5140/5142-5144); Removable Storage | Security | - | **Partial**: per-file auditing (4663) needs File System subcategory + SACLs on chosen paths, a per-asset design decision, deliberately not blanket-enabled | +| Certificates and keys | Certification Services (4898/4899); Other Policy Change (CNG) | Security; Crypto-DPAPI/Debug (Optional) | AD CS `AuditFilter=127` (only when AD CS installed; CertSvc restart) | Full where AD CS present; limited elsewhere (accepted) | +| Network flow and sessions | Filtering Platform Connection 5156/5157 (HV); RPC Events | Firewall channel; SmbClient/Security | - | **Partial**: no byte counts / flow aggregation natively; true flow telemetry needs network-layer sources, outside host scope | + +The partial rows are the recognised gaps of agentless native logging +(registry autoruns, per-file SACLs, flow statistics, execution depth beyond +4688 command lines) - do not expect a native setting to close them; see +[Safety - known limits](safety.md#known-limits-stated-plainly). ## How the native mapping works diff --git a/docs/safety.md b/docs/safety.md index 40b0fd3..660c6f6 100644 --- a/docs/safety.md +++ b/docs/safety.md @@ -1,4 +1,4 @@ -# Safety & Volume +# Safety & FAQ The settings that can genuinely hurt a Windows machine, how the kit avoids every one of them, and which of the *safe* settings still cost real disk @@ -39,7 +39,7 @@ decision. - **English-language OS assumed for verification**: `auditpol` output text is localised; setting uses GUIDs and is locale-safe. Locale-neutral - verification is a roadmap item. + verification is planned. - **Native gaps**: registry autoruns need SACLs for change auditing (the optional [Autoruns add-on](addons.md) adds a daily inventory of them, which is a partial mitigation, not SACL coverage); no file hashes or DLL @@ -47,3 +47,120 @@ decision. of agentless native logging - the docs say so instead of pretending. - **Domain-joined hosts**: GPO reapplies audit policy at refresh; deliver fleet-wide via the [deployment artefacts](deployment.md). + +## FAQ + +### Does the kit send anything anywhere, or fetch live data? + +No. The kit is a static snapshot: the Yamato baselines and the MITRE +ATT&CK mapping data are vendored with recorded provenance (source, commit, +date). Nothing is fetched at runtime, and nothing about your hosts, +results or baselines leaves them. The baseline has one optional network +action, `Invoke-WELACheck.ps1 -Download`, which fetches WELA from GitHub +when you explicitly ask; the optional [Autoruns add-on](addons.md) adds a +second, `Install-AutorunsToWinEventLog.ps1 -Download`, which fetches +`autorunsc` from live.sysinternals.com. Both have an offline alternative +(bring the files yourself), so air-gapped estates need no network at all. + +### How is this different from just running Yamato's batch script? + +Same settings, operationalised: idempotent apply with `-WhatIf` and +rollback, tiered volume decisions, read-only verification with evidence +CSVs, per-role baseline files, fleet delivery (Intune/WEF/GPO) compiled +from one settings table, and ATT&CK coverage numbers for the selection. +Plus a handful of documented fixes to upstream quirks (e.g. the batch +sizes PrintService/Operational but never enables it; WELA's `configure` +sets an NTLM value that *blocks* rather than audits). + +### Why isn't Sysmon included? + +The kit's core is native Windows configuration, for environments where +agents are unwelcome (change-restricted servers, OT-adjacent estates). +Sysmon is excellent; if you can run it, run it, and the coverage report +tells you which techniques are Sysmon-only. Since February 2026 Sysmon is +also a +[built-in optional feature](https://learn.microsoft.com/windows/security/operating-system-security/sysmon/overview) +of Windows 11 and Windows Server 2025, which removes the third-party-agent +objection on those versions; supporting it as a tier of the baseline is +planned. Earlier versions still need the standalone Sysinternals build, +which stays out of scope. + +The one deliberate exception today is the optional +[AutorunsToWinEventLog add-on](addons.md), which depends on Sysinternals +`autorunsc` (a command-line tool, not a resident agent) to add a daily +inventory over the registry-autorun Persistence gap - partial mitigation, +not SACL-grade change auditing. It lives in its own folder, is never +installed by the baseline scripts, and is documented as the exception it +is. + +### Something broke / I want out. How do I undo everything? + +```powershell +.\Enable-LoggingBaseline.ps1 -Rollback +``` + +restores the audit policy, channel sizes/state and registry values captured +on the first real run. Nothing in the kit requires a reboot. + +Backups are automatic, and always taken **before** any change: the first +real apply captures the complete pre-kit state to `.\Baseline\` (that is +what `-Rollback` restores), and every later apply saves a timestamped +pre-change snapshot to `.\Baseline\snapshots\\` - so stepping +from, say, Minimal to Heavy leaves a point-in-time record. To return to an +intermediate state rather than the very beginning: +`auditpol /restore /file:\auditpol-backup.csv`, plus the channel, +registry and SMB audit values recorded in that snapshot's `State.json` +(restore each `SmbAudit` entry with `Set-SmbServerConfiguration` or +`Set-SmbClientConfiguration` per its `Side`). + +### Can I run this on a domain controller? + +Yes - DC-only items (Kerberos, Directory Service subcategories, and more) +activate automatically on DCs and report NOT APPLICABLE elsewhere. Mind the +volume notes for DCs (SAM, File Share, Kerberos are busy there) and pilot +on one DC first. + +### Windows Home edition? + +Works - the kit's mechanisms (`auditpol`, `wevtutil`, registry) do not +depend on Group Policy tooling, which Home lacks. The kit's own workstation +field testing was done on Windows 11 Home: full apply, verify (all 16 +categories PASS) and rollback. + +### What's special on Server 2025 and Windows 11 24H2? + +Both can audit which SMB peers cannot do signing or encryption (events +3021/3022 server-side, 31998/31999 client-side; availability per +Microsoft's +[SMB feature descriptions](https://learn.microsoft.com/windows-server/storage/file-server/smb-feature-descriptions)). +The kit enables these audit-only settings and sizes both Audit channels; +on earlier versions the properties do not exist and the items report +NOT APPLICABLE. Two related notes: + +- **NTLM**: NTLMv1 is removed in Server 2025 and the SMB client supports + NTLM blocking. The kit's NTLM values stay audit-only + (`RestrictSendingNTLMTraffic = 1`), safe on all supported versions, and + feed the evidence you need before turning any blocking on. +- **Alignment**: Microsoft's own Server 2025 security baseline + ([OSConfig](https://learn.microsoft.com/windows-server/security/osconfig/osconfig-overview)) + audits Success and Failure on nearly all subcategories, captures 4688 + command lines, and requires the Security log at 192 MB minimum. This kit + meets or exceeds all of that (Security at 1 GB). + +On workstations generally, volume calibration differs from servers: far +fewer logons and connections make the HighVolume tier more affordable per +host, while the 1 GB Security log matters more on small SSDs. + +### Does a "PASS" mean I'm detecting attacks? + +No - it means the configured events are being generated and retained. +Detection needs rules on top (Sigma, SIEM analytics). WELA's rule counts +and the [coverage mapping](mapping.md) tell you what your events *support*. + +### How do I update the kit without losing my baselines? + +Your selection CSVs and per-host output folders are separate from the kit +scripts. Pull the new release, keep your CSVs, rerun +`Test-LoggingBaseline.ps1 -BaselineFile ` - the settings table may +have new items, which show as unlisted/excluded until you re-run the +builder and re-select. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 3ba9f51..f67def2 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,5 +1,5 @@ /* ========================================================================= - WinLogKit docs — spydi theme (steel blue + signal teal) + WinLogKit docs - spydi theme (steel blue + signal teal) Structure adapted from Yamato Security's WELA docs stylesheet (MIT). ========================================================================= */ @@ -54,63 +54,6 @@ max-width: 68rem; } -/* ========================================================================= - Landing-page hero - ========================================================================= */ -.sp-hero { - text-align: center; - padding: 2.2rem 0 1rem; -} -.sp-hero h1 { - margin-bottom: 0.6rem; -} -.sp-hero .sp-tagline { - font-size: 1.12rem; - line-height: 1.6; - max-width: 44rem; - margin: 0 auto 1.3rem; - color: var(--md-default-fg-color--light); -} -.sp-badges { - margin: 0.3rem 0 1.3rem; -} -.sp-badges img { - margin: 2px; - vertical-align: middle; -} -.sp-cta { - display: flex; - gap: 0.6rem; - justify-content: center; - flex-wrap: wrap; - margin-bottom: 1rem; -} -.sp-cta .md-button { - margin: 0.2rem; -} -.sp-hook { - max-width: 44rem; - margin: 0 auto; - color: var(--md-default-fg-color--light); - font-size: 0.95rem; -} - -/* ========================================================================= - Grid cards (feature highlights) - ========================================================================= */ -.md-typeset .grid.cards > ul > li { - border-radius: 0.5rem; - transition: border-color 160ms ease, box-shadow 160ms ease, transform 160ms ease; -} -.md-typeset .grid.cards > ul > li:hover { - border-color: var(--md-accent-fg-color); - box-shadow: 0 4px 16px rgba(0, 0, 0, 0.10); - transform: translateY(-2px); -} -.md-typeset .grid.cards .lg.middle { - color: var(--md-accent-fg-color); -} - /* ========================================================================= Misc readability ========================================================================= */ diff --git a/docs/wec.md b/docs/wec.md index 8303c88..c2ca595 100644 --- a/docs/wec.md +++ b/docs/wec.md @@ -1,27 +1,81 @@ -# WEC Collector +# Collect -A practical guide to the Windows Event Collector side of central -collection: reading what a collector is already doing, understanding the -subscription that controls it, and verifying that sources are actually -sending. Everything here is read-only unless marked otherwise, so it is -safe on a production collector. +Central collection with Windows Event Forwarding (WEF): generate the +subscription from the same selection you applied, set up the collector and +the sources, read what an existing collector is already doing, and prove +that events arrive. The commands under "Set up" change configuration; +everything else on this page is read-only and safe on a production +collector. Where this sits in the chain: ```text -Member server WEC collector SIEM -[audit policy + channels] --push--> [subscription -> ForwardedEvents] --agent--> [workspace] +Source host WEC collector SIEM +[audit policy + channels] --push--> [subscription -> ForwardedEvents] --agent--> [your platform] Gate 1 Gate 2 Gate 3 ``` The gates multiply. An event reaches the collector only if it is -**generated** on the source (Gate 1, this kit's job) *and* **matched** by -the subscription query (Gate 2, this page). A subscription cannot forward +**generated** on the source (Gate 1, the baseline's job) *and* **matched** +by the subscription query (Gate 2, this page). A subscription cannot forward what was never generated, and source config cannot force forwarding of a channel the subscription does not name. Keeping both generated from the same baseline selection is why [`New-WefSubscription.ps1`](commands.md#new-wefsubscriptionps1) exists. -Gate 3 is covered on the [Sentinel KQL](kql.md) page. +Gate 3, the hop from ForwardedEvents into a SIEM, is deliberately outside +the kit: any agent or connector that reads a Windows event log will do. One +worked example for Microsoft Sentinel is kept as an +[extra](extras/sentinel-kql.md). + +## Generate the subscription + +```powershell +.\New-WefSubscription.ps1 [-BaselineFile ] [-Filter Channel|Baseline] [-Validate] [-SubscriptionId ] +``` + +Generates a source-initiated subscription XML with one query per selected +channel, plus a sidecar `.expected-eventids.csv` saying what it +should deliver. Transport defaults (`Events` format, 30s/500-item batching, +1h heartbeat, source SDDL) live in the settings table and are overridable +per run. + +Two filter modes. `-Filter Channel` (default) forwards every event of each +selected channel: the baseline's channel selection is the coarse filter and +the right first deployment. `-Filter Baseline` narrows the Security channel +to exactly the event IDs the baseline's enabled audit subcategories can +produce, plus the always-on log-tamper events, and leaves every other +channel whole; see +[filtering with XPath](#filtering-with-xpath-matching-the-subscription-to-the-baseline) +below. Add `-Validate` to parse each query in the local event engine before +deploying, then prove the filter on the collector with +`Test-WefFilter.ps1`. + +## Set up the collector and the sources + +The generator prints the full setup; the essentials: + +```text +Collector: winrm qc -q (WinRM listener first) + wecutil qc /q (then the collector service) + wecutil cs .\WEF\WinLogKit-Baseline.xml + wevtutil sl ForwardedEvents /ms:1073741824 +Sources: winrm qc -q (WinRM must be configured on each source too - or + enable the WinRM service via GPO fleet-wide) + GPO > Event Forwarding > Configure target Subscription Manager + Server=http://:5985/wsman/SubscriptionManager/WEC,Refresh=60 +``` + +Per [Microsoft's source-initiated subscription procedure](https://learn.microsoft.com/windows/win32/wec/setting-up-a-source-initiated-subscription), +both ends need WinRM: the collector to listen, the sources to forward. + +The classic trap: for the Security log, add NETWORK SERVICE to **Event Log +Readers** on sources, or Security forwarding silently fails. Verify either +side with: + +```powershell +.\Test-LoggingBaseline.ps1 -WefRole Source # forwarding host: SubscriptionManager policy present, WinRM state +.\Test-LoggingBaseline.ps1 -WefRole Collector # collector: Wecsvc, ForwardedEvents sizing, a subscription loaded +``` ## There is no default subscription @@ -53,7 +107,7 @@ XML is what you keep. Command reference: | `` | `SourceInitiated` (sources push to the collector over WinRM, the model that scales) or `CollectorInitiated` (the collector pulls; account-heavy, usually legacy) | | `` | The authoritative "what is forwarded" filter - one `