target-query

target-query is a tool used to query specific data inside a one or more targets. These queries are available in the form of functions that reside within plugins. Each plugin is focussed on providing specific functionality.

This functionality can range from parsing log sources, such as command history logs (i.e. bash history, PowerShell history, etc.), to returning the hostname and operating system version.

The most basic usage of target-query is to execute a function on a target:

$ target-query -f <FUNCTION_NAME> /example_path/target.vmdk

You can also use basic path expansion to execute functions over multiple targets. For example, to execute a function on all .vmdk files in a directory:

$ target-query -f <FUNCTION_NAME> /example_path/*.vmdk

See also

Please refer to Use-cases for more examples of how to use target-query.

Usage

target-query - CLI interface

dissect.target

target-query [-f FUNCTION] [-xf EXCLUDED_FUNCTIONS] [-n] [--child CHILD] [--children]
             [-l [LIST]] [-s] [-d ','] [-j] [--limit LIMIT] [--no-cache] [--only-read-cache]
             [--rewrite-cache] [--cmdb] [--hash] [--resolve] [--report-dir REPORT_DIR]
             [-K KEYCHAIN_FILE] [-Kv KEYCHAIN_VALUE] [-L LOADER] [-v] [--version] [-q]
             [--plugin-path PLUGIN_PATH [PLUGIN_PATH ...]]
             [TARGETS ...]

target-query positional arguments

  • TARGETS - Targets to load (default: None)

target-query optional arguments

  • -f FUNCTION, --function FUNCTION - function to execute (default: None)

  • -xf EXCLUDED_FUNCTIONS, --excluded-functions EXCLUDED_FUNCTIONS - functions to exclude from execution (default: )

  • -n, --dry-run - do not execute the functions, but just print which functions would be executed

  • --child CHILD - load a specific child path or index (default: None)

  • --children - include children

  • -l LIST, --list LIST - list (matching) available plugins and loaders (default: None)

  • -s, --strings - print output as string

  • -d ',', --delimiter ',' (default: )

  • -j, --json - output records as json

  • --limit LIMIT - limit number of produced records (default: None)

  • --no-cache, --ignore-cache - do not use file based caching

  • --only-read-cache - only read cache files, never write them (has no effect if –no-cache is specified

  • --rewrite-cache - force cache files to be rewritten (has no effect if either –no-cache or –only-read-cache are specified)

  • --cmdb

  • --hash - hash all paths in records

  • --resolve - resolve all paths in records

  • --report-dir REPORT_DIR - write the query report file to the given directory (default: None)

  • -K KEYCHAIN_FILE, --keychain-file KEYCHAIN_FILE - keychain file in CSV format (default: None)

  • -Kv KEYCHAIN_VALUE, --keychain-value KEYCHAIN_VALUE - passphrase, recovery key or key file path value (default: None)

  • -L LOADER, --loader LOADER - select a specific loader (i.e. vmx, raw) (default: None)

  • -v, --verbose - increase output verbosity (default: 0)

  • --version - print version

  • -q, --quiet - do not output logging information

  • --plugin-path PLUGIN_PATH - a file or directory containing plugins and extensions (default: None)

For more information on the -K, --keychain-file and -Kv, --keychain-value arguments, please refer to Disk encryption (FVE).

The -f, --function argument

Since target-query is based on functions, the -f, --function argument is required. Its usage is simple, supply the argument followed by the function(s) that you wish to run on the target(s). So if you wish to run the runkeys function, it would look something like this:

$ target-query -f runkeys targets/EXAMPLE.tar
<windows/registry/run hostname='EXAMPLE' domain='EXAMPLE.local' ts=2021-02-08 15:33:17.949652+00:00 name='SecurityHealth' path='%windir%/system32/SecurityHealthSystray.exe' key='HKEY_LOCAL_MACHINE\\Software\\Microsoft\\Windows\\CurrentVersion\\Run' hive_filepath='sysvol/windows/system32/config/SOFTWARE' username=None user_sid=None user_home=None>
<windows/registry/run hostname='EXAMPLE' domain='EXAMPLE.local' ts=2021-02-08 15:33:17.949652+00:00 name='VMware VM3DService Process' path='"C:/Windows/system32/vm3dservice.exe" -u' key='HKEY_LOCAL_MACHINE\\Software\\Microsoft\\Windows\\CurrentVersion\\Run' hive_filepath='sysvol/windows/system32/config/SOFTWARE' username=None user_sid=None user_home=None>
<windows/registry/run hostname='EXAMPLE' domain='EXAMPLE.local' ts=2021-02-08 15:33:17.949652+00:00 name='VMware User Process' path='"C:/Program Files/VMware/VMware Tools/vmtoolsd.exe" -n vmusr' key='HKEY_LOCAL_MACHINE\\Software\\Microsoft\\Windows\\CurrentVersion\\Run' hive_filepath='sysvol/windows/system32/config/SOFTWARE' username=None user_sid=None user_home=None>
<windows/registry/run hostname='EXAMPLE' domain='EXAMPLE.local' ts=2021-12-09 12:06:20.037806+00:00 name='OneDriveSetup' path='C:/Windows/SysWOW64/OneDriveSetup.exe /thfirstsetup' key='HKEY_CURRENT_USER\\Software\\Microsoft\\Windows\\CurrentVersion\\Run' hive_filepath='C:\\Windows/ServiceProfiles/LocalService/ntuser.dat' username='LocalService' user_sid='S-1-5-19' user_home='%systemroot%\\ServiceProfiles\\LocalService'>

You can also execute multiple functions at the same time by separating each function name with a comma (,). For example -f hostname,version. Functions can have one of the following different output types:

This also means that functions with different output types cannot be run to together.

To list all available plugin functions and their description you can use the target-query --list argument to get an overview. More detailed information on a specific plugin’s function can be obtained using target-query -f [FUNCTION_NAME] -h.

The --child argument

The --child argument can be used to query a specific child within a target, for example when dealing with a hypervisor. Provide either the full path to the child or the index of the child (where 0 is the first entry).

See also

Please refer to Targets in targets for more information.

The --children argument

If a target contains multiple other targets, such as a hypervisor, the children argument includes all children for the query as well.

See also

Please refer to Targets in targets for more information.

The -l, --list argument

The -l, --list argument lists all the available functions and their short description. To get a more elaborate description of a specific function, use target-query -f [FUNCTION_NAME] -h.

The -s, --strings argument

The -s, --string argument prints the records as strings. This might come in handy when, for example, post-processing the results with grep or other text-based tools.

The -j, --json argument

When the output of a function is records, the -j, --json argument converts these records into JSON format. This might come in handy when post-processing the results with a tool such as jq.

The --limit argument

the --limit [LIMIT] limits the amount of returned records to the specified amount.

The --no-cache, --ignore-cache argument

To improve performance on repetitive queries, target-query can create cache files. The --no-cache, --ignore-cache argument prevents target-query from creating these cache files.

See also

Please refer to Caching to learn more about in target-query.

The --only-read-cache argument

Use the --only-read-cache argument when the cache files should only be read and not written.

See also

Please refer to Caching to learn more about in target-query.

The --rewrite-cache argument

The --rewrite-cache argument rewrites the cache files, such that previous tracked progression is overwritten.

See also

Please refer to Caching to learn more about caching in target-query.

The --cmdb argument

The --cmdb argument can be used to generate a CMDB output for the targets. This argument only works with basic OS functions, namely hostname, version, domain, ips, and os. The following example shows how it can be used:

$ target-query targets/* -f hostname,domain,version,ips --cmdb -d ";"
EXAMPLE.vmx;EXAMPLE;EXAMPLE.local;Windows Server 2012 Enterprise (NT 6.3) 14393;["some.ip.address.here", "another.ip.address.here"]
EXAMPLE.vmx;EXAMPLE;EXAMPLE.local;Windows Server 2016 Enterprise (NT 6.3) 14393;["some.ip.address.here", "another.ip.address.here"]
EXAMPLE.tar;EXAMPLE;EXAMPLE.local;Red Hat Enterprise Linux 9.0;["some.ip.address.here", "another.ip.address.here"]

The --hash argument

The --hash argument hashes all the files located at the uri paths in the records, if the uri path can be resolved. This can be useful to, for example, compare file hashes with known-good-hashes.

The --report-dir argument

Use the --report-dir argument when you want to write the query result report to a specific location.