OWASP VWAD - GitHub Pages

Static GitHub Pages site for the OWASP Vulnerable Web Applications Directory (VWAD) project. The site builds into _site/ as deployable static HTML, CSS, JS, and data, with dedicated app pages at /app/<slug>/ and a lightweight stdlib-only build pipeline that is easy to run and test locally.

Live Site

https://vwad.owasp.org/

Build and Preview Locally

From this directory (you should probably use a virtual environment):

Setup

# 1. Create the virtual environment (named .venv)
python3 -m venv .venv

# 2. Activate the environment
source .venv/bin/activate

# 3. Install dependencies (Pillow for logo resizing; PyGithub, requests and jsonschema for the workflow scripts) if you haven't previously
python3 -m pip install -r requirements.txt

Run Locally

source .venv/bin/activate
python3 scripts/build_site.py
python3 serve.py 8000 _site

Then open http://localhost:8000.

Deploy the _site/ output (for example via the GitHub Actions workflow). Serving the repo root without building means homepage templates still contain build placeholders (for example <!-- BUILD_APP_LOGO_PATHS -->) and the SPA will not know which bundled logo files exist, so the browser may request missing assets.

Serving Paths and URLs

• The same build works when served from /, /vwad-new/, or another subpath
• A small script derives window.VWAD_BASE from location.pathname, so data and app URLs resolve correctly without changing the built files
• Canonical app pages live at /app/<slug>/
• data/collection.json contains explicit stable slug values (the build does not add extra fields to this file)
• Legacy app/#<slug>, app/?slug=<slug>, and app/?name=<name> URLs resolve through the compatibility page at /app/

App Logos

Bundled logos for the browse table, featured card, and static app pages are discovered as files under images/app_logos/ named for each app slug (SVG preferred over same-stem PNG/JPEG when both exist). The build injects window.VWAD_APP_LOGO_PATHS (slug → relative path) into the built homepage and app compatibility page so the client only requests files that exist.

The build resizes raster logos (PNG, JPEG, WebP) in _site/images/app_logos/ to at most 144px on the longest side, without upscaling. Source files, SVGs, and animated GIFs are not resized. A skipped animated GIF, or a logo that cannot be processed, keeps its original and is reported as a non-blocking warning in the build output, generated_site_report.json, and the GitHub Actions job summary.

Site Branding Images

• images/logos/vwad-icon-bolt-400.png - 400x400 avatar (profile picture) for the VWAD GitHub organization and any related GitHub accounts. It is not referenced by the site; upload it manually in the GitHub settings.
• images/logos/og-image.png - 1200x630 social preview card (og:image and twitter:image).
• images/logos/favicon.svg, favicon-maskable.svg, apple-touch-icon.png - browser, PWA, and iOS icons.

Structure

• index.html - Homepage source template. The build injects homepage JSON-LD and replaces <!-- BUILD_APP_LOGO_PATHS --> with the logo paths script before writing _site/index.html.
• app/index.html - Compatibility redirect page for legacy app URLs; the same logo paths placeholder is filled at build time.
• data/collection.json - Source-of-truth app directory data, including required stable slug.
• data/contributors.json - Contributor data used by the homepage contributors section.
• data/archived_repos.json - Archive-status data maintained by the stats workflow.
• schema.json - Source validation schema for data/collection.json.
• requirements.txt - Python dependencies for the site build (Pillow) and the workflow scripts in .github/workflows/scripts/ (PyGithub, requests, jsonschema). Shared by all Python workflows. Kept current by Dependabot.
• scripts/build_site.py - Builds _site/, pre-renders app pages, resizes raster app logos, injects JSON-LD and inline logo metadata, writes sitemap, flattens CSS into shared and page-specific bundles under _site/css/build/, and emits generated_site_report.json.
• scripts/validate_generated_site.py - Validates generated app pages, sitemap, canonical tags, JSON-LD, and compatibility redirects.
• _site/ - Generated deploy output, including flattened shared and page-specific CSS bundles. Not committed.
• js/app.js - Loads collection data, validates explicit slugs, and exposes shared browse/app lookup and search helpers.
• js/home.js - Homepage bootstrap and browse-search orchestration for mode switching, reset behavior, and result rendering.
• js/advanced-search.js - Advanced browse-search controller, including custom multi-select filters, grouped pills, and Advanced-only UI behavior.
• js/search-options.js - Shared option definitions and label helpers used by the browse-search UI.
• js/search-table.js - Browse table rendering, sorting, sticky/scroll behavior, and table interaction helpers.
• js/theme.js - Theme toggle, system-theme syncing, and back-to-top button behavior.
• css/base.css - Shared tokens, dark-theme variables, reset/base element styles, accessibility helpers, and utilities.
• css/shell.css - Shared layout, containers, site header, project header, and common section framing.

Automation

See .github/workflows/README.md for workflow details.

The workflows most relevant to the site build and deploy path are:

• validate.yml - Validates source data/collection.json against schema.json
• validate-generated-site.yml - Builds and validates the generated _site/
• deploy-pages.yml - Rebuilds _site/ and deploys GitHub Pages from Actions on main

GitHub Pages Setting

This repo should be configured to deploy GitHub Pages from GitHub Actions, not from the branch root.

Cache Busting

The build flattens CSS into content-hashed shared and page-specific bundles under _site/css/build/, so deployed stylesheets automatically get new URLs when their contents change.

JS and Google Fonts URLs still use a manual version query parameter (?v=... or &v=...) so browsers don’t serve stale assets. Search for v= when you need to bump those.