Skip to content

Command Line Interface

Martin Drab edited this page Jan 24, 2021 · 7 revisions

Command Line Interface

Accessing IRPMon functionality through the GUI IRPMon.exe application is nice for those who like the manual approach, or are just used to programs like Process Monitor from SysInternals. Others may take advantage of the command-line interface implemented as the irpmonc.exe console application. Its functionality matches the GUI application with exception of request filters; they are simply not present.

More precisely, the console application is capable of the following tasks:

  • hooking and unhooking drivers and devices,
  • registering and unregistering driver name watches,
  • reading and modifying global driver settings,
  • retrieving requests (from the driver or a file) and sending them to other places (standard output or a file) in different formats (binary, text or JSON).

Specifying Input

The input is a place from where the application can retrieve requests in order to process them further. This can be a control device of the IRPMon driver (usually named \\.\IRPMon), an IP address and port where the IRPMon server service listents, or a binary log file generated previously. In the first two cases, it is also possible to hook or unhook drivers and devices, register or unregister driver name watches etc. If the file is specified, irpmonc just reads requests stored there and processes them.

Exactly one input must be specified. To do that, use the --input argument in one of the following ways:

  • --input=D:\\.\IRPMon connects to the IRPMon driver running on the local machine.
  • --input=N:IP:port attempts to connect to an instance of the IRPMon server listening at IP:port. Both IPv4 and IPv6 are protocols supported.
  • --input=L:C:\log\irpmon.log opens a log file C:\log\irpmon.log.

Specifying Outputs

irpmonc is capable of writting processed requests into multiple areas, called outputs, at the same time. Use the --output argument repeatedly to define all outputs. The syntax is

--output=B:<filename>
--output=J:<filename>
--output=T:<filename>

The output format is determined by the letter before the colon:

  • B stands for the IRPMon binary request format. Such a file can later be specified either as an input to another irpmonc instance, or can be opened in the IRPMon graphics application. No other format can do that.
  • T is a simple text format where each line contains one name-value pair. This format is easily readable by human users, however, is hardly useful for anything also.
  • J instructs irpmonc to output each request as a JSON object. One request is printed per line. This format is expected to be useful in some automatic post-processing.

To output to the standard output, specify - as file name. If no output is specified, irpmonc just does operations, such as driver (un)hooking and driver name watch (un)registration; it does not processes requests from the input.

Hooking Drivers and Devices

Hooking drivers can be done via the --hook-driver commands. As shown below, its capabilities are rather broad.

--hook-driver=[I][C][F][A][S][U][N][D][W][E][a]:<drivername>

Drivers are always hooked by their object names. Multiple letters may be specified before the colon, allowing to alter the following monitoring options:

  • IRPs (I),
  • IRP completions (C),
  • Fast I/O callbacks (F),
  • AddDevice callbacks for PnP drivers (A),
  • StartIo callback (S),
  • driver unload (U).
  • associate extra data with requests, i,e. bytes being read or written (D).

Use a to hook all devices currently managed by the target driver. To monitor only devices newly created by the driver in the future, specify N. The E character causes a device extension-based hook, rather than standard IRP one which may bypass Patchguard.

If the target driver is not loaded yet, you may specify W. In that case, a driver name watch is registered and the driver is hooked when its presence is detected.

Use the --unhook-driver command to unhook a driver. To unregister a driver name watch, specify the W character.

--unhook-driver=[W]:<drivername>

Commands for hooking and unhooking individual devices have the same syntax. You must specify either A or N to determine whether irpmonc should search for the target device by its name or address.

--hook-device=<A|N>:<devicename|address>
--unhook-device=<A|N>:<devicename|address>

Keep in mind that it is possible to hook a device object only if its parent driver is also hooked. irpmonc always hooks drivers before attempting to hook any device directly. Also, when a driver is unhooked, all its devices are automatically unhooked as well.

Global Driver Settings

Most of the global settings are of boolean type. To change a setting, specify the following on the command line:

--setting=<0|no|false|1|yes|true>

Use 1, yes or true to change the boolean value to true and 0, no or false to set it to false. The following table lists all available settings. They are specified without the -- prefix.

Setting Description
clear-on-disconnect Clear the driver event queue after disconnecting it.
process-events Report process creating, terminating and PE image loads.
file-object-events Report mappings between file objects and their names in order to track file names accross multiple operations.
snapshot-events Report new driver and device objects detected by the driver.
strip-data Truncate data associated with individual requests up to a limit specified by the --strip-threshold=<sizeinbytes> parameter.
boot-log Enable boot logging. You also may need to change the start type of the driver service (irpmndrv) to appropriate value. irpmonc does not do that.
save-settings Instructs the driver to save new settings into registry to preserve them accross system reboots or driver unloads.

Global driver settings are automatically displayed by irpmonc on the standard error output during its startup, unless a file-based input is specified.

Example

General

For Users-Developers

Tutorial

Public API

Functions

Types

Clone this wiki locally