TZWorks LLC
System Analysis and Programming
www.tzworks.com
(Version 0.79)
TZWorks LLC software and related documentation ("Software") is governed by separate licenses issued from TZWorks LLC. The User Agreement, Disclaimer, and/or Software may change from time to time. By continuing to use the Software after those changes become effective, you agree to be bound by all such changes. Permission to use the Software is granted provided that (1) use of such Software is in accordance with the license issued to you and (2) the Software is not resold, transferred or distributed to any other person or entity. Refer to your specific EULA issued to for your specific the terms and conditions. There are 3 types of licenses available: (i) for educational purposes, (ii) for demonstration and testing purposes and (iii) business and/or commercial purposes. Contact TZWorks LLC (info@tzworks.com) for more information regarding licensing and/or to obtain a license. To redistribute the Software, prior approval in writing is required from TZWorks LLC. The terms in your specific EULA do not give the user any rights in intellectual property or technology, but only a limited right to use the Software in accordance with the license issued to you. TZWorks LLC retains all rights to ownership of this Software.
The Software is subject to U.S. export control laws, including the U.S. Export Administration Act and its associated regulations. The Export Control Classification Number (ECCN) for the Software is 5D002, subparagraph C.1. The user shall not, directly or indirectly, export, re-export or release the Software to, or make the Software accessible from, any jurisdiction or country to which export, re-export or release is prohibited by law, rule or regulation. The user shall comply with all applicable U.S. federal laws, regulations and rules, and complete all required undertakings (including obtaining any necessary export license or other governmental approval), prior to exporting, re-exporting, releasing, or otherwise making the Software available outside the U.S.
The user agrees that this Software made available by TZWorks LLC is experimental in nature and use of the Software is at user's sole risk. The Software could include technical inaccuracies or errors. Changes are periodically added to the information herein, and TZWorks LLC may make improvements and/or changes to Software and related documentation at any time. TZWorks LLC makes no representations about the accuracy or usability of the Software for any purpose.
ALL SOFTWARE ARE PROVIDED "AS IS" AND "WHERE IS" WITHOUT WARRANTY OF ANY KIND INCLUDING ALL IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR ANY PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL TZWORKS LLC BE LIABLE FOR ANY KIND OF DAMAGE RESULTING FROM ANY CAUSE OR REASON, ARISING OUT OF IT IN CONNECTION WITH THE USE OR PERFORMANCE OF INFORMATION AVAILABLE FROM THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY DAMAGES FROM ANY INACCURACIES, ERRORS, OR VIRUSES, FROM OR DURING THE USE OF THE SOFTWARE.
The Software are the original works of TZWorks LLC. However, to be in compliance with the Digital Millennium Copyright Act of 1998 ("DMCA") we agree to investigate and disable any material for infringement of copyright. Contact TZWorks LLC at email address: info@tzworks.com, regarding any DMCA concerns.
usp is a command line version of a tool that finds documented USB storage device artifacts on an NTFS system volume. Sources of artifacts include the registry hives as well as some log files that Windows updates autonomously when a USB device is inserted into a computer. One of the issues usp solves is taking artifacts from different locations and matching like entries to connect scattered information into a quick look report. The artifacts usp analyzes are documented in various publications. See references below.
In the reports that usp generates, we avoid putting statements like the 'last time USB device was inserted' and opted to put the last write time of selected registry keys. From empirical testing, it was found, in certain cases, the last write time of a selected registry key did not necessarily correlate to the last insert time of a specific USB device. While these were corner cases, we did not want to mislead any user in the outputs produced by this tool.
usp was designed so that it could be compiled to run on any operating system to analyze Windows USB storage artifacts, but can also work on a live Windows system. When analyzing a live system, usp accesses the raw clusters to pull out the registry information. This means it is slower that if it was implemented to directly access the Windows registry API's. Making the engine Windows API agnostic causes usp to take snapshots of the registry hives and certain logs directly from raw clusters on the live volume to produce results.
When processing images of NTFS volumes in an off-line manner, usp expects to parse an image that is a 'bit-for-bit' copy of the original volume (eg. images obtained with a 'dd' or similar type tool).
This version of usp has been compiled to run on Windows, Linux and Mac OS-X.
To use this tool, an authentication file is required to be in the same directory as the binary in order for the tool to run.
Since usp is a command line tool, one will need to open the command prompt. Below is the menu with the various options. Details of each option can be found here.
Usage usp -sys <hive> -user <hive> -setupapi <file> [-sw <hive>] [-evtx <log>] usp -livesys = pull from live computer usp -image <file> [-offset <vol offset>] = use image as source usp -vmdk "file1 | file2 | .." = process a VMWare volume usp -drivenum <#> [-offset <vol>] = use drive num as source usp -partition <drive letter> = use partition as source usp -vss <index> = use vol shadow as source Basic Options -csv = output is comma separated value format -csvl2t = log2timeline output -v = verbose, multiple lines per record -sys "hive1 | hive2 | ..." = use specified system hives -user "hive1 | hive2 | ..." = add user hive(s) to analysis -setupapi "file1 | file2 | .." = add setupapi file(s) to analysis -sw "hive1 | hive2 | ..." = add software hives to analysis -amcache "file1 | file2 | .." = add amcache file(s) to analysis -evtx "file1 | file2 | .." = add eventlog(s) to analysis Additional Options -dateformat mm/dd/yyyy = "yyyy-mm-dd" is the default -timeformat hh:mm:ss = "hh:mm:ss.xxx" is the default -pair_datetime = combine date/time into 1 field for csv -no_whitespace = remove whitespace between csv delimiter -csv_separator "|" = change csv delimiter to a pipe char -all_usb_devices = pull stats on all USB devices -base10 = use base10 for evtx records numbers New (Experimental) Options -pipe = pipe specially named files to process -inc_regback = include primary and backup system hives -show_other_times = show other times [uses -pair_datetime] -show_files_used = show files contributing to USB device -use_eventlogs = incl event logs for additional times -event_res <# secs> = group evtx records by # sec intervals
usp -livesys
The default output is stats on each USB device on one line using a delimiter per entry. It is best to redirect the output to a file, since the lines are very long to display the information. Below is an example:
usp -livesys > results.txt
usp -image <disk image> [-offset <volume offset>]
After extracting the needed files: (a) the appropriate hives from %windir%\system32\config\system and %userprofile%\ntuser.dat, (b) the setupapi log(s) from %windir%\setupapi.log (xp) or %windir%\inf\setupapi.dev.log (vista and later), one can invoke usp on the extracted files:
usp -sys <system hive> [-user <user hive>] [-sw <software hive>] [-setupapi <file>] [-csv]
The first set of experimental options is to analyze an external drive that has a system partition on it. First, it requires one to know the physical drive number and volume offset within the drive that has the system partition. The second one, assumes one can mount the external drive as a drive letter.. Both of these options assume the partition has a system partition.
usp -drivenum <num> [-offset <volume offset>] usp -partition <drive letter>
For VMWare Virtual hard drives that only have 1 partition on it, one can use this experimental option. This also assumes the VMWare drive is signatured as 'KDMV' and is a monolithic type drive (eg. the drive is not broken into separate files).
usp -vmdk <VMDK disk file>
For Volume Shadow Copies, the option -vss <index of volume shadow> was added. Invoking this option will tell usp to extract and parse all relevant and available artifacts from the specified Volume Shadow Copy.
To determine which indexes are available from the various Volume Shadows, one can use the Windows built-in utility vssadmin, as follows:
vssadmin list shadows -- or to filter out extraneous detail -- vssadmin list shadows | find /i "volume"
While the amount of data can be voluminous from that above command, the keywords one needs to look for are names that look like this:
Shadow Copy Volume: \\?\GLOBALROOT\Device\HarddiskVolumeShadowCopy1
Shadow Copy Volume: \\?\GLOBALROOT\Device\HarddiskVolumeShadowCopy2
...
From the example above, notice the number after the word HarddiskvolumeShadowCopy. This would be the number that is passed as an argument to the -vss option.
Use the -use_eventlogs option to incorporate evtx type event logs.
Added with the version 0.55 of usp is the ability to parse event log data from evtx type logs and integrate it with the USB results collected from the registry hives and setupapi logs. Since this is a new feature, it is still experimental in nature. Currently, up to four log files are can be analyzed:
From the logs listed above, certain events are enumerated and categorized into 3 areas:
Additional data can be extracted with the Microsoft-Windows-Partition%4Diagnostic.evtx log, such as the, partition table and volume boot record of the USB device (if present). Since event log data can be noisy, in the sense, that many events can be recorded during one of the categories above (insert, remove or delete), the usp tool will collate clusters of events within a set interval and report each cluster as a significant event. Even though this clustering is done for reporting purposes, the tool provides traceability down to the record numbers used during a cluster operation, so the analyst can go back to a particular event log and look up the specific event record, if desired.
The following shorthand notation is used when reporting event log artifacts:
When Microsoft-Windows-Partition%4Diagnostic.evtx event log is present, then usp can examine some of the partition and volume boot record data. Below is an example and the type of format the data is put in. Volume offset, volume size, disk signature, volume signature, partition type, and other data is displayed as shown below. The output below shows the numbers in hex. If desiring to view the size and offset numbers in base10, then one can use the -base10 option.
Partition table: vol1;byte_offset:0x4c0000;num_bytes:0x1e7340000;disk_sig:2e47-c29a;vol_type:fat32 Volume boot record data: sysid:fat32;sector_size(bytes):0x200;cluster_size(bytes):0x1000;media:hard_disk;partition_size(bytes):0x1e7340000;vol_sig:34c7-f6a3
While there is more data in these types of events, only some of the information that was present in the partition and volume boot record is displayed. If wanting to get all the data, one can use either the evtwalk or evtx_view tools and navigate to the appropriate record# displayed in the usp report.
In the output, there are various timestamps taken from various locations in the registry as well as the setup API log.
Device name: Imation Pivot USB Device vid/pid key update [UTC]: 08/17/2016 07:41:25.418 ven/prod/rev key update [UTC]: 08/17/2016 07:41:25.442 Disk Device update [UTC]: 08/11/2016 20:10:36.605 Volume Device update [UTC]: 08/11/2016 20:10:36.615 SetupAPI Log dates: [Inst: 08/11/2016 15:58:49.919 Local]; [Inst: 08/11/2016 15:58:50.554 Local]; [Inst: 08/11/2016 15:58:51.787 Local] Eventlog dates: [UTC]: [EVTX_INS_KP#371: 08/11/2016 19:58:50.103 UTC] DEVPKEY InstallDate [UTC]: 08/11/2016 19:58:49.919 DEVPKEY LastArrivalDate [UTC]: 08/17/2016 07:42:18.467 DEVPKEY LastRemovalDate [UTC]: 08/17/2016 19:58:12.961 Instance ID/Serial #: 3610a4a42ca185&0 Container ID: db16f407-665f-519d-bed8-eb2a02b37ef1 Volume ID: 13a6e427-5f16-11e6-adc9-00a0c6000021 Embedded time in Volume ID: 08/10/2016 16:18:30.500 Embedded MAC in Volume ID: 00-a0-c6-00-00-21 Disk ID: 13a6e425-5f16-11e6-adc9-00a0c6000021 Embedded time in Disk ID: 08/10/2016 16:18:30.500 Embedded MAC in Disk ID: 00-a0-c6-00-00-21 Volume name: PILOT Volume name update [UTC]: 08/11/2016 19:58:52.130 Parent ID Prefix: <none found> <-- usually on older OS's Vendor ID: 0718 Product ID: 0359 Revision: 1.20 Vendor/product: imation/pivot USB hub/port used: 03/01 Acct that mounted vol: loan acct, on 08/11/2016 20:19:01.226 [UTC] InventoryDevicePnp [UTC]: 01/24/2018 04:45:40.964 Vol serial/name/last time(s): d20f-7ce1/xfer : 08/11/2016 19:58:50.100 [UTC] System hive details: C:\windows\system32\config\system [09/27/2016 03:54:25.037 UTC] [md5:50dd4eb15c0d4babb4df52e76c70e9a3] Software hive details: C:\windows\system32\config\software [09/27/2016 03:50:37.476 UTC] [md5:f33b456fc7abe55f2e4feb2d255df261] ntuser hive details: C:\users\tzlabs\ntuser.dat [09/27/2016 03:54:30.051 UTC] [md5:171fa4440c263403e121e85351dd9051] SetupAPI log details: C:\windows\inf\setupapi.dev.log [md5:9b5a2467745327fc98da82522da06579] Amcache hive details: C:\windows\AppCompat\Programs\Amcache.hve [md5:c13e7636db33c2259d4a12e520a0cd71] Eventlog details: C:\windows\System32\winevt\logs\Microsoft-Windows-Kernel-PnP%4Configuration.evtx [md5:bec83b52-a603-b337-499d-b8cccdc40dbd]
Below is a listing of where each of the timestamps is extracted.
Option | Description |
---|---|
-csv | Outputs the data fields delimited by commas. Since filenames can have commas, to ensure the fields are uniquely separated, any commas in the filenames get converted to spaces. |
-csvl2t | Outputs the data fields in accordance with the log2timeline format. |
-v | Verbose output. This option will output the parsed data as multiple lines for one record inputted. |
-pipe |
This is an experimental option. Used to pipe files into the tool via STDIN (standard input).
Tool will pull in all files first
and begin parsing after last file is inputted. The set of files will be processed in one session. There are
naming restrictions for the files that are processed. Specifically: (a) System hives must have the sequence of letters
"system" in the name for it to be recognized as a system hive. (b) Software hives must have the sequence of letters
"software" in the name to be recognized as a software hive. (c) ntuser.dat hives must have the sequence of letters "user"
in the name to be recognized as a ntuser.dat hive. (d) setupapi.[dev].log files must have the sequence of letters "setup"
of letters in the name to be recognized as a log file. As long as the each of the respective artifact files has the requisite sequence of letters, then any other letters can go before or after the sequence. |
-enumdir |
Experimental. Used to process files within a folder and/or subfolders. Each file is parsed in sequence.
Tool will pull in all files first
and begin parsing after last file is inputted. The set of files will be processed in one session. There are
naming restrictions for the files that are processed. Specifically: (a) System hives must have the sequence of letters
"system" in the name for it to be recognized as a system hive. (b) Software hives must have the sequence of letters
"software" in the name to be recognized as a software hive. (c) ntuser.dat hives must have the sequence of letters "user"
in the name to be recognized as a ntuser.dat hive. (d) setupapi.[dev].log files must have the sequence of letters "setup"
of letters in the name to be recognized as a log file. As long as the each of the respective artifact files has the requisite sequence of letters, then any other letters can go before or after the sequence. The syntax is -enumdir <"folder"> -num_subdirs <#>. |
-sys | Use the specified system hive during the parsing. Syntax is -sys <system hive>. To specify multiple user hives, use the syntax: -sys "<hive1> | <hive2> | ...". When specifying multiple system hives, usp tries to match any additional system hives with any additional software hives. |
-user | Use the specified user hive(s) during the parsing. Syntax is -user <user hive>. To specify multiple user hives, use the syntax: -user "<user hive1> | <user hive2> | ..." |
-setupapi | Use the specified setup API log during the parsing. Syntax is -setupapi <logfile>. To specify multiple setup API logs, use the syntax: -setupapi "<log1> | <log2> | ..." |
-sw | Use the specified software hive during the parsing. Syntax is -sw <software hive>. To specify multiple sw hives, use the syntax: -sw "<hive1> | <hive2> | ...". |
-amcache | Use the specified AmCache hive during the parsing. Syntax is -amcache <hive>. |
-evtx | Use the specified event log(s) during the parsing. Syntax is -evtx <log>. To specify multiple evtx logs, use the syntax: -evtx "<log1> | <log2> | ...". |
-livesys | Pull USB stats from the live system |
-inc_regback | When used in conjunction with targeting a volume, tells usp to also look at the backup system and software hives as well as the primary system and software hives. The output will merge the data appropriately. |
-partition | Extracts USB artifacts from a mounted Windows volume. The syntax is -partition <drive letter>. |
-vmdk | Extracts USB artifacts from a VMWare monolithic NTFS formatted volume. The syntax is -vmdk <disk name>. For a collection of VMWare disks that include snapshots, one can use the following syntax: -vmdk "<disk1> | <disk2> | ..." |
-drivenum | Extracts USB artifacts from a mounted disk specified by a drive number and volume offset. The syntax is -drivenum <#> -offset <volume offset> |
-image | Extracts USB artifacts from a volume specified by an image and volume offset. The syntax is -image <filename> -offset <volume offset> |
-vss | Parse USB artifacts from Volume Shadow. The syntax is -vss <index number of shadow copy>. Only applies to Windows Vista, Win7, Win8 and beyond. Does not apply to Windows XP. |
-no_whitespace | Used in conjunction with -csv option to remove any whitespace between the field value and the CSV separator. |
-csv_separator | Used in conjunction with the -csv option to change the CSV separator from the default comma to something else. Syntax is -csv_separator "|" to change the CSV separator to the pipe character. To use the tab as a separator, one can use the -csv_separator "tab" OR -csv_separator "\t" options. |
-dateformat | Output the date using the specified format. Default behavior is -dateformat "yyyy-mm-dd". Using this option allows one to adjust the format to mm/dd/yy, dd/mm/yy, etc. The restriction with this option is the forward slash (/) or dash (-) symbol needs to separate month, day and year and the month is in digit (1-12) form versus abbreviated name form. |
-timeformat | Output the time using the specified format. Default behavior is -timeformat "hh:mm:ss.xxx" One can adjust the format to microseconds, via "hh:mm:ss.xxxxxx" or nanoseconds, via "hh:mm:ss.xxxxxxxxx", or no fractional seconds, via "hh:mm:ss". The restrictions with this option is that a colon (:) symbol needs to separate hours, minutes and seconds, a period (.) symbol needs to separate the seconds and fractional seconds, and the repeating symbol 'x' is used to represent number of fractional seconds. (Note: the fractional seconds applies only to those time formats that have the appropriate precision available. The Windows internal filetime has, for example, 100 nsec unit precision available. The DOS time format and the UNIX 'time_t' format, however, have no fractional seconds). Some of the times represented by this tool may use a time format without fractional seconds and therefore will not show a greater precision beyond seconds when using this option. |
-pair_datetime | Output the date/time as 1 field vice 2 for csv option |
-all_usb_devices | The default behavior of usp is to try to pull data on those USB devices that store data. Typically, these are labeled as USBSTOR devices. If one wants to expand the data returned to be all USB devices, use this switch. Keep in mind every USB device that was connected to the computer will be displayed, including: HID (human interface devices, like mice and keyboards), USBHUBs, and other non-USBSTOR devices. |
-base10 | Added for the evtx logs. The default behavior is to use hex for numbers. This says to use base10 for evtx records numbers and other related data in the eventlogs. |
-show_other_times | Experimental Option. This switch will display any additional timestamps found or derived. This option will also force the -pair_datetime option to allow rendering of multiple timestamps within a CSV field. Multiple timestamps in a field are delimited by semicolons. |
-show_files_used | Experimental Option. This switch will display which artifact files contributed to a specific device report data. |
-use_eventlogs | Experimental Option. Tells the tool to evaluate USB artifacts in the evtx type logs. |
-event_res | Experimental Option. When looking at evtx logs, group events into intervals separated byte # seconds. The default is 2 seconds. This option also affects the SetupAPI log data similarly. Syntax is: -event_res <# secs> |
-utf8_bom | All output is in Unicode UTF-8 format. If desired, one can prefix an UTF-8 byte order mark to the CSV output using this option. |
This tool has authentication built into the binary. The primary authentication mechanism is the digital X509 code signing certificate embedded into the binary (Windows and macOS).
The other mechanism is the runtime authentication, which applies to all the versions of the tools (Windows, Linux and macOS). The runtime authentication ensures that the tool has a valid license. The license needs to be in the same directory of the tool for it to authenticate. Furthermore, any modification to the license, either to its name or contents, will invalidate the license.
The tools from TZWorks will output header information about the tool's version and whether it is running in limited, demo or full mode. This is directly related to what version of a license the tool authenticates with. The limited and demo keywords indicates some functionality of the tool is not available, and the full keyword indicates all the functionality is available. The lacking functionality in the limited or demo versions may mean one or all of the following: (a) certain options may not be available, (b) certain data may not be outputted in the parsed results, and (c) the license has a finite lifetime before expiring.