ProjectHandle

The ProjectHandle object provides access to several project-level methods in VulHunt rules. It allows to enumerate functions, search for patterns, decompile code, and more.

Fields

Field	Type	Description
architecture	string	Architecture of the analyzed binary

Methods

Method	Description	Parameters	Return Type
size_of	Returns the size of the given type	string	number
lookup_prototype	Returns the function prototype for the given name	string	IRTerm
lookup_type	Returns the type definition for the given name	string	IRTerm
register_name	Returns the register name for a variable term	IRTerm	string
resolve_type	Expands a type term, resolving aliases	IRTerm	IRTerm
decompile	Decompiles one or more functions	string, AddressValue, or FunctionQuery	DecompiledFunction or DecompiledFunction[]
functions	Returns one or more functions	string, AddressValue, FunctionQuery, or none	FunctionContext or FunctionContext[]
functions_where	Returns a table of functions matching the given predicate function	fun(context: FunctionContext)	FunctionContext[]
calls_matching	Returns the table of calls matching the predicates	CallsMatchingParam	CallsMatchingTable[]
search_bytes	Returns true if the set of bytes is found in the binary, false otherwise	string	boolean
search_string	Returns true if the string is found in the binary, false otherwise	[string, string (Kind)]	boolean
search_code	Returns a SearchCodeResult if the code is found	[string, string (Location)]	SearchCodeResult
search_guid	Returns true if the GUID is found, false otherwise	[string (UUID), string (Name)]	boolean
search_nvram	Returns true if the NVRAM variable is found, false otherwise	[string (Service), string (Name), string (UUID)]	boolean
search_ppi	Returns true if the PPI is found, false otherwise	[string (Service), string (Name), string (UUID)]	boolean
search_protocol	Returns true if the Protocol is found, false otherwise	[string (Service), string (Name), string (UUID)]	boolean

Reference

architecture

The architecture field contains the architecture of the analyzed binary in the triplet format (e.g., "AARCH64:LE:64", "X86:LE:64").

size_of

Returns the size in bytes of the given type name.

lookup_prototype

Looks up a function prototype by name in the type database.

lookup_type

Looks up a type by name in the type database.

register_name

Returns the architecture register name for a variable that refers to a register. Accepts an IRTerm with kind VAR. Returns nil if the variable is not a register.

resolve_type

Expands a type term by resolving aliases and typedefs.

decompile

Decompiles one or more functions based on a string (function name), AddressValue (function address), or FunctionQuery object. Returns DecompiledFunction or DecompiledFunction[] when using FunctionQuery with all=true.

decompile requires enabling the decompiler feature via the extension API.

functions

Returns one or more functions based on a string (function name), AddressValue (function address), FunctionQuery object, or no input to return all functions. Returns FunctionContext or FunctionContext[] when using FunctionQuery with all=true.

functions_where

Returns FunctionContext[] based on the Lua function given as predicate.

calls_matching

Returns a table of calls matching the provided predicates.

search_bytes

Returns true if the specified byte sequence is found in the binary, false otherwise. Takes a hex pattern string as argument.

search_string

Returns true if the specified string is found in the binary, false otherwise. Takes a string value and an optional encoding kind as arguments. The kind parameter specifies the string encoding, valid values are:

• ascii
• utf8
• utf16
• utf16-le
• utf16le
• utf16-be
• utf16be

search_code

Returns a SearchCodeResult if the specified code is found in the binary. Takes a hex pattern string and an optional location string as arguments. The loc parameter is only available on UEFI platforms; valid values are:

• sw_smi_handlers
• child_sw_smi_handlers

search_guid

Returns true if the binary references the specified GUID, false otherwise. Takes the GUID and its symbolic name as arguments. (UEFI only)

search_nvram

Returns true if the binary accesses the specified NVRAM variable, false otherwise. Takes the runtime service used to access it (e.g., GetVariable, SetVariable), the variable name, and the vendor GUID as arguments. (UEFI only)

search_ppi

Returns true if the binary uses the specified PPI (PEIM-to-PEIM Interface), false otherwise. Takes the PEI service used to locate it (e.g., LocatePpi), the PPI name, and its GUID as arguments. (UEFI only)

search_protocol

Returns true if the binary uses the specified UEFI protocol, false otherwise. Takes the boot service used to locate it (e.g., LocateProtocol, HandleProtocol), the protocol name, and its GUID as arguments. (UEFI only)

Example

scopes = scope:project{
  with = function(project)
    -- Get a single function by name
    local func = project:functions("main")
    if func then
      print("Function:", func.name, "at address", func.address)
    end

    -- Get all functions matching a pattern
    local ssh_funcs = project:functions({matching = "^ssh_", kind = "symbol", all = true})
    for _, func in ipairs(ssh_funcs) do
      print("Function:", func.name)
    end

    -- Search for a specific string in the binary
    if project:search_string("vulnerable", "ascii") then
      print("The string 'vulnerable' was found in the binary.")
    end

    -- Decompile a function by name (requires decompiler extension)
    local decompiled = project:decompile("main")
    if decompiled then
      print("Decompiled pseudocode for 'main':\n", decompiled)
    end

    -- Decompile by address
    local decompiled = project:decompile(AddressValue.new(0x401000))

    -- Decompile all functions matching a byte pattern
    local decompiled = project:decompile({
      matching = "415455534881EC2004000064488B04",
      kind = "bytes",
      all = true
    })

    -- Filter functions with a predicate
    local function has_malloc_call(f)
      return f:has_call("malloc")
    end
    local filtered = project:functions_where(has_malloc_call)
  end
}

The following example shows UEFI-specific search methods available on the ProjectHandle:

scopes = scope:project{
  with = function(project)
    -- Search for a protocol GUID
    if project:search_guid("5B1B31A1-9562-11D2-8E3F-00A0C969723B", "EFI_LOADED_IMAGE_PROTOCOL_GUID") then
      print("EFI_LOADED_IMAGE_PROTOCOL_GUID found")
    end

    -- Search for an NVRAM variable
    if project:search_nvram("GetVariable", "PlatformLang", "8BE4DF61-93CA-11D2-AA0D-00E098032B8C") then
      print("PlatformLang NVRAM variable found")
    end

    -- Search for a protocol
    if project:search_protocol("LocateProtocol", "PCD_PROTOCOL_GUID", "11B34006-D85B-4D0A-A290-D5A571310EF7") then
      print("PCD_PROTOCOL_GUID found")
    end
  end
}