Skip to content

libdebug.snapshots.thread.thread_snapshot

ThreadSnapshot

Bases: Snapshot

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

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

Source code in libdebug/snapshots/thread/thread_snapshot.py 
 23
 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
class ThreadSnapshot(Snapshot):
    """This object represents a snapshot of the target thread. It holds information about a thread's state.

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

    def __init__(self: ThreadSnapshot, thread: ThreadContext, level: str = "base", name: str | None = None) -> None:
        """Creates a new snapshot object for the given thread.

        Args:
            thread (ThreadContext): 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 = thread._snapshot_count
        thread.notify_snapshot_taken()

        # Basic snapshot info
        self.thread_id = thread.thread_id
        self.tid = thread.tid
        self.name = name
        self.level = level
        self.arch = thread._internal_debugger.arch
        self.aslr_enabled = thread._internal_debugger.aslr_enabled
        self._process_full_path = thread.debugger._internal_debugger._process_full_path
        self._process_name = thread.debugger._internal_debugger._process_name
        self._serialization_helper = thread._internal_debugger.serialization_helper

        # Get thread registers
        self._save_regs(thread)

        # Memory maps
        match level:
            case "base":
                map_list = []

                for curr_map in thread.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,
                    )
                    map_list.append(saved_map)

                self.maps = MemoryMapSnapshotList(map_list, self._process_name, self._process_full_path)

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

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

                symbols = SymbolList(thread.debugger.symbols, self)
                self._memory = SnapshotMemoryView(self, symbols)
            case "full":
                if not thread.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(thread._internal_debugger, writable_only=False)

                symbols = SymbolList(thread.debugger.symbols, self)

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

        # 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 thread {self.tid}{named_addition}",
        )

    def diff(self: ThreadSnapshot, other: ThreadSnapshot) -> Diff:
        """Creates a diff object between two snapshots."""
        if not isinstance(other, ThreadSnapshot):
            raise TypeError("Both arguments must be ThreadSnapshot objects.")

        return ThreadSnapshotDiff(self, other)

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

Creates a new snapshot object for the given thread.

Parameters:

Name Type Description Default
thread ThreadContext

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/thread/thread_snapshot.py 
 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
def __init__(self: ThreadSnapshot, thread: ThreadContext, level: str = "base", name: str | None = None) -> None:
    """Creates a new snapshot object for the given thread.

    Args:
        thread (ThreadContext): 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 = thread._snapshot_count
    thread.notify_snapshot_taken()

    # Basic snapshot info
    self.thread_id = thread.thread_id
    self.tid = thread.tid
    self.name = name
    self.level = level
    self.arch = thread._internal_debugger.arch
    self.aslr_enabled = thread._internal_debugger.aslr_enabled
    self._process_full_path = thread.debugger._internal_debugger._process_full_path
    self._process_name = thread.debugger._internal_debugger._process_name
    self._serialization_helper = thread._internal_debugger.serialization_helper

    # Get thread registers
    self._save_regs(thread)

    # Memory maps
    match level:
        case "base":
            map_list = []

            for curr_map in thread.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,
                )
                map_list.append(saved_map)

            self.maps = MemoryMapSnapshotList(map_list, self._process_name, self._process_full_path)

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

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

            symbols = SymbolList(thread.debugger.symbols, self)
            self._memory = SnapshotMemoryView(self, symbols)
        case "full":
            if not thread.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(thread._internal_debugger, writable_only=False)

            symbols = SymbolList(thread.debugger.symbols, self)

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

    # 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 thread {self.tid}{named_addition}",
    )

diff(other)

Creates a diff object between two snapshots.

Source code in libdebug/snapshots/thread/thread_snapshot.py 
110
111
112
113
114
115
def diff(self: ThreadSnapshot, other: ThreadSnapshot) -> Diff:
    """Creates a diff object between two snapshots."""
    if not isinstance(other, ThreadSnapshot):
        raise TypeError("Both arguments must be ThreadSnapshot objects.")

    return ThreadSnapshotDiff(self, other)