X-Ways Forensics X-Tensions API Documentation

Repository of downloadable X-Tensions

Introduction to the X-Tension API by Ted Smith (YouTube video, for programmers)

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:

• read from a disk/partition/volume/image
• retrieve abundant information about each file and directory in the volume snapshot
• read from any file
• add new objects to the volume snapshot, e.g. attach results of translations, decryption, decoding etc.
• bookmark/classify/categorize files by assigning them to report tables
• add free text comments to files
• run searches
• process, validate and delete search hits
• create and fill evidence file containers
• add events to the event list
• retrieve information about evidence objects
• add evidence objects to the currently loaded case
• and do practically everything else that is possible with a Windows program! (thanks to the Windows API)

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 and Lazarus (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 language. A C# port of the X-Tension API is available from 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. The external links here are not to be interpreted as endorsements or recommendations.

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:

• when refining the volume snapshot (to process the volume snapshot and/or the volume that it represents)
• when running a simultaneous search (to process search hits at the moment when they are found, before they are stored)
• via the Tools | Run X-Tensions menu command (to process the disk or volume or file or image that the active data window represents, no volume snapshot, or to run totally without context, i.e. no disk/volume/file/image open at all)
• via the directory browser context menu (to process the selected items in the volume snapshot)

So-called Viewer X-Tensions (supported 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 can be selected by the user through the Case Data window's context menu when opening an evidence object. They allow you to intercept data read by X-Ways Forensics from storage 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 or partition/volume-based 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 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 X-Tensions 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. 

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 as an aspiring script writer, you do actually get called, though.

All exported XT_* functions and internal XWF_* API functions use stdcall calling conventions under 32 bit. The API is available in X-Ways Forensics 16.5 and later plus (with some limitations) WinHex Lab Edition 18.6 and later, both 32-bit and 64-bit. The data types used are described here.

X-Ways Forensics is a DPI-aware application (more precisely system DPI aware), meaning it will scale its graphical user interface elements to match the user's expectations for their individual screen resolution and eyesight (only once, when started). X-Tensions that have their own windows/dialogs/forms will be treated by Windows as DPI-aware as well because they are part of the same process, meaning they should size their windows, controls, font etc. accordingly.

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. It has been found that C#-based DLLs cannot easily be unloaded with a single call to FreeLibrary. If so, X-Ways Forensics will inform and prompt the user as follows: "Stubborn X-Tension DLL. Force unload?" (This message box can be suppressed by the user.) After clicking Yes, X-Ways Forensics tries calling FreeLibrary a second time. That often succeeds, but may have undesirable side effects. 

C++ function definitions and sample projects (updated Apr 2021)
Delphi function definitions and 5 sample projects (updated May 2023)
Project in C with source code
32-bit demo, 64-bit demo (updated June 2016)

Plug-in for Python 3.10 with sample scripts (64-bit, from Jan 2023)

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)

Below please find a list of XT_* functions in an X-Tension, which you have to/may implement/export, which are called by X-Ways Forensics:

1) for “ordinary” X-Tensions
2) for viewer X-Tensions
3) for disk I/O X-Tensions

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.

If X-Ways Forensics rejects your X-Tension, claiming that "The specified procedure could not be found", please check the actual exported function names. You can for example view your own DLL in X-Ways Forensics with the viewer component and look for the section entitled "Export table". If there is no such section that means your DLL does not actually export at of the required XT_* functions at all, let alone with the right names.

The following is a list of XWF_* functions in X-Ways Forensics, which you may call:

1) disk and general I/O functions
2) evidence object/case management functions
3) volume snapshot management functions
4) volume snapshot item property functions
5) file contents functions
6) search-related functions
7) event-related functions
8) evidence file container functions
9) data window functions
10) miscellaneous functions

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 (zero). Or in other words 0 (zero) is not a valid handle. 

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:

XTParam:ID:value

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 must not contain a colon.