wafpass-server 0.3.4__tar.gz

wafpass_server-0.3.4/.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    name: Build & publish release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write   # required for PyPI trusted publishing (OIDC)
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Compute version
+        id: ver
+        run: |
+          BASE=$(cat VERSION | tr -d '[:space:]')
+          echo "Base version: $BASE"
+
+          LATEST=$(git tag -l "v${BASE}.*" | sort -V | tail -1)
+          echo "Latest matching tag: ${LATEST:-none}"
+
+          if [ -z "$LATEST" ]; then
+            PATCH=0
+          else
+            PATCH=$(echo "$LATEST" | sed "s/v${BASE}\.//")
+            PATCH=$((PATCH + 1))
+          fi
+
+          FULL="${BASE}.${PATCH}"
+          TAG="v${FULL}"
+          echo "New version: $TAG"
+
+          echo "full=${FULL}" >> $GITHUB_OUTPUT
+          echo "tag=${TAG}"   >> $GITHUB_OUTPUT
+
+      - name: Bump version in pyproject.toml
+        run: |
+          VER="${{ steps.ver.outputs.full }}"
+          sed -i "s/^version = \".*\"/version = \"${VER}\"/" pyproject.toml
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build
+        run: python -m build
+
+      - name: Install package + test deps
+        run: pip install ".[dev]"
+
+      - name: Test
+        run: pytest
+
+      # ── Publish to PyPI (trusted publishing / OIDC) ───────────────────────────
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name:              ${{ steps.ver.outputs.tag }}
+          name:                  WAF++ PASS Server ${{ steps.ver.outputs.tag }}
+          generate_release_notes: true
+          files: |
+            dist/*.whl
+            dist/*.tar.gz

wafpass_server-0.3.4/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+RUN pip install --no-cache-dir hatchling build
+
+# Install wafpass-core from the local sibling package (pass/).
+# This must happen before wafpass-server is installed so that
+# `from wafpass.control_schema import WizardControl` resolves correctly.
+COPY pass/ /tmp/wafpass-core/
+RUN pip install --no-cache-dir /tmp/wafpass-core && rm -rf /tmp/wafpass-core
+
+COPY wafpass-server/pyproject.toml wafpass-server/VERSION wafpass-server/README.md ./
+COPY wafpass-server/wafpass_server/ wafpass_server/
+COPY wafpass-server/alembic/ alembic/
+COPY wafpass-server/alembic.ini wafpass-server/entrypoint.sh ./
+
+RUN pip install --no-cache-dir . && chmod +x entrypoint.sh
+
+EXPOSE 8000
+
+ENTRYPOINT ["./entrypoint.sh"]

wafpass_server-0.3.4/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: wafpass-server
+Version: 0.3.4
+Summary: WAF++ PASS – API server for persisting and querying scan results
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.13
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: fastapi>=0.100
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: uvicorn[standard]>=0.23
+Provides-Extra: dev
+Requires-Dist: httpx>=0.26; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# wafpass-server
+
+REST API for persisting and querying WAF++ PASS scan results.
+
+Receives `wafpass-result.json` payloads from `wafpass check --output json`,
+stores them in PostgreSQL, and exposes them to the dashboard and CI tooling.
+
+## API endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/runs` | Ingest a `wafpass-result.json` payload |
+| `GET` | `/runs` | List runs (query: `limit`, `offset`, `project`) |
+| `GET` | `/runs/{id}` | Single run with all findings |
+| `GET` | `/runs/{id}/findings` | Findings only (query: `severity`, `pillar`, `status`) |
+| `GET` | `/health` | Health check |
+| `GET` | `/api/docs` | Swagger UI |
+
+## Setup
+
+### Environment variables
+
+Copy `.env.example` from the repo root:
+
+```
+DATABASE_URL=postgresql+asyncpg://wafpass:changeme@localhost:5432/wafpass
+WAFPASS_ENV=local
+CORS_ORIGINS=http://localhost:5173,http://localhost:3000
+```
+
+### Run locally
+
+```bash
+pip install -e ".[dev]"
+alembic upgrade head
+uvicorn wafpass_server.main:app --reload --port 8000
+```
+
+### Run migrations
+
+```bash
+alembic upgrade head       # apply all migrations
+alembic downgrade -1       # roll back one step
+alembic revision --autogenerate -m "add column"  # generate new migration
+```
+
+### Docker
+
+```bash
+docker build -t wafpass-server .
+docker run -e DATABASE_URL=... -p 8000:8000 wafpass-server
+```
+
+### docker-compose (full stack)
+
+From the repo root:
+
+```bash
+cp .env.example .env   # fill in passwords
+docker compose up
+```
+
+## Posting a scan result
+
+```bash
+wafpass check infra/ --output json > result.json
+curl -X POST http://localhost:8000/runs \
+     -H "Content-Type: application/json" \
+     -d @result.json
+```
+
+Or set metadata fields before posting:
+
+```python
+import json, httpx
+
+result = json.load(open("result.json"))
+result.update({"project": "my-infra", "branch": "main", "git_sha": "abc1234"})
+httpx.post("http://localhost:8000/runs", json=result)
+```
+
+## Result schema
+
+The payload shape is defined by `WafpassResultSchema` in `wafpass-core`
+(`wafpass/schema.py`). `wafpass-server` mirrors that schema in
+`wafpass_server/schemas.py` (`RunCreate`). Once `wafpass-core` is published
+to PyPI, replace the local definition with a direct import.
+
+Key fields stored per run:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | uuid | Auto-generated primary key |
+| `project` | text | Repo / project name |
+| `branch` | text | VCS branch |
+| `git_sha` | text | Commit SHA |
+| `triggered_by` | text | `local` \| `github-actions` \| `gitlab-ci` \| … |
+| `iac_framework` | text | `terraform` \| `cdk` \| … |
+| `score` | int | Overall compliance score (0–100) |
+| `pillar_scores` | jsonb | Per-pillar scores `{"SEC": 90, …}` |
+| `findings` | jsonb | Array of check results |
+| `created_at` | timestamptz | Inserted at |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

wafpass_server-0.3.4/README.md

@@ -0,0 +1,109 @@
+# wafpass-server
+
+REST API for persisting and querying WAF++ PASS scan results.
+
+Receives `wafpass-result.json` payloads from `wafpass check --output json`,
+stores them in PostgreSQL, and exposes them to the dashboard and CI tooling.
+
+## API endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/runs` | Ingest a `wafpass-result.json` payload |
+| `GET` | `/runs` | List runs (query: `limit`, `offset`, `project`) |
+| `GET` | `/runs/{id}` | Single run with all findings |
+| `GET` | `/runs/{id}/findings` | Findings only (query: `severity`, `pillar`, `status`) |
+| `GET` | `/health` | Health check |
+| `GET` | `/api/docs` | Swagger UI |
+
+## Setup
+
+### Environment variables
+
+Copy `.env.example` from the repo root:
+
+```
+DATABASE_URL=postgresql+asyncpg://wafpass:changeme@localhost:5432/wafpass
+WAFPASS_ENV=local
+CORS_ORIGINS=http://localhost:5173,http://localhost:3000
+```
+
+### Run locally
+
+```bash
+pip install -e ".[dev]"
+alembic upgrade head
+uvicorn wafpass_server.main:app --reload --port 8000
+```
+
+### Run migrations
+
+```bash
+alembic upgrade head       # apply all migrations
+alembic downgrade -1       # roll back one step
+alembic revision --autogenerate -m "add column"  # generate new migration
+```
+
+### Docker
+
+```bash
+docker build -t wafpass-server .
+docker run -e DATABASE_URL=... -p 8000:8000 wafpass-server
+```
+
+### docker-compose (full stack)
+
+From the repo root:
+
+```bash
+cp .env.example .env   # fill in passwords
+docker compose up
+```
+
+## Posting a scan result
+
+```bash
+wafpass check infra/ --output json > result.json
+curl -X POST http://localhost:8000/runs \
+     -H "Content-Type: application/json" \
+     -d @result.json
+```
+
+Or set metadata fields before posting:
+
+```python
+import json, httpx
+
+result = json.load(open("result.json"))
+result.update({"project": "my-infra", "branch": "main", "git_sha": "abc1234"})
+httpx.post("http://localhost:8000/runs", json=result)
+```
+
+## Result schema
+
+The payload shape is defined by `WafpassResultSchema` in `wafpass-core`
+(`wafpass/schema.py`). `wafpass-server` mirrors that schema in
+`wafpass_server/schemas.py` (`RunCreate`). Once `wafpass-core` is published
+to PyPI, replace the local definition with a direct import.
+
+Key fields stored per run:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | uuid | Auto-generated primary key |
+| `project` | text | Repo / project name |
+| `branch` | text | VCS branch |
+| `git_sha` | text | Commit SHA |
+| `triggered_by` | text | `local` \| `github-actions` \| `gitlab-ci` \| … |
+| `iac_framework` | text | `terraform` \| `cdk` \| … |
+| `score` | int | Overall compliance score (0–100) |
+| `pillar_scores` | jsonb | Per-pillar scores `{"SEC": 90, …}` |
+| `findings` | jsonb | Array of check results |
+| `created_at` | timestamptz | Inserted at |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

wafpass_server-0.3.4/VERSION

@@ -0,0 +1 @@
+0.3

wafpass_server-0.3.4/alembic/env.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import pool
+
+from wafpass_server.database import Base
+from wafpass_server import models as _models  # noqa: F401 – ensure models are registered
+
+config = context.config
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Override sqlalchemy.url from DATABASE_URL env var when running in Docker / CI.
+# Falls back to the value in alembic.ini for local development.
+if os.environ.get("DATABASE_URL"):
+    config.set_main_option("sqlalchemy.url", os.environ["DATABASE_URL"])
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection) -> None:
+    context.configure(connection=connection, target_metadata=target_metadata)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    from sqlalchemy.ext.asyncio import create_async_engine
+
+    url = config.get_main_option("sqlalchemy.url")
+    connectable = create_async_engine(url, poolclass=pool.NullPool)
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

wafpass_server-0.3.4/alembic/script.py.mako

@@ -0,0 +1,27 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

wafpass_server-0.3.4/alembic/versions/0001_create_runs.py

@@ -0,0 +1,45 @@
+"""create runs table
+
+Revision ID: 0001
+Revises:
+Create Date: 2026-01-01 00:00:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+revision = "0001"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "runs",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("project", sa.Text(), nullable=False, server_default=""),
+        sa.Column("branch", sa.Text(), nullable=False, server_default=""),
+        sa.Column("git_sha", sa.Text(), nullable=False, server_default=""),
+        sa.Column("triggered_by", sa.Text(), nullable=False, server_default="local"),
+        sa.Column("iac_framework", sa.Text(), nullable=False, server_default="terraform"),
+        sa.Column("score", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("pillar_scores", postgresql.JSONB(), nullable=False, server_default="{}"),
+        sa.Column("findings", postgresql.JSONB(), nullable=False, server_default="[]"),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+    )
+    op.create_index("ix_runs_project", "runs", ["project"])
+    op.create_index("ix_runs_created_at", "runs", ["created_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_runs_created_at", "runs")
+    op.drop_index("ix_runs_project", "runs")
+    op.drop_table("runs")

wafpass_server-0.3.4/alembic/versions/0002_add_run_metadata.py

@@ -0,0 +1,32 @@
+"""add run metadata columns
+
+Revision ID: 0002
+Revises: 0001
+Create Date: 2026-01-02 00:00:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+revision = "0002"
+down_revision = "0001"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("runs", sa.Column("path", sa.Text(), nullable=False, server_default=""))
+    op.add_column("runs", sa.Column("controls_loaded", sa.Integer(), nullable=False, server_default="0"))
+    op.add_column("runs", sa.Column("controls_run", sa.Integer(), nullable=False, server_default="0"))
+    op.add_column("runs", sa.Column("detected_regions", postgresql.JSONB(), nullable=False, server_default="[]"))
+    op.add_column("runs", sa.Column("source_paths", postgresql.JSONB(), nullable=False, server_default="[]"))
+
+
+def downgrade() -> None:
+    op.drop_column("runs", "source_paths")
+    op.drop_column("runs", "detected_regions")
+    op.drop_column("runs", "controls_run")
+    op.drop_column("runs", "controls_loaded")
+    op.drop_column("runs", "path")

wafpass_server-0.3.4/alembic/versions/0003_add_controls_meta.py

@@ -0,0 +1,24 @@
+"""add controls_meta column
+
+Revision ID: 0003
+Revises: 0002
+Create Date: 2026-03-28 00:00:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+revision = "0003"
+down_revision = "0002"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("runs", sa.Column("controls_meta", postgresql.JSONB(), nullable=False, server_default="[]"))
+
+
+def downgrade() -> None:
+    op.drop_column("runs", "controls_meta")

wafpass_server-0.3.4/alembic/versions/0004_add_plan_changes.py

@@ -0,0 +1,24 @@
+"""add plan_changes column
+
+Revision ID: 0004
+Revises: 0003
+Create Date: 2026-03-28 00:00:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+revision = "0004"
+down_revision = "0003"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("runs", sa.Column("plan_changes", postgresql.JSONB(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("runs", "plan_changes")

wafpass_server-0.3.4/alembic/versions/0005_add_controls.py

@@ -0,0 +1,59 @@
+"""add controls table
+
+Revision ID: 0005
+Revises: 0004
+Create Date: 2026-03-29 00:00:00.000000
+"""
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision = "0005"
+down_revision = "0004"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "controls",
+        sa.Column("id", sa.Text, primary_key=True),
+        sa.Column("pillar", sa.Text, nullable=False, server_default=""),
+        sa.Column("severity", sa.Text, nullable=False, server_default=""),
+        sa.Column(
+            "type",
+            postgresql.JSONB(astext_type=sa.Text()),
+            nullable=False,
+            server_default=sa.text("'[]'::jsonb"),
+        ),
+        sa.Column("description", sa.Text, nullable=False, server_default=""),
+        sa.Column(
+            "checks",
+            postgresql.JSONB(astext_type=sa.Text()),
+            nullable=False,
+            server_default=sa.text("'[]'::jsonb"),
+        ),
+        sa.Column("source", sa.Text, nullable=False, server_default="wafpass"),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+    )
+    op.create_index("ix_controls_pillar", "controls", ["pillar"])
+    op.create_index("ix_controls_severity", "controls", ["severity"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_controls_severity", table_name="controls")
+    op.drop_index("ix_controls_pillar", table_name="controls")
+    op.drop_table("controls")

wafpass_server-0.3.4/alembic.ini

@@ -0,0 +1,41 @@
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+version_path_separator = os
+sqlalchemy.url = postgresql+asyncpg://wafpass:wafpass@localhost:5432/wafpass
+
+[post_write_hooks]
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

wafpass_server-0.3.4/entrypoint.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+set -e
+
+echo "DATABASE_URL: $DATABASE_URL"
+
+python - <<'EOF'
+import os, sys
+from alembic.config import Config
+from alembic import command
+
+url = os.environ.get("DATABASE_URL")
+if not url:
+    print("ERROR: DATABASE_URL is not set", file=sys.stderr)
+    sys.exit(1)
+
+cfg = Config("alembic.ini")
+cfg.set_main_option("sqlalchemy.url", url)
+command.upgrade(cfg, "head")
+print("Migrations complete.")
+EOF
+
+exec uvicorn wafpass_server.main:app --host 0.0.0.0 --port 8000

wafpass_server-0.3.4/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wafpass-server"
+version = "0.3.4"
+description = "WAF++ PASS – API server for persisting and querying scan results"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = [
+    "fastapi>=0.100",
+    "uvicorn[standard]>=0.23",
+    "sqlalchemy>=2.0",
+    "asyncpg>=0.29",
+    "alembic>=1.13",
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+    "httpx>=0.26",
+    "pytest-cov>=4.0",
+]
+
+[project.scripts]
+wafpass-server = "wafpass_server.main:start"
+
+[tool.hatch.build.targets.wheel]
+packages = ["wafpass_server"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"
+asyncio_mode = "auto"

wafpass_server-0.3.4/tests/test_runs.py

@@ -0,0 +1,14 @@
+"""Smoke tests for the /runs endpoints.
+
+Integration tests require a running PostgreSQL instance. Set DATABASE_URL
+in the environment or .env file before running.
+"""
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_placeholder() -> None:
+    """Placeholder — replace with real integration tests once DB is available."""
+    assert True

wafpass_server-0.3.4/wafpass_server/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("wafpass-server")
+except PackageNotFoundError:
+    __version__ = "0.3.0-dev"

wafpass_server-0.3.4/wafpass_server/config.py

@@ -0,0 +1,21 @@
+"""Application configuration via environment variables."""
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    database_url: str = "postgresql+asyncpg://wafpass:wafpass@localhost:5432/wafpass"
+    wafpass_env: str = "local"
+
+    # CORS origins (comma-separated)
+    cors_origins: str = "http://localhost:5173,http://localhost:3000"
+
+    @property
+    def cors_origins_list(self) -> list[str]:
+        return [o.strip() for o in self.cors_origins.split(",") if o.strip()]
+
+
+settings = Settings()

wafpass_server-0.3.4/wafpass_server/database.py

@@ -0,0 +1,21 @@
+"""Async SQLAlchemy engine and session factory."""
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase
+
+from wafpass_server.config import settings
+
+engine = create_async_engine(settings.database_url, echo=False, pool_pre_ping=True)
+AsyncSessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with AsyncSessionLocal() as session:
+        yield session

wafpass_server-0.3.4/wafpass_server/main.py

@@ -0,0 +1,46 @@
+"""WAF++ PASS server entry point."""
+from __future__ import annotations
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from wafpass_server.config import settings
+from wafpass_server.routers.controls import router as controls_router
+from wafpass_server.routers.runs import router as runs_router
+
+app = FastAPI(
+    title="wafpass-server",
+    version="0.3.0",
+    description="REST API for persisting and querying WAF++ PASS scan results.",
+    docs_url="/api/docs",
+    redoc_url="/api/redoc",
+    openapi_tags=[
+        {"name": "runs", "description": "Scan run results ingestion and retrieval."},
+        {"name": "controls", "description": "WAF++ control catalogue management."},
+    ],
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(runs_router)
+app.include_router(controls_router)
+
+
+@app.get("/health", tags=["health"])
+async def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+def start() -> None:
+    uvicorn.run("wafpass_server.main:app", host="0.0.0.0", port=8000, reload=False)
+
+
+if __name__ == "__main__":
+    start()

wafpass_server-0.3.4/wafpass_server/models.py

@@ -0,0 +1,51 @@
+"""SQLAlchemy ORM models."""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import DateTime, Integer, Text
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from wafpass_server.database import Base
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class Control(Base):
+    __tablename__ = "controls"
+
+    id: Mapped[str] = mapped_column(Text, primary_key=True)
+    pillar: Mapped[str] = mapped_column(Text, default="")
+    severity: Mapped[str] = mapped_column(Text, default="")
+    type: Mapped[list] = mapped_column(JSONB, default=list)
+    description: Mapped[str] = mapped_column(Text, default="")
+    checks: Mapped[list] = mapped_column(JSONB, default=list)
+    source: Mapped[str] = mapped_column(Text, default="wafpass")
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
+
+
+class Run(Base):
+    __tablename__ = "runs"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    project: Mapped[str] = mapped_column(Text, default="")
+    branch: Mapped[str] = mapped_column(Text, default="")
+    git_sha: Mapped[str] = mapped_column(Text, default="")
+    triggered_by: Mapped[str] = mapped_column(Text, default="local")
+    iac_framework: Mapped[str] = mapped_column(Text, default="terraform")
+    score: Mapped[int] = mapped_column(Integer, default=0)
+    pillar_scores: Mapped[dict] = mapped_column(JSONB, default=dict)
+    findings: Mapped[list] = mapped_column(JSONB, default=list)
+    path: Mapped[str] = mapped_column(Text, default="")
+    controls_loaded: Mapped[int] = mapped_column(Integer, default=0)
+    controls_run: Mapped[int] = mapped_column(Integer, default=0)
+    detected_regions: Mapped[list] = mapped_column(JSONB, default=list)
+    source_paths: Mapped[list] = mapped_column(JSONB, default=list)
+    controls_meta: Mapped[list] = mapped_column(JSONB, default=list)
+    plan_changes: Mapped[dict | None] = mapped_column(JSONB, nullable=True, default=None)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)

wafpass_server-0.3.4/wafpass_server/routers/controls.py

@@ -0,0 +1,119 @@
+"""POST/GET/DELETE /controls endpoints."""
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from wafpass_server.database import get_db
+from wafpass_server.models import Control, _now
+from wafpass_server.schemas import ControlIn, ControlOut, Envelope, Meta
+
+router = APIRouter(prefix="/controls", tags=["controls"])
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _to_out(ctrl: Control) -> ControlOut:
+    return ControlOut.model_validate(ctrl, from_attributes=True)
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+
+@router.post("", response_model=Envelope[ControlOut], status_code=200)
+async def upsert_control(
+    payload: ControlIn,
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> Envelope[ControlOut]:
+    """Create or update a control (idempotent upsert on ``id``)."""
+    ctrl = await db.get(Control, payload.id)
+
+    if ctrl is None:
+        ctrl = Control(
+            id=payload.id,
+            pillar=payload.pillar,
+            severity=payload.severity,
+            type=list(payload.type),
+            description=payload.description,
+            checks=[c.model_dump() for c in payload.checks],
+            source=payload.source,
+        )
+        db.add(ctrl)
+    else:
+        ctrl.pillar = payload.pillar
+        ctrl.severity = payload.severity
+        ctrl.type = list(payload.type)
+        ctrl.description = payload.description
+        ctrl.checks = [c.model_dump() for c in payload.checks]
+        ctrl.source = payload.source
+        ctrl.updated_at = _now()
+
+    await db.commit()
+    await db.refresh(ctrl)
+    return Envelope(data=_to_out(ctrl))
+
+
+@router.get("", response_model=Envelope[list[ControlOut]])
+async def list_controls(
+    db: Annotated[AsyncSession, Depends(get_db)],
+    pillar: str | None = Query(default=None, description="Filter by pillar name."),
+    severity: str | None = Query(default=None, description="Filter by severity level."),
+    page: int = Query(default=1, ge=1, description="1-based page number."),
+    per_page: int = Query(default=50, ge=1, le=200, description="Results per page."),
+) -> Envelope[list[ControlOut]]:
+    """List controls, optionally filtered by pillar and/or severity."""
+    base = select(Control)
+    count_base = select(func.count()).select_from(Control)
+
+    if pillar:
+        base = base.where(Control.pillar == pillar.lower())
+        count_base = count_base.where(Control.pillar == pillar.lower())
+    if severity:
+        base = base.where(Control.severity == severity.lower())
+        count_base = count_base.where(Control.severity == severity.lower())
+
+    total: int = (await db.execute(count_base)).scalar() or 0
+
+    offset = (page - 1) * per_page
+    stmt = base.order_by(Control.created_at.desc()).limit(per_page).offset(offset)
+    result = await db.execute(stmt)
+    controls = list(result.scalars().all())
+
+    return Envelope(
+        data=[_to_out(c) for c in controls],
+        meta=Meta(total=total, page=page, per_page=per_page),
+    )
+
+
+@router.get("/{control_id}", response_model=Envelope[ControlOut])
+async def get_control(
+    control_id: str,
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> Envelope[ControlOut]:
+    """Return a single control by ID."""
+    ctrl = await db.get(Control, control_id.upper())
+    if ctrl is None:
+        # Also try as-provided (case-sensitive stored IDs)
+        ctrl = await db.get(Control, control_id)
+    if ctrl is None:
+        raise HTTPException(status_code=404, detail=f"Control '{control_id}' not found")
+    return Envelope(data=_to_out(ctrl))
+
+
+@router.delete("/{control_id}", status_code=204)
+async def delete_control(
+    control_id: str,
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> None:
+    """Remove a control by ID."""
+    ctrl = await db.get(Control, control_id.upper())
+    if ctrl is None:
+        ctrl = await db.get(Control, control_id)
+    if ctrl is None:
+        raise HTTPException(status_code=404, detail=f"Control '{control_id}' not found")
+    await db.delete(ctrl)
+    await db.commit()

wafpass_server-0.3.4/wafpass_server/routers/runs.py

@@ -0,0 +1,101 @@
+"""POST/GET /runs endpoints."""
+from __future__ import annotations
+
+import uuid
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from wafpass_server.database import get_db
+from wafpass_server.models import Run
+from wafpass_server.schemas import ControlMetaSchema, FindingSchema, RunCreate, RunDetail, RunSummary
+
+router = APIRouter(prefix="/runs", tags=["runs"])
+
+
+@router.post("", response_model=RunSummary, status_code=201)
+async def create_run(
+    payload: RunCreate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> Run:
+    run = Run(
+        project=payload.project,
+        branch=payload.branch,
+        git_sha=payload.git_sha,
+        triggered_by=payload.triggered_by,
+        iac_framework=payload.iac_framework,
+        score=payload.score,
+        pillar_scores=payload.pillar_scores,
+        findings=[f.model_dump() for f in payload.findings],
+        path=payload.path,
+        controls_loaded=payload.controls_loaded,
+        controls_run=payload.controls_run,
+        detected_regions=payload.detected_regions,
+        source_paths=payload.source_paths,
+        controls_meta=[c.model_dump() for c in payload.controls_meta],
+        plan_changes=payload.plan_changes,
+    )
+    db.add(run)
+    await db.commit()
+    await db.refresh(run)
+    return run
+
+
+@router.get("", response_model=list[RunSummary])
+async def list_runs(
+    db: Annotated[AsyncSession, Depends(get_db)],
+    limit: int = Query(default=50, ge=1, le=200),
+    offset: int = Query(default=0, ge=0),
+    project: str | None = Query(default=None),
+) -> list[Run]:
+    stmt = select(Run).order_by(Run.created_at.desc()).limit(limit).offset(offset)
+    if project:
+        stmt = stmt.where(Run.project == project)
+    result = await db.execute(stmt)
+    return list(result.scalars().all())
+
+
+@router.get("/{run_id}", response_model=RunDetail)
+async def get_run(
+    run_id: uuid.UUID,
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> Run:
+    run = await db.get(Run, run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail="Run not found")
+    return run
+
+
+@router.get("/{run_id}/controls", response_model=list[ControlMetaSchema])
+async def get_controls(
+    run_id: uuid.UUID,
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> list[dict]:
+    run = await db.get(Run, run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail="Run not found")
+    return run.controls_meta or []
+
+
+@router.get("/{run_id}/findings", response_model=list[FindingSchema])
+async def get_findings(
+    run_id: uuid.UUID,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    severity: str | None = Query(default=None),
+    pillar: str | None = Query(default=None),
+    status: str | None = Query(default=None),
+) -> list[dict]:
+    run = await db.get(Run, run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail="Run not found")
+
+    findings: list[dict] = run.findings or []
+    if severity:
+        findings = [f for f in findings if f.get("severity", "").upper() == severity.upper()]
+    if pillar:
+        findings = [f for f in findings if f.get("pillar", "").upper() == pillar.upper()]
+    if status:
+        findings = [f for f in findings if f.get("status", "").upper() == status.upper()]
+    return findings

wafpass_server-0.3.4/wafpass_server/schemas.py

@@ -0,0 +1,136 @@
+"""Pydantic schemas for the API layer."""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Re-export control schema types from wafpass-core so callers only need one import.
+from wafpass.control_schema import WizardCheck, WizardControl  # noqa: F401
+
+# ── Generic response envelope ─────────────────────────────────────────────────
+
+T = TypeVar("T")
+
+
+class Meta(BaseModel):
+    total: int | None = None
+    page: int | None = None
+    per_page: int | None = None
+
+
+class Envelope(BaseModel, Generic[T]):
+    """Consistent API response wrapper used by all /controls endpoints."""
+
+    data: T
+    meta: Meta = Field(default_factory=Meta)
+
+
+class FindingSchema(BaseModel):
+    check_id: str
+    check_title: str
+    control_id: str
+    pillar: str = ""
+    severity: str
+    status: str
+    resource: str
+    message: str
+    remediation: str
+    example: dict[str, Any] | None = None
+
+
+class ControlCheckMetaSchema(BaseModel):
+    id: str
+    title: str
+    severity: str
+    remediation: str = ""
+    example: dict[str, Any] | None = None
+
+
+class ControlMetaSchema(BaseModel):
+    id: str
+    title: str
+    pillar: str
+    severity: str
+    category: str = ""
+    description: str = ""
+    rationale: str = ""
+    threat: list[str] = Field(default_factory=list)
+    regulatory_mapping: list[dict[str, Any]] = Field(default_factory=list)
+    checks: list[ControlCheckMetaSchema] = Field(default_factory=list)
+
+
+class RunCreate(BaseModel):
+    """Payload accepted by POST /runs — matches wafpass-result.json schema."""
+    schema_version: str = "1.0"
+    project: str = ""
+    branch: str = ""
+    git_sha: str = ""
+    triggered_by: str = "local"
+    iac_framework: str = "terraform"
+    score: int = Field(default=0, ge=0, le=100)
+    pillar_scores: dict[str, int] = Field(default_factory=dict)
+    path: str = ""
+    controls_loaded: int = 0
+    controls_run: int = 0
+    detected_regions: list[list[str]] = Field(default_factory=list)
+    source_paths: list[str] = Field(default_factory=list)
+    controls_meta: list[ControlMetaSchema] = Field(default_factory=list)
+    findings: list[FindingSchema] = Field(default_factory=list)
+    plan_changes: dict[str, Any] | None = None
+
+
+class RunSummary(BaseModel):
+    id: uuid.UUID
+    project: str
+    branch: str
+    git_sha: str
+    triggered_by: str
+    iac_framework: str
+    score: int
+    pillar_scores: dict[str, int]
+    path: str
+    controls_loaded: int
+    controls_run: int
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class RunDetail(RunSummary):
+    findings: list[dict[str, Any]]
+    detected_regions: list[list[str]]
+    source_paths: list[str]
+    controls_meta: list[dict[str, Any]]
+    plan_changes: dict[str, Any] | None = None
+
+    model_config = {"from_attributes": True}
+
+
+# ── Control schemas ───────────────────────────────────────────────────────────
+
+
+class ControlIn(WizardControl):
+    """Request body for POST /controls.
+
+    Extends WizardControl (from wafpass-core) with an optional ``source``
+    field indicating the authoring origin.
+    """
+
+    source: str = "wafpass"
+
+
+class ControlOut(WizardControl):
+    """Response schema for /controls endpoints.
+
+    Extends WizardControl with server-managed timestamp fields.
+    ``from_attributes=True`` enables construction from SQLAlchemy ORM rows.
+    """
+
+    source: str
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)