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
...
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.
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: 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.
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.
- Needs
PROCESS_QUERY_INFORMATION | PROCESS_VM_READon the target for the module map; elevated targets require an elevated console (thread start addresses need onlyTHREAD_QUERY_*, which survives partial access). - Windows-build quirk (verified on build 26200): opening a thread with
THREAD_QUERY_INFORMATION | THREAD_QUERY_LIMITED_INFORMATIONsucceeds, butNtQueryInformationThread(ThreadQuerySetWin32StartAddress)still returnsSTATUS_ACCESS_DENIED— even on the caller's own child process. The query needsTHREAD_ALL_ACCESSon this build.winthreadmaphandles 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.
MIT — see LICENSE.