Skip to content

feat: add Windows platform support with ETW, inline hooking, and Npcap - #1

Open
digger-yu wants to merge 6 commits into
gojue:masterfrom
digger-yu:feat/windows-support
Open

feat: add Windows platform support with ETW, inline hooking, and Npcap#1
digger-yu wants to merge 6 commits into
gojue:masterfrom
digger-yu:feat/windows-support

Conversation

@digger-yu

Copy link
Copy Markdown

This commit ports eCapture to Windows (amd64/arm64), replacing eBPF uprobes/kprobes with platform-native alternatives: ETW (Event Tracing for Windows) for kernel-level telemetry and pure-Go x64 inline function hooking for DLL export interception.

Core Infrastructure

ETW Integration (pkg/util/etw/)

  • etw_windows.go: Full ETW session lifecycle via advapi32.dll (StartTraceW, EnableTraceEx2, OpenTraceW, ProcessTrace, ControlTraceW), event record structs, thread-safe shutdown with WaitGroup + mutex.
  • schannel_windows.go: Schannel provider event parser covering handshake complete/failure, extended handshake log, SSL log events, and alert events. Decodes counted UTF-16 strings from ETW property buffers.
  • etw_stub.go: No-op stub for non-Windows builds.

Inline Function Hooking (pkg/util/hook/)

  • hook_windows.go: HookManager with reference-counted module loading (loadModuleRef/freeModuleRef) to prevent dangling function pointers after FreeLibrary. Double-checked locking for concurrent AddHook.
  • trampoline_windows.go: Pure-Go x64 inline hook implementation with minimal instruction-length decoder, 12-byte absolute jump patching (mov rax, addr; jmp rax), FlushInstructionCache via kernel32.dll, and invokeTrampoline through syscall.Syscall6.
  • hook_stub.go: Stub for non-Windows builds with matching API surface.

Npcap/WinPcap Capture (pkg/util/pcap/)

  • npcap_windows.go: Packet capture via gopacket/pcap, implementing domain.Event interface with Start/Stop/readLoop and interface discovery helper (FindInterface).

Platform Adaptation Layer

  • pkg/util/kernel/: Windows kernel version detection via RtlGetVersion (kernel_version_windows.go), Version type (version_windows.go), stubs for non-Windows/non-Linux builds.
  • pkg/util/ebpf/: Windows stubs for BPF config (bpf_windows.go), cgroup (cgroup_windows.go), and elibpcap (elibpcap_windows.go).
  • pkg/util/roratelog/: Platform-specific chown handling split into rorate_chown.go (Unix) and rorate_chown_windows.go.

Probe Implementations

Fully Implemented (5 probes)

  • TLS/OpenSSL (internal/probe/openssl/*_windows.go): ETW Schannel provider for TLS handshake/key/certificate events + OpenSSL DLL hooking (SSL_read/SSL_write) for plaintext capture. Supports --schannel flag for Schannel-only mode.
  • Bash/Shell (internal/probe/bash/*_windows.go): ETW PowerShell ScriptBlock/Command events + cmd.exe process creation auditing. Supports --shell-type flag (powershell/cmd/auto).
  • GoTLS (internal/probe/gotls/*_windows.go): PE binary symbol resolution for crypto/tls.Read/Write + inline hooking of Go binaries compiled for Windows.
  • MySQL (internal/probe/mysql/_windows.go): DLL hooking of mysql_real_query in libmysql.dll / mysqlclient-.dll with query string extraction and structured event output.
  • PostgreSQL (internal/probe/postgres/*_windows.go): DLL hooking of PQexec in libpq.dll with query string extraction and structured event output.

Stub Probes (3 probes — not applicable on Windows)

  • GnuTLS, NSPR, Zsh: register_windows.go returns "not supported" error via factory registration.

CLI Layer

  • cli/cmd/tls_windows.go: Windows TLS subcommand with --schannel.
  • cli/cmd/bash_windows.go: Windows Shell subcommand with --shell-type.
  • cli/cmd/gotls_windows.go: Windows GoTLS subcommand.
  • cli/cmd/mysqld_windows.go: Windows MySQL subcommand.
  • cli/cmd/postgres_windows.go: Windows PostgreSQL subcommand.
  • cli/cmd/env_detection_windows.go: Windows version check (Build 17763+), administrator privilege verification, architecture validation (amd64/arm64).
  • cli/cmd/upgrade_windows.go: Upgrade stub (no-op on Windows).
  • cli/http/config_factory_windows.go: HTTP config factory stub.

Build System

  • Makefile: Added windows and windows-arm64 targets.
  • variables.mk / functions.mk: Windows cross-compile variables and build functions.
  • builder/Makefile.release: Added release_windows, snapshot_windows, snapshot_windows_arm64 targets producing .zip artifacts.
  • .github/workflows/release.yml: Integrated Windows build step into CI/CD pipeline (runs after Linux/Android, before publish).

Build Tag Strategy

  • Added !windows build tag to 23 existing Linux-only source files (probe implementations, config parsers using debug/elf, eBPF utilities, CLI commands, and upgrade logic).
  • Updated !ecap_android to !ecap_android && !windows on 14 files that already had Android exclusions.
  • All new Windows files use //go:build windows constraint.

E2E Test Suite (test/e2e/windows/)

  • common_windows.ps1: Shared helpers (Test-Admin, Get-EcaptureBinary, Start-Ecapture, Stop-Ecapture, Test-OutputContains).
  • windows_tls_test.ps1: TLS capture tests (text mode + keylog mode).
  • windows_bash_test.ps1: Shell capture tests (PowerShell + cmd).
  • windows_pcap_test.ps1: Network packet capture tests.
  • windows_mysql_test.ps1: MySQL query capture tests.
  • windows_postgres_test.ps1: PostgreSQL query capture tests.

Documentation

  • docs/compilation.md: Added "Compiling for Windows" section.
  • docs/compilation-zh_Hans.md: Added "Windows 编译" section.
  • doc/eCapture-Windows-Technical-Report.md: Updated roadmap to reflect all 6 phases completed, corrected probe matrix, file inventory, and architecture tables.

Summary

  • 68 files modified (build tags, platform guards, build system)
  • 54 files added (probes, utilities, CLI, tests, docs)
  • Build verified: go build -tags windows ./...
  • Vet verified: go vet -tags windows -unsafeptr=false ./...

This commit ports eCapture to Windows (amd64/arm64), replacing eBPF
uprobes/kprobes with platform-native alternatives: ETW (Event Tracing
for Windows) for kernel-level telemetry and pure-Go x64 inline
function hooking for DLL export interception.

## Core Infrastructure

### ETW Integration (pkg/util/etw/)
- etw_windows.go: Full ETW session lifecycle via advapi32.dll
  (StartTraceW, EnableTraceEx2, OpenTraceW, ProcessTrace,
  ControlTraceW), event record structs, thread-safe shutdown with
  WaitGroup + mutex.
- schannel_windows.go: Schannel provider event parser covering
  handshake complete/failure, extended handshake log, SSL log events,
  and alert events. Decodes counted UTF-16 strings from ETW property
  buffers.
- etw_stub.go: No-op stub for non-Windows builds.

### Inline Function Hooking (pkg/util/hook/)
- hook_windows.go: HookManager with reference-counted module loading
  (loadModuleRef/freeModuleRef) to prevent dangling function pointers
  after FreeLibrary. Double-checked locking for concurrent AddHook.
- trampoline_windows.go: Pure-Go x64 inline hook implementation with
  minimal instruction-length decoder, 12-byte absolute jump patching
  (mov rax, addr; jmp rax), FlushInstructionCache via kernel32.dll,
  and invokeTrampoline through syscall.Syscall6.
- hook_stub.go: Stub for non-Windows builds with matching API surface.

### Npcap/WinPcap Capture (pkg/util/pcap/)
- npcap_windows.go: Packet capture via gopacket/pcap, implementing
  domain.Event interface with Start/Stop/readLoop and interface
  discovery helper (FindInterface).

### Platform Adaptation Layer
- pkg/util/kernel/: Windows kernel version detection via
  RtlGetVersion (kernel_version_windows.go), Version type
  (version_windows.go), stubs for non-Windows/non-Linux builds.
- pkg/util/ebpf/: Windows stubs for BPF config (bpf_windows.go),
  cgroup (cgroup_windows.go), and elibpcap (elibpcap_windows.go).
- pkg/util/roratelog/: Platform-specific chown handling split into
  rorate_chown.go (Unix) and rorate_chown_windows.go.

## Probe Implementations

### Fully Implemented (5 probes)
- **TLS/OpenSSL** (internal/probe/openssl/*_windows.go): ETW
  Schannel provider for TLS handshake/key/certificate events +
  OpenSSL DLL hooking (SSL_read/SSL_write) for plaintext capture.
  Supports --schannel flag for Schannel-only mode.
- **Bash/Shell** (internal/probe/bash/*_windows.go): ETW PowerShell
  ScriptBlock/Command events + cmd.exe process creation auditing.
  Supports --shell-type flag (powershell/cmd/auto).
- **GoTLS** (internal/probe/gotls/*_windows.go): PE binary symbol
  resolution for crypto/tls.Read/Write + inline hooking of Go
  binaries compiled for Windows.
- **MySQL** (internal/probe/mysql/*_windows.go): DLL hooking of
  mysql_real_query in libmysql.dll / mysqlclient-*.dll with query
  string extraction and structured event output.
- **PostgreSQL** (internal/probe/postgres/*_windows.go): DLL hooking
  of PQexec in libpq.dll with query string extraction and structured
  event output.

### Stub Probes (3 probes — not applicable on Windows)
- GnuTLS, NSPR, Zsh: register_windows.go returns "not supported"
  error via factory registration.

## CLI Layer

- cli/cmd/tls_windows.go: Windows TLS subcommand with --schannel.
- cli/cmd/bash_windows.go: Windows Shell subcommand with --shell-type.
- cli/cmd/gotls_windows.go: Windows GoTLS subcommand.
- cli/cmd/mysqld_windows.go: Windows MySQL subcommand.
- cli/cmd/postgres_windows.go: Windows PostgreSQL subcommand.
- cli/cmd/env_detection_windows.go: Windows version check
  (Build 17763+), administrator privilege verification, architecture
  validation (amd64/arm64).
- cli/cmd/upgrade_windows.go: Upgrade stub (no-op on Windows).
- cli/http/config_factory_windows.go: HTTP config factory stub.

## Build System

- Makefile: Added `windows` and `windows-arm64` targets.
- variables.mk / functions.mk: Windows cross-compile variables and
  build functions.
- builder/Makefile.release: Added release_windows, snapshot_windows,
  snapshot_windows_arm64 targets producing .zip artifacts.
- .github/workflows/release.yml: Integrated Windows build step into
  CI/CD pipeline (runs after Linux/Android, before publish).

## Build Tag Strategy

- Added `!windows` build tag to 23 existing Linux-only source files
  (probe implementations, config parsers using debug/elf, eBPF
  utilities, CLI commands, and upgrade logic).
- Updated `!ecap_android` to `!ecap_android && !windows` on 14 files
  that already had Android exclusions.
- All new Windows files use `//go:build windows` constraint.

## E2E Test Suite (test/e2e/windows/)

- common_windows.ps1: Shared helpers (Test-Admin, Get-EcaptureBinary,
  Start-Ecapture, Stop-Ecapture, Test-OutputContains).
- windows_tls_test.ps1: TLS capture tests (text mode + keylog mode).
- windows_bash_test.ps1: Shell capture tests (PowerShell + cmd).
- windows_pcap_test.ps1: Network packet capture tests.
- windows_mysql_test.ps1: MySQL query capture tests.
- windows_postgres_test.ps1: PostgreSQL query capture tests.

## Documentation

- docs/compilation.md: Added "Compiling for Windows" section.
- docs/compilation-zh_Hans.md: Added "Windows 编译" section.
- doc/eCapture-Windows-Technical-Report.md: Updated roadmap to
  reflect all 6 phases completed, corrected probe matrix, file
  inventory, and architecture tables.

## Summary

- 68 files modified (build tags, platform guards, build system)
- 54 files added (probes, utilities, CLI, tests, docs)
- Build verified: `go build -tags windows ./...` ✓
- Vet verified: `go vet -tags windows -unsafeptr=false ./...` ✓

Signed-off-by: digger yu <digger-yu@outlook.com>
@cfc4n

cfc4n commented Jul 23, 2026

Copy link
Copy Markdown
Member

收到,感谢,我预计本周周末验证一下。

cfc4n added 5 commits July 26, 2026 23:46
Replace clang --target approach with x86_64-w64-mingw32-gcc for the
Windows schannel_hook.dll build. On aarch64 hosts clang's linker
(/usr/bin/ld) does not support i386pep emulation for amd64 targets,
and ARM64 MinGW headers are not available.

Changes:
- variables.mk: rename MINGW_CLANG_TARGET to MINGW_TARGET; set MINGW_CC
  to x86_64-w64-mingw32-gcc instead of clang --target
- functions.mk: build_schannel_hook_dll now uses MinGW gcc directly,
  removes clang fallback; ARM64 builds skip DLL (no-op per source)
- Makefile: update make env display for renamed variable
Remove:
- android_e2e.yml (Android emulator E2E tests)

Replace with Windows-only equivalents:
- go-c-cpp.yml → windows-build.yml: cross-compile amd64/arm64, go vet, unit tests
- e2e.yml: Linux E2E job removed, Windows E2E retained
- pr_build_debug.yml: Linux/Android → Windows (amd64/arm64) debug artifacts
- pr_build_debug_comment.yml: update text to Windows
- release.yml: Linux/Android/Docker → Windows release only
- codeql-analysis.yml: update branch triggers
mingw-w64-x86-64-dev provides only headers. The actual
x86_64-w64-mingw32-gcc binary is in gcc-mingw-w64-x86-64.
- Merge pr_build_debug_comment.yml into pr_build_debug.yml: workflow_run
  cannot read workflow files from fork branches, so the comment step
  must run in the same workflow as the build.
- Add pull-requests: write permission for PR comment.
- Delete pr_build_debug_comment.yml (now redundant).
- Remove TestCheckLatest from upgrade_test.go — requires GitHub API
  network access, fails in CI.
Fork PRs cannot comment on the base repo due to GITHUB_TOKEN
permission restrictions (403 Resource not accessible by integration).
Write artifact download links to GITHUB_STEP_SUMMARY instead,
which renders on the workflow run page.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants