LFx Mentorship (CNCF - urunc: Fuzzing and robustness testing for urunc)

[cmainas]

Mentorship plan: Fuzzing and robustness testing for urunc

This discussion outlines the proposed plan for the CNCF mentorship project "Fuzzing and robustness testing for urunc”.

The plan is structured into three phases. Each phase has clear goals and specific outcomes, along with suggested tasks and sub-tasks to help guide the work. The listed sub-tasks are meant as guidance and reference points, they are not strict requirements. The exact order of tasks within each phase can be adjusted as long as the main outcomes are achieved.

Phase 1

The goal of Phase 1 is to build the necessary background on fuzzing in Go, to map the input surface of urunc and to establish where the current testing suite stands. This phase is expected to last up to 3 weeks (07/09/2026 – 27/09/2026). During this time, the focus will be on understanding what fuzzing can and can not do for a container runtime, identifying every input that reaches urunc and from where, and validating the background with a first set of fuzz targets on the parts of the code that are easy to reach.

Tentative tasks and sub-tasks

• Theoretical background (fuzzing and property based testing):
  • Get familiar with the native fuzzing support of Go.
  • Get familiar with the tooling around long running fuzzing: coverage guided corpus growth, corpus minimization, deduplication of findings and regression corpora.
  • Explore how other runtimes and container projects fuzz themselves (runc, containerd, Kata Containers), which parts of their code they chose to fuzz and how their targets are structured.
  • Read and have as a reference CNCF fuzzing handbook.
• Theoretical background (urunc's input surface):
  • Go through urunc's execution flow and identify every input it reads and who controls it.
  • For each input identify who controls it and identify the risk of a malicious input.
  • Identify the "output side": the argv and the configuration that urunc builds for each monitor, the guest command line it builds per unikernel type, etc.
  • For each of the above write down the properties that should always hold (e.g. decoding an annotation never corrupts it, a converted memory value never exceeds the requested limit, a built argument list never contains empty or split elements)
• Auditing the current testing suite:
  • Map the existing unit and e2e tests to the packages of the repo and measure the coverage of each one.
  • Find the files with no tests at all and the ones that are not part of the unittest target.
  • Find the code that is hard to test today and identify why (pure logic, needs a filesystem, needs root).
• Scope and preparation for continuous fuzzing:
  • Based on all the above create a priority-based list for fuzzing and testing targets.
  • Explore OSS-Fuzz and ClusterFuzzLite.
  • Scope the integration with urunc with such projects, what urunc needs to provide etc.

Outcome

Deadline: Completed no later than 27/09/2026 (AoE).
Description: A report with:

• the theoretical background of fuzzing in Go and the findings from the exploration of other projects.
• the inputs of urunc, who controls each one and the properties that should hold
• the coverage of the current testing suite and its untested parts
• a list of fuzzing and testing targets, sorted by their importance.

Phase 2

The goal of Phase 2 is to turn the list of the previous phase into an actual testing and fuzzing suite. This phase is expected to last up to 5 weeks (28/09/2026 – 01/11/2026). During this time, the focus will be on writing the targets, fixing what they find and getting everything merged and running in the CI.

Tentative tasks and sub-tasks

• Design and implementation of the fuzzing suite *starting with the highest priority ones from phase 1):
  • Decide and start the implementation for the high priority targets, making th respective decisions for inputs, seeds etc.
  • Keep in mind that the same targets should work with the continuous fuzzing of Phase 3.
  • For each input write down what urunc should accept, what it should reject and with which error.
  • Turn each decision into an assertion of a fuzz target, so that it is enforced and not only documented.
• Small refactors to improve testing and fuzzing coverage:
  • Fix any issues found during the process of testing and fuzzing.
  • Design and suggest small refactors to cover currently unreachable fuzzing and testing targets (block / network handling).
  • Design and implement more sophisticated tests with failures in the mid of setting up the monitor environment etc.
  • Add failure injection for the setup paths that have many steps
  • CI:
    • Add a short fuzzing run on the PRs, so that the targets keep building and the regression seeds are always tested.
    • Add a longer run in the nightly CI, keeping the crashes and the corpus so a finding can be reproduce
      d from the CI run
• Continuous fuzzing:
  • Plan and submit the necessary requirements for continuous fuzzing.

Outcomes

Deadline: Completed no later than 01/11/2026 (AoE).
Description: The following items:

• Merged PRs with the fuzz targets, their seeds and the new unit, integration and e2e tests
• Merged PRs with the fixes and the better error messages, and issues with reproducers for what was out of scope
• A short and a nightly fuzzing job in the CI, along with coverage measurement
• A report with the findings, the coverage before and after and the paths that are still not reachable

Phase 3

The goal of Phase 3 is to make the fuzzing run continuously and ensure its extensibility and maintenance. This phase is expected to last up to 4 weeks (02/11/2026 – 27/11/2026). During this time, the focus will be on the continuous fuzzing setup and on the documentation.

Tentative tasks and sub-tasks

• Continuous fuzzing:

  • Finalize the integration of urunc wit OSS-fuzz or ClusterFuzzLite
  • Take into account who receives the reports and how this fits the project's security policy
  • Replace the short CI run of Phase 2 with CIFuzz, which comes for free once the OSS-Fuzz integration
    is in place
  • Keep ClusterFuzzLite as the fallback, in case the OSS-Fuzz onboarding does not complete inside the mentorship, and document what would be needed to switch later
  • Show that a real crash is detected and reported end to end, and that a fixed one stops being reported

• Documentation:

  • Document how the suite is organized, how to run it locally and how to reproduce a finding from a crash file.
  • Document how to add a new target and which properties the existing targets check.

• Robustness beyond fuzzing (time permitting):

  • Test the lifecycle under faults: interrupt the boot, delete a container twice, force a delete while the sandbox runs, and repeat these in parallel
  • Check for leftovers after each case (tap devices, loop devices, mounts, snapshots, sockets, file descriptors)
  • Add anything found in the suite as a test

Outcomes

Deadline: Completed no later than 27/11/2026 (AoE).
Description: The following items:

• urunc onboarded to OSS-Fuzz (or at least the majority of the work), running without manual work and reporting coverage and crashes automatically, with CIFuzz on the PRs
• A report summarizing all the work: the increase in testing and fuzzing coverage, the bugs found, the code improvements and the parts that remain uncovered

[cmainas]

Hello @pocopepe,

please take a look on the above plan and feel free to suggest any changes. If you agree with everything just reply here that everything looks ok.

[pocopepe]

everything looks good to me.

[pocopepe]

Phase 1 report

1. Fuzzing in Go, and how other projects do it

1.1 Go's native fuzzing

Read up on go’s native fuzzing tool chain off of Go's fuzzing docs, it needs no extra installs. Read up on how targets are set and how seeds are derived and mutated. A failing input seems to be saved inside testdata/fuzz/*function name*/ and is replayed as a subtest on every later go tests so a found bug would be reached instantaneously. Maybe a skip function to be implemented for the mean time least until we fix up the initial set of bugs that pop up. Targets seem to take primitives or byte slices, and go-fuzz-headers can build a whole struct, like an OCI spec, from the input bytes.

I used the CNCF Fuzzing Handbook as my reference. (link) It separates panics from logic bugs. In Go, logic bugs are most of what's left to find, so a target is only as good as what it asserts.

Property-based testing fits in the same place. A fuzz target that asserts a property is a property-based test whose inputs come from coverage feedback instead of pure randomness. Go's older property-testing package, testing/quick, is frozen, so native fuzzing is what I’m planning to use for both.

1.2 Long-running fuzzing

• Corpus growth. Inputs that reach new code are kept in $GOCACHE/fuzz/, and go test doesn't replay them unless they're copied into testdata. Any CI job we set up has to keep that directory between runs, or every run starts over from the seeds. Reach didn’t seem to be much of a problem but rather with go being memory safe, panic bugs are pretty much non-existent, more on that later.
• Minimization. Each new failing input is shrunk automatically before it's saved. There's no command to shrink an existing corpus; -fuzzminimizetime only bounds each attempt.
• Deduplication. Go has none, so one frequent defect produces a fresh failing input on every run and eats the time budget. In Phase 2 I'd add a way to mark a known, tracked failure so fuzzing keeps going past it, without hiding a different failure at the same place (like ASan's ignore lists).
• Regression corpora. Every input saved under testdata/fuzz/FuzzX/ becomes an ordinary test case: go test replays it without -fuzz, so a failure found once keeps getting checked on every run and in CI, and a fixed bug can't come back unnoticed. Each saved file lists one value per target parameter, in order and with its type. So changing a target's parameters breaks its saved entries, and I'd prune or regenerate them in the same change.

1.3 runc and containerd

I read how the two closest projects fuzz themselves. The links go to the files I read.

runc. Its in-repo fuzzing is a single legacy-style target, FuzzUnmarshalJSON, which decodes hook JSON and throws the result away. It's built by tests/fuzzing/oss_fuzz_build.sh with compile_go_fuzzer. The rest live in cncf-fuzzing/projects/runc, nine more targets across seven files, covering spec conversion, cgroup handling, device rules, Intel RDT and libcontainer utilities. They build whole specs with go-fuzz-headers (see specconv_fuzzer.go) and only check that nothing crashes. That directory was last touched in December 2024. runc runs on OSS-Fuzz.

containerd. Everything is native testing.F in its own repo. Most targets are in contrib/fuzz, image import, archives, diff, the event exchange, the CRI server, and the metadata stores. The store targets turn one input into a sequence of up to 50 operations against a single store, so they test state, not just parsing. The integration targets start a real containerd daemon (downloading the release binaries on first use), import up to 30 generated tar archives, and create containers from generated OCI specs. They never start a task. Setup is spread across iterations because OSS-Fuzz stops an iteration after 25 seconds, and there are variants with and without teardown between iterations. The build script finds targets by grepping for the Fuzz signature instead of keeping a list, and a dictionary for the image-import target sits next to it. Its OSS-Fuzz config uses a mailing list as the contact, with libFuzzer and the address sanitizer.

How they check results. runc's targets are all crash-only: each one calls the code and throws the result away, so the only thing it can report is a panic or a crash. containerd is mostly the same. Its CRI target catches a panic and logs the sequence of operations that led to it. Only two targets check a real property: the local content store checks that a copy writes exactly as many bytes as it was given, and the docker fetcher checks that it returns exactly the bytes that were served. In memory-safe Go, a target that only waits for a panic rarely finds anything, so for urunc I'd assert properties instead (Section 2.3).

What I'd take from this for urunc:

• Write native targets beside the code, like containerd, rather than legacy-style ones in a separate repo.
• Have the build script find targets instead of keeping a list. Autodetecting would save us from manually maintaining a list.
• Use go-fuzz-headers where the input is a struct (specs, configs), and plain string or integer parameters where the risk is in the bytes.
• Fuzzing urunc create end to end has direct precedent in containerd's integration targets. Fuzzing urunc start, which boots a guest, would go further than they do. Not too sure if you want integration targets per se, with the sync call, assumed I’d keep it in here to answer it all structured and keep a paper trail of it.

2. urunc's inputs

2.1 Inputs and who controls them

Here's every input I found in urunc's execution flow, and who controls it.

Input	Read by	Controlled by
com.urunc.unikernel.* annotations	getConfigFromSpec	image, orchestrator
urunc.json in the rootfs	getConfigFromJSON	image
Process.Env	CommandString, buildUrunitConfig	image, orchestrator
Process.Args, Cwd, User	buildUrunitConfig, BuildExecCmd	image, orchestrator
Linux.Resources	monitorMemoryBytes	orchestrator
Mounts; rootfs, block and initrd annotations	applyMounts, rootfs selection	orchestrator, image
Hooks	ExecuteHooks	orchestrator only
Linux.Namespaces[].Path	checkValidNsPath	orchestrator
Linux.Seccomp	presence check	orchestrator
Guest network (IP, gateway, mask)	guest Init	urunc's network setup
/etc/urunc/config.toml	LoadUruncConfig	host operator
State file	every command after create	urunc
Container ID, signal	validateID, parseSignal	containerd, CRI
/proc/self/mountinfo	getMountInfo	kernel
Internal log pipe	ForwardLogs	urunc's own child

The spec and containerd's output are what the targets feed into urunc: they are its inputs, so they're exactly what gets fuzzed. What I'm not doing is treating them as hostile. Following #797, whoever writes the spec can already run arbitrary hooks, so defending against a deliberately malicious spec buys nothing. Instead I generate well-formed values, including the odd but legal ones (spaces, newlines, dots, empty strings, very long values), and check that urunc handles every one of them correctly. That rules out targets whose only job is rejecting garbage, like validateID, and puts the weight on inputs urunc passes on to other programs.

2.2 The output side

Output	Built by	Read by
Monitor argv	BuildExecCmd for qemu, cloud-hypervisor, hvt, spt, hyperlight (hedge is a stub)	the monitor
Firecracker config	firecracker's BuildExecCmd, as a JSON file	firecracker
Guest command line	CommandString for linux, freebsd, unikraft, mirage, mewz, hermit	guest kernel or unikernel
Rumprun config	Rumprun.CommandString, one "env" key per variable	Rumprun's config.c
urunit config	buildUrunitConfig for linux and freebsd	urunit, when it's the guest's init
Hook argv and order	ExecuteHooks, executeHook	execve; the OCI spec
State file	UruncConfig.Map	UruncConfigFromMap

Each row is a format urunc writes and another program parses. Your tests cover each side on its own, where tests exist, but nothing checks the contract between them, so that's where most of Section 4's targets sit. Where urunc interprets a value it validates it (getDNSServer, for example). Where it only passes a value on, it concatenates.

2.3 Properties that should hold

runc and containerd mostly wait for a panic (Section 1.3). Go is memory safe, so panics are rare, and a target that only waits for one finds little. So these are the oracles I'm planning to add: properties each target asserts on every input.

• Each env entry reaches the guest as exactly one variable.
• Converted memory, read back in the monitor's own unit, never exceeds the OCI limit.
• All backends agree on whether a guest command line is passed.
• Hooks run in the listed order, with the spec's args as their argv.
• Map and UruncConfigFromMap are inverses.
• The state file reads back exactly as written.
• Decoding annotations never changes a value that was already readable.
• A built argv never contains an empty element unless the input was empty (qemu's -append "" for an empty command line is fine), and never splits a single path across two elements.
• Every mount option lands in exactly one class: propagation flag, VFS flag, or passthrough.
• A failed initrd merge leaves the original file untouched.

3. The current test suite

3.1 Unit test coverage by package

I measured unit-test coverage on upstream main as of 18 September 2026, for every package in the repo.

Package	Test files	Statements covered	Coverage
pkg/unikontainers	11	631 / 2,044	30.9%
pkg/unikontainers/hypervisors	9	161 / 322	50.0%
pkg/unikontainers/unikernels	3	168 / 567	29.6%
pkg/unikontainers/initrd	1	126 / 175	72.0%
pkg/network	1	4 / 283	1.4%
internal/metrics	2	8 / 15	53.3%
cmd/urunc	0	0 / 591	0.0%
pkg/containerd-shim/containerd	0	0 / 137	0.0%
pkg/containerd-shim	0	0 / 26	0.0%
cmd/containerd-shim-urunc-v2	0	0 / 1	0.0%
pkg/unikontainers/types	0	declarations only
internal/constants	0	declarations only
Overall	27	1,098 / 4,161	26.4%

How I got these numbers. On a clean checkout of main from that date, I ran every package's unit tests with a coverage profile:

go test -count=1 -coverprofile=cover.out $(go list ./... | grep -v /tests/)

How the percentages are calculated. It's Go's statement coverage, counted by go test itself (how Go counts it): a statement is what the Go spec calls one, found by parsing the source rather than by hand. So pkg/unikontainers has 2,044 statements and the unit tests run 631 of them: 631 / 2,044 = 30.9%. The overall row is every covered statement over the 4,161 in the repo outside tests/, not an average of the package percentages. go tool cover -func prints a higher total, since it skips the 91 statements in closures outside named functions, mostly cmd/urunc's CLI actions.

Where the gaps are. Two things the table doesn't show. cmd/urunc and the three shim packages aren't part of make unittest, so each would need a target once it has tests. And within packages, the least-covered files by untested statements are unikontainers.go (566 untested, 10.3% covered), network.go (212, 1.9%), cmd/urunc/create.go (209, 0%), mount.go (186, 0%), block.go (168, 14.7%), rootfs.go (164, 12.8%) and unikernels/linux.go (153, 3.2%).

3.2 End-to-end tests

tests/e2e has 61 distinct scenarios, run 79 times across nerdctl, ctr, crictl and docker. They boot real guests through the installed urunc and its shim, so they exercise the packages unit tests barely reach: cmd/urunc, the shim, pkg/network and all of pkg/unikontainers.

• By monitor: qemu 21, firecracker 16, hvt 11, spt 8, cloud-hypervisor 4, hyperlight 1. hedge is a stub, so it has none.
• By guest: unikraft 20, linux 15, rumprun 12, mirage 8, freebsd 4, mewz 1, hermit 1.
• By feature: networking 21, block devices 9, seccomp 7, shared filesystems 3, initrd 2, vAccel none.

I measured e2e coverage the way vm_test.yml runs the suite: all four tools, once with urunc's own runtime and once more with libcontainer = true. Every scenario passed in both runs (79, then 78, since CI skips Firecracker-unikraft-httpreply-static-net in the libcontainer run).

Package	Statements	Unit	e2e	Unit + e2e
pkg/unikontainers	2,044	631 (30.9%)	1,416 (69.3%)	1,549 (75.8%)
cmd/urunc	591	0 (0.0%)	365 (61.8%)	365 (61.8%)
pkg/unikontainers/unikernels	567	168 (29.6%)	473 (83.4%)	489 (86.2%)
pkg/unikontainers/hypervisors	322	161 (50.0%)	225 (69.9%)	236 (73.3%)
pkg/network	283	4 (1.4%)	151 (53.4%)	152 (53.7%)
pkg/unikontainers/initrd	175	126 (72.0%)	126 (72.0%)	137 (78.3%)
pkg/containerd-shim/containerd	137	0 (0.0%)	94 (68.6%)	94 (68.6%)
pkg/containerd-shim	26	0 (0.0%)	19 (73.1%)	19 (73.1%)
internal/metrics	15	8 (53.3%)	2 (13.3%)	9 (60.0%)
cmd/containerd-shim-urunc-v2	1	0 (0.0%)	1 (100.0%)	1 (100.0%)
Overall	4,161	1,098 (26.4%)	2,872 (69.0%)	3,051 (73.3%)

Each cell is statements run (and the percentage of the package's total), counted as in Section 3.1. In the last column a statement counts once if either kind of test runs it. Measured separately, the plain run covers 2,681 statements (64.4%) and the libcontainer run 2,798 (67.2%). The unit tests add 179 statements the e2e runs never reach, 133 of them in pkg/unikontainers.

How I got these numbers. Same main from 18 September, built with coverage on (Go's docs):

GOFLAGS="-cover -covermode=atomic -coverpkg=github.com/urunc-dev/urunc/..." make urunc_static shim_static

Then I set GOCOVERDIR on containerd so the shim and every urunc call inherit it, installed the monitor versions CI pins, pre-pulled the images, and ran make -k e2etest. go tool covdata textfmt turns the output into a profile, and I merged that with the unit profile statement by statement. There's one catch: urunc ends by exec'ing the monitor, and a Go process that execs never writes its counters. So the build carries a local-only patch that flushes them just before each exec, and bind-mounts the counter directory into the monitor's rootfs so the flush still works after the pivot. It's about 25 lines, only for measuring, and its own statements aren't counted. This covers amd64 only, and doesn't include the arm64 job or the kind test.

What neither reaches. 1,110 statements. About half are small error-return or logging blocks. The larger untested paths are:

• urunc delete --force on a running container. It's the only caller of Unikontainer.Kill, which joins the sandbox's network namespace and runs the tap cleanup in pkg/network (CleanupAllUruncTaps and its helpers), about 100 statements together. Every scenario stops a container before removing it.
• A container with a terminal. The pty and console-socket path in cmd/urunc/create.go never runs.
• vAccel over vsock in Exec, since there's no vAccel scenario.
• Joining existing mount, cgroup or time namespaces in FormatNsenterInfo. The suite joins existing IPC, UTS, network and PID namespaces, but never those three.

The first three need new e2e scenarios. The namespace branches can be unit-tested directly, since FormatNsenterInfo only encodes the spec and checks that each path exists.

3.3 What gets fuzzed and what gets unit-tested

I'd split the work by what the risk looks like.

Fuzzing, where the shape of the input is the risk. urunc takes values it doesn't control the shape of and turns them into something another program reads: env and args into the guest command line or urunit's config, memory and the command into each monitor's argv, annotations into config, config into the state file and back, mount options into flags. Those inputs are open-ended strings and maps, and the bugs hide in awkward but legal shapes: a space, a newline, a dot in a name, an empty value, a very long one. The check can be written once, as a property that has to hold for every input: an env entry stays one variable, a round trip loses nothing, every backend agrees. Hand-written cases only cover the shapes someone thought of. The fuzzer tries the rest.

• Differential, where urunc has more than one implementation of the same job: argv across the seven monitor backends, command lines across the guest types, the same config arriving through annotations or urunc.json. The oracle is just “these must agree”.
• Property, where there's one implementation: env encoding, the config and state file round trips, mount option classification, the initrd merge.

Unit tests, where the right answer is known exactly. Most of urunc's logic is per backend or per guest type: the argv qemu gets for a given config, the command line a unikraft guest gets, which rootfs a set of annotations selects, what the monitor spec looks like. For a given input there's exactly one right output, so a table of cases with the expected output checks it more precisely than random inputs can, and doubles as documentation of the intended behaviour. It's also the direct way to reach specific combinations (this monitor, this guest type, this rootfs) that a fuzzer would take a long time to hit. This covers the per-backend and per-guest output, the lifecycle helpers (buildMonitorSpec, ChooseRootfs, getMonitorResources), hook execution, and the command and shim wiring in cmd/urunc and pkg/containerd-shim.

How the two fit together.

• A fuzz target sits next to the unit tests for the same code and reuses their fixtures. The hypervisor tests already have a fake guest (fakeUnikernel in qemu_test.go) that a target can use.
• When fuzzing finds a failing input, Go saves it as a regression entry. If it points at a case worth naming, it also becomes a row in the unit-test table.
• Both run in make unittest: the seed and regression entries of every target replay on each test run. Long fuzzing runs belong to the nightly job.
• Mutation testing keeps both honest: a test or target has to fail when the code it covers is deliberately broken.
• Code that needs root or a running guest (mounts, pivot_root, networking, the monitors themselves) stays with e2e.

4. Fuzzing and testing targets

4.1 Targets, by importance

This is the order I'd work through them in Phase 2. I ranked them by who controls the input (image before orchestrator before host), how many guests or monitors it reaches, and how little the current suite checks it.

#	Surface	Kind	Checks	Why here
1	Guest env and command line (Process.Env into the kernel command line and urunit's config)	fuzz: property, and differential against urunit's parser	each env entry arrives as exactly one variable, and urunc's own parameters and sections stay intact. urunit's rules are modelled from its source.	image-controlled, reaches every Linux and FreeBSD guest, passed on unescaped; linux.go is 3.2% covered
2	Monitor argv across backends (BuildExecCmd)	fuzz: differential	backends agree on memory (in each monitor's unit) and on whether a command line is passed; no single path is split	every container, seven backends; half of hypervisors is untested
3	Annotations and urunc.json	fuzz: round trip; unit tests	the same config decodes identically from either source, and validation rejects the same values	image-controlled; picks monitor, binary and paths
4	Rootfs selection, mounts, initrd, block	fuzz: property; unit tests	each mount option lands in one class; the rootfs choice follows the annotations; a failed initrd merge leaves the file untouched	mount.go 0%, block.go 14.7%, rootfs.go 12.8% covered
5	Hooks	fuzz: differential against the spec; unit tests	argv equals the spec's args, and hooks run in the listed order	orchestrator-controlled, but ordering is a spec MUST
6	Namespaces, capabilities, seccomp into the libcontainer config	fuzz: differential	the generated config asks for exactly what the spec asks for	security settings translated without a test; coordinate with PR #974
7	config.toml and state file	fuzz: round trip	Map and UruncConfigFromMap are inverses; the state file reads back as written	host- or urunc-controlled
8	Container lifecycle (unikontainers.go)	unit tests	each step of create, start, kill and delete	10.3% covered, 566 statements untested: the largest gap
9	cmd/urunc	unit tests; needs a make target	argument handling and command wiring	591 statements, no tests
10	urunc create as root	integration fuzzing	creation succeeds or fails cleanly for generated specs	containerd precedent; Phase 3

Known upstream issues on these surfaces should each get a regression target: the open ones once they're fixed (#754, #818, #867, #897), and the subnet-mask reports alongside them (#909 and #963, both closed as duplicates). I'm not planning to fuzz pkg/network or pkg/containerd-shim; e2e covers them better.

How I'd judge each target:

• The oracle is differential wherever a second implementation exists (seven backends, seven guest types, code copied from runc), a stated property otherwise, and never just “doesn't panic.”
• Where the check depends on another program (a monitor, the kernel, urunit), I'd model that program from its own source, not from urunc's encoder.
• Coverage shows what a test runs, not what it checks, so I'd also use mutation testing (deliberately breaking the code and seeing whether a test fails) to decide whether a target or test earns its place.

4.2 OSS-Fuzz and ClusterFuzzLite

I read OSS-Fuzz's own docs: how it accepts new projects, the new project guide and its Go page, and the bug disclosure guidelines. For ClusterFuzzLite I read its build integration and GitHub Actions pages. I also looked at how runc and containerd are set up there (Section 1.3).

Getting urunc into OSS-Fuzz:

1. Open a PR to google/oss-fuzz adding projects/urunc/project.yaml: homepage, main repo, language go and a primary contact.
2. In the same directory, add a Dockerfile (starting from gcr.io/oss-fuzz-base/base-builder-go and cloning urunc) and a build.sh that compiles each target with compile_native_go_fuzzer.
3. Check it locally with OSS-Fuzz's helper: infra/helper.py build_image, build_fuzzers, check_build, then run_fuzzer on each target.
4. Once merged, it fuzzes continuously and files bugs in OSS-Fuzz's tracker, CCing the primary contact (file_github_issue mirrors them to GitHub too). A report goes public 90 days after it's filed or once the fix ships, whichever is first, with a 14-day grace period.

The lighter route is runc's: keep the targets in cncf-fuzzing. runc's OSS-Fuzz project clones both runc and cncf-fuzzing and runs both build scripts.

ClusterFuzzLite uses the same three build files, kept in .clusterfuzzlite/ in urunc's own repo, and runs in its CI instead of Google's. On GitHub Actions that's three workflows: cflite_pr.yml fuzzes the code a pull request changes, cflite_batch.yml runs longer on a schedule, and cflite_cron.yml prunes the corpus and builds coverage reports. To keep the corpus and crashes between runs, it pushes them to a separate storage repo, which needs an access token stored as a secret. No approval is needed, and results stay with the project.

4.3 What it would take on urunc's side

• Fuzz targets in importable packages. cmd/urunc is package main, so OSS-Fuzz can't build targets there. Section 5 covers what that means in practice.
• A build script that compiles every target with compile_native_go_fuzzer, finding them by grepping for the signature as containerd does, plus dictionaries for string-shaped targets. The same script can serve both OSS-Fuzz and ClusterFuzzLite.
• Seed corpora shipped as zip files next to each target. OSS-Fuzz doesn't use f.Add seeds, and supports only F.Fuzz() from testing.F.
• A project.yaml: language go, libFuzzer with the address sanitizer (containerd's settings), and a primary contact. OSS-Fuzz asks for an established committer's address tied to a Google account, and verifies it informally if it isn't the submitter's own. containerd's contact is a mailing list, so that has been accepted before.
• A Dockerfile on OSS-Fuzz's base-builder-go image that clones urunc.
• A ClusterFuzzLite workflow: a short run on pull requests, and a nightly batch run that keeps its corpus and crashes, probably something for phase 2 as mentioned in the discussions thread.

5. What would change in urunc

Here's what the plan above would touch, and how big each change is. Most of it is new test files. The code changes are small and internal.

5.1 New files only

• Tests and fuzz targets go in _test.go files next to the code they test. A test in the same package can call unexported functions such as buildUrunitConfig or splitMountOptions, so none of this touches production code.
• Build and CI: cmd/urunc and the shim packages added to make unittest once they have tests, a make target that discovers and runs every fuzz target, and the OSS-Fuzz and ClusterFuzzLite files from Section 4.3, with seed corpora and dictionaries.

5.2 Small changes, to make code testable

• getMountInfo hardcodes /proc/self/mountinfo inside the function. Passing the path (or a reader) in lets block-rootfs selection be tested against a fixture file instead of the host's own mounts. One signature and its two callers.
• Firecracker's BuildExecCmd builds the monitor's JSON config and writes it to disk in the same function. Splitting building from writing lets the config be tested and fuzzed like the other backends' argv, without touching the disk. One function split in two.
• Most of cmd/urunc's commands (delete, kill, ps, run, and parts of create, start and monitor) keep their logic in closures inside the command definitions: 85 statements that no named function holds. Moving each body into a named function lets a unit test call it. Mechanical.

I'd put these tests on what the create phase gathers (ChooseRootfs, getMonitorResources), which both the current and the libcontainer path run, and leave Exec and setupMonitorRootfs to e2e, since #780 puts that path behind a configuration option.

5.3 package main and OSS-Fuzz

Native go test -fuzz works in package main, so nothing has to move to fuzz cmd/urunc locally or in our own CI. OSS-Fuzz is different: its build imports the package under test, and Go doesn't allow importing package main. None of the targets in Section 4.1 live in cmd/urunc, so nothing needs to move now. If we later want OSS-Fuzz to cover something there, that function moves to an internal/ package first, one function at a time.

If you'd rank any of this differently, I'd like to hear it before Phase 2 starts.

[cmainas]

Hello @pocopepe ,

please submit the first PRs for the introduction of the fuzzing skeleton. We will iterate over it multiple times.

[pocopepe]

Hi, just noticed I could open the prs, I've opened a tiny one to start with; #1095

[pocopepe]

The order I plan to send the fuzzing work in. I'll tick these off as they merge.

• make fuzz and a target for urunc.json (test: add make fuzz and a urunc.json fuzz target #1095)
• a GitHub Actions workflow that runs the targets nightly with ClusterFuzzLite (ci: add nightly ClusterFuzzLite fuzzing and corpus pruning #1128)
• annotation targets: the container spec annotations, and annotations vs urunc.json read the same way
• the create-path target with its checks: a whole bundle through create, up to the monitor's command line
• two more checks on it: same input gives the same result, file mounts end up in the initrd
• shim and CLI targets: annotations patched into config.json, reading annotations from the image, container id and signal parsing, log forwarding
• stricter checks on the create-path target, one at a time as the issues they trip on get fixed

[cmainas]

Thank you @pocopepe for the plan. a few questions:

• Just for clarification by "a whole bundle through create, up to the monitor's command line" you mena various specific targets in that path like the ones you list and not the entire end-to-end create path, right?
• Similarly for "same input gives the same result, file mounts end up in the initrd" this is one big integration test or smaller ones?

[pocopepe]

Thanks for taking a look.

• One target at the top, fed the whole bundle the way a real container arrives. It grows over a few PRs, each reaching further into create. I grouped them into one line in the list; I'll split the PRs depending on how big each one turns out.
• Smaller, both are checks on that same target, in one small PR after those.

[pocopepe]

Hi @cmainas,
Few questions before the next two PRs (create-path target, then CI).

Target runs a bundle (config.json + optional urunc.json) through create, New to BuildContainerConfig, stub monitors, no root, checks what urunc hands the monitor.
CI would be a nightly ClusterFuzzLite batch + daily corpus prune, grown corpus kept in workflow artifacts (mimicking what oss fuzzer does with runc for now), build.sh lists targets like runc's.

1. Seeds: runc commits none, its parsers get going from random bytes and oss fuzzer keeps the corpus. Ours needs a full spec, so seeds go in testdata/fuzz/FuzzCreate/ (libFuzzer ignores f.Add, this recommendation was found on OSS-Fuzz's issue tracker). Tho the converter splits two input seeds in half, so the target takes one input split at a NUL (libFuzzer's Rust docs split on a separator the same way). Alternative being either settling for two inputs + own seed encoding; only third party converter is corpus2ossfuzz but seems to cut values over 255 bytes and is pretty outdated. NUL split works or we look into a third party converter or something of our own? was thinking of settling for NUL split for now and improve over time.
2. urunc looks up /dev/kvm to build the monitor's device list, and the fuzzing container doesn't have it when ran on github actions. runc's fuzzers pass temp paths with fake files to get around this. Ok to make that path passable, or stop the target before that step?
3. CI runs ~30 mins every night, plus a ~10 min prune every day. Is that ok on Actions minutes?

[cmainas]

Hello @pocopepe ,

as discussed in syncs, please open draft PRs and we can discuss in more details there. We can also invoke the CI from draft PRs (and then replace it with nightly).

Some answers:

1. I am not sure I understand the question. It is also not clear why we need a full spec and runc does not.
2. I think the /dev/kvm path is available in github actions. We use that to run e2e tests. In any case, we are not going to open this device, so a stub is fine.
3. Yes this is fine.