> ## Documentation Index
> Fetch the complete documentation index at: https://vulhunt-docs.binarly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](/vulhunt-reference/types/ir-term)                                                                                                   |
| `lookup_type`      | Returns the type definition for the given name                                                   | `string`                                                                                                                                | [`IRTerm`](/vulhunt-reference/types/ir-term)                                                                                                   |
| `register_name`    | Returns the register name for a variable term                                                    | [`IRTerm`](/vulhunt-reference/types/ir-term)                                                                                            | `string`                                                                                                                                       |
| `resolve_type`     | Expands a type term, resolving aliases                                                           | [`IRTerm`](/vulhunt-reference/types/ir-term)                                                                                            | [`IRTerm`](/vulhunt-reference/types/ir-term)                                                                                                   |
| `decompile`        | Decompiles one or more functions                                                                 | `string`, [`AddressValue`](/vulhunt-reference/types/address-value), or [`FunctionQuery`](/vulhunt-reference/types/function-query)       | [`DecompiledFunction`](/vulhunt-reference/types/decompiled-function) or [`DecompiledFunction[]`](/vulhunt-reference/types/decompiled-function) |
| `functions`        | Returns one or more functions                                                                    | `string`, [`AddressValue`](/vulhunt-reference/types/address-value), [`FunctionQuery`](/vulhunt-reference/types/function-query), or none | [`FunctionContext`](/vulhunt-reference/types/function-context) or [`FunctionContext[]`](/vulhunt-reference/types/function-context)             |
| `functions_where`  | Returns a table of functions matching the given predicate function                               | `fun(context: FunctionContext)`                                                                                                         | [`FunctionContext[]`](/vulhunt-reference/types/function-context)                                                                               |
| `calls_matching`   | Returns the table of calls matching the predicates                                               | [`CallsMatchingParam`](/vulhunt-reference/types/calls-matching-param)                                                                   | [`CallsMatchingTable[]`](/vulhunt-reference/types/calls-matching-table)                                                                        |
| `callees_matching` | Returns the table of function callees matching the predicates                                    | [`CalleesMatchingParam`](/vulhunt-reference/types/callees-matching-param)                                                               | [`CalleesMatchingTable[]`](/vulhunt-reference/types/callees-matching-table)                                                                    |
| `callee_at`        | Returns the callee details at the given call site                                                | [`CalleeAtParam`](/vulhunt-reference/types/callee-at-param)                                                                             | [`CalleeAtTable`](/vulhunt-reference/types/callee-at-table) or `nil`                                                                           |
| `search_bytes`     | Returns true if the set of bytes is found in the binary, false otherwise                         | `string`                                                                                                                                | `boolean`                                                                                                                                      |
| `find_bytes`       | Returns the addresses of every occurrence of the set of bytes found in the binary                | `string`                                                                                                                                | [`AddressValue[]`](/vulhunt-reference/types/address-value)                                                                                     |
| `search_string`    | Returns true if the string is found in the binary, false otherwise                               | \[`string`, `string` (Kind)]                                                                                                            | `boolean`                                                                                                                                      |
| `find_string`      | Returns the addresses of every occurrence of the string found in the binary                      | \[`string`, `string` (Kind)]                                                                                                            | [`AddressValue[]`](/vulhunt-reference/types/address-value)                                                                                     |
| `search_code`      | Returns a [`SearchCodeResult`](/vulhunt-reference/types/search-code-result) if the code is found | \[`string`, `string` (Location)]                                                                                                        | [`SearchCodeResult`](/vulhunt-reference/types/search-code-result)                                                                              |
| `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`](/vulhunt-reference/types/ir-term) 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`](/vulhunt-reference/types/address-value) (function address), or [`FunctionQuery`](/vulhunt-reference/types/function-query) object.
Returns [`DecompiledFunction`](/vulhunt-reference/types/decompiled-function) or [`DecompiledFunction[]`](/vulhunt-reference/types/decompiled-function) when using [`FunctionQuery`](/vulhunt-reference/types/function-query) with `all=true`.

<Note>
  `decompile` requires enabling the decompiler feature via the extension API.
</Note>

#### functions

Returns one or more functions based on a string (function name), [`AddressValue`](/vulhunt-reference/types/address-value) (function address), [`FunctionQuery`](/vulhunt-reference/types/function-query) object, or no input to return all functions.
Returns [`FunctionContext`](/vulhunt-reference/types/function-context) or [`FunctionContext[]`](/vulhunt-reference/types/function-context) when using [`FunctionQuery`](/vulhunt-reference/types/function-query) with `all=true`.

#### functions\_where

Returns [`FunctionContext[]`](/vulhunt-reference/types/function-context) based on the Lua function given as predicate.

#### calls\_matching

Returns a table of calls matching the provided predicates.

#### callees\_matching

Returns a table of function callees matching the provided predicates.

#### callee\_at

Returns the details of the callee invoked at a specific call site address.

<Note>
  The target address does not need to point exactly at the call instruction: the call site is resolved from the basic block that contains the specified address.
</Note>

#### search\_bytes

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

#### find\_bytes

Returns a table of addresses where the specified byte sequence is located in the binary. Takes a hex pattern string as argument.

<Note>
  This method returns overlapping matches. For example, if the binary contains the byte sequence `41 41 41 41` at offset 0x0,

  ```lua theme={null}
    project:find_bytes("4141")
  ```

  returns three matches, at addresses `0x0`, `0x1`, and `0x2`.

  It is recommended to make the search pattern as unique as possible.
</Note>

#### 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`

#### find\_string

Returns a table of addresses where the specified string is located in the binary. 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`

<Note>
  This method returns overlapping matches. For example, if the binary contains the string `AAAA` at offset 0x0,

  ```lua theme={null}
    project:find_string("AA")
  ```

  returns three matches, at addresses `0x0`, `0x1`, and `0x2`.

  It is recommended to make the search pattern as unique as possible.
</Note>

#### search\_code

Returns a [`SearchCodeResult`](/vulhunt-reference/types/search-code-result) 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

```lua theme={null}
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`:

```lua theme={null}
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
}
```