windiff-version-diff-analysis
Generate and interpret security-research diffs between Windows versions or patch levels using this repo's WinDiff CLI and databases. Use when comparing Windows builds or binaries such as ntoskrnl.exe, ntdll.dll, win32k*.sys, ci.dll, or cng.sys to find changed syscalls, symbols, t
Install
npx skills add https://github.com/ergrelet/windiff/tree/master/skills/windiff-version-diff-analysis
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install ergrelet-windiff@llmmart
git clone https://github.com/ergrelet/windiff.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole ergrelet/windiff collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
WinDiff Version Diff Analysis
Compare two Windows builds and turn the raw symbol/type/syscall delta into a security-research report: what was added, what it probably does, and why it matters for attack surface, exploitation, or defense.
Run this skill from a WinDiff repository checkout. It uses windiff_cli to
generate the per-binary JSON databases, then diffs and interprets them. The
interpretation is the point: explain intent from Windows internals conventions
instead of merely listing symbols.
Locate bundled resources
Resolve all scripts/ and references/ paths relative to this SKILL.md, not
relative to the current working directory and not through a harness-specific
directory such as .claude/ or .agents/. Before running a bundled script, set
SKILL_DIR to the absolute directory containing this file. The examples below
assume that has been done:
SKILL_DIR="<absolute directory containing this SKILL.md>"
If separate shell-tool calls do not share environment, substitute that absolute
path for $SKILL_DIR in each command instead of relying on prior shell state.
Also identify the repository root (the directory containing windiff_cli/,
windiff_frontend/, and ci/) and run repository commands from there. Keep
generated configs, databases, and analysis artifacts under its git-ignored
local/ directory.
Workflow
1. Pin down scope
Establish, asking the user only if genuinely ambiguous:
- Two OS versions as WinDiff triples
version / update / architecture(e.g.21H2 / BASE / amd64and11-24H2 / KB5074105 / amd64).updateisBASEfor an RTM image or aKB...number for a patch. The path suffix used in filenames isversion_update_architecture, e.g.11-24H2_KB5074105_amd64. - Binaries to compare. Default to the security-relevant core when the user is
vague:
ntoskrnl.exe,ntdll.dll,win32k.sys,win32kbase.sys,win32kfull.sys,ci.dll,cng.sys. Read$SKILL_DIR/references/windows-components.mdfor what each one governs. - Focus: syscalls, mitigation flags, new attack surface, a specific component/feature, etc. This steers interpretation, not data generation.
ci/db_configuration.json is the canonical list of tracked versions and binaries
— consult it for valid version/update spellings.
2. Generate the databases with windiff_cli
Write a minimal config containing only the two OS versions and the chosen
binaries, then run the CLI into a scratch output dir (keep it under the repo's
git-ignored local/). Use $SKILL_DIR/scripts/make_config.py to build the
config:
python3 "$SKILL_DIR/scripts/make_config.py" \
--os "21H2:BASE:amd64" --os "11-24H2:KB5074105:amd64" \
--binary ntoskrnl.exe --binary ntdll.dll --binary win32k.sys --binary ci.dll \
> local/windiff_diff_config.json
cd windiff_cli
cargo run --release -- --low-storage-mode \
../local/windiff_diff_config.json ../local/windiff_diff_out/
This downloads PEs from Winbindex and PDBs from MSDL, so it needs network
access and takes minutes per binary. Follow the active harness's normal
permission or approval flow for networked commands. --low-storage-mode keeps
memory bounded. If the CLI fails for one OS (a build may be missing from
Winbindex), report which version/update is unavailable and suggest the nearest
tracked one from ci/db_configuration.json.
If the user says the databases already exist (e.g. in windiff_frontend/public/),
skip generation and point the diff script at that directory instead.
3. Diff each binary
$SKILL_DIR/scripts/windiff_diff.py does the deterministic set/text diff so you
never hand-compute it. Run it per binary; it prints a summary to stderr and
structured JSON to stdout.
python3 "$SKILL_DIR/scripts/windiff_diff.py" \
local/windiff_diff_out ntoskrnl.exe 21H2_BASE_amd64 11-24H2_KB5074105_amd64 \
> local/diff_ntoskrnl.json
Use --list to see available suffixes, --kinds to restrict (e.g.
--kinds syscalls types). Anonymous _unnamed_0xNNNN types are hidden from the
top-level added/removed/modified lists by default (their synthetic ids churn
between builds — noise); pass --include-anon only if you specifically need them.
resolved_member_changes — where new mitigation flags actually show up.
Bitfields like _EPROCESS::MitigationFlagsValues, MitigationFlags2Values, or
_KPROCESS flag words are typed as anonymous _unnamed_0xNNNN structs, and the
individual bits (e.g. RedirectionTrustPolicyEnabled : 1) live inside them. When
Microsoft adds a mitigation, a new bit appears in that anonymous struct — and its
synthetic id churns, so a naive diff would either hide it or show it as noise. The
script resolves this for you: the types.resolved_member_changes array follows
each anonymous member back to its named parent (across the id change) and reports
the real per-member delta as <parent>::<member> with the added/removed
declarations. This is the first place to look for new mitigation bits and other
new bitfield flags — e.g. a new bit under _EPROCESS::MitigationFlags2Values, or
a new _KALPC_MESSAGE::u1::s1 flag. Resolution recurses through nested anonymous
structs/unions, so the path may be several :: levels deep.
Noise to discount when reading the output:
- The script already strips
modifiedlines that differ only by an anonymous type id, and folds genuine anonymous-struct changes intoresolved_member_changes. What remains inmodifiedis real: renamed/added named fields, size changes, new enum values. Still sanity-check againstresolved_member_changesfor the bits. - Exports differing only by ordinal/decoration are usually not meaningful.
- Syscall renumbering with no name change is a rebuild artifact (see
$SKILL_DIR/references/windows-internals.md§3).
4. Interpret with Windows internals knowledge — the core of the analysis
For every meaningful addition, infer what it is and why it matters. Do not
just relay names. Read $SKILL_DIR/references/windows-internals.md for the
reasoning toolkit: API prefixes
(Nt/Zw/Ps/Ke/Mm/Ob/Se/Cm/Alpc/Etw/Ci/Bcrypt), naming
patterns for mitigations, the structures where security flags live
(_PS_MITIGATION_OPTIONS, _KPROCESS/_EPROCESS flag bitfields,
_SEP_TOKEN_*, CI policy structs), and — equally important — the
non-mitigation security surface: kernel notification/callback registration,
ETW providers and the EtwTi threat-intelligence channel, ELAM/AMSI, PPL and
anti-tamper, minifilter hooks, and entirely new drivers/modules. Read
$SKILL_DIR/references/windows-components.md for per-binary roles.
Mitigations are only one of several things worth surfacing. Cast a wide net for
any new security-relevant feature or component and frame it for whichever of
these audiences it serves — $SKILL_DIR/references/windows-internals.md §7 maps
the signals:
- Anti-malware / EDR developers — new ETW providers/events (especially
EtwTi*/ Microsoft-Windows-Threat-Intelligence), newPs/Ob/Cmnotification callbacks, AMSI/ELAM, scanning/notification hooks: new visibility they can consume, or blind spots Microsoft closed. - Anti-cheat developers — process protection (PPL signers), anti-tamper, handle/object hardening, integrity and VBS/HVCI surface, registry/handle monitoring: primitives for protecting a game or detecting cheats.
- Vulnerability researchers — new syscalls/IOCTLs, new parsing surface, new drivers/components, widened structs, callback registration reachable from low privilege: fresh attack surface and exploit primitives (added or removed).
For each finding, aim to state: the prefix/component it belongs to, the subsystem it touches, a concrete hypothesis about the feature/mitigation/component it implements, the security angle (new attack surface, hardening, telemetry, exploit primitive added/removed), and which audience(s) should care and why. Flag uncertainty honestly — "likely", "consistent with" — and suggest how a researcher could confirm (reverse the routine, check public symbols, diff the disassembly).
5. Write the report
Use the structure in $SKILL_DIR/references/report-template.md. Lead with the
highest-signal security findings (new syscalls, mitigation flags, new
ETW/callback surface, new components), not an alphabetical dump. Group related
symbols by component and feature. Every nontrivial item gets an interpretation,
not just a name, and a note on which audience (EDR / anti-cheat / vuln research)
it matters to. The report includes a dedicated section for security-relevant
features and components beyond mitigations so EDR and anti-cheat findings aren't
buried.
Quick reference
$SKILL_DIR/scripts/make_config.py— build a minimal WinDiff config for the two versions$SKILL_DIR/scripts/windiff_diff.py— diff one binary across two OS suffixes (JSON + summary)$SKILL_DIR/references/windows-internals.md— prefixes, mitigation structures, how to infer intent$SKILL_DIR/references/windows-components.md— role of each tracked binary$SKILL_DIR/references/report-template.md— the report format
Files (windiff)
-
agents
-
openai.yaml 253 B
Loading…
-
-
evals
-
evals.json 3.3 KB
Loading…
-
-
references
-
report-template.md 4 KB
Loading… -
windows-components.md 3 KB
Loading… -
windows-internals.md 12.9 KB
Loading…
-
-
scripts
-
make_config.py 2.2 KB
Loading… -
windiff_diff.py 14.8 KB
Loading…
-
-
SKILL.md 9.7 KB
--- name: windiff-version-diff-analysis description: >- Generate and interpret security-research diffs between Windows versions or patch levels using this repo's WinDiff CLI and databases. Use when comparing Windows builds or binaries such as ntoskrnl.exe, ntdll.dll, win32k*.sys, ci.dll, or cng.sys to find changed syscalls, symbols, types, mitigation flags, callbacks, ETW/EtwTi telemetry, code-integrity behavior, drivers, or attack surface. Explain likely intent and security relevance with Windows-internals knowledge, and frame findings for anti-malware/EDR, anti-cheat, and vulnerability-research audiences rather than returning an uninterpreted symbol list. --- # WinDiff Version Diff Analysis Compare two Windows builds and turn the raw symbol/type/syscall delta into a security-research report: what was added, what it probably *does*, and why it matters for attack surface, exploitation, or defense. Run this skill from a **WinDiff** repository checkout. It uses `windiff_cli` to generate the per-binary JSON databases, then diffs and interprets them. The interpretation is the point: explain intent from Windows internals conventions instead of merely listing symbols. ## Locate bundled resources Resolve all `scripts/` and `references/` paths relative to this `SKILL.md`, not relative to the current working directory and not through a harness-specific directory such as `.claude/` or `.agents/`. Before running a bundled script, set `SKILL_DIR` to the absolute directory containing this file. The examples below assume that has been done: ```bash SKILL_DIR="<absolute directory containing this SKILL.md>" ``` If separate shell-tool calls do not share environment, substitute that absolute path for `$SKILL_DIR` in each command instead of relying on prior shell state. Also identify the repository root (the directory containing `windiff_cli/`, `windiff_frontend/`, and `ci/`) and run repository commands from there. Keep generated configs, databases, and analysis artifacts under its git-ignored `local/` directory. ## Workflow ### 1. Pin down scope Establish, asking the user only if genuinely ambiguous: - **Two OS versions** as WinDiff triples `version / update / architecture` (e.g. `21H2 / BASE / amd64` and `11-24H2 / KB5074105 / amd64`). `update` is `BASE` for an RTM image or a `KB...` number for a patch. The path suffix used in filenames is `version_update_architecture`, e.g. `11-24H2_KB5074105_amd64`. - **Binaries** to compare. Default to the security-relevant core when the user is vague: `ntoskrnl.exe`, `ntdll.dll`, `win32k.sys`, `win32kbase.sys`, `win32kfull.sys`, `ci.dll`, `cng.sys`. Read `$SKILL_DIR/references/windows-components.md` for what each one governs. - **Focus**: syscalls, mitigation flags, new attack surface, a specific component/feature, etc. This steers interpretation, not data generation. `ci/db_configuration.json` is the canonical list of tracked versions and binaries — consult it for valid `version`/`update` spellings. ### 2. Generate the databases with windiff_cli Write a **minimal** config containing only the two OS versions and the chosen binaries, then run the CLI into a scratch output dir (keep it under the repo's git-ignored `local/`). Use `$SKILL_DIR/scripts/make_config.py` to build the config: ```bash python3 "$SKILL_DIR/scripts/make_config.py" \ --os "21H2:BASE:amd64" --os "11-24H2:KB5074105:amd64" \ --binary ntoskrnl.exe --binary ntdll.dll --binary win32k.sys --binary ci.dll \ > local/windiff_diff_config.json cd windiff_cli cargo run --release -- --low-storage-mode \ ../local/windiff_diff_config.json ../local/windiff_diff_out/ ``` This downloads PEs from Winbindex and PDBs from MSDL, so it **needs network access** and takes minutes per binary. Follow the active harness's normal permission or approval flow for networked commands. `--low-storage-mode` keeps memory bounded. If the CLI fails for one OS (a build may be missing from Winbindex), report which version/update is unavailable and suggest the nearest tracked one from `ci/db_configuration.json`. If the user says the databases already exist (e.g. in `windiff_frontend/public/`), skip generation and point the diff script at that directory instead. ### 3. Diff each binary `$SKILL_DIR/scripts/windiff_diff.py` does the deterministic set/text diff so you never hand-compute it. Run it per binary; it prints a summary to stderr and structured JSON to stdout. ```bash python3 "$SKILL_DIR/scripts/windiff_diff.py" \ local/windiff_diff_out ntoskrnl.exe 21H2_BASE_amd64 11-24H2_KB5074105_amd64 \ > local/diff_ntoskrnl.json ``` Use `--list` to see available suffixes, `--kinds` to restrict (e.g. `--kinds syscalls types`). Anonymous `_unnamed_0xNNNN` types are hidden from the top-level added/removed/modified lists by default (their synthetic ids churn between builds — noise); pass `--include-anon` only if you specifically need them. **`resolved_member_changes` — where new mitigation flags actually show up.** Bitfields like `_EPROCESS::MitigationFlagsValues`, `MitigationFlags2Values`, or `_KPROCESS` flag words are typed as *anonymous* `_unnamed_0xNNNN` structs, and the individual bits (e.g. `RedirectionTrustPolicyEnabled : 1`) live inside them. When Microsoft adds a mitigation, a new bit appears in that anonymous struct — and its synthetic id churns, so a naive diff would either hide it or show it as noise. The script resolves this for you: the `types.resolved_member_changes` array follows each anonymous member back to its named parent (across the id change) and reports the real per-member delta as `<parent>::<member>` with the added/removed declarations. **This is the first place to look for new mitigation bits and other new bitfield flags** — e.g. a new bit under `_EPROCESS::MitigationFlags2Values`, or a new `_KALPC_MESSAGE::u1::s1` flag. Resolution recurses through nested anonymous structs/unions, so the `path` may be several `::` levels deep. **Noise to discount when reading the output:** - The script already strips `modified` lines that differ only by an anonymous type id, and folds genuine anonymous-struct changes into `resolved_member_changes`. What remains in `modified` is real: renamed/added named fields, size changes, new enum values. Still sanity-check against `resolved_member_changes` for the bits. - Exports differing only by ordinal/decoration are usually not meaningful. - Syscall renumbering with no name change is a rebuild artifact (see `$SKILL_DIR/references/windows-internals.md` §3). ### 4. Interpret with Windows internals knowledge — the core of the analysis For every meaningful addition, infer **what it is and why it matters**. Do not just relay names. Read `$SKILL_DIR/references/windows-internals.md` for the reasoning toolkit: API prefixes (`Nt`/`Zw`/`Ps`/`Ke`/`Mm`/`Ob`/`Se`/`Cm`/`Alpc`/`Etw`/`Ci`/`Bcrypt`), naming patterns for mitigations, the structures where security flags live (`_PS_MITIGATION_OPTIONS`, `_KPROCESS`/`_EPROCESS` flag bitfields, `_SEP_TOKEN_*`, CI policy structs), and — equally important — the **non-mitigation** security surface: kernel notification/callback registration, ETW providers and the `EtwTi` threat-intelligence channel, ELAM/AMSI, PPL and anti-tamper, minifilter hooks, and entirely new drivers/modules. Read `$SKILL_DIR/references/windows-components.md` for per-binary roles. Mitigations are only one of several things worth surfacing. Cast a wide net for any new security-relevant **feature or component** and frame it for whichever of these audiences it serves — `$SKILL_DIR/references/windows-internals.md` §7 maps the signals: - **Anti-malware / EDR developers** — new ETW providers/events (especially `EtwTi*` / Microsoft-Windows-Threat-Intelligence), new `Ps`/`Ob`/`Cm` notification callbacks, AMSI/ELAM, scanning/notification hooks: new visibility they can consume, or blind spots Microsoft closed. - **Anti-cheat developers** — process protection (PPL signers), anti-tamper, handle/object hardening, integrity and VBS/HVCI surface, registry/handle monitoring: primitives for protecting a game or detecting cheats. - **Vulnerability researchers** — new syscalls/IOCTLs, new parsing surface, new drivers/components, widened structs, callback registration reachable from low privilege: fresh attack surface and exploit primitives (added or removed). For each finding, aim to state: the prefix/component it belongs to, the subsystem it touches, a concrete hypothesis about the feature/mitigation/component it implements, the security angle (new attack surface, hardening, telemetry, exploit primitive added/removed), and **which audience(s) should care and why**. Flag uncertainty honestly — "likely", "consistent with" — and suggest how a researcher could confirm (reverse the routine, check public symbols, diff the disassembly). ### 5. Write the report Use the structure in `$SKILL_DIR/references/report-template.md`. Lead with the highest-signal security findings (new syscalls, mitigation flags, new ETW/callback surface, new components), not an alphabetical dump. Group related symbols by component and feature. Every nontrivial item gets an interpretation, not just a name, and a note on which audience (EDR / anti-cheat / vuln research) it matters to. The report includes a dedicated section for security-relevant features and components beyond mitigations so EDR and anti-cheat findings aren't buried. ## Quick reference - `$SKILL_DIR/scripts/make_config.py` — build a minimal WinDiff config for the two versions - `$SKILL_DIR/scripts/windiff_diff.py` — diff one binary across two OS suffixes (JSON + summary) - `$SKILL_DIR/references/windows-internals.md` — prefixes, mitigation structures, how to infer intent - `$SKILL_DIR/references/windows-components.md` — role of each tracked binary - `$SKILL_DIR/references/report-template.md` — the report format
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.