winappdbg.system

System settings.

class winappdbg.system.System

Interface to a batch of processes, plus some system wide settings. Contains a snapshot of processes.

Variables:

arch – Name of the processor architecture we’re running on. For more details see _get_arch().
bits – Size of the machine word in bits for the current architecture. For more details see _get_bits().
os – Name of the Windows version we’re runing on. For more details see _get_os().
wow64 – True if the debugger is a 32 bits process running in a 64 bits version of Windows, False otherwise.
pageSize – Page size in bytes. Defaults to 0x1000 but it’s automatically updated on runtime when importing the module.
registry – Windows Registry for this machine.

classmethod add_to_postmortem_exclusion_list(pathname, bits=None)

Adds the given filename to the exclusion list for postmortem debugging.

Warning

This method requires administrative rights.

See also

get_postmortem_exclusion_list()

Parameters:

pathname (str) – Application pathname to exclude from postmortem debugging.
bits (int) – Set to 32 for the 32 bits debugger, or 64 for the 64 bits debugger. Set to {None} for the default (System.bits).

Raises:

WindowsError – Raises an exception on error.

static adjust_privileges(state, privileges)

Requests or drops privileges.

Parameters:

state (bool) – True to request, False to drop.
privileges (list(int)) – Privileges to request or drop.

Raises:

WindowsError – Raises an exception on error.

classmethod drop_debug_privileges(bIgnoreExceptions=False)

Drops debug privileges.

This may be needed to avoid being detected by certain anti-debug tricks.

Parameters:: bIgnoreExceptions (bool) – True to ignore any exceptions that may be raised when dropping debug privileges.
Return type:: bool
Returns:: True on success, False on failure.
Raises:: WindowsError – Raises an exception on error, unless bIgnoreExceptions is True.

classmethod drop_privileges(*privileges)

Drops privileges.

Parameters:: privileges (int...) – Privileges to drop.
Raises:: WindowsError – Raises an exception on error.

classmethod enable_step_on_branch_mode()

When tracing, call this on every single step event for step on branch mode.

Raises:

WindowsError – Raises ERROR_DEBUGGER_INACTIVE if the debugger is not attached to least one process.
NotImplementedError – Current architecture is not i386 or amd64.

Warning

This method uses the processor’s machine specific registers (MSR). While this usage should be generally safe, it may fail under some special circumstances (for example with certain types of virtualization). In extremely old processors (circa 1995) using these registers may have occasionally cause a crash, but that’s no longer the case in modern processors.

static find_window(className=None, windowName=None)

Find the first top-level window in the current desktop to match the given class name and/or window name. If neither are provided any top-level window will match.

See also

get_window_at()

Parameters:

className (str) – (Optional) Class name of the window to find. If None or not used any class name will match the search.
windowName (str) – (Optional) Caption text of the window to find. If None or not used any caption text will match the search.

Return type:

Window or None

Returns:

A window that matches the request. There may be more matching windows, but this method only returns one. If no matching window is found, the return value is None.

Raises:

WindowsError – An error occured while processing this request.

static fix_symbol_store_path(symbol_store_path=None, remote=True, force=False)

Fix the symbol store path. Equivalent to the .symfix command in Microsoft WinDbg.

If the symbol store path environment variable hasn’t been set, this method will provide a default one.

Parameters:

symbol_store_path (str or None) – (Optional) Symbol store path to set.
remote (bool) –
(Optional) Defines the symbol store path to set when the symbol_store_path is None.

If True the default symbol store path is set to the Microsoft symbol server. Debug symbols will be downloaded through HTTP. This gives the best results but is also quite slow.

If False the default symbol store path is set to the local cache only. This prevents debug symbols from being downloaded and is faster, but unless you’ve installed the debug symbols on this machine or downloaded them in a previous debugging session, some symbols may be missing.

If the symbol_store_path argument is not None, this argument is ignored entirely.

force (bool) –

(Optional) If True the new symbol store path is set always. If False the new symbol store path is only set if missing.

This allows you to call this method preventively to ensure the symbol server is always set up correctly when running your script, but without messing up whatever configuration the user has.

Example:

from winappdbg import Debug, System

def simple_debugger( argv ):

    # Instance a Debug object
    debug = Debug( MyEventHandler() )
    try:

        # Make sure the remote symbol store is set
        System.fix_symbol_store_path(remote = True,
                                      force = False)

        # Start a new process for debugging
        debug.execv( argv )

        # Wait for the debugee to finish
        debug.loop()

    # Stop the debugger
    finally:
        debug.stop()

Return type:

str or None

Returns:

The previously set symbol store path if any, otherwise returns None.

static get_active_services()

Retrieve a list of all active system services.

Return type:: list of win32.ServiceStatusProcessEntry
Returns:: List of service status descriptors.

static get_desktop_window()

Return type:: Window
Returns:: Returns the desktop window.
Raises:: WindowsError – An error occured while processing this request.

classmethod get_file_version_info(filename)

Get the program version from an executable file, if available.

Parameters:

filename (str) – Pathname to the executable file to query.

Return type:

tuple(str, str, bool, bool, str, str)

Returns:

Tuple with version information extracted from the executable file metadata, containing the following:

File version number ("major.minor").
Product version number ("major.minor").
True for debug builds, False for production builds.
True for legacy OS builds (DOS, OS/2, Win16), False for modern OS builds.
Binary file type. May be one of the following values:
- ”application”
- ”dynamic link library”
- ”static link library”
- ”font”
- ”raster font”
- ”TrueType font”
- ”vector font”
- ”driver”
- ”communications driver”
- ”display driver”
- ”installable driver”
- ”keyboard driver”
- ”language driver”
- ”legacy driver”
- ”mouse driver”
- ”network driver”
- ”printer driver”
- ”sound driver”
- ”system driver”
- ”versioned printer driver”
Binary creation timestamp.

Any of the fields may be None if not available.

Raises:

WindowsError – Raises an exception on error.

static get_foreground_window()

Return type:: Window
Returns:: Returns the foreground window.
Raises:: WindowsError – An error occured while processing this request.

classmethod get_last_branch_location()

Returns the source and destination addresses of the last taken branch.

Return type:

tuple( int, int )

Returns:

Source and destination addresses of the last taken branch.

Raises:

WindowsError – Raises an exception on error.
NotImplementedError – Current architecture is not i386 or amd64.

Warning

This method uses the processor’s machine specific registers (MSR). While this usage should be generally safe, it may fail under some special circumstances (for example with certain types of virtualization). In extremely old processors (circa 1995) using these registers may have occasionally cause a crash, but that’s no longer the case in modern processors.

classmethod get_postmortem_debugger(bits=None)

Returns the postmortem debugging settings from the Registry.

See also

set_postmortem_debugger()

Parameters:: bits (int) – Set to 32 for the 32 bits debugger, or 64 for the 64 bits debugger. Set to {None} for the default (System.bits).
Return type:: tuple( str, bool, int )
Returns:: A tuple containing the command line string to the postmortem debugger, a boolean specifying if user interaction is allowed before attaching, and an integer specifying a user defined hotkey. Any member of the tuple may be None. See set_postmortem_debugger() for more details.
Raises:: WindowsError – Raises an exception on error.

classmethod get_postmortem_exclusion_list(bits=None)

Returns the exclusion list for the postmortem debugger.

See also

get_postmortem_debugger()

Parameters:: bits (int) – Set to 32 for the 32 bits debugger, or 64 for the 64 bits debugger. Set to None for the default (System.bits).
Return type:: list( str )
Returns:: List of excluded application filenames.
Raises:: WindowsError – Raises an exception on error.

static get_service(name)

Get the service descriptor for the given service name.

Parameters:: name (str) – Service unique name. You can get this value from the ServiceName member of the service descriptors returned by get_services() or get_active_services().
Return type:: win32.ServiceStatusProcess
Returns:: Service status descriptor.

static get_service_display_name(name)

Get the service display name for the given service name.

See also

get_service()

Parameters:: name (str) – Service unique name. You can get this value from the ServiceName member of the service descriptors returned by get_services() or get_active_services().
Return type:: str
Returns:: Service display name.

static get_service_from_display_name(displayName)

Get the service unique name given its display name.

See also

get_service()

Parameters:: displayName (str) – Service display name. You can get this value from the DisplayName member of the service descriptors returned by get_services() or get_active_services().
Return type:: str
Returns:: Service unique name.

static get_services()

Retrieve a list of all system services.

Return type:: list of win32.ServiceStatusProcessEntry
Returns:: List of service status descriptors.

static get_shell_window()

Return type:: Window
Returns:: Returns the shell window.
Raises:: WindowsError – An error occured while processing this request.

static get_top_level_windows()

Return type:: list[Window]
Returns:: Returns the top-level windows in the current desktop.
Raises:: WindowsError – An error occured while processing this request.

static get_window_at(x, y)

Get the window located at the given coordinates in the desktop. If no such window exists an exception is raised.

See also

find_window()

Parameters:

x (int) – Horizontal coordinate.
y (int) – Vertical coordinate.

Return type:

Window

Returns:

Window at the requested position. If no such window exists a WindowsError exception is raised.

Raises:

WindowsError – An error occured while processing this request.

static is_admin()

Return type:: bool
Returns:: True if the current user as Administrator privileges, False otherwise. Since Windows Vista and above this means if the current process is running with UAC elevation or not.

classmethod load_dbghelp(pathname=None)

Load the specified version of the dbghelp.dll library.

This library is shipped with the Debugging Tools for Windows, and it’s required to load debug symbols.

If you don’t specify the pathname, this method will try to find the location of the dbghelp.dll library despite Microsoft’s efforts to keep us from using it, since they keep moving it around…

This method can be useful for bundling dbghelp.dll in your scripts, so users won’t need to have the Microsoft SDK installed.

Example:

from winappdbg import Debug

def simple_debugger( argv ):

    # Instance a Debug object, passing it the event handler callback
    debug = Debug( my_event_handler )
    try:

        # Load a specific dbghelp.dll file
        debug.system.load_dbghelp("C:\\Custom install path\\dbghelp.dll")

        # Start a new process for debugging
        debug.execv( argv )

        # Wait for the debugee to finish
        debug.loop()

    # Stop the debugger
    finally:
        debug.stop()

Parameters:

pathname (str) – (Optional) Full pathname to the dbghelp.dll library. If not provided this method will try to autodetect it.

Return type:

ctypes.WinDLL

Returns:

Loaded instance of dbghelp.dll.

Raises:

NotImplementedError – This feature was not implemented for the current architecture.
WindowsError – An error occurred while processing this request.

static pause_service(name): Pause the service given by name.

Warning

This method requires UAC elevation in Windows Vista and above.

Note

Not all services support this.

See also

get_services(), get_active_services(), start_service(), stop_service(), resume_service()

static read_msr(address)

Read the contents of the specified MSR (Machine Specific Register).

Parameters:

address (int) – MSR to read.

Return type:

int

Returns:

Value of the specified MSR.

Raises:

WindowsError – Raises an exception on error.
NotImplementedError – Current architecture is not i386 or amd64.

Warning

This method uses the processor’s machine specific registers (MSR). While this usage should be generally safe, it may fail under some special circumstances (for example with certain types of virtualization). In extremely old processors (circa 1995) using these registers may have occasionally cause a crash, but that’s no longer the case in modern processors.

classmethod remove_from_postmortem_exclusion_list(pathname, bits=None)

Removes the given filename to the exclusion list for postmortem debugging from the Registry.

Warning

This method requires administrative rights.

Warning

Don’t ever delete entries you haven’t created yourself! Some entries are set by default for your version of Windows. Deleting them might deadlock your system under some circumstances.

For more details see: http://msdn.microsoft.com/en-us/library/bb204634(v=vs.85).aspx

See also

get_postmortem_exclusion_list()

Parameters:

pathname (str) – Application pathname to remove from the postmortem debugging exclusion list.
bits (int) – Set to 32 for the 32 bits debugger, or 64 for the 64 bits debugger. Set to {None} for the default (System.bits).

Raises:

WindowsError – Raises an exception on error.

classmethod request_debug_privileges(bIgnoreExceptions=False)

Requests debug privileges.

This may be needed to debug processes running as SYSTEM (such as services) since Windows XP.

Parameters:: bIgnoreExceptions (bool) – True to ignore any exceptions that may be raised when requesting debug privileges.
Return type:: bool
Returns:: True on success, False on failure.
Raises:: WindowsError – Raises an exception on error, unless bIgnoreExceptions is True.

classmethod request_privileges(*privileges)

Requests privileges.

Parameters:: privileges (int...) – Privileges to request.
Raises:: WindowsError – Raises an exception on error.

static resume_service(name): Resume the service given by name.

Warning

This method requires UAC elevation in Windows Vista and above.

Note

Not all services support this.

See also

get_services(), get_active_services(), start_service(), stop_service(), pause_service()

static set_kill_on_exit_mode(bKillOnExit=False)

Defines the behavior of the debugged processes when the debugging thread dies. This method only affects the calling thread.

Works on the following platforms:

Microsoft Windows XP and above.

Wine (Windows Emulator).

Fails on the following platforms:

Microsoft Windows 2000 and below.

ReactOS.

Parameters:: bKillOnExit (bool) – True to automatically kill processes when the debugger thread dies. False to automatically detach from processes when the debugger thread dies.
Return type:: bool
Returns:: True on success, False on error.

Note

This call will fail if a debug port was not created. That is, if the debugger isn’t attached to at least one process. For more info see: http://msdn.microsoft.com/en-us/library/ms679307.aspx

classmethod set_postmortem_debugger(cmdline, auto=None, hotkey=None, bits=None)

Sets the postmortem debugging settings in the Registry.

Warning

This method requires administrative rights.

See also

get_postmortem_debugger()

Parameters:

cmdline (str) – Command line to the new postmortem debugger. When the debugger is invoked, the first “%ld” is replaced with the process ID and the second “%ld” is replaced with the event handle. Don’t forget to enclose the program filename in double quotes if the path contains spaces.
auto (bool) – Set to True if no user interaction is allowed, False to prompt a confirmation dialog before attaching. Use None to leave this value unchanged.
hotkey (int) – Virtual key scan code for the user defined hotkey. Use 0 to disable the hotkey. Use None to leave this value unchanged.
bits (int) – Set to 32 for the 32 bits debugger, or 64 for the 64 bits debugger. Set to {None} for the default (System.bits).

Return type:

tuple( str, bool, int )

Returns:

Previously defined command line and auto flag.

Raises:

WindowsError – Raises an exception on error.

static start_service(name, argv=None)

Start the service given by name.

Warning

This method requires UAC elevation in Windows Vista and above.

Parameters:: name (str) – Service unique name. You can get this value from the ServiceName member of the service descriptors returned by get_services() or get_active_services().

static stop_service(name): Stop the service given by name.

Warning

This method requires UAC elevation in Windows Vista and above.

See also

get_services(), get_active_services(), start_service(), pause_service(), resume_service()

static write_msr(address, value)

Set the contents of the specified MSR (Machine Specific Register).

Parameters:

address (int) – MSR to write.
value (int) – Contents to write on the MSR.

Raises:

WindowsError – Raises an exception on error.
NotImplementedError – Current architecture is not i386 or amd64.

Warning

This method uses the processor’s machine specific registers (MSR). While this usage should be generally safe, it may fail under some special circumstances (for example with certain types of virtualization). In extremely old processors (circa 1995) using these registers may have occasionally cause a crash, but that’s no longer the case in modern processors.