Truxton C API

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 interface to. The coding convention is all lower case names with underscores separating words. Truxton is a member of the east const posse.

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 -
• truxton_message_set_signature -
• truxton_message_get_file_type -
• truxton_message_set_file_type -
• truxton_message_get_depot_name -
• truxton_message_set_depot_filename -
• truxton_message_get_dont_route -
• truxton_message_set_dont_route -
• truxton_message_get_truxton -
• truxton_message_set_truxton -

File Export

• truxton_file_export_create
• truxton_file_export_destroy
• truxton_file_export_set_option
• truxton_file_export_get_where_clause
• truxton_file_export_add_string_criteria
• truxton_file_export_add_integer_criteria
• truxton_file_export_set_truxton
• truxton_file_export_where_clause

Artifacts

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

• truxton_artifact_create
• truxton_artifact_destroy
• truxton_artifact_save
• truxton_artifact_get_data_type
• truxton_artifact_set_data_type
• truxton_artifact_get_file_id
• truxton_artifact_set_file_id
• truxton_artifact_get_id
• truxton_artifact_get_length
• truxton_artifact_set_length
• truxton_artifact_get_media_id
• truxton_artifact_set_media_id
• truxton_artifact_get_object_id
• truxton_artifact_set_object_id
• truxton_artifact_get_object_type
• truxton_artifact_set_object_type
• truxton_artifact_get_offset
• truxton_artifact_set_offset
• truxton_artifact_get_value
• truxton_artifact_set_value

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)

• truxton_exif_create
• truxton_exif_destroy
• truxton_exif_save
• truxton_exif_get_id
• truxton_exif_get_file_id
• truxton_exif_set_file_id
• truxton_exif_get_media_id
• truxton_exif_set_media_id
• truxton_exif_get_gps_time
• truxton_exif_set_gps_time
• truxton_exif_get_gps_time_offset
• truxton_exif_set_gps_time_offset
• truxton_exif_get_device_time
• truxton_exif_set_device_time
• truxton_exif_get_device_time_offset
• truxton_exif_set_device_time_offset
• truxton_exif_get_latitude
• truxton_exif_set_latitude
• truxton_exif_get_latitude_offset
• truxton_exif_set_latitude_offset
• truxton_exif_get_longitude
• truxton_exif_set_longitude
• truxton_exif_get_longitude_offset
• truxton_exif_set_longitude_offset
• truxton_exif_get_altitude
• truxton_exif_set_altitude
• truxton_exif_get_altitude_offset
• truxton_exif_set_altitude_offset
• truxton_exif_get_heading
• truxton_exif_set_heading
• truxton_exif_get_heading_offset
• truxton_exif_set_heading_offset
• truxton_exif_get_focal_length
• truxton_exif_set_focal_length
• truxton_exif_get_focal_length_offset
• truxton_exif_set_focal_length_offset
• truxton_exif_get_shutter_count
• truxton_exif_set_shutter_count
• truxton_exif_get_shutter_count_offset
• truxton_exif_set_shutter_count_offset
• truxton_exif_get_thumbnail_offset
• truxton_exif_set_thumbnail_offset
• truxton_exif_get_thumbnail_offset_offset
• truxton_exif_set_thumbnail_offset_offset
• truxton_exif_get_thumbnail_length
• truxton_exif_set_thumbnail_length
• truxton_exif_get_thumbnail_length_offset
• truxton_exif_set_thumbnail_length_offset
• truxton_exif_get_make
• truxton_exif_set_make
• truxton_exif_get_make_offset
• truxton_exif_set_make_offset
• truxton_exif_get_model
• truxton_exif_set_model
• truxton_exif_get_model_offset
• truxton_exif_set_model_offset
• truxton_exif_get_body_serial_number
• truxton_exif_set_body_serial_number
• truxton_exif_get_body_serial_number_offset
• truxton_exif_set_body_serial_number_offset
• truxton_exif_get_lens_serial_number
• truxton_exif_set_lens_serial_number
• truxton_exif_get_lens_serial_number_offset
• truxton_exif_set_lens_serial_number_offset

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

• truxton_location_create
• truxton_location_destroy
• truxton_location_save
• truxton_location_get_id
• truxton_location_get_file_id
• truxton_location_set_file_id
• truxton_location_get_media_id
• truxton_location_set_media_id
• truxton_location_get_altitude
• truxton_location_set_altitude
• truxton_location_get_label
• truxton_location_set_label
• truxton_location_get_latitude
• truxton_location_set_latitude
• truxton_location_get_longitude
• truxton_location_set_longitude
• truxton_location_get_type
• truxton_location_set_type
• truxton_location_get_when
• truxton_location_set_when

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

• truxton_relation_create
• truxton_relation_destroy
• truxton_relation_save
• truxton_relation_get_a_id
• truxton_relation_set_a_id
• truxton_relation_get_b_id
• truxton_relation_set_b_id
• truxton_relation_get_source_id
• truxton_relation_set_source_id
• truxton_relation_get_a_type
• truxton_relation_set_a_type
• truxton_relation_get_b_type
• truxton_relation_set_b_type
• truxton_relation_get_source_type
• truxton_relation_set_source_type
• truxton_relation_get_relation
• truxton_relation_set_relation

Website Visit

• truxton_url_create
• truxton_url_destroy
• truxton_url_save
• truxton_url_get_account
• truxton_url_set_account
• truxton_url_get_account_offset
• truxton_url_set_account_offset
• truxton_url_get_file_id
• truxton_url_set_file_id
• truxton_url_get_format
• truxton_url_set_format
• truxton_url_get_id
• truxton_url_get_local_filename
• truxton_url_set_local_filename
• truxton_url_get_media_id
• truxton_url_set_media_id
• truxton_url_get_method
• truxton_url_set_method
• truxton_url_get_type
• truxton_url_set_type
• truxton_url_set_url
• truxton_url_get_url
• truxton_url_get_url_offset
• truxton_url_set_url_offset
• truxton_url_get_when
• truxton_url_set_when

USB Device

• truxton_usb_create
• truxton_usb_destroy
• truxton_usb_save
• truxton_usb_get_id
• truxton_usb_get_file_id
• truxton_usb_set_file_id
• truxton_usb_get_media_id
• truxton_usb_set_media_id
• truxton_usb_get_device_id
• truxton_usb_set_device_id
• truxton_usb_get_device_type
• truxton_usb_set_device_type
• truxton_usb_get_file_offset
• truxton_usb_set_file_offset
• truxton_usb_get_product_id
• truxton_usb_set_product_id
• truxton_usb_get_revision
• truxton_usb_set_revision
• truxton_usb_get_when
• truxton_usb_set_when
• truxton_usb_get_vendor_id
• truxton_usb_set_vendor_id