SyzABI

Offline differential replay for syzkaller programs across OS kernels.

SyzABI takes a corpus of *.syz programs, compiles them into reproducible testcase binaries, runs them simultaneously on a reference kernel (Linux) and a candidate kernel (Asterinas, StarryOS, ArceOS, etc.), normalizes the resulting syscall traces, compares the outputs, and produces actionable divergence reports.

Core Concept

Every workflow follows the same pattern:

syz programs  →  testcase binaries  →  run on reference + candidate  →  compare traces  →  report

The interface is unified: every workflow is driven by make <command> WORKFLOW=<name>.

Side	Typical kernel	Role
`reference`	Linux	Ground truth
`candidate`	Asterinas / StarryOS / ArceOS / Linux	System under test

Quick Start

1. Bootstrap once

make bootstrap        # Install pinned Go toolchain
make init-layout      # Create directory scaffolding

2. Prepare target source (example: Asterinas)

git clone https://github.com/asterinas/asterinas.git third_party/asterinas
git -C third_party/asterinas checkout main

3. Generate or import corpus

make generate-corpus
make import-corpus

4. Run

# Default: Asterinas smoke, 100 cases, 4 jobs
make run

# Or fully explicit
make run WORKFLOW=asterinas CAMPAIGN=smoke LIMIT=100 JOBS=4

Supported Workflows

Workflow	Purpose	Comparison
`baseline`	Validate replay framework	Linux vs Linux
`asterinas`	Differential replay	Linux vs Asterinas
`asterinas_scml`	SCML-aware filtering + preflight	Linux vs Asterinas
`tgoskits_starryos`	TGOSKits StarryOS integration	Linux vs StarryOS
`tgoskits_arceos_smoke`	TGOSKits ArceOS smoke / PoC	Linux vs ArceOS

Workflow Guides

Asterinas

One-shot:

make run
# or
ASTERINAS_JOBS=80 make run WORKFLOW=asterinas CAMPAIGN=smoke LIMIT=100

Step by step:

make filter-corpus
make derive WORKFLOW=asterinas
make prepare-target WORKFLOW=asterinas
make build WORKFLOW=asterinas
make run WORKFLOW=asterinas CAMPAIGN=smoke LIMIT=50 JOBS=4
make analyze WORKFLOW=asterinas
make report WORKFLOW=asterinas

Baseline

make filter-corpus
make build WORKFLOW=baseline
make run WORKFLOW=baseline CAMPAIGN=smoke LIMIT=100
make run WORKFLOW=baseline CAMPAIGN=full LIMIT=1000
make analyze WORKFLOW=baseline
make report WORKFLOW=baseline

SCML

make build-asterinas-scml-manifest
make derive WORKFLOW=asterinas_scml
make preflight-workflow WORKFLOW=asterinas_scml
python3 orchestrator/scheduler.py --workflow asterinas_scml --campaign smoke --limit 100 --jobs 8
python3 tools/render_summary.py --workflow asterinas_scml

TGOSKits — StarryOS

Prerequisites:

SYZABI_ENABLE_TGOSKITS=1
SYZABI_TGOSKITS_DIR=/path/to/tgoskits
Rust toolchain (rustc, cargo)
riscv64-linux-musl-gcc
QEMU system-mode qemu-system-riscv64

Preflight and healthcheck:

export SYZABI_ENABLE_TGOSKITS=1
export SYZABI_TGOSKITS_DIR=/path/to/tgoskits

python3 tools/tgoskits_launch.py --workflow tgoskits_starryos preflight
python3 tools/tgoskits_launch.py --workflow tgoskits_starryos healthcheck

Smoke campaign:

make run WORKFLOW=tgoskits_starryos CAMPAIGN=smoke LIMIT=20 JOBS=4

Scale campaign:

make run WORKFLOW=tgoskits_starryos_scale CAMPAIGN=full LIMIT=200 JOBS=8

For detailed host prerequisites, PATH setup, and troubleshooting, see docs/targets/tgoskits-starryos.md.

TGOSKits — ArceOS

Prerequisites:

SYZABI_ENABLE_TGOSKITS=1
SYZABI_TGOSKITS_DIR=/path/to/tgoskits

Preflight and healthcheck:

export SYZABI_ENABLE_TGOSKITS=1
export SYZABI_TGOSKITS_DIR=/path/to/tgoskits

python3 tools/tgoskits_launch.py --workflow tgoskits_arceos_smoke preflight
python3 tools/tgoskits_launch.py --workflow tgoskits_arceos_smoke healthcheck

Experimental single-case campaign:

make run WORKFLOW=tgoskits_arceos_smoke CAMPAIGN=smoke LIMIT=1 JOBS=1

For details, see docs/targets/tgoskits-arceos.md.

System Requirements

Host tools

bash
python3
make
git
curl
tar
gcc
strace

For Asterinas workflows

docker
qemu-system-x86_64
/dev/kvm (recommended for speed)

For TGOSKits StarryOS

qemu-system-riscv64
riscv64-linux-musl-gcc
Rust nightly toolchain

Notes

make bootstrap installs the pinned Go toolchain into artifacts/toolchains/go/current/go.
Asterinas runs use Docker by default; the shared kernel bundle is prepared once and reused.
TGOSKits targets are gated by SYZABI_ENABLE_TGOSKITS=1 and require an external TGOSKits checkout pointed to by SYZABI_TGOSKITS_DIR.

What the Runner Does

Build — syz-prog2c turns each *.syz program into a standalone C binary.
Prepare — Target-specific assets (kernel image, initramfs, Docker bundle) are built or reused.
Run — Each testcase executes in an isolated sandbox against both reference and candidate sides.
Trace — Syscall events, return values, errno, and memory outputs are captured.
Compare — Traces are normalized and compared. Results are classified:
- NO_DIFF — behavior matches
- BASELINE_INVALID — reference side failed (infrastructure issue)
- WEAK_SPEC_OR_ENV_NOISE — expected environmental difference
- UNSUPPORTED_FEATURE — candidate does not implement the syscall
- BUG_LIKELY — semantic divergence detected

Important Outputs

Asterinas

eligible_programs/targets/asterinas/asterinas/default.jsonl
build/targets/asterinas/asterinas/testcases/
artifacts/runs/targets/asterinas/asterinas/
artifacts/targets/asterinas/build-info.json
reports/targets/asterinas/asterinas/campaign-results.jsonl
reports/targets/asterinas/asterinas/summary.json
reports/targets/asterinas/asterinas/summary.md
reports/targets/asterinas/asterinas/failure-report.json

Baseline

eligible_programs/targets/linux/baseline/default.jsonl
build/targets/linux/baseline/testcases/
artifacts/runs/targets/linux/baseline/
reports/targets/linux/baseline/summary.json

TGOSKits StarryOS

artifacts/runs/targets/tgoskits_starryos/tgoskits_starryos/
reports/targets/tgoskits_starryos/tgoskits_starryos/summary.json

When investigating failures, the first files to inspect are usually:

reports/targets/<target>/<workflow>/summary.json
reports/targets/<target>/<workflow>/campaign-results.jsonl
The corresponding candidate/console.log under artifacts/runs/targets/<target>/<workflow>/

Repository Layout

.
├── agent/                 # Guest-side trace helpers
├── analyzer/              # Normalize / compare / classify
├── cmd/                   # Go helper tools
├── compat_specs/          # SCML and generation metadata
├── configs/               # Workflow and target configuration
├── orchestrator/          # Scheduler and VM runner
├── targets/               # Target-owned runtime/build logic
├── tools/                 # Corpus / build / report scripts
├── tests/                 # Regression and unit tests
├── corpus/                # Raw / normalized / meta
├── eligible_programs/     # Executable JSONL lists
├── build/                 # Testcase build roots
├── artifacts/             # Runtime state, sandboxes, caches
└── reports/               # Summaries and failure reports

Version Pins

Component	Version / Commit
`syzkaller`	`5b92003d577daa0766edda7ed533d75e1ac545ff`
Asterinas Docker image	`asterinas/asterinas:0.17.1-20260317`

The exact Asterinas revision is resolved from the configured workflow path during preparation.

Design Goals

One command to run — make run WORKFLOW=... should cover the full pipeline.
Safe parallelism — Higher JOBS should scale without corruption.
Asset reuse — Prepared kernel bundles are cached and reused across testcases.
Clean interface — No hard-coded target names in generic tooling; everything is workflow-driven.