API Reference

API Reference

1. AnalysisModule()
2. Vendor()
3. Reproducer()
4. VM()

Plugin

class AnalysisModule()

• name

  name is the string of plugin name

• analyzor

  analyzor is the instance of current plugin

• init(self, manager)

  init() passes manager to the plugin. The manager contains all necessary info of the current case, including case hash, config, logger, case path and etc. init() is called automatically by the deployer whenever a plugin is loaded.

• setup(self)

  setup() sets the plugin path and creates the plugin work folder in the case directory. It also prepares the plugin logger.

• install_analyzor(self, analyzor)

  install_analyzor() installs the next plugin. It's automatically called by the deployer.

• run(self)

  run() eventually executes the plugin's run() function. Once the plugin has finished running, it dumps the results to the plugin folder, and procceed the cleanup process.

• prepare(self)

  prepare() checks whether the dependencies has met. If it does, procceed the prepare() of the plugin.

• generate_report(self)

  generate_report() generates the plugin report in the plugin folder.

• success(self)

  success() calls the plugin's success().

• create_stamp(self)

  create_stamp() generates the finish stamp for the plugin.

• check_stamp(self)

  check_stamp() checks whether the plugin has a finish stamp

• null_results(self)

  null_results() resets the finish and results of the plugin

• plugin_finished(self, plugin_name)

  plugin_finished() returns whether a plugin has finished successfully.

• plugin_capable(self, plugin_name)

  plugin_capable() returns whether a plugin is enabled.

• cleanup(self)

  pass

• dump_results(self)

  dump_results() generates a results.json in the plugin folder.

• build_mainline_kernel(self, commit=None, config=None, image=None, gcc_version=None, kernel=None, patch="", keep_ori_config=False, extra_cmd="", kernel_repo="", branch="")

  build_mainline_kernel() controls the building process of a upstream kernel. commit specifies the git commit of the kernel source. If commit is None, it uses the case kernel commit. config links to a url of a kernel config that is used for compilation. If config is None, it uses the case kernel config. image specfies the image name, e.g., stretch. gcc_version is decided by case report date unless if it's None. kernel can be upstream, net, linux-next and etc. It will be set by the case if it's not specified. patch points to a path of a kernel patch, it will be apply to the source code if it's a valid patch. If keep_ori_config is True, the kernel config will not be changed. extra_cmd will be executed before compiling the kernel. kernel_repo is a url to a Linux kernel repo if it's need to be specified. branch indicates a particular branch of Linux kernel source code.

• err_msg(self, msg)

  err_msg() logs an error message.

• info_msg(self, msg)

  info_msg() logs a info message

• debug_msg(self, msg)

  debug_msg logs a debug message

Vendor

class Vendor()

• repro

  repro is a Reproducer() class for each vendor kernel.

• root_user

  root_user specifies the root user.

• normal_user

  normal_user specifies the normal user.

• type

  type indicates three types: distro, upstream, and android.

• distro_image

  distro_image is an absolute path of the distro image.

• vmlinux

  vmlinux is an absolute path of the vmlinux.

• ssh_key

  ssh_key is an absolute path of ssh private key

• ssh_port

  ssh_port indicates the ssh port

• gdb_port

  gdb_port indicates the gdb port

• mon_port

  mon_port indicates the QEMU monitor port

• distro_src

  distro_src is an absolute path of the distro source code folder

• distro_code_name

  distro_code_name indicates the distro code name (e.g., Ubuntu has focal, bionic

• distro_version

  distro_version indicates the kernel version of the distro kernel

• effective_cycle_start

  effective_cycle_start is the date that the vendor kernel releases

• effective_cycle_end

  effective_cycle_end is the date that the vendor kernel ends the support

• include

  include is a list of keywords, and SyzBridge only captures the crash that contains one of those keywords

• exclude

  exclude is a list of keywords, and SyzBridge discards the crash that contains one of those keywords

Reproducer

class Reproducer()

• ssh_port

  ssh_port specifies the ssh port of the reproducer VM

• mon_port

  mon_port specifies the qemu monitor port of the reproducer VM

• gdb_port

  gdb_port specifies the gdb port of the reproducer VM

• prepare(self)

  prepare() creates an image snapshot of the testing distro.

• create_snapshot(self, src, img_dir, image_name, target_format="qcow2")

  create_snapshot() creates an image snapshot of the testing distro. src specifies the testing distro image. img_dir is the path of the directory that keep the snapshot image. image_name indicates the snapshot image name. target_format indicates the format of the snapshot image. It needs to be set to raw when creating snapshot of bullseye and android image.

• save_crash_log(self, log_msg, name)

  save_crash_log() save the content of log_msg to {self.path_case}/crash_log-{name}

• need_repro(self)

  need_repro() checks whether a case need to reproduce on the testing distro. A case will not reproduce when SyzBridge decides this bug doesn't affect the testing distro or the patch already exist in the testing distro kernel.

• reproduce(self, func, func_args, work_dir, timeout, vm_tag="reproducer", root=True, attempt=3, **kwargs)

  reproduce() is the main function for bug reproducing. It invokes launch_qemu() to boot up the kernel and wait for the callback function func to execute. func_args pass the arguments to func. work_dir specifies the folder that store the QEMU log and launch script. timeout indicates the maximum time for running the QEMU. vm_tag is used as a identifier for QEMU log. PoC will run as root user if root is True. attempt indicates how many times that SyzBridge tries to reproduce the bug if it fails. **kwargs contains arguments for VM class, they can be specified as well.

• launch_qemu(self, c_hash=0, log_suffix="", log_name=None, timeout=None, enable_gdb=False, enable_qemu_mon=False, gdb_port=None, mon_port=None, ssh_port=None, **kwargs)

  launch_qemu() returns a VM class. c_hash represents that hash value of the bug, it usually comes with the bug from syzbot. log_suffix append to the log file for better identification. log_name specifies the name of the log file. timeout indicates the maximum time for running the QEMU. enable_gdb controls whether open the gdb port. enable_qemu_mon controls whether open the QEMU monitor port. gdb_port or mon_port will be ignored they are not enabled. ssh_port specifies the ssh port, it will be automatically set an unused port if it's not specified. **kwargs contains arguments for VM class, they can be specified as well.

• run_qemu(self, qemu, func, *args)

  run_qemu() boots up the QEMU and invoke the callback function func. *args is the arguments of func

VM

class VM()

• __init__(self, linux :str, kernel :Vendor(), port, image, hash_tag, key, vmlinux=None, tag='', arch='amd64', work_path='/tmp/', mem="4G", cpu="2", gdb_port=-1, mon_port=-1, timeout=None, debug=False, logger=None, log_name='vm.log', log_suffix="", snapshot=True)

  linux is the path to the upstream Linux directory. (Only for upstream) kernel is the Vendor() class initiated from SyzBridge config. port indicates the ssh port. image is the path of the kernel image. hash_tag indicates the case hahs from syzbot. key is the path of the ssh key. vmlinux is the path of vmlinux (Only for upstream). tag is used for better identification. arch indicates the architecture of the kernel. work_path stores logs and launch scripts of QEMU. mem indicates the how many memory is used by the VM. cpu indicates how many cpu cores are used by the VM. gdb_port indicates the gdb port. mon_port indicates the QEMU monitor port. timeout is maximum running time of the QEMU. debug enables the debug mode. logger specifies the logger instance. log_name indicates the name of the log file. log_suffix add additional suffix to the log file name. snapshot indicates whether using snapshot for booting the image.

• reset(self)

  reset() resets QEMU instance by empty multiple VM() flag, including qemu_ready, kill_qemu, trigger_crash, and etc.

• run(self, alternative_func=None, alternative_func_output=None, args=())

  run() boots up the kernel in QEMU and prepares monitor, logger, and timer for the VM() instance. alternative_func specifies the callback function that will be called after booting up. alternative_func_output is a Queue that all the output writes to. args contains the arguments of the alternative_func.

• wait(self)

  wait() function waits until the alternative_func exits. It blocks the process.

• shutdown(self)

  shutdown runs the command shutdown -h now to shutdown the VM() instance.

• kill_vm(self)

  kill_vm force the the VM() instance exits by killing all the related processes.

• upload(self, user, src: list, dst, wait: bool)

  upload relies on scp to tansfer file to QEMU. user indicates the scp user. src is a list of files on the local machine that are ready to upload. dst is the path in the virtual machine. wait determines whether block the process.

• download(self, user, src: list, dst, wait: bool)

  download uses scp to transfer file from the QEMU to local machine. user indicates the scp user. src is a list of files on the virtual machine that are ready to upload. dst is the path in the local machine. wait determines whether block the process.

• command(self, cmds, user, wait: bool, timeout=None)

  command uses ssh to execute command in the virtual machine. cmds is the command. user indicates the ssh user. wait determines whether block the process. timeout indicates the timeout for the ssh.

• is_qemu_ready(self)

  is_qemu_ready() determines the status of the QEMU by checking the ssh connect.