Struct haybale::function_hooks::FunctionHooks

pub struct FunctionHooks<'p, B: Backend + 'p> { /* private fields */ }

A set of function hooks, which will be executed instead of their respective hooked functions if/when the symbolic execution engine encounters a call to one of those hooked functions.

You can hook internal functions (which are defined in some available LLVM Module), external functions (e.g., calls to external libraries), LLVM intrinsics, or any other kind of function.

The function resolution process is as follows:

(1) If the function is hooked, then the hook will be used instead of any other option. That is, the hook has the highest precedence.

(2) Haybale provides default hooks for certain LLVM intrinsics like memcpy, which have specially reserved names; it will apply these hooks unless a different hook was defined for the intrinsic in (1).

(3) Else, if the function is not hooked but is defined in an available LLVM Module, the function will be symbolically executed (called).

(4) Else, if a default function hook was supplied with add_default_hook(), that hook will be used.

(5) If none of the above options apply, an error will be raised. Note that this means that calls to external functions will always error unless a hook for them is provided, either by name or via the default hook.

Implementations

impl<'p, B: Backend + 'p> FunctionHooks<'p, B>

pub fn new() -> Self

Create a blank FunctionHooks instance with no function hooks.

You may want to consider FunctionHooks::default(), which provides predefined hooks for common functions.

pub fn add<H>(&mut self, hooked_function: impl Into<String>, hook: &'p H)where H: Fn(&mut State<'p, B>, &'p dyn IsCall) -> Result<ReturnValue<B::BV>>,

Adds a function hook. The hook will be executed instead of the body of the hooked_function.

pub fn add_cpp_demangled<H>( &mut self, hooked_function: impl Into<String>, hook: &'p H )where H: Fn(&mut State<'p, B>, &'p dyn IsCall) -> Result<ReturnValue<B::BV>>,

Exactly like add(), but takes the (C++) demangled name of the function to hook, so you can use a function name like “namespace::function”.

pub fn add_rust_demangled<H>( &mut self, hooked_function: impl Into<String>, hook: &'p H )where H: Fn(&mut State<'p, B>, &'p dyn IsCall) -> Result<ReturnValue<B::BV>>,

Exactly like add(), but takes the (Rust) demangled name of the function to hook, so you can use a function name like “module::function”.

pub fn add_inline_asm_hook<H>(&mut self, hook: &'p H) -> boolwhere H: Fn(&mut State<'p, B>, &'p dyn IsCall) -> Result<ReturnValue<B::BV>>,

Add a hook to be used for calls to inline assembly. This one hook will handle all calls to any inline assembly, regardless of the contents; it is responsible for inspecting the contents and acting appropriately. If another inline assembly hook is added, it will replace any inline assembly hook which was previously present.

Returns true if an inline assembly hook was previously present, or false if no inline assembly hook was present.

Note that as of this writing, due to a limitation of the LLVM C API (see the ‘Limitations’ section of the llvm-ir README), the hook will actually have no way of obtaining the contents of the asm string itself, although it can still inspect function parameters etc. For now, this is the best we can do.

pub fn add_default_hook<H>(&mut self, hook: &'p H) -> boolwhere H: Fn(&mut State<'p, B>, &'p dyn IsCall) -> Result<ReturnValue<B::BV>>,

Add a hook to be used if no other definition or hook is found for the call. If another default hook is added, it will replace any default hook which was previously present.

Returns true if a default hook was previously present, or false if no default hook was present.

pub fn remove(&mut self, hooked_function: &str)

Removes the function hook for the given function, which was added with add(). That function will no longer be hooked.

pub fn remove_cpp_demangled(&mut self, hooked_function: &str)

Removes the function hook for the given function, which was added with add_cpp_demangled(). That function will no longer be hooked.

pub fn remove_rust_demangled(&mut self, hooked_function: &str)

Removes the function hook for the given function, which was added with add_rust_demangled(). That function will no longer be hooked.

pub fn remove_inline_asm_hook(&mut self)

Removes the function hook used for calls to inline assembly, which was added with add_inline_asm_hook(). Calls to inline assembly will no longer be hooked, and thus will result in errors, until the next call to add_inline_asm_hook().

pub fn remove_default_hook(&mut self)

Removes the default function hook which was added with add_default_hook(). Calls to functions which are neither defined in the Project nor specifically hooked will thus result in Error::FunctionNotFound errors, until the next call to add_default_hook().

pub fn is_hooked(&self, funcname: &str) -> bool

Determine whether there is an active hook for the given funcname

pub fn has_inline_asm_hook(&self) -> bool

Is there currently an inline asm hook active? (See add_inline_asm_hook() for more info)

pub fn has_default_hook(&self) -> bool

Is there currently a default hook active? (See add_default_hook() for more info)

Trait Implementations

impl<'p, B: Clone + Backend + 'p> Clone for FunctionHooks<'p, B>

fn clone(&self) -> FunctionHooks<'p, B>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'p, B: Backend + 'p> Default for FunctionHooks<'p, B>

fn default() -> Self

Provides predefined hooks for common functions. (At the time of this writing, this includes malloc-related functions malloc(), calloc(), realloc(), and free(), as well as some C++ exception-handling functions such as __cxa_throw() and __cxa_allocate_exception(), and a few other C and Rust standard library functions.)

If you don’t want these hooks, you can use FunctionHooks::remove_function_hook() to remove individual hooks, or you can use FunctionHooks::new(), which comes with no predefined hooks.