syzqemuctl

A command-line tool and Python API for managing QEMU disk images and virtual machines created through Syzkaller's `create-image.sh`.

Documentation

• Official documentation
• 简体中文文档
• Getting started
• CLI reference
• Python API reference
• Agent Skill guide

The repository also ships a portable syzqemuctl Agent Skill for Codex, Claude Code, OpenCode, and other Agent Skills-compatible tools under skills/syzqemuctl.

Features

• Easy VM creation and management
• Automated template image creation using syzkaller's create-image.sh
• Selectable Debian image distributions with Trixie as the new-install default
• SSH and file transfer support
• Command execution in VMs
• Guest-side syzkaller temporary artifact cleanup
• Screen session management for VM console access

See details in Usage section :)

Change Log

Each version without BUG tag is usable.

Installation

pip install syzqemuctl

Requirements

python3.8+ qemu screen ssh  

Configuration

The configuration file is stored in ~/.config/syzqemuctl/settings.json. It contains:

• Images home directory path
• Default VM settings

Concepts

• Image: A QEMU disk image created by create-image.sh. New images use disk.img; v0.3.x Bullseye images retain bullseye.img. Images are stored as directories under IMAGES_HOME.
• VM: A running QEMU virtual machine booted from an image with a specified kernel. A VM shares the same name as its underlying image directory.

Usage

⭐ As a command-line tool (CLI)

You can check the usage of syzqemuctl or syzqemuctl CMD by adding --help. Here are some common uses:

1. Initialize syzqemuctl:

syzqemuctl init --images-home /path/to/images

New image homes default to Debian Trixie. Select another release explicitly for historical-kernel compatibility:

syzqemuctl init --images-home /path/to/images \
  --distribution bullseye --wait

2. Create a new disk image:

syzqemuctl create my-image [--size 3072] [--distribution bullseye]

Omitting --distribution inherits the initialized default template. New caches are separated by distribution and size.

3. Run a VM from the image:

syzqemuctl run my-image --kernel /path/to/kernel

Run with snapshot mode (all disk changes discarded on shutdown):

syzqemuctl run my-image --kernel /path/to/kernel --snapshot

Append case-specific arguments to the saved command line, or to the default command line on first boot:

syzqemuctl run my-image --kernel /path/to/kernel \
  --extra-kernel-args "systemd.unified_cgroup_hierarchy=0"

Use --kernel-args "..." instead to replace the complete guest kernel command line. Explicit kernel arguments are stored in boot.sh and reused by later starts unless new arguments are supplied.

4. Check image/VM status:

syzqemuctl status my-image

5. Copy files/dir to/from VM:

syzqemuctl cp --timeout 600 local_file my-image:/remote/path  # Copy to VM
syzqemuctl cp --timeout 600 my-image:/remote/file local_path  # Copy from VM

syzqemuctl cp local_dir my-image:/remote/       # Copy local_dir to VM
syzqemuctl cp local_dir/ my-image:/remote/      # Copy local_dir/* to VM

6. Execute commands in VM:

syzqemuctl exec --timeout 30 my-image "uname -a" # You'd better wrap the command with double quotes

7. Remove common temporary artifacts left by an earlier syzkaller reproducer:

syzqemuctl cleanup-guest my-image --timeout 20

This command requires a running, SSH-ready VM. It does not stop the VM or clean host-side runtime resources.

8. Stop the VM:

syzqemuctl stop my-image
syzqemuctl stop my-image --wait --force --timeout 20

9. Restart the VM:

syzqemuctl restart my-image

10. Diagnose VM runtime resources without changing them:

syzqemuctl diagnose my-image
syzqemuctl diagnose my-image --timeout 5 --json

11. List all images:

syzqemuctl list

12. Delete the image:

syzqemuctl delete my-image

A running image must be stopped before it can be deleted.

⭐ As a Python package (API)

from syzqemuctl import global_conf, ImageManager, VM

images_home = "/path/to/images_home"
# API defaults to quiet (verbose=False); pass verbose=True to see informational prints
global_conf.initialize(images_home, force=False)
manager = ImageManager(images_home)
manager.initialize(force=False, distribution="trixie")
manager.create("my-image")

# Select an older userspace for a historical kernel when needed:
# manager.create("old-image", distribution="bullseye", size=4096)

# Or just direct specify a created image and run a VM from it
# Use verbose=True if you want to see boot script and screen session tips
vm = VM("/path/to/images_home/my-image")
vm.start(
    kernel="/path/to/kernel",
    extra_kernel_args="systemd.unified_cgroup_hierarchy=0",
)

# Use kernel_args="..." to replace the complete guest kernel command line.
# start() cleans stale runtime belonging to this image before launching QEMU.

# Wait several minutes for the VM to be ready, or you can check by:
if vm.is_ready():
    pass

# Or use this API to wait:
if vm.wait_until_ready(timeout=180):
    pass

# You need to use this context manager to auto-connect/disconnect
with vm:
    # Run after the previous workload has stopped and before uploading a new PoC.
    vm.cleanup_guest_artifacts(timeout=20)
    vm.copy_to_vm("/path/to/local/file", "/path/to/vm/remote/file", timeout=600)
    stdout, stderr = vm.execute("uname -a", timeout=30)
    print(f"stdout: {stdout}\nstderr: {stderr}")

# timeout is optional and defaults to None.
# It limits the total duration of a single execute/copy operation.
# After a timeout, reconnect before issuing the next SSH/SCP request.

# Use wait=True and force=True when you need runtime cleanup to fully converge.
vm.stop(wait=True, force=True, timeout=20)
vm.cleanup_runtime(timeout=20)

# force=True is useful after a failed start.
# wait=True is useful before reusing an image.

# Collect a read-only runtime snapshot after start or cleanup failures.
diagnostics = vm.runtime_diagnostics(timeout=5, check_port=True)
print(diagnostics.summary())
record = diagnostics.to_dict()  # JSON/CSV-friendly structured fields

License

Apache-2.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.