Impacket wmipersist.py

Back to the category index / Back to the command index

Overview

Creates or deletes WMI event filters, consumers, and bindings to run VBScript when an event occurs.

Item	Details
Implementation	`examples/wmipersist.py`
Category	Remote execution / WMI / services
Size	246 lines
Distribution	Installed as a script through `scripts=examples/*.py` in `setup.py`

CLI and input

Run python examples/wmipersist.py -h for the current option definitions.

Subcommands: install, remove

Argument	Description
`target`	[domain/][username[:password]@]
`-debug`	Enable debug output
`-ts`	Add a timestamp to each log message
`-com-version`	DCOM version in MAJOR_VERSION:MINOR_VERSION format, for example 5.7
`-name`	Event name; required
`-vbs`	VBS file containing the script to run; required
`-filter`	WQL filter string that triggers the script
`-timer`	Milliseconds before the script is triggered
`-hashes`	NTLM hashes in LMHASH:NTHASH format
`-no-pass`	Do not prompt for a password (useful with `-k`)
`-k`	Use Kerberos authentication. Look for matching credentials in the ccache file named by `KRB5CCNAME`; if none are valid, use those specified on the command line
`-aesKey`	AES key for Kerberos authentication (128 or 256 bits)
`-dc-ip`	Domain controller IP address; if omitted, use the domain name (FQDN) from the target parameter

Detailed processing flow

The tool connects to root\subscription through DCOM/WMI. install creates a named event filter, ActiveScript consumer, and binding between them, rolling back objects it has created if an operation fails. remove finds and deletes the associated objects by name.

How it works

A permanent WMI event subscription consists of three objects: an __EventFilter describing the event condition, a consumer holding the action to run, and a binding linking them. This command connects to the root\subscription namespace, creates all three with install, and finds and deletes objects linked to the same name with remove.

A filter contains a WQL event query or timer reference, while the consumer stores VBScript text. Until the binding is created, the filter and consumer are unconnected, so a failure midway may leave orphaned objects. Consider rollback in reverse creation order, and do not delete another subscription if its name collides.

A permanent subscription remains in the repository after the command process exits. Success therefore means the consumer can run whenever the trigger condition is met in the future, rather than that the script ran once. Check the filter query syntax, namespace, consumer engine availability, and references left after deletion separately.

Key implementation elements

Symbol	Location	Where to trace its responsibility
`WMIPERSISTENCE`	64	`__init__()`, `checkError()`, `run()`

Dependencies

Within Impacket

Module	Main names used
`impacket.examples`	`logger`
`impacket.examples.utils`	`parse_target`
`impacket`	`version`
`impacket.dcerpc.v5.dcomrt`	`COMVERSION`, `DCOMConnection`
`impacket.dcerpc.v5.dcom`	`wmi`
`impacket.dcerpc.v5.dtypes`	`NULL`
`impacket.dcerpc.v5.dcom.wmi`	`WBEMSTATUS`

Output, side effects, and required privileges

Some operations change the target’s state. Check the target name, SID, and path before making changes.

Failure paths and cleanup

On failure, use protocol status codes to determine whether name resolution, connection, authentication, service state, or permissions caused the stop.

When changing the implementation

The code depends on dcerpc.v5.dcomrt and dcom.wmi; WMIPERSISTENCE.run() handles actions. Change the lifecycle of the three objects, name collisions, and rollback together.

Verification

Syntax: python -m py_compile examples/wmipersist.py
CLI: python examples/wmipersist.py -h
Related test: tests/SMB_RPC/test_wmi.py
Related test: tests/dcerpc/test_dcomrt.py