Expand description
panda-rs is a set of Rust bindings for PANDA.
The following are provided:
- Callbacks to various PANDA events in the form of attribute macros
- Callbacks for when guest syscalls happen
- Bindings to various core PANDA plugins (hooks2, osi, etc)
- Safe bindings to the core PANDA API
- An API for driving PANDA via libpanda
- Access to raw PANDA and QEMU API bindings via panda_sys
§Feature flags:
libpanda- enable libpanda mode. This is used to allow for compiling as a binary that links against libpanda, for pypanda-style use.
§Architecture-specific features
PANDA supports multiple architectures, but requires plugins to be compiled for each
architecture. In order to target a specific guest arch, use exactly one of the following:
x86_64, i386, arm, aarch64, mips, mipsel, mips64, ppc
Typically PANDA plugins forward each of these features in their Cargo.toml:
[features]
x86_64 = ["panda/x86_64"]
i386 = ["panda/i386"]
# ...§Callbacks
panda-rs makes extensive use of callbacks for handling analyses on various events. To use
callbacks, you simply apply the callback’s attribute to any functions which should be called
for the given callback. In order to use a callback in a PANDA plugin (not to be confused with
an application that uses libpanda), one function must be marked #[panda::init],
otherwise the plugin will not work in PANDA.
Callbacks come in two forms: free form functions (which use the attribute macros)
mentioned above) and closure callbacks, which use the Callback API.
§libpanda Mode
PANDA also offers a dynamic library (libpanda). panda-rs allows linking against libpanda
instead of linking as a PANDA plugin. This creates a executable that requires libpanda to run.
To compile in libpanda mode, make sure the PANDA_PATH environment variable is set to your
PANDA build folder.
§Helpful Links
Modules§
- abi
- Helpers and constants for interacting with various ABIs
- enums
- hook
- A set of functions for building hooks out of closures.
- llvm
- Functions for working with PANDA’s LLVM execution
- mem
- Utilities for working with the guest’s memory
- on_sys
- Callbacks for linux syscalls (from syscalls2)
- os
- Utilities for working with the PANDA OS API
- panda_
arg - Helpers for getting plugin arguments from panda
- plugins
- Bindings for various built-in PANDA plugins
- prelude
- A set of types PANDA frequently requires but have a low likelihood of clashing with other types you import, for use as a wildcard import.
- regs
- Functions for reading and modifying guest registers
- rr
- Functions for record and replay
- sys
- Raw bindings to the PANDA API
- syscall_
injection syscall-injection - Everything to perform async system call injection to perform system calls within the guest.
- taint
- Taint analysis API
Macros§
- cpu_
arch_ state - export_
ppp_ callback - Declare and export a plugin-to-plugin (PPP) callback, which allows other plugins to add callbacks for this plugin to run.
- plugin_
import - A macro for importing an external PANDA plugin to use
Structs§
- Callback
- A reference to a given callback slot which can be used to install, enable, disable, or otherwise reference, a closure-based callback.
- Guest
Ptr - Guest
Read Fail - Guest
Write Fail - Panda
- Builder for creating PANDA instances. Only for use in libpanda mode.
- Plugin
Handle - An opaque type used to register/unregister callbacks with PANDA. Passed into init/unit callbacks
- PppCallback
- A reference to a given callback slot which can be used to install, enable, disable, or otherwise reference, a closure-based callback for PANDA plugin-to-plugin (“PPP”) callbacks.
- Uninit
Callback - A callback set to run on plugin uninit. To add an uninit callback use
#[panda::uninit]on a function which takes an&mut PluginHandleas an argument.
Enums§
Constants§
- ARCH_
ENDIAN - The byte order of the guest architecture being targetted by PANDA
- ARCH_
NAME - The name of the architecture as used by PANDA
Traits§
- Callback
Return - A type which can be returned from a callback and folded into a single value
- Guest
Type - A type which can be converted to and from a guest memory representation, allowing
it to be used with
GuestPtr. - Init
Return - A trait representing types that can be used as the return value for a
#[panda::init]function - Panda
Args - A trait for allowing conversion to and from PANDA command line arguments. Should only be used with the provided derive macro.
Functions§
- argc
- Get count of commandline arguments
- argv
- Get commandline arguments
- current_
asid - Get current architecture independent Address-Space ID (ASID)
- current_
ksp - Get current guest kernelspace stack pointer
- current_
pc - Get current guest program counter
- current_
sp - Get current guest userspace stack pointer
- current_
sp_ masked_ pagesize - Get current guest userspace stack pointer, masking of page size MSBs
- enter_
priv - If required for the target architecture, enter into a high-privilege mode in order to conduct some memory access. Returns true if a switch into high-privilege mode has been made. A NO-OP on systems where such changes are unnecessary.
- exit_
priv - Revert the guest to the privilege mode it was in prior to the last call to enter_priv(). A NO-OP for architectures where enter_priv() is a NO-OP.
- get_
ret_ val - Get current guest function return value
- in_
kernel_ code_ linux - Determine if guest is currently executing kernel code
- in_
kernel_ mode - Determine if guest is currently executing in kernel mode
- require_
plugin - Require a plugin to be loaded, and if it isn’t loaded load it with the given arguments. If the plugin is already loaded the arguments will be discarded.
Type Aliases§
Attribute Macros§
- after_
block_ exec - (Callback) Called after execution of every basic block. If exitCode > TB_EXIT_IDX1, then the block exited early.
- after_
block_ translate - (Callback) Called after execution of every basic block. If exitCode > TB_EXIT_IDX1, then the block exited early.
- after_
cpu_ exec_ enter - (Callback) Called after cpu_exec calls cpu_exec_enter function.
- after_
insn_ exec - (Callback) Called after execution of an instruction identified by the PANDA_CB_AFTER_INSN_TRANSLATE callback
- after_
insn_ translate - (Callback) Called after the translation of each instruction.
- after_
loadvm - (Callback) Called right after a snapshot has been loaded (either with loadvm or replay initialization), but before any guest code runs.
- after_
machine_ init - (Callback) Called right after the machine has been initialized, but before any guest code runs.
- asid_
changed - (Callback) Called when asid changes.
- before_
block_ exec - (Callback) Called before execution of every basic block.
- before_
block_ exec_ invalidate_ opt - (Callback) Called before execution of every basic block, with the option to invalidate the TB.
- before_
block_ translate - (Callback) Called before translation of each basic block.
- before_
cpu_ exec_ exit - (Callback) Called before cpu_exec calls cpu_exec_exit function.
- before_
handle_ exception - (Callback) Called just before we are about to handle an exception.
- before_
handle_ interrupt - (Callback)
- before_
loadvm - (Callback) Called at start of replay, before loadvm is called. This allows us to hook devices’ loadvm handlers. Remember to unregister the existing handler for the device first. See the example in the sample plugin.
- before_
tcg_ codegen - (Callback) Callback ID: PANDA_CB_BEFORE_TCG_CODEGEN
- cpu_
restore_ state - (Callback) Called inside of cpu_restore_state(), when there is a CPU fault/exception.
- during_
machine_ init - (Callback) Called in the middle of machine initialization
- end_
block_ exec - (Callback) Callback ID: PANDA_CB_END_BLOCK_EXEC
- guest_
hypercall - (Callback) Called when a program inside the guest makes a hypercall to pass information from inside the guest to a plugin
- hd_read
- (Callback) Called when there is a hard drive read
- hd_
write - (Callback) Called when there is a hard drive write
- hook
- An attribute to declare a function for hooking using the PANDA ‘hooks’ plugin, enabling the ability to add callbacks for when a specifc instruction is hit, with control over the address space, kernel mode, and callback type to use.
- init
- (Required Callback) Called when the plugin is being uninitialized
- insn_
exec - (Callback) Called before execution of any instruction identified by the PANDA_CB_INSN_TRANSLATE callback.
- insn_
translate - (Callback) Called before the translation of each instruction.
- main_
loop_ wait - (Callback) Called in IO thread in place where monitor cmds are processed
- mmio_
after_ read - (Callback) Called after MMIO memory is read.
- mmio_
before_ write - (Callback) Called after MMIO memory is written to.
- monitor
- (Callback) Called when someone uses the plugin_cmd monitor command.
- on_
all_ sys_ enter - Callback that runs when any syscall is entered
- on_
all_ sys_ return - Callback that runs when any syscall returns.
- on_
mmap_ updated - (Callback)
- on_
process_ end - (Callback)
- on_
process_ start - (Callback)
- on_
rec_ auxv - (Callback) Runs when proc_start_linux recieves the
AuxvValuesfor a given process. - on_
thread_ end - (Callback)
- on_
thread_ start - (Callback)
- phys_
mem_ after_ read - (Callback) Called after memory is read.
- phys_
mem_ after_ write - (Callback) Called after memory is written.
- phys_
mem_ before_ read - (Callback) Called after memory is read.
- phys_
mem_ before_ write - (Callback) Called before memory is written.
- pre_
shutdown - (Callback) Called just before qemu shuts down
- replay_
after_ dma - (Callback) In replay only, we are about to dma between qemu buffer and guest memory
- replay_
before_ dma - (Callback) In replay only. We are about to dma between qemu buffer and guest memory.
- replay_
handle_ packet - (Callback) In replay only, we have a packet (incoming / outgoing) in hand.
- replay_
hd_ transfer - (Callback) In replay only. Some kind of data transfer involving hard drive.
- replay_
net_ transfer - (Callback) In replay only, some kind of data transfer within the network card (currently, only the E1000 is supported).
- replay_
serial_ read - (Callback) In replay only, called when a byte read from the serial RX FIFO
- replay_
serial_ receive - (Callback) In replay only, called when a byte is received on the serial port.
- replay_
serial_ send - (Callback) In replay only, called when a byte is sent on the serial port.
- replay_
serial_ write - (Callback) In replay only, called when a byte written to the serial TX FIFO
- start_
block_ exec - (Callback) Callback ID: PANDA_CB_START_BLOCK_EXEC
- top_
loop - (Callback) Called at the top of the loop that manages emulation.
- unassigned_
io_ read - (Callback) Called when the guest attempts to read from an unmapped peripheral via MMIO
- unassigned_
io_ write - (Callback) Called when the guest attempts to write to an unmapped peripheral via MMIO
- uninit
- (Callback) Called when the plugin is being uninitialized
- virt_
mem_ after_ read - (Callback) Called after memory is read.
- virt_
mem_ after_ write - (Callback) Called after memory is written.
- virt_
mem_ before_ read - (Callback) Called before memory is read.
- virt_
mem_ before_ write - (Callback) Called before memory is written.