OWASP Top 10: the repository builds 2021 and 2025 and nothing else

Three editions are labelled, one of them only as downloadable files

The README marks the 2025 edition as released and final, the 2021 edition as superseded, and the 2017 edition as historic. The 2025 and 2021 links point at owasp.org pages rather than into the repository, while the 2017 entry hands you a PPTX and a PDF stored in the 2017 folder. The tree goes further back: separate folders exist for 2003, 2004, 2007, 2010, 2013 and 2021-2003_Comparison, alongside archives/, generated/, osib/ and scripts/. Feedback is routed to the issue tracker on the repository. Leadership is spelled out in the README itself: five co-leaders, Andrew van der Stock, Brian Glas, Neil Smithline, Tanya Janca and Torsten Gigler. No GitHub releases exist for this repository, so those README labels are the only status markers a reader gets.

The Makefile builds two sites and serves them on two ports

The build entry point is a Makefile with a Python 3 virtual environment living at the repository root. The install target creates that environment and pulls requirements.txt into it, then the per-edition targets run mkdocs from inside each edition folder and write output to ../build/.

make install-python-requirements
make build-2021
make build-2025
make serve-2025

serve-2021 starts on localhost:8000 and serve-2025 starts on localhost:8001, and the combined serve target announces the 2021 site on localhost:8000 after running the full build. clean targets remove build/2021, build/2025 and build/ in turn. One quirk is worth knowing before you script around it: the install target tests for a file at bin/activate while the environment it creates lives in venv/ (venvdir is $(current_dir)/venv). The combined build target simply calls ./scripts/build-all.sh, so the redirect logic between editions lives in a shell script rather than in the Makefile itself.

npm test lints the 2021 folder and never touches 2025

The JavaScript side exists for linting, not for runtime. package.json declares an empty dependencies object, and the devDependencies are markdownlint-cli at ^0.26.0 plus textlint at ^11.6.3 with a terminology rule and two filter rules, one for comments and one for a whitelist. The test script chains markdown and terminology linting, and both of those scripts point at ./2021/ and nothing else:

npm run lint-markdown
npm run lint-terminology

The lint-markdown script is markdownlint ./2021/ --ignore node_modules. A separate link-check script walks the 2021 folder for markdown files and runs markdown-link-check with markdown-link-check-config.json, redirecting output into log and err, then exiting 113 when err contains an ERROR line. No script targets the 2025 folder, so the newest edition gets no markdown, terminology or link checking through npm, even though its Makefile target builds it.

requirements.txt pulls the macro plugin from git with no pins

The Python side of the build is a bare requirements list with no version constraints at all. The whole file is short enough to reproduce exactly:

requests
feedgen
wheel
mkdocs
mkdocs-material
pymdown-extensions
Pygments
mkdocs-static-i18n[material]
mkdocs-macros-plugin
dacite
git+https://github.com/OWASP/OSIB.git#subdirectory=mkdocs_macro_osib_package

The install target runs python3 -m pip install -r requirements.txt inside that virtual environment. The final entry is the one that shapes your setup most, because it is not a package index reference: it points at the OWASP/OSIB repository and asks for the mkdocs_macro_osib_package subdirectory. A build therefore depends on the current head of an unrelated repository at the moment you install, and an environment you reproduce later can differ from the one you validated. Because nothing is pinned, a fresh install can also resolve a newer mkdocs release than the committed documentation was written against.

Three site generators and two linters share one tree

The root holds configuration for several toolchains at once. mkdocs.yml drives the mkdocs builds that the Makefile calls, while _config.yml is a Jekyll style configuration and book.json is a GitBook style file, both of which sit beside the mkdocs one. A Project.code-workspace file targets the editor, and .markdownlint.json and .textlintrc hold the two linter configurations that the npm scripts read. The presence of four separate configuration formats in a single root is a maintenance cost rather than a feature, since a change to document structure has to be reflected in more than one of them. Governance and process files sit alongside them: CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, Preface.md, Index.md and a REORGANIZATION-2025.md.

package.json names an index.js that the tree does not contain

The manifest declares a main entry of index.js and a package name of owasptop10 at version 1.0.0, described as an OWASP CSS Project. There is no index.js anywhere in the top-level listing, and with an empty dependencies object there is nothing for a consumer to import. This manifest exists to drive the linters, not to be installed as a package. The license field is worth attention because it does not line up with the repository metadata: package.json declares CC-BY-SA-4.0, while GitHub's metadata reports the licence as NOASSERTION even though a LICENSE file sits at the root. If you plan to republish text from these documents, resolve that mismatch first rather than assuming the manifest value settles it.

No target rebuilds the 2003 through 2017 editions

The gaps in the build are where this repository stops being usable as a source. There are build targets for 2021 and 2025, and the earlier editions sit in their own year folders with no target of any kind, so the 2017 PPTX and PDF are distributed as finished files and the 2003, 2004, 2007, 2010 and 2013 content cannot be rebuilt from this tree at all. The 2021-2003_Comparison folder has the same problem. The npm tooling repeats the pattern from the other direction, since the terminology, markdown and link checks all read the 2021 folder only. In short, the repository is a publishing pipeline for two editions with the older ones preserved as static artifacts.

There is no runtime library here to import

Set expectations before you clone it. The primary language is HTML and the package manifest has no runtime dependencies, so nothing in this repository scans an application, checks a running service, or produces a report about your own code. What you get is document sources, a mkdocs build, two linters and a link checker. If your goal is to measure a codebase against the Top 10 categories, this is the wrong place, and the project page linked from the README is where the rest of the program lives. If your goal is to quote the categories, translate the text, or restate a definition in your own compliance documentation, then the 2025 and 2021 source folders are exactly what you want, and the 2021-2003_Comparison folder sits alongside them.

Editorial conclusion

Use this repository when you want the 2025 or 2021 document sources, the 2017 slide deck and PDF, or the 2021 to 2003 comparison, and you are willing to install a mkdocs toolchain plus a plugin fetched from git. Before depending on it, check whether your target edition has a build target, whether you accept unpinned Python packages, and whether the CC-BY-SA-4.0 declaration in package.json matches how you intend to redistribute the text.

Frequently asked questions

Official sources

1. Issues
2. OWASP/Top10 on GitHub
3. README