OWASP Top 10: What the Official Document Repository Actually Contains

What the OWASP Top 10 repository is, and what it is not

This is the document repository for the OWASP Top 10, the awareness document that lists the most critical web application security risks. The README opens with a single line describing it as the "Official OWASP Top 10 Document Repository", and the directory listing backs that up: numbered folders from 2003 through 2025, plus archives, generated output and scripts. If you came looking for a library that flags vulnerabilities in your code, this is the wrong repository. There is no scanning code here. What you get is the source text of each edition, the MkDocs configuration that renders it, and the contribution process around it.

The audience is narrower than the name suggests. Application security engineers use it to cite the current list in threat models and review checklists. Translators and reviewers use it to correct wording. Framework authors use it as the mapping target when they label a rule as covering a Top 10 category. All three groups need the text, not a runtime.

Editions, directories and the 2025 release

The README states that the OWASP Top 10:2025 has been released as final, linking to the published site. It labels the 2021 edition as superseded and the 2017 edition as historic, with the 2017 material still present as PPTX and PDF files under the 2017 directory. Older editions going back to 2003 sit in their own numbered folders, and a 2021-2003_Comparison directory exists for cross-edition work.

That layout matters more than it first appears. Because every edition keeps its own directory, a mapping that says "A03:2021" stays traceable after the list changes. The repository also carries a REORGANIZATION-2025.md file at the top level, which indicates the 2025 restructuring was documented rather than done silently. If you maintain mappings across editions, that file is worth reading before you assume a category kept its meaning.

How the site is built: MkDocs, a Makefile and a Python venv

The build is a static site pipeline. The Makefile defines a venv directory, an activate target, and per-edition build and serve targets. The Python dependencies in requirements.txt include mkdocs, mkdocs-material, mkdocs-static-i18n with the material extra, mkdocs-macros-plugin, dacite, pymdown-extensions and Pygments. Two entries are less common: feedgen, which suggests feed generation, and a direct Git dependency on the OWASP OSIB package installed from a subdirectory of the OWASP/OSIB repository. That last line means a build is not fully reproducible from PyPI alone; it pulls code from another OWASP repository at install time.

On the JavaScript side, package.json declares no runtime dependencies and only lint tooling as devDependencies: markdownlint-cli, textlint, two textlint filter rules and textlint-rule-terminology. The test script runs markdown linting and terminology linting, and both point at the 2021 directory. The link-check script walks the 2021 markdown files with markdown-link-check and exits non-zero when the error log contains "ERROR:". Note that these npm scripts are scoped to 2021, so they do not validate the 2025 content as written.

Installing it and building the 2025 site locally

The Makefile is the entry point. Its help target prints every documented target, so start there rather than guessing. The install target creates a Python virtual environment in a venv directory next to the Makefile if one does not already exist, then upgrades pip and installs requirements.txt inside it.

make help
make install-python-requirements

After the install finishes you should have a venv directory containing the MkDocs toolchain. From there you can build a single edition. The build-2025 target activates the venv, changes into the 2025 directory and runs mkdocs build with the output written to build/2025.

make build-2025

The generated static site lands under build/2025. To preview instead of building, the serve-2025 target runs mkdocs serve bound to localhost:8001, while serve-2021 uses localhost:8000. Running make serve builds both sites first and then reports a server on http://localhost:8000.

make serve-2025

If you only want the published text and not a local build, the README points at the hosted editions instead: the 2025 and 2021 links on owasp.org, and the 2017 PPTX and PDF files in the repository. For most readers that is the faster path.

The build has moving parts that the README does not cover

Two things stand out as real friction. First, the requirements.txt line that installs from git+https://github.com/OWASP/OSIB.git#subdirectory=mkdocs_macro_osib_package means your build depends on a second repository's default branch at the moment you install. There is no version pin in that line, so a change upstream can alter your build without any change in this repository. If you need a repeatable build, that is the line to pin.

Second, the lint and link-check scripts in package.json target ./2021/ explicitly. The README does not document equivalent checks for the 2025 directory. Whether that is an oversight or a deliberate staging decision is not stated. Either way, do not assume that a passing npm test validates the current edition.

The third limitation is conceptual. The Top 10 is an awareness document, and the README describes it as such. It is not a testable standard with pass and fail criteria per item, and the repository does not pretend otherwise. Teams that need prescriptive, verifiable requirements are looking at the wrong artifact, and no amount of tooling in this repository changes that.

Alternatives and how they differ in approach

The closest alternative is the OWASP Application Security Verification Standard, which takes the opposite approach: instead of ten broad risk categories, it defines numbered, verifiable requirements at several assurance levels. A team that needs to write acceptance criteria for a release can use ASVS requirements directly; the Top 10 gives categories that still require interpretation. Many organisations use both, mapping ASVS requirements back to Top 10 categories for reporting.

A second alternative is the OWASP OSIB package, which this repository already consumes as a build dependency. If your goal is generating structured output from OWASP content rather than rendering the Top 10 site, working with OSIB directly is closer to the source of that capability than forking this repository. The difference is one of purpose: this repository publishes a document, OSIB is the machinery it borrows.

Maintenance, licence and the cost of tracking editions

The repository is not archived and the last push was on 2026-09-10, so the project is still receiving changes. Maintenance cost for a consumer is low if you only read the published site, and moderate if you build locally, because the unpinned git dependency and the Python toolchain both need attention over time. The Makefile offers clean-2021, clean-2025 and clean-all targets, which keeps build output from accumulating.

The licensing picture needs care. The LICENSE file exists at the top level, and package.json declares "license": "CC-BY-SA-4.0". The repository metadata reports the licence as NOASSERTION, which typically means an automated classifier could not match the file to a known template. The README does not discuss reuse terms at all. If you plan to redistribute the text, read LICENSE itself; CC-BY-SA-4.0 as declared in package.json carries attribution and share-alike conditions, but that field is not the licence file and the two should not be treated as interchangeable. This is a description of what the repository states, not legal advice.

Editorial conclusion

Adopt this repository if you need the authoritative text, translations or build tooling behind the OWASP Top 10, or if you are contributing corrections through GitHub issues. Do not adopt it expecting a scanning engine or a machine-readable control catalog; the repository is prose plus a static site generator. Before relying on it, verify which edition your process references, confirm that the 2025 directory builds with the pinned requirements.txt, and read LICENSE rather than trusting the package.json field, which states CC-BY-SA-4.0 while the repository license is reported as NOASSERTION.

Frequently asked questions

Official sources

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