Impacket reg.py
Back to the category index / Back to the command index
Overview
Section titled “Overview”Uses Remote Registry RPC to query, modify, and save registry data and to back up the SAM, SYSTEM, and SECURITY hives.
| Item | Details |
|---|---|
| Implementation | examples/reg.py |
| Category | Secrets / DPAPI / registry / file analysis |
| Size | 703 lines |
| Distribution | Installed as a script through scripts=examples/*.py in setup.py |
CLI and input
Section titled “CLI and input”Run python examples/reg.py -h for the current option definitions.
Subcommands: query, add, delete, save, backup
| Argument | Description |
|---|---|
target | [[domain/]username[:password]@] |
-debug | Enable debug output |
-ts | Add a timestamp to each log message |
-keyName | Full subkey path, including a valid root key; local root keys: HKLM, HKU, HKCU, HKCR; required |
-v | Value name to query; if omitted, return all value names under -keyName |
-ve | Query the default value or an empty value name |
-s | Query all subkeys and value names recursively |
-vt | Value type to set (default: REG_SZ; types: REG_NONE, REG_SZ, REG_EXPAND_SZ, REG_BINARY, REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_LINK, REG_MULTI_SZ, REG_QWORD) |
-vd | Registry value data to set; for REG_MULTI_SZ, specify this option once per line (may be repeated) |
--persistent | Keep the created key through reboot; by default, create a volatile key |
-va | Delete all values under the key |
-o | Output UNC path where the target must save registry exports; required |
-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 |
-target-ip | Target machine IP address; if omitted, use the target value. Useful when a NetBIOS target name cannot be resolved |
-port | Destination SMB server port (choices: 139, 445; default: 445) |
Detailed processing flow
Section titled “Detailed processing flow”The tool connects to the winreg endpoint over SMB/RPC. If RemoteRegistry is stopped, it temporarily changes its startup state through SCMR. The subcommand opens hive or key handles, converts value types, enumerates recursively, or saves data. On exit, it closes handles and restores the service state if needed.
How it works
Section titled “How it works”Remote Registry operations use the winreg RPC interface, but the target service
may be stopped. RemoteOperations reads the current RemoteRegistry startup mode
and state through SCMR, then enables and starts it temporarily only if needed.
It separates service preparation from registry actions so it can restore the original state on exit.
RegHandler resolves the root hive and key path. query enumerates subkeys and
values and decodes them by type; add and delete create or remove keys and values.
Conversion from CLI text to wire values differs for REG_SZ, DWORD, binary, and
multi-string data. save calls the server-side hive save API, so target paths and
permissions matter, unlike local file output.
backup takes a consistent set of SAM, SYSTEM, and SECURITY hives through a special path.
Close key and service handles regardless of whether an action succeeds, and restore
RemoteRegistry if it was started, unless --persistent is specified. Even if an
access denial interrupts a recursive query, distinguish retrieved branches from the failed key.
Key implementation elements
Section titled “Key implementation elements”| Symbol | Location | Where to trace its responsibility |
|---|---|---|
RemoteOperations | 50 | __init__(), getRRP(), connectWinReg(), enableRegistry(), finish() |
RegHandler | 139 | __init__(), connect(), run(), triggerWinReg(), save(), query(), add(), delete() |
Dependencies
Section titled “Dependencies”Within Impacket
Section titled “Within Impacket”| Module | Main names used |
|---|---|
impacket | version |
impacket.dcerpc.v5 | rpcrt, rrp, scmr, transport |
impacket.examples | logger |
impacket.examples.utils | parse_target |
impacket.system_errors | ERROR_NO_MORE_ITEMS |
impacket.structure | hexdump |
impacket.winregistry | format_multi_sz |
impacket.smbconnection | SMBConnection, SessionError |
impacket.dcerpc.v5.dtypes | READ_CONTROL |
Output, side effects, and required privileges
Section titled “Output, side effects, and required privileges”- Some operations change the target’s state. Check the target name, SID, and path before making changes.
- Options may create or update local files. Check how existing files are handled and the permissions on output containing secrets.
- Some paths use temporary resources such as remote services, tasks, files, shares, and WMI/RPC resources. Cleaning them up after an abnormal exit is part of the behavior contract.
Failure paths and cleanup
Section titled “Failure paths and cleanup”- On failure, use protocol status codes to determine whether name resolution, connection, authentication, service state, or permissions caused the stop.
- Cleanup-related methods include
finish(). Check that new early returns and exception paths reach it too.
When changing the implementation
Section titled “When changing the implementation”The code depends on dcerpc.v5.rrp, scmr, transport, SMBConnection, and the registry value formatter. RemoteOperations handles the service lifecycle, while RegHandler handles actions.
Verification
Section titled “Verification”- Syntax:
python -m py_compile examples/reg.py - CLI:
python examples/reg.py -h - Related test:
tests/misc/test_winregistry.py - Related test:
tests/misc/test_dcerpc_v5_ndr.py - Related test:
tests/misc/test_structure.py