nat-engine 1__py3-none-any.whl

mannf/product/notifications/dispatcher.py

@@ -0,0 +1,411 @@
+# 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 dispatcher for scan lifecycle events.
+
+Delivers formatted notifications to Slack (Block Kit) and Microsoft Teams
+(Adaptive Cards) via incoming webhooks.  Both channels use a plain HTTP POST
+with a JSON payload — no SDK required.
+
+Webhook URLs are resolved in this order:
+1. Per-tenant ``notification_slack_webhook_url`` / ``notification_teams_webhook_url``
+   stored in the DB (populated via ``PUT /api/v1/notifications/config``).
+2. Global env var fallback: ``NAT_SLACK_WEBHOOK_URL`` / ``NAT_TEAMS_WEBHOOK_URL``.
+
+Supported event types (scan lifecycle):
+- ``scan.started``
+- ``scan.completed``
+- ``scan.failed``
+- ``security_scan.completed``
+- ``security_scan.failed``
+- ``autonomous_run.regression``
+- ``autonomous_run.recovery``
+- ``autonomous_run.flake_spike``
+- ``plan.generated``
+- ``plan.approved``
+- ``finding.commented``
+- ``schedule.fired``
+- ``e2e.regression``
+
+All delivery errors are caught and logged — notifications must never block or
+break the scan flow.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import hmac
+import json
+import logging
+import os
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Event metadata helpers
+# ---------------------------------------------------------------------------
+
+_EVENT_EMOJI: dict[str, str] = {
+    "scan.started": "🚀",
+    "scan.completed": "✅",
+    "scan.failed": "❌",
+    "security_scan.completed": "🔒",
+    "security_scan.failed": "🚨",
+    "autonomous_run.regression": "🔴",
+    "autonomous_run.recovery": "🟢",
+    "autonomous_run.flake_spike": "⚡",
+    "plan.generated": "📋",
+    "plan.approved": "🏷️",
+    "finding.commented": "💬",
+    "schedule.fired": "🗓️",
+    "e2e.regression": "🔴",
+}
+
+_EVENT_TITLE: dict[str, str] = {
+    "scan.started": "Scan Started",
+    "scan.completed": "Scan Completed",
+    "scan.failed": "Scan Failed",
+    "security_scan.completed": "Security Scan Completed",
+    "security_scan.failed": "Security Scan Failed",
+    "autonomous_run.regression": "Autonomous Run — New Regression",
+    "autonomous_run.recovery": "Autonomous Run — Recovery Detected",
+    "autonomous_run.flake_spike": "Autonomous Run — Flakiness Spike",
+    "plan.generated": "Test Plan Generated",
+    "plan.approved": "Test Plan Approved",
+    "finding.commented": "Finding Commented",
+    "schedule.fired": "Schedule Fired",
+    "e2e.regression": "E2E Regression Detected",
+}
+
+
+# ---------------------------------------------------------------------------
+# Slack notifier
+# ---------------------------------------------------------------------------
+
+
+class SlackNotifier:
+    """Deliver a formatted Slack message via an incoming webhook URL.
+
+    Uses Slack Block Kit for rich message formatting.
+    """
+
+    def __init__(self, webhook_url: str) -> None:
+        self.webhook_url = webhook_url
+
+    def _build_payload(self, event_type: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Build a Slack Block Kit message payload."""
+        emoji = _EVENT_EMOJI.get(event_type, "🔔")
+        title = f"{emoji} NAT — {_EVENT_TITLE.get(event_type, event_type)}"
+
+        fields = [
+            {
+                "type": "mrkdwn",
+                "text": f"*Event:*\n`{event_type}`",
+            },
+        ]
+        if payload.get("scan_id"):
+            fields.append(
+                {"type": "mrkdwn", "text": f"*Scan ID:*\n`{payload['scan_id']}`"}
+            )
+        if payload.get("tenant_id"):
+            fields.append(
+                {"type": "mrkdwn", "text": f"*Tenant:*\n`{payload['tenant_id']}`"}
+            )
+
+        blocks: list[dict[str, Any]] = [
+            {
+                "type": "header",
+                "text": {"type": "plain_text", "text": title, "emoji": True},
+            },
+            {"type": "section", "fields": fields},
+        ]
+
+        details = payload.get("details") or {}
+        if details:
+            detail_lines = [f"*{k}:* {v}" for k, v in details.items()]
+            blocks.append(
+                {
+                    "type": "section",
+                    "text": {"type": "mrkdwn", "text": "\n".join(detail_lines)},
+                }
+            )
+
+        return {"blocks": blocks}
+
+    async def send(self, event_type: str, payload: dict[str, Any]) -> None:
+        """POST the formatted payload to the Slack webhook URL."""
+        slack_payload = self._build_payload(event_type, payload)
+        await _http_post(self.webhook_url, slack_payload)
+
+
+# ---------------------------------------------------------------------------
+# Microsoft Teams notifier
+# ---------------------------------------------------------------------------
+
+
+class TeamsNotifier:
+    """Deliver a formatted Teams message via an incoming webhook connector.
+
+    Uses Adaptive Cards for rich card formatting.
+    """
+
+    def __init__(self, webhook_url: str) -> None:
+        self.webhook_url = webhook_url
+
+    def _build_payload(self, event_type: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Build a Teams Adaptive Card message payload."""
+        emoji = _EVENT_EMOJI.get(event_type, "🔔")
+        title = f"{emoji} NAT — {_EVENT_TITLE.get(event_type, event_type)}"
+
+        body: list[dict[str, Any]] = [
+            {
+                "type": "TextBlock",
+                "text": title,
+                "weight": "Bolder",
+                "size": "Medium",
+            },
+        ]
+
+        facts: list[dict[str, str]] = [{"title": "Event", "value": event_type}]
+        if payload.get("scan_id"):
+            facts.append({"title": "Scan ID", "value": str(payload["scan_id"])})
+        if payload.get("tenant_id"):
+            facts.append({"title": "Tenant", "value": str(payload["tenant_id"])})
+
+        details = payload.get("details") or {}
+        for k, v in details.items():
+            facts.append({"title": str(k).replace("_", " ").title(), "value": str(v)})
+
+        body.append({"type": "FactSet", "facts": facts})
+
+        adaptive_card = {
+            "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+            "type": "AdaptiveCard",
+            "version": "1.4",
+            "body": body,
+        }
+
+        return {
+            "type": "message",
+            "attachments": [
+                {
+                    "contentType": "application/vnd.microsoft.card.adaptive",
+                    "contentUrl": None,
+                    "content": adaptive_card,
+                }
+            ],
+        }
+
+    async def send(self, event_type: str, payload: dict[str, Any]) -> None:
+        """POST the formatted payload to the Teams webhook URL."""
+        teams_payload = self._build_payload(event_type, payload)
+        await _http_post(self.webhook_url, teams_payload)
+
+
+# ---------------------------------------------------------------------------
+# Public dispatcher
+# ---------------------------------------------------------------------------
+
+
+async def dispatch_scan_notification(
+    event_type: str,
+    *,
+    tenant_id: Optional[str] = None,
+    scan_id: Optional[str] = None,
+    details: Optional[dict[str, Any]] = None,
+) -> None:
+    """Dispatch a scan lifecycle notification to all configured channels.
+
+    Resolves Slack and Teams webhook URLs from:
+    1. Per-tenant DB fields (``notification_slack_webhook_url`` /
+       ``notification_teams_webhook_url`` on the ``tenants`` table).
+    2. Global env var fallback (``NAT_SLACK_WEBHOOK_URL`` /
+       ``NAT_TEAMS_WEBHOOK_URL``).
+
+    All failures are swallowed and logged — notifications must never break
+    the scan flow.
+
+    Args:
+        event_type: Scan event identifier, e.g. ``"scan.completed"``.
+        tenant_id: UUID string of the tenant that owns the scan.
+        scan_id: UUID string of the affected scan.
+        details: Additional event context (scan summary counts, error info).
+    """
+    payload: dict[str, Any] = {
+        "event_type": event_type,
+        "tenant_id": tenant_id,
+        "scan_id": scan_id,
+        "details": details or {},
+    }
+
+    slack_url = await _resolve_webhook_url(tenant_id, "slack")
+    teams_url = await _resolve_webhook_url(tenant_id, "teams")
+
+    tasks: list[Any] = []
+    if slack_url:
+        tasks.append(SlackNotifier(slack_url).send(event_type, payload))
+    if teams_url:
+        tasks.append(TeamsNotifier(teams_url).send(event_type, payload))
+
+    if not tasks:
+        logger.debug(
+            "No notification channels configured for scan event: %s (tenant=%s)",
+            event_type,
+            tenant_id,
+        )
+        return
+
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+    for i, result in enumerate(results):
+        if isinstance(result, Exception):
+            logger.warning(
+                "Scan notification delivery failed (task %d) for event %s: %s",
+                i,
+                event_type,
+                result,
+            )
+
+
+# ---------------------------------------------------------------------------
+# URL resolution
+# ---------------------------------------------------------------------------
+
+
+async def _resolve_webhook_url(
+    tenant_id: Optional[str], channel: str
+) -> str:
+    """Resolve the webhook URL for a given channel.
+
+    Tries the per-tenant DB field first, then falls back to the global env var.
+
+    Args:
+        tenant_id: Tenant UUID string (or None for anonymous scans).
+        channel: ``"slack"`` or ``"teams"``.
+
+    Returns:
+        Webhook URL string, or empty string if not configured.
+    """
+    env_var = "NAT_SLACK_WEBHOOK_URL" if channel == "slack" else "NAT_TEAMS_WEBHOOK_URL"
+    db_field = (
+        "notification_slack_webhook_url"
+        if channel == "slack"
+        else "notification_teams_webhook_url"
+    )
+
+    if tenant_id:
+        try:
+            db_url = await _get_tenant_webhook_url(tenant_id, db_field)
+            if db_url:
+                return db_url
+        except Exception as exc:  # noqa: BLE001
+            logger.debug(
+                "_resolve_webhook_url: DB lookup failed for tenant %s (%s): %s",
+                tenant_id,
+                channel,
+                exc,
+            )
+
+    return os.environ.get(env_var, "")
+
+
+async def _get_tenant_webhook_url(tenant_id: str, field: str) -> str:
+    """Fetch a webhook URL field from the tenant record in the DB.
+
+    Returns empty string if DB is unavailable or field is null.
+    """
+    try:
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+
+        if _build_engine() is None or _async_session_factory is None:
+            return ""
+
+        import uuid  # noqa: PLC0415
+
+        from mannf.product.models import Tenant  # noqa: PLC0415
+
+        tid = uuid.UUID(tenant_id)
+        async with _async_session_factory() as session:
+            tenant = await session.get(Tenant, tid)
+            if tenant is None:
+                return ""
+            return getattr(tenant, field, None) or ""
+    except Exception:  # noqa: BLE001
+        return ""
+
+
+# ---------------------------------------------------------------------------
+# HTTP delivery backend
+# ---------------------------------------------------------------------------
+
+
+async def _http_post(
+    url: str,
+    payload: dict[str, Any],
+    *,
+    timeout: float = 10.0,
+    signing_secret: Optional[str] = None,
+) -> None:
+    """POST a JSON payload to the given URL.
+
+    Optionally adds an HMAC signature header (``X-NAT-Signature``) when
+    ``NAT_NOTIFICATION_WEBHOOK_SECRET`` is set or ``signing_secret`` is
+    provided.
+
+    Args:
+        url: Target webhook endpoint.
+        payload: JSON-serialisable message payload.
+        timeout: Request timeout in seconds.
+        signing_secret: Override for the signing secret (defaults to
+            ``NAT_NOTIFICATION_WEBHOOK_SECRET`` env var).
+
+    Raises:
+        RuntimeError: on network error or unexpected exception.
+    """
+    try:
+        import aiohttp  # noqa: PLC0415
+    except ImportError:
+        logger.warning(
+            "_http_post: aiohttp not installed — notification delivery skipped"
+        )
+        return
+
+    try:
+        body = json.dumps(payload, default=str)
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "User-Agent": "NAT-Notifications/1.0",
+        }
+
+        secret = signing_secret or os.environ.get("NAT_NOTIFICATION_WEBHOOK_SECRET", "")
+        if secret:
+            sig = hmac.new(
+                secret.encode(), body.encode(), hashlib.sha256
+            ).hexdigest()
+            headers["X-NAT-Signature"] = f"sha256={sig}"
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                url,
+                data=body,
+                headers=headers,
+                timeout=aiohttp.ClientTimeout(total=timeout),
+            ) as resp:
+                if resp.status >= 400:
+                    logger.warning(
+                        "_http_post: server returned %d for event posted to %s",
+                        resp.status,
+                        url,
+                    )
+                else:
+                    logger.debug(
+                        "_http_post: delivered notification to %s (status=%d)",
+                        url,
+                        resp.status,
+                    )
+    except Exception as exc:  # noqa: BLE001
+        raise RuntimeError(
+            f"Notification HTTP POST to {url!r} failed: {exc}"
+        ) from exc

mannf/product/onboarding.py

@@ -0,0 +1,190 @@
+# 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.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Onboarding progress tracker for new NAT tenants.
+
+Tracks each tenant through their first-time setup journey:
+
+    ACCOUNT_CREATED → API_KEY_PROVISIONED → FIRST_SCAN_STARTED
+        → FIRST_SCAN_COMPLETED → RESULTS_VIEWED → BILLING_CONFIGURED
+
+Progress is stored in-memory (per-process) and keyed by ``tenant_id``.
+When a database is available, progress is also persisted as billing audit
+events so it survives restarts.
+
+Usage::
+
+    from mannf.product.onboarding import OnboardingStepName, mark_step_complete, get_onboarding_status
+
+    await mark_step_complete(tenant_id, OnboardingStepName.FIRST_SCAN_STARTED)
+    status = get_onboarding_status(tenant_id)
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Step definitions
+# ---------------------------------------------------------------------------
+
+# Ordered list of all steps — the order here determines progress_percent.
+_ORDERED_STEPS = [
+    "ACCOUNT_CREATED",
+    "API_KEY_PROVISIONED",
+    "FIRST_SCAN_STARTED",
+    "FIRST_SCAN_COMPLETED",
+    "RESULTS_VIEWED",
+    "BILLING_CONFIGURED",
+]
+
+
+class OnboardingStepName(str, Enum):
+    """Canonical names for each onboarding step."""
+
+    ACCOUNT_CREATED = "ACCOUNT_CREATED"
+    API_KEY_PROVISIONED = "API_KEY_PROVISIONED"
+    FIRST_SCAN_STARTED = "FIRST_SCAN_STARTED"
+    FIRST_SCAN_COMPLETED = "FIRST_SCAN_COMPLETED"
+    RESULTS_VIEWED = "RESULTS_VIEWED"
+    BILLING_CONFIGURED = "BILLING_CONFIGURED"
+
+
+# ---------------------------------------------------------------------------
+# Pydantic response models
+# ---------------------------------------------------------------------------
+
+
+class OnboardingStepDetail(BaseModel):
+    """Completion state for a single onboarding step."""
+
+    step: str
+    completed: bool = False
+    completed_at: Optional[str] = None
+
+
+class OnboardingStatusResponse(BaseModel):
+    """Full onboarding progress for a tenant."""
+
+    tenant_id: str
+    completed_steps: List[str] = Field(default_factory=list)
+    next_step: Optional[str] = None
+    progress_percent: float = 0.0
+    all_steps: List[OnboardingStepDetail] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# In-memory progress store
+# ---------------------------------------------------------------------------
+
+# Maps tenant_id (str) → {step_name: completed_at ISO string}
+_progress: Dict[str, Dict[str, str]] = {}
+
+
+def _tenant_progress(tenant_id: str) -> Dict[str, str]:
+    """Return (and lazily initialise) the progress dict for *tenant_id*."""
+    return _progress.setdefault(tenant_id, {})
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+async def mark_step_complete(tenant_id: str, step: OnboardingStepName) -> None:
+    """Record *step* as completed for *tenant_id* (idempotent).
+
+    If the step is already marked complete, this is a no-op.  Progress is
+    stored in-memory and, when a database is available, also logged as a
+    billing audit event for durability.
+    """
+    progress = _tenant_progress(tenant_id)
+    if step.value in progress:
+        return  # already done — idempotent
+
+    completed_at = datetime.now(timezone.utc).isoformat()
+    progress[step.value] = completed_at
+    logger.debug("Onboarding step %s completed for tenant %s", step.value, tenant_id)
+
+    # Fire-and-forget: persist to audit log when DB is available
+    try:
+        import asyncio  # noqa: PLC0415
+        from mannf.product.billing.audit import log_billing_event  # noqa: PLC0415
+
+        asyncio.create_task(
+            log_billing_event(
+                "onboarding.step_completed",
+                tenant_id=tenant_id,
+                source="system",
+                details={"step": step.value, "completed_at": completed_at},
+            )
+        )
+    except Exception:  # noqa: BLE001
+        pass  # DB not configured — in-memory only is fine
+
+
+def is_step_complete(tenant_id: str, step: OnboardingStepName) -> bool:
+    """Return ``True`` if *step* has been completed for *tenant_id*."""
+    return step.value in _tenant_progress(tenant_id)
+
+
+def get_onboarding_status(tenant_id: str) -> OnboardingStatusResponse:
+    """Build and return the full onboarding status for *tenant_id*."""
+    progress = _tenant_progress(tenant_id)
+
+    all_steps: List[OnboardingStepDetail] = []
+    completed_steps: List[str] = []
+    next_step: Optional[str] = None
+
+    for name in _ORDERED_STEPS:
+        completed_at = progress.get(name)
+        completed = completed_at is not None
+        all_steps.append(
+            OnboardingStepDetail(
+                step=name,
+                completed=completed,
+                completed_at=completed_at,
+            )
+        )
+        if completed:
+            completed_steps.append(name)
+        elif next_step is None:
+            next_step = name
+
+    total = len(_ORDERED_STEPS)
+    done = len(completed_steps)
+    progress_percent = round((done / total) * 100, 1) if total > 0 else 0.0
+
+    return OnboardingStatusResponse(
+        tenant_id=tenant_id,
+        completed_steps=completed_steps,
+        next_step=next_step,
+        progress_percent=progress_percent,
+        all_steps=all_steps,
+    )
+
+
+def reset_progress(tenant_id: str) -> None:
+    """Clear all onboarding progress for *tenant_id* (used in tests)."""
+    _progress.pop(tenant_id, None)
+
+
+def _mark_step_complete_sync(tenant_id: str, step: OnboardingStepName) -> None:
+    """Synchronously mark *step* as completed (in-memory only, no async).
+
+    This is intended for use in synchronous test code where calling
+    ``asyncio.run()`` would interfere with the event loop.  It updates the
+    in-memory progress dict without attempting to persist to the audit log.
+    """
+    progress = _tenant_progress(tenant_id)
+    if step.value not in progress:
+        progress[step.value] = datetime.now(timezone.utc).isoformat()

mannf/product/orchestration/__init__.py

@@ -0,0 +1,39 @@
+# 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.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Orchestration package — closed-loop Ingest → Prioritize → Scan → Export → Learn pipeline.
+
+Public API::
+
+    from mannf.product.orchestration import IngestScanOrchestrator, Pipeline
+    from mannf.product.orchestrator_models import OrchestrationConfig, OrchestrationResult
+
+    # Fluent builder
+    result = await (
+        Pipeline()
+        .with_source("api.yaml", format="openapi")
+        .with_base_url("http://localhost:8080")
+        .with_exporter("github-issues", repo="org/repo")
+        .run()
+    )
+
+    # Direct orchestrator
+    config = OrchestrationConfig(
+        source_path="api.yaml",
+        scan_config={"base_url": "http://localhost:8080"},
+    )
+    orch = IngestScanOrchestrator(config)
+    result = await orch.orchestrate()
+"""
+
+from __future__ import annotations
+
+from mannf.product.orchestration.ingest_scan_orchestrator import IngestScanOrchestrator
+from mannf.product.orchestration.pipeline import Pipeline
+
+__all__ = [
+    "IngestScanOrchestrator",
+    "Pipeline",
+]