Skip to content

libdebug.snapshots.snapshot

Snapshot

This object represents a snapshot of a system task.

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

Source code in libdebug/snapshots/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
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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
class Snapshot:
    """This object represents a snapshot of a system task.

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

    def _save_regs(self: Snapshot, thread: ThreadContext) -> None:
        # Create a register field for the snapshot
        self.regs = SnapshotRegisters(
            thread.thread_id,
            thread._register_holder.provide_regs(),
            thread._register_holder.provide_special_regs(),
            thread._register_holder.provide_vector_fp_regs(),
        )

        # Set all registers in the field
        all_regs = dir(thread.regs)
        all_regs = [reg for reg in all_regs if isinstance(thread.regs.__getattribute__(reg), int | float)]

        for reg_name in all_regs:
            reg_value = thread.regs.__getattribute__(reg_name)
            self.regs.__setattr__(reg_name, reg_value)

    def _save_memory_maps(self: Snapshot, debugger: InternalDebugger, writable_only: bool) -> None:
        """Saves memory maps of the process to the snapshot."""
        process_name = debugger._process_name
        full_process_path = debugger._process_full_path
        self.maps = MemoryMapSnapshotList([], process_name, full_process_path)

        for curr_map in debugger.maps:
            # Skip non-writable maps if requested
            # Always skip maps that fail on read
            if not writable_only or "w" in curr_map.permissions:
                try:
                    contents = debugger.memory[curr_map.start : curr_map.end, "absolute"]
                except (ValueError, OSError, OverflowError):
                    # There are some memory regions that cannot be read, such as [vvar], [vdso], etc.
                    contents = None
            else:
                contents = None

            saved_map = MemoryMapSnapshot(
                curr_map.start,
                curr_map.end,
                curr_map.permissions,
                curr_map.size,
                curr_map.offset,
                curr_map.backing_file,
                contents,
            )
            self.maps.append(saved_map)

    @property
    def registers(self: Snapshot) -> SnapshotRegisters:
        """Alias for regs."""
        return self.regs

    @property
    def memory(self: Snapshot) -> SnapshotMemoryView:
        """Returns a view of the memory of the thread."""
        if self._memory is None:
            if self.level != "base":
                liblog.error("Inconsistent snapshot state: memory snapshot is not available.")

            raise ValueError("Memory snapshot is not available at base level.")

        return self._memory

    @property
    def mem(self: Snapshot) -> SnapshotMemoryView:
        """Alias for memory."""
        return self.memory

    @abstractmethod
    def diff(self: Snapshot, other: Snapshot) -> Diff:
        """Creates a diff object between two snapshots."""

    def save(self: Snapshot, file_path: str) -> None:
        """Saves the snapshot object to a file."""
        self._serialization_helper.save(self, file_path)

    def backtrace(self: Snapshot) -> list[int]:
        """Returns the current backtrace of the thread."""
        if self.level == "base":
            raise ValueError("Backtrace is not available at base level. Stack is not available.")

        stack_unwinder = stack_unwinding_provider(self.arch)
        return stack_unwinder.unwind(self)

    def pprint_registers(self: Snapshot) -> None:
        """Pretty prints the thread's registers."""
        pprint_registers_util(self.regs, self.maps, self.regs._generic_regs)

    def pprint_regs(self: Snapshot) -> None:
        """Alias for the `pprint_registers` method.

        Pretty prints the thread's registers.
        """
        self.pprint_registers()

    def pprint_registers_all(self: Snapshot) -> None:
        """Pretty prints all the thread's registers."""
        pprint_registers_all_util(
            self.regs,
            self.maps,
            self.regs._generic_regs,
            self.regs._special_regs,
            self.regs._vec_fp_regs,
        )

    def pprint_regs_all(self: Snapshot) -> None:
        """Alias for the `pprint_registers_all` method.

        Pretty prints all the thread's registers.
        """
        self.pprint_registers_all()

    def pprint_backtrace(self: ThreadContext) -> None:
        """Pretty prints the current backtrace of the thread."""
        if self.level == "base":
            raise ValueError("Backtrace is not available at base level. Stack is not available.")

        stack_unwinder = stack_unwinding_provider(self.arch)
        backtrace = stack_unwinder.unwind(self)
        pprint_backtrace_util(backtrace, self.maps, self._memory._symbol_ref)

    def pprint_maps(self: Snapshot) -> None:
        """Prints the memory maps of the process."""
        pprint_maps_util(self.maps)

    def pprint_memory(
        self: Snapshot,
        start: int,
        end: int,
        file: str = "hybrid",
        override_word_size: int | None = None,
        integer_mode: bool = False,
    ) -> None:
        """Pretty print the memory diff.

        Args:
            start (int): The start address of the memory diff.
            end (int): The end address of the memory diff.
            file (str, optional): The backing file for relative / absolute addressing. Defaults to "hybrid".
            override_word_size (int, optional): The word size to use for the diff in place of the ISA word size. Defaults to None.
            integer_mode (bool, optional): If True, the diff will be printed as hex integers (system endianness applies). Defaults to False.
        """
        if self.level == "base":
            raise ValueError("Memory is not available at base level.")

        if start > end:
            tmp = start
            start = end
            end = tmp

        word_size = get_platform_gp_register_size(self.arch) if override_word_size is None else override_word_size

        # Resolve the address
        if file == "absolute":
            address_start = start
        elif file == "hybrid":
            try:
                # Try to resolve the address as absolute
                self.memory[start, 1, "absolute"]
                address_start = start
            except ValueError:
                # If the address is not in the maps, we use the binary file
                address_start = start + self.maps.filter("binary")[0].start
                file = "binary"
        else:
            map_file = self.maps.filter(file)[0]
            address_start = start + map_file.base
            file = map_file.backing_file if file != "binary" else "binary"

        extract = self.memory[start:end, file]

        file_info = f" (file: {file})" if file not in ("absolute", "hybrid") else ""
        print(f"Memory from {start:#x} to {end:#x}{file_info}:")

        pprint_memory_util(
            address_start,
            extract,
            word_size,
            self.maps,
            integer_mode=integer_mode,
        )

mem property

Alias for memory.

memory property

Returns a view of the memory of the thread.

registers property

Alias for regs.

_save_memory_maps(debugger, writable_only)

Saves memory maps of the process to the snapshot.

Source code in libdebug/snapshots/snapshot.py 
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
def _save_memory_maps(self: Snapshot, debugger: InternalDebugger, writable_only: bool) -> None:
    """Saves memory maps of the process to the snapshot."""
    process_name = debugger._process_name
    full_process_path = debugger._process_full_path
    self.maps = MemoryMapSnapshotList([], process_name, full_process_path)

    for curr_map in debugger.maps:
        # Skip non-writable maps if requested
        # Always skip maps that fail on read
        if not writable_only or "w" in curr_map.permissions:
            try:
                contents = debugger.memory[curr_map.start : curr_map.end, "absolute"]
            except (ValueError, OSError, OverflowError):
                # There are some memory regions that cannot be read, such as [vvar], [vdso], etc.
                contents = None
        else:
            contents = None

        saved_map = MemoryMapSnapshot(
            curr_map.start,
            curr_map.end,
            curr_map.permissions,
            curr_map.size,
            curr_map.offset,
            curr_map.backing_file,
            contents,
        )
        self.maps.append(saved_map)

backtrace()

Returns the current backtrace of the thread.

Source code in libdebug/snapshots/snapshot.py 
117
118
119
120
121
122
123
def backtrace(self: Snapshot) -> list[int]:
    """Returns the current backtrace of the thread."""
    if self.level == "base":
        raise ValueError("Backtrace is not available at base level. Stack is not available.")

    stack_unwinder = stack_unwinding_provider(self.arch)
    return stack_unwinder.unwind(self)

diff(other) abstractmethod

Creates a diff object between two snapshots.

Source code in libdebug/snapshots/snapshot.py 
109
110
111
@abstractmethod
def diff(self: Snapshot, other: Snapshot) -> Diff:
    """Creates a diff object between two snapshots."""

pprint_backtrace()

Pretty prints the current backtrace of the thread.

Source code in libdebug/snapshots/snapshot.py 
153
154
155
156
157
158
159
160
def pprint_backtrace(self: ThreadContext) -> None:
    """Pretty prints the current backtrace of the thread."""
    if self.level == "base":
        raise ValueError("Backtrace is not available at base level. Stack is not available.")

    stack_unwinder = stack_unwinding_provider(self.arch)
    backtrace = stack_unwinder.unwind(self)
    pprint_backtrace_util(backtrace, self.maps, self._memory._symbol_ref)

pprint_maps()

Prints the memory maps of the process.

Source code in libdebug/snapshots/snapshot.py 
162
163
164
def pprint_maps(self: Snapshot) -> None:
    """Prints the memory maps of the process."""
    pprint_maps_util(self.maps)

pprint_memory(start, end, file='hybrid', override_word_size=None, integer_mode=False)

Pretty print the memory diff.

Parameters:

Name Type Description Default
start int

The start address of the memory diff.

 required
end int

The end address of the memory diff.

 required
file str

The backing file for relative / absolute addressing. Defaults to "hybrid".

 'hybrid'
override_word_size int

The word size to use for the diff in place of the ISA word size. Defaults to None.

 None
integer_mode bool

If True, the diff will be printed as hex integers (system endianness applies). Defaults to False.

 False
Source code in libdebug/snapshots/snapshot.py 
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
def pprint_memory(
    self: Snapshot,
    start: int,
    end: int,
    file: str = "hybrid",
    override_word_size: int | None = None,
    integer_mode: bool = False,
) -> None:
    """Pretty print the memory diff.

    Args:
        start (int): The start address of the memory diff.
        end (int): The end address of the memory diff.
        file (str, optional): The backing file for relative / absolute addressing. Defaults to "hybrid".
        override_word_size (int, optional): The word size to use for the diff in place of the ISA word size. Defaults to None.
        integer_mode (bool, optional): If True, the diff will be printed as hex integers (system endianness applies). Defaults to False.
    """
    if self.level == "base":
        raise ValueError("Memory is not available at base level.")

    if start > end:
        tmp = start
        start = end
        end = tmp

    word_size = get_platform_gp_register_size(self.arch) if override_word_size is None else override_word_size

    # Resolve the address
    if file == "absolute":
        address_start = start
    elif file == "hybrid":
        try:
            # Try to resolve the address as absolute
            self.memory[start, 1, "absolute"]
            address_start = start
        except ValueError:
            # If the address is not in the maps, we use the binary file
            address_start = start + self.maps.filter("binary")[0].start
            file = "binary"
    else:
        map_file = self.maps.filter(file)[0]
        address_start = start + map_file.base
        file = map_file.backing_file if file != "binary" else "binary"

    extract = self.memory[start:end, file]

    file_info = f" (file: {file})" if file not in ("absolute", "hybrid") else ""
    print(f"Memory from {start:#x} to {end:#x}{file_info}:")

    pprint_memory_util(
        address_start,
        extract,
        word_size,
        self.maps,
        integer_mode=integer_mode,
    )

pprint_registers()

Pretty prints the thread's registers.

Source code in libdebug/snapshots/snapshot.py 
125
126
127
def pprint_registers(self: Snapshot) -> None:
    """Pretty prints the thread's registers."""
    pprint_registers_util(self.regs, self.maps, self.regs._generic_regs)

pprint_registers_all()

Pretty prints all the thread's registers.

Source code in libdebug/snapshots/snapshot.py 
136
137
138
139
140
141
142
143
144
def pprint_registers_all(self: Snapshot) -> None:
    """Pretty prints all the thread's registers."""
    pprint_registers_all_util(
        self.regs,
        self.maps,
        self.regs._generic_regs,
        self.regs._special_regs,
        self.regs._vec_fp_regs,
    )

pprint_regs()

Alias for the pprint_registers method.

Pretty prints the thread's registers.

Source code in libdebug/snapshots/snapshot.py 
129
130
131
132
133
134
def pprint_regs(self: Snapshot) -> None:
    """Alias for the `pprint_registers` method.

    Pretty prints the thread's registers.
    """
    self.pprint_registers()

pprint_regs_all()

Alias for the pprint_registers_all method.

Pretty prints all the thread's registers.

Source code in libdebug/snapshots/snapshot.py 
146
147
148
149
150
151
def pprint_regs_all(self: Snapshot) -> None:
    """Alias for the `pprint_registers_all` method.

    Pretty prints all the thread's registers.
    """
    self.pprint_registers_all()

save(file_path)

Saves the snapshot object to a file.

Source code in libdebug/snapshots/snapshot.py 
113
114
115
def save(self: Snapshot, file_path: str) -> None:
    """Saves the snapshot object to a file."""
    self._serialization_helper.save(self, file_path)