Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 87 additions & 0 deletions .github/workflows/docs-quality.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
name: Documentation Quality

on:
pull_request:
paths:
- "docs/**"
- "*.md"
- "tests/README.md"
- "scripts/*.md"
- "scripts/check-*.py"
- ".github/workflows/docs-quality.yml"
- ".markdownlint-cli2.yaml"
- "cspell.json"
- "lychee.toml"
- "requirements-test.txt"
- "pytest.ini"
push:
branches: [main]
paths:
- "docs/**"
- "*.md"
- "tests/README.md"
- "scripts/*.md"
- "scripts/check-*.py"
- ".github/workflows/docs-quality.yml"

permissions:
contents: read

jobs:
markdown-lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: DavidAnson/markdownlint-cli2-action@v19
with:
globs: |
**/*.md
!venv/**
!.venv/**
!node_modules/**
!site/**
!docs/tmp/**

link-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check external links
uses: lycheeverse/lychee-action@v2
with:
args: --config lychee.toml --no-progress .
fail: true
jobSummary: true

spell-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check spelling
uses: streetsidesoftware/cspell-action@v6
with:
config: cspell.json
files: "**/*.md"
inline: error
incremental_files_only: false
strict: true

validate-codeblocks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Validate Python code blocks in markdown
run: python3 scripts/check-codeblocks.py

check-doc-coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Check documentation covers all routes and modules
run: python3 scripts/check-doc-coverage.py
46 changes: 14 additions & 32 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -1,59 +1,41 @@
name: Deploy MkDocs to GitHub Pages
name: Deploy Documentation

on:
push:
branches:
- main
- 'feature/**'
paths:
- 'docs/**'
- 'mkdocs.yml'
- '.github/workflows/docs.yml'
pull_request:
branches:
- main
paths:
- 'docs/**'
- 'mkdocs.yml'
- '.github/workflows/docs.yml'
- "docs/**"
- "mkdocs.yml"
- ".github/workflows/docs.yml"

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: "pages"
group: pages
cancel-in-progress: false

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Set up Python
uses: actions/setup-python@v5
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'

- name: Install dependencies
run: pip install mkdocs mkdocs-material

- name: Build site
run: mkdocs build

- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v3
python-version: "3.11"
- run: pip install mkdocs-material mkdocstrings mkdocstrings-python pymdown-extensions
- run: python3 scripts/sync-docs.py
- run: mkdocs build --site-dir site
- uses: actions/upload-pages-artifact@v3
with:
path: site

deploy:
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
Expand Down
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ tmp/
docs/tmp/
CTFd-Docker-Challenges/

# MkDocs build output
site/

# Database
instance/
uploads/
Expand All @@ -34,4 +37,7 @@ catering_sql_lab.db
.commandcode/
site/

# Command Code (AI coding assistant state)
.commandcode/

# Core maintainers only: optional commit-msg in .git/hooks/ (local-only, never pushed).
41 changes: 41 additions & 0 deletions .markdownlint-cli2.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Markdownlint configuration for PwnzzAI docs
# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md

default: true

# Allow inline HTML (needed for <img>, <a>, <video> embeds)
MD033: false

# Allow line length (URLs and table rows exceed 80 chars)
MD013: false

# Allow duplicate headings (labs reuse "Overview", "Setup")
MD024: false

# Allow bare URLs without angle brackets
MD034: false

# Allow emphasis used instead of heading
MD036: false

# Allow trailing punctuation in headings ("Why?")
MD026: false

# Allow first line not being H1
MD041: false

# Allow code blocks without language spec
MD040: false

# Allow dollar signs in code blocks (command examples)
MD014: false

# Allow spaces after hash for atx-style headings
MD019: false
MD021: false

# Allow underscore in filenames (doc_standards.md)
MD045: false

# Allow indented code blocks (some legacy)
MD046: false
42 changes: 40 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contributing to PwnzzAI Shop

Thank you for your interest in contributing to PwnzzAI Shop! This project aims to educate developers about LLM security vulnerabilities through practical, hands-on examples. We welcome contributions that enhance the educational value and quality of this project.

Check failure on line 3 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Line length

CONTRIBUTING.md:3:81 MD013/line-length Line length [Expected: 80; Actual: 262] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md013.md

## Table of Contents

Expand All @@ -10,14 +10,14 @@
- [Development Setup](#development-setup)
- [Coding Standards](#coding-standards)
- [Testing](#testing)
- [Docker Smoke Tests](#docker-smoke-tests)

Check failure on line 13 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Unordered list indentation

CONTRIBUTING.md:13:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 3] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md007.md
- [Submitting Changes](#submitting-changes)
- [Reporting Issues](#reporting-issues)
- [Security Considerations](#security-considerations)

## Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment. Be kind, professional, and considerate in all interactions.

Check failure on line 20 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Line length

CONTRIBUTING.md:20:81 MD013/line-length Line length [Expected: 80; Actual: 155] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md013.md

## Ways to Contribute

Expand All @@ -27,7 +27,7 @@
- **New Vulnerabilities**: Add demonstrations of additional LLM vulnerabilities
- **Documentation**: Improve explanations, tutorials, or documentation
- **Test Coverage**: Add or improve test cases
- **Security Mitigations**: Enhance security soutions in the mitigation strategies sections
- **Security Mitigations**: Enhance security solutions in the mitigation strategies sections

Check failure on line 30 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Line length

CONTRIBUTING.md:30:81 MD013/line-length Line length [Expected: 80; Actual: 92] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md013.md
- **Model Support**: Add support for additional LLM models
- **UI/UX Improvements**: Enhance the user interface or user experience
- **Code Quality**: Refactor code for better maintainability
Expand All @@ -37,20 +37,20 @@
1. **Fork the Repository**: Click the **Fork** button on the canonical repo: [https://github.com/OWASP/PwnzzAI](https://github.com/OWASP/PwnzzAI)

2. **Clone Your Fork**:
```bash

Check failure on line 40 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Fenced code blocks should be surrounded by blank lines

CONTRIBUTING.md:40 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```bash"] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md031.md
git clone https://github.com/YOUR-USERNAME/PwnzzAI.git
cd PwnzzAI
```

3. **Add Upstream Remote** (track the canonical OWASP project):
```bash

Check failure on line 46 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Fenced code blocks should be surrounded by blank lines

CONTRIBUTING.md:46 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```bash"] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md031.md
git remote add upstream https://github.com/OWASP/PwnzzAI.git
```

If your GitHub fork still shows the **old parent repository**, GitHub will not let you open a pull request into **OWASP/PwnzzAI** from that fork. Fix it by **forking again from [OWASP/PwnzzAI](https://github.com/OWASP/PwnzzAI)** (or asking an org admin to **re-parent** your existing fork), then add a second remote (for example `origin` → your fork, `upstream` → OWASP) and push your topic branch there before opening the PR.

Check failure on line 50 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Line length

CONTRIBUTING.md:50:81 MD013/line-length Line length [Expected: 80; Actual: 429] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md013.md

4. **Create a Branch**:
```bash

Check failure on line 53 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Fenced code blocks should be surrounded by blank lines

CONTRIBUTING.md:53 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```bash"] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md031.md
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
Expand All @@ -67,13 +67,13 @@
### Local Setup

1. **Create a Virtual Environment**:
```bash

Check failure on line 70 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Fenced code blocks should be surrounded by blank lines

CONTRIBUTING.md:70 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```bash"] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md031.md
python -m venv venv

Check failure on line 71 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / spell-check

Unknown word (venv)

Check failure on line 71 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / spell-check

Unknown word (venv)
source venv/bin/activate # On Windows: venv\Scripts\activate

Check failure on line 72 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / spell-check

Unknown word (venv)

Check failure on line 72 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / spell-check

Unknown word (venv)
```

2. **Install Dependencies**:
```bash

Check failure on line 76 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Fenced code blocks should be surrounded by blank lines

CONTRIBUTING.md:76 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```bash"] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md031.md
pip install -r requirements.txt
pip install -r requirements-test.txt
```
Expand All @@ -81,11 +81,11 @@
3. **Install System Dependencies** (if needed for testing):
```bash
sudo apt-get update
sudo apt-get install -y libzbar0

Check failure on line 84 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / spell-check

Unknown word (libzbar)
```.

4. **Configure Environment**:
- Copy `.flaskenv` if needed

Check failure on line 88 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / spell-check

Unknown word (flaskenv)

## Testing

Expand Down Expand Up @@ -118,4 +118,42 @@
APP_IMAGE=pwnzzai:my-local-test ./scripts/docker-smoke-test.sh
```

The script cleans up test containers automatically when it exits.
The script cleans up test containers automatically when it exits.

## Coding Standards

- Follow [PEP 8](https://peps.python.org/pep-0008/) with a soft 100-character line limit.
- Use meaningful variable and function names.
- Add type hints to function signatures where practical.
- Write docstrings for public functions and classes.

Check failure on line 128 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / spell-check

Unknown word (docstrings)
- Use `snake_case` for variables and functions, `PascalCase` for classes.
- Keep functions small and single-purpose.
- Avoid adding comments that describe what the code does — let the code speak for itself. Use comments only for non-obvious intent.

For docs contributions, see [Doc Standards](docs/community/doc-standards.md).

## Submitting Changes

1. Ensure all tests pass: `pytest -v`
2. Run the Docker smoke test if you changed infrastructure: `./scripts/docker-smoke-test.sh`
3. Rebase your branch onto the latest `main` before opening a PR
4. Write a clear PR title and description
5. Reference any related issues in the PR body
6. Keep PRs focused — one change per PR

## Reporting Issues

Use GitHub Issues to report bugs, suggest features, or ask questions.

- **Bug report**: Include steps to reproduce, expected vs actual behavior, and your environment (OS, Python version, Docker version)
- **Feature request**: Describe the problem you're solving and how your suggestion helps
- **Question**: Use the [OWASP AI Exchange Discussions](https://github.com/OWASP/PwnzzAI/discussions)

## Security Considerations

This project contains intentional vulnerabilities for educational purposes.

- **Never** submit a PR that fixes a documented lab vulnerability without prior discussion — these are features
- New vulnerability contributions must include a hardened alternative (mode flag or separate endpoint)
- Do not commit real API keys, credentials, or PII — use example values
- If you discover an accidental vulnerability that is not part of the curriculum, follow the [Responsible Disclosure](docs/security/disclosure.md) process
51 changes: 51 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ PWNZZAI_IMAGE ?= ghcr.io/owasp/pwnzzai:latest
LOCAL_IMAGE ?= pwnzzai-local:dev
TEST_IMAGE ?= pwnzzai:test-ci
APP_PORT ?= 8080
DOCS_SITE_DIR ?= site
OLLAMA_MODEL ?= llama3.2:1b

export FLASK_APP ?= main.py
Expand Down Expand Up @@ -361,3 +362,53 @@ register-challenge-py: ## python3 deploy/register_pwnzzai_challenge.py (env from
.PHONY: reregister-challenge-py
reregister-challenge-py: ## python3 deploy/reregister_pwnzzai_challenge.py
python3 deploy/reregister_pwnzzai_challenge.py

# =============================================================================
# Documentation (MkDocs)
# =============================================================================

.PHONY: sync-docs
sync-docs: ## Copy canonical files into docs/ before build (single source of truth)
python3 scripts/sync-docs.py

.PHONY: docs
docs: sync-docs ## Build MkDocs site (runs sync-docs first)
mkdocs build --site-dir $(DOCS_SITE_DIR)

.PHONY: docs-serve
docs-serve: sync-docs ## Serve MkDocs locally with live reload (runs sync-docs first)
mkdocs serve

# =============================================================================
# Documentation Quality (local)
# =============================================================================

.PHONY: install-docs-qa
install-docs-qa: ## Install doc quality tools (pytest-codeblocks)
"$(PYTHON)" -m pip install pytest-codeblocks

.PHONY: check-codeblocks
check-codeblocks: ## Validate Python code blocks in documentation (scripts/check-codeblocks.py)
python3 scripts/check-codeblocks.py

.PHONY: check-doc-coverage
check-doc-coverage: ## Check all routes and vulnerability modules are documented (scripts/check-doc-coverage.py)
python3 scripts/check-doc-coverage.py

.PHONY: check-links
check-links: ## Check external links in markdown (requires lychee, or runs in CI)
@if command -v lychee >/dev/null 2>&1; then lychee --config lychee.toml .; \
else printf '%s\n' "lychee not found. Install: cargo install lychee, or let CI run this check." >&2; fi

.PHONY: check-spelling
check-spelling: ## Spell-check docs (requires cspell, or runs in CI)
@if command -v cspell >/dev/null 2>&1; then cspell --config cspell.json "**/*.md" --no-summary; \
else printf '%s\n' "cspell not found. Install: npm install -g cspell, or let CI run this check." >&2; fi

.PHONY: check-markdown
check-markdown: ## Lint markdown style (requires markdownlint-cli2, or runs in CI)
@if command -v markdownlint-cli2 >/dev/null 2>&1; then markdownlint-cli2 "**/*.md" "#venv" "#.venv" "#node_modules" "#site" "#docs/tmp"; \
else printf '%s\n' "markdownlint-cli2 not found. Install: npm install -g markdownlint-cli2, or let CI run this check." >&2; fi

.PHONY: check-docs
check-docs: check-markdown check-links check-spelling check-codeblocks check-doc-coverage ## Run all doc quality checks (best-effort locally, authoritative in CI)
25 changes: 23 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Here, you'll explore **practical examples** of how vulnerabilities are created,
- [Option 2: Docker (Your Own Ollama + PwnzzAI Image)](#option-2-docker-your-own-ollama--pwnzzai-image)
- [Option 3: Run Source Code Yourself](#option-3-run-source-code-yourself)
- [Troubleshooting: Ollama Connection (WSL + Docker)](OLLAMA_CONNECTION_TROUBLESHOOTING.md)
- [Workshop hosts: choosing OpenAI, Claude, Gemini, or other cloud models](docs/workshop-cloud-llm-setup.md)
- [Workshop hosts: choosing OpenAI, Claude, Gemini, or other cloud models](docs/ops/cloud-setup.md)
- [Features](#features)
- [AI Security Coverage](#ai-security-coverage)
- [Learning Framework](#learning-framework)
Expand Down Expand Up @@ -79,7 +79,7 @@ cp .env.example .env
# (or LITELLM_MODEL=gemini/gemini-2.5-flash, etc.)
```

Restart the app after editing `.env`. For a full provider/model walkthrough, see [Workshop hosts: choosing OpenAI, Claude, Gemini, or other cloud models](docs/workshop-cloud-llm-setup.md).
Restart the app after editing `.env`. For a full provider/model walkthrough, see [Workshop hosts: choosing OpenAI, Claude, Gemini, or other cloud models](docs/ops/cloud-setup.md).

### Option 1: Docker (PwnzzAI + Ollama)

Expand Down Expand Up @@ -335,4 +335,25 @@ and,
- **Ollama Models**: Free models, such as Mistral 7B and LLaMA 3.2 1B, are accessible through Ollama.


## Documentation

Full MkDocs site in `docs/` (built with Material theme, Mermaid diagrams, mkdocstrings).

**Single source of truth rule:** content lives in one place — root files (`README.md`, `CONTRIBUTING.md`, `OLLAMA_CONNECTION_TROUBLESHOOTING.md`, `tests/README.md`, `.env.example`) are the canonical versions. Copying into `docs/` happens automatically before every build via:

```bash
make docs # sync + mkdocs build
make docs-serve # sync + mkdocs serve
```

Available docs:

- **[Architecture](docs/ARCHITECTURE.md)** — System design, module dependencies, request lifecycle (Mermaid diagrams)
- **[API Reference](docs/API_REFERENCE.md)** — Complete endpoint documentation with request/response formats
- **[Developer Guide](docs/DEVELOPER_GUIDE.md)** — Adding new vulnerabilities, doc workflow, coding conventions
- **[Escalation Ladder](docs/ESCALATION_LADDER.md)** — B0–B9 prompt injection stages, defense techniques
- **[Environment Variables](docs/ENVIRONMENT_VARIABLES.md)** — Precedence chains for all config vars
- **[Challenge Solutions](docs/CHALLENGE_SOLUTIONS.md)** — Walkthrough scaffold for all challenges
- **[Cloud LLM Setup](docs/ops/cloud-setup.md)** — Workshop provider configuration

**⚠️ Educational Purpose Only**: This application contains intentional security vulnerabilities. Do not use in production environments.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading