libpince package

Submodules

libpince.debugcore module

libpince.regexes module

Copyright (C) 2016-2017 Korcan Karaokçu <korcankaraokcu@gmail.com>

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

libpince.regexes.gdb_command_source(command_file)

Return type:

Pattern[str]

libpince.typedefs module

Copyright (C) 2016-2017 Korcan Karaokçu <korcankaraokcu@gmail.com>

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

class libpince.typedefs.ATTACH_RESULT

Bases: object

ALREADY_DEBUGGING = 4

ALREADY_TRACED = 5

ATTACH_SELF = 1

PERM_DENIED = 6

PROCESS_NOT_VALID = 3

SUCCESSFUL = 2

class libpince.typedefs.AllocatedMemory(address, size, identity=None)

Bases: object

class libpince.typedefs.BREAKPOINT_MODIFY

Bases: object

CONDITION = 1

DISABLE = 3

ENABLE = 2

ENABLE_COUNT = 5

ENABLE_DELETE = 6

ENABLE_ONCE = 4

class libpince.typedefs.BREAKPOINT_ON_HIT

Bases: object

BREAK = 1

FIND_ADDR = 3

FIND_CODE = 2

TRACE = 4

class libpince.typedefs.BREAKPOINT_TYPE

Bases: object

HARDWARE = 1

SOFTWARE = 2

class libpince.typedefs.BitFieldValueType(bits=1, start_bit=0, *, value_repr=0)

Bases: ValueType

decode(data)

Return type:

str | int

encode(value)

Return type:

bytes | None

encode_into(current, value)

Return type:

bytes | None

parse(text)

Return type:

int | None

property read_size: int

Number of bytes required for a memory read.

serialize()

Return type:

tuple[int, int, int, int]

text()

Return type:

str

class libpince.typedefs.ByteArrayValueType(length=10)

Bases: ValueType

decode(data)

Return type:

str

encode(value)

Return type:

bytes | None

parse(text)

Return type:

list[int] | None

property read_size: int | None

Number of bytes required for a memory read.

text()

Return type:

str

class libpince.typedefs.ENDIANNESS

Bases: object

BIG = 2

HOST = 0

LITTLE = 1

class libpince.typedefs.FREEZE_TYPE

Bases: object

ALLOW_DECREMENT = 2

ALLOW_INCREMENT = 1

DEFAULT = 0

class libpince.typedefs.FloatValueType(bits=32, *, endian=0)

Bases: ValueType

decode(data)

Return type:

float

encode(value)

Return type:

bytes | None

parse(text)

Return type:

float | None

property read_size: int

Number of bytes required for a memory read.

text()

Return type:

str

class libpince.typedefs.Frozen(value, freeze_type=0)

Bases: object

exception libpince.typedefs.GDBInitializeException(message='GDB not initialized')

Bases: Exception

class libpince.typedefs.INFERIOR_ARCH

Bases: object

ARCH_32 = 1

ARCH_64 = 2

class libpince.typedefs.INFERIOR_STATUS

Bases: object

RUNNING = 1

STOPPED = 2

class libpince.typedefs.IntegerValueType(bits=32, *, value_repr=0, endian=0)

Bases: ValueType

decode(data)

Return type:

str | int

encode(value)

Return type:

bytes | None

parse(text)

Return type:

int | None

property read_size: int

Number of bytes required for a memory read.

text()

Return type:

str

class libpince.typedefs.PATHS

Bases: object

FROM_PINCE = '/from_PINCE'

GDB = '/bin/gdb'

IPC = '/dev/shm/PINCE_IPC/'

TMP = '/tmp/PINCE/'

TO_PINCE = '/to_PINCE'

class libpince.typedefs.PointerChainRequest(base_address, offsets_list=None)

Bases: object

base_address: str | int

get_base_address_as_str()

Returns the text representation of this pointer’s base address

Return type:

str

offsets_list: list[int]

serialize()

Return type:

tuple[str | int, list[int]]

class libpince.typedefs.PointerChainResult

Bases: object

get_final_address()

Return type:

int | None

get_final_address_as_hex()

Returns the hex representation of this pointer chain’s final/destination address

Return type:

str | None

get_pointer_by_index(index)

Return type:

int | None

pointer_chain: list[int]

class libpince.typedefs.REGISTERS

Bases: object

FLAG = ['cf', 'pf', 'af', 'zf', 'sf', 'tf', 'if', 'df', 'of']

class FLOAT

Bases: object

ST = ['st0', 'st1', 'st2', 'st3', 'st4', 'st5', 'st6', 'st7']

XMM_32 = ['xmm0', 'xmm1', 'xmm2', 'xmm3', 'xmm4', 'xmm5', 'xmm6', 'xmm7']

XMM_64 = ['xmm0', 'xmm1', 'xmm2', 'xmm3', 'xmm4', 'xmm5', 'xmm6', 'xmm7', 'xmm8', 'xmm9', 'xmm10', 'xmm11', 'xmm12', 'xmm13', 'xmm14', 'xmm15']

GENERAL_32 = ['eax', 'ebx', 'ecx', 'edx', 'esi', 'edi', 'ebp', 'esp', 'eip']

GENERAL_64 = ['rax', 'rbx', 'rcx', 'rdx', 'rsi', 'rdi', 'rbp', 'rsp', 'rip', 'r8', 'r9', 'r10', 'r11', 'r12', 'r13', 'r14', 'r15']

SEGMENT = ['cs', 'ss', 'ds', 'es', 'fs', 'gs']

class libpince.typedefs.RegisterQueue

Bases: object

broadcast_message(message)

Return type:

None

delete_queue(queue_instance)

Return type:

None

queue_list: list[Queue]

register_queue()

Return type:

Queue

class libpince.typedefs.SCAN_INDEX

Bases: object

ANY = 8

AOB = 10

FLOAT32 = 6

FLOAT64 = 7

FLOAT_ANY = 5

INT16 = 2

INT32 = 3

INT64 = 4

INT8 = 1

INT_ANY = 0

STRING = 9

class libpince.typedefs.SCAN_MODE

Bases: object

NEW = 0

ONGOING = 1

class libpince.typedefs.SCAN_TYPE

Bases: object

BETWEEN = 8

CHANGED = 9

DECREASED = 4

DECREASED_BY = 5

EXACT = 0

INCREASED = 2

INCREASED_BY = 3

LESS = 6

MORE = 7

NOT = 1

UNCHANGED = 10

UNKNOWN = 11

class libpince.typedefs.STEP_MODE

Bases: object

SINGLE_STEP = 1

STEP_OVER = 2

class libpince.typedefs.STOP_REASON

Bases: object

DEBUG = 2

PAUSE = 1

class libpince.typedefs.ScriptEntry(script='')

Bases: object

An address table row that runs a Libpince Engine script when toggled instead of freezing a value.

Only the script is serialized to the cheat table. Namespace is built on first enable and kept so variables set by the [ENABLE] section survive into a later [DISABLE] run within the same session.

namespace: dict[str, Any] | None

class libpince.typedefs.Signal

Bases: object

callbacks: list[Callable]

connect(callback)

Return type:

None

disconnect(callback)

Return type:

None

emit(*args, **kwargs)

Return type:

None

class libpince.typedefs.StringValueType(encoding, *, length=10, zero_terminate=True, endian=0)

Bases: ValueType

decode(data)

Return type:

str

encode(value)

Return type:

bytes | None

parse(text)

Return type:

str | None

property read_size: int | None

Number of bytes required for a memory read.

text()

Return type:

str

class libpince.typedefs.StructValueType

Bases: ValueType

decode(data)

Return type:

None

encode(value)

Return type:

None

parse(text)

Return type:

None

property read_size: None

Number of bytes required for a memory read.

text()

Return type:

str

class libpince.typedefs.Structure(name, members=None)

Bases: object

A named, ordered list of StructureMembers. Offsets are explicit and relative to a base.

classmethod deserialize(data)

Return type:

Structure

serialize()

Return type:

tuple

class libpince.typedefs.StructureMember(name, offset, value_type=None, struct_ref=None, is_pointer=False)

Bases: object

One field of a Structure: a value at an offset or a link to another structure.

Exactly one of value_type / struct_ref is set. Nested members (struct_ref set) are pointer members when is_pointer else inline/embedded.

classmethod deserialize(data)

Return type:

StructureMember

serialize()

Return type:

tuple

class libpince.typedefs.TOGGLE_ATTACH

Bases: object

ATTACHED = 1

DETACHED = 2

class libpince.typedefs.TRACE_STATUS

Bases: object

FINISHED = 3

IDLE = 1

TRACING = 2

class libpince.typedefs.USER_PATHS

Bases: object

CONFIG = '.config/'

GDBINIT = '.config/PINCE/gdbinit'

GDBINIT_AA = '.config/PINCE/gdbinit_after_attach'

PINCEINIT = '.config/PINCE/pinceinit.py'

PINCEINIT_AA = '.config/PINCE/pinceinit_after_attach.py'

ROOT = '.config/PINCE/'

static get_init_files()

Return type:

tuple[str, str, str, str]

class libpince.typedefs.VALUE_REPR

Bases: object

HEX = 2

SIGNED = 1

UNSIGNED = 0

class libpince.typedefs.ValueType

Bases: object

decode(data)

Return type:

Any

static deserialize(data)

Return type:

ValueType

encode(value)

Return type:

bytes | None

parse(text)

Return type:

Any | None

property read_size: int | None

Number of bytes required for a memory read.

serialize()

Return type:

tuple[int, ...]

text()

Return type:

str

class libpince.typedefs.WATCHPOINT_TYPE

Bases: object

BOTH = 3

READ_ONLY = 2

WRITE_ONLY = 1

class libpince.typedefs.gdb_output_mode(async_output, command_output, command_info)

Bases: tuple

async_output

Alias for field number 0

command_info

Alias for field number 2

command_output

Alias for field number 1

class libpince.typedefs.tuple_breakpoint_info(number, breakpoint_type, disp, enabled, address, size, on_hit, hit_count, enable_count, condition)

Bases: tuple

address

Alias for field number 4

breakpoint_type

Alias for field number 1

condition

Alias for field number 9

disp

Alias for field number 2

enable_count

Alias for field number 8

enabled

Alias for field number 3

hit_count

Alias for field number 7

number

Alias for field number 0

on_hit

Alias for field number 6

size

Alias for field number 5

class libpince.typedefs.tuple_examine_expression(all, address, symbol)

Bases: tuple

address

Alias for field number 1

all

Alias for field number 0

symbol

Alias for field number 2

class libpince.typedefs.tuple_region_info(start, end, perms, file_name, region_index)

Bases: tuple

end

Alias for field number 1

file_name

Alias for field number 3

perms

Alias for field number 2

region_index

Alias for field number 4

start

Alias for field number 0

libpince.utils module

Copyright (C) Korcan Karaokçu <korcankaraokcu@gmail.com>

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

libpince.utils.aob_to_str(list_of_bytes, encoding='ascii', replace_unprintable=True)

Converts given array of hex strings to str

Parameters:

• list_of_bytes (list[int | str] | int | str) – Must be returned from debugcore.hex_dump()

• encoding (str) – See here–>https://docs.python.org/3/library/codecs.html#standard-encodings

• replace_unprintable (bool) – If True, replaces non-printable characters with a period (.)

Returns:

str equivalent of array

Return type:

str

libpince.utils.append_file_extension(string, extension)

Appends the given extension to the given string if it doesn’t end with the given extension

Parameters:

• string (str) – Self-explanatory

• extension (str) – Self-explanatory, you don’t have to include the dot

Returns:

Given string with the extension

Return type:

str

libpince.utils.assemble(instructions, address, inferior_arch)

Assembles the given instructions

Parameters:

• instructions (str) – A string of instructions, multiple entries separated by ;

• address (int) – Starting address of the instructions

• inferior_arch (int) – Can be a member of typedefs.INFERIOR_ARCH

Returns:

A tuple of (list, int) –> Assembled bytes (list of int) and instruction count (int) None: If there was an error

Return type:

tuple[list[int], int] | None

libpince.utils.change_trace_status(pid, trace_status)

Change trace status for given pid

Parameters:

• pid (int | str) – PID of the process

• trace_status (int) – New trace status, can be a member of typedefs.TRACE_STATUS

Return type:

None

libpince.utils.clear_log()

Return type:

None

libpince.utils.create_ipc_path(pid)

Creates the IPC directory of given pid

Parameters:

pid (int | str) – PID of the process

Return type:

None

libpince.utils.create_tmp_path(pid)

Creates the tmp directory of given pid

Parameters:

pid (int | str) – PID of the process

Return type:

None

libpince.utils.delete_ipc_path(pid)

Deletes the IPC directory of given pid

Parameters:

pid (int | str) – PID of the process

Return type:

None

libpince.utils.disassemble(aob, address, inferior_arch)

Returns the instructions from the given array of bytes

Parameters:

• aob (str) – Opcode bytes of the instruction as an array of bytes

• address (int) – The address where the instruction starts from

• inferior_arch (int) – Architecture type (x86, x64). Can be a member of typedefs.INFERIOR_ARCH

Returns:

Instructions, multiple entries are separated with ; None: If there was an error

Return type:

str | None

libpince.utils.execute_command_as_user(command)

Executes given command as the original user who invoked PINCE

Parameters:

command (str) – Command that’ll be invoked from the shell

Return type:

None

libpince.utils.execute_script(file_path)

Loads and executes the script in the given path

Parameters:

file_path (str) – Self-explanatory

Returns:

(module, exception) module–> Loaded script as module exception–> traceback as str

Returns (None, exception) if fails to load the script Returns (module, None) if script gets loaded successfully

Return type:

tuple[ModuleType | None, str | None]

libpince.utils.extract_hex_address(string)

Extracts hex address from the given string

Parameters:

string (str) – The string that the hex address will be extracted from

Returns:

Hex address None: If no hex address is found

Return type:

str | None

libpince.utils.extract_symbol_name(symbol_string)

Extract symbol name from examine_expression result

Parameters:

symbol_string (str) – A string that contains a symbol in format <symbol_name>

Returns:

Symbol name without brackets or empty string if no symbol is found

Return type:

str

libpince.utils.filter_regions(pid, attribute, regex, case_sensitive=False)

Filters memory regions by searching for the given regex within the given attribute

Parameters:

• pid (int) – PID of the process

• attribute (str) – The attribute that’ll be filtered. Can be one of the below

• start_address

• end_address

• permissions

• map_offset

• device_node

• inode

• path

• regex (str) – Regex statement that’ll be searched

• case_sensitive (bool) – If True, search will be case sensitive

Returns:

List of (start_address, end_address, permissions, map_offset, device_node, inode, path) -> all str

Return type:

list[tuple[str, ...]]

libpince.utils.get_default_gdb_path()

Return type:

str

libpince.utils.get_defined_dynamic_symbols(elf_path, symbol_names)

Parses the .dynsym/.dynstr of an ELF file and returns {name: st_value} for each requested symbol that is defined in the file. Handles ELFCLASS32/64 and both endiannesses.

Parameters:

• elf_path (str) – Path to the ELF file on disk

• symbol_names (list[str]) – List of symbol names to look up

Returns:

{symbol_name: st_value} for each defined symbol found Empty dict on failure or if no section headers are present

Return type:

dict[str, int]

libpince.utils.get_effective_arch(pid)

Returns the arch of the code the debugged program actually executes, unlike the arch of the host process.

They can differ in WINE processes, particularly with New-WoW64 where 32 bits PE programs run inside a 64 bits host process.

Parameters:

pid (int) – PID of the process

Returns:

A member of typedefs.INFERIOR_ARCH, -1 if detection fails

Return type:

int

libpince.utils.get_from_pince_file(pid)

Get the path of IPC file sent to custom gdb commands from PINCE for given pid

Parameters:

pid (int | str) – PID of the process

Returns:

Path of IPC file

Return type:

str

libpince.utils.get_gdb_command_file(pid)

Get the path of gdb command file of given pid

Parameters:

pid (int | str) – PID of the process

Returns:

Path of gdb command file

Return type:

str

libpince.utils.get_ipc_path(pid)

Get the IPC directory of given pid

Parameters:

pid (int | str) – PID of the process

Returns:

Path of IPC directory

Return type:

str

libpince.utils.get_libpince_directory()

Get libpince directory

Returns:

A string pointing to the libpince directory

Return type:

str

Note

In fact this function returns the directory where utils in and considering the fact that utils resides in libpince, it works. So, please don’t move out utils outside of libpince folder!

libpince.utils.get_logging_file(pid)

Get the path of gdb logfile of given pid

Parameters:

pid (int | str) – PID of the process

Returns:

Path of gdb logfile

Return type:

str

libpince.utils.get_logo_directory()

Get logo directory

Returns:

A string pointing to the logo directory

Return type:

str

libpince.utils.get_media_directory()

Get media directory

Returns:

A string pointing to the media directory

Return type:

str

libpince.utils.get_module_dict(pid_or_memory_regions)

Returns logical module bases keyed by basename, or by full path when a basename is ambiguous. Unique shortcuts for versioned sonames are also included. Empty paths are ignored.

Parameters:

pid_or_memory_regions (int | list[tuple[str, ...]]) – PID of the process or output from get_regions

Returns:

{module_name_or_path:load_base}

Return type:

dict[str, str]

libpince.utils.get_module_load_bias(pid, name_regex)

Finds the first mapped file whose basename matches name_regex and returns its load bias and absolute path.

Parameters:

• pid (int) – PID of the process

• name_regex (str) – Regular expression to match against the basename of mapped files

Returns:

(load_bias, absolute_path) where load_bias is an int and absolute_path is a str None: If no matching module is found

Return type:

tuple[int, str] | None

libpince.utils.get_process_list()

Returns a list of processes

Returns:

List of (pid, user, process_name) -> (str, str, str)

Return type:

list[tuple[str, str, str]]

libpince.utils.get_process_name(pid)

Returns the process name of given pid

Parameters:

pid (int | str) – PID of the process

Returns:

Process name

Return type:

str

libpince.utils.get_process_start_time(pid)

Returns the process start time (field 22 of /proc/<pid>/stat, clock ticks since boot). Combined with pid this uniquely identifies a process instance, guarding against PID reuse.

Parameters:

pid (int | str) – PID of the process

Returns:

starttime field, or None on error

Return type:

int | None

libpince.utils.get_referenced_calls_file(pid)

Get the path of referenced calls dict file for given pid

Parameters:

pid (int | str) – PID of the process

Returns:

Path of referenced calls dict file

Return type:

str

libpince.utils.get_referenced_jumps_file(pid)

Get the path of referenced jumps dict file for given pid

Parameters:

pid (int | str) – PID of the process

Returns:

Path of referenced jumps dict file

Return type:

str

libpince.utils.get_referenced_strings_file(pid)

Get the path of referenced strings dict file for given pid

Parameters:

pid (int | str) – PID of the process

Returns:

Path of referenced strings dict file

Return type:

str

libpince.utils.get_region_dict(pid_or_memory_regions)

Returns memory regions of a process as a dictionary where key is the path tail and value is the list of the corresponding start addresses of the tail, empty paths will be ignored. Also adds shortcuts for file extensions. Returned dict will include both sonames, with and without version information.

Parameters:

pid_or_memory_regions (int | list[tuple[str, ...]]) – PID of the process or output from get_regions

Returns:

{file_name:start_address_list}

Return type:

dict[str, list[str]]

libpince.utils.get_region_info(pid, address)

Finds the closest valid starting/ending address and region to given address, assuming given address is in the valid address range

Parameters:

• pid (int | str) – PID of the process

• address (int | str) – Can be an int or a hex str

Returns:

List of (start_address, end_address, permissions, file_name) -> (int, int, str, str) None: If the given address isn’t in any valid address range

Return type:

tuple_region_info | None

libpince.utils.get_regions(pid)

Returns memory regions of a process

Parameters:

pid (int) – PID of the process

Returns:

List of (start_address, end_address, permissions, map_offset, device_node, inode, path) -> all str

Return type:

list[tuple[str, ...]]

libpince.utils.get_script_directory()

Get main script directory

Returns:

A string pointing to the main script directory

Return type:

str

libpince.utils.get_tmp_path(pid)

Get the tmp directory of given pid

Parameters:

pid (int | str) – PID of the process

Returns:

Path of tmp directory

Return type:

str

libpince.utils.get_to_pince_file(pid)

Get the path of IPC file sent to PINCE from custom gdb commands for given pid

Parameters:

pid (int | str) – PID of the process

Returns:

Path of IPC file

Return type:

str

libpince.utils.get_trace_status_file(pid)

Get the path of trace status file for given pid

Parameters:

pid (int | str) – PID of the process

Returns:

Path of trace status file

Return type:

str

libpince.utils.get_track_breakpoint_file(pid, breakpoint_number)

Get the path of track breakpoint file for given pid and breakpoint

Parameters:

• pid (int | str) – PID of the process

• breakpoint_number (int | str)

Returns:

Path of track breakpoint file

Return type:

str

libpince.utils.get_track_watchpoint_file(pid, watchpoint_list)

Get the path of track watchpoint file for given pid and watchpoint

Parameters:

• pid (int | str) – PID of the process

• watchpoint_list (list | str) – Numbers of the watchpoints

Returns:

Path of track watchpoint file

Return type:

str

libpince.utils.get_user_home_dir()

Returns the home directory of the current user

Returns:

Home directory of the current user

Return type:

str

libpince.utils.get_user_ids()

Gets uid and gid of the user who invoked PINCE/libpince. Resolves real user if invoked through sudo/pkexec.

Returns:

uid and gid of the real invoking user.

Return type:

tuple[str, str]

libpince.utils.get_user_path(user_path)

Returns the specified user path for the current user

Parameters:

user_path (str) – Can be a member of typedefs.USER_PATHS

Returns:

Specified user path of the current user

Return type:

str

libpince.utils.ignore_exceptions(func)

A decorator to ignore exceptions

Return type:

Callable

libpince.utils.init_logging()

Return type:

None

libpince.utils.init_user_files()

Initializes user files

Return type:

None

libpince.utils.instruction_aligned_size(aob, minimum_bytes, inferior_arch)

Walks instructions from offset 0 of aob until cumulative size meets or exceeds minimum_bytes. Used by code-injection hooks where the patch must end on an instruction boundary so the next instruction decodes cleanly.

Parameters:

• aob (bytes) – Instruction stream starting at offset 0.

• minimum_bytes (int) – Minimum number of bytes the result must cover.

• inferior_arch (int) – Member of typedefs.INFERIOR_ARCH.

Returns:

Smallest instruction-aligned size >= minimum_bytes, or 0 if the bytes couldn’t be decoded far enough.

Return type:

int

libpince.utils.instruction_follow_address(string)

Searches for the location changing instructions such as Jcc, CALL and LOOPcc in the given string. Returns the hex address the instruction jumps to

Parameters:

string (str) – An assembly expression

Returns:

Hex address None: If no hex address is found or no location changing instructions found

Return type:

str | None

libpince.utils.is_process_valid(pid)

Check if the process corresponding to given pid is valid

Parameters:

pid (int) – PID of the process

Returns:

True if the process is still running, False if not

Return type:

bool

libpince.utils.is_traced(pid)

Check if the process corresponding to given pid traced by any other process

Parameters:

pid (int) – PID of the process

Returns:

Name of the tracer if the specified process is being traced None: if the specified process is not being traced or the process doesn’t exist anymore

Return type:

str | None

libpince.utils.is_wine_process(pid)

Check if the inferior is running under Wine or Proton.

Scans /proc/<pid>/maps for WINE or Proton libraries. Mostly used to gate features that don’t yet work reliably under WINE in the GUI.

Parameters:

pid (int) – PID of the process

Returns:

True if Wine/Proton libraries are mapped into the process

Return type:

bool

libpince.utils.load_file(file_path, load_method='json')

Loads data from the given path

Parameters:

• file_path (str) – Path of the saved file

• load_method (str) – Can be “json” or “pickle”

Returns:

file_path is like a box of chocolates, you never know what you’re gonna get None: If loading fails

Return type:

Any

libpince.utils.modulo_address(int_address, arch_type)

Calculates the modulo of the given integer based on the given architecture type to make sure that it doesn’t exceed the borders of the given architecture type (0xffffffff->x86, 0xffffffffffffffff->x64)

Parameters:

• int_address (int) – Self-explanatory

• arch_type (int) – Architecture type (x86, x64). Can be a member of typedefs.INFERIOR_ARCH

Returns:

Modulo of the given integer based on the given architecture type

Return type:

int

libpince.utils.parse_response(response, line_num=0)

Parses the given GDB/MI output. Wraps gdbmiparser.parse_response debugcore.send_command returns an additional “^done” output because of the “source” command This function is used to get rid of that output before parsing

Parameters:

• response (str) – GDB/MI response

• line_num (int) – Which line of the response will be parsed

Returns:

Contents of the dict depends on the response

Return type:

dict

libpince.utils.resolve_mapped_path(pid, mapped_path)

Resolves a path from an inferior’s /proc/PID/maps into one PINCE can open.

Sandboxed inferiors (Flatpak, Steam pressure-vessel) report library paths in their own mount namespace (e.g. /run/host/usr/lib/libc.so.6) which don’t exist in PINCE’s namespace. Going through /proc/PID/root resolves the exact file the inferior mapped regardless of the sandbox.

Parameters:

• pid (int) – PID of the inferior

• mapped_path (str) – A file path as it appears in the inferior’s /proc/PID/maps

Returns:

mapped_path if it’s directly readable, else the /proc/PID/root path to the same file, falling back to mapped_path if neither exists.

Return type:

str

libpince.utils.return_optional_int(val)

Return type:

int | None

libpince.utils.safe_int_cast(input)

Return type:

int

libpince.utils.safe_str_to_int(input, base)

Return type:

int

libpince.utils.save_file(data, file_path, save_method='json')

Saves the specified data to given path

Parameters:

• data (Any) – Saved data, can be anything, must be supported by save_method

• file_path (str) – Path of the saved file

• save_method (str) – Can be “json” or “pickle”

Returns:

True if saved successfully, False if not

Return type:

bool

libpince.utils.search_files(directory, regex)

Searches the files in given directory for given regex recursively

Parameters:

• directory (str) – Directory to search for

• regex (str) – Regex to search for

Returns:

Sorted list of the relative paths(to the given directory) of the files found

Return type:

list[str]

libpince.utils.search_processes(name_or_pid)

Searches processes and returns a list of the ones that contain given process name or pid

Parameters:

name_or_pid (str | int) – Name or PID of the process that’ll be searched for

Returns:

List of (pid, user, process_name) -> (str, str, str)

Return type:

list[tuple[str, str, str]]

libpince.utils.split_symbol(symbol_string)

Splits symbol part of typedefs.tuple_function_info into smaller fractions Fraction count depends on the symbol_string. See Examples section for demonstration

Parameters:

symbol_string (str) – symbol part of typedefs.tuple_function_info

Returns:

A list containing parts of the split symbol

Return type:

list[str]

Examples

symbol_string–>”func(param)@plt” returned_list–>[“func”,”func(param)”,”func(param)@plt”]

symbol_string–>”malloc@plt” returned_list–>[“malloc”, “malloc@plt”]

symbol_string–>”printf” returned_list–>[“printf”]

libpince.utils.str_to_aob(string, encoding='ascii')

Converts given string to aob string

Parameters:

• string (str) – Any string

• encoding (str) – See here–>https://docs.python.org/3/library/codecs.html#standard-encodings

Returns:

AoB equivalent of the given string

Return type:

str

libpince.utils.upper_hex(hex_str)

Converts the given hex string to uppercase while keeping the ‘x’ character lowercase

Return type:

str

Module contents