nat-engine 1__py3-none-any.whl

mannf/product/scheduling/engine.py

@@ -0,0 +1,473 @@
+# 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.
+
+"""Background scheduler engine for recurring scans.
+
+The engine runs a configurable tick loop.  On each tick it:
+
+1. Queries all *enabled* schedules where ``next_run_at <= now``.
+2. For each due schedule, spawns a background coroutine that executes
+   the appropriate scan type (functional or security) via the existing
+   NAT infrastructure.
+3. Updates ``last_run_at``, ``last_run_status``, ``last_run_scan_id``,
+   and ``run_count`` on the schedule.
+4. Recalculates and sets ``next_run_at`` via
+   :func:`~mannf.product.scheduling.cron_utils.next_run_after`.
+
+The engine checks the tenant's monthly quota before dispatching each
+scan.  If the tenant has exceeded their quota the scan is skipped and
+``last_run_status`` is set to ``"skipped_quota"``.
+
+Usage::
+
+    from mannf.product.scheduling.engine import SchedulerEngine
+    from mannf.product.scheduling.store import ScheduleStore
+
+    store = ScheduleStore()
+    engine = SchedulerEngine(store=store, tick_interval=60)
+    await engine.start()   # returns immediately; engine runs in background
+    # ... later ...
+    await engine.stop()
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from mannf.product.scheduling.cron_utils import next_run_after
+from mannf.product.scheduling.models import ScanSchedule
+from mannf.product.scheduling.store import ScheduleStore
+
+logger = logging.getLogger(__name__)
+
+# Module-level imports for external dependencies — imported here so that
+# tests can patch them at this module's namespace.
+try:
+    from mannf.product.notifications import dispatch_scan_notification
+except Exception:  # noqa: BLE001
+    dispatch_scan_notification = None  # type: ignore[assignment]
+
+try:
+    from mannf.product.database import _build_engine
+except Exception:  # noqa: BLE001
+    _build_engine = None  # type: ignore[assignment]
+
+try:
+    from mannf.product.billing.tenant_auth import get_monthly_usage
+except Exception:  # noqa: BLE001
+    get_monthly_usage = None  # type: ignore[assignment]
+
+
+class SchedulerEngine:
+    """Async background engine that fires scheduled scans on a tick loop.
+
+    Args:
+        store: The :class:`~mannf.product.scheduling.store.ScheduleStore`
+            instance shared with the API layer.
+        tick_interval: Seconds between scheduler ticks (default: 60).
+    """
+
+    def __init__(
+        self,
+        store: ScheduleStore,
+        tick_interval: int = 60,
+    ) -> None:
+        self._store = store
+        self._tick_interval = tick_interval
+        self._task: asyncio.Task[None] | None = None
+        self._running = False
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def start(self) -> None:
+        """Start the background tick loop.
+
+        This method returns immediately; the loop runs as an
+        :class:`asyncio.Task`.  Call :meth:`stop` to cancel it cleanly.
+        """
+        if self._running:
+            logger.warning("SchedulerEngine is already running; ignoring start()")
+            return
+        self._running = True
+        self._task = asyncio.create_task(self._tick_loop(), name="nat-scheduler")
+        logger.info(
+            "SchedulerEngine started (tick_interval=%ds)", self._tick_interval
+        )
+
+    async def stop(self) -> None:
+        """Cancel the background tick loop and wait for it to finish."""
+        self._running = False
+        if self._task is not None and not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        self._task = None
+        logger.info("SchedulerEngine stopped")
+
+    @property
+    def is_running(self) -> bool:
+        """``True`` when the engine's background task is active."""
+        return self._running and self._task is not None and not self._task.done()
+
+    # ------------------------------------------------------------------
+    # Internal tick loop
+    # ------------------------------------------------------------------
+
+    async def _tick_loop(self) -> None:
+        """Main loop: sleep, then process due schedules."""
+        while self._running:
+            try:
+                await self._process_due_schedules()
+            except Exception:  # noqa: BLE001
+                logger.exception("Unexpected error in SchedulerEngine tick loop")
+            try:
+                await asyncio.sleep(self._tick_interval)
+            except asyncio.CancelledError:
+                break
+
+    async def _process_due_schedules(self) -> None:
+        """Identify and execute all schedules that are due to run."""
+        now = datetime.now(timezone.utc)
+        for schedule in self._store.iter_enabled():
+            if not schedule.next_run_at:
+                # First run: calculate and persist next_run_at, then check.
+                try:
+                    nxt = next_run_after(
+                        schedule.cron_expression, now, tz=schedule.timezone
+                    )
+                    schedule.next_run_at = nxt.isoformat()
+                    self._store.update(schedule)
+                except Exception:  # noqa: BLE001
+                    logger.exception(
+                        "Failed to calculate next_run_at for schedule %s",
+                        schedule.schedule_id,
+                    )
+                continue
+
+            try:
+                next_dt = datetime.fromisoformat(schedule.next_run_at)
+            except ValueError:
+                logger.warning(
+                    "Schedule %s has invalid next_run_at %r; skipping",
+                    schedule.schedule_id,
+                    schedule.next_run_at,
+                )
+                continue
+
+            # Ensure next_dt is timezone-aware for comparison.
+            if next_dt.tzinfo is None:
+                next_dt = next_dt.replace(tzinfo=timezone.utc)
+
+            if next_dt <= now:
+                # When a distributed queue is configured, enqueue the schedule
+                # instead of spawning a local asyncio task.
+                from mannf.product.scheduling.queue import get_default_queue  # noqa: PLC0415
+                default_queue = get_default_queue()
+                if default_queue is not None:
+                    import json as _json  # noqa: PLC0415
+                    try:
+                        await default_queue.enqueue(
+                            "scheduled_scan",
+                            {
+                                "schedule_id": schedule.schedule_id,
+                                "tenant_id": schedule.tenant_id,
+                                "schedule_type": schedule.schedule_type,
+                                "schedule_config": _json.dumps(schedule.scan_config or {}),
+                            },
+                            dedup_key=f"schedule:{schedule.schedule_id}",
+                        )
+                        logger.info(
+                            "Enqueued scheduled scan %s to worker pool",
+                            schedule.schedule_id,
+                        )
+                    except Exception:  # noqa: BLE001
+                        logger.exception(
+                            "Failed to enqueue scheduled scan %s; falling back to local task",
+                            schedule.schedule_id,
+                        )
+                        asyncio.create_task(
+                            self._run_schedule(schedule),
+                            name=f"nat-scheduled-scan-{schedule.schedule_id}",
+                        )
+                else:
+                    asyncio.create_task(
+                        self._run_schedule(schedule),
+                        name=f"nat-scheduled-scan-{schedule.schedule_id}",
+                    )
+
+    # ------------------------------------------------------------------
+    # Scan execution
+    # ------------------------------------------------------------------
+
+    async def _check_quota(self, tenant_id: str, scan_type: str) -> bool:
+        """Return ``True`` if the tenant is within their monthly quota.
+
+        Gracefully returns ``True`` (allow) when the database is not
+        available (legacy / dev mode).
+        """
+        try:
+            if _build_engine is None or _build_engine() is None:
+                return True  # No DB — no quota enforcement
+
+            # We need the tenant's quota limit.  Load it from the DB.
+            from mannf.product.models import Tenant  # noqa: PLC0415
+            from mannf.product.database import _async_session_factory  # noqa: PLC0415
+
+            if _async_session_factory is None:
+                return True
+
+            import sqlalchemy as sa  # noqa: PLC0415
+            async with _async_session_factory() as session:
+                result = await session.execute(
+                    sa.select(Tenant).where(Tenant.id == uuid.UUID(tenant_id))
+                )
+                tenant_obj = result.scalar_one_or_none()
+                if tenant_obj is None:
+                    return True  # Unknown tenant — allow (don't block)
+
+            quota_attr = (
+                "monthly_scan_quota"
+                if scan_type == "functional"
+                else "monthly_security_scan_quota"
+            )
+            tenant_quota = getattr(tenant_obj, quota_attr, 999_999)
+
+            if get_monthly_usage is None:
+                return True
+            used = await get_monthly_usage(uuid.UUID(tenant_id), scan_type)
+            return used < tenant_quota
+        except Exception:  # noqa: BLE001
+            logger.warning(
+                "Quota check failed for tenant %s (%s); allowing scan",
+                tenant_id,
+                scan_type,
+            )
+            return True  # Fail open
+
+    async def _run_schedule(self, schedule: ScanSchedule) -> None:
+        """Execute a single scheduled scan and update the schedule record."""
+        logger.info(
+            "Running scheduled %s scan '%s' (id=%s, tenant=%s)",
+            schedule.schedule_type,
+            schedule.name,
+            schedule.schedule_id,
+            schedule.tenant_id,
+        )
+
+        # Quota guard
+        quota_ok = await self._check_quota(schedule.tenant_id, schedule.schedule_type)
+        if not quota_ok:
+            logger.warning(
+                "Skipping scheduled scan %s: tenant %s has exceeded quota",
+                schedule.schedule_id,
+                schedule.tenant_id,
+            )
+            schedule.last_run_status = "skipped_quota"
+            schedule.last_run_at = datetime.now(timezone.utc).isoformat()
+            self._advance_schedule(schedule)
+            self._store.update(schedule)
+            return
+
+        # Mark as running
+        schedule.last_run_at = datetime.now(timezone.utc).isoformat()
+        schedule.last_run_status = "running"
+        self._store.update(schedule)
+
+        scan_id: str | None = None
+        status = "failed"
+        try:
+            if schedule.schedule_type == "security":
+                scan_id, status = await self._execute_security_scan(schedule)
+            elif schedule.schedule_type == "autonomous":
+                scan_id, status = await self._execute_autonomous_sweep(schedule)
+            else:
+                scan_id, status = await self._execute_functional_scan(schedule)
+        except Exception:  # noqa: BLE001
+            logger.exception(
+                "Scheduled scan %s ('%s') raised an unhandled exception",
+                schedule.schedule_id,
+                schedule.name,
+            )
+            status = "failed"
+
+        # Update result metadata
+        schedule.last_run_status = status
+        schedule.last_run_scan_id = scan_id
+        schedule.run_count += 1
+        self._advance_schedule(schedule)
+        self._store.update(schedule)
+
+        # Dispatch notification (fire-and-forget)
+        event = (
+            "scheduled_scan.completed"
+            if status == "completed"
+            else "scheduled_scan.failed"
+        )
+        try:
+            if dispatch_scan_notification is not None:
+                asyncio.create_task(
+                    dispatch_scan_notification(
+                        event,
+                        tenant_id=schedule.tenant_id,
+                        scan_id=scan_id,
+                        details={
+                            "schedule_id": schedule.schedule_id,
+                            "schedule_name": schedule.name,
+                            "schedule_type": schedule.schedule_type,
+                            "run_count": schedule.run_count,
+                            "status": status,
+                        },
+                    ),
+                    name=f"nat-scheduler-notify-{schedule.schedule_id}",
+                )
+        except Exception:  # noqa: BLE001
+            logger.warning(
+                "Failed to dispatch notification for scheduled scan %s",
+                schedule.schedule_id,
+            )
+
+    # ------------------------------------------------------------------
+    # Scan delegates
+    # ------------------------------------------------------------------
+
+    async def _execute_security_scan(
+        self, schedule: ScanSchedule
+    ) -> tuple[str, str]:
+        """Run a security scan for *schedule* and return ``(scan_id, status)``."""
+        from mannf.product.security.scanner import SecurityScanner  # noqa: PLC0415
+        from mannf.product.security.checks.base import EndpointInfo  # noqa: PLC0415
+
+        cfg = schedule.scan_config or {}
+        spec_path = schedule.spec_path
+        base_url = schedule.base_url
+        spec_format = schedule.spec_format
+
+        if spec_format == "postman":
+            from mannf.product.integrations.postman_parser import PostmanParser  # noqa: PLC0415
+            parser: Any = PostmanParser(spec_path=spec_path, base_url=base_url)
+        else:
+            from mannf.product.integrations.openapi_parser import OpenApiParser  # noqa: PLC0415
+            from mannf.product.integrations.http_sut import HttpApiSUT  # noqa: PLC0415
+            sut = HttpApiSUT(base_url=base_url)
+            parser = OpenApiParser(
+                spec_path=spec_path, base_url=base_url, registry=sut.registry
+            )
+
+        test_cases = parser.parse()
+        endpoints: list[EndpointInfo] = []
+        seen: set[str] = set()
+        for tc in test_cases:
+            method = tc.inputs.get("method", "GET").upper()
+            path = tc.target
+            key = f"{method} {path}"
+            if key not in seen:
+                seen.add(key)
+                endpoints.append(
+                    EndpointInfo(
+                        method=method,
+                        path=path,
+                        base_url=base_url,
+                        parameters=tc.inputs.get("parameters", []),
+                        request_body=tc.inputs.get("body"),
+                    )
+                )
+
+        scanner = SecurityScanner(
+            base_url=base_url,
+            enabled_checks=cfg.get("checks"),
+            severity_threshold=cfg.get("severity_threshold", "low"),
+            belief_guided=True,
+            adaptive_checks=True,
+        )
+        report = await scanner.scan(endpoints)
+        return report.scan_id, "completed"
+
+    async def _execute_functional_scan(
+        self, schedule: ScanSchedule
+    ) -> tuple[str, str]:
+        """Run a functional scan for *schedule* and return ``(scan_id, status)``."""
+        from mannf.product.integrations.openapi_parser import OpenApiParser  # noqa: PLC0415
+        from mannf.product.integrations.http_sut import HttpApiSUT  # noqa: PLC0415
+
+        cfg = schedule.scan_config or {}
+        spec_path = schedule.spec_path
+        base_url = schedule.base_url
+        spec_format = schedule.spec_format
+        max_tests: int | None = cfg.get("max_tests")
+        auth_token: str | None = cfg.get("auth_token")
+        api_key: str | None = cfg.get("api_key")
+        api_key_header: str = cfg.get("api_key_header", "X-API-Key")
+
+        if spec_format == "postman":
+            from mannf.product.integrations.postman_parser import PostmanParser  # noqa: PLC0415
+            test_cases = PostmanParser(spec_path=spec_path, base_url=base_url).parse()
+        else:
+            sut_tmp = HttpApiSUT(base_url=base_url)
+            test_cases = OpenApiParser(
+                spec_path=spec_path, base_url=base_url, registry=sut_tmp.registry
+            ).parse()
+
+        if max_tests:
+            test_cases = test_cases[:max_tests]
+
+        sut = HttpApiSUT(
+            base_url=base_url,
+            auth_token=auth_token,
+            api_key=api_key,
+            api_key_header=api_key_header,
+        )
+
+        scan_id = str(uuid.uuid4())
+        for tc in test_cases:
+            await sut.execute(tc)
+
+        return scan_id, "completed"
+
+    # ------------------------------------------------------------------
+    # Next-run helper
+    # ------------------------------------------------------------------
+
+    def _advance_schedule(self, schedule: ScanSchedule) -> None:
+        """Recalculate and set ``next_run_at`` on *schedule*."""
+        try:
+            now = datetime.now(timezone.utc)
+            nxt = next_run_after(
+                schedule.cron_expression, now, tz=schedule.timezone
+            )
+            schedule.next_run_at = nxt.isoformat()
+        except Exception:  # noqa: BLE001
+            logger.exception(
+                "Failed to advance next_run_at for schedule %s",
+                schedule.schedule_id,
+            )
+
+    async def _execute_autonomous_sweep(
+        self, schedule: ScanSchedule
+    ) -> tuple[str, str]:
+        """Run an autonomous test-loop sweep for *schedule* and return ``(run_id, status)``."""
+        from mannf.core.agents.autonomous_loop_agent import AutonomousTestLoopAgent  # noqa: PLC0415
+
+        cfg = schedule.scan_config or {}
+        agent = AutonomousTestLoopAgent(
+            target_url=schedule.base_url,
+            max_iterations=cfg.get("max_iterations", 5),
+            max_duration_s=cfg.get("max_duration_s", 600.0),
+            stability_threshold=cfg.get("stability_threshold", 2),
+            strategy=cfg.get("strategy", "all"),
+            risk_threshold=cfg.get("risk_threshold", 0.6),
+            max_pages=cfg.get("max_pages", 50),
+            max_depth=cfg.get("max_depth", 5),
+            recrawl_every=cfg.get("recrawl_every", 3),
+        )
+        report = await agent.run_loop()
+        final_status = "completed" if report.status in ("complete", "stable") else "failed"
+        return agent.run_id, final_status

mannf/product/scheduling/models.py

@@ -0,0 +1,86 @@
+# 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.
+
+"""Data model for scheduled scans."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ScanSchedule:
+    """Persistent configuration for a recurring scan.
+
+    Attributes:
+        schedule_id: UUID identifying this schedule.
+        tenant_id: UUID of the owning tenant.
+        name: Human-readable label, e.g. ``"Nightly API regression"``.
+        schedule_type: ``"functional"`` or ``"security"``.
+        cron_expression: Standard 5-field cron string, e.g. ``"0 2 * * *"``.
+        timezone: IANA timezone name (default ``"UTC"``).
+        spec_path: Path or URL to the OpenAPI / Postman spec file.
+        spec_format: ``"openapi"`` or ``"postman"``.
+        base_url: Target API base URL.
+        enabled: When ``False`` the schedule is paused and will not fire.
+        scan_config: Extra per-schedule config forwarded to the scanner
+            (e.g. ``checks``, ``severity_threshold``, ``max_tests``, ``auth``).
+        max_schedules_for_tier: Maximum schedules allowed on the tenant's
+            plan tier (populated by the store on creation).
+        created_at: ISO 8601 timestamp of creation.
+        updated_at: ISO 8601 timestamp of last modification.
+        last_run_at: ISO 8601 timestamp of the most recent execution, or
+            ``None`` if the schedule has never fired.
+        next_run_at: ISO 8601 timestamp of the next scheduled execution, or
+            ``None`` if not yet calculated.
+        last_run_status: ``"completed"``, ``"failed"``, ``"running"``, or
+            ``None`` when the schedule has never fired.
+        last_run_scan_id: UUID of the scan result from the last execution, or
+            ``None``.
+        run_count: Total number of times this schedule has been executed.
+    """
+
+    schedule_id: str
+    tenant_id: str
+    name: str
+    schedule_type: str          # "functional" or "security"
+    cron_expression: str
+    timezone: str
+    spec_path: str
+    spec_format: str            # "openapi" or "postman"
+    base_url: str
+    enabled: bool
+    scan_config: dict = field(default_factory=dict)
+    max_schedules_for_tier: int = 0
+    created_at: str = ""
+    updated_at: str = ""
+    last_run_at: str | None = None
+    next_run_at: str | None = None
+    last_run_status: str | None = None
+    last_run_scan_id: str | None = None
+    run_count: int = 0
+
+    def to_dict(self) -> dict:
+        """Return a JSON-serialisable dictionary representation."""
+        return {
+            "schedule_id": self.schedule_id,
+            "tenant_id": self.tenant_id,
+            "name": self.name,
+            "schedule_type": self.schedule_type,
+            "cron_expression": self.cron_expression,
+            "timezone": self.timezone,
+            "spec_path": self.spec_path,
+            "spec_format": self.spec_format,
+            "base_url": self.base_url,
+            "enabled": self.enabled,
+            "scan_config": self.scan_config,
+            "max_schedules_for_tier": self.max_schedules_for_tier,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "last_run_at": self.last_run_at,
+            "next_run_at": self.next_run_at,
+            "last_run_status": self.last_run_status,
+            "last_run_scan_id": self.last_run_scan_id,
+            "run_count": self.run_count,
+        }