diff --git a/docs/source/conf.py b/docs/source/conf.py index f562ada..4fdf8c9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -73,8 +73,9 @@ api_dir = Path(__file__).parent / "api" for dir_name in ["acquire/nop", "dissect/nop", "flow/nop"]: - api_dir.joinpath(dir_name).mkdir(parents=True, exist_ok=True) - api_dir.joinpath(dir_name, "index.rst").write_text(":orphan:\n\nTITLE\n#####\n") + if not (nop_dir := api_dir.joinpath(dir_name)).exists(): + nop_dir.mkdir(parents=True, exist_ok=True) + nop_dir.joinpath("index.rst").write_text(":orphan:\n\nTITLE\n#####\n") else: extensions.append("autoapi.extension") diff --git a/docs/source/index.rst b/docs/source/index.rst index 0a8ae28..eb09fe3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,17 +18,17 @@ Usage Example ------------- One of the most prominent tools that Dissect offers is called *target-query*. -With this simple command you can, for example, extract all user accounts from a disk image: +With this simple command you can, for example, extract all user accounts from a disk image: .. code-block:: console $ target-query pc.img -f users - + - + To see what other useful artefacts you can query use ``-l``: .. code-block:: console @@ -80,31 +80,31 @@ Or you can start by taking a look at some community articles and videos: :doc:`/resources/dissect-in-action` or :doc:`/resources/talks-and-conferences` to begin with. -Get in touch, join us on `github `_! +Get in touch, join us on `GitHub `_! .. toctree:: :hidden: - + Home .. toctree:: :caption: Basics :hidden: - Install - Tutorial + /install + /supported-targets + /tutorial Querying Shell Mount Acquire RDump - - + .. toctree:: :caption: In-Depth :hidden: - + /tools/index /projects/index /usage/index diff --git a/docs/source/supported-targets.rst b/docs/source/supported-targets.rst new file mode 100644 index 0000000..0c28bc5 --- /dev/null +++ b/docs/source/supported-targets.rst @@ -0,0 +1,413 @@ +Supported Targets +----------------- + +Dissect supports a large range of formats. +From various disk images, volume systems, file systems and operating systems, to tarballs and proprietary backup formats, and everything combined! +This page aims to provide you with an overview of what you can expect Dissect to be able to handle! + +Loaders +~~~~~~~ + +Loaders provide a way to interact with a "target" by combining and accessing source data into usable parts. +This creates a virtual representation of the original system. + +.. seealso:: + + For a deeper dive into how loaders work, see :doc:`loaders `. + +In most cases, Dissect selects the appropriate loader automatically based on the file you target. +It does this by looking at things like the file type, folder structure or special configurations files. +If needed, you can choose the loader yourself by using ``-L `` option or by using the URI-style notation ``://``. + +.. code-block:: console + + target-query -f func /path/to/target.ab + target-query -f func -L ab /path/to/target + target-query -f func ab:///path/to/target + +.. important:: + + Just because it does not have a loader, does not mean Dissect cannot open it! In those cases, Dissect falls back to a "raw loader", + which allows it to be opened as any of the :ref:`supported containers ` or even + :ref:`supported filesystems `. Whether a target is supported + as a loader, a container or a filesystem depends on implementation details for that specific format. + +.. list-table:: Supported loaders + :header-rows: 1 + :widths: 20 15 5 + + * - Description + - Format + - API + * - Android backup + - ``.ab`` + - :mod:`ab ` + * - Acquire + - ZIP or tar with Acquire structure + - :mod:`acquire ` + * - AccessData AD1 + - ``.ad1`` + - :mod:`ad1 ` + * - Carbon Black Live Response endpoint + - ``cb://`` or ``-L cb`` [#f1]_ + - :mod:`cb ` + * - Cellebrite UFED export + - ``.ufdx``, ``.ufd`` + - :mod:`cellebrite ` + * - Docker and OCI container images + - tar file with Docker or OCI image structure + - :mod:`containerimage ` + * - Local directory + - Common OS structure (``path/Windows/System32`` or ``path/etc``) + - :mod:`dir ` + * - Microsoft Hyper-V virtual machine configuration + - ``.vmcx``, ``.xml`` + - :mod:`hyperv ` + * - iTunes backup + - Directory with iTunes backup structure + - :mod:`itunes ` + * - KAPE + - Directory or ``.vhdx`` with KAPE structure + - :mod:`kape ` + * - Libvirt XML configuration + - ``.xml`` + - :mod:`libvirt ` + * - Local system (automatically load all drives such as ``/dev/sda`` or ``\\.\PhysicalDrive0``) + - ``local`` + - :mod:`local ` + * - MQTT broker + - ``mqtt://`` or ``-L mqtt`` [#f2]_ + - :mod:`mqtt ` + * - Netscaler Techsupport Collector + - tar with Netscaler Techsupport structure + - :mod:`nscollector ` + * - Open Virtual Appliance (OVA) + - ``.ova`` + - :mod:`ova ` + * - Podman OCI overlay + - Directory with Podman overlay structure + - :mod:`overlay ` + * - Docker overlay2 + - Directory with Docker overlay2 structure + - :mod:`overlay2 ` + * - Open Virtualization Format (OVF) + - ``.ovf`` + - :mod:`ovf ` + * - Proxmox virtual machine configuration + - ``.conf`` + - :mod:`proxmox ` + * - Parallels virtual machine directory + - ``.pvm``, + - :mod:`pvm ` + * - Parallels virtual machine configuration + - ``config.pvs`` + - :mod:`pvs ` + * - Single raw binary file + - Default fallback for unknown files + - :mod:`raw ` + * - Multiple raw binary files + - Paths with ``+`` (``/dev/vda+/dev/vdb``) + - :mod:`multiraw ` + * - Remote Dissect agent + - ``remote://`` or ``-L remote`` + - :mod:`remote ` + * - Remote SMB server + - ``smb://`` or ``-L smb`` [#f3]_ + - :mod:`smb ` + * - Tanium + - Directory with Tanium structure + - :mod:`tanium ` + * - (Compressed) tar + - ``.tar``, ``.tar.``, ``.t`` + - :mod:`tar ` + * - Unix-like Artifacts Collector (UAC) + - Directory, ZIP or tar with UAC structure + - :mod:`uac ` + * - UTM virtual machine + - ``.utm`` + - :mod:`utm ` + * - Oracle VirtualBox virtual machine + - ``.vbox`` + - :mod:`vbox ` + * - Veeam Backup (VBK) + - ``.vbk`` + - :mod:`vbk ` + * - Rapid7 Velociraptor + - Directory or ZIP with Velociraptor structure + - :mod:`velociraptor ` + * - Proxmox Virtual Machine Archive (VMA) + - ``.vma`` + - :mod:`vma ` + * - VMware Fusion virtual machine + - ``.vmwarevm`` + - :mod:`vmwarevm ` + * - VMware virtual machine configuration + - ``.vmx`` + - :mod:`vmx ` + * - Citrix Hypervisor backup (XVA) + - ``.xva`` + - :mod:`xva ` + * - ZIP + - ``.zip`` + - :mod:`zip ` + +.. [#f1] Requires ``dissect.target[cb]`` +.. [#f2] Requires ``dissect.target[mqtt]`` +.. [#f3] Requires ``dissect.target[smb]`` + +Containers +~~~~~~~~~~ + +Containers let Dissect interact with a disk-like structure in a consistent way. +These can be virtual machine files, forensic containers or a hard disk itself. + +.. seealso:: + + For a deeper understanding on how containers work, see :doc:`containers `. + +Dissect can select the appropriate container automatically based on either the file extension or file magic. +For example, the QCOW2 container gets selected if the file extension is ``.qcow2`` or if the first bytes of the file are ``b"QFI\xfb"``. + +.. list-table:: Supported containers + :header-rows: 1 + :widths: 15 5 5 + + * - Description + - Format + - API + * - Apple Sparse Image Format + - ``.asif`` + - :mod:`asif ` + * - FTK Expert Witness Disk Image Format (EWF) + - ``.E01``, ``.L01`` + - :mod:`ewf ` + * - Fortinet firmware + - ``*-fortinet.out`` + - :mod:`fortifw ` + * - Parallels HDD virtual disk + - ``.hdd`` + - :mod:`hdd ` + * - Parallels HDS sparse virtual disk + - ``.hds`` + - :mod:`hds ` + * - QEMU QCOW2 + - ``.qcow2`` + - :mod:`qcow2 ` + * - VirtualBox VDI virtual disk + - ``.vdi`` + - :mod:`vdi ` + * - Hyper-V VHD virtual disk + - ``.vhd`` + - :mod:`vhd ` + * - Hyper-V VHDX virtual disk + - ``.vhdx`` + - :mod:`vhdx ` + * - VMware virtual disk + - ``.vmdk`` + - :mod:`vmdk ` + +Partition Schemes and Volume Systems +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Dissect supports most common partition schemes. Nested partitions are supported as well. + +.. list-table:: Supported Partition Schemes + :header-rows: 1 + :widths: 20 5 + + * - Description + - API + * - Apple Partition Map (APM) + - :mod:`apm ` + * - BSD Disklabel + - :mod:`bsd ` + * - GUID Partition Table (GPT) + - :mod:`gpt ` + * - Master Boot Record (MBR) + - :mod:`mbr ` + +Besides these standard partition schemes, Dissect supports disks in RAID configurations or disks with logical volumes that span multiple disks. + +.. seealso:: + + For more details, see :doc:`volumes `. + +.. list-table:: Supported volume systems + :header-rows: 1 + :widths: 20 5 + + * - Description + - API + * - DDF (Disk Data Format) RAID, common in Dell RAID controllers + - :mod:`ddf ` + * - LVM2 + - :mod:`lvm2 ` + * - Linux MD RAID + - :mod:`md ` + * - VMFS LVM + - :mod:`vmfs ` + +Dissect also has decryption capability for some well known systems. +This functionality can be accessed with a keychain file (specified with ``-K``) with multiple passphrases or a keychain value (``-Kv``) in most Dissect tools. + +.. list-table:: Supported encrypted volume systems + :header-rows: 1 + :widths: 20 5 + + * - Description + - API + * - LUKS (version 1 and 2) + - :mod:`luks ` + * - BitLocker (all configurations and versions, including EOW) + - :mod:`bde ` + +Filesystems +~~~~~~~~~~~ + +In Dissect, filesystems go beyond traditional disk-based structures. +If it behaves like a filesystem, Dissect can likely treat it as one. +This includes both standard filesystems and formats that resemble filesystem behavior. + +There might be some overlap with loaders and containers, as some formats can function in multiple roles, +or need implementation in different areas to work correctly. + +.. seealso:: + + For more details, see :doc:`Filesystems `. + +.. list-table:: Supported filesystems + :header-rows: 1 + :widths: 20 5 + + * - Description + - API + * - AccessData AD1 + - :mod:`ad1 ` + * - Apple File System (APFS) + - :mod:`apfs ` + * - Linux Btrfs + - :mod:`btrfs ` + * - CPIO archive + - :mod:`cpio ` + * - Linux cramfs + - :mod:`cramfs ` + * - exFAT + - :mod:`exfat ` + * - Linux EXT2, EXT3, EXT4 + - :mod:`extfs ` + * - FAT12, FAT16, FAT32 + - :mod:`fat ` + * - BSD Fast Filesystem (FFS) + - :mod:`ffs ` + * - Linux Journaling Flash Filesystem (JFFS) + - :mod:`jffs ` + * - Network File Share (NFS) + - :mod:`nfs ` + * - Microsoft NTFS + - :mod:`ntfs ` + * - QNX4 and QNX6 + - :mod:`qnxfs ` + * - Linux SquashFS + - :mod:`squashfs ` + * - Veeam Backup (VBK) + - :mod:`vbk ` + * - VMware (VMFS) + - :mod:`vmfs ` + * - VMware vmtar + - :mod:`vmtar ` + * - Linux XFS + - :mod:`xfs ` + +Operating Systems +~~~~~~~~~~~~~~~~~ + +Dissect tries to automatically figure out what operating system is available on the target, based on known file locations and structures. +Once the operating system is known, it enables you to get more accurate information from the system, for example, the user or network configuration. + +.. list-table:: Supported operating systems + :header-rows: 1 + :widths: 20 5 + + * - Description + - API + * - Windows + - :mod:`windows ` + * - Generic Unix + - :mod:`unix ` + * - BSD + - :mod:`unix.bsd ` + * - Citrix + - :mod:`unix.bsd.citrix ` + * - FreeBSD + - :mod:`unix.bsd.freebsd ` + * - OpenBSD + - :mod:`unix.bsd.openbsd ` + * - Generic Darwin + - :mod:`unix.bsd.darwin ` + * - iOS + - :mod:`unix.bsd.darwin.ios ` + * - macOS + - :mod:`unix.bsd.darwin.macos ` + * - ESXi + - :mod:`unix.esxi ` + * - Generic Linux + - :mod:`unix.linux ` + * - Android + - :mod:`unix.linux.android ` + * - FortiOS + - :mod:`unix.linux.fortios ` + * - OpenSUSE + - :mod:`unix.linux.suse ` + * - RedHat + - :mod:`unix.linux.redhat ` + * - Debian + - :mod:`unix.linux.debian ` + * - Proxmox + - :mod:`unix.linux.debian.proxmox ` + * - VyOS + - :mod:`unix.linux.debian.vyos ` + +Child Targets +~~~~~~~~~~~~~ + +Dissect supports identifying, listing and querying *child targets*. +These are targets within other targets, such as virtual machines or containers. +Dissect finds these by looking inside configuration files on a target. +It can do this recursively, and look for *child targets* inside the *child targets* for even more *child targets*. + +.. seealso:: + + For more details, see :ref:`Child targets `. + +.. list-table:: Supported child targets + :header-rows: 1 + :widths: 20 5 + + * - Description + - API + * - Colima containers + - :mod:`colima ` + * - Docker containers + - :mod:`docker ` + * - ESXi virtual machines + - :mod:`esxi ` + * - Hyper-V virtual machines + - :mod:`hyperv ` + * - Lima containers and virtual machines + - :mod:`lima ` + * - Parallels virtual machines + - :mod:`parallels ` + * - Podman containers + - :mod:`podman ` + * - Proxmox virtual machines + - :mod:`proxmox ` + * - QEMU virtual machines + - :mod:`qemu ` + * - Oracle VirtualBox virtual machines + - :mod:`virtualbox ` + * - Virtuozzo containers + - :mod:`virtuozzo ` + * - VMware Workstation virtual machines + - :mod:`vmware_workstation ` + * - Windows Subsystem for Linux 2 (WSL2) instances + - :mod:`wsl ` diff --git a/submodules/dissect.target b/submodules/dissect.target index 73dd16d..0041dd4 160000 --- a/submodules/dissect.target +++ b/submodules/dissect.target @@ -1 +1 @@ -Subproject commit 73dd16d197442368ad42e6e2117c047e6a946b4f +Subproject commit 0041dd4f5d2e9bcaa483f3540890eecf596d1f51