LLSoftSecBook: a book on hardening binaries, written in the open

The gap that started the book

LLSoftSecBook exists because two compiler engineers could not find the book they wanted. The README tells the story plainly: Kristof Beyls and Georgia Kouveli, compiler engineers who work on security features from time to time, wished a book like this would exist, and after not finding one decided to write one.

The problem they set out to solve is stated in the first paragraph. The book aims to provide a structured, broad overview of all attacks and security hardening techniques relevant for code generation tools. The reason it is needed is that compilers, assemblers and similar tools generate all the binary code that processors execute, so they matter for hardening binaries against security threats. And the reason nobody had written it is that the variety of attacks and hardening techniques has been rising sharply, and it is becoming difficult to maintain a good broad basic understanding of all of them.

That is a well defined problem with a well defined audience. The book is for every compiler developer who needs to learn about software security relevant to compilers, and it aims to do that by providing a description of the high-level aspects of attacks, vulnerabilities, mitigations and hardening techniques, with pointers onward to more detailed sources for specific techniques.

The primary language of the repository is TeX, and the top level holds book.md, book.bib, a Makefile, a theme directory, a docs directory, image sources and the contribution guide. So the object is a book, written in a form that builds to both a PDF and a web version from the same source.

Unfinished on purpose, and the strategy for getting there

The most unusual thing about this project is stated in the README without embarrassment: as you read this, the book remains unfinished, and this book may well never be finished, as new vulnerabilities continue to be discovered regularly.

That is a design position, not an apology. The argument is that developing the book as an open source project allows it to continue to evolve and improve, and that being open source increases the likelihood that it remains relevant as new vulnerabilities and mitigations emerge.

The authors are also explicit that they are far from experts on all possible vulnerabilities, so they set out a two-fold plan for reaching high quality coverage. First, by studying specific topics, they hope to gain enough knowledge to write a good summary for the book. Second, they very much invite and welcome contributions from other experts, and the book was created in an open source style precisely because the authors realised they did not have all the necessary expertise to complete such a daunting task on their own.

The project also invites readers to contribute rather than only authors. The README raises the possibility of improving the book as a reader, and asks for feedback, both positive and constructive criticism, shared through a GitHub Issue, a GitHub Discussion, or the project's Discord server.

The contributor list shows how distributed the work has become. The all-contributors badge records 29 people, and the visible entries include Kristof Beyls, Francesco Petrogalli and g-kouv among the maintainers and reviewers, with Simon Tatham listed as a contributor. A book about compiler security that has been reviewed by people of that calibre is a different proposition from a wiki page, and the open process is the mechanism that makes it possible.

Building the book, locally or in a container

The build is a Makefile driven pandoc pipeline, and the README gives two ways to run it.

The plain route is:

$ make all

which requires pandoc, latex and the necessary latex packages to be installed. The Makefile shows what that means concretely. The all target depends on pdf, html, the default pandoc html and latex templates, a native build, epub and the downloads targets, so a single `make all` produces every artefact. The pdf target is build/book.pdf, the html target is build/book.html plus build/default.css and build/index.html, and there are separate epub and native targets.

The pandoc flags are set for a self-contained output. The Makefile passes --table-of-contents, --number-sections, --resource-path=., --standalone and --embed-resources, with the comment noting that --self-contained ensures images are embedded in the generated HTML and that --resource-path indicates where pandoc can find external resources such as images. The version string is injected as metadata, taken from `git describe --match '0'`.

The reproducible route is the script the README recommends, which builds a container with the exact versions of pandoc, latex and the extra packages:

$ ./build_with_docker.sh

The README says the easiest way to make sure you build the book with the right versions of those tools is to use that script, and that it builds a docker container with the exact versions and then builds the book using that container. A Windows equivalent, build_with_docker.bat, sits alongside it.

Either way, the output lands in the build directory: build/book.pdf and build/book.html when the build finishes successfully. The image sources are SVG, and the Makefile converts them to PDF with rsvg-convert so they can be included in the LaTeX build, a small detail that only matters if you are debugging the PDF path.

A live web version alongside the PDF

The book is not only a source repository. A live top-of-main version is published as a webpage, and a PDF is available from the same site.

That arrangement matters for how a book like this gets used. A PDF is the right artefact for reading a chapter end to end, or for citing a page. A web version of the top of main is the right artefact for checking what the project currently says about a technique, because it reflects the current state of the source rather than the last release. There are no GitHub releases for this project, so the live site is effectively the canonical published artefact.

The build produces the same outputs twice, with a naming distinction that suggests a distribution channel. The downloads target builds LLSoftSecBook.pdf, LLSoftSecBook.html and LLSoftSecBook.epub, alongside the internal build/book.pdf and build/book.html.

The theme directory and the lua filters in the Makefile, theme/fignos.lua and theme/index.lua, plus a citeproc pass and the book.bib bibliography, show that citations are part of the source rather than an afterthought. A book that points onward to more detailed sources for specific techniques needs a working bibliography, and the citeproc filter in COMMONFILTERS is what produces it.

The home page for the project is at llsoftsec.github.io/llsoftsecbook, and the build badge in the README shows that the book is built by a Docker container in CI, which is the same container approach the README recommends for local builds.

Where a book like this does not help

The first limit is the obvious one: this is not a specification. The book is explicitly unfinished and may never be, so a team that wants a checklist of what a compiler must implement will not find one here. It is a map, and the README describes its role as providing pointers onward for further details on specific techniques. A chapter that summarises a class of attack is a signpost, not a conformance document.

The second limit is that summaries age. A book built as a picture of the field in a given year is out of date on the specific mitigations even if its structure still holds. The open source process is the answer to that problem, and it works, but it works at the pace of contributions rather than at the pace of disclosure. A newly disclosed vulnerability with a novel mitigation strategy will be in the book when somebody writes that chapter.

The third is the audience mismatch. The stated audience is compiler developers, with an expectation that the book will also be useful to other people working on low-level software. If you are an application security engineer looking for a general vulnerability catalogue, this is aimed somewhere else, and the pointers to specific techniques will send you to better sources anyway.

The fourth is licence, and it needs care because the project is described in two ways at once. The README badge says CC BY 4.0, and the Makefile header carries an SPDX-License-Identifier of CC-BY-4.0 with a copyright line naming Arm Limited. The repository licence field, however, records a custom licence that GitHub cannot classify. So the code in the repository, the Makefile and the docker build scripts are under CC BY 4.0, while the top-level LICENSE file and the LICENSES/ directory hold something else. If you intend to reuse the build tooling in your own project, read the LICENSE file rather than assuming the badge covers everything.

The alternative: read the papers and the specs directly

The realistic alternative to this book is not another book. It is the primary literature: the original vulnerability disclosures, the processor architecture manuals, the compiler documentation, and the specifications for the mitigations themselves.

The difference in approach is what a book gives you and what a paper does not. A primary source is precise and complete for one technique, and says nothing about the fifty others. It is written for someone already inside the topic, and it assumes the surrounding vocabulary. Reading a paper about a control flow integrity mechanism tells you exactly how the mechanism works and roughly nothing about how it relates to the other mitigations a toolchain might emit.

A book in this style is an index. Its value is the map: which attacks apply to generated code, which mitigations address them, and where the interactions between them are complicated. For a compiler developer who knows their area and needs to widen it, that is a genuine saving.

The other alternative is a course or a workshop on compiler security, which gives the same broad orientation with the added benefit of an expert in the room. The difference is that it is a fixed event with a fixed curriculum, whereas this book is a living document whose coverage you can see and contribute to.

There is a third practical route worth naming: a security team that already owns a compiler or assembler simply writes down its own hardening checklist, using this book to check for topics nobody has covered yet. Given that the project explicitly solicits contributions and flags its gaps, that feedback loop is the one the authors have in mind.

Editorial conclusion

Adopt LLSoftSecBook as a reading list and a reference map if you work on a compiler, assembler or code generation tool and need one place to see how attacks on generated binaries connect to the mitigations a toolchain can apply. Do not adopt it as a specification to implement against, since the README says the book remains unfinished and may never be, and the chapters are summaries that point onward to more detailed sources. Before you plan a chapter from it, check the topics you intend to cover against the current table of contents, and if you find a gap, the project asks for contributions through GitHub issues, discussions or the Discord server.

Frequently asked questions

Official sources

1. Issues
2. llsoftsec/llsoftsecbook on GitHub
3. Project website
4. README