OWASP CheatSheetSeries: the Markdown is a working source, and the README asks you not to quote it

The Markdown is a working source, and the README asks you not to quote it

There is a flagged note near the top of the README that is easy to scroll past and that changes how you should treat the whole project.

It says the Markdown files are the working sources and are not intended to be referenced in any external documentation, books or websites. In the same section, the project asks you to read and reference the cheat sheets through the official website, and says the project details are on the main OWASP site.

The licence and the instruction pull in different directions and an engineer needs both. The repository is under a Creative Commons share-alike licence, which in ordinary terms permits reuse and copying provided you attribute and licence derivatives the same way. The README is asking for something narrower: that the prose not be copied into your own wiki or your own handbook, and that people be pointed at the site instead.

That request has a good reason behind it. A cheat sheet copied into a company wiki is a snapshot with no update path, and a snapshot of security advice is exactly the thing that goes stale while still being trusted. Linking costs nothing and keeps the reader on the maintained copy.

Five index files, so a cheat sheet is a pointer into the rest of OWASP

The repository root has one obvious index and five others, and the names of the extra five are the interesting part.

There is a main index, and then indexes keyed to other OWASP projects: two for a security verification standard, one of them explicitly the fourth generation, one for a mobile verification standard, one for proactive controls, and one for the project's own top ten list.

That is a structural decision rather than a set of extra files. It says the series is not a self-contained library of advice, it is a set of documents that are indexed against the wider OWASP project portfolio, and a reader arriving from an application security verification assessment or a mobile one has a path in.

For a team, the practical consequence is that a cheat sheet is best treated as the entry point to a standard rather than as the standard. The indexes are the map, and they are the part to watch if you want to know whether a topic has been connected to an assessment framework yet.

The entire JavaScript side is three linters and a link checker

The Node manifest is the clearest statement of what this repository is, because it contains no application code at all.

There are five development dependencies and they are all checking tools: a link checker, a Markdown linter, a text linter, a rule that lets comments be filtered out of text linting, and a terminology rule. The main entry point is a file called index.js, which is not described anywhere in the project because there is nothing to describe.

The scripts are equally narrow. One lints Markdown across the whole tree with a configuration file and two ignore paths. One runs the terminology rules over the cheat sheets directory specifically. One runs a link checking script. And the test script is the composition of the first two plus a link check test.

So the quality gates on this project are about prose. A sentence that uses the wrong term for a security concept fails the build, in the same way a failing test would. That is a deliberate choice for a corpus whose failure mode is imprecise advice rather than broken code, and it is also the reason the repository needs no test framework for behaviour.

Link checking is a test, and it has an allowlist of known failures

The link checking deserves its own paragraph because it is the most interesting engineering decision in the repository.

There is a configuration file for the link checker, and beside it a file whose name is a list of known link check failures. The link check itself runs a script from the scripts directory. And there is a test script that runs two test files, both under a link-check test directory: one for applying the link check and one for workflow diagnostics.

Read together, those four facts mean link checking is a tested component of the build rather than a lint that runs once and is ignored. A new external reference has to pass, and a reference that is known to be broken has to be recorded in the allowlist rather than quietly tolerated.

The allowlist is the part an adopter should notice, because it is a standing admission that some links in a document set of this age do not resolve. That is a maintenance cost the project has chosen to carry explicitly rather than by removing the check, and a contributor adding a reference inherits the obligation to keep it alive.

There is a draft directory, so content waits before it is published

Two directories sit side by side at the root: one holding the cheat sheets and one holding drafts.

The existence of a draft directory is a small thing that says a lot about how the project works. A cheat sheet is not written once and published; it is proposed, iterated on, and moved when it is good enough. That is what a contributor guide and a cheatsheet writing guideline at the root are for.

It also means the published set and the proposed set are distinguishable, and that a reader who wants to know whether a topic exists in any form should look at both. A search that finds nothing in the published set may still find a draft.

The rest of the root supports the same shape. There is a template directory, a scripts directory that holds the site generation script, a tests directory, a help guide and a preface that are part of the book rather than of the repository, an assets directory, and two site configurations, one for a different site generator than the one the build script actually calls.

Serving the site is the standard library's file server on port 8000

The build is three commands, in this order:

make install-python-requirements
make generate-site
make serve  # Binds port 8000

The first creates a virtual environment and installs pinned requirements into it. The second depends on the first and runs the site generation script from the scripts directory. The third serves the generated directory.

That third target is where the design shows. It is a single invocation of the standard library's HTTP file server against the generated site directory, and it carries a comment explaining that the virtual environment is not required for it because it is simply HTML. No web framework is involved in serving the documentation.

The same shape appears in the container build, where the entry point is that make target rather than a server command, and in the offline bundle, which is a zip of the built site. So the deliverable is static files in three forms: a website, a download, and a container.

The project moved off a wiki in 2019, and three people are thanked for it

The contributors section is split by era, and the split is the history.

The first version ran from 2014 to 2018 and was hosted on the OWASP wiki, with its own contributor file. The second version has been hosted on GitHub since 2019. A separate thanks section names three people for the migration, two of them for the same task of updating the wiki links across all the migrated cheat sheets, and one of them for years of leadership and project support in addition.

Two things follow for anyone reading or linking to this material. Links to the old wiki location are stale by construction, because the content moved and the wiki copy was not maintained afterwards. And the contributor record is split across two systems, so a count of contributors drawn from one of them understates the project's history.

There is also a trademark line at the end: the Open Worldwide Application Security Project name and the OWASP acronym are registered trademarks of the OWASP Foundation. That matters for an organisation using the name in its own materials, separately from the share-alike licence that covers the content.

Editorial conclusion

Use the OWASP Cheat Sheet Series as a reference to link to rather than a corpus to copy, because the README states plainly that the Markdown files are working sources and are not intended to be referenced in external documentation, books or websites, and because a security guide that drifts out of date in your wiki is worse than one you link to. Do not expect a packaged artefact: there are no GitHub releases, the distribution is a generated site, an offline bundle, or a container image. Before you build it: run the three make commands in order, since generating the site creates the virtual environment as a dependency, and expect a link checker to fail the build on any dead reference that is not in its known-failures list. If you want to contribute, the three routes the project names are proofreading, picking up an existing issue, and opening one, and all three start with the contribution guide and the cheatsheet writing guide.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository