The first piece of security research I published that turned into a credited fix started with a man page. Not with a fuzzer, not with a disassembler, not with a sophisticated static analysis tool. With reading the unveil(2) man page carefully and asking a simple question: does the code actually do what this says?

The man page said: “An attempt to increase permissions was made” returns EPERM. The code said: #if 0. The escalation guard had been disabled since the initial commit in 2018. The man page had been making a promise the code was not keeping for eight years.

This is not a story about a spectacular bug. It is a story about the value of reading documentation carefully, taking it seriously as a specification, and checking whether the implementation matches. That sounds obvious. In practice, it is a surprisingly underused technique.

Documentation as specification

A man page, when it is well-written, is a specification. It describes the intended behaviour of the system: what inputs are accepted, what outputs are produced, what error conditions are defined, what invariants hold. It is written by someone who either implemented the thing or understands it deeply, and it represents a claim about how the system behaves.

A security researcher reading that specification is asking: is this claim true? Not in the general case, but in the specific: does the code path that handles this input produce this output under these conditions? Does the error condition fire when the man page says it should? Does the invariant hold under adversarial input as well as normal input?

This is exactly the approach I used on the OpenBSD unveil(2) implementation, and it is exactly the approach I use when I start working on any new subsystem. Read the documentation first. Understand what the system claims to do. Then read the code and check whether the claims are honoured.

Why OpenBSD's man pages are worth reading

Not all man pages are created equal. Some documentation is cursory, out of date, or simply wrong — accurate for an earlier version of the code and never updated. OpenBSD's man pages are, in my experience, the gold standard. They are precise, they are honest about edge cases and error conditions, and they are maintained alongside the code rather than as an afterthought.

The OpenBSD culture of correctness — which I wrote about in an earlier post — extends to documentation. A man page that makes a false claim about behaviour is a bug, and it is treated as such. This means that when you read an OpenBSD man page and find a discrepancy with the code, you have found something worth reporting: either the code is wrong or the documentation is wrong, and either way the project wants to know.

The BBC BASIC manual and the habit of reading carefully

My dad had a BBC BASIC manual for the Commodore PET. I used to read it alongside him when he was typing in games from magazines — partly to help spot mistakes before they became bugs, and partly because I found the manual itself interesting. It was precise in the way that technical documentation for machines has to be precise: a BASIC interpreter does not guess what you meant, it does what you said, and the manual explained what “what you said” meant in terms the machine understood.

The habit of reading technical documentation carefully — not skimming for the gist but reading for the exact claim being made — formed early, in front of that green screen, trying to understand why the listing was not working the way the magazine said it should. The magazine, it turned out, was sometimes wrong. Which taught me something useful: documentation is written by humans, and humans make mistakes, and the gap between what was written and what was meant is always worth checking.

The Apple Platform Security Guide as documentation

Apple's Platform Security Guide — which I wrote about in a recent post — is documentation in this same sense: a detailed public specification of what the security architecture is intended to do. Reading it carefully, and then reading the XNU source, is a productive research approach precisely because Apple takes the documentation seriously enough that discrepancies are meaningful.

Not every vendor provides documentation at this level of detail. Those that do are, in a sense, inviting the careful reader to check their work. The invitation is worth accepting.