wtrace

wtrace

---

:warning: Some antivirus engines mark wtrace as malware/virus :warning:

Those are false-positives. As you know, wtrace source code is open, and all the officially released binaries are built using GitHub Actions (you may check the workflow in the release.yml file). If your antivirus thinks that wtrace is malware, calculate the binary checksum, and if it matches the one on the release page, please report it as false-positive. Thank you!

---

Table of contents:

• Introduction
• Installation
• Tracing targets
  • System-only (-s)
  • System-wide
  • A single process (optionally, with child processes)
• Filtering events
• Event handlers
• RPC
• Error messages
  • WARNING: the session did not finish in the allotted time.
  • WARNING: … events were lost in the session.
  • Other issues
• Thanks

Introduction

Wtrace [spelled: wɪtreɪs] is a command-line tool for recording trace events from the Operating System or a group of processes. Wtrace may collect, among others, File I/O and Registry operations, TPC/IP connections, and RPC calls. Its purpose is to give you some insights into what is happening in the system.

Additionally, it has various filtering capabilities and may also dump statistics at the end of the trace session. As it's just a standard command-line tool, you may pipe its output to another tool for further processing.

The available options are listed below:

…

If the command-line argument is not a number, wtrace tries to start the process with arguments that follow the executable path.

# Start and trace the opening of the test.txt file by notepad.exe
wtrace notepad c:\temp\test.txt

Filtering events

We may define an event filter with the -f/--filter option. The filter is built from a keyword, an operator, and a value. The keyword represents an event field and must be one of the following values:

• pid - the process ID (useful in system-wide tracing)
• pname - the process name
• name - the event name
• level - the event level (debug [5], info [4], warning [3], error [2], critical [1])
• path - the event path
• details - the event details

The operators are the same for numeric and text values and include: =, <>, =, ~. For numbers, the ~ operator has the same effect as the = operator. For text fields, the >= operator returns true if the field value starts with a given text value. Consequently, the = d:\temp”

Trace a process with id 12572 and its children and show only TCP/IP events

wtrace -f "name >= tcp" -c 12572

…

Trace only registry and tcp events system-wide

wtrace --handlers registry,tcp

## RPC

Wtrace displays the endpoint name, the interface ID, and the procedure index, for example:

14:14:53.3295 firefox (12572.21620) RPC/ClientCallEnd 'fb8a0729-2d04-4658-be93-27b4ad553fac (lsapolicylookup) [5]' -> SUCCESS

Thanks to the [NtApiDotNet](https://www.nuget.org/packages/NtApiDotNet) library, wtrace may resolve RPC procedure names in the summary view. To make it work, make sure the image handler is enabled and you have symbols configured for the wtrace session. If you have the `_NT_SYMBOL_PATH` environment variable set (I highly recommend configuring it), wtrace will use it. Otherwise, you need to set debugging symbols path through the `--symbols` parameter, for example:

wtrace.exe --symbols="SRV*C:\symbols*https://msdl.microsoft.com/download/symbols" -v notepad.exe

If RPC procedure name resolution worked, you should see a procedure name in the curly braces, next to the procedure number:

---

   RPC (client calls)

---

fb8a0729-2d04-4658-be93-27b4ad553fac (ncalrpc:[lsapolicylookup]) [5]{LsaLookuprGetDomainInfo} calls: 2

## Error messages

### WARNING: the session did not finish in the allotted time.

This warning may indicate a problem with ETW session handling. If it happens, the wtrace ETW session might still be running in your system. You may stop it using the logman tool:

logman stop wtrace-rt -ets

### WARNING: … events were lost in the session.

This warning usually indicates that the number of events was too high, and wtrace could not process them. In such a case, add some additional filters to the command line or disable the unneeded handlers.

### Other issues

If you find an error in wtrace, please [report it on GitHub](https://github.com/lowleveldesign/wtrace/issues), providing the error message and steps to reproduce the problem. Thank you!

## Thanks

I would like to thank the authors of the [TraceEvent](https://github.com/Microsoft/perfview) and [NtApiDotNet](https://github.com/googleprojectzero/sandbox-attacksurface-analysis-tools) libraries. Wtrace would not exist without those libraries.