Automate investigative tasks and extend the
functionality of X-Ways Forensics
and WinHex with X-Tensions.
The X-Ways Forensics X-Tensions API is an application programming interface that allows you to use many of the advanced capabilities of the X-Ways Forensics computer software programmatically and extend them with your own functionality. For example, you could implement some specialized file carving for certain file types, automated triage functionality, alternative report generation, automatically filter out unwanted search hits depending on your requirements, or generate your own human-readable representations of special file formats as previews etc.
Among other things, X-Tensions allow you to:
You can use your compiler and programming language of choice, any one which can create Windows DLLs, for example Visual Studio Express (freeware, more information), Free Pascal (also free), lcc-win (free for non-commercial use) and generally languages such as C++, C, Delphi/Pascal, Visual Basic, so you do not have to learn any new scripting language. A C# port of the X-Tension API is available from here (also here) to make it easier to develop X-Tensions in .Net, thanks to Chad Gough. An updated C# port by Jason Copeland can be found here.
X-Tensions give you easy and direct access to crucial and powerful functions deep inside our software. Since an X-Tension is not an interpreted script, but regular compiled executable code that is running in the address space of the application itself, you can expect highest performance, the same as with internally implemented functionality in X-Ways Forensics. This is a far cry from running EnScripts in a competing software (for example the C4All X-Tension is about 6 times faster than the EnScript), and you are not forced to learn a proprietary programming language.
How/when X-Tensions functions can get called:
So-called Viewer X-Tensions (supported as of v17.6 of X-Ways Forensics, and also in X-Ways Investigator and even in X-Ways Investigator CTR!) are selected by the user in the Options | Viewer Programs dialog window.
So-called Disk I/O X-Tensions (supported as of v18.4 of X-Ways Forensics) allow you to intercept data read by X-Ways Forensics from devices or images and alter it on the fly before it gets parsed or reaches the display in the user interface, for example in order to decrypt the data in the presence of any full disk encryption scheme that you wish to support.
Related: X-Ways Forensics Image I/O API
You may distribute X-Tensions that you compile and/or their source code (ideally both) free of charge or even for a fee, under whatever license terms you see fit. X-Ways does not require any royalty payment. However, you have to accept that the terms, the functionality and the availability of the XWF X-Tensions API/engine may change in future versions of X-Ways Forensics.
You are encouraged to submit your XWF extensions for download from the X-Ways web site. X-Ways does not check third party X-Tensions and will not be responsible for their quality or any damage caused by them. Please be advised that X-Tensions are executable files that run with the same rights as X-Ways Forensics and could be malware.
Your code needs to be compiled as a DLL, which will be loaded by X-Ways Forensics at run time. In each DLL you have to implement (and export) one or more out of the below-mentioned functions. Which function(s) you implement depends for example on when exactly you would like X-Ways Forensics to call them, such as either at the start or end of the volume snapshot refinement, dealing with the volume or the volume snapshot as a whole, or for each item in the volume snapshot separately when refining it. This part of the API (the XT_* functions) is like a framework based on the so-called Hollywood principle “don't call us, we call you”. Unlike in Hollywood, you actually get called, though.
All exported X-Tension functions and internal XWF API functions use stdcall calling conventions under 32 bit. The API is available only in v16.4 and later of X-Ways Forensics (also if X-Ways Forensics is executed as WinHex), both 32-bit and 64-bit. The name of the DLL should be descriptive. For use in v16.4 the name should start with "XT" and must be less than 32 ASCII characters long, and the DLL must be placed in the same directory where X-Ways Forensics is run from (or if a 64-bit DLL, in the \x64 subdirectory). The data types used are described here.
Up to 8 X-Tensions can be run at a time when refining the volume snapshot. Simultaneous instead of subsequent execution is not only convenient, but also saves time if each X-Tension opens and reads from all the files in the volume snapshot one after the other as caching is improved and no time is wasted on multiple identical open/close file operations.
An X-Tensions DLL gets unloaded as soon as the overall operation has completed, so that when you are debugging your DLL, you can recompile it (overwrite the previous built) while X-Ways Forensics is still running.
C++ function definitions and sample projects (updated
Plug-in for Python with sample scripts (64-bit, from Apr 2021)
Plug-in for Python with sample scripts (32-bit, from Aug 2012. Outdated version, not recommended.)
Please note that interpreted Python code is much, much slower than native code. Not all the functionality is available via the Python plug-in, and available functions may be different in Python, so Python is not recommended for the X-Tension API. Refer to readme.txt instead of the below specifications when in doubt. Select the scripts by clicking the ... button in the X-Tension window. Mini Python (outdated)
|Documentation of all Functions||
The technical specifications apply to X-Ways Forensics 16.4 SR-3 and later and WinHex 18.6 with a Lab Edition license, unless noted otherwise. Last updated on June 22, 2018.
XT_* functions in an X-Tension, which you have to/may implement/export, that are called by X-Ways Forensics:
XWF_* functions in X-Ways Forensics that you may call:
1) disk and general
Please note that all HANDLE variables for evidence objects, volumes, files, and directories and only valid handles in the context of this API! These handles are not operating system handles and cannot be used in conjunction with Windows API functions! Conversely, Windows handles cannot be used in the X-Tension API. Handles that are not available are initialized with 0. Or in other words 0 is not a valid handle.
Please also note that you have to export your XT_* functions with undecorated names, or else they will not be found by X-Ways Forensics! This concept is described for example here and here. In Microsoft Visual Studio that might mean that you should not declare your functions with __declspec(dllexport), but extern "C" __declspec(dllexport) instead. To check the actual exported function names, you can view your own DLL in X-Ways Forensics with the viewer component.
|Command Line Parameters||
The user may run X-Ways Forensics with command line parameters for automatic processing. These parameters are usually meant for X-Ways Forensics itself to process. However, as of v19.4 SR-6, it is defined that parameters starting with the characters "XTParam:" are ignored by X-Ways Forensics, so that no message box about a "file not found" error condition or so pops up. Such parameters can be used by X-Tensions. They may retrieve the entire command line with the Windows GetCommandLine function, parse it, and look for a parameter with the above-mentioned prefix. Such an X-Tension that expects one or more command line parameters should also define a short ID that identifies the X-Tension (e.g. its short name) and identifies parameters meant for that particular X-Tension (in case the user executes multiple X-Tensions at the same time). The documentation of an X-Tension that works with command line parameters should specify that ID. The ID follows the prefix. The actual value/payload of the parameter follows the ID. Prefix, ID and value are delimited by colons:
If either the ID or the value contains spaces, the entire expression has to be put into quotation marks so that it will be treated as one (ignorable) parameter by X-Ways Forensics. The value may contain colons itself. The ID should not contain a colon.