dissect.target 3.20.2.dev61__tar.gz → 3.20.2.dev63__tar.gz

{dissect_target-3.20.2.dev61/dissect.target.egg-info → dissect_target-3.20.2.dev63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: dissect.target
-Version: 3.20.2.dev61
+Version: 3.20.2.dev63
 Summary: This module ties 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)
 Author-email: Dissect Team <dissect@fox-it.com>
 License: Affero General Public License v3
@@ -86,6 +86,7 @@ Requires-Dist: dissect.util<4.0.dev,>=3.0.dev; extra == "dev"
 Requires-Dist: dissect.vmfs[dev]<4.0.dev,>=3.0.dev; extra == "dev"
 Requires-Dist: dissect.volume[dev]<4.0.dev,>=3.0.dev; extra == "dev"
 Requires-Dist: dissect.xfs[dev]<4.0.dev,>=3.0.dev; extra == "dev"
+Requires-Dist: pexpect; extra == "dev"
 Provides-Extra: yara
 Requires-Dist: dissect.target[full]; extra == "yara"
 Requires-Dist: yara-python; extra == "yara"

{dissect_target-3.20.2.dev61 → dissect_target-3.20.2.dev63}/dissect/target/helpers/cache.py

@@ -95,7 +95,7 @@ class Cache:
         target = args[0].target
 
         output = getattr(self.wrapper, "__output__", None)
-        if output not in ("record", "yield"):
+        if output not in ("record", "yield", "none"):
             # Cache property and default outputs on the target object itself
             func_cache = target._cache.setdefault(self.fname, {})
             key = (args[1:], frozenset(sorted(kwargs.items())))

dissect_target-3.20.2.dev63/dissect/target/helpers/scrape.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import io
+import logging
+import re
+import string
+from typing import TYPE_CHECKING, BinaryIO, Callable, Union
+
+from dissect.target.helpers.record import TargetRecordDescriptor
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+Needle = Union[bytes, re.Pattern]
+
+
+def find_needles(
+    fh: BinaryIO,
+    needles: Needle | list[Needle],
+    *,
+    start: int | None = None,
+    end: int | None = None,
+    lock_seek: bool = True,
+    block_size: int = io.DEFAULT_BUFFER_SIZE,
+    progress: Callable[[int], None] | None = None,
+) -> Iterator[tuple[bytes, int]]:
+    """Yields needles and their offsets found in provided byte stream.
+
+    Args:
+        fh: The byte stream to search for needles.
+        needles: The list of bytes needles to search for.
+        start: The offset to start searching from.
+        end: The offset to stop searching at.
+        lock_seek: Whether the file position is maintained by the scraper or the consumer.
+                   Setting this to ``False`` will allow the consumer to seek the file pointer, i.e. to skip forward.
+        block_size: The block size to use for reading from the byte stream.
+        progress: A function to call with the current offset.
+    """
+
+    if not isinstance(needles, list):
+        needles = [needles]
+
+    if not needles:
+        raise ValueError("At least one needle value must be provided")
+
+    if start is not None and end is not None and start >= end:
+        raise ValueError("Start offset must be less than end offset")
+
+    max_needle_len = max(len(n.pattern if isinstance(n, re.Pattern) else n) for n in needles)
+    overlap_len = max_needle_len
+
+    offset = fh.tell() if start is None else start
+    current_block = b""
+
+    while offset < end if end is not None else True:
+        if lock_seek:
+            fh.seek(offset)
+        else:
+            offset = fh.tell()
+
+        read_size = min(block_size, end - offset) if end is not None else block_size
+        if not (next_block := fh.read(read_size)):
+            break
+
+        if progress:
+            progress(offset)
+
+        overlap = current_block[-overlap_len:] if overlap_len > 0 else b""
+        current_block = overlap + next_block
+        current_block_offset = offset - len(overlap)
+
+        # Look for a needle in a current block
+        last_needle_pos = -1
+        last_needle_end = 0
+        while True:
+            needle_positions = [
+                (pos, needle)
+                for needle in needles
+                if (
+                    pos := (match.start(0) if (match := needle.search(current_block, last_needle_pos + 1)) else -1)
+                    if isinstance(needle, re.Pattern)
+                    else current_block.find(needle, last_needle_pos + 1)
+                )
+                > -1
+            ]
+
+            if not needle_positions:
+                break
+
+            closest_needle_pos, closest_needle = min(needle_positions)
+            yield closest_needle, current_block_offset + closest_needle_pos
+
+            last_needle_pos = closest_needle_pos
+            last_needle_end = last_needle_pos + 1
+
+        # The size of the data from the current block that will be prepended to the next block
+        overlap_len = min(len(current_block) - last_needle_end, max_needle_len)
+
+        offset += block_size
+
+
+def _read_plain_chunk(fh: BinaryIO, needle: Needle, offset: int, chunk_size: int) -> bytes:
+    """Read chunk from a byte stream for provided needle, offset and chunk size."""
+    fh.seek(offset)
+    return fh.read(chunk_size)
+
+
+def find_needle_chunks(
+    fh: BinaryIO,
+    needle_chunk_size_map: dict[Needle, int],
+    chunk_reader: Callable[[BinaryIO, Needle, int, int], bytes] | None = None,
+    lock_seek: bool = True,
+    block_size: int = io.DEFAULT_BUFFER_SIZE,
+) -> Iterator[tuple[bytes, int, bytes]]:
+    """Yields tuples with an offset, a needle and a byte chunk found in provided byte stream.
+
+    Args:
+        fh: The byte stream to search for needles.
+        needle_chunk_size_map: A dictionary with needle bytes as keys and chunk sizes as values.
+        chunk_reader: A function to read a chunk from a byte stream for provided needle, offset and chunk size.
+        lock_seek: Whether the file position is maintained by the scraper or the consumer.
+                   Setting this to ``False`` wil allow the consumer to seek the file pointer, i.e. to skip forward.
+        block_size: The block size to use for reading from the byte stream.
+    """
+    chunk_reader = chunk_reader or _read_plain_chunk
+
+    needles = list(needle_chunk_size_map.keys())
+    for needle, offset in find_needles(fh, needles, lock_seek=lock_seek, block_size=block_size):
+        yield (needle, offset, chunk_reader(fh, needle, offset, needle_chunk_size_map[needle]))
+
+
+def scrape_chunks(
+    fh: BinaryIO,
+    needle_chunk_size_map: dict[Needle, int],
+    chunk_parser: Callable[[Needle, bytes], Iterator[TargetRecordDescriptor]],
+    chunk_reader: Callable[[BinaryIO, Needle, int, int], bytes] | None = None,
+    block_size: int = io.DEFAULT_BUFFER_SIZE,
+    log: logging.Logger | None = None,
+) -> Iterator[TargetRecordDescriptor]:
+    """Yields records scraped from chunks found in a provided byte stream.
+
+    Args:
+        fh: The byte stream to search for needles.
+        needle_chunk_size_map: A dictionary with needle bytes as keys and chunk sizes as values.
+        chunk_parser: A function to parse a chunk and yield records.
+        chunk_reader: A function to read a chunk from a byte stream for provided needle, offset and chunk size.
+        block_size: The block size to use for reading from the byte stream.
+        log: A logger to use for logging.
+    """
+
+    chunk_count = 0
+    record_count = 0
+
+    chunk_stream = find_needle_chunks(
+        fh,
+        needle_chunk_size_map,
+        block_size=block_size,
+        chunk_reader=chunk_reader or _read_plain_chunk,
+    )
+
+    for needle, _, chunk in chunk_stream:
+        try:
+            for record in chunk_parser(needle, chunk):
+                yield record
+                record_count += 1
+            chunk_count += 1
+        except Exception as e:
+            if log:
+                log.warning("Chunk parsing failed with %r", e)
+
+    if log:
+        log.debug("Scraped %d chunks with %d records", chunk_count, record_count)
+
+
+def recover_string(buf: bytes, encoding: str, *, reverse: bool = False, ascii: bool = True) -> str:
+    """Recover the longest possible string from a byte buffer, forward or reverse.
+
+    Args:
+        buf: The byte buffer to recover a string from.
+        encoding: The encoding to use for decoding the buffer.
+        reverse: Whether to recover the string from the end of the buffer.
+        ascii: Whether to recover only ASCII characters.
+    """
+    if reverse:
+        decoded = ""
+        error_count = 0
+        max_error_count = 8  # Arbitrary limit
+
+        for i in range(1, len(buf) + 1):
+            try:
+                decoded = buf[-i:].decode(encoding)
+                error_count = 0
+            except UnicodeDecodeError:
+                error_count += 1
+
+                if error_count > max_error_count:
+                    break
+
+        decoded = decoded.split("\x00")[-1]
+
+        if ascii:
+            for i in range(1, len(decoded) + 1):
+                if decoded[-i] not in string.printable:
+                    decoded = decoded[-i + 1 :]
+                    break
+    else:
+        try:
+            decoded = buf.decode(encoding)
+        except UnicodeDecodeError as e:
+            decoded = buf[: e.start].decode(encoding)
+
+        decoded = decoded.split("\x00")[0]
+
+        if ascii:
+            for i in range(len(decoded)):
+                if decoded[i] not in string.printable:
+                    decoded = decoded[:i]
+                    break
+
+    return decoded

{dissect_target-3.20.2.dev61 → dissect_target-3.20.2.dev63}/dissect/target/plugins/os/windows/log/evt.py

@@ -8,7 +8,6 @@ from typing import Any, BinaryIO, Iterator
 from dissect.eventlog import evt
 from flow.record import Record
 
-from dissect.target import plugin
 from dissect.target.exceptions import (
     FilesystemError,
     PluginError,
@@ -17,6 +16,7 @@ from dissect.target.exceptions import (
     UnsupportedPluginError,
 )
 from dissect.target.helpers.record import TargetRecordDescriptor
+from dissect.target.plugin import Plugin, arg, export
 
 re_illegal_characters = re.compile(r"[\(\): \.\-#]")
 
@@ -110,7 +110,7 @@ class WindowsEventlogsMixin:
             raise UnsupportedPluginError(f'Event log directory "{self.LOGS_DIR_PATH}" not found')
 
 
-class EvtPlugin(WindowsEventlogsMixin, plugin.Plugin):
+class EvtPlugin(WindowsEventlogsMixin, Plugin):
     """Windows ``.evt`` event log plugin."""
 
     LOGS_DIR_PATH = "sysvol/windows/system32/config"
@@ -118,9 +118,9 @@ class EvtPlugin(WindowsEventlogsMixin, plugin.Plugin):
     NEEDLE = b"LfLe"
     CHUNK_SIZE = 0x10000
 
-    @plugin.arg("--logs-dir", help="logs directory to scan")
-    @plugin.arg("--log-file-glob", default=EVT_GLOB, help="glob pattern to match a log file name")
-    @plugin.export(record=EvtRecordDescriptor)
+    @arg("--logs-dir", help="logs directory to scan")
+    @arg("--log-file-glob", default=EVT_GLOB, help="glob pattern to match a log file name")
+    @export(record=EvtRecordDescriptor)
     def evt(self, log_file_glob: str = EVT_GLOB, logs_dir: str | None = None) -> Iterator[EvtRecordDescriptor]:
         """Parse Windows Eventlog files (``*.evt``).
 
@@ -174,7 +174,7 @@ class EvtPlugin(WindowsEventlogsMixin, plugin.Plugin):
             _target=self.target,
         )
 
-    @plugin.export(record=EvtRecordDescriptor)
+    @export(record=EvtRecordDescriptor)
     def scraped_evt(self) -> Iterator[EvtRecordDescriptor]:
         """Yields EVT log file records scraped from target disks"""
         yield from self.target.scrape.scrape_chunks_from_disks(

dissect_target-3.20.2.dev63/dissect/target/plugins/scrape/qfind.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import codecs
+import re
+import string
+import sys
+from pathlib import Path
+from typing import Callable
+
+from dissect.cstruct import utils
+
+from dissect.target.container import Container
+from dissect.target.helpers.scrape import recover_string
+from dissect.target.plugin import Plugin, arg, export
+from dissect.target.target import Target
+from dissect.target.volume import Volume
+
+
+class QFindPlugin(Plugin):
+    """Basically ``grep -a "malware"`` on steroids."""
+
+    def check_compatible(self) -> None:
+        pass
+
+    @arg("-n", "--needles", type=str, nargs="*", metavar="NEEDLES", help="needles to search for")
+    @arg("-nf", "--needle-file", type=Path, help="file containing the needles to search for")
+    @arg("-e", "--encoding", type=str, help="encode text needles with these comma separated encodings")
+    @arg("--no-hex-decode", action="store_true", help="do not automatically add decoded hex needles (only in raw mode)")
+    @arg("-R", "--raw", action="store_true", help="show raw hex dumps instead of post-processed string output")
+    @arg("-i", "--ignore-case", action="store_true", help="case insensitive search")
+    @arg("--allow-non-ascii", action="store_true", help="allow non-ASCII characters in the output")
+    @arg("-u", "--unique", action="store_true", help="only show unique string hits (does not apply to raw output)")
+    @arg("-W", "--window", type=int, default=256, help="maximum window size in bytes for context around each hit")
+    @export(output="none")
+    def qfind(
+        self,
+        needles: list[str] | None = None,
+        needle_file: Path | None = None,
+        encoding: str = "",
+        no_hex_decode: bool = False,
+        raw: bool = False,
+        ignore_case: bool = False,
+        allow_non_ascii: bool = False,
+        unique: bool = False,
+        window: int = 256,
+    ) -> None:
+        """Find a needle in a haystack.
+
+        Example:
+            .. code-block::
+
+                # find all instances of "malware" in the target
+                target-qfind <TARGET> --needles malware
+
+                # find all instances of "malware" in the target, ignoring case
+                target-qfind <TARGET> --needles MaLwArE --ignore-case
+
+                # find all instances of "malware" in the target and show raw hex dumps
+                target-qfind <TARGET> --needles malware --raw
+
+                # find all instances of "malware" in the target, in UTF-8 and UTF-16-LE (UTF-8 is default)
+                target-qfind <TARGET> --needles malware --encoding utf-16-le
+
+                # use target-query instead of target-qfind
+                target-query <TARGET> -f qfind --needles malware
+        """
+        all_needles = set(needles or [])
+        if needle_file and needle_file.exists():
+            with needle_file.open("r") as fh:
+                for line in fh:
+                    if (line := line.strip()) and not line.startswith("#"):
+                        all_needles.add(line)
+
+        encodings = set()
+        for codec in (encoding or "").split(","):
+            codec = codec.strip()
+
+            try:
+                codecs.lookup(codec.strip())
+            except LookupError:
+                self.target.log.warning("Unknown encoding: %s", codec)
+            else:
+                encodings.add(codec)
+
+        needle_lookup = {}
+        for needle in all_needles:
+            encoded_needle = needle.encode("utf-8")
+            needle_lookup[encoded_needle] = (needle, "utf-8")
+
+            if not no_hex_decode and len(needle) % 2 == 0 and all(c in string.hexdigits for c in needle):
+                encoded_needle = bytes.fromhex(needle)
+                needle_lookup[encoded_needle] = (needle, "hex")
+
+            for codec in encodings:
+                try:
+                    encoded_needle = needle.encode(codec)
+                except UnicodeEncodeError:
+                    self.target.log.warning("Cannot encode needle with %s: %s", codec, needle)
+                else:
+                    needle_lookup[encoded_needle] = (needle, codec)
+
+        if not needle_lookup:
+            self.target.log.error("No needles to search for")
+            return
+
+        if ignore_case:
+            tmp = {}
+            for encoded_needle, _ in needle_lookup.items():
+                tmp[re.compile(re.escape(encoded_needle), re.IGNORECASE)] = _
+            needle_lookup = tmp
+
+        seen = set()
+        for _, stream, needle, offset in self.target.scrape.find(
+            list(needle_lookup.keys()), progress=progress(self.target)
+        ):
+            original_needle, codec = needle_lookup[needle]
+            needle_len = len(needle.pattern if isinstance(needle, re.Pattern) else needle)
+            before_offset = max(0, offset - window)
+            stream.seek(before_offset)
+            buf = stream.read((offset - before_offset) + max(window, needle_len))
+
+            header = f"\r[{offset:#08x} @ {original_needle} ({codec})]"
+
+            if raw:
+                print(header)
+                palette = [(offset - before_offset, utils.COLOR_NORMAL), (needle_len, utils.COLOR_BG_RED)]
+                utils.hexdump(buf, palette, offset=before_offset)
+            else:
+                codec = "utf-8" if codec == "hex" else codec
+                before_part = recover_string(
+                    buf[: offset - before_offset], codec, reverse=True, ascii=not allow_non_ascii
+                )
+                after_part = recover_string(buf[offset - before_offset :], codec, ascii=not allow_non_ascii)
+                hit = (
+                    before_part
+                    + utils.COLOR_BG_RED
+                    + after_part[:needle_len]
+                    + utils.COLOR_NORMAL
+                    + after_part[needle_len:]
+                )
+
+                if unique:
+                    if hit in seen:
+                        continue
+                    seen.add(hit)
+
+                print(header)
+                print(hit)
+
+
+def progress(target: Target) -> Callable[[Container | Volume, int, int], None]:
+    """Progress handler of the qfind plugin."""
+    current_disk = None
+
+    def update(disk: Container | Volume, offset: int, size: int) -> None:
+        nonlocal current_disk
+        if current_disk is None:
+            sys.stderr.write(f"{target}\n")
+
+        if current_disk != disk:
+            sys.stderr.write(f"[Current disk: {disk}]\n")
+            current_disk = disk
+
+        sys.stderr.write(f"\r{offset / float(size) * 100:0.2f}%")
+        sys.stderr.flush()
+
+    return update

dissect_target-3.20.2.dev63/dissect/target/plugins/scrape/scrape.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import io
+from collections import defaultdict
+from typing import TYPE_CHECKING, BinaryIO, Callable
+
+from dissect.util.stream import MappingStream
+
+from dissect.target.container import Container
+from dissect.target.helpers.record import TargetRecordDescriptor
+from dissect.target.helpers.scrape import Needle, find_needles, scrape_chunks
+from dissect.target.plugin import Plugin, internal
+from dissect.target.volume import EncryptedVolumeSystem, LogicalVolumeSystem, Volume
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+class ScrapePlugin(Plugin):
+    __namespace__ = "scrape"
+
+    def check_compatible(self) -> None:
+        pass
+
+    def create_streams(
+        self, *, encrypted: bool = True, lvm: bool = True, all: bool = False
+    ) -> Iterator[tuple[Container | Volume, MappingStream]]:
+        """Yields streams for all disks and volumes of a target.
+
+        At the basis, each disk of a target is represented as a stream of itself. If the target has volumes, these are
+        checked to be either encrypted or LVM volumes (if the respective flags are set). If so, that volume is replaced
+        in the disk stream with a stream of the volume itself, or removed.
+
+        In the case of encrypted volumes, the encrypted volume is replaced with the decrypted volume. This is done
+        transparently on the disk stream level, so the consumer does not need to worry about the decryption process.
+
+        In the case of LVM volumes (including any sort of RAID), the base volumes are removed from the disk stream,
+        and a new stream will be yielded for each logical volume. This ensures that no unnecessary scraping is
+        performed on base volumes of a logical volume, but only on the reconstructed logical volume.
+
+        Args:
+            encrypted: Whether to replace encrypted volumes for their decrypted counterpart.
+            lvm: Whether to skip base volumes of LVM volumes and yield the logical volume itself.
+            all: Whether to yield all disks and volumes, regardless of their type.
+
+        Yields:
+            A tuple containing the disk (or volume, in the case of an LVM volume) and a stream of that disk.
+        """
+        # Create a map of disk regions we want to scrape
+        scrape_map = defaultdict(dict)
+
+        # Start off by making a very simple `disk: {(offset, size): volume}` map for every volume
+        # Spaces in between volumes are also added as disk regions
+        offset = 0
+        for disk in self.target.disks:
+            for volume in disk.vs.volumes if disk.vs else []:
+                if offset != volume.offset:
+                    # There's data between the volumes, so add that from the disk
+                    scrape_map[disk][(offset, volume.offset - offset)] = (disk, offset)
+                    offset = volume.offset
+
+                # Add the volume to the stream
+                scrape_map[disk][(volume.offset, volume.size)] = (volume, 0)
+                offset += volume.size
+
+            # There's data after the volumes until the end of the disk
+            # Coincidentally this also takes care of disks with no volumes
+            if offset != disk.size:
+                scrape_map[disk][(offset, disk.size - offset)] = (disk, offset)
+
+        # Iterate over all volumes and add the decrypted variant of encrypted volumes
+        for volume in self.target.volumes:
+            if encrypted and isinstance(volume.vs, EncryptedVolumeSystem):
+                if not all:
+                    # Decrypted volumes have the encrypted volume as the disk
+                    source_volume: Volume = volume.disk
+                    source_disk = source_volume.disk
+
+                    # Replace the encrypted volume region with the decrypted volume region
+                    scrape_map[source_disk][(source_volume.offset, source_volume.size)] = (volume, 0)
+                else:
+                    # Add the encrypted volume separately to the map
+                    scrape_map[volume][(0, volume.size)] = (volume, 0)
+
+            if lvm and isinstance(volume.vs, LogicalVolumeSystem):
+                if not all:
+                    # Remove the base volumes from the map
+                    for source_volume in volume.disk:
+                        source_disk = source_volume.disk
+                        del scrape_map[source_disk][(source_volume.offset, source_volume.size)]
+
+                # Add the logical volumes to the map
+                scrape_map[volume][(0, volume.size)] = (volume, 0)
+
+        for disk, volumes in scrape_map.items():
+            # If we ended up removing all regions from the disk, skip it
+            # I.e. when a disk is fully occupied by an LVM volume
+            if not volumes:
+                continue
+
+            size = 0
+            stream = MappingStream()
+            for (map_offset, map_size), (source, source_offset) in volumes.items():
+                stream.add(map_offset, map_size, source, source_offset)
+                size = max(size, map_offset + map_size)
+            stream.size = size
+
+            yield disk, stream
+
+    @internal
+    def find(
+        self,
+        needles: Needle | list[Needle],
+        lock_seek: bool = True,
+        block_size: int = io.DEFAULT_BUFFER_SIZE,
+        progress: Callable[[Container | Volume, int, int], None] | None = None,
+    ) -> Iterator[tuple[Container | Volume, MappingStream, Needle, int]]:
+        """Yields needles and their offsets found in all disks and volumes of a target.
+
+        Args:
+            needles: The needle or list of needles to search for.
+            lock_seek:  Whether the file position is maintained by the scraper or the consumer.
+                        Setting this to ``False`` wil allow the consumer to seek the file pointer, i.e. to skip forward.
+            block_size: The block size to use for reading from the byte stream.
+            progress: A function to call with the current disk, offset and size of the stream.
+        """
+        for disk, stream in self.create_streams():
+            for needle, offset in find_needles(
+                stream,
+                needles,
+                lock_seek=lock_seek,
+                block_size=block_size,
+                progress=(lambda current: progress(disk, current, stream.size)) if progress else None,
+            ):
+                yield disk, stream, needle, offset
+
+    @internal
+    def scrape_chunks_from_disks(
+        self,
+        chunk_parser: Callable[[Needle, bytes], Iterator[TargetRecordDescriptor]],
+        needle_chunk_size_map: dict[Needle, int] | None = None,
+        needle: Needle | None = None,
+        chunk_size: int | None = None,
+        chunk_reader: Callable[[BinaryIO, Needle, int, int], bytes] | None = None,
+        block_size: int = io.DEFAULT_BUFFER_SIZE,
+    ) -> Iterator[TargetRecordDescriptor]:
+        """Yields records scraped from chunks found in ``target.disks``.
+
+        Args:
+            chunk_parser: A function to parse a chunk and yield records.
+            needle_chunk_size_map: A dictionary with needle as keys and chunk sizes as values.
+            needle: A single needle to search for.
+            chunk_size: The size of the chunks to scrape, when providing a single needle.
+            chunk_reader: A function to read a chunk from a byte stream for provided needle, offset and chunk size.
+            block_size: The block size to use for reading from the byte stream.
+        """
+
+        if needle_chunk_size_map and (needle or chunk_size):
+            raise ValueError("Either `needle_chunk_size_map` or both `needle` and `chunk_size` must be provided")
+
+        if (needle and not chunk_size) or (not needle and chunk_size):
+            raise ValueError("Both `needle` and `chunk_size` must be provided")
+        else:
+            needle_chunk_size_map = {needle: chunk_size}
+
+        for disk in self.target.disks:
+            disk.seek(0)
+            yield from scrape_chunks(
+                disk,
+                needle_chunk_size_map=needle_chunk_size_map,
+                chunk_parser=chunk_parser,
+                chunk_reader=chunk_reader,
+                block_size=block_size,
+            )
+
+    @internal
+    def scrape_needles_from_disks(
+        self,
+        needle: Needle | None = None,
+        needles: list[Needle] | None = None,
+        block_size: int = io.DEFAULT_BUFFER_SIZE,
+    ) -> Iterator[tuple[BinaryIO, bytes, int]]:
+        """Yields ``(bytestream, needle, offset)`` tuples, scraped from ``target.disks``.
+
+        Args:
+            needles: A list of byte needles to search for.
+            needle: A single byte needle to search for.
+            block_size: The block size to use for reading from the byte stream.
+        """
+
+        if needle and needles:
+            raise ValueError("Either `needles` values or a single `needle` value must be provided")
+        elif not needle and not needles:
+            raise ValueError("At least one needle value must be provided")
+
+        if needle:
+            needles = [needle]
+
+        for disk in self.target.disks:
+            disk.seek(0)
+            for needle, offset in find_needles(disk, needles=needles, block_size=block_size):
+                yield disk, needle, offset