WinAPIOverride

WinApiOverride

   - Toolbar
   - Shortcuts
   - Starting
         - Hook already existing process(es)
         - Hook a single process at startup
         - Hook all starting processes
   - Loading Monitoring files and Overriding dlls
   - Modules filtering
   - Logs Views
         - Main view
         - Detailed view
   - Analysing
         - Call Tree
         - Global Statistics
         - Detailed Statistics
         - Timing Charts
         - Sequences Auto Detection
         - Known Sequences Search
   - Launching WinAPIOverride by Command Line

   - Tutorial
   - FAQ


Toolbar
Start / Stop hooking (monitoring, overriding) and remote call
Notice: Stop automatically unload monitoring files and overriding dll
 
Pause / Resume functions monitoring and breaking (doesn't affect other functionnalities)
Notice: As logs are put into a queue, you can see monitoring logs be added even if you click the "Pause monitoring" button.
Logs will continue to appear until the queue becomes empty.

Pause / Resume functions overriding (doesn't affect other functionnalities)
Open the processes filters dialog (only available when "Attach to all new Processes option" is checked)
Open the modules filters dialog (only available when started)
Open the threads filters dialog, to select which threads are hooked (only available when started)
Clear the current logs list
Open a previously saved log file
Save logs to file
Export logs to file (html, xml, txt, cvs). According to the options, only selected logs and/or visible columns are exported. Full parameter content export can be queried too.
Enable or disable COM, OLE and ActiveX (OCX) auto hooking
COM, OLE and ActiveX (OCX) Tools: Monitored interfaces selection, Hooked objects interaction, Show methods addresses, CLSID-ProgId and IID-Interface Name converters
Direct access to COM options
Enable or disable .NET functions hooking (Applies only to new started applications and services. Applies to all running WinApiOverride instances)
.NET jitted functions interaction (show disassembly, allow live hooking and unhooking)
Direct access to .NET options
Allow to select visible columns for the main view
Show the options dialog
Check for software updates
Report bug to author
Help
Gives software information
Allow you to support this software by making a donation
Allow memory operations on other processes
Allow dump of hooked processes (only available when started)
Convert a dump file to exe or dll
  - By removing nonraw parts (default) : remove virtual memory space not present in raw mapping
  - By modifying PE : let all the virtual memory space present, and modify the raw mapping of the exe or dll file
Allow to call a function inside an hooked process (only available when started)
Threads : display all the threads of an hooked process, and allow operations on them (only available when started)
All call stacks : retreive the call stack of all the threads of an hooked process (only available when started)
Display modules sections of an hooked process (only available when started)
Allow to do raw disassembly from memory of an hooked process (only available when started)
Launch the MonitoringFileBuilder application and other WinApiOverride tools
Give access to plugins menus
Compare 2 log files
Compare the 2 first selected logs
Do Call Tree for logged functions. (Since v6.5.1 you can do API monitoring with Call Tree enabled but it is slower)
Do Sequences Auto Detection for logged functions
Do Known Sequences Search for logged functions
Make search into logs
Allow to quickly jump to a log
Show the message description for the LastError value of selected item
String to byte buffer convertion (works for Ascii or Unicode)
Undecorate C++ function
Browse to online MSDN for the selected function definition
Show global logs statistics for all functions
Show detailed statistics for the selected function only
Display a timing chart for all logs
Display a timing chart for selected logs ony : provides a closer view of events of interest without being disturb by other logs



Shortcuts
Shortcut Description
F1 Show help
F5 Start
Shift + F5 Stop
Ctrl + O Open a previously saved logged file (xml.zip or xml)
Ctrl + S Save logs
Ctrl + E Export logs to HTML, CSV, RTF or TXT formats
Ctrl + F Find logs
Ctrl + M Display Memory dialog
Ctrl + D Show Dump dialog
Ctrl + R Show the Remote Call dialog
Ctrl + Q Do log compare of the 2 first selected function call logs
Ctrl + N Go to next failure
Ctrl + P Go to previous failure
Ctrl + W Search in MSDN for function name
Ctrl + G Google function name
Ctrl + B Display String <-> Hex convertion dialog
Ctrl + I Display software information



Starting
1) First select the hooking way and the process(es) to be hooked

   - To hook already existing process(es), check "Attach to a running process(es)".
You can choose an existing process by directly enter PID (in decimal or hex) or by selecting the target application with the cross (simply drag and drop the cross)   
If you want to hook multiple processes, enter processes id splitted by ";", or use the button to select processes in a list   
If you want to hook services, enter processes id splitted by ";", or use the button to select services in a list   

   - To hook a process at startup, select "Attach at application startup".
Enter the application name and it's command line if necessary.

If you want to make multiple runs, you can chack "Automatically resume application after having loaded the following file list" and specify which monitoring files and overriding dll will be automatically reloaded (the process will resume after theses injections)

If you want to run application under another user account, simply check "Run as" and sepcify user and password. (Notice: for security reason these settings are not saved)

If you want to spy only after a while, you can set a small amount of time in milliseconds specifying the elapsed time between application startup and begin of hook.

If you want to start hooking application before statically linked dll TLS or DllMain execution, check the "Inject before statically linked dll execution".
Notice :
   1) This can be done for all dlls but ntdll.dll, kernel32.dll and kernelbase.dll
   2) You must have write access in the application directory


As soon as the application is hooked, it is suspended and the following message box appears.
At this point you can load monitoring files and/or overriding dll while the application is still suspended.
When you have finished to load all your files, just close the message box and your application will be resumed
To avoid to miss some calls, loads your files before clicking OK
As soon as you close this message box application will be resumed,
So load your config files before clicking OK

   - To hook all starting processes, select "Attach to all new processes"
You can specify running processes to hook, or define filter rules for new starting processes.
Do to this, click the "Filters" button. The processes filters dialog will allow you to configure all these options.
Hooking this way, all defined monitoring files and overriding dll are loaded at the startup of new processes matching filters.
Notice : Filters can be changed even if hooking is started


2) Once configured, start hooking by clicking the start button in the toolbar

To enable COM hooking, click the toolbar button on the main window before starting the application to hook.
Next it's recommended to attach application at startup to avoid COM object creation miss
With default options you don't need to do anything else.


To enable .Net hooking, click the toolbar button on the main window before starting the application to hook.
Next you can attach application at startup or after launching it.
With default options you don't need to do anything else.




Loading Monitoring files and Overriding dll

As soon as process is hooked, interface changes a little, and a new space is displayed.

Monitoring part

Enter the path of a monitoring file (see monitoring file syntax) and next click the "Load" button.
Once the file is successfully loaded it will appear in the list.
You can load as many monitoring file you want and unload them independently in any order.
To unload monitoring file(s) select them and click the "Unload" button.

Open a monitoring library dialog for an easy function selection. Notice: monitoring library applies only on files located in the "monitoring files" subdirectory of WinApiOverride
Reload previous monitoring files (if no files have been loaded)
or Reload current monitoring files (usefull if you modify some monitoring file during the hooking process)
Monitoring library gives an easy way to select funtions to monitor
Monitoring Library allows to quickly edit and/or select functions you want to monitor

Check the wanted files to load and then click "Ok"
To change function selection in a monitoring file, first select the file (warning selecting is different of checking, click on the name of the file) and you will be able to search, select/unselect function and quick edit them.
To unload previous loaded files, just check the "Unload previous loaded monitoring files" at the lower left corner


Overriding part

Enter the path of an overriding dll (see creating overriding dll) and next click the "Load" button.
Once the dll is successfully loaded, it will appear in the list.
You can load as many overriding dll you want and unload them independently in any order.
To unload overriding dll(s) select them and click the "Unload" button.

Reloads previous overriding dll (if no files have been loaded)
or Reloads the current ones (DllMain will be executed again)




Modules filtering

To avoid a big list of useless logs coming from system dlls (like kernel32.dll, user32.dll...), you can put filters to discard modules from being logged.
For more information see the Modules Filters documentation.



Logs views

The main view

This view allow you to see
- Log identifier (Id) : unique id of the log
- Log direction (Dir) : specify the way of parameter logging In, Out or InNoRet
- A string representation of the call (Call)
- The value returned by the function (Ret Value) According to direction
- The caller address : address location from which call is done (Caller Addr). See FAQ: What is caller address and how is it computed ? for more information
- The caller relative address : caller address relative to the module base address (Caller Relative Addr)
- The process ID : process Id in which the call has been done. This is usefull only when hooking multiple applications
- The thread Id : thread Id in which the call has been done
- The win32 last error after the call. This field is displayed even if function succeed and last error has not been changed
- Processor registers before the call
- Processor registers after the call According to direction
- The floating value returned by function. Significant only for function returning double or float values. According to direction
- The Start time : the time when function was called
- The duration requiered for the function execution (Duration)
- The module name : the name of dll containing the hooked API. This field is usefull if functions of different dll have the same name.
- The name of the API. Can be usefull to make more advanced statistics in your favorite spreadsheet with the export options
- The full path of calling module (Caller Full path)

Use the toolbar item to select visible columns for the main view

Calls with a red background are the failing ones.


The context menu

- Copy Selected : copy visibles colomns of selected logs into clipboard
- Copy All : copy visibles columns of all logs into clipboard
- Save All : save logs
- Export Selected : export visibles colomns of selected logs
- Export All : export visibles columns of all logs
- Invert Selection : invert the current selection
- Remove Selected logs : removes thes selected logs
- Clear Logs : removes all logs
- Online MSDN : automatically go to online MSDN and display the definition of the first selected function (fails somtimes)
- Google Function Name : open your default browser and make a query with the name of first selected function in google
- Copy Function Name : copy first selected function name into clipboard
- Go To Previous Failure : go to previous call failure
- Go To Next Failure : go to next call failure
- Get non rebased virtual address:   If dll has been rebased, this function compute the caller address, as if dll was not rebased.
  If dll was not rebased, you'll get the same value as caller address
- Show GetLastError error message : convert the Last Error value to a user message. Same as the toolbar button
- Show returned value error message : convert the returned value to a user message. Use this menu when functions directly return the error code


The detailed view

As the string representation of the calls is limited in the main view, there's another view called the detailed view at the right of the main view.
Each time you select a log in the main view, the detail view is updated.

Default supported types, user types and user defines are fully expended and displayed.
This view has a context menu too which provides Copy and Save functionnalities, and a "Show Hex Data" item to display parameters content (string, buffer, array, struct...) in hex


Due to Microsoft ListView control limitation, data representation using more than 260 characters are not fully displayed.
To display the full data content do a right click on it and use the "Show Hex Data" menu (or simply double click on it).
The "Copy"and "Save" menu will copy and save the full content not only the 260 characters.

If the "Try to retrieve call stack" options has been set (See option dialog), and call retrieval has been successful, you will get the following additional information
Since version 6.0, WinApiOverride can use Microsoft pdb server to display better function information for microsoft dll.
Look at Options /General Options / Uses Debug Symbols Servers
As first element is the returned address of current monitored function, all information (function name and parameters) are already displayed upper.
For next elements, you get two rows : one called "Possible Func Name" and another "Parameters".

In the "Possible Func Name" one, you will find, only for dll, the name of the exported function whose address is the nearset lower address of the calling address.
As you can see on the screenshot it can fail (as soon you get two or more time the same name it is suspicious).
The reason is the following one :

The dll code could be represented like

ExportedFunction1 address
ExportedFunction1 asm code

NotExportedFunction1 address
NotExportedFunction1 asm code

NotExportedFunction2 address
NotExportedFunction2 asm code

ExportedFunction2 address
ExportedFunction2 asm code

So if you return address is between ExportedFunction1 address and ExportedFunction2 address,
the display name will be the ExportedFunction1 name; although the real calling function can be ExportedFunction1, NotExportedFunction1 or NotExportedFunction2.

In the "Parameters" row, you will find raw parameter value. An advanced parsing on parameters can't be done as we don't know function name and type.
So you will get only stack values.

Analysing
   - Call Tree
   - Global Statistics
   - Detailed Stats
   - Timing Charts
   - Sequence Auto Detection
   - Known Sequences Search

Call Tree
Since version 5.0 "Try to retrieve call stack" option is no more requiered to do a call tree.
Since version 6.5.1 live call tree is available : tree is built during monitoring.
WinAPIOverride will display call depth of function and subfunctions.

To go out of the Call Tree view, just click the "Time View / Call Tree View" button again.
Inside Call Tree view, column sorting is disabled, go back to classic view to enable sorting again



Launching WinAPIOverride by Command Line

Command line has multiple advantages.
By the way, using it in your favorite debugger, you can debug and monitor an application in the same time;
or with the NoGUI option, you can change an application shortcut to override an API, without visible changes, each time this application is launched.

One of the arguments "AppPath", "AppPid" or "All" must be present

When you run a 32-bit graphical user interface (GUI) application, cmd does not wait for the application to quit before returning to the command prompt.
This behavior does not occur if you run the application from a command script (.bat file)

The following arguments are supported (case insensitive, free arguments order) :

   AppPath="Application Path" : Launch and hook specified application
   AppCmdLine="Application Command Line" : Command line to pass to Launched application. Only available for "AppPath" option. Optional
   InjectOnlyAfter=TimeInMs : Time in millisecond to wait between process start and hooking start.TimeInMs can be in decimal or hexadecimal Available only for AppPath or All option. Optional
   StopAndKillAfter=TimeInMs : Time in millisecond to wait before stop logging and kill launched application.TimeInMs can be in decimal or hexadecimal Available only for AppPath option. Optional
   HookBeforeDllExecution= : If you want to start hooking application before statically linked dll TLS or DllMain execution

   AppPid=ProcessId : hook the specified process(es). ProcessId can be in decimal or hexadecimal. To hook multiple processes, split process id by ';' ex: "AppPid=3392;0x1567;2758"

   All : to hook all processes matching AllProcessesInclusion, AllProcessesExclusion and AllProcessesParentPID filters. All processes defined in AllProcessesPID are hooked just after WinApiOverride start.
   AllProcessesInclusion= "filter 1";"filter 2": Inclusion filters (See Processes filters ) Optional, available only for All option
   AllProcessesExclusion="filter 1";"filter 2" : Exclusion filters (See Processes filters ) Optional, available only for All option
   AllProcessesParentInclusion= "filter 1";"filter 2": Parent Inclusion filters (See Processes filters ) Optional, available only for All option
   AllProcessesParentExclusion="filter 1";"filter 2" : Parent Exclusion filters (See Processes filters ) Optional, available only for All option
   AllProcessesParentPID=Number;Number-Number;Number : Process parent Id filters (See Processes filters ) Optional, available only for All option.
   AllProcessesPID=Number;Number-Number;Number : Current running processes to hook (See Processes filters ) Optional, available only for All option.

   MonitoringFiles="Monitoring file path 1";"Monitoring file path 2";"Monitoring file path 3" : load monitoring files as soon as applications are hooked Optional
   OverridingDlls="Overriding dll path 1";"Overriding dll path 2";"Overriding dll path 3" : load overriding dll as soon as applications are hooked Optional

   OnlyBaseModule : To log only base module (See Modules filters ) Optional
   ExclusionList="Exclusion list file path" Allow to specify a module exclusion list file(See Modules filters ) Optional
   InclusionList="Inclusion list file path" Allow to specify a module inclusion list file(See Modules filters ) Optional

   MonitoringFileDebug : Enable the monitoring file debug mode (See Options/Basic options ) Force all api to be spyed in the InOut mode and do not respect filters : every calls are logged Optional
   MonitoringForceInOutForAllApi : Force all api to be spyed in the InOut mode and respect filters (modules names, returned values,...) (See Options/Basic options ) Optional

   DontBreakAPIOverrideThreads : Allow you to make action while the break dialog is displayed (See Options/Basic options ) Optional

   GetCallStack : Try to retrieve call stack for each call. Optional
   CallStackNbParams=NumberOfParameters : Number of parameter to retrieve for each call found in the call stack. NumberOfParameters can be in decimal or hexadecimal Available only for "GetCallStack" option. Optional

   SecureLenDAsm : Specify to install hooks using internal secure length disassembler (See Options/Advanced options ) Optional
   InsecureLenDAsm : Specify to install hooks using internal insecure length disassembler (See Options/Advanced options ) Optional

   NoGUI : The user interface wont be shown.Usefull if you want to only to do overriding. WinApiOverride exits automatically at the target application end. If you want to use this option for logging, use the SavingFileName option, so logs are automatically saved before WinApiOverride exits. Optional
   SavingFileName="file path" : For NoGUI option only : save logs in provided file path before exiting. The format for the saving file name is ".xml" or ".xml.zip" (recommanded to reduce disk space usage). Optional

If you use the "NoGUI" option and specify the "All" argument, as WinApiOverride mustn't exit at the end of each hooked process,
you have to manually kill WinApiOverride using task manager, and so no logs saving can be done.


Com specific keywords. See COM Options for more explanations
   COMNotHookedClsid="Exclusion list file path" Allow to specify a CLSID exclusion list file Optional
   COMOnlyHookedClsid="Inclusion list file path" Allow to specify a CLSID inclusion list file Optional
   COMObjectCreationFile="file path" Allow to specify monitored API creating COM objects for COM auto hooking Optional
                                               Needed if "COMAutoHook" argument is set
   COMReportMonitoringFileLack : Report warning when a monitoring file is not found for COM auto hooking. Optional
   COMUseName : Display class name and interface name instead of CLSID and IID in reports. Optional
   COMReportObjectsLife : Report created and destroyed COM objects. Optional
   COMIDispatchAutoMonitoring : Enable COM IDispatch auto monitoring. Optional
   COMAutoHook : Enable COM auto hooking. Optional
                                Needs "COMObjectCreationFile" argument to be set
   COMIDispatchQueryMethodToHook : if COM IDispatch auto monitoring is activated, query for method to hook for each new interface supporting IDispatch hooked. Optional

Examples :

To hook notpad at startup injecting 2 monitoring files :
WinAPIOverride32.exe AppPath="c:\windows\notepad.exe" MonitoringFiles="D:\WinAPIOverride\monitoring files\InputTextDataRetrival.txt";"D:\WinAPIOverride\monitoring files\MessageBox.txt"

To hook notepad 200 ms after startup, passing "foo.txt" throw command line, and injecting an overriding dll :
WinAPIOverride32.exe AppPath="c:\windows\notepad.exe" InjectOnlyAfter=200 AppCmdLine="foo.txt" OverridingDlls="D:\WinAPIOverride\FakeMessageBox.dll"

To hook process Id 2024, injecting a monitoring file and using NotHookedModuleList as module list filters file :
WinAPIOverride32.exe AppPid=2024 MonitoringFiles="D:\WinAPIOverride\monitoring files\InputTextDataRetrival.txt" ExclusionList="NotHookedModuleList.txt"

To silently override Notepad MessageBox API
WinAPIOverride32.exe AppPath="c:\windows\notepad.exe" NoGUI OverridingDlls="D:\WinAPIOverride\FakeMessageBox.dll"

To hook multiple applications using some processes filters, hooking only base module, using a monitoring file and an overriding dll :
WinAPIOverride32.exe All OnlyBaseModule AllProcessesInclusion="not*";"calc*" AllProcessesExclusion="*.com";"*.pif" AllProcessesParentPID=2032;3056 AllProcessesPID=2027;2045-2050;3012 MonitoringFiles="D:\WinAPIOverride\monitoring files\InputTextDataRetrival.txt" OverridingDlls="D:\WinAPIOverride\FakeMessageBox.dll"