TZWorks LLC
System Analysis and Programming
www.tzworks.com
(Version 0.29; nx protocol ver: 0.08)
minx is a command line tool that runs on an endpoint target machine, acting as an agent to collect data from the endpoint and send it a central forensics workstation running the nx tool. Therefore, to understand minx, one needs to understand nx.
As background, the nx tool can act as both a client and server for the purposes of transferring data from one computer to a central computer. From a terminology standpoint, the server in this case, would be the forensic workstation gathering information during an incident response (not necessarily a Windows Microsoft Server). The clients would be those endpoint computers that are under investigation that would be sending information to the central forensics workstation. What can be confusing at first, is the nx tool can be both (a client and a server), depending on how the application was configured via the command line. minx and nx clients can co-exist and both work with an nx server.
The network relationship between the minx client and the nx service uses peer-to-peer communication. This is defined to be communications between two nodes, as opposed to multi-node or broadcast communication. For peer to peer communication, no domain credentials are required to be set up if deployed in an enterprise network. As long as minx can communicate to the nx service's IP address/port, without being impacted by firewalls or other network devices that can block IP traffic, the communications should be seamless.
When designing minx, and expanding the existing nx client capabilities, there were 3 main additional requirements levied by users: (a) the ability to copy files that were locked down by the operating system, (b) to have the client run from an internal script, such that a separate instance was not required for each command executed, and (c) image/copy raw bytes from a disk or volume.
The enhancements put into minx include: (a) an integrated NTFS engine to allow minx to copy any file from a host Windows computer by accessing the file data via raw cluster reads, (b) an ability to scan all drives attached to a Windows computer, (c) an ability to copy any number of bytes from a specific drive, (d) an internal directory enumerator with filtering to target specific files within one, or a group, of subdirectories, (e) the ability for to spawn other applications and either act on their output, (f) the ability pull common artifacts from all the volume shadow copies, and (g) an internal scripting engine that allows minx to receive instructions from the nx service and act on them.
The communications protocol between nx and minx is the same as the previous nx-client to the nx-server communication, with some additional changes to accommodate the enhanced features of minx. The network transport used is TCP/IP, with the data content encrypted in a RC4 stream cipher. To ensure data integrity from the client computer to the final archived file on the server, a hash is computed at client side before transmission, and during receipt by the server. A mismatch in hashes results in the archive file being labeled as having errors. Labels, comments and filenames are allowed to be passed during each data transfer, which are read by the server and acted upon accordingly. Currently, minx and nx are restricted to IPv4.
There are compiled versions for Windows, Linux and Mac OS X, and the architecture is such that each one is designed to play well with another instance operating on a different OS (eg. use nx on a Linux box as the server and use minx on a Windows client box to send data to the server).
To use this tool an enterprise license is required to be in the same directory as the binary in order for the tool to run.
One can display the menu options by typing in the executable name without parameters. Below is the menu with the various options. Details of each option can be found here.
Usage:
Connect to server
minx -ip <server ip addr> -port <server port #> [options]
Basic options
-key <"password"> = set the encryption key
-nx <lic num of nx> = only access nx using license # specified\n");
-ping = ping server and displays time stats
-quiet = don't echo what is being sent
-cust_id <label> = assoc transactions w/ this client label
-host_id <label> = assoc transactions w/ this host label
-pipe = use stdin to pipe in cmds.
-name <"tell server to use this filename to store results">
-comment <"insert a comment in the server log">
-subdir <folder> = store results in this subdirectory
-retain_path = store results in orig subdir context
Drive options
-scandrives = pull stats on all the drives
-copydrive <drive #> [-offset <start>] [-size <#>] [-gzip]
-copyvolume <partition letter> [-offset <start>] [-size <#>] [-gzip]
-copy_diskgaps <disk #> [-gzip] = pull sectors from disk# not tied to a vol
-copy_all_diskgaps[-gzip] = pull sectors from all disks not tied to a vol
-copy_bootfiles = pull MBR, VBR (vol boot record) files
File copy options
-copyfile <file> = specific file
-copydir <dir> [-level <#>] = entire folder and/or subdirectories
Combo copy options [for common collections of files]
-pull_sysfiles = pull $MFT, $UsnJrnl:$J files
-pull_reghives = pull system and user registry hives
-pull_evtlogs = pull system event logs
-pull_lnks = pull user LNK files and JumpLists
-pull_pfs = pull system prefetch files
-pull_systrash = pull recycle bin from system vol
-pull_all = pull all of the above
Targeting Volume shadow copy's that can be used with above options
-vssall <partition letter> = pull data from vol shadows
Enumerate directory examples
dir <folder> /b /s | minx64 -pipe -filter <*partial*|*.ext> -copyfile
minx64 -copydir <dir> -level <#> -filter <*partial*|*.ext>
Automation options [Experimental]
-script <script file> = run specified script
-get_cmds [-queryfile <script>] = get script from server
Examples of running client via piping cmds via stdin or copying files
ipconfig /all | minx64 -pipe -ip <serv> -port <#> -name ipconfig_all.txt
netstat -anob | minx64 -pipe -ip <serv> -port <#> -name netstat_anob.txt
wmic process list full | minx64 -pipe -ip <serv> -port <#> -name procs.txt
dir c:\*.pdf /b /s | minx64 -ip <serv> -port <#> -copyfile -pipe
To configure nx as a server to work with a minx client, both the nx and minx network protocols need to be in sync. This can be done by looking at the version of either of the tools protocol (which is different than the version of the tool). For example, version 0.27 is the first version of nx that is compatible with minx. The protocol used with version 0.27 of nx is version 0.08.
If you are unsure which version you have or need, then just run nx (or minx) at the command prompt; the tool will display the current version you have as well as what version of the protocol it is using. The protocol version matching allows for proper network handshaking between the minx client and the nx service. It is anticipated that the protocol will be rarely updated, so while the version number of the tools (nx and minx) will increment with each update, the protocol version typically will not.
To run nx in server mode, these are the required parameters:
The rest of the server parameters can be optional, depending on whether they are needed or not. For example, if you want to set up a session key, one can use the -key <password phrase>. If this is done, then the same <password phrase> needs to be used at the minx client end. This is <password phrase> is used to assist in the generation of the RC4 encryption key that is used. Without using the -key option, minx and nx still encrypts the data transferred over the network, but will use its own key generation algorithm.
Still in the experimental phase, if you want to have the nx server offer up scripts for the minx client to run, then use the -scripts <folder> option. Then when a request comes in from minx to retrieve a particular script, the above option tells the nx server where to look for them and then pass the script back to the minx client. Once minx receives the script, it will execute it and pass the results back to the nx server. This architecture allows the scripts to reside and be maintained on the server side. Thus, when a change is made to a script, all the minx clients will have access to the same modifications of the script when they run. More details about scripts and how to write them are discussed in the users guide.
In some situations it may be required to make use of a redirector to send data from a private network to the host computer running the nx service. To handle this use-case, we have the -redirect <ip addr> option available. This just tells nx service to expect minx network packets will be directed to another IP address prior to reaching the nx service. Since network configuration and IP and port redirection can be a complex topic it is discussed in the user's guide.
The final set of server options is for formatting the log file. Since the results log file is archived as a CSV type file, one can use the same TZWorks command options used in many of the other tools, such as: excluding whitespace between field delimiters (-no_whitespace), changing the field delimiter from a pipe character to a comma character (-csv_separator ","), changing the timestamp format (dateformat "yyyy/mm/dd") or grouping the date and time together (-pair_datetime).
Below is an example of setting up nx in server mode.
nx -server -dir c:\archive\case1 -ip 192.168.1.10 -port 2222
After invoking the above command, the operating system will request permission to open up a network connection at the port specified in the 'listen' mode. To configure nx to work with minx clients (or nx clients) on various networks, select the "public networks" option.
When configuring minx to talk to the nx service, one just needs to specify the same IP address and port number used when configuring the nx server, and then, append the desire command to whatever action is desired.
One should test out the network connectivity between the minx client and the nx service. To do this, one should try to 'ping' the server from the client computer using the -ping option. This will ensure the crypto is synchronized between minx and nx. Below is an example of doing this.
minx -ip 192.168.1.10 -port 2222 -ping
After the minx client and nx server connectivity has been verified, one can send artifacts from a client computer to the server in a couple of ways. These can be categorized into 3 groups: (a) running separate or built-in operating system tools and piping their output into minx to send to the server, (b) sending the contents of a file to the server with one of minx's copy options, and (c) sending raw bytes from a drive or the drive's statistics to the server.
This first example uses standard input to define which files to copy. In this case, we use the built-in Windows 'dir' command to enumerate all the prefetch files and send them into minx to copy. Asside from the server's IP address/port, the key options to do this are: -copyfile and -pipe.
dir c:\windows\prefetch\*.pf /b /s | minx -ip 192.168.1.10 -port 2222 -copyfile -pipe
The second example is similar to the first in that we will use standard input to send data to minx, but this time minx send the raw data directly to the server. This example enumerate all the networks connections and tells the server to store the resulting dataas "netstat_a.txt".
netstat -a | minx -ip 192.168.1.10 -port 2222 -name netstat_a.txt -comment "netstat -a"
This last example is just copying a set of files by explicity listing them. Because of the nature of these files, minx will automatically resort to raw cluster reads to copy the files.
minx -ip 192.168.1.10 -port 2222 -copyfile "c:\$MFT | c:\$Boot | c:\$Bitmap | c:\$Extend\$UsnJrnl:$J" -retain_path
One can use the optional -copydir <folder> to copy a directory and if wishing to go to subdirectories as well, use the -level <#> option. If desiring to filter out certain patterns, one can use the -filter <*partial*|*.ext> option. When using all this options complex directory enumeration can occur. Below are some examples:
// copy all user registry hives
minx -ip 192.168.1.10 -port 2222 -copydir "C:\users" -level 6 -filter "ntuser.dat*|usrclass.dat*" -retain_path
// copy LNK and JumpLists
minx -ip 192.168.1.10 -port 2222 -copydir "C:\users" -level 9 -filter "*.lnk|*ions-ms" -retain_path
// copy some registry hives
minx -ip 192.168.1.10 -port 2222 -copydir "%systemroot%\system32\config" -level 0 -filter "sam|security|system|software" -retain_path
The additional option of -retain_path was used to tell the server to store the copied files in their proper directory structure. The default copy action would store each file contents in a subfolder that matches the source target machine which would be the IP address/hostname of the source machine. More details about this and changing it are discussed in the user's guide.
There is a set of options that are command shortcuts that make use of the various internal options to copy common collections of files. These include:
| Group Option | Files Targeted |
|---|---|
| -pull_sysfiles | $MFT, $Boot, $LogFile, $Bitmap, $BadClus:$Bad, &UsnJrnl:$J files |
| -pull_reghives | User and OS level (system, software, security, etc) registry hives |
| -pull_evtlogs | Event and setupapi logs |
| -pull_lnks | LNK and JumpList files |
| -pull_pfs | prefetch files |
| -pull_systrash | Recycle Bin directory on the system drive |
| -pull_all | All pre-defined groups above |
There are groups for registry hives, event logs, prefetch files, LNK/JumpList, trash entries, and system files. One can use one or more of the options listed above in one session, or just invoke the -pull_all parameter to tell minx to pull all pre-canned artifacts. minx will discern which version of the Windows operating system the tool is running on so the proper default directories are targeted for the file groups selected. The other nice aspect about this option is it will spawn multiple instances to go after the specific groups. For computers with multiple cores, this will result in a faster copy.
By default, all files that are generated on the server side use the following syntax:
<md5hash>_<filename that was provided by client>
The above behavior makes for long filenames, but it ensures that each modified filename is unique so filenames that were previously the same (in their original form) are not overwritten. If this default behavior is not desired, one can use the -retain_path option instead, which will store the files in their original subdirectories.
Finally, there will be a results file in a quasi-CSV format that will contain all metadata that was gathered during the transaction. This results file uses the following syntax:
<readable date>_<readable time>_results.csv
<readable date> = yyyy_mm_dd
<readable time> = hhmm_ss_msec , where hhmm = 24 hour format
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:
minx64 -ip 192.168.1.10 -port 2222 -copyfile %vss%3\Users\testuser\ntuser.dat
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 appended to the %vss% keyword.
The second flavor of targeting artifacts in the volume shadow copies is to use the -vssall <partition letter>. This instructs minx to analyze all volume shadow copies on that volume and pull the requested files requested.
Since minx has the capability to pull the file contents by reading raw clusters, this functionality is extended to perform imaging of volumes, drives and/or specific sectors.
One should keep in mind that imaging over the network can be very slow when considering disk densities are extremely large in today's age, clearly making network imaging not the choice method. With that in mind, this capability is provided, if it is needed. The imaging format available for minx does not allow for E01 or AFF formats, but only in the raw 'dd' format. One, however, can compress the 'dd' image by using the -gzip option. The compression uses the zlib library and will make use of multiple threads to process the raw data in parallel chunks to minimize the processing image of the compression.
When using the default option, the extension used for the resulting image file will be ".dd". If using the compression option (-gzip), then the extension used will be ".gz". The other naming convention is to use the following syntax to represent the drive image name.
<MD5 hash>_drive_<#>_offset_<starting offset>_<ending offset>.[dd | gz]
To copy specific raw sectors of a drive, one should understand the details of the drives on the system. Specifically, one needs to know: (a) the physical drive number of the device, (b) the device volume offsets and (c) the number of bytes for each volume. There are a number of built in Windows tools to get this information, but an easy way is just to use the -scandrives option in minx. This option will enumerate all the drives attached on the target system and output the results to the console (as well as send the results to the nx server). From the data, one will be able to find the starting/ending offset of a volume along with its signature. Based on this data, one can extract volume data using the starting offset and desired number of bytes one wishes to extract.
If desiring to image an entire drive one would use the -copydrive <#> option without specifying either the -offset or the -size options. To have the results compressed, use the -gzip option.
If desiring to image an entire volume one would use the -copyvolume <partition letter> option without specifying either the -offset or the -size options. To have the results compressed, use the -gzip option.
If interested in boot sectors, whether it is from the master boot record or volume boot record, one can use the -copy_bootfiles option.
If interested in locations on the drive that may be used by malware for persistence storage, one can use the -copy_diskgaps <#> or -copy_all_diskgaps options. The first one targets a specific disk, whereas the second pulls the disk gaps from all the drives on the system.
Refer to the user's guide for details about this subject.
| Option | Description |
|---|---|
| -ip | IP address of the server. The syntax is: -ip <server IP address>. |
| -port | Port address of the server. The syntax is: -port <server port address>. |
| -key | If network encryption is required, this is the symmetric key to use. If used, the same key is needed for both the minx client and nx server. The syntax is: -key <password phrase>. |
| -nx | If one wants to run minx without a license file, then one can use the license number of the nx server, as follows: nx <license number>. |
| -ping | Option for the client to check whether the server is up and synchronized time statistics. These statistics are recorded in the server side logs. |
| -quiet | Option for minx to not echo to the user what is being sent to the server. |
| -cust_id | Option for the client to identify itself to the server with a unique client label. This label is associated with all the files sent by this client. The syntax is: -cust_id <label>. |
| -host_id | Option for the client to identify itself to the server with a unique host label. This label is associated with all the files sent by this client. The syntax is: -host_id <label>. |
| -pipe | Used to pipe files or commands into the tool via STDIN (standard input). Each file passed in is parsed in sequence. |
| -copydir | Option to enumerate a directory or subdirectories without using the piping option. The -level sub-option specifies how deep to look in the subdirectories. A value of 0 (which is the default), means just the current directory. The -filter is discussed later as its own separate option. The syntax is: -copydir <dir> -level <#> -filter <*partial*|*.ext>. |
| -name | Option for the client to request the server to use the specified filename to archive the results. The syntax is: -name <filename>. |
| -comment | Option for the client to send to the server to make a comment in the logs stored on the server session side. The syntax is: -comment <"phrase">. |
| -filter | Filters data passed in via stdin via the -pipe option or via the -enumdir option. The syntax is -filter <"*.ext | *partialname* | ...">. The wildcard character '*' is restricted to either before the name or after the name. |
| -copyfile | Option for the client to copy a specified file and send it to the server. The syntax is: -copyfile <file to copy>. Can also be used for copy more than one file if delimiting the other files with a pipe character: -copyfile <file1 | file2 | ...> |
| -retain_path | Option to store the copied file in the original subdirectory tree as the target. Default (without this option) is to copy all the files in a common subdirectory; and files are prepended with a MD5 hash to ensure files with like names are not overwritten |
| -scandrives | Enumerates the drives on the host machine and pull stats, including volume information. |
| -copydrive | Copies raw sectors from a specified drive. The syntax is: -copydrive <drive #> -offset <start> [-size <#>]. |
| -script | If one wants to run minx with a script, use this option. The syntax is: -script <script file>. |
| -get_cmds | This instructs minx to contact the nx server and ask if any scripts are available to run. If a script is present on the server side, it will be sent to the minx client and minx will execute it. The optional sub argument allows minx to specify which script file for the nx server to send to it. The syntax is: -get_cmds [-queryfile <script>]. |
This tool requires an enterprise type license to run.
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.