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 
 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
128
129
130
131
132
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)

                symbols = SymbolList(debugger.symbols, self)

                self._memory = SnapshotMemoryView(self, 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)

                symbols = SymbolList(debugger.symbols, self)

                self._memory = SnapshotMemoryView(self, 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 
 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
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)

            symbols = SymbolList(debugger.symbols, self)

            self._memory = SnapshotMemoryView(self, 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)

            symbols = SymbolList(debugger.symbols, self)

            self._memory = SnapshotMemoryView(self, 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 
127
128
129
130
131
132
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)