INSTALLATION GUIDE

Install WAFPass

Complete installation guide for WAFPass CLI, Server, and Dashboard — from a single pip install to a full Docker Compose stack.

THE STACK

Three components. One compliance workflow.

Install just the CLI for CI/CD pipelines, or add the server and dashboard for persistent history and visual exploration.

wafpass CLI

Core evaluation engine. Parses Terraform and AWS CDK, runs in any CI/CD pipeline. No cloud credentials needed.

PyPI: wafpass-core

wafpass-server

FastAPI REST API with PostgreSQL. Stores runs, waivers, risk acceptances, secrets findings, and full audit events.

PyPI: wafpass-server

wafpass-dashboard

React web dashboard. 22+ pages of compliance exploration, auditor-ready evidence export, and RBAC role management.

React + Vite
OPTION A — RECOMMENDED

Docker Compose: Full Stack

The waf++ monorepo ships a unified docker-compose.yml. Clone once, configure your .env, and bring up the entire stack in a single command.

bash
$ git clone https://github.com/WAF2p/pass.git
$ cd pass
$ cp .env.example .env
$ # Edit .env — set POSTGRES_PASSWORD, WAFPASS_JWT_SECRET, etc.
$ docker compose up -d
Services after startup
Service URL Description
wafpass-dashboard http://localhost:3000 React dashboard
wafpass-server http://localhost:8000 FastAPI REST API
Keycloak (SSO) http://localhost:8080 Identity provider (admin / admin)
postgres localhost:5432 PostgreSQL database

Push your first scan result:

bash
$ wafpass check ./infra/ --output json
$ wafpass check ./infra/ --output json | curl -s -X POST http://localhost:8000/runs \
-H "Content-Type: application/json" -d @-
View full docker-compose.yml
services:

  # ── PostgreSQL ────────────────────────────────────────────
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER:     ${POSTGRES_USER:-wafpass}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-wafpass}
      POSTGRES_DB:       ${POSTGRES_DB:-wafpass}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./keycloak/init.sql:/docker-entrypoint-initdb.d/01-keycloak-db.sql:ro
    ports:
      - "${POSTGRES_PORT:-5432}:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-wafpass} -d ${POSTGRES_DB:-wafpass}"]
      interval: 5s
      timeout: 5s
      retries: 10

  # ── wafpass-server ────────────────────────────────────────
  wafpass-server:
    build:
      context: .
      dockerfile: wafpass-server/Dockerfile
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL:               postgresql+asyncpg://${POSTGRES_USER:-wafpass}:${POSTGRES_PASSWORD:-wafpass}@postgres:5432/${POSTGRES_DB:-wafpass}
      WAFPASS_ENV:                ${WAFPASS_ENV:-local}
      CORS_ORIGINS:               ${API_URL:-http://localhost:3000},http://wafpass-dashboard,http://cloud.waf2p
      WAFPASS_CONTROLS_DIR:       ${WAFPASS_CONTROLS_DIR:-/app/controls}
      WAFPASS_JWT_SECRET:         ${WAFPASS_JWT_SECRET:-change-me-in-production}
      WAFPASS_JWT_EXPIRE_MINUTES: ${WAFPASS_JWT_EXPIRE_MINUTES:-60}
      WAFPASS_JWT_REFRESH_DAYS:   ${WAFPASS_JWT_REFRESH_DAYS:-7}
      WAFPASS_ADMIN_USERNAME:     ${WAFPASS_ADMIN_USERNAME:-admin}
      WAFPASS_ADMIN_PASSWORD:     ${WAFPASS_ADMIN_PASSWORD:-admin}
      WAFPASS_ADMIN_ROLE:         ${WAFPASS_ADMIN_ROLE:-admin}
      WAFPASS_API_KEY:            ${WAFPASS_API_KEY:-key}
    ports:
      - "8000:8000"

  # ── Keycloak (SSO / IdP — dev mode) ──────────────────────
  keycloak:
    image: quay.io/keycloak/keycloak:26.1
    command: start-dev
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      KC_DB:                   postgres
      KC_DB_URL:               jdbc:postgresql://postgres:5432/${KEYCLOAK_DB:-keycloak}
      KC_DB_USERNAME:          ${KEYCLOAK_DB_USER:-keycloak}
      KC_DB_PASSWORD:          ${KEYCLOAK_DB_PASSWORD:-keycloak}
      KEYCLOAK_ADMIN:          ${KEYCLOAK_ADMIN_USER:-admin}
      KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD:-admin}
      KC_HTTP_ENABLED:         "true"
      KC_HOSTNAME_STRICT:      "false"
      KC_HEALTH_ENABLED:       "true"
    ports:
      - "${KEYCLOAK_PORT:-8080}:8080"
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:8080/health/ready || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 20
      start_period: 60s

  # ── wafpass-dashboard ─────────────────────────────────────
  wafpass-dashboard:
    build:
      context: ./wafpass-dashboard
      dockerfile: Dockerfile
    restart: unless-stopped
    depends_on:
      - wafpass-server
    ports:
      - "3000:80"

volumes:
  postgres_data:
OPTION B — FLEXIBLE

Install Components Individually

Install only what you need. Start with the CLI for immediate CI/CD integration, then add server and dashboard when you're ready for persistent history and visual compliance exploration.

1

Install wafpass CLI

The core evaluation engine — parse IaC, evaluate controls, generate reports

From PyPI (recommended)

bash
$ pip install wafpass-core
$ uv add wafpass-core # recommended for Python projects

From source

bash
$ git clone https://github.com/WAF2p/pass.git
$ cd pass
$ uv pip install -e . # recommended
$ pip install -e ".[pdf]" # with PDF report support
$ pip install -e ".[dev]" # with dev dependencies

macOS (Apple M-series)

bash
$ brew install git python uv
$ git clone https://github.com/WAF2p/pass.git && cd pass
$ uv pip install -e .
$ wafpass --version # verify installation
2

Install wafpass-server

FastAPI persistence layer — stores runs, waivers, secrets findings, and audit events

From PyPI (recommended)

bash
$ pip install wafpass-server
$ uv add wafpass-server # recommended for Python projects

Configure & start

bash
$ cp .env.example .env # set DATABASE_URL and JWT secret
$ alembic upgrade head # apply database migrations
$ uvicorn wafpass_server.main:app --reload --port 8000

API docs available at http://localhost:8000/api/docs

3

Install wafpass-dashboard

React web dashboard — 22+ compliance views, evidence export, RBAC

bash
$ git clone https://github.com/WAF2p/wafpass-dashboard.git
$ cd wafpass-dashboard
$ npm install
$ cp .env.example .env.local # set VITE_API_URL
$ npm run dev # dev server at http://localhost:5173
$ npm run build # production build
PRE-COMMIT HOOK

Block non-compliant commits.

WAFPass ships a pre-commit hook that runs compliance checks before every git commit. Non-compliant commits are blocked automatically — no cloud call, no extra CI wait.

Works on macOS, Linux, and Windows (Git Bash / PowerShell).

One-time setup

bash
$ bash hooks/install.sh # macOS / Linux / Git Bash
$ .\hooks\install.ps1 # Windows PowerShell
POST-INSTALLATION

Get up and running.

Download controls, run your first scan, and open the dashboard to explore your compliance posture.

1. Download Controls

WAF++ controls are published separately and downloaded on demand.

  1. Visit waf2p.dev/wafpass/
  2. Click Download Controls
  3. Extract to your controls directory
bash
$ git clone https://github.com/WAF2p/framework.git
$ cp framework/modules/controls/controls/*.yml controls/

2. Run Your First Scan

Point WAFPass at your Terraform or CDK code and get a full compliance report.

bash
$ wafpass check ./infra/
$ wafpass check ./infra/ --output pdf \
--pdf-out report.pdf

3. Open the Dashboard

Explore your compliance posture, manage waivers, and export evidence packages.

  1. Open localhost:3000 (Docker) or localhost:5173 (dev)
  2. Login with admin credentials from your .env
  3. Explore findings, drift, and compliance matrix
TROUBLESHOOTING

Common issues & fixes.

Quick answers to the most frequent setup problems.

Controls not found

If wafpass check reports "controls directory not found", the CLI will display download instructions automatically. Follow the post-installation steps above.

Port already in use

Use a different port for the server or dashboard:

$ uvicorn wafpass_server.main:app --port 8001
$ npm run dev -- --port 5174

Database connection errors

Verify PostgreSQL is running and your DATABASE_URL is correct:

$ psql $DATABASE_URL -c "SELECT 1"

Docker build fails

Ensure all three repositories are cloned side-by-side in the same parent directory:

$ ls -1
pass/
wafpass-server/
wafpass-dashboard/
NEXT STEPS

Ready to validate your infrastructure?

Download the WAF++ controls, run WAFPass against your Terraform or CDK code, and get a full compliance report in minutes.

GDPR SOC 2 HIPAA BSI C5 ISO 27001 NIS2
COMING SOON · 12 MAY 2026
WAF++ 1.0
incl. WAFPass 1.0

The first stable release of the WAF++ Framework and WAFPass CLI.

Launching on the pre-eve of Cloud Native Conference DE12 May 2026 · 20:00 CEST