PPatch Partner

PPatch Partner is a research automation toolkit for Linux kernel patch experiments. It connects patch application, per-POC kernel builds, QEMU crash checks, and optional syzkaller reproduction into a single Python command-line workflow.

Full setup, command reference, workspace layout, Docker notes, and troubleshooting live in docs/USAGE.md.

Features

• Initialize a Linux kernel source tree at a configured stable tag.
• Apply patches/*.patch with GNU patch, ppatch auto, or both.
• Create commits and tags for successfully applied patches.
• Prepare per-POC overlayfs work directories and kernel configs.
• Build kernels and collect compiler diagnostics.
• Retry failed builds with compiler JSON diagnostics.
• Run QEMU VM crash checks for POCs.
• Optionally run syzkaller reproduction and corpus workflows.

What Is In This Repository

This repository contains the orchestration code, helper scripts, Docker setup, and documentation.

It does not include Linux source trees, patch datasets, POCs, VM images, syzkaller builds, local configs, database dumps, or generated experiment outputs. Those artifacts should be supplied by the user through the configured workspace paths.

Requirements

• Linux host for full overlayfs/QEMU workflows.
• Python 3.12 and PDM 2.x.
• Git, GNU patch, compiler toolchain, and Linux kernel build dependencies.
• QEMU/KVM for VM crash checks.
• Optional PostgreSQL for result storage.
• Optional syzkaller for reproduction workflows.

See docs/USAGE.md for system package installation.

Install

pdm use -f 3.12
pdm install
pdm run python -m ppatch_partner --help

Configuration

Start from the safe example config:

cp src/ppatch_partner/config/config.example.env src/ppatch_partner/config/config.env

Or point to an external private config:

export PPATCH_PARTNER_ENV_FILE=/abs/path/to/ppatch-partner.env

Private config.env files are ignored by git. See docs/USAGE.md for all settings.

Quick Start

pdm run python -m ppatch_partner.scripts.initialize main
pdm run python -m ppatch_partner.scripts.ppatch_auto main --use-gnu-first
pdm run python -m ppatch_partner.scripts.overlay auto --cve-id poc_0
pdm run python -m ppatch_partner.scripts.monitor_crash main --cve-id poc_0

For retry, batch, database, and syzkaller workflows, see docs/USAGE.md.

Docker

docker compose up --build ppatch-partner
docker compose run --rm ppatch-partner bash

The Compose setup also provides local PostgreSQL for development. Full overlayfs and QEMU flows require a Linux Docker host with the necessary kernel capabilities.

License

MIT. See LICENSE.