Install WAFPass
Complete installation guide for WAFPass CLI, Server, and Dashboard — from a single pip install to a full Docker Compose stack. Validated against WAF++ v1.1 with 8 pillars and 83+ controls.
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.
Core evaluation engine. Parses Terraform and AWS CDK, runs in any CI/CD pipeline. No cloud credentials needed.
PyPI: wafpass-coreFastAPI REST API with PostgreSQL. Stores runs, waivers, risk acceptances, secrets findings, and full audit events.
PyPI: wafpass-serverReact web dashboard. 22+ pages of compliance exploration, auditor-ready evidence export, and RBAC role management.
React + ViteDocker Compose: Full Stack
The WAF2p/pass monorepo ships a unified docker-compose.yml. Clone once, configure your .env, and bring up the entire stack in a single command.
| 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:
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:
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.
The core evaluation engine — parse IaC, evaluate controls, generate reports
From PyPI (recommended)
From source
macOS (Apple M-series)
FastAPI persistence layer — stores runs, waivers, secrets findings, and audit events
From PyPI (recommended)
Configure & start
API docs available at http://localhost:8000/api/docs
React web dashboard — 22+ compliance views, evidence export, RBAC
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
Get up and running.
Download controls, run your first scan, and open the dashboard to explore your compliance posture.
WAF++ controls are published separately and downloaded on demand.
- Visit waf2p.dev/wafpass/
- Click Download Controls
- Extract to your controls directory
Point WAFPass at your Terraform or CDK code and get a full compliance report.
Explore your compliance posture, manage waivers, and export evidence packages.
- Open
localhost:3000(Docker) orlocalhost:5173(dev) - Login with admin credentials from your
.env - Explore findings, drift, and compliance matrix
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:
Database connection errors
Verify PostgreSQL is running and your DATABASE_URL is correct:
Docker build fails
Ensure all three repositories are cloned side-by-side in the same parent directory:
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.