Truxton functionality is exposed to the C programming world as a DLL named TruxtonCAPI.dll in the C:\Program Files\Truxton\SDK folder. This DLL can be called from any programming language that has the ability to make operating system calls.

Philosophy

The API is considered to be "flat" in that only sixty-four bit integers and ASCII character strings are used in the interface. This was chosen to make it easy for other languages to call the API. The coding convention is all lower case names with underscores separating words. Truxton is a member of the east const posse.

Creating a lib

Truxton doesn't ship a linker library for TruxtonCAPI.dll in order not to tie the developer to any particular compiler. If you want to link TruxtonCAPI.dll with your own C/C++ code, you will need to generate a linker library.

Generating a Linker Library for Microsoft Compilers

You can download a free Visual Studio from Microsoft. The steps to produce a LIB file from a DLL are:

Generate a module definition (DEF) file from TruxtonCAPI.dll.
Use the DEF file to create the linker library (LIB) file.

Generate a Module Definition File

The following Powershell script will create the DEF file.

$dumpbin = "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.28.29333\bin\Hostx64\x64\dumpbin.exe"

$lines = (& $dumpbin /exports TruxtonCAPI.dll)

Write-Output "EXPORTS"

foreach ( $line in $lines )
{
   if ( $line.Contains(" = ") -EQ $true )
   {
      Write-Output $line.SubString($line.IndexOf(" = ") + 3)
   }
}

In your SDK folder, execute the script from Powershell:

MakeDef.ps1 >TruxtonCAPI.def

Generate a LIB File

Now that you have the DEF file, you can create the linker library using lib.exe (which is found in the same folder as dumpbin.exe) in the command window:

lib.exe /def:TruxtonCAPI.def /out:TruxtonCAPI.lib /machine:x64

API Groups

The API is broken down into the different areas of Truxton.

Initialization

truxton_start - Initializes Truxton
truxton_stop - Uninitializes Truxton

Functions

truxton_create - Creates a Truxton object
truxton_destroy - Frees a Truxton object
truxton_get_device_id - Retrieves the Device identifier
truxton_get_machine_id - Retrieves the machine identifier
truxton_get_version - Retrieves the version of Truxton
truxton_start_adding_files - Prepares Truxton to add files to the database
truxton_route_message - Send a message to down-stream ETL processors

ETL Functions

truxton_etl_create - Creates a Truxton ETL object
truxton_etl_destroy - Destroys a Truxton ETL object
truxton_etl_add_command_line_argument - Adds a command line argument
truxton_etl_add_desired_file_type - Tells Truxton what types of files you want to process
truxton_etl_get_description - Retrieves the human readable description of this exploitation process
truxton_etl_set_description - Sets a description that has meaning to another human about this exploitation process
truxton_etl_get_message - Halts the execution of your program until a message arrives from your message queue
truxton_etl_get_stage_number - Retreives the stage of this exploitation process
truxton_etl_set_stage_number - Sets the stage at which this exploitation process should run
truxton_etl_set_application_name - Sets the name of your application
truxton_etl_set_depot_type - Sets the type of depot you want to use
truxton_etl_set_depot_type_name - Sets a seed name for the type of depot you want to use
truxton_etl_set_expander_identifier - Sets an identifier to use during reprocessing
truxton_etl_set_expander_version - Sets a custom version of your process
truxton_etl_set_queue_name - Sets the name of the message queue for this process
truxton_etl_set_thread_safe - Tells Truxton if it is safe to use your message handler in a multi-threaded fashion
truxton_etl_set_poly_file_expander - Tells Truxton you are a file expander that needs multiple source files
truxton_etl_send_me_file_id - Used during development and debugging
truxton_etl_send_me_files - Used during development and debugging
truxton_etl_send_me_hash - Used during development and debugging
truxton_etl_send_me_local_file - Used during development and debugging

Child Files

A child file is one that you have created and need to save in Truxton.

truxton_child_file_create - Create a file object to save to Truxton
truxton_child_file_destroy - Destroys a file object
truxton_child_file_clear - Returns a file object to an initial state of all zeroes
truxton_child_file_get_id - Retrieves the GUID of the child file
truxton_child_file_set_id - Sets the GUID of the child file
truxton_child_file_get_parent_id - Retrieves the GUID of the parent file
truxton_child_file_set_parent_id - Sets the GUID of the parent of the child
truxton_child_file_get_media_id - Retrieves the GUID of the media this child belongs to
truxton_child_file_set_media_id - Sets the GUID of the media this child belongs to
truxton_child_file_get_name - Retrieves the name of the file
truxton_child_file_set_name - Sets the name of the file
truxton_child_file_get_path - Retrieves the path of the file
truxton_child_file_set_path - Sets the path of the file
truxton_child_file_get_hash - Retrieves the MD5 hash (digital fingerprint) of the file's contents
truxton_child_file_get_number_of_children - Retrieves the number of child files of this file
truxton_child_file_set_number_of_children - Sets the number of child files of this file
truxton_child_file_get_created - Retrieves the date and time of when the file was created
truxton_child_file_set_created - Sets the date and time of when the file was created
truxton_child_file_get_accessed - Retrieves the date and time of when the file was accessed
truxton_child_file_set_accessed - Sets the date and time of when the file was accessed
truxton_child_file_get_modified - Retrieves the date and time of when the file was modified (last written to)
truxton_child_file_set_modified - Sets the date and time of when the file was modified (last written to)
truxton_child_file_get_size - Retrieves the size of the file, in bytes, as reported by the operating system
truxton_child_file_set_size - Sets the size of the file, in bytes, as reported by the operating system
truxton_child_file_get_origin - Retrieves the origin of the file
truxton_child_file_set_origin - Sets the origin of the file
truxton_child_file_get_content_status - Retrieves the status of the contents of the file
truxton_child_file_set_content_status - Sets the status of the contents of the file
truxton_child_file_get_truxton - Retrieves the instance of Truxton this child belongs to
truxton_child_file_begin_write - Prepares Truxton for writing contents to be associated with this file
truxton_child_file_end_write - Tells Truxton to finish writing contents
truxton_child_file_write - Gives Truxton bytes to store as the file contents
truxton_child_file_save - Commits data to the database
truxton_child_file_set_type - Sets the type of the file
truxton_child_file_get_type - Retrieves the type of the file
truxton_child_file_set_attributes - Sets the attributes of the file
truxton_child_file_get_attributes - Retrieves the attributes of the file
truxton_child_file_set_disk_offset - Sets the physical disk offset of the first byte of contents
truxton_child_file_get_disk_offset - Retrieves the physical disk offset of the first byte of contents
truxton_child_file_get_entropy - Retrieves the entropy of the file contents

Creating things related to this file:

truxton_child_file_create_artifact - Creates and associates an artifact with this file. The artifact will be saved to the [Entity] table.
truxton_child_file_create_event - Creates and associates an event with this file. The event will be saved to the [Event] table.
truxton_child_file_create_exif - Creates and associates camera information with this file. The data will be saved to the [EXIF] table.
truxton_child_file_create_location - Creates and associates a geographic location with this file. The data will be saved to the [Location] table.
truxton_child_file_create_relation - Creates a relationship with this file as the source. The data will be saved to the [Relation] table.
truxton_child_file_create_url - Creates a website visit with this file as the source. This data will be saved to the [WebsiteVisit] table.
truxton_child_file_create_usb - Creates a USB device with this file as the source. This data will be saved to the[Entity] table.
truxton_child_file_tag - Creates a tag and puts it on this file. This data will be saved to the [Tagged] table.
truxton_child_file_new_child - Creates a child of this file

File IO

truxton_file_open_id - Retrieves a particular file specified by the file's GUID.
truxton_file_open_md5 - Retrieves the first file in Truxton whose contents have the given MD5 hash.
truxton_file_close - Closes the contents. You will no longer be able to read from the file.
truxton_file_free - Deallocates any resources allocated for this object. The file is no longer valid after this call.
truxton_file_tell - Returns the current file pointer position.
truxton_file_length - Returns the number of bytes in the file's contents.
truxton_file_is_closed - Tells you if the file has been closed or not.
truxton_file_seek - Changes the file pointer.
truxton_file_readline - Reads a single line of text from the file.
truxton_file_read - Reads bytes from the file.

File Record Fields

truxton_file_get_accessed - Reads the file's last access timestamp in FILETIME ticks
truxton_file_get_attributes - Reads the attributes of the file
truxton_file_get_content_status - Reads the status of the file's contents
truxton_file_get_created - Reads the file's creation timestamp in FILETIME ticks
truxton_file_get_depot_id - Reads the GUID of the depot holding the file's contents
truxton_file_get_depot_length - Reads the number of bytes in the depot taken by this file's contents
truxton_file_get_depot_name - Reads the file name of the depot holding this file's contents
truxton_file_get_depot_offset - The offset from the beginning of the depot where this file's contents begin
truxton_file_get_disk_offset - Reads physical offset of the first byte of the file's contents
truxton_file_get_entropy - Reads the entropy of the file's contents
truxton_file_get_hash - Reads the MD5 of the file's contents
truxton_file_get_id - Reads the file's GUID
truxton_file_get_is_eliminated - Tells you of the file's contents were discarded
truxton_file_get_is_resident - Tells you if the file's contents exist contiguously within its parent
truxton_file_get_media_id - Reads the GUID of the file's media
truxton_file_get_modified - Reads the file's last write timestamp in FILETIME ticks
truxton_file_get_number_of_children - Returns the number of files that have this one as their parent
truxton_file_get_name - Reads the name of the file
truxton_file_get_number_of_children - Returns the number of files that have this one as their parent
truxton_file_get_origin - Reads the origin of the file's contents
truxton_file_get_parent_id - Reads the GUID of the file's parent
truxton_file_get_size - Reads the size of the file as recorded in the directory entry for the file
truxton_file_get_signature - Gets the first four bytes of the contents as an integer
truxton_file_get_type - Reads the type of the file

File Actions

These are things your can do to a file. These are not data items stored in the database.

truxton_file_change_type - Allows you to change the type of the file
truxton_file_get_details - Retrieves JSON with details of the file's contents
truxton_file_get_truxton - Retrieves the Truxton connection used to get this file

Create Objects from File

The following APIs are used to create objects with a file as their parent.

truxton_file_create_artifact - Creates and associates an artifact with this file. The artifact be saved to the [Entity] table.
truxton_file_create_child - For creating a file.
truxton_file_create_event - Creates and associates an event with this file. The event will be saved to the [Event] table.
truxton_file_create_exif - Creates and associates camera information with this file. The data will be saved to the [EXIF] table.
truxton_file_create_location - Creates and associates a geographic location with this file. The data will be saved to the [Location] table.
truxton_file_create_relation - Creates a relationship with this file as the source. The data will be saved to the [Relation] table.
truxton_file_create_url - Creates a website visit with this file as the source. This data will be saved to the [WebsiteVisit] table.
truxton_file_create_usb - Creates a USB device with this file as the source. This data will be saved to the [USBDevice] table.
truxton_file_tag - Creates a tag and puts it on this file. This data will be saved to the [Tagged] table.

Debugging

truxton_etl_send_me_file_id - Puts a message in your queue given a GUID that matches the [ID] column of the [File] table.
truxton_etl_send_me_files - Put a specified number messages in your queue of a particular file type.
truxton_etl_send_me_hash - Put one file that matches an MD5 hash.
truxton_etl_send_me_local_file - Put a specified file on your system into your message queue.

Media

These are the API's that allow you to add to the Media table in the database.

truxton_media_create - Creates a new media object
truxton_media_open_id - Opens an existing media in the database given the media's GUID.
truxton_media_destroy - Frees any resources allocated to this object
truxton_media_get_id - Retrieves the GUID of the media
truxton_media_set_id - Sets the GUID of the media
truxton_media_get_name - Retrieves the name of the media
truxton_media_set_name - Sets the name of the media
truxton_media_get_description - Retrieves the longer description of the media
truxton_media_set_description - Sets the description of the media
truxton_media_get_case_number - Retrieves the case identifier of the media
truxton_media_set_case_number - Sets the case identifier of the media
truxton_media_get_originator - Retrieves who asked you to process the media
truxton_media_set_originator - Sets the origin of the media
truxton_media_get_evidence_bag - Retrieves the identifier of the evidence bag the media is being kept in
truxton_media_set_evidence_bag - Records the identifier of the evidence bag the media is stored in.
truxton_media_get_status - Retrieves the status of the media
truxton_media_set_status - Sets the status of the media
truxton_media_get_type - Retrieves the type of the media
truxton_media_set_type - Sets the type of the media
truxton_media_get_created - Retrieves when the media was created
truxton_media_set_created - Sets when the media was created
truxton_media_get_last_updated - Retrieves when the media was last updated
truxton_media_set_last_updated - Sets when the media was last updated
truxton_media_get_expires - Retrieves the expiration date of the media
truxton_media_set_expires - Sets the expiration date of the media
truxton_media_get_percent_complete - Retrieves the completeness the processing of this media
truxton_media_set_percent_complete - Sets the completeness the processing of this media
truxton_media_get_load_configuration_id - Retrieves the load configuration of this media
truxton_media_set_load_configuration_id - Sets the load configuration of this media
truxton_media_get_size - Retrieves the size, in bytes, of the original media
truxton_media_set_size - Sets the size, in bytes, of the original media
truxton_media_get_latitude - Retrieves the latitude portion of the WGS84 coordinates of where the media was seized.
truxton_media_set_latitude - Sets the latitude portion of the WGS84 coordinates of where the media was seized.
truxton_media_get_longitude - Retrieves the longitude portion of the WGS84 coordinates of where the media was seized.
truxton_media_set_longitude - Sets the longitude portion of the WGS84 coordinates of where the media was seized.
truxton_media_get_generated_files_folder_id - Retrieves the GUID of the Generated Files folder in the media
truxton_media_get_root_file_id - Retrieves the GUID of the top level file in the media
truxton_media_add_child - Created a child file object belonging to this media.
truxton_media_save - Saves the media information to the database
truxton_media_tag - Associating a tag with this media

Message

This is the message sent on the message bus between the ETL processes.

truxton_message_create - Creates a new message object
truxton_message_destroy - Destroys the message object
truxton_message_get_queue_is_empty - Tells you if the message queue is empty
truxton_message_set_queue_is_empty - Sets the empty-queue attribute
truxton_message_get_route_id - Retrieves the route this message is taking
truxton_message_set_route_id - Sets the route the message should take
truxton_message_get_priority - Retrieves the priority of the message
truxton_message_set_priority - Sets the priority of the message
truxton_message_get_file_id - Retrieves the identifier of the file
truxton_message_set_file_id - Sets the identifier of the file
truxton_message_get_parent_id - Retrieves the parent file identifier
truxton_message_set_parent_id - Sets the parent file identifier
truxton_message_get_media_id - Retrieves the media identifier
truxton_message_set_media_id - Sets the media identifier
truxton_message_get_depot_id - Retrieves the depot identifier
truxton_message_set_depot_id - Sets the depot identifier
truxton_message_get_depot_offset - Retrieves the offset into the depot of the first byte of the file's contents
truxton_message_set_depot_offset - Sets the offset into the depot of the first byte of the file's contents
truxton_message_get_depot_length - Retrieves the number of bytes in the depot for this file's contents
truxton_message_set_depot_length - Sets the number of bytes in the depot for this file's contents
truxton_message_get_hash - Retrieves the MD5 hash (digital fingerprint) of the file's contents
truxton_message_set_hash - Sets the MD5 hash (digital fingerprint) of the file's contents
truxton_message_get_signature - Retrieves the first four bytes of the contents as an integer
truxton_message_set_signature - Sets the first four bytes of the contents as an integer
truxton_message_get_file_type - Retrieves the type of the file
truxton_message_set_file_type - Sets the type of the file
truxton_message_get_depot_name - Retrieves the name of the file that stores this file's contents
truxton_message_set_depot_name - Sets the name of the file that stores this file's contents
truxton_message_get_dont_route - Retrieves the Don't Route flag
truxton_message_set_dont_route - Sets the Don't Route flag
truxton_message_get_truxton - Retrieves the Truxton handle
truxton_message_set_truxton - Sets the Truxton handle

File Export

truxton_file_export_create - Creates a new file export object
truxton_file_export_destroy - Destroys an existing file export object
truxton_file_export_execute - Exports files
truxton_file_export_set_option - Sets options for the export
truxton_file_export_get_where_clause - Retrieves the SQL WHERE clause of the current criteria
truxton_file_export_add_string_criteria - Adds a string criteria to the export
truxton_file_export_add_integer_criteria - Adds an integer criteria to the export
truxton_file_export_set_truxton - Sets the parent Truxton object for this export

Artifacts

Artifacts are pieces of information that are also known as entities.

truxton_artifact_create - Creates a new artifact object
truxton_artifact_destroy - Destroys an existing artifact object
truxton_artifact_save - Saves the artifact to the [Entity] table in the database
truxton_artifact_get_data_type - Retrieves the raw data type
truxton_artifact_set_data_type - Sets the raw data type
truxton_artifact_get_file_id - Retrieves the identifier of the file the artifact was found in
truxton_artifact_set_file_id - Sets the identifier of the file the artifact was found in
truxton_artifact_get_id - After saving, retrieves the identifier of the artifact
truxton_artifact_get_length - Retrieves the number of bytes in the raw data that make up this artifact
truxton_artifact_set_length - Sets the number of bytes in the raw data that make up this artifact
truxton_artifact_get_media_id - Retrieves the identifier of the media this artifact is in
truxton_artifact_set_media_id - Sets the identifier of the media this artifact is in
truxton_artifact_get_object_id - Retrieves the identifier of the object the artifact came from
truxton_artifact_set_object_id - Sets the identifier of the object the artifact came from
truxton_artifact_get_object_type - Retrieves the type of object the artifact came from
truxton_artifact_set_object_type - Sets the type of object the artifact came from
truxton_artifact_get_offset - Retrieves the offset in the file where the artifact came from
truxton_artifact_set_offset - Sets the offset in the file where the artifact came from
truxton_artifact_get_value - Retrieves the value of the artifact
truxton_artifact_set_value - Sets the value of the artifact

Event

If you need to save a significant place in time, use the following functions. These will create a record in the [Event] table.

truxton_event_create - Creates a new event object
truxton_event_destroy - Destroys an existing event object
truxton_event_save - Saves the data in this object to the [Event] table
truxton_event_get_id - After saving, retrieves the GUID of the event.
truxton_event_get_title - Gets the short title of the event
truxton_event_set_title - Sets the short title of the event
truxton_event_get_description - Gets the long description of the event
truxton_event_set_description - Sets the long description of the event
truxton_event_get_start - Gets the beginning of the event
truxton_event_set_start - Sets the beginning of the event
truxton_event_get_end - Gets the end of the event
truxton_event_set_end - Sets the end of the event
truxton_event_get_type - Gets the type of event
truxton_event_set_type - Sets the type of event
truxton_event_get_media_id - Gets the GUID of the media this event belongs to
truxton_event_set_media_id - Sets the GUID of the media this event belongs to
truxton_event_get_file_id - Gets the GUID of the file this event came from
truxton_event_set_file_id - Sets the GUID of the file this event came from

EXIF (Camera Information)

File Type

truxton_file_type_create - Creates a file type object.
truxton_file_type_destroy - Deallocates any resources assigned to the file object.
truxton_file_type_get_id - Retrieves the identifier you assigned to this object.
truxton_file_type_set_id - Sets the unique identifier. This corresponds to the [ID] column of the [FileType] table.
truxton_file_type_get_parent_id - Retrieves the parent identifier you assigned to this object.
truxton_file_type_set_parent_id - Sets the more generic type of the file. This corresponds to the [ParentFileTypeID] column of the [FileType] table.
truxton_file_type_get_short_name - Retrieves the short name you assigned to this object.
truxton_file_type_set_short_name - Sets the short name to use for this file type. This corresponds to the [ShortName] column of the [FileType] table.
truxton_file_type_get_long_name - Retrieves the longer description you assigned to this object.
truxton_file_type_set_long_name - Sets the longer description of the file type. This corresponds to the [LongName] column of the [FileType] table.
truxton_file_type_get_extension - Retrieves the file name extension you assigned to this object.
truxton_file_type_set_extension - Sets the file name extension for this object.
truxton_file_type_get_mime_type - Retrieves the MIME type you assigned to this object. This corresponds to the [Extension] column of the [FileType] table.
truxton_file_type_set_mime_type - Sets the MIME type. This corresponds to the [MIME] column of the [FileType] table.
truxton_file_type_save - This will write the information in the object to the [FileType] table.

Geographic Location

Options

Truxton "options" are otherwise known as configuration settings, command line options, etc. They are configuration items that your program can use.

truxton_options_create - Creates the options object
truxton_options_destroy - Frees any resources allocated by the options
truxton_option_get_boolean - Reads a named boolean value
truxton_option_get_integer - Reads a named integer value
truxton_option_get_string - Reads a named string value

Relation

Website Visit

USB Device

Truxton C API

Contents