diff --git a/docs/source/advanced/children.rst b/docs/source/advanced/children.rst new file mode 100644 index 0000000..0e07e73 --- /dev/null +++ b/docs/source/advanced/children.rst @@ -0,0 +1,104 @@ +Children +======== + +Dissect also supports the concept of targets within targets, referred to as child targets. For example, when a +target contains a ``.vmdk`` file within itself, we can tell ``dissect.target`` to load that target from within the +context of the first target. This can be useful when dealing with hypervisors. + +Say, for example, we opened a Hyper-V target locally from ``\\.\PhysicalDrive0``, we can parse the metadata +in ``ProgramData/Microsoft/Windows/Hyper-V/data.vmcx`` which tells us where all of the virtual machines are stored. +We can then use these paths and tell ``dissect.target`` to load another target from there. Reading all of these +files will still happen from ``\\.\PhysicalDrive0``, passing through the various abstraction layers of ``dissect.target``. +This allows Dissect to read the disks from running virtual machines, regardless of locks the operating has on these files. + +Child targets can be anything that Dissect already supports, but we also provide some automatic detection of +child targets for certain systems. Automatic child target detection is currently supported for: + +* VMware ESXi (also known as vSphere) +* VMWare Workstation +* Microsoft Hyper-V +* Windows Subsystem for Linux (WSL2) +* Virtuozzo + +Using child targets +------------------- + +To apply ``target-query`` to child targets simply add the ``--children`` flag like this: + +.. code-block:: console + + $ target-query /path/to/target -f hostname --children + +Replace the example path ``/path/to/target`` with the path to the host image. +To just query a specific child, simply use the ``--child`` option and provide the path to +the file within the host target that contains the child target: + +.. code-block:: console + + $ target-query /path/to/target -f hostname --child /virtualmachines/host123.vmcx + +Alternatively you can use the index number of the child: + +.. code-block:: console + + $ target-query /path/to/target -f hostname --child 1 + +When using :doc:`target-shell ` you can access the child target by using the ``enter`` command +on the file that contains the child target: + +.. code-block:: console + + $ enter host123.vmcx + + +Child target API +---------------- + + +To obtain a list of nested targets use ``list_children``: + +.. code-block:: python + + target = Target.open("host.img") + target.list_children() + +This will produce a list of records describing the child targets inside: + +.. code-block:: console + + + +You can now open each target by passing the path attribute to the ``target.open_child()`` method: + +.. code-block:: python + + target.open_child(child.path) + +To open all child targets of a target: + +.. code-block:: python + + children = target.open_children() + +This can also be done recursively by passing ``True`` as a parameter. +To open all child targets when opening a batch of targets: + +.. code-block:: python + + all = Target.open_all(["hyper1.img","hyper2.img"], children=True) + +Child targets are loaded through special ``Child plugins`` that reside in the +``/dissect/target/plugins/child`` folder. To get a list of all child plugins +available: + +.. code-block:: python + + supported_children = child_plugins() + +To craft your own child plugin, subclass the :class:`ChildTargetPlugin ` and implement the +``list_children()`` method. Use the ``__type__`` attribute to specify the type of the child plugin (i.e. "wsl"). + +.. seealso:: + + The :class:`HyperV ` child plugin is a good example to get started! + diff --git a/docs/source/advanced/index.rst b/docs/source/advanced/index.rst index e0162aa..c83371c 100644 --- a/docs/source/advanced/index.rst +++ b/docs/source/advanced/index.rst @@ -5,6 +5,7 @@ Advanced /advanced/api /advanced/targets + /advanced/children /advanced/loaders /advanced/containers /advanced/volumes diff --git a/docs/source/advanced/targets.rst b/docs/source/advanced/targets.rst index 67403bd..9375227 100644 --- a/docs/source/advanced/targets.rst +++ b/docs/source/advanced/targets.rst @@ -131,12 +131,13 @@ that may have had its superblock or ``$BOOT`` destroyed: Targets in targets ------------------ -Dissect also supports the concept of targets within targets, referred to as child targets. For example, when a -target contains a ``.vmdk`` file within itself, we can tell ``dissect.target`` to load that target from within the -context of the first target. This can be useful when dealing with hypervisors. - -Say, for example, we opened a Hyper-V target locally from ``\\.\PhysicalDrive0``, we can parse the metadata -in ``ProgramData/Microsoft/Windows/Hyper-V/data.vmcx`` that tells us where all of the virtual machines are stored. -Then we can then use these paths and tell ``dissect.target`` to load another target from there. Reading all of these -files will still happen from ``\\.\PhysicalDrive0``, passing through the various abstraction layers of ``dissect.target``. -This allows Dissect to read the disks from running virtual machines, regardless of locks the operating has on these files. +Dissect also supports the concept of targets within targets, referred to as child targets. +Child targets are especially useful for dealing with hypervisors. With the child target feature +you can query virtual machines that are running on a host. Because of the way Dissect handles the +underlying data streams you can query these virtual machines regardless of the locks the host +operating system has on these files. It is even possible to explore the contents of the child targets +using ``target-shell`` just like regular targets! + +.. hint:: + + Learn more about child targets :doc:`here `.