The dissect.target project

.gitattributes

@@ -0,0 +1 @@
+tests/data/enc-volume.bin filter=lfs diff=lfs merge=lfs -text

.github/workflows/dissect-ci.yml

@@ -0,0 +1,7 @@
+name: Dissect CI
+on: [push, pull_request, workflow_dispatch]
+
+jobs: 
+  ci:
+    uses: fox-it/dissect-workflow-templates/.github/workflows/dissect-ci-template-self-hosted.yml@main
+    secrets: inherit

.gitignore

@@ -0,0 +1,9 @@
+coverage.xml
+.coverage
+dist/
+.eggs/
+*.egg-info/
+*.pyc
+__pycache__/
+.pytest_cache/
+.tox/

COPYRIGHT

@@ -0,0 +1,5 @@
+Dissect is released as open source by Fox-IT (https://www.fox-it.com) part of NCC Group Plc (https://www.nccgroup.com)
+
+Developed by the Dissect Team ([email protected]) and made available at https://github.com/fox-it/dissect.target
+
+License terms: AGPL3 (https://www.gnu.org/licenses/agpl-3.0.html)

MANIFEST.in

@@ -0,0 +1,4 @@
+exclude .gitignore
+exclude .github
+
+graft autocompletion/

README.md

@@ -0,0 +1,169 @@
+# dissect.target
+
+The Dissect module tying all other Dissect modules together. It provides a programming API and command line tools which
+allow easy access to various data sources inside disk images or file collections (a.k.a. targets). For more information,
+please see [the documentation](https://dissect.readthedocs.io/en/latest/projects/dissect.target).
+
+## Tools inside this project
+
+### target-query
+`target-query` is a tool used to query specific data inside one or more targets.
+These queries are available in the form of functions that reside within [plugins](https://dissect.readthedocs.io/en/latest/advanced/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 basic usage of `target-query` is to execute a function on a target:
+
+```bash
+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
+```
+
+Not every target plugin will function on every target, they are OS specific.
+More information on how to use `target-query` is found in [the documentation](https://dissect.readthedocs.io/en/latest/tools/target-query).
+
+### target-shell
+`target-shell` gives you the ability to access a target using a virtual shell environment. Once a shell is opened
+on a target, type `help` to list the available commands. To see the documentation of each command,
+you can use `help [COMMAND]`.
+
+Opening a shell on a target is straight-forward. You can do so by specifying a path to a target as follows:
+
+```bash
+    target-shell targets/EXAMPLE.vmx
+    EXAMPLE /> help
+
+    Documented commands (type help <topic>):
+    ========================================
+    cat    disks  filesystems  help     less  python    save
+    cd     exit   find         hexdump  ls    readlink  stat
+    clear  file   hash         info     pwd   registry  volumes
+
+    EXAMPLE /> ls
+    c:
+    sysvol
+```
+
+Further interacting with the target can be done using the commands listed above.
+You can exit the shell by running `exit` or by pressing `CTRL+D`.
+
+More information on how to use `target-shell` is found in [the documentation](https://dissect.readthedocs.io/en/latest/tools/target-shell).
+
+### target-fs
+With `target-fs` you can interact with the filesystem of a target using a set of familiar Unix commands.
+
+The basic structure of a `target-fs` command is as follows:
+
+```bash
+target-fs <path_to_target> <command> <path_for_command>
+```
+
+**NOTE:** As with any shell command, you have to properly escape backlashes and spaces. Unless you use single or double quotes (`'`, `"`).
+
+More information on how to use `target-fs` is found in [the documentation](https://dissect.readthedocs.io/en/latest/tools/target-fs).
+
+### target-reg
+With `target-reg` you can easily query the registry of Windows targets and print the results in a tree. A `+` symbol indicates that it is a registry key (i.e. may have subkeys). A `-` symbol indicates a registry value.
+
+```bash
+user@dissect~$ target-reg targets/EXAMPLE.E01 -k "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft"
++ 'Microsoft' (last-modified-date-shows-here)
+    + '.NETFramework' (last-modified-date-shows-here)
+    - 'Enable64Bit' value-shows-here
+[...]
+```
+
+More information on how to use `target-reg` is found in [the documentation](https://dissect.readthedocs.io/en/latest/tools/target-reg).
+
+### target-dump
+With `target-dump` you can export records of a specific `function` used in target-query to a file.
+
+The basic structure of a `target-dump` command is as follows:
+
+```bash
+target-dump -f <comma_seperated_functions> <path_to_target>
+```
+
+Futhermore, the tool can apply certain compression algorithms to the dump, to create small archives of the output.
+
+More information on how to use `target-dump` is found in [the documentation](https://dissect.readthedocs.io/en/latest/tools/target-dump).
+
+### target-dd
+With `target-dd` you can export (a part of) a target to a file or to stdout. At the moment, `target-dd` can be used for targets that have only one disk.
+
+The basic structure of a `target-dd` command is as follows:
+
+```bash
+target-dd --write <output_file> --offset <offset_on_target_in_bytes> --bytes <nr_of_bytes_to_read> <path_to_target>
+```
+
+More information on how to use `target-dd` is found in [the documentation](https://dissect.readthedocs.io/en/latest/tools/target-dd).
+
+### target-mount
+With `target-mount` you can mount the filesystem of a target to any arbitrary directory on your analysis machine, similar to the `mount` command on Unix systems.
+To perform this function, we use `fusepy` to mount a filesystem in linux and mac.
+This interacts with `fuselib` to mount disk images in linux userspace, so no administrative access is required.
+
+`target-mount` has two required positional arguments:
+
+* `TARGET` - Target to mount
+* `MOUNT` - Directory to mount the target's filesystem on
+
+
+The following example command can be used to mount a target to the directory ``mnt``:
+
+```bash
+user@dissect~$ target-mount targets/EXAMPLE.vmx ~/mnt/EXAMPLE
+user@dissect~$ ls ~/mnt/EXAMPLE/
+disks   fs   volumes
+```
+
+When mounting a target using `target-mount` the process is kept in the foreground. This will occupy your current
+terminal session. It is recommended to either open a second terminal, let this command run in the background by
+appending `&` to the command or use a terminal multiplexer like `tmux` to start a second session. Using one
+of these methods enables you to interact with the mountpoint.
+
+More information on how to use `target-mount` is found in [the documentation](https://dissect.readthedocs.io/en/latest/tools/target-mount).
+
+## Build and test instructions
+
+This project uses `tox` to build source and wheel distributions. Run the following command from the root folder to build
+these:
+
+```bash
+tox -e build
+```
+
+The build artifacts can be found in the `dist/` directory.
+
+`tox` is also used to run linting and unit tests in a self-contained environment. To run both linting and unit tests
+using the default installed Python version, run:
+
+```bash
+tox
+```
+
+For a more elaborate explanation on how to build and test the project, please see [the
+documentation](https://dissect.readthedocs.io/en/latest/contributing/developing.html#building-testing).
+
+## Contributing
+
+The Dissect project encourages any contribution to the codebase. To make your contribution fit into the project, please
+refer to [the style guide](https://dissect.readthedocs.io/en/latest/contributing/style-guide.html).
+
+## Copyright and license
+
+Dissect is released as open source by Fox-IT (<https://www.fox-it.com>) part of NCC Group Plc
+(<https://www.nccgroup.com>).
+
+Developed by the Dissect Team (<[email protected]>) and made available at <https://github.com/fox-it/dissect>.
+
+License terms: AGPL3 (<https://www.gnu.org/licenses/agpl-3.0.html>). For more information, see the LICENSE file.

autocompletion/target_bash_completion.sh

@@ -0,0 +1,110 @@
+#!/bin/env bash
+
+#######################################
+# Enables to create a comma seperated list argument
+# Arguments:
+#   cur: The current argument that the tab completion is busy with
+#   list: The list of completion options
+# Outputs:
+#   list of comma seperated tab completions
+#######################################
+__comma_seperated_list_completion ()
+{
+    local cur=${1} list=${2}
+    local filtered_list realcur prefix
+
+    if [[ "${cur}" = *,* ]]; then
+        realcur=${cur##*,}
+        prefix=${cur%,*}
+
+        # Create filtered_list depending on the prefix
+        filtered_list=$(__filter_list "${list[@]}" "${prefix}")
+        echo $( compgen -W "${filtered_list}" -P "${prefix}," -- ${realcur})
+    else
+        echo $( compgen -W "${list}" -- ${cur} )
+    fi
+}
+
+#######################################
+# Filters a list based on a comma seperated ${prefix}
+#   If a list element is inside ${prefix} it is excluded from the output
+# Arguments:
+#   prefix: Comma seperated list
+#   list: The list of completion options
+# Outputs:
+#   list of filtered completion outputs
+#######################################
+__filter_list() {
+    # Filter the total array that was already selected.
+    local list=(${1}) prefix=${2} filtered_array=()
+
+    for i in ${list[@]}; do
+        # Exclude list elements that are in ${prefix}
+        if [[ ! (*",${prefix},"* =~ ",${i},") ]]; then
+            filtered_array+=(${i})
+        fi
+    done
+    echo "${filtered_array[@]}"
+}
+
+#######################################
+# A default help command for the target-* commands
+# It filters the target-* --help command to get a list of command line arguments
+# Globals
+#   COMPREPLY: Fills it with help command line arguments
+# Outputs:
+#   None
+#######################################
+__target_help() {
+    local cur options
+
+    COMPREPLY=()
+    cur=${COMP_WORDS[COMP_CWORD]}
+    options=$(${COMP_WORDS[0]} --help | grep -Eo ' --?([a-zA-Z]|-)+' | awk '{print $1}' | sort -u)
+
+    case "${cur}" in
+    -*)
+        COMPREPLY=($( compgen -W "${options}" -- ${cur} ))
+        ;;
+    esac
+}
+
+#######################################
+# Autocomplete target-query entries
+# sets COMPREPLY for completion argument
+# Globals:
+#   COMPREPLY
+#   DISSECT_PLUGINS: A list of target-query plugins
+# Arguments:
+#   None
+#######################################
+__target_query ()
+{
+    local cur prev
+    # Set compreply to command line arguments if -* is detected
+    __target_help
+
+    cur=${COMP_WORDS[COMP_CWORD]}
+    prev=${COMP_WORDS[COMP_CWORD-1]}
+
+    # Store plugin in global variable, so it only gets executed once
+    if [[ -z ${DISSECT_PLUGINS+x} ]]; then
+        DISSECT_PLUGINS=$(target-query --list | grep ' -' | awk '{print $1}')
+    fi
+
+    case "${prev}" in
+    -f | --function )
+        COMPREPLY=($(__comma_seperated_list_completion "${cur}" "${DISSECT_PLUGINS}"))
+        ;;
+    esac
+
+}
+
+
+complete -F __target_query -o filenames -o default target-query
+
+complete -F __target_help -o filenames -o default target-dd
+complete -F __target_help -o filenames -o default target-fs
+complete -F __target_help -o filenames -o default target-mount
+complete -F __target_help -o filenames -o default target-reg
+complete -F __target_help -o filenames -o default target-shell

dissect/target/__init__.py

@@ -0,0 +1,3 @@
+from dissect.target.target import Target
+
+__all__ = ["Target"]