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)

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.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.CONST_TIME

Bases: object

GDB_INPUT_SLEEP = 2.2250738585072014e-308

class libpince.typedefs.ENDIANNESS

Bases: object

BIG = 2

HOST = 0

LITTLE = 1

class libpince.typedefs.FREEZE_TYPE

Bases: object

DECREMENT = 2

DEFAULT = 0

INCREMENT = 1

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.INJECTION_METHOD

Bases: object

ADVANCED = 2

DLOPEN = 1

class libpince.typedefs.KeyboardModifiersTupleDict(OrderedDict_like_list)

Bases: Mapping

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

get_base_address_as_str()

Returns the text representation of this pointer’s base address

Return type:

str

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

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)

delete_queue(queue_instance)

register_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_SCOPE

Bases: object

BASIC = 1

FULL = 4

FULL_RW = 3

NORMAL = 2

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

static get_list(scan_mode, value_type)

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.TOGGLE_ATTACH

Bases: object

ATTACHED = 1

DETACHED = 2

class libpince.typedefs.TRACE_STATUS

Bases: object

CANCELED = 3

FINISHED = 4

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()

class libpince.typedefs.VALUE_INDEX

Bases: object

AOB = 10

FLOAT32 = 4

FLOAT64 = 5

INT16 = 1

INT32 = 2

INT64 = 3

INT8 = 0

STRING_ASCII = 6

STRING_UTF16 = 8

STRING_UTF32 = 9

STRING_UTF8 = 7

static has_length(value_index)

static is_float(value_index)

static is_integer(value_index)

static is_number(value_index)

static is_string(value_index)

class libpince.typedefs.VALUE_REPR

Bases: object

HEX = 2

SIGNED = 1

UNSIGNED = 0

class libpince.typedefs.ValueType(value_index=2, length=10, zero_terminate=True, value_repr=0, endian=0)

Bases: object

serialize()

text()

Returns the text representation according to its members

Returns:

A str generated by given parameters

Return type:

str

Examples

value_index=VALUE_INDEX.STRING_UTF16, length=15, zero_terminate=False–▼ returned str=”String_UTF16[15],NZT” value_index=VALUE_INDEX.AOB, length=42–>returned str=”AoB[42]”

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)

Bases: tuple

end

Alias for field number 1

file_name

Alias for field number 3

perms

Alias for field number 2

start

Alias for field number 0

libpince.utils 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.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) – 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) – Address of the instruction

• 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

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

libpince.utils.create_ipc_path(pid)

Creates the IPC directory of given pid

Parameters:

pid (int,str) – PID of the process

libpince.utils.create_tmp_path(pid)

Creates the tmp directory of given pid

Parameters:

pid (int,str) – PID of the process

libpince.utils.delete_ipc_path(pid)

Deletes the IPC directory of given pid

Parameters:

pid (int,str) – PID of the process

libpince.utils.execute_command_as_user(command)

Executes given command as user

Parameters:

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

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

libpince.utils.extract_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

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

libpince.utils.get_default_gdb_path()

libpince.utils.get_dissect_code_status_file(pid)

Get the path of dissect code status file for given pid

Parameters:

pid (int,str) – PID of the process

Returns:

Path of dissect code status file

Return type:

str

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) – 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_name(module)

Gets the name of the given module without the package name

Parameters:

module (module) – A module

Returns:

Name of the module

Return type:

str

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

Returns the instructions from the given array of bytes

Parameters:

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

• aob (str) – Bytes of the opcode as an array of bytes

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

Returns:

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

Return type:

str

libpince.utils.get_process_list()

Returns a list of processes

Returns:

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

Return type:

list

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_referenced_calls_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 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)

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 (int) – PID of the process

Returns:

{file_name:start_address_list}

Return type:

dict

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) – 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:

list

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

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) – 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)

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

Parameters:

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

• breakpoint (str) – breakpoint number

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 current user

Returns:

(str, str)–>uid and gid of the current user

Return type:

tuple

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

libpince.utils.init_user_files()

Initializes user files

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

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

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:

??

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.parse_string(string, value_index)

Parses the string according to the given value_index

Parameters:

• string (str) – String that’ll be parsed

• value_index (int) – Determines the type of data. Can be a member of typedefs.VALUE_INDEX

Returns:

If the value_index is STRING list: If the value_index is AOB. A list of ints is returned float: If the value_index is FLOAT32 or FLOAT64 int: If the value_index is anything else None: If the string is not parsable by using the parameter value_index

Return type:

str

Examples

string=”42 DE AD BE EF 24”,value_index=typedefs.VALUE_INDEX.AOB–▼ returned_list=[66, 222, 173, 190, 239, 36]

libpince.utils.return_optional_int(val)

Return type:

int | None

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

Saves the specified data to given path

Parameters:

• data – 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

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) – Name or PID of the process that’ll be searched for

Returns:

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

Return type:

list

libpince.utils.split_symbol(symbol_string)

Splits symbol part of typedefs.tuple_function_info into smaller fractions Fraction count depends on the 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 splitted symbol

Return type:

list

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

Module contents