X-Ways Forensics X-Tensions API Documentation

  Automate investigative tasks and extend the functionality of X-Ways Forensics and WinHex with X-Tensions.

Repository of downloadable X-Tensions

 

Summary

The X-Ways Forensics X-Tensions API is a 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 (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:

  • 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 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. Details.

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. Details.

Legalities

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.

Technical Details

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. 

API Downloads

C++ function definitions and sample projects (updated 2014-04-22)
Delphi function definitions and 5 sample projects (updated 2016-06-15)
Project in C with source code
32-bit demo, 64-bit demo (updated 2016-06-15)

Plug-in for Python with sample scripts (32-bit, updated 2012-08-14)
Not recommended. 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

Function Details

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 July 8, 2017.

XT_* functions in an X-Tension, which you have to/may implement/export, that are called by X-Ways Forensics:

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

XWF_* functions in X-Ways Forensics that 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) 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. 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.