Skip to content

libdebug.snapshots.process.process_snapshot

ProcessSnapshot

Bases: Snapshot

This object represents a snapshot of the target process. It holds information about the process's state.

Snapshot levels: - base: Registers - writable: Registers, writable memory contents - full: Registers, stack, all readable memory contents

Source code in libdebug/snapshots/process/process_snapshot.py 
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
class ProcessSnapshot(Snapshot):
    """This object represents a snapshot of the target process. It holds information about the process's state.

    Snapshot levels:
    - base: Registers
    - writable: Registers, writable memory contents
    - full: Registers, stack, all readable memory contents
    """

    def __init__(
        self: ProcessSnapshot, debugger: InternalDebugger, level: str = "base", name: str | None = None
    ) -> None:
        """Creates a new snapshot object for the given process.

        Args:
            debugger (Debugger): The thread to take a snapshot of.
            level (str, optional): The level of the snapshot. Defaults to "base".
            name (str, optional): A name associated to the snapshot. Defaults to None.
        """
        # Set id of the snapshot and increment the counter
        self.snapshot_id = debugger._snapshot_count
        debugger.notify_snaphot_taken()

        # Basic snapshot info
        self.process_id = debugger.process_id
        self.pid = self.process_id
        self.name = name
        self.level = level
        self.arch = debugger.arch
        self.aslr_enabled = debugger.aslr_enabled
        self._process_full_path = debugger._process_full_path
        self._process_name = debugger._process_name
        self._serialization_helper = debugger.serialization_helper

        # Memory maps
        match level:
            case "base":
                self.maps = MemoryMapSnapshotList([], self._process_name, self._process_full_path)

                for curr_map in debugger.maps:
                    saved_map = MemoryMapSnapshot(
                        start=curr_map.start,
                        end=curr_map.end,
                        permissions=curr_map.permissions,
                        size=curr_map.size,
                        offset=curr_map.offset,
                        backing_file=curr_map.backing_file,
                        content=None,
                    )
                    self.maps.append(saved_map)

                self._memory = None
            case "writable":
                if not debugger.fast_memory:
                    liblog.warning(
                        "Memory snapshot requested but fast memory is not enabled. This will take a long time.",
                    )

                # Save all memory pages
                self._save_memory_maps(debugger, writable_only=True)

                self._memory = SnapshotMemoryView(self, debugger.symbols)
            case "full":
                if not debugger.fast_memory:
                    liblog.warning(
                        "Memory snapshot requested but fast memory is not enabled. This will take a long time.",
                    )

                # Save all memory pages
                self._save_memory_maps(debugger, writable_only=False)

                self._memory = SnapshotMemoryView(self, debugger.symbols)
            case _:
                raise ValueError(f"Invalid snapshot level {level}")

        # Snapshot the threads
        self._save_threads(debugger)

        # Log the creation of the snapshot
        named_addition = " named " + self.name if name is not None else ""
        liblog.debugger(
            f"Created snapshot {self.snapshot_id} of level {self.level} for process {self.pid}{named_addition}"
        )

    def _save_threads(self: ProcessSnapshot, debugger: InternalDebugger) -> None:
        self.threads = []

        for thread in debugger.threads:
            # Create a lightweight snapshot for the thread
            lw_snapshot = LightweightThreadSnapshot(thread, self)

            self.threads.append(lw_snapshot)

    @property
    def regs(self: ProcessSnapshot) -> SnapshotRegisters:
        """Returns the registers of the process snapshot."""
        return self.threads[0].regs

    def diff(self: ProcessSnapshot, other: ProcessSnapshot) -> Diff:
        """Returns the diff between two process snapshots."""
        if not isinstance(other, ProcessSnapshot):
            raise TypeError("Both arguments must be ProcessSnapshot objects.")

        return ProcessSnapshotDiff(self, other)

regs property

Returns the registers of the process snapshot.

__init__(debugger, level='base', name=None)

Creates a new snapshot object for the given process.

Parameters:

Name Type Description Default
debugger Debugger

The thread to take a snapshot of.

 required
level str

The level of the snapshot. Defaults to "base".

 'base'
name str

A name associated to the snapshot. Defaults to None.

 None
Source code in libdebug/snapshots/process/process_snapshot.py 
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__(
    self: ProcessSnapshot, debugger: InternalDebugger, level: str = "base", name: str | None = None
) -> None:
    """Creates a new snapshot object for the given process.

    Args:
        debugger (Debugger): The thread to take a snapshot of.
        level (str, optional): The level of the snapshot. Defaults to "base".
        name (str, optional): A name associated to the snapshot. Defaults to None.
    """
    # Set id of the snapshot and increment the counter
    self.snapshot_id = debugger._snapshot_count
    debugger.notify_snaphot_taken()

    # Basic snapshot info
    self.process_id = debugger.process_id
    self.pid = self.process_id
    self.name = name
    self.level = level
    self.arch = debugger.arch
    self.aslr_enabled = debugger.aslr_enabled
    self._process_full_path = debugger._process_full_path
    self._process_name = debugger._process_name
    self._serialization_helper = debugger.serialization_helper

    # Memory maps
    match level:
        case "base":
            self.maps = MemoryMapSnapshotList([], self._process_name, self._process_full_path)

            for curr_map in debugger.maps:
                saved_map = MemoryMapSnapshot(
                    start=curr_map.start,
                    end=curr_map.end,
                    permissions=curr_map.permissions,
                    size=curr_map.size,
                    offset=curr_map.offset,
                    backing_file=curr_map.backing_file,
                    content=None,
                )
                self.maps.append(saved_map)

            self._memory = None
        case "writable":
            if not debugger.fast_memory:
                liblog.warning(
                    "Memory snapshot requested but fast memory is not enabled. This will take a long time.",
                )

            # Save all memory pages
            self._save_memory_maps(debugger, writable_only=True)

            self._memory = SnapshotMemoryView(self, debugger.symbols)
        case "full":
            if not debugger.fast_memory:
                liblog.warning(
                    "Memory snapshot requested but fast memory is not enabled. This will take a long time.",
                )

            # Save all memory pages
            self._save_memory_maps(debugger, writable_only=False)

            self._memory = SnapshotMemoryView(self, debugger.symbols)
        case _:
            raise ValueError(f"Invalid snapshot level {level}")

    # Snapshot the threads
    self._save_threads(debugger)

    # Log the creation of the snapshot
    named_addition = " named " + self.name if name is not None else ""
    liblog.debugger(
        f"Created snapshot {self.snapshot_id} of level {self.level} for process {self.pid}{named_addition}"
    )

diff(other)

Returns the diff between two process snapshots.

Source code in libdebug/snapshots/process/process_snapshot.py 
122
123
124
125
126
127
def diff(self: ProcessSnapshot, other: ProcessSnapshot) -> Diff:
    """Returns the diff between two process snapshots."""
    if not isinstance(other, ProcessSnapshot):
        raise TypeError("Both arguments must be ProcessSnapshot objects.")

    return ProcessSnapshotDiff(self, other)