Crate panda

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

Important	Popular Callbacks	Popular Plugins
init	before_block_exec	osi
Panda	virt_mem_after_read	proc_start_linux
hook	virt_mem_after_write	hooks2
on_sys	asid_changed	guest_plugin_manager
uninit	before_block_exec_invalidate_opt
regs	insn_translate
PandaArgs	insn_exec

Re-exports

• pub use closure::set_plugin_ref;
• pub use ppp_closures::InternalPppClosureCallback;
• pub use ppp_closures::__internal_install_ppp_closure_callback;

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_injectionsyscall-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.
• GuestPtr
• GuestReadFail
• GuestWriteFail
• Panda
  Builder for creating PANDA instances. Only for use in libpanda mode.
• PluginHandle
  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.
• UninitCallback
  A callback set to run on plugin uninit. To add an uninit callback use #[panda::uninit] on a function which takes an &mut PluginHandle as an argument.

Enums

• Arch
  Architecture of the guest system
• Error
• RrError

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

• CallbackReturn
  A type which can be returned from a callback and folded into a single value
• GuestType
  A type which can be converted to and from a guest memory representation, allowing it to be used with GuestPtr.
• InitReturn
  A trait representing types that can be used as the return value for a #[panda::init] function
• PandaArgs
  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

• CPUArchPtr

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 AuxvValues for 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.

Derive Macros

• GuestType