wafpass-server 0.3.4__py3-none-any.whl

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/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/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/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/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/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/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/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)

wafpass_server-0.3.4.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+wafpass_server/__init__.py,sha256=9EoKGeTrY5JnBKcERuTMzJtP34xpSQ0RqD2dOJv52es,191
+wafpass_server/config.py,sha256=XU8ea65sgb-oQIPO-kBBb_hfzJAWouvesmKjCYaOwyQ,650
+wafpass_server/database.py,sha256=uecjB4WgDW7ujKMpcpcHdozlDTO7HqX4vjyGK--xPd0,632
+wafpass_server/main.py,sha256=pMtQqFhVu5-hKpH8ywTWJE45wOCOwsTYdfNVITVCPH0,1230
+wafpass_server/models.py,sha256=mUYvO8cZ6Dn9gDjJjQPQDB8mH1hfThCrFoNHwFR1v1g,2270
+wafpass_server/schemas.py,sha256=to39HnfYpNi7dxElrOHwZCneT8Ffzk4aMdy6G2vdoAI,3784
+wafpass_server/routers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wafpass_server/routers/controls.py,sha256=O2CoIGWWNeT81Qw4pO5HnUxIvG1brk-Th-wu7wbH6ys,4491
+wafpass_server/routers/runs.py,sha256=y_etZa7h7tbmKJobY8KHlVAI6FLQrzB-uk8Z4WD76cU,3386
+wafpass_server-0.3.4.dist-info/METADATA,sha256=4UT9JCSCp646NYyWaJ4Lh_9FLpcq19OMt2AVg6tggIA,3549
+wafpass_server-0.3.4.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+wafpass_server-0.3.4.dist-info/entry_points.txt,sha256=1PNS1zNpHTnOPK6zZ8AwIBMXndvXpPVnXieBRVPRlNE,61
+wafpass_server-0.3.4.dist-info/RECORD,,

wafpass_server-0.3.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

wafpass_server-0.3.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wafpass-server = wafpass_server.main:start