Reporting issues

File it in Issues — have a quick look at the open ones first, including the ones filed as debt: several known gaps already have a number, and a comment on the right issue is worth more than a new one.

What a usable report contains

Kernel bugs are reproduced on someone else's machine, under emulation, from a toolchain built from source. Half the useful information is about your setup, so say it plainly:

• Host OS and CPU architecture. "macOS 15, Apple Silicon" and "Ubuntu 24.04, x86_64" are different machines in a way that matters here: on ARM the container is emulated.
• Commit. git rev-parse --short HEAD on the tree you built. "Latest main" ages badly.
• QEMU version, from inside the container: qemu-system-i386 --version. It comes from the distro packages in the image, so it is not fixed forever. If the problem is in the build rather than the run, i686-elf-gcc --version instead.
• The exact command, and where you ran it. make run inside the container is not the same report as a hand-written qemu-system-i386 line, and both are fine — but not interchangeable.
• Whether you did a clean rebuild. make clean && make iso before reproducing. An incremental build hides warnings and can boot a stale ISO (Troubleshooting covers both), and the first question will be this one.
• The serial output, pasted verbatim in a fenced code block, from the banner line (it carries the version) down to where things stop. Not summarised, not "then it panicked", not a screenshot of a terminal: the register dump is the bug report. make run puts it in your terminal; make run-vga leaves it in build/serial.log.
• What you expected instead. Sometimes the answer is that the kernel is behaving as intended for this phase, and knowing what you expected is what makes that answer useful rather than dismissive.

If the kernel reboots with no output at all, say that too — silence is a symptom with its own short list of causes.

Leave the milestone empty; issues get sorted into the phase that has to settle them during triage.

Labels

Most are GitHub's defaults, used as expected: bug, enhancement, documentation, question, duplicate, invalid, wontfix, help wanted, good first issue.

Three are the project's own:

Label	Meaning
security	Privilege boundaries, untrusted input, and constraints to respect before ring 3 exists.
portability	Keeps the generic kernel independent from one architecture or one target.
debt	A deliberate shortcut or a known gap, written down so it is not rediscovered later.

What a security label does not mean

None of the security issues are open holes. There is no ring 3 yet, no users, no processes, no paging and no system call interface: today the kernel is the only thing running, and everything it runs is its own code. There is no privilege boundary to cross, so there is nothing to escalate from.

They are design constraints with a deadline. Each one records something that is harmless now and would be a real vulnerability the moment the boundary appears — flat user segments, a TSS whose esp0 is still the boot stack, EFLAGS that must be masked on the way back, Multiboot data that must be validated as outside input before anything trusts it. That is why they sit in the phase 4 and phase 5 milestones rather than being marked urgent: they have to be settled before the first iret into ring 3, not after someone finds them from the other side.

So: a security issue here is a promise to keep, and new ones are welcome in the same spirit — "this will not hold once there are two privilege levels" is exactly the kind of report that is cheap now and expensive later. If you do believe you have found something exploitable in the kernel as it stands today, say so explicitly in the issue; it would be the first.