nat-engine 1__py3-none-any.whl

mannf/product/middleware/tenant_isolation.py

@@ -0,0 +1,114 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+
+"""Tenant data isolation dependency for FastAPI route injection.
+
+Usage in a route::
+
+    from mannf.product.middleware.tenant_isolation import get_current_tenant
+
+    @app.get("/api/v1/some-endpoint")
+    async def some_endpoint(
+        request: Request,
+        tenant: dict = Depends(get_current_tenant),
+    ) -> ...:
+        # tenant is guaranteed to be the authenticated tenant dict
+        ...
+
+When ``NAT_API_KEY`` legacy mode is in use (no DB tenant), this dependency
+returns ``None`` — callers can choose to gate multi-tenant logic on
+``tenant is not None`` to preserve backward compatibility.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import HTTPException, Request
+
+
+async def get_current_tenant(request: Request) -> dict:
+    """FastAPI dependency that extracts the authenticated tenant.
+
+    Returns the tenant dict from ``request.state.tenant`` when a tenant has
+    been resolved by the auth middleware.
+
+    Raises ``HTTP 401`` if no tenant is authenticated (DB mode with no valid
+    API key, or API key not present).
+
+    In legacy ``NAT_API_KEY`` mode, ``request.state.tenant`` is ``None``.
+    Use :func:`get_optional_tenant` if you need backward-compatible behaviour
+    where unauthenticated/legacy access is still permitted.
+    """
+    tenant = getattr(request.state, "tenant", None)
+    if tenant is None:
+        raise HTTPException(
+            status_code=401,
+            detail="Authentication required",
+        )
+    return tenant
+
+
+async def get_optional_tenant(request: Request) -> Optional[dict]:
+    """FastAPI dependency that returns the tenant or ``None`` in legacy mode.
+
+    Use this on endpoints that must remain backward-compatible with the legacy
+    ``NAT_API_KEY`` environment variable.  The returned value is either:
+
+    - ``dict`` — the authenticated tenant record, or
+    - ``None`` — legacy mode (no DB tenant; auth still validated by middleware).
+    """
+    return getattr(request.state, "tenant", None)
+
+
+async def get_current_user(request: Request) -> dict:
+    """Return the authenticated user dict from request.state.user.
+
+    Raises HTTP 401 if no user is set on the request state.
+    The user is set by the SAML/SSO auth path in the middleware.
+    When using API key auth (not SSO), this returns a synthetic user dict
+    derived from the tenant record.
+    """
+    user = getattr(request.state, "user", None)
+    if user is None:
+        # Fallback: synthesize a minimal user from the tenant if available
+        tenant = getattr(request.state, "tenant", None)
+        if tenant is not None:
+            # API-key auth: synthesize a user with admin role for backward compat
+            return {
+                "id": None,
+                "email": tenant.get("email", ""),
+                "name": tenant.get("name", ""),
+                "role": "admin",
+                "tenant_id": tenant.get("tenant_id") or str(tenant.get("id", "")),
+            }
+        raise HTTPException(status_code=401, detail="Authentication required")
+    return user
+
+
+def require_role(*allowed_roles: str):
+    """FastAPI dependency factory that enforces RBAC.
+
+    Usage::
+
+        @app.post("/api/v1/scan")
+        async def trigger_scan(
+            user: dict = Depends(require_role("admin", "operator")),
+        ):
+            ...
+    """
+    async def _check_role(request: Request) -> dict:
+        user = await get_current_user(request)
+        if user.get("role") not in allowed_roles:
+            raise HTTPException(
+                status_code=403,
+                detail={
+                    "error": {
+                        "code": "INSUFFICIENT_ROLE",
+                        "message": f"Role {user.get('role')!r} is not permitted. Required: {list(allowed_roles)}",
+                    }
+                },
+            )
+        return user
+    return _check_role

mannf/product/models.py

@@ -0,0 +1,347 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+
+"""SQLAlchemy ORM models for the NAT persistence layer.
+
+Tables:
+- scans              — replaces the ``_scans`` in-memory dict
+- security_scans     — replaces ``_security_scans``
+- healing_reports    — replaces ``_healing_reports``
+- tenants            — SaaS tenant / organisation records
+- api_keys           — hashed API keys linked to tenants
+- usage_records      — per-month scan usage metering
+- billing_events     — auditable log of billing lifecycle events
+- autonomous_runs    — replaces the ``_autonomous_runs`` in-memory dict
+- discovery_runs     — replaces the ``_discoveries`` in-memory dict
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from mannf.product.database import Base
+
+try:
+    from sqlalchemy import Boolean, DateTime, ForeignKey, Index, Integer, String, Text
+    from sqlalchemy.dialects.postgresql import JSON, UUID
+    from sqlalchemy.orm import Mapped, mapped_column
+    from sqlalchemy.sql import func
+
+    class Scan(Base):
+        """Persistent record for a functional (NAT) scan."""
+
+        __tablename__ = "scans"
+
+        id: Mapped[uuid.UUID] = mapped_column(
+            UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+        )
+        status: Mapped[str] = mapped_column(String(32), nullable=False, index=True)
+        created_at: Mapped[DateTime] = mapped_column(
+            DateTime(timezone=True), server_default=func.now(), nullable=False
+        )
+        completed_at: Mapped[DateTime | None] = mapped_column(
+            DateTime(timezone=True), nullable=True
+        )
+        spec_name: Mapped[str | None] = mapped_column(String(512), nullable=True)
+        base_url: Mapped[str | None] = mapped_column(String(2048), nullable=True)
+        summary: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+        results: Mapped[list | None] = mapped_column(JSON, nullable=True)
+        error: Mapped[str | None] = mapped_column(Text, nullable=True)
+        prioritization: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+        llm_cases_generated: Mapped[int] = mapped_column(
+            Integer, nullable=False, default=0
+        )
+        healing_summary: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+        tenant_id: Mapped[uuid.UUID | None] = mapped_column(
+            UUID(as_uuid=True),
+            ForeignKey("tenants.id"),
+            nullable=True,
+            index=True,
+        )
+
+    class SecurityScan(Base):
+        """Persistent record for an OWASP security scan."""
+
+        __tablename__ = "security_scans"
+
+        id: Mapped[uuid.UUID] = mapped_column(
+            UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+        )
+        status: Mapped[str] = mapped_column(String(32), nullable=False, index=True)
+        created_at: Mapped[DateTime] = mapped_column(
+            DateTime(timezone=True), server_default=func.now(), nullable=False
+        )
+        completed_at: Mapped[DateTime | None] = mapped_column(
+            DateTime(timezone=True), nullable=True
+        )
+        spec_name: Mapped[str | None] = mapped_column(String(512), nullable=True)
+        base_url: Mapped[str | None] = mapped_column(String(2048), nullable=True)
+        report: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+        error: Mapped[str | None] = mapped_column(Text, nullable=True)
+        tenant_id: Mapped[uuid.UUID | None] = mapped_column(
+            UUID(as_uuid=True),
+            ForeignKey("tenants.id"),
+            nullable=True,
+            index=True,
+        )
+
+    class HealingReport(Base):
+        """Persistent record for a self-healing analysis report."""
+
+        __tablename__ = "healing_reports"
+
+        id: Mapped[uuid.UUID] = mapped_column(
+            UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+        )
+        created_at: Mapped[DateTime] = mapped_column(
+            DateTime(timezone=True), server_default=func.now(), nullable=False
+        )
+        report_data: Mapped[dict] = mapped_column(JSON, nullable=False)
+        tenant_id: Mapped[uuid.UUID | None] = mapped_column(
+            UUID(as_uuid=True),
+            ForeignKey("tenants.id"),
+            nullable=True,
+            index=True,
+        )
+
+    class Tenant(Base):
+        """SaaS tenant / organisation record."""
+
+        __tablename__ = "tenants"
+
+        id: Mapped[uuid.UUID] = mapped_column(
+            UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+        )
+        name: Mapped[str] = mapped_column(String(256), nullable=False)
+        email: Mapped[str] = mapped_column(String(512), nullable=False, unique=True)
+        plan_tier: Mapped[str] = mapped_column(
+            String(32), nullable=False, default="free"
+        )
+        stripe_customer_id: Mapped[str | None] = mapped_column(
+            String(256), nullable=True, unique=True
+        )
+        stripe_subscription_id: Mapped[str | None] = mapped_column(
+            String(256), nullable=True
+        )
+        monthly_scan_quota: Mapped[int] = mapped_column(
+            Integer, nullable=False, default=50
+        )
+        monthly_security_scan_quota: Mapped[int] = mapped_column(
+            Integer, nullable=False, default=10
+        )
+        max_concurrent_scans: Mapped[int] = mapped_column(
+            Integer, nullable=False, default=1
+        )
+        is_active: Mapped[bool] = mapped_column(
+            Boolean, nullable=False, default=True
+        )
+        notification_slack_webhook_url: Mapped[str | None] = mapped_column(
+            String(2048), nullable=True
+        )
+        notification_teams_webhook_url: Mapped[str | None] = mapped_column(
+            String(2048), nullable=True
+        )
+        created_at: Mapped[DateTime] = mapped_column(
+            DateTime(timezone=True), server_default=func.now(), nullable=False
+        )
+        updated_at: Mapped[DateTime] = mapped_column(
+            DateTime(timezone=True),
+            server_default=func.now(),
+            onupdate=func.now(),
+            nullable=False,
+        )
+
+    class ApiKey(Base):
+        """Hashed API key linked to a tenant."""
+
+        __tablename__ = "api_keys"
+
+        id: Mapped[uuid.UUID] = mapped_column(
+            UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+        )
+        tenant_id: Mapped[uuid.UUID] = mapped_column(
+            UUID(as_uuid=True),
+            ForeignKey("tenants.id"),
+            nullable=False,
+            index=True,
+        )
+        key_hash: Mapped[str] = mapped_column(String(128), nullable=False, unique=True)
+        key_prefix: Mapped[str] = mapped_column(String(12), nullable=False)
+        label: Mapped[str | None] = mapped_column(String(256), nullable=True)
+        is_active: Mapped[bool] = mapped_column(
+            Boolean, nullable=False, default=True
+        )
+        created_at: Mapped[DateTime] = mapped_column(
+            DateTime(timezone=True), server_default=func.now(), nullable=False
+        )
+        last_used_at: Mapped[DateTime | None] = mapped_column(
+            DateTime(timezone=True), nullable=True
+        )
+
+    class UsageRecord(Base):
+        """Per-month scan usage record for quota metering."""
+
+        __tablename__ = "usage_records"
+
+        id: Mapped[uuid.UUID] = mapped_column(
+            UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+        )
+        tenant_id: Mapped[uuid.UUID] = mapped_column(
+            UUID(as_uuid=True),
+            ForeignKey("tenants.id"),
+            nullable=False,
+            index=True,
+        )
+        scan_type: Mapped[str] = mapped_column(String(32), nullable=False)
+        scan_id: Mapped[uuid.UUID | None] = mapped_column(
+            UUID(as_uuid=True), nullable=True
+        )
+        recorded_at: Mapped[DateTime] = mapped_column(
+            DateTime(timezone=True), server_default=func.now(), nullable=False
+        )
+        period_year: Mapped[int] = mapped_column(Integer, nullable=False)
+        period_month: Mapped[int] = mapped_column(Integer, nullable=False)
+
+        __table_args__ = (
+            Index(
+                "ix_usage_records_tenant_period",
+                "tenant_id",
+                "period_year",
+                "period_month",
+                "scan_type",
+            ),
+        )
+
+    class BillingEvent(Base):
+        """Auditable log of billing lifecycle events."""
+
+        __tablename__ = "billing_events"
+
+        id: Mapped[uuid.UUID] = mapped_column(
+            UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+        )
+        tenant_id: Mapped[uuid.UUID | None] = mapped_column(
+            UUID(as_uuid=True),
+            ForeignKey("tenants.id"),
+            nullable=True,
+            index=True,
+        )
+        event_type: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+        source: Mapped[str] = mapped_column(
+            String(32), nullable=False, default="system"
+        )
+        details: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+        created_at: Mapped[DateTime] = mapped_column(
+            DateTime(timezone=True), server_default=func.now(), nullable=False, index=True
+        )
+
+    class AutonomousRun(Base):
+        """Persistent record for an autonomous test-loop run."""
+
+        __tablename__ = "autonomous_runs"
+
+        id: Mapped[uuid.UUID] = mapped_column(
+            UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+        )
+        status: Mapped[str] = mapped_column(String(32), nullable=False, index=True)
+        target_url: Mapped[str | None] = mapped_column(String(2048), nullable=True)
+        strategy: Mapped[str | None] = mapped_column(String(64), nullable=True)
+        report: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+        error: Mapped[str | None] = mapped_column(Text, nullable=True)
+        created_at: Mapped[DateTime] = mapped_column(
+            DateTime(timezone=True), server_default=func.now(), nullable=False
+        )
+        completed_at: Mapped[DateTime | None] = mapped_column(
+            DateTime(timezone=True), nullable=True
+        )
+        last_heartbeat_at: Mapped[DateTime | None] = mapped_column(
+            DateTime(timezone=True), nullable=True
+        )
+        tenant_id: Mapped[uuid.UUID | None] = mapped_column(
+            UUID(as_uuid=True),
+            ForeignKey("tenants.id"),
+            nullable=True,
+            index=True,
+        )
+
+    class DiscoveryRun(Base):
+        """Persistent record for a discovery crawl + scenario generation run."""
+
+        __tablename__ = "discovery_runs"
+
+        id: Mapped[uuid.UUID] = mapped_column(
+            UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+        )
+        status: Mapped[str] = mapped_column(String(32), nullable=False, index=True)
+        base_url: Mapped[str | None] = mapped_column(String(2048), nullable=True)
+        scenarios: Mapped[list | None] = mapped_column(JSON, nullable=True)
+        stats: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+        error: Mapped[str | None] = mapped_column(Text, nullable=True)
+        created_at: Mapped[DateTime] = mapped_column(
+            DateTime(timezone=True), server_default=func.now(), nullable=False
+        )
+        tenant_id: Mapped[uuid.UUID | None] = mapped_column(
+            UUID(as_uuid=True),
+            ForeignKey("tenants.id"),
+            nullable=True,
+            index=True,
+        )
+
+    class Workspace(Base):
+        __tablename__ = "workspaces"
+        id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+        tenant_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("tenants.id"), nullable=False, index=True)
+        name: Mapped[str] = mapped_column(String(256), nullable=False)
+        description: Mapped[str | None] = mapped_column(Text, nullable=True)
+        is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+        created_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+        updated_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
+
+    class Project(Base):
+        __tablename__ = "projects"
+        id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+        workspace_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("workspaces.id"), nullable=False, index=True)
+        tenant_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("tenants.id"), nullable=False, index=True)
+        name: Mapped[str] = mapped_column(String(256), nullable=False)
+        description: Mapped[str | None] = mapped_column(Text, nullable=True)
+        parent_project_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), ForeignKey("projects.id"), nullable=True)
+        is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+        created_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+        updated_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
+
+    class User(Base):
+        __tablename__ = "users"
+        id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+        tenant_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("tenants.id"), nullable=False, index=True)
+        email: Mapped[str] = mapped_column(String(512), nullable=False)
+        name: Mapped[str] = mapped_column(String(256), nullable=False)
+        sso_subject: Mapped[str | None] = mapped_column(String(512), nullable=True, unique=True)
+        is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+        created_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+        updated_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
+        __table_args__ = (Index("uq_users_email_tenant", "email", "tenant_id", unique=True),)
+
+    class UserRole(Base):
+        __tablename__ = "user_roles"
+        id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+        user_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False, index=True)
+        tenant_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("tenants.id"), nullable=False, index=True)
+        workspace_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), ForeignKey("workspaces.id"), nullable=True)
+        role: Mapped[str] = mapped_column(String(32), nullable=False)
+        created_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    class ApiAuditLog(Base):
+        __tablename__ = "api_audit_log"
+        id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+        tenant_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), ForeignKey("tenants.id"), nullable=True, index=True)
+        user_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
+        method: Mapped[str] = mapped_column(String(10), nullable=False)
+        path: Mapped[str] = mapped_column(String(2048), nullable=False)
+        status_code: Mapped[int] = mapped_column(Integer, nullable=False)
+        request_summary: Mapped[str | None] = mapped_column(Text, nullable=True)
+        source_ip: Mapped[str | None] = mapped_column(String(64), nullable=True)
+        created_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False, index=True)
+
+except ImportError:  # pragma: no cover — SQLAlchemy not installed
+    pass

mannf/product/notifications/__init__.py

@@ -0,0 +1,24 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+
+"""Product notification service for scan lifecycle events.
+
+Delivers real-time notifications to Slack and Microsoft Teams via incoming
+webhooks whenever key scan or platform events occur.
+
+Usage::
+
+    from mannf.product.notifications import dispatch_scan_notification
+
+    await dispatch_scan_notification(
+        "scan.completed",
+        tenant_id="<uuid>",
+        scan_id="<uuid>",
+        details={"total": 10, "passed": 9, "failed": 1},
+    )
+"""
+
+from mannf.product.notifications.dispatcher import dispatch_scan_notification
+
+__all__ = ["dispatch_scan_notification"]