How assured/wstg works
Project type and purpose
• This is a documentation‐centric repository that powers the OWASP Web Security Testing Guide (WSTG).
• It isn’t a “running” full‐stack app; rather it’s a static‐site and multi‐format build pipeline for a large body of Markdown content.
• Purpose: maintain and publish the WSTG as HTML (via GitHub Pages), PDF, and machine‐readable JSON.
File structure
• Top‐level content directories:
• document/ – the core guide content in Markdown, organized by chapters and sections
• checklist/ – JSON and Excel assets for the WSTG checklist
• template/ – sample testing templates
• Configuration and build orchestrators:
• .devcontainer/ – Dockerfile and VS Code devcontainer.json for local development
• .github/ – CI/CD workflows, linting configs, PDF/JSON build scripts, and www site artifacts
• Build metadata: package.json, style_guide.md, Testing_for_APIs.md
• Key patterns: single “monorepo” holding source content + CI/CD code + output artifacts, using scripts and containers for reproducible builds.
README for additional insights
• Describes the guide’s purpose, versioning scheme, linking conventions, contribution instructions.
• Mentions that releases produce HTML, PDF, and JSON outputs (via GitHub Actions).
• No “runtime” components: it’s purely a content publication pipeline.
Main components
a. Content Store
– Markdown files in document/, checklist/, template/
– Style guide and asset directories
b. Local Development Environment
– Developer workstation + VS Code DevContainer
– Container: Node.js, linting tools, build scripts installed
c. CI/CD Orchestrator (GitHub Actions)
– Workflows: md‑lint‑check, md‑link‑check, build‑json, build‑pdf, www‑deploy
– Triggers on push, PRs, and releases
d. Build Script Layer
– make-json.sh → converts Markdown to JSON
– make-pdf.sh → assembles PDF via pandoc/PrinceXML or similar
– NPM scripts invoked by workflows
e. Artifact Repository / Deployment
– .github/www/ → static HTML fragments for GitHub Pages
– PDF files stored in release assets
– JSON published for machine consumption or API use
f. External Services
– GitHub (repo, Actions, Pages)
– Slack/Google Groups for chat
– npm registry (if any dependencies)
Relationships and interactions
1. Author edits Markdown locally (DevContainer) → commits to GitHub
2. GitHub Actions pick up changes → run linting workflows → fail fast on errors
3. On successful checks or tagged release → run build-json and build-pdf
4. Generated JSON and PDF pushed to release assets
5. Static site content (.github/www) updated and deployed to GitHub Pages
Architectural patterns and design principles
• GitOps: everything version controlled, build/deploy via code
• Containerized local dev for consistency
• Single‐source‐of‐truth for content (Markdown)
• Multi‐format derivation (JSON, PDF, HTML) via scripting layer
• Separation of concerns: content vs. linting vs. build vs. deployment
Essential elements
• Callouts for key technologies (Markdown, Docker, Node.js, GitHub Actions, pandoc/PDF tool, GitHub Pages)