Skip to content

README.md

Latest commit

 

History

History
333 lines (243 loc) · 9.92 KB

README.md

File metadata and controls

333 lines (243 loc) · 9.92 KB
Raw

KN Win32 API Monitor

KN Win32 API Monitor screenshot

KN Win32 API Monitor is a modern Windows 10/11 API monitoring workstation for security engineering, reverse engineering, debugging, and anti-cheat research.

The project is inspired by Rohitab API Monitor, but the implementation is being rebuilt around a modern desktop UI, explicit native helper contracts, durable capture artifacts, and generated API definition metadata.

What It Does

  • Launches supported targets and injects the monitoring agent through the controlled early-bird APC path.
  • Attaches to already-running same-bitness, non-protected targets through the native helper path.
  • Captures API calls through native IAT hooks and shared-memory event transport.
  • Supports dynamic loader and resolver coverage for loaded modules, GetProcAddress, and LdrGetProcedureAddress.
  • Stores durable .knapm replay sessions and supports target-free validation, replay, catalog indexing, trace indexing, and full-text trace search.
  • Provides a Tauri 2 + React/TypeScript desktop UI for target selection, launch/attach control, trace browsing, filtering, highlighting, timeline views, replay, and catalog/search workflows.
  • Uses generated API definition metadata for module/API IDs, groups, argument labels, decode aliases, enum/flag rendering, and coverage reporting.

Current Coverage

The current definition and hook pipeline reports:

  • Microsoft-source inventory candidates: 30,182
  • Defined APIs: 30,112
  • Compiled manual hooks available on x86/x64: 314
  • Additional compiler-bound typed wrappers on x86/x64: 6 (total 320)
  • Generic generated wrappers enabled: 0 (unverified ABI contracts are blocked)
  • Differential-verified APIs: 6, scoped to the recorded x86/x64 Debug corpus
  • Data exports included as monitor targets: 0
  • Parameter metadata rows: 226,700
  • Parameters missing decode metadata: 0
  • API families: 62
  • API categories/groups: 476
  • Runtime support source: generated/runtime-support.json, shared by the generator, native selection policy, Agent, and UI
  • Dynamic resolver substitution is restricted to the same compiled subset

The executed comparison corpus records actual x86/x64 original, KN Monitor, Frida and private ETW runs with source/binary hashes, semantic comparisons and caller-measured latency/RSS. Its scope and unverified platforms are explicit; it does not establish a general competitive ranking.

Catalog definitions do not imply safe runtime support. Opaque prototypes, variadic calls, aggregates, and unresolved typedefs cannot use the old integer dispatcher. Explicit unsupported selections fail before injection; module selectors select only the compiled subset. ARM64 and ARM64EC are unsupported. Manual hook availability does not certify semantic equivalence. Promotion needs compiler-checked typed contracts and uninstrumented/instrumented comparisons.

Dynamic resolver substitution means a monitored GetProcAddress or LdrGetProcedureAddress call can return a KN monitor wrapper instead of the raw target function pointer when the requested API name is present in the runtime hook table. Ordinal resolver lookups are classified for audit, but are not substituted until ordinal metadata is added.

Architecture

apps/knmon-ui/          Tauri + React workstation UI
crates/knmon-tauri/     Rust command layer
native/                 C++20 helper, collector, controller, and agent code
contracts/              Versioned JSON contracts
definitions/            API definitions and metadata registries
generated/              Deterministic generated API/decoder/hook artifacts
docs/                   Architecture and design notes
samples/                Controlled sample targets
tools/                  Validators, generators, importer, and smoke tests
tests/                  Test and validation assets

The native path is intentionally explicit:

  1. The helper owns process launch, attach, preflight, cancellation, and session lifecycle.
  2. The injected agent keeps hot-path work compact and writes API events through shared memory.
  3. The host-side collector drains committed transport records, decodes metadata, writes sessions, and reports drop/overhead counters.
  4. Replay, catalog indexing, and trace indexing validate/read .knapm data without launching targets or reinjecting agents.

Safety Boundary

The supported native monitoring paths are currently same-bitness user-mode flows:

  • x64 helper -> x64 target -> knmon-agent64.dll
  • Win32 helper -> x86 target -> knmon-agent32.dll

Cross-bitness injection, protected-process bypass, manual mapping, stealth loading, kernel-mode capture, skip-call, forced return values, memory editing, and broad inline detours are not enabled by default and require separate design review.

Data exports are excluded from the runtime monitoring target set because they are not callable APIs.

Prerequisites

  • Windows 10/11
  • Node.js 24.21.0 LTS for reproduction (supported: 22.18+, 24.x, 26.x)
  • Rust toolchain with Cargo
  • CMake 3.24 or newer
  • Visual Studio Build Tools with a C++20-capable MSVC toolchain
  • WebView2 runtime for Tauri desktop execution

Optional:

  • Win32/x86 MSVC components if you want to build the x86 helper/agent/target tree.

Install

Clone the repository and install JavaScript dependencies:

git clone https://github.com/kernullist/KnWin32ApiMonitor.git
cd KnWin32ApiMonitor
npm install

Configure and build the native x64 tree:

npm run native:configure
npm run native:build

Build the desktop UI:

npm run build

Or use the repository build script:

.\Build.ps1

Release builds preserve VERSION. To deliberately increment its fourth component, pass -BumpBuildVersion alongside -Release:

.\Build.ps1 -Release

Optional Win32/x86 native build:

cmake -S native -B build/native-win32 -A Win32
cmake --build build/native-win32 --config Debug

Run

Run the Tauri desktop app:

npm run tauri:dev

Run the browser/Vite UI only:

npm run dev

Browser/Vite mode is useful for UI work, but native launch/attach actions require the Tauri desktop runtime and built native helper binaries.

Use the root scripts when you want simple local app control:

.\Start-App.ps1
.\Stop-App.ps1

Source archives must contain hydrated Git LFS payloads. Run npm run source:check before building; a verified checkout can use npm run source:hydrate to fetch them. Use python tools/source/package-source.py --output dist/release/knmon-source.zip from a clean tracked checkout to produce a complete source ZIP with per-file hashes. Build inputs and the toolchain baseline are documented in the source build contract.

Native Helper Examples

List target processes:

build\native\Debug\knmon-native-helper.exe list-targets

Launch the controlled sample target:

build\native\Debug\knmon-native-helper.exe launch-sample

Run the broad API exerciser target for UI Launch/Attach validation:

build\native\Debug\knmon-api-exerciser.exe --once
build\native\Debug\knmon-api-exerciser.exe --api-exerciser --delay-ms 250

Capture the controlled sample target:

build\native\Debug\knmon-native-helper.exe capture-sample

Attach to an already-running supported same-bitness target:

build\native\Debug\knmon-native-helper.exe attach-capture --pid <pid> --duration-ms 3000

Write and validate a replayable session:

build\native\Debug\knmon-native-helper.exe capture-sample --write-session captures\latest-sample-fileio
build\native\Debug\knmon-native-helper.exe validate-session --session captures\latest-sample-fileio
build\native\Debug\knmon-native-helper.exe replay-session --session captures\latest-sample-fileio

Validation

Validate API definitions, generated decoder tables, inventory, plans, importer fixtures, and the runtime support policy gate:

npm run defs:validate

Regenerate definition artifacts when intentionally changing API metadata:

npm run defs:bulk-expansion
npm run defs:generate
npm run defs:inventory
npm run agent-hooks:generate

Run the core build checks:

npm run build
npm run native:build

Run the generic profile smokes used to verify the current broad hook table:

npm run tier1-generic:smoke
npm run tier2-generic:smoke

Run the broad API exerciser target smoke:

npm run api-exerciser:smoke

Run all available repository verification:

npm run verify

Additional focused native smokes are available under tools/native-smoke/.

Definition Reports

Print the current definition and inventory report:

npm run defs:coverage

Check generated agent hook coverage directly:

npm run agent-hooks:check

Expected current hook check:

Generated agent hook definitions. required=320 manual=314 typed=6 generated_generic=0 covered=320 chunks=0

Release Package

Create a ZIP package from existing Release build outputs:

.\Release.ps1

Include an already-built Win32/x86 native tree:

.\Release.ps1 -IncludeWin32

The ZIP is written under dist\release\. Extract it and run knmon-ui.exe from the extracted folder. The x64 native helper, agent, and collector binaries are copied beside the desktop executable so the app can run without repo-relative paths. Optional Win32/x86 binaries are copied under win32\.

License

KN Win32 API Monitor is licensed under the Apache License, Version 2.0. See LICENSE.

Design Docs