Skip to main content

wombat-server

REST API for persisting and querying WOMBATpass scan results. Part of the Wombat framework monorepo.

Component Role
pass/ · wombat-core Compliance engine, CLI, IaC parsers ← produces results
wombat-server/ · this package FastAPI + PostgreSQL · stores results, exposes APIs
wombat-dashboard/ · React SPA Consumes this API · visualises compliance posture

BREAKING CHANGE: All API routes are now versioned under /api/v1. Update any direct callers, the dashboard, and the CLI to use paths like /api/v1/runs, /api/v1/auth/login, and /api/v1/public/badge/{project}.svg. /health, /version, and /framework-update-info.yml remain at the root.


Quick start

From the repo root:

cp .env.example .env        # fill in passwords
docker compose up --build
  • API: http://localhost:8000
  • Swagger UI: http://localhost:8000/api/v1/docs
  • Dashboard: http://localhost:3000

Local development

# Prerequisites: PostgreSQL running locally
pip install -e ".[dev]"

# Copy and edit the environment file
cp .env.example .env
# Edit .env — at minimum set DATABASE_URL to point at your local PostgreSQL instance

# Export variables into your shell (or use direnv)
export $(grep -v '^#' .env | xargs)

# Apply database migrations
alembic upgrade head

# Start server with auto-reload
uvicorn wombat_server.main:app --reload --port 8000

Environment variables

Copy .env.example to .env for local development — it contains all variables with documented defaults.

Variable Default Description
DATABASE_URL — PostgreSQL async DSN, e.g. postgresql+asyncpg://user:pass@host:5432/db
WOMBAT_ENV local Environment tag (local, staging, production)
CORS_ORIGINS http://localhost:3000 Comma-separated allowed CORS origins
WOMBAT_CONTROLS_DIR controls Path to Wombat control YAML files (used by Sandbox endpoint)
WOMBAT_JWT_SECRET change-me-… HS256 signing key for access tokens. Required in non-local environments — the server refuses to start with the default value when WOMBAT_ENV != local. Generate with openssl rand -hex 32.
WOMBAT_JWT_EXPIRE_MINUTES 60 Access token lifetime in minutes
WOMBAT_JWT_REFRESH_DAYS 7 Refresh token lifetime in days
WOMBAT_ENCRYPTION_KEY (empty) At-rest encryption key for SSO secrets (OIDC client secret, SAML2 private key). Fernet-compatible 32-byte base64 key or any passphrase (PBKDF2-derived). Required in non-local environments — without it the server derives the key from WOMBAT_JWT_SECRET, which is insecure. Generate with openssl rand -base64 32.
WOMBAT_SECRETS_BACKEND local Encryption backend for SSO secrets: local (Fernet AES), aws_sm (AWS Secrets Manager), vault_transit (HashiCorp Vault Transit)
WOMBAT_ADMIN_USERNAME admin Username for the bootstrap admin user (seeded once on first startup)
WOMBAT_ADMIN_PASSWORD (empty) Password for the bootstrap admin — set this to enable auto-seeding
WOMBAT_ADMIN_ROLE engineer Role for the bootstrap admin (clevel | ciso | architect | engineer)
WOMBAT_API_KEY (empty) Pre-shared key for CI/CD pushes — pass as X-Api-Key header on POST /api/v1/runs / POST /api/v1/scan

Local dev tip: When running the dashboard dev server alongside the API, add http://localhost:5173 to CORS_ORIGINS so Vite's dev server can reach the API without CORS errors.


Authentication

All API endpoints under /api/v1 require a valid Bearer JWT except POST /api/v1/auth/login, the SSO flow endpoints, and GET /health.

Local accounts

# 1. Set admin credentials in .env (first-run only — auto-seeds one user)
WOMBAT_ADMIN_USERNAME=admin
WOMBAT_ADMIN_PASSWORD=changeme123
WOMBAT_ADMIN_ROLE=admin

# 2. Obtain a token
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"changeme123"}' | jq -r .access_token)

# 3. Use it on any request
curl http://localhost:8000/api/v1/runs -H "Authorization: Bearer $TOKEN"

SSO (OIDC / SAML2)

SSO is configured through the dashboard SSO Settings page (admin only) or directly via the API. Configuration is stored in the database — no server restart required.

OIDC flow:

  1. Admin configures discovery URL, client ID/secret, redirect URI, and role mapping in SSO Settings.
  2. Users click "Sign in with OIDC" on the login page → redirect to IdP → callback → JWT issued.
  3. GET /api/v1/auth/oidc/authorize initiates the Authorization Code flow. A cryptographically random nonce is embedded in the signed state JWT and also sent to the IdP as the nonce parameter so the IdP includes it in the id_token.
  4. GET /api/v1/auth/oidc/callback exchanges the code, then:
    • Verifies the state JWT (CSRF protection).
    • Fetches the IdP's public JWKS from jwks_uri and verifies the id_token signature (RS256/EC).
    • Validates the aud claim equals client_id and the nonce claim matches the state JWT.
    • Provisions the user and issues a Wombat JWT, then redirects to the dashboard.

SAML2 flow:

  1. Admin configures SP/IdP entity IDs, ACS URL, IdP certificate, and role mapping.
  2. Register the SP using the metadata endpoint: GET /api/v1/auth/saml/metadata.
  3. GET /api/v1/auth/saml/login initiates the SP-initiated SSO redirect.
  4. POST /api/v1/auth/saml/acs validates the assertion, provisions the user, issues a JWT, and redirects.

SAML2 requires the optional python3-saml system dependency: pip install "wombat-server[saml]" (also needs libxmlsec1 on the host).

CI/CD (no user account needed)

Set WOMBAT_API_KEY=some-secret on the server and pass it as a header:

wombat check ./infra --output json | \
  curl -s -X POST http://localhost:8000/api/v1/runs \
       -H "Content-Type: application/json" \
       -H "X-Api-Key: some-secret" \
       -d @-

To enable dashboard Local preview / auto-fix diffs, add --upload-source:

wombat check ./infra --output json --upload-source | \
  curl -s -X POST http://localhost:8000/api/v1/runs \
       -H "Content-Type: application/json" \
       -H "X-Api-Key: some-secret" \
       -d @-

Role hierarchy

Role Inherits Permitted operations
clevel — Read: all run data, waivers, risks, controls
ciso clevel + Create/update/delete waivers and risk acceptances
architect ciso + Create/delete controls catalogue entries, run sandbox
engineer architect + Trigger scans (POST /api/v1/scan), user management
admin engineer + User lifecycle, API key management, SSO configuration

API reference

Authentication

Method Path Auth Description
POST /api/v1/auth/login None Exchange credentials for access + refresh tokens
POST /api/v1/auth/refresh None Exchange refresh token for new access token
POST /api/v1/auth/logout None Revoke a refresh token
GET /api/v1/auth/me Any Return current user profile
GET /api/v1/auth/users engineer List all users
POST /api/v1/auth/users engineer Create a user
PUT /api/v1/auth/users/{id} engineer Update user role / password / status
DELETE /api/v1/auth/users/{id} engineer Delete a user

SSO

Method Path Auth Description
GET /api/v1/sso/providers None List enabled SSO providers (for login page)
GET /api/v1/sso/config admin List all SSO configurations
PUT /api/v1/sso/config/{provider} admin Upsert OIDC or SAML2 configuration
DELETE /api/v1/sso/config/{provider} admin Remove an SSO configuration
GET /api/v1/sso/group-mappings admin List all group → role mappings
POST /api/v1/sso/group-mappings admin Create a group → role mapping
PUT /api/v1/sso/group-mappings/{id} admin Update a group → role mapping
DELETE /api/v1/sso/group-mappings/{id} admin Delete a group → role mapping
GET /api/v1/auth/oidc/authorize None Initiate OIDC Authorization Code flow
GET /api/v1/auth/oidc/callback None OIDC callback — issue JWT, redirect to dashboard
GET /api/v1/auth/saml/metadata None SP metadata XML (register with IdP)
GET /api/v1/auth/saml/login None Initiate SAML2 SP-initiated SSO
POST /api/v1/auth/saml/acs None SAML2 Assertion Consumer Service

Health

Method Path Description
GET /health Liveness check → {"status": "ok"}

Runs

Ingest and retrieve compliance scan results produced by wombat check --output json.

Method Path Description
POST /api/v1/runs Ingest a wombat-result.json payload
GET /api/v1/runs List runs (limit, offset, project)
GET /api/v1/runs/{id} Full run with findings, controls metadata, secret findings
GET /api/v1/runs/{id}/controls Controls metadata for a run
GET /api/v1/runs/{id}/findings Filtered findings (severity, pillar, status)

Push a result from CI:

wombat check ./infra --output json | \
  curl -s -X POST http://localhost:8000/api/v1/runs \
       -H "Content-Type: application/json" \
       -d @-

Push a result with source snapshots (required for dashboard Local preview diffs):

wombat check ./infra --output json --upload-source | \
  curl -s -X POST http://localhost:8000/api/v1/runs \
       -H "Content-Type: application/json" \
       -d @-

Set metadata before posting:

import json, httpx

result = json.loads(open("wombat-result.json").read())
result.update({"project": "my-infra", "branch": "main", "git_sha": "abc1234"})
httpx.post("http://localhost:8000/api/v1/runs", json=result)

Controls catalogue

Browse and manage Wombat controls independently of scan runs.

Method Path Description
POST /api/v1/controls Upsert a control (returns {data, meta} envelope)
GET /api/v1/controls List controls (pillar, severity, page, per_page)
GET /api/v1/controls/{id} Get a single control
DELETE /api/v1/controls/{id} Delete a control

Waivers

Team-shared waiver records. Suppresses a control from failing in the dashboard, shared across all team members.

Method Path Description
GET /api/v1/waivers List waivers (project filter — returns global + project-specific)
PUT /api/v1/waivers/{id} Upsert a waiver (idempotent — create or update by control ID)
DELETE /api/v1/waivers/{id} Delete a waiver
{
  "reason": "Covered by external quarterly IAM review — SEC-1234",
  "owner": "platform-team",
  "expires": "2026-09-30",
  "project": ""
}

Risk acceptances

Formally accepted residual risks with approver sign-off, RFC, and traceability links.

Method Path Description
GET /api/v1/risks List risk acceptances
PUT /api/v1/risks/{id} Upsert a risk acceptance
DELETE /api/v1/risks/{id} Delete a risk acceptance
{
  "reason": "Legacy system — migration planned Q3 2026",
  "approver": "Jane Smith",
  "owner": "platform-team",
  "rfc": "RFC-0042",
  "jira_link": "https://jira.example.com/browse/SEC-100",
  "risk_level": "high",
  "residual_risk": "medium",
  "expires": "2026-09-30",
  "accepted_at": "2026-01-15T09:00:00Z",
  "project": ""
}

Architect Sandbox

Run the real Wombat engine against arbitrary IaC snippets in-process. The sandbox currently evaluates HCL snippets; pass "iac": "terraform" (or another supported framework identifier) to select the parser. Requires wombat-core and a populated WOMBAT_CONTROLS_DIR.

Method Path Description
POST /api/v1/sandbox Evaluate an IaC snippet against all loaded controls
GET /api/v1/sandbox/status Check engine availability
# Check if engine is ready
curl http://localhost:8000/api/v1/sandbox/status

# Run an HCL snippet (Terraform example)
curl -X POST http://localhost:8000/api/v1/sandbox \
  -H "Content-Type: application/json" \
  -d '{"hcl": "resource \"aws_s3_bucket\" \"b\" {}", "iac": "terraform"}'

Without wombat-core, the server starts normally and all other endpoints remain available. Sandbox returns 503 with a descriptive message.

Evidence Locker

Cryptographically-locked, immutable audit packages. Locking freezes a run snapshot at the moment of creation, computes a SHA-256 hash of the canonical payload, and generates a shareable public token so auditors can view the package without a login.

Method Path Auth Description
POST /api/v1/evidence engineer Lock a run as an immutable evidence package
GET /api/v1/evidence clevel List evidence packages (project, limit, offset)
GET /api/v1/evidence/{id} clevel Get evidence metadata
GET /api/v1/evidence/{id}/snapshot clevel Return the raw frozen JSON snapshot
GET /api/v1/evidence/{id}/report.html clevel Download the locked HTML report
GET /api/v1/evidence/{id}/qr.svg clevel QR code SVG linking to the public auditor URL
DELETE /api/v1/evidence/{id} admin Delete an evidence package
GET /api/v1/evidence/p/{token} None Public auditor view (unauthenticated)
GET /api/v1/evidence/p/{token}/qr.svg None Public QR code (for PDF embedding)
GET /api/v1/evidence/p/{token}/meta None Public metadata (used by CLI)

Each locked package includes: title, prepared-by, organization, audit period, regulatory frameworks, SHA-256 hash digest, a public token, and the locking user. The WOMBAT_PUBLIC_URL env var controls the base URL embedded in QR codes (defaults to the incoming request's scheme + host).

Achievements

Maturity tier milestones. Achievements are awarded automatically when a project reaches a new compliance score threshold for the first time. The public verification page is unauthenticated, making achievements shareable on READMEs and external dashboards.

Method Path Auth Description
GET /api/v1/achievements clevel List all achievements (project filter)
GET /api/v1/achievements/{project} clevel List achievements for a project
GET /api/v1/public/achievements/{token} None Public cryptographic verification page

Tier thresholds:

Level Label Min Score
L1 Foundational 0
L2 Operational 40
L3 Governed 60
L4 Optimized 75
L5 Excellence 90

Achievements are evaluated automatically on every POST /api/v1/runs. A new achievement is recorded only when the project reaches a tier level it has not previously held.

Leaderboard

Hall of Fame — top sovereign and most improved projects across the organisation.

Method Path Auth Description
GET /api/v1/leaderboard clevel Top-sovereign and most-improved project rankings

Returns two ranked lists:

  • Top Sovereign — projects that have held Tier 5 the longest (by achieved_at ascending).
  • Most Improved — projects that gained the most tier levels in the last 30 days.

Both lists include project display name, owner, team, current score, tier, and days held (from ProjectPassport if configured).

Live Status Badges

Shields.io-style SVG badges for READMEs and external dashboards. Live badges reflect the latest run score; static tier badges are pre-rendered for air-gapped environments.

Method Path Auth Description
GET /api/v1/public/badge/{project}.svg None Dynamic SVG badge (latest run → tier label)
GET /api/v1/public/badge/{project}/download None Same badge with Content-Disposition: attachment
GET /api/v1/public/badge/{project}/json None JSON status (shields.io endpoint-badge compatible)
GET /api/v1/public/badge/static/{tier_level}.svg None Pre-rendered static badge (1–5)

Embed a live badge in your README:

![WOMBATpass](https://wombat.example.com/public/badge/my-project.svg)

For air-gapped environments: download via /download and commit the SVG.

Project Passports

Per-project metadata — display name, owner, team, contact, description, criticality, environment, cloud provider, and repository/documentation URLs. Used by the Leaderboard and Dashboard pages to enrich project listings.

Method Path Auth Description
GET /api/v1/projects/passports clevel List all project passports
GET /api/v1/projects/{project}/passport clevel Get a project's passport
PUT /api/v1/projects/{project}/passport architect Upsert a project passport
DELETE /api/v1/projects/{project}/passport admin Delete a project passport

Findings Comments

Team collaboration on findings — comments, notifications, and remediation tracking. Comments can be added to regular findings or secret findings.

Method Path Auth Description
GET /api/v1/findings-comments clevel List comments for a run (finding_id or secret_finding_id filter)
POST /api/v1/findings-comments clevel Create a comment on a finding
GET /api/v1/findings-comments/count clevel Comment count per finding (aggregated)

Widgets

Create and manage dashboards for compliance data display on computers, TVs, or web pages. Widgets have unique authentication tokens and can be configured to show specific projects, data types, and refresh intervals.

Method Path Auth Description
POST /api/v1/widgets engineer Create a new widget
GET /api/v1/widgets engineer List all widgets (is_active filter)
GET /api/v1/widgets/{id} engineer Get widget details
PUT /api/v1/widgets/{id} engineer Update a widget
DELETE /api/v1/widgets/{id} admin Delete a widget
GET /api/v1/widget/p/{token}.json None Public JSON data endpoint
GET /api/v1/widget/p/{token}/badge.svg None Public SVG badge endpoint

Create a widget:

curl -X POST http://localhost:8000/api/v1/widgets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Office Display",
    "config": {
      "widget_type": "compliance-tile",
      "projects": ["my-app", "api-service"],
      "refresh_interval": 300,
      "show_score": true,
      "show_pillars": true,
      "theme": "auto",
      "layout": "horizontal"
    }
  }'

Fetch widget data (public endpoint, no auth required):

curl http://localhost:8000/api/v1/widget/p/abc123xyz.json

Response:

{
  "token": "abc123xyz",
  "name": "Main Office Display",
  "data": {
    "score": 85,
    "tier_level": 4,
    "tier_label": "Optimized",
    "tier_color": "#7c3aed",
    "projects": [...],
    "pillar_scores": {...},
    "last_run_at": "2026-01-15T10:30:00Z"
  }
}

Embed the badge in your README or dashboard:

![WOMBATpass](https://your-server.com/widget/p/abc123xyz.svg)

Database migrations

Migrations use Alembic.

alembic upgrade head                           # apply all migrations
alembic downgrade -1                           # roll back one step
alembic revision --autogenerate -m "my change" # generate migration after editing models.py
alembic current                                # show applied revision

Migration history:

Revision Change
0001_create_runs Initial runs table
0002_add_run_metadata path, controls_loaded, controls_run, regions, source_paths
0003_add_controls_meta controls_meta JSONB
0004_add_plan_changes plan_changes JSONB
0005_add_controls controls catalogue table
0006_add_secret_findings secret_findings JSONB
0007_add_waivers_risks waivers and risk_acceptances tables
0008_add_stage_to_runs stage column on runs
0009_add_auth_tables users and refresh_tokens tables
0010_add_api_keys api_keys table
0011_add_api_key_usage_logs api_key_usage_logs table
0012_add_user_audit_logs user_audit_logs table
0013_add_sso_config sso_configs table (OIDC + SAML2 configuration)
0014_add_group_role_mappings group_role_mappings table (centralized IdP group → role resolution)
0015_add_evidence evidence table (locked audit packages with SHA-256 hash and public token)
0016_add_project_passports project_passports table (per-project metadata)
0017_add_passport_image_url image_url column on project_passports
0018_add_achievements project_achievements table (maturity tier milestones with verification tokens)
0019_add_findings_comments findings_comments table (team collaboration on findings)
0020_add_secret_findings_comments secret_findings_comments table (comments on secret findings)

Docker

The build context is the monorepo root because the Dockerfile copies pass/ first to install wombat-core:

# From repo root
docker build -t wombat-server -f wombat-server/Dockerfile .

docker run \
  -e DATABASE_URL=postgresql+asyncpg://wombat:wombat@host.docker.internal/wombat \
  -e CORS_ORIGINS=http://localhost:3000 \
  -e WOMBAT_CONTROLS_DIR=/app/controls \
  -p 8000:8000 \
  wombat-server

The entrypoint (entrypoint.sh) runs alembic upgrade head automatically before starting uvicorn — no manual migration step needed in production.

Custom controls directory:

# docker-compose.yml — wombat-server service
volumes:
  - ./my-controls:/app/controls:ro
environment:
  WOMBAT_CONTROLS_DIR: /app/controls

Interactive docs

URL Description
http://localhost:8000/api/v1/docs Swagger UI — try requests in browser
http://localhost:8000/api/v1/redoc ReDoc — read-only reference

Development

pip install -e ".[dev]"
pytest

See TECH.md for architecture details, database schema, and contribution guidance.


Contributing and security

  • CONTRIBUTING.md — how to set up local development, run tests, add endpoints, and open pull requests.
  • CODE_OF_CONDUCT.md — community standards and enforcement.
  • SECURITY.md — supported versions, how to report vulnerabilities, and security-sensitive configuration.
  • LICENSE — Apache License 2.0.

Metadata

Release files for wombat-server 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wombat-server 1.2.0
File Size Uploaded Provenance Actions
wombat_server-1.2.0.tar.gz 393.7 kB With provenance Details for wombat_server-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wombat-server 1.2.0
File Interpreter ABI Platform Actions
wombat_server-1.2.0-py3-none-any.whl Python 3 none any Details for wombat_server-1.2.0-py3-none-any.whl

Total release size: 570.9 kB

Release files / wombat_server-1.2.0.tar.gz

Download URL wombat_server-1.2.0.tar.gz
Size 393.7 kB
Tags Source
SHA-256 checksum
How to use checksums
a7badecf59f12d9b777a9a5f8f39494a9925f304e19d0d75b9cb7a84fea956e8
BLAKE2b-256 checksum
How to use checksums
b304086bf93b256a3459700392c559be80fa5f821f36c796c57e616b648d5ac9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Release files / wombat_server-1.2.0-py3-none-any.whl

Download URL wombat_server-1.2.0-py3-none-any.whl
Size 177.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
548e0c5f7b7b796e4d87334ed127c738c399890ad7799dae1f9a121591675d7f
BLAKE2b-256 checksum
How to use checksums
5d81af9696544b5b71611b677e9247c323c89cb3a8e6957ce706a0ed168147a6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Security for wombat-server 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for wombat_server-1.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page