From 7938fd25c4bb18bc5bb9270530ad53ec7f2e2600 Mon Sep 17 00:00:00 2001 From: cecinestpasunepipe <110607403+cecinestpasunepipe@users.noreply.github.com> Date: Fri, 15 Dec 2023 18:12:29 +0100 Subject: [PATCH 1/6] DIS-1378 --- docs/source/advanced/children.rst | 57 +++++++++++++++++++++++++++++++ docs/source/advanced/index.rst | 1 + docs/source/advanced/targets.rst | 4 +++ 3 files changed, 62 insertions(+) create mode 100644 docs/source/advanced/children.rst diff --git a/docs/source/advanced/children.rst b/docs/source/advanced/children.rst new file mode 100644 index 0000000..7c49900 --- /dev/null +++ b/docs/source/advanced/children.rst @@ -0,0 +1,57 @@ +Children +======== + +Child targets are nested targets. Targets can contain nested targets, this is almost always the case if +the target is an hypervisor. After retrieving a child target, it behaves just like a regular target, all +the plugin methods are available. The following child targets are supported: + +* ESXi +* Hyper-V +* Virtuozzo +* VMWare +* WSL + +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 ``ChildTargetPlugin`` and implement the +``list_children()`` method. Use the ``__type__`` attribute to specify the type of the child plugin (i.e. "wsl"). + + 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..bba4cff 100644 --- a/docs/source/advanced/targets.rst +++ b/docs/source/advanced/targets.rst @@ -140,3 +140,7 @@ in ``ProgramData/Microsoft/Windows/Hyper-V/data.vmcx`` that tells us where all o 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. + +.. hint:: + + Learn more about child targets :doc:`here `. From 4050b79b6cc8aabdcec1466846e555d9efe81e7d Mon Sep 17 00:00:00 2001 From: cecinestpasunepipe <110607403+cecinestpasunepipe@users.noreply.github.com> Date: Fri, 22 Mar 2024 12:55:14 +0100 Subject: [PATCH 2/6] Update docs/source/advanced/children.rst Co-authored-by: Erik Schamper <1254028+Schamper@users.noreply.github.com> --- docs/source/advanced/children.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/advanced/children.rst b/docs/source/advanced/children.rst index 7c49900..93ba2c3 100644 --- a/docs/source/advanced/children.rst +++ b/docs/source/advanced/children.rst @@ -5,11 +5,11 @@ Child targets are nested targets. Targets can contain nested targets, this is al the target is an hypervisor. After retrieving a child target, it behaves just like a regular target, all the plugin methods are available. The following child targets are supported: -* ESXi -* Hyper-V +* VMware ESXi (also known as vSphere) +* VMWare Workstation +* Microsoft Hyper-V +* Windows Subsystem for Linux (WSL2) * Virtuozzo -* VMWare -* WSL To obtain a list of nested targets use ``list_children``: From 7b6589e7370d6bf49223cad20b9f4925dc1b3412 Mon Sep 17 00:00:00 2001 From: cecinestpasunepipe <110607403+cecinestpasunepipe@users.noreply.github.com> Date: Fri, 22 Mar 2024 12:55:21 +0100 Subject: [PATCH 3/6] Update docs/source/advanced/children.rst Co-authored-by: Erik Schamper <1254028+Schamper@users.noreply.github.com> --- docs/source/advanced/children.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/advanced/children.rst b/docs/source/advanced/children.rst index 93ba2c3..f2e145e 100644 --- a/docs/source/advanced/children.rst +++ b/docs/source/advanced/children.rst @@ -1,9 +1,9 @@ Children ======== -Child targets are nested targets. Targets can contain nested targets, this is almost always the case if -the target is an hypervisor. After retrieving a child target, it behaves just like a regular target, all -the plugin methods are available. The following child targets are supported: +Dissect supports the concept of targets within targets, referred to as child or nested targets. This can be useful when dealing with hypervisors, where we can individually address each virtual machine as a separate target. Child targets behave just like regular targets, so all functionality and plugins we can expect on a regular target is available on a child target. + +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 From 52c496127bdcc15ccd7cb12a2274efdb76ef8201 Mon Sep 17 00:00:00 2001 From: cecinestpasunepipe <110607403+cecinestpasunepipe@users.noreply.github.com> Date: Fri, 22 Mar 2024 14:10:05 +0100 Subject: [PATCH 4/6] Improvements --- docs/source/advanced/children.rst | 42 +++++++++++++++++++++++++++++-- docs/source/advanced/targets.rst | 15 +++++------ 2 files changed, 46 insertions(+), 11 deletions(-) diff --git a/docs/source/advanced/children.rst b/docs/source/advanced/children.rst index f2e145e..c328978 100644 --- a/docs/source/advanced/children.rst +++ b/docs/source/advanced/children.rst @@ -1,9 +1,18 @@ Children ======== -Dissect supports the concept of targets within targets, referred to as child or nested targets. This can be useful when dealing with hypervisors, where we can individually address each virtual machine as a separate target. Child targets behave just like regular targets, so all functionality and plugins we can expect on a regular target is available on a child target. +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. -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: +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. + +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 @@ -11,6 +20,35 @@ Child targets can be anything that Dissect already supports, but we also provide * 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 + + +When using ``target-shell`` you can access the child target by using the ``enter`` command: + +.. code-block:: console + + $ enter host123.vmcx + + +Child target API +---------------- + + To obtain a list of nested targets use ``list_children``: .. code-block:: python diff --git a/docs/source/advanced/targets.rst b/docs/source/advanced/targets.rst index bba4cff..9375227 100644 --- a/docs/source/advanced/targets.rst +++ b/docs/source/advanced/targets.rst @@ -131,15 +131,12 @@ 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:: From 20c7d3088907ca058a3d0a7c3d2f662faeee7fe5 Mon Sep 17 00:00:00 2001 From: cecinestpasunepipe <110607403+cecinestpasunepipe@users.noreply.github.com> Date: Wed, 27 Mar 2024 15:43:35 +0100 Subject: [PATCH 5/6] Improvements --- docs/source/advanced/children.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/advanced/children.rst b/docs/source/advanced/children.rst index c328978..ebaeace 100644 --- a/docs/source/advanced/children.rst +++ b/docs/source/advanced/children.rst @@ -6,8 +6,8 @@ target contains a ``.vmdk`` file within itself, we can tell ``dissect.target`` t 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 +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. From 33fcdeaf102811f92cbfc7271816a14d2cfa6474 Mon Sep 17 00:00:00 2001 From: cecinestpasunepipe <110607403+cecinestpasunepipe@users.noreply.github.com> Date: Tue, 16 Apr 2024 11:42:53 +0200 Subject: [PATCH 6/6] Improvements --- docs/source/advanced/children.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/source/advanced/children.rst b/docs/source/advanced/children.rst index ebaeace..0e07e73 100644 --- a/docs/source/advanced/children.rst +++ b/docs/source/advanced/children.rst @@ -37,8 +37,14 @@ the file within the host target that contains the child target: $ target-query /path/to/target -f hostname --child /virtualmachines/host123.vmcx +Alternatively you can use the index number of the child: -When using ``target-shell`` you can access the child target by using the ``enter`` command: +.. 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 @@ -89,7 +95,10 @@ available: supported_children = child_plugins() -To craft your own child plugin, subclass the ``ChildTargetPlugin`` and implement the +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!