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.
sbag is a command line version of a Windows registry parser that targets the Shellbag subkeys to pull useful directory, and file, artifacts to help identify user activity. There are binaries available for Windows, Linux and Mac OS-X. The Windows version allows one to parse hives resident from a live system.
As background, the ShellBag information is a set of subkeys in a user registry hive (eg. ntuser.dat and usrclass.dat files) used by the Windows operating system to track user window viewing preferences. It does this by storing various Windows Explorer settings that relates to dimensions, settings, etc. This allows one to reopen the same folder at a later time with the settings restored from the previous time. Each user will have separate preferences for folders, and therefore, these settings are stored in the appropriate user hive.
Since the ShellBag subkeys store various metadata on how Windows Explorer items were arranged, and since they are recorded for each user, from a computer forensics standpoint, one can parse the data and pull out various pieces of information that relate to user interaction. When combined with other available computer artifacts, it could provide a more complete picture of what files were accessed, or deleted, by the user and from what storage device they were accessing (could be either an internal, external or network storage device). The 'ShellNoRoam\BagXxx' key(s) has data for local folders, and the 'Shell\BagXxx' key(s) has data for the remote folders.
The registry subkeys that sbag evaluates include the following::
On Vista and Windows 7, the UsrClass hive is new and is located in the C:\Users\<user>\AppData\Local\Microsoft\Windows directory.
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.
sbag is a console application, and thus, to use this tool on a live system, one will need to open the command prompt with administrator privileges first. One can display the menu options by typing in the executable name without parameters. While the menu shows a number of different options, the only required parameter to pass in is the user hive one wishes to extract shellbag artifacts from. The available options include: (a) annotating username and/or hostname to the output (version 0.23+), (b) specifying what type of format one wishes to put the output data in, (c) whether to extract data from cell slack space (version 0.24+), (d) various format options including date/time (version 0.29+), (e) the ability to pipe in hives for analysis (version 0.33+) and (f) the ability to parse all the user hives by either pointing a to drive letter or Volume Shadow copy (version 0.38).
The output options include: (a) the default output, where each record is on a separate line and each field is separated by the pipe character, (b) the SleuthKit body-file format [5], and (c) the log2timeline CSV (comma separated value) format. [6]
Below is the menu with the various options. Details of each option can be found here.
Usage: sbag -hive <user hive> [format options] sbag -partition <drive> = parse user hives given partition sbag -vss <num> = parse user hives from Vol Shadow sbag -livehives = list user hives available dir <somedir>\*ntuser* /b /s [/a:h] | sbag -pipe > out.txt Basic options -csv = output in comma separated value format -csvl2t = log2timeline output -bodyfile = sleuthkit output Additional options -base10 = use base10 for file size instead of hex -userstats = pull acct from hive [ntuser.dat only] -username <name> = output will contain this username -hostname <name> = output will contain this hostname -inc_slack = include slack data in parse -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 "|" = use a pipe char for separator -pipe = pipe user hives into sbag for processing -filter <*partial*|*.ext> = filters stdin data from -pipe option
Below is an example syntax of parsing a user hive in an off-line manner. For this example, it assumes a user hive was extracted to the c:\dump directory beforehand. To parse the hive, one could then invoke the following command:
sbag -hive c:\dump\ntuser.dat > results.txt
Since the output that is generated is very wide, it is recommended that one redirect the output of the command into a results file as show above. Then, it can be reviewed in any text editor by turning off the word wrap option to see each record on a separate line. If one wants to take advantage of the Comma Separate Value (CSV) format that is easily opened with any spreadsheet application, one could use the -csv option, like below:
sbag -hive c:\dump\ntuser.dat -csv > results.csv
The only difference in the results between the normal output and the CSV output is the CSV processed output is checked for any occurrences of commas. If any commas are found, they are changed into semicolons so as to not disrupt the CSV format for separating the fields. Thus, if one needs exact data without any possible modifications, one should choose the normal (default) output. The normal (default) output uses the pipe character '|' for a delimiter which does not conflict with any valid Windows filename syntax.
For starters, to access Volume Shadow copies, one needs to be running with administrator privileges. Also, it is important to note that, Volume Shadow copies as is discussed here, only applies to Windows Vista, Win7, Win8, and beyond. It does not apply to Windows XP.
To make it easier with the syntax, we've built in a shortcut syntax in order to more easily access a specific file in a specified Volume Shadow copy, via the %vss% keyword. This internally gets expanded into \\?\GLOBALROOT\Device\HarddiskVolumeShadowCopy. Thus, to access index 1 of the volume shadow copy, one would combine the keyword and index, index, (eg. %vss%1) in front of the normal path of the file. For example, to access a user hive located in the testuser account from the HarddiskVolumeShadowCopy1, the following syntax can be used:
sbag -hive %vss%1\Users\testuser\ntuser.dat > results.txt
In addition, one can process all the user related hives using the command sbag -vss <index of volume shadow>. This option will traverse the specified volume shadow copy and look for both ntuser.dat and usrclass.dat hives to process.
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 previous options.
One can process all the user hives on a specified volume (including the live system volume). This option is invoked with the following syntax:
sbag -partition <drive letter>
The above command only looks in the normal user's directories to find which hives are available, and then, proceeds to processes those hives. It is useful if mounting a collected image of a system volume as another drive letter.
For processing shellbag artifacts on a live system, one can use the -livehives option to enumerate the available hives that sbag can process.
Once the path of the location of the user hives are known, one can parse any of the desired hives by passing in the path of the active hive. For this type of live processing, sbag will take care of taking a snapshot of the requested hive by reading the appropriate raw NTFS clusters, and then, proceed to extract the artifacts from the snapshot.
For cases where there is sufficient slack space available in the registry cell value data, sbag will try to parse this data into some intelligible output. Since this option is still experimental, it has been added as a separate option one can invoke. This allows one to isolate the option should it exhibit any instability, until sufficient testing has been done. To use this option, use the -inc_slack switch.
There are a number of timestamps displayed in the output. Since the data resides in the user's registry hives (ntuser.dat and usrclass.dat), the parent registry subkey timestamp of the bag, or BagMRU entry, is displayed along with a modify/access/create timestamp that is pulled from the DOS timestamp of the ItemID List (or IDList). For some of the IDList's the DOS timestamp is not present, and for those cases, a blank entry is displayed.
Since the IDList has additional metadata about the target folder or file it references, it may contain the MFT entry (inode) and sequence number of the target. If present, sbag displays them in their own respective columns. One should note, however, if the sequence number is zero, one can interpret the target folder or file as residing on a non-NTFS partition, since the zero is an invalid sequence number.
When available, the size of the target file is displayed. This is most commonly populated with the Bags ItemPos parse rather than the BagMRU parse.
A Most Recently Used (MRU) indicator is displayed in the output for BagMRU entries to clearly show which registry subkey timestamp relates to the IDList entry
There is a column that identifies the source registry subkey and value name used. This was provided to allow an analyst to easily track where the entry was parsed from, and therefore, allow for independent verification of the results.
Starting with version 0.35, there is a new column in the output that contains related Bags subkey timestamps that are associated with the IDList in the BagMRU hierarchy. These additional timestamps are useful, in combination with the BagMRU timestamps, to give more insight to those entries that did not have a MRU indicator and when they were last updated.
Finally, a new metadata column was added with version 0.35 to account for additional data parsed from various devices. For portable devices, there is a wealth of information that is embedded, so this additional information is outputted in the metadata column.
Option | Description |
---|---|
-hive | Option to explicitly point a specific hive to process. The syntax is -hive <path of hive to process> . In older versions this switch was not needed, but as more options to process hives were included, we added this option to help the parsing of commandline parameters. |
-partition | Experimental. Enumerates user hives from a selected partition letter and parses any found. (Note: only looks for the standard user directories for the hives). The syntax is -partition <drive letter>. |
-vss | Experimental. Enumerates user hives from Volume Shadow and parses any found. (Note: only looks for the standard user directories for the hives). The syntax is -vss <index number of shadow copy>. Only applies to Windows Vista, Win7, Win8 and beyond. Does not apply to Windows XP. |
-livehives | Switch to enumerate the user hives on the current system. Since this option only makes sense when running sbag on a Windows box, this option will not show up when running on Linux or Mac OS-X. |
-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. |
-bodyfile | Outputs the data fields in accordance with the 'body-file' version3 specified in the SleuthKit. The date/timestamp outputted to the body-file is in terms of UTC. So if using the body-file in conjunction with the mactime.pl utility, one needs to set the environment variable TZ=UTC. |
-base10 | Ensure all size/address outputs are displayed in base-10 format versus hexadecimal format. Default is hexadecimal format. |
-username | Option is used to populate the output records with a specified username. The syntax is -username <name to use> . |
-hostname | Option is used to populate the output records with a specified hostname. The syntax is -hostname <name to use>. |
-userstats | Switch tells sbag to try to extract the user account name from the ntuser.dat hive and populate it in the data that is outputted. |
-pipe | Used to pipe files into the tool via STDIN (standard input). Each file passed in is parsed in sequence. |
-enumdir | Experimental. Used to process files within a folder and/or subfolders. Each file is parsed in sequence. The syntax is -enumdir <"folder"> -num_subdirs <#>. |
-filter | Filters data passed in via stdin via the -pipe option. The syntax is -filter <"*.ext | *partialname* | ...">. The wildcard character '*' is restricted to either before the name or after the name. An example of using the filter to screen out just user hives would be the following: dir C:\Users /b /s /a | cafae -pipe -filter "ntuser.dat|usrclass.dat" |
-inc_slack | Switch to extract and parse any slack data in the Bags ItemPosXxx value data. |
-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 |
-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. |
Field | Definition |
---|---|
regdate | Last registry modify date for this subkey |
reg-UTC | Last registry modify time for this subkey |
mru | If set, this entry was the last modified entry for the subkey |
mdate | Target modify date |
time-UTC (after mdate) | Target modify time |
adate | Target access date |
time-UTC (after adate) | Target access time |
cdate | Target create date |
time-UTC (after cdate) | Target create time |
type | file or dir |
bag | Bag subkey that is associated with this record |
file size | Target size |
inode | Target MFT entry (0 is an invalid entry) |
seq# | Target MFT entry sequence number |
full path | Target full path |
source subkey/value name | Registry subkey/name |
extra metadata | Extra data parsed out of IDList. This is embedded metadata that can include additional timestamps (both FILETIME which is expressed in UTC or OLE which is usually in local time), file/folder flags, thumbnail IDs, size (max and free) for portable devices with memory, and various other data. Thu |
bag registry dates related to this entry | Records associated bag entry and pulls registry subkey dates to help determine last activity of this record. |
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.