Skip to content

About

Map Windows threads to their Win32 start address and owning module — user-mode, read-only, no debugger, no dependencies

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

win-threadmap

ci

Map every thread of a Windows process to its Win32 start address and the module that owns it — user-mode, read-only, no debugger, no dependencies.

$ python -m winthreadmap.cli --pid 4242 --duration 30

start              where                               kind     hits tids  first   last
0x7FFAE60B6A90     ntdll.dll+0x76A90                   module      61    1      0   18300
0x7FFAE4521B20     KERNELBASE.dll+0x21B20              module      60    4      0   18300
0x1F2A3B4C5D00     appcore.dll+0x1BD00                 module      31    2    902   17940
...

Why

NtQueryInformationThread(ThreadQuerySetWin32StartAddress) returns the exact lpStartAddress a thread was created with — the function the thread began executing, not where it happens to be now. Mapping those addresses to modules answers questions debuggers make awkward:

  • Thread triage — "what is spawning all these threads, and from where?" (worker pools, plugins, leaked thread-per-request patterns)
  • Bloat / attack-surface review — which DLLs registered threads in a process (injectors, overlays, telemetry, AV shims)
  • Black-box software study — watch a running process create its thread population over time, with a per-thread first-seen timeline, without attaching anything to it

The queries are plain reads (OpenThread/NtQueryInformationThread, OpenProcess/EnumProcessModulesEx, VirtualQueryEx). No debug object is created, nothing is written to the target.

Install

None. Windows 10/11, Python 3.9+, standard library only.

git clone <this repo> && cd win-threadmap
python -m unittest discover -s tests      # 8 tests, spawns a throwaway python child

Usage

usage: winthreadmap [-h] (--pid PID | --exe EXE) [--launch LAUNCH]
                    [--duration SECONDS] [--interval-ms MS] [--wait SECONDS]
                    [--rescan-modules-every N] [--out DIR] [--max-rows N]
  • --pid 1234 — attach to a running process right now
  • --exe notepad — wait (up to --wait, default 60 s) for a process whose image name starts with the prefix, then poll it
  • --launch path\app.exe --exe app — start a program and capture its threads from the very first poll
  • --duration 30 — how long to poll (default 30 s)
  • --interval-ms 300 — poll cadence (default 300 ms)
  • --out threadmaps/ — a JSON report with every unique start address is written here next to the console table

Rows are sorted by hit count; first/last are milliseconds since capture start, so the timeline of thread creation is visible even for short-lived threads you never saw in Task Manager.

ETW companion (winthreadmap/etw.py)

Threads that start and finish between two polls are invisible to the polling mapper. The companion captures the same information kernel-side with the built-in NT Kernel Logger session (THREAD + IMAGE_LOAD events), which sees every thread creation regardless of poll cadence:

# elevated prompt
python -m winthreadmap.etw --launch "path\app.exe" --exe app --duration 90 \
       --traceevent-tool path\to\your\traceevent-decoder.exe

It only drives logman around the target and stops cleanly; decoding the ETL is delegated to any TraceEvent-based tool you pass via --traceevent-tool (one is a ~40-line C# program — see the TraceEvent samples). Windows-build note: kernel event payload layouts vary between builds; on the builds tested (26100/26200-class), Win32StartAddress sits at payload offset 48 in the thread-start event. Sanity-check that offset against a process with known thread origins before trusting a decoder's addresses.

Limitations

  • Needs PROCESS_QUERY_INFORMATION | PROCESS_VM_READ on the target for the module map; elevated targets require an elevated console (thread start addresses need only THREAD_QUERY_*, which survives partial access).
  • Windows-build quirk (verified on build 26200): opening a thread with THREAD_QUERY_INFORMATION | THREAD_QUERY_LIMITED_INFORMATION succeeds, but NtQueryInformationThread(ThreadQuerySetWin32StartAddress) still returns STATUS_ACCESS_DENIED — even on the caller's own child process. The query needs THREAD_ALL_ACCESS on this build. winthreadmap handles this automatically: it opens narrow first, then escalates on denial. For foreign processes with hardened ACLs the escalation may fail; running from an elevated console usually resolves it.
  • Processes with more than 2048 modules truncate the module list.
  • Start addresses of threads created before the module they live in was unloaded can only be classified by memory-region type (private/mapped), not by name.
  • Polling sees a thread only if it exists at a poll tick; use the ETW companion for complete coverage.

License

MIT — see LICENSE.

About

Map Windows threads to their Win32 start address and owning module — user-mode, read-only, no debugger, no dependencies

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages