Extend website

.github/workflows/deploy.yml

@@ -0,0 +1,32 @@
+name: Build and Deploy 2021
+on:
+  push:
+    branches:
+      - 'master'
+      - 'main'
+jobs:
+  build-and-deploy:
+    permissions:
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install and Build
+        run: |
+          cd 2021
+          make install-python-requirements
+          make generate-site
+      - name: Upload static files as artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 2021/site/
+      - name: Deploy
+        uses: actions/deploy-pages@v4

.github/workflows/test.yml

@@ -0,0 +1,35 @@
+name: Test 2021
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install and Build
+        run: |
+          cd 2021
+          make install-python-requirements
+          make install-python-requirements-test
+          make generate-site
+  # check-links:
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - uses: actions/setup-python@v5
+  #       with:
+  #         python-version: '3.13'
+  #     - name: Checkout
+  #       uses: actions/checkout@v4
+  #     - name: Install and Build
+  #       run: |
+  #         cd 2021
+  #         make install-python-requirements
+  #         make install-python-requirements-test
+  #         make generate-site
+  #     - name: Links validation
+  #       run: |
+  #         cd 2021
+  #         make check-links

.gitignore

@@ -90,4 +90,6 @@ lib/
 
 # Pipenv
 Pipfile
-2021/site/0x00-notice/index.html
+
+env
+venv

2021/Makefile

@@ -0,0 +1,20 @@
+.PHONY: help
+.SILENT:
+
+help:
+	@grep -E '^[a-zA-Z_-]+:.*?# .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?# "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+install-python-requirements:  # Install Python 3 required libraries
+	python -m pip install -r requirements.txt
+
+install-python-requirements-test:  # Install Python 3 required libraries
+	python -m pip install -r requirements-test.txt
+
+generate-site:  # Builds ./2021
+	mkdocs build
+
+serve:  # Build and hot-reloads ./2021
+	mkdocs serve
+
+check-links:  # Checks for dead links
+	python -m linkcheckmd

2021/README.md

@@ -4,45 +4,38 @@ Final Release
 
 ## Building a local copy
 
-- Install Python 3 for your platform
-- From the main folder, ...
+Make sure Python 3 is installed.
 
 ```bash
-make install-python-requirements
-```
-### Prepare a local virtual environment to manage the versions of the required Python libraries for mkdocs
+# Build and activate virtual environment
+python3 -m venv ./venv
+source .venv/bin/activate
 
-```bash$
-# build and activate venv
-cd 2021
-python3 -m venv .
-source ./bin/activate
-# install all required library versions
+# Install dependencies
 pip install -r requirements.txt
-# optionally verify if OWASP OSIB is in your pip list
-pip list | grep osib
-```
 
-You might need to use ```--break-system-packages``` with pip if it gives you an error.
-
-This installs all requirements including the (OSIB Macro)[https://github.com/OWASP/OSIB]
+# Build HTML
+mkdocs build
+# Browse /2021/site
+```
 
 ### Test it locally
 
-You should test your changes locally:
+Alternatively you can spin up a hot-reloading server:
 
-```bash
-cd 2021
-mkdocs serve
+```sh
+make serve
 ```
 
 Once you are happy, check in your changes as a branch / PR and let someone on the main team know. We'll review your changes, and merge and redeploy.
 
-### Redeploy to gh-pages
+### Deploy to gh-pages
 
-This only works if you have commit privileges on master and Git is correctly setup in your environment.
+When the `master` branch is pushed, a Github Action will take care of everything and publish the website as a Github Page.
 
-```bash
+Alternatively `mkdocs` can be used to publish the website. This only works if you have commit privileges on master and Git is correctly setup in your environment.
+
+```sh
 cd 2021
 mkdocs gh-deploy
 ```

2021/docs/en/0x01_2021-about-owasp.md

@@ -32,3 +32,5 @@ Come join us!
 ![license](assets/license.png)
 
 Copyright © 2003-2025 The OWASP® Foundation, Inc. This document is released under the Creative Commons Attribution Share-Alike 4.0 license. For any reuse or distribution, you must make it clear to others the license terms of this work.
+
+--8<-- "includes/abbreviations.md"

2021/docs/en/A00_2021-How_to_start_an_AppSec_program_with_the_OWASP_Top_10.md

@@ -1,4 +1,4 @@
-# How to start an AppSec Program with the OWASP Top 10 
+# How to start an AppSec Program with the OWASP Top 10
 
 Previously, the OWASP Top 10 was never designed to be the basis for an
 AppSec program. However, it's essential to start somewhere for many
@@ -113,3 +113,5 @@ going if we're ever going to get on top of appsec vulnerabilities.
     limited impact, do something different. Just because we've done
     testing like desk checks since the 1970s doesn't mean it's a good
     idea. Measure, evaluate, and then build or improve.
+
+--8<-- "includes/abbreviations.md"

2021/docs/en/A00_2021_How_to_use_the_OWASP_Top_10_as_a_standard.md

@@ -45,3 +45,5 @@ comprehensively detect, test, or protect against the OWASP Top 10 due to
 the nature of several of the OWASP Top 10 risks, with reference to
 A04:2021-Insecure Design. OWASP discourages any claims of full coverage
 of the OWASP Top 10, because it’s simply untrue.
+
+--8<-- "includes/abbreviations.md"

2021/docs/en/A00_2021_Introduction.md

@@ -116,3 +116,5 @@ The OWASP Top 10 2021 team gratefully acknowledge the financial support of Secur
 [![Secure Code Warrior](assets/securecodewarrior.png){ width="256" }](https://securecodewarrior.com)    
 
 [![Just Eats](assets/JustEat.png){ width="256" }](https://www.just-eat.co.uk/)
+
+--8<-- "includes/abbreviations.md"

2021/docs/en/A09_2021-Security_Logging_and_Monitoring_Failures.md

@@ -19,7 +19,7 @@ Insufficient Logging* to include *CWE-117 Improper Output Neutralization
 for Logs*, *CWE-223 Omission of Security-relevant Information*, and
 *CWE-532* *Insertion of Sensitive Information into Log File*.
 
-## Description 
+## Description
 
 Returning to the OWASP Top 10 2021, this category is to help detect,
 escalate, and respond to active breaches. Without logging and
@@ -54,7 +54,7 @@ events visible to a user or an attacker (see [A01:2021-Broken Access Control](A0
 
 ## How to Prevent
 
-Developers should implement some or all the following controls, 
+Developers should implement some or all the following controls,
 depending on the risk of the application:
 
 -   Ensure all login, access control, and server-side input validation

2021/docs/en/index.md

@@ -115,3 +115,5 @@ The OWASP Top 10 2021 team gratefully acknowledge the financial support of Secur
 [![Secure Code Warrior](assets/securecodewarrior.png){ width="256" }](https://securecodewarrior.com)    
 
 [![Just Eats](assets/JustEat.png){ width="256" }](https://www.just-eat.co.uk/)
+
+--8<-- "includes/abbreviations.md"

2021/docs/scripts/extra.js

@@ -0,0 +1,40 @@
+window.addEventListener("DOMContentLoaded", _ => {
+    const MutationObserver = window.MutationObserver || window.WebKitMutationObserver;
+    const observer = new MutationObserver((mutations, _) => {
+        const nodesForRemoval = [];
+        for (const record of mutations) {
+            for (const liNode of record.addedNodes) {
+                let removeNode = false;
+                for (const anchor of liNode.querySelectorAll("a")) {
+                    const searchResultLocale = getSearchResultLocaleFromAnchor(anchor);
+                    const isSearchResultFromCurrentPageLocale = searchResultLocale === document.querySelector('html[lang]').lang;
+                    if (!isSearchResultFromCurrentPageLocale) {
+                        removeNode = true;
+                        continue;
+                    }
+                }
+
+                if (removeNode) {
+                    nodesForRemoval.push(liNode);
+                }
+            }
+        }
+
+        for (const node of nodesForRemoval) {
+            node.remove();
+        }
+
+        const amountDisplay = document.querySelector(".md-search-result__meta");
+        const result = document.querySelector('.md-search-result__list').childNodes.length
+        amountDisplay.textContent = amountDisplay.textContent.replace(/\d+/i, result.toString());
+    });
+
+    observer.observe(document.querySelector(".md-search-result__list"), { childList: true });
+});
+
+function getSearchResultLocaleFromAnchor(anchor) {
+    const localeSegment = anchor.href.split("/")[3];
+    // Note that we make an assumption here that the only length 2
+    // link segments will be the locale immediately after the site's base URL.
+    return (localeSegment.length === 2 || localeSegment.length === 5 || localeSegment.length === 7) ? localeSegment : 'en';
+}

2021/docs/stylesheets/extra.css

@@ -0,0 +1,3 @@
+:root {
+    --md-text-font-family: Segoe UI,Frutiger,Frutiger Linotype,Dejavu Sans,Helvetica Neue,-apple-system,BlinkMacSystemFont,Helvetica,Arial,sans-serif;
+}

2021/includes/abbreviations.md

@@ -0,0 +1,12 @@
+*[W3C]: World Wide Web Consortium
+*[CVE]: Common Vulnerabilities and Exposures
+*[CWE]: Common Weakness Enumeration
+*[XXE]: XML External Entity
+*[XSS]: Cross Site Scripting
+*[CVSS]: Common Vulnerability Scoring System
+*[CSRF]: Cross Site Request Forgery
+*[NVD]: National Vulnerability Database
+*[GDPR]: General Data Protection Regulation
+*[ASVS]: Application Security Verification Standard
+*[QA]: Quality Assurance
+*[CSP]: Content Security Policy