libpince package

Submodules

libpince.debugcore 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.debugcore.Tracer

Bases: object

cancel_trace()

Prematurely ends the trace session, trace data will still be collected

set_breakpoint(**kwargs)

tracer_loop()

The main tracer loop, call within a thread

libpince.debugcore.add_breakpoint(expression, breakpoint_type=1, on_hit=1)

Adds a breakpoint at the address evaluated by the given expression. Uses a software breakpoint if all hardware breakpoint slots are being used

Parameters:

• expression (str) – Any gdb expression

• breakpoint_type (int) – Can be a member of typedefs.BREAKPOINT_TYPE

• on_hit (int) – Can be a member of typedefs.BREAKPOINT_ON_HIT

Returns:

Number of the breakpoint set None: If setting breakpoint fails

Return type:

str

libpince.debugcore.add_watchpoint(*args, **kwargs)

libpince.debugcore.attach(pid, gdb_path='/bin/gdb')

Attaches gdb to the target and initializes some of the global variables

Parameters:

• pid (int,str) – PID of the process that’ll be attached to

• gdb_path (str) – Path of the gdb binary

Returns:

A member of typedefs.ATTACH_RESULT

Return type:

int

Note

If gdb is already initialized, gdb_path will be ignored

libpince.debugcore.call_function_from_inferior(expression)

Calls the given function expression from the inferior

Parameters:

expression (str) – Any gdb expression

Returns:

A tuple containing assigned value and result, both as str Returns a tuple of (False, False) if the call fails

Return type:

tuple

Examples

call_function_from_inferior(“printf(‘123’)”) returns (“$26”,”3”)

libpince.debugcore.can_attach(pid)

Check if we can attach to the target

Parameters:

pid (int,str) – PID of the process that’ll be attached

Returns:

True if attaching is successful, False otherwise

Return type:

bool

libpince.debugcore.cancel_dissect_code()

Finishes the current dissect code process early on

libpince.debugcore.cancel_last_command()

Cancels the last gdb command sent if it’s still present

libpince.debugcore.complete_command(gdb_command)

Tries to complete the given gdb command and returns completion possibilities

Parameters:

gdb_command (str) – The gdb command that’ll be completed

Returns:

Possible completions as a list of str

Return type:

list

libpince.debugcore.continue_inferior()

Continue the inferior

libpince.debugcore.convert_to_hex(expression)

Converts numeric values in the expression into their hex equivalents Respects edge cases like indexed maps and keeps indexes as decimals

Parameters:

expression (str) – Any gdb expression

Returns:

Converted str

Return type:

str

libpince.debugcore.create_process(process_path, args='', ld_preload_path='', gdb_path='/bin/gdb')

Creates a new process for debugging and initializes some of the global variables Current process will be detached even if the create_process call fails Make sure to save your data before calling this monstrosity

Parameters:

• process_path (str) – Absolute path of the target binary

• args (str) – Arguments of the inferior, optional

• ld_preload_path (str) – Path of the preloaded .so file, optional

• gdb_path (str) – Path of the gdb binary

Returns:

True if the process has been created successfully, False otherwise

Return type:

bool

Note

If gdb is already initialized, gdb_path will be ignored

libpince.debugcore.delete_breakpoint(expression)

Deletes a breakpoint at the address evaluated by the given expression

Parameters:

expression (str) – Any gdb expression

Returns:

True if the breakpoint has been deleted successfully, False otherwise

Return type:

bool

libpince.debugcore.detach()

See you, space cowboy

libpince.debugcore.disassemble(expression, offset_or_address)

Disassembles the address evaluated by the given expression

Parameters:

• expression (the address range between the) – Any gdb expression

• offset_or_address (str) – If you pass this parameter as an offset, you should add “+” in front of it

• address (it always should be bigger than the first)

• expression

• disassembled (and the secondary address is)

• address

• address

Returns:

A list of str values in this format–>[(address1, bytes1, opcodes1), (address2, …), …]

Return type:

list

libpince.debugcore.dissect_code(region_list, discard_invalid_strings=True)

Searches given regions for jumps, calls and string references Use function get_dissect_code_data() to gather the results

Parameters:

• region_list (list) – A list of (start_address, end_address) -> (str, str)

• utils.filter_regions (Can be returned from functions like)

• discard_invalid_strings (bool) – Entries that can’t be decoded as utf-8 won’t be included in referenced strings

libpince.debugcore.examine_expression(expression)

Evaluates the given expression and returns evaluated value, address and symbol

Parameters:

expression (str) – Any gdb expression

Returns:

Evaluated value, address and symbol in a tuple Any erroneous field will be returned as None instead of str

Return type:

typedefs.tuple_examine_expression

libpince.debugcore.examine_expressions(expression_list)

Optimized version of examine_expression for multiple inputs

Parameters:

expression_list (list) – List of gdb expressions as str

Returns:

List of typedefs.tuple_examine_expression

Return type:

list

libpince.debugcore.execute_func_temporary_interruption(func, *args, **kwargs)

Interrupts the inferior before executing the given function, continues inferior’s execution after calling the given function

!!!WARNING!!! This function is NOT thread-safe. Use it with caution!

Parameters:

• func (function) – The function that’ll be called between interrupt&continue routine

• *args (args) – Arguments for the function that’ll be called

• **kwargs (kwargs) – Keyword arguments for the function that’ll be called

Returns:

Result of the given function. Return type depends on the given function

Return type:

???

libpince.debugcore.execute_till_return()

Continues inferior till current stack frame returns

libpince.debugcore.execute_with_temporary_interruption(func)

Decorator version of execute_func_temporary_interruption

libpince.debugcore.find_closest_instruction_address(address, instruction_location='next', instruction_count=1)

Finds address of the closest instruction next to the given address, assuming that the given address is valid

Parameters:

• address (str) – Hex address or any gdb expression that can be used in disas command

• instruction_location (str) – If it’s “next”, instructions coming after the address is searched

• "previous" (If it's)

• instead (the instructions coming before the address is searched)

• instruction_count (int) – Number of the instructions that’ll be looked for

Returns:

The address found as hex string. If starting/ending of a valid memory range is reached, starting/ending address is returned instead as hex string.

Return type:

str

Note

From gdb version 7.12 and onwards, inputting negative numbers in x command are supported(x/-3i for instance) So, modifying this function according to the changes in 7.12 may speed up things a little bit but also breaks the backwards compatibility. The speed gain is not much of a big deal compared to backwards compatibility, so I’m not changing this function for now

libpince.debugcore.find_entry_point()

Finds entry point of the inferior

Returns:

Entry point as hex str None: If fails to find an entry point

Return type:

str

libpince.debugcore.get_address_info(expression)

Runs the gdb command “info symbol” for given expression and returns the result of it

Parameters:

expression (str) – Any gdb expression

Returns:

The result of the command “info symbol” for given expression

Return type:

str

libpince.debugcore.get_breakpoint_info()

Returns current breakpoint/watchpoint list

Returns:

A list of typedefs.tuple_breakpoint_info where;

number is the gdb breakpoint number breakpoint_type is the breakpoint type disp shows what will be done after breakpoint hits enabled shows if the breakpoint enabled or disabled address is the address of breakpoint size is the size of breakpoint on_hit is the action that’ll happen when the breakpoint is reached hit_count shows how many times the breakpoint has been hit enable_count shows how many times the breakpoint will get hit before it gets disabled condition is the condition of breakpoint

size–>int everything else–>str

Return type:

list

Note

GDB’s python API can’t detect hardware breakpoints, that’s why we are using parser for this job

libpince.debugcore.get_breakpoints_in_range(address, length=1)

Checks if given address exists in breakpoint list

Parameters:

• address (str,int) – Start address of the range, hex address or an int

• length (int) – If this parameter is bigger than 1, the range between address and address+length-1 will be

• itself (checked instead of just the address)

Returns:

A list of typedefs.tuple_breakpoint_info, info of the existing breakpoints for given address range

Return type:

list

libpince.debugcore.get_dissect_code_data(referenced_strings=True, referenced_jumps=True, referenced_calls=True)

Returns shelve.DbfilenameShelf objects of referenced dicts

Parameters:

• referenced_strings (bool) – If True, include referenced strings in the returned list

• referenced_jumps (bool) – If True, include referenced jumps in the returned list

• referenced_calls (bool) – If True, include referenced calls in the returned list

Returns:

A list of shelve.DbfilenameShelf objects. Can be used as dicts, they are backwards compatible

For instance, if you call this function with default params, you’ll get this–▼ [referenced_strings_dict,referenced_jumps_dict,referenced_calls_dict]

And if you, let’s say, pass referenced_jumps as False, you’ll get this instead–▼ [referenced_strings_dict,referenced_calls_dict]

referenced_strings_dict–>(shelve.DbfilenameShelf object) Holds referenced string addresses Format: {referenced_address1:referrer_address_set1, referenced_address2:referrer_address_set2, …}

referenced_jumps_dict–>(shelve.DbfilenameShelf object) Holds referenced jump addresses Format: {referenced_address1:referenced_by_dict1, referenced_address2:referenced_by_dict2, …} Format of referenced_by_dict: {address1:opcode1, address2:opcode2, …}

referenced_calls_dict–>(shelve.DbfilenameShelf object) Holds referenced call addresses Format: {referenced_address1:referrer_address_set1, referenced_address2:referrer_address_set2, …}

Return type:

list

libpince.debugcore.get_dissect_code_status()

Returns the current state of dissect code process

Returns:

(current_region, current_region_count, referenced_strings_count,

referenced_jumps_count, referenced_calls_count)

current_region–>(str) Currently scanned memory region current_region_count–>(str) “Region x of y” current_range–>(str) Currently scanned memory range(current buffer) referenced_strings_count–>(int) Count of referenced strings referenced_jumps_count–>(int) Count of referenced jumps referenced_calls_count–>(int) Count of referenced calls

Returns a tuple of (“”, “”, “”, 0, 0, 0) if fails to gather info

Return type:

tuple

libpince.debugcore.get_inferior_arch()

Returns the architecture of the current inferior

Returns:

A member of typedefs.INFERIOR_ARCH

Return type:

int

libpince.debugcore.get_inferior_pid()

Get pid of the current inferior

Returns:

pid

Return type:

str

libpince.debugcore.get_modified_instructions()

Returns currently modified instructions

Returns:

A dictionary where the key is the start address of instruction and value is the aob before modifying

Return type:

dict

libpince.debugcore.get_stack_frame_info(index)

Returns information about stack by the given index

Parameters:

index (int,str) – Index of the frame

Returns:

Information that looks like this:

Stack level 0, frame at 0x7ffc5f87f6a0:
    rip = 0x7fd1d639412d in poll (../sysdeps/unix/syscall-template.S:81); saved rip = 0x7fd1d27fcfe4
    called by frame at 0x7ffc5f87f700
    source language asm.
    Arglist at 0x7ffc5f87f688, args:
    Locals at 0x7ffc5f87f688, Previous frame's sp is 0x7ffc5f87f6a0
    Saved registers:
        rip at 0x7ffc5f87f698

Return type:

str

libpince.debugcore.get_stack_frame_return_addresses()

Returns return addresses of stack frames

Returns:

A list of str values in this format–>[return_address_info1,return_address_info2, …]

return_address_info looks like this–>Return address of frame+symbol–>0x40c431 <_start>

Return type:

list

libpince.debugcore.get_stack_info(from_base_pointer=False)

Returns information about current stack Also can view stack from EBP or RBP register

Returns:

A list of str values in this format–▼ [[stack_pointer_info1,hex_value1,pointer_info1],[stack_pointer_info2, …], …]

stack_pointer_info looks like this–>Hex address+distance from stack pointer–>0x7ffd0d232f88(rsp+0xff8) hex_value looks like this–>Value hold by corresponding address–>0x1bfda20 pointer_info shows the value hold by hex_value address. It looks like this–▼ if points to a string–>(str)Some String if points to a symbol–>(ptr)<function_name> pointer_info becomes a null string if pointer isn’t valid

Return type:

list

libpince.debugcore.get_stacktrace_info()

Returns information about current stacktrace

Returns:

A list of str values in this format–>[[return_address_info1,frame_address_info1],[info2, …], …]

return_address_info looks like this–>Return address of frame+symbol–>0x40c431 <_start> frame_address_info looks like this–>Beginning of frame+distance from stack pointer–>0x7ffe1e989a40(rsp+0x100)

Return type:

list

libpince.debugcore.get_symbol_info(expression)

Runs the gdb command “info address” for given expression and returns the result of it

Parameters:

expression (str) – Any gdb expression

Returns:

The result of the command “info address” for given expression

Return type:

str

libpince.debugcore.get_thread_info()

Invokes “info threads” command and returns the line corresponding to the current thread

Returns:

Current thread information None: If the output doesn’t fit the regex

Return type:

str

libpince.debugcore.get_track_breakpoint_info(breakpoint)

Gathers the information for the tracked breakpoint

Parameters:

breakpoint (str) – breakpoint number, must be returned from track_breakpoint()

Returns:

Holds the register expressions as keys and their info as values Format of dict–> {expression1:expression_info_dict1, expression2:expression_info_dict2, …} expression–>(str) The register expression Format of expression_info_dict–> {value1:count1, value2:count2, …} value–>(str) Value calculated by given register expression as hex str count–>(int) How many times this expression has been reached

Return type:

dict

libpince.debugcore.get_track_watchpoint_info(watchpoint_list)

Gathers the information for the tracked watchpoint(s)

Parameters:

watchpoint_list (list) – A list that holds the watchpoint numbers, must be returned from track_watchpoint()

Returns:

Holds the program counter addresses at the moment watchpoint hits as keys Format of dict–> {address1:info_list1, address2:info_list2, …} Format of info_list–> [count, previous_pc_address, register_info, float_info, disas_info] count–>(int) Count of the hits for the same pc address previous_pc_address–>(str) The address of the instruction that comes before the instruction pc address holds. If there’s no previous address available(end of region etc.), previous_pc_address=pc_address register_info–>(dict) Same dict returned from read_registers() float_info–>(dict) Same dict returned from read_float_registers() disas_info–>(str) A small section that’s disassembled just after previous_pc_counter

Return type:

dict

libpince.debugcore.handle_signal(signal_name, stop, pass_to_program)

Decides on what will GDB do when the process recieves a signal

Parameters:

• signal_name (str) – Name of the signal

• stop (bool) – Stop the program and print to the console

• pass_to_program (bool) – Pass signal to program

Return type:

None

libpince.debugcore.handle_signals(signal_list)

Optimized version of handle_signal for multiple signals

Parameters:

signal_list (list) – A list of the parameters of handle_signal

libpince.debugcore.hardware_breakpoint_available()

Checks if there is an available hardware breakpoint slot

Returns:

True if there is at least one available slot, False if not

Return type:

bool

libpince.debugcore.hex_dump(address, offset)

Returns hex dump of range (address to address+offset)

Parameters:

• address (int) – Self-explanatory

• offset (int) – The range that’ll be read

Returns:

List of strings read as str. If an error occurs while reading a memory cell, that cell is returned as “??” An empty list is returned if an error occurs

Return type:

list

Examples

returned list–>[“??”,”??”,”??”,”7f”,”43”,”67”,”40”,”??”,”??, …]

libpince.debugcore.init_gdb(gdb_path='/bin/gdb')

Spawns gdb and initializes/resets some of the global variables

Parameters:

gdb_path (str) – Path of the gdb binary

Returns:

True if initialization is successful, False otherwise

Return type:

bool

Note

Calling init_gdb() will reset the current session

libpince.debugcore.init_referenced_dicts(pid)

Initializes referenced dict shelve databases

Parameters:

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

libpince.debugcore.inject_with_advanced_injection(library_path)

Injects the given .so file to current process

Parameters:

library_path (str) – Path to the .so file that’ll be injected

Returns:

Result of the injection

Return type:

bool

Note

This function was reserved for linux-inject and since linux-inject is no more(F to pay respects), I’ll leave this function as a template for now

libpince.debugcore.inject_with_dlopen_call(library_path)

Injects the given .so file to current process This is a variant of the function inject_with_advanced_injection This function won’t break the target process unlike other complex injection methods The downside is it fails if the target doesn’t support dlopen calls or simply doesn’t have the library

Parameters:

library_path (str) – Path to the .so file that’ll be injected

Returns:

Result of the injection

Return type:

bool

libpince.debugcore.interrupt_inferior(interrupt_reason=2)

Interrupt the inferior

Parameters:

interrupt_reason (int) – Just changes the global variable stop_reason. Can be a member of typedefs.STOP_REASON

libpince.debugcore.interrupt_signal = 'SIGINT'

When PINCE was first launched, it used gdb 7.7.1, which is a very outdated version of gdb interpreter-exec mi command of gdb showed some buggy behaviour at that time Because of that, PINCE couldn’t support gdb/mi commands for a while But PINCE is now updated with the new versions of gdb as much as possible and the interpreter-exec works much better So, old parts of codebase still get their required information by parsing gdb console output New parts can try to rely on gdb/mi output

libpince.debugcore.is_attached()

Checks if gdb is attached to the current process

Returns:

True if attached, False if not

Return type:

bool

libpince.debugcore.memory_handle()

Acquire the handle of the currently attached process

Returns:

A file handle that points to the memory file of the current process

Return type:

BinaryIO

libpince.debugcore.modify_breakpoint(expression, modify_what, condition=None, count=None)

Adds a condition to the breakpoint at the address evaluated by the given expression

Parameters:

• expression (str) – Any gdb expression

• modify_what (int) – Can be a member of typedefs.BREAKPOINT_MODIFY_TYPES

• CONDITION (This function modifies condition of the breakpoint if)

• ENABLE (enables the breakpoint if)

• the (disables)

• DISABLE (breakpoint if)

• ENABLE_ONCE (enables once then disables after hit if)

• then (enables for specified count)

• ENABLE_COUNT (disables after the count is reached if)

• ENABLE_DELETE (enables once then deletes the breakpoint if)

• condition (str) – Any gdb condition expression. This parameter is only used if modify_what passed as CONDITION

• count (int) – Only used if modify_what passed as ENABLE_COUNT

Returns:

True if the condition has been set successfully, False otherwise

Return type:

bool

Examples

modify_what–>typedefs.BREAKPOINT_MODIFY_TYPES.CONDITION condition–>$eax==0x523 condition–>$rax>0 && ($rbp<0 || $rsp==0) condition–>printf($r10)==3

modify_what–>typedefs.BREAKPOINT_MODIFY_TYPES.ENABLE_COUNT count–>10

libpince.debugcore.modify_instruction(start_address, array_of_bytes)

Replaces an instruction’s opcodes with a new AOB

Parameters:

• start_address (int) – Self-explanatory

• array_of_bytes (str) – String that contains the replacement bytes of the instruction

Returns:

None

libpince.debugcore.nop_instruction(start_address, length_of_instr)

Replaces an instruction’s opcodes with NOPs

Parameters:

• start_address (int) – Self-explanatory

• length_of_instr (int) – Length of the instruction that’ll be NOP’ed

Returns:

None

libpince.debugcore.parse_and_eval(expression, cast=<class 'str'>)

Calls gdb.parse_and_eval with the given expression and returns the value after casting with the given type Use examine_expression if your data can be expressed as an address or a symbol, use this function otherwise Unlike examine_expression, this function can read data that has void type or multiple type representations For instance:

• $eflags has both str and int reprs

• $_siginfo is a struct with many fields

• x64 register convenience vars such as $rax are void if the process is x86

Parameters:

• expression (str) – Any gdb expression

• cast (type) – Evaluated value will be cast to this type in gdb

Returns:

Self-explanatory None: If casting fails

Return type:

cast

libpince.debugcore.read_float_registers()

Returns the current floating point registers

Returns:

A dict that holds floating point registers. Check typedefs.REGISTERS.FLOAT for the full list

Return type:

OrderedDict[str, str]

Note

Returned xmm values are based on xmm.v4_float

libpince.debugcore.read_memory(address, value_index, length=0, zero_terminate=True, value_repr=0, endian=0, mem_handle=None)

Reads value from the given address

Parameters:

• address (str, int) – Can be a hex string or an integer.

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

• length (int) – Length of the data that’ll be read. Must be greater than 0. Only used when the value_index is

• otherwise (value_index is STRING. Ignored)

• zero_terminate (bool) – If True, data will be split when a null character has been read. Only used when

• otherwise

• value_repr (int) – Can be a member of typedefs.VALUE_REPR. Only usable with integer types

• endian (int) – Can be a member of typedefs.ENDIANNESS

• mem_handle (io.BufferedReader, None) – A file handle that points to the memory file of the current process

• optimization (This parameter is used for)

• memory_handle (See)

• manually (Don't forget to close the handle after you're done if you use this parameter)

Returns:

If the value_index is STRING or AOB, also when value_repr is HEX float: If the value_index is FLOAT32 or FLOAT64 int: If the value_index is anything else None: If an error occurs while reading the given address

Return type:

str

libpince.debugcore.read_pointer_chain(pointer_request)

Reads the addresses pointed by this pointer chain

Parameters:

pointer_request (typedefs.PointerChainRequest) – class containing a base_address and an offsets list

Returns:

Class containing every pointer dereference result while walking the chain None: If an error occurs while reading the given pointer chain

Return type:

typedefs.PointerChainResult

libpince.debugcore.read_registers()

Returns the current registers

Returns:

A dict that holds general, flag and segment registers. Check typedefs.REGISTERS for the full list

Return type:

dict

libpince.debugcore.restore_instruction(start_address)

Restores a modified instruction to it’s original opcodes

Parameters:

start_address (int) – Self-explanatory

Returns:

None

libpince.debugcore.search_functions(expression, case_sensitive=False)

Runs the gdb command “info functions” for given expression and returns the result of it

Parameters:

• expression (str) – Any gdb expression

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

Returns:

A list of str–>[(address1, symbol1), (address2, symbol2), …]

address will be None if the corresponding symbol is in defined category

Return type:

list

libpince.debugcore.search_opcode(searched_str, starting_address, ending_address_or_offset, case_sensitive=False, enable_regex=False)

Searches for the given str in the disassembled output

Parameters:

• searched_str (str) – String that will be searched

• starting_address (str) – Any gdb expression

• ending_address_or_offset (str) – If you pass this parameter as an offset, you should add “+” in front of it

• address ((e.g "+42" or "+0x42"). If you pass this parameter as an hex)

• expression (the address range between the)

• disassembled. (and the secondary address is)

• address. (If the second parameter is an address. it always should be bigger than the first)

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

• enable_regex (bool) – If True, searched_str will be treated as a regex expression

Returns:

A list of str values in this format–>[[address1,opcodes1],[address2, …], …] None: If enable_regex is True and given regex isn’t valid

Return type:

list

libpince.debugcore.search_referenced_calls(searched_str, case_sensitive=True, enable_regex=False)

Searches for given str in the referenced calls

Parameters:

• searched_str (str) – String that will be searched

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

• enable_regex (bool) – If True, searched_str will be treated as a regex expression

Returns:

[[referenced_address1, found_string1], …] None: If enable_regex is True and searched_str isn’t a valid regex expression

Return type:

list

libpince.debugcore.search_referenced_strings(searched_str, value_index=7, case_sensitive=False, enable_regex=False)

Searches for given str in the referenced strings

Parameters:

• searched_str (str) – String that will be searched

• value_index (int) – Can be a member of typedefs.VALUE_INDEX

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

• enable_regex (bool) – If True, searched_str will be treated as a regex expression

Returns:

[[referenced_address1, reference_count1, found_value1], …] None: If enable_regex is True and searched_str isn’t a valid regex expression

Return type:

list

libpince.debugcore.send_command(command, control=False, cli_output=False, send_with_file=False, file_contents_send=None, recv_with_file=False)

Issues the command sent, raises an exception if gdb isn’t initiated

Parameters:

• command (str) – The command that’ll be sent

• control (bool) – This param should be True if the command sent is ctrl+key instead of the regular command

• cli_output (bool) – If True, returns a readable cli output instead of gdb/mi output

• send_with_file (bool) – Custom commands declared in gdbextensions.py requires file communication. If

• parameters (called command has any)

• True (pass this as)

• file_contents_send (any) – Arguments for the custom gdb command called

• recv_with_file (bool) – Pass this as True if the called custom gdb command returns something

Examples

send_command(c,control=True)–> Sends ctrl+c instead of the str “c” send_command(“pince-read-addresses”, file_contents_send=nested_list, recv_file=True)–> This line calls the custom gdb command “pince-read-addresses” with parameter nested_list and since that gdb command returns the addresses read as a list, we also pass the parameter recv_file as True

Returns:

Result of the command sent, commands in the form of “ctrl+key” always returns a null string ???: If recv_with_file is True. Content of the returned thing depends on the command sent

Return type:

str

Note

TODO:This bug doesn’t seem like to exist anymore. Remove the unnecessary file communication layer of IPC File communication system is used to avoid BEL emitting bug of pexpect. If you send more than a certain amount of characters to gdb, the input will be sheared at somewhere and gdb won’t be receiving all of the input Visit this page for more information–>http://pexpect.readthedocs.io/en/stable/commonissues.html

You don’t have to write interpreter-exec while sending a gdb/mi command. Just pass the gdb/mi command as itself. This function will convert it automatically.

libpince.debugcore.set_convenience_variable(variable, value)

Sets given convenience variable to given value Can be also used for modifying registers directly

Parameters:

• variable (str) – Any gdb convenience variable(with “$” character removed)

• value (str) – Anything

libpince.debugcore.set_gdb_output_mode(output_mode_tuple)

Adjusts gdb output

Parameters:

• output_mode_tuple (typedefs.gdb_output_mode) – Setting any field True will enable the output that’s associated

• output (with that field. Setting it False will disable the associated)

libpince.debugcore.set_interrupt_signal(signal_name)

Decides on what signal to use to stop the process

Parameters:

signal_name (str) – Name of the signal

libpince.debugcore.set_logging(state)

Sets logging on or off

Parameters:

state (bool) – Sets logging on if True, off if False

libpince.debugcore.set_pince_paths()

Initializes $PINCE_PATH and $GDBINIT_AA_PATH convenience variables to make commands in gdbextensions.py and gdbutils.py work. GDB scripts need to know libpince and .config directories, unfortunately they don’t start from the place where script exists

libpince.debugcore.set_register_flag(flag, value)

Sets given register flag to given value

Parameters:

• flag (str) – A member of typedefs.REGISTERS.FLAG

• value (Union[int,str]) – 0 or 1

libpince.debugcore.state_observe_thread()

Observes the state of gdb, uses conditions to inform other functions and threads about gdb’s state Also generates output for send_command function Should be called by creating a thread. Usually called in initialization process by attach function

libpince.debugcore.step_instruction()

Step one assembly instruction

libpince.debugcore.step_over_instruction()

Step over one assembly instruction

libpince.debugcore.toggle_attach()

Detaches from the current process without ending the season if currently attached. Attaches back if detached

Returns:

The new state of the process as a member of typedefs.TOGGLE_ATTACH None: If detaching or attaching fails

Return type:

int

libpince.debugcore.track_breakpoint(*args, **kwargs)

libpince.debugcore.track_watchpoint(*args, **kwargs)

libpince.debugcore.wait_for_stop(timeout=0)

Block execution till the inferior stops

Parameters:

timeout (float) – Timeout time in seconds, passing 0 will wait for stop indefinitely

libpince.debugcore.write_memory(address, value_index, value, zero_terminate=True, endian=0)

Sets the given value to the given address

If any errors occurs while setting value to the according address, it’ll be ignored but the information about error will be printed to the terminal.

Parameters:

• address (str, int) – Can be a hex string or an integer

• value_index (int) – Can be a member of typedefs.VALUE_INDEX

• value (str, int, float, list) – The value that’ll be written to the given address

• zero_terminate (bool) – If True, appends a null byte to the value. Only used when value_index is STRING

• endian (int) – Can be a member of typedefs.ENDIANNESS

Notes

TODO: Implement a mem_handle parameter for optimization, check read_memory for an example If a file handle fails to write to an address, it becomes unusable You have to reopen the file to continue writing

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 = 7

CHANGED = 8

DECREASED = 3

DECREASED_BY = 4

EXACT = 0

INCREASED = 1

INCREASED_BY = 2

LESS = 5

MORE = 6

NOT = 11

UNCHANGED = 9

UNKNOWN = 10

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

Searches processes and returns a list of the ones that contain process_name

Parameters:

process_name (str) – Name 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