nat-engine 1__py3-none-any.whl

mannf/product/scheduling/store.py

@@ -0,0 +1,235 @@
+# 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.
+
+"""In-memory schedule store with per-tier limit enforcement.
+
+The store is a simple dict-backed registry that mirrors the pattern used
+by ``_scans`` and ``_security_scans`` in ``mannf.product.server``.
+
+Tier schedule limits
+--------------------
++------------+------------------+
+| Plan       | Max schedules    |
++============+==================+
+| free       | 0 (blocked)      |
++------------+------------------+
+| pro        | 3                |
++------------+------------------+
+| team       | 10               |
++------------+------------------+
+| enterprise | 999 999          |
++------------+------------------+
+
+Usage::
+
+    from mannf.product.scheduling.store import ScheduleStore, TierLimitExceeded
+
+    store = ScheduleStore()
+    schedule = store.create(schedule, plan_tier="pro")
+    schedules = store.list_for_tenant("tenant-uuid")
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Iterator
+
+from mannf.product.scheduling.models import ScanSchedule
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Per-tier limit constants
+# ---------------------------------------------------------------------------
+
+TIER_SCHEDULE_LIMITS: dict[str, int] = {
+    "free": 0,
+    "pro": 3,
+    "team": 10,
+    "enterprise": 999_999,
+}
+
+_DEFAULT_TIER = "free"
+
+
+def get_schedule_limit(plan_tier: str) -> int:
+    """Return the maximum number of schedules allowed for *plan_tier*.
+
+    Unknown tiers default to the ``"free"`` limit (0 — blocked).
+    """
+    return TIER_SCHEDULE_LIMITS.get(plan_tier, TIER_SCHEDULE_LIMITS[_DEFAULT_TIER])
+
+
+# ---------------------------------------------------------------------------
+# Custom exceptions
+# ---------------------------------------------------------------------------
+
+class TierLimitExceeded(Exception):
+    """Raised when a tenant tries to exceed the schedule limit for their plan.
+
+    Attributes:
+        plan_tier: The tenant's plan tier name.
+        limit: The maximum number of schedules allowed.
+        current: The current number of schedules the tenant already has.
+    """
+
+    def __init__(self, plan_tier: str, limit: int, current: int) -> None:
+        self.plan_tier = plan_tier
+        self.limit = limit
+        self.current = current
+        super().__init__(
+            f"Schedule limit exceeded for plan '{plan_tier}': "
+            f"limit is {limit}, current count is {current}"
+        )
+
+
+class ScheduleNotFound(KeyError):
+    """Raised when a schedule_id does not exist in the store."""
+
+
+# ---------------------------------------------------------------------------
+# Store implementation
+# ---------------------------------------------------------------------------
+
+class ScheduleStore:
+    """Thread-safe, in-memory store for :class:`~mannf.product.scheduling.models.ScanSchedule` objects.
+
+    All mutating operations enforce per-tier schedule limits.  Pass
+    ``plan_tier`` on :meth:`create` to have the limit checked; use
+    ``"enterprise"`` for privileged callers that bypass gating.
+
+    The store is intentionally simple — persistence and cross-process
+    sharing are out of scope for PR 1.
+    """
+
+    def __init__(self) -> None:
+        self._schedules: dict[str, ScanSchedule] = {}
+
+    # ------------------------------------------------------------------
+    # CRUD helpers
+    # ------------------------------------------------------------------
+
+    def create(self, schedule: ScanSchedule, plan_tier: str = _DEFAULT_TIER) -> ScanSchedule:
+        """Persist a new schedule, enforcing the per-tier limit.
+
+        Args:
+            schedule: A fully-populated :class:`ScanSchedule` instance.  The
+                ``schedule_id`` must be unique within the store.
+            plan_tier: The owning tenant's plan tier name.  Defaults to
+                ``"free"`` (which blocks scheduling).
+
+        Returns:
+            The stored :class:`ScanSchedule` (same object, unchanged).
+
+        Raises:
+            TierLimitExceeded: When the tenant already has the maximum number
+                of schedules allowed for their plan.
+            ValueError: When a schedule with the same ``schedule_id`` already
+                exists.
+        """
+        limit = get_schedule_limit(plan_tier)
+        current = sum(
+            1 for s in self._schedules.values()
+            if s.tenant_id == schedule.tenant_id
+        )
+        if current >= limit:
+            raise TierLimitExceeded(plan_tier, limit, current)
+
+        if schedule.schedule_id in self._schedules:
+            raise ValueError(
+                f"Schedule with id '{schedule.schedule_id}' already exists"
+            )
+
+        # Stamp the tier limit so API callers can surface it.
+        schedule.max_schedules_for_tier = limit
+
+        self._schedules[schedule.schedule_id] = schedule
+        logger.debug(
+            "Created schedule %s for tenant %s (tier=%s, %d/%d used)",
+            schedule.schedule_id,
+            schedule.tenant_id,
+            plan_tier,
+            current + 1,
+            limit,
+        )
+        return schedule
+
+    def get(self, schedule_id: str) -> ScanSchedule:
+        """Return the schedule with *schedule_id*.
+
+        Raises:
+            ScheduleNotFound: When no schedule with that ID exists.
+        """
+        try:
+            return self._schedules[schedule_id]
+        except KeyError:
+            raise ScheduleNotFound(schedule_id)
+
+    def list_for_tenant(self, tenant_id: str) -> list[ScanSchedule]:
+        """Return all schedules owned by *tenant_id*, sorted by name."""
+        return sorted(
+            (s for s in self._schedules.values() if s.tenant_id == tenant_id),
+            key=lambda s: s.name,
+        )
+
+    def update(self, schedule: ScanSchedule) -> ScanSchedule:
+        """Replace the stored schedule entry for ``schedule.schedule_id``.
+
+        Args:
+            schedule: The updated :class:`ScanSchedule`.  The ``schedule_id``
+                must already exist in the store.
+
+        Returns:
+            The updated :class:`ScanSchedule`.
+
+        Raises:
+            ScheduleNotFound: When the schedule does not exist.
+        """
+        if schedule.schedule_id not in self._schedules:
+            raise ScheduleNotFound(schedule.schedule_id)
+        self._schedules[schedule.schedule_id] = schedule
+        return schedule
+
+    def delete(self, schedule_id: str) -> None:
+        """Remove the schedule with *schedule_id* from the store.
+
+        Raises:
+            ScheduleNotFound: When no schedule with that ID exists.
+        """
+        if schedule_id not in self._schedules:
+            raise ScheduleNotFound(schedule_id)
+        del self._schedules[schedule_id]
+
+    # ------------------------------------------------------------------
+    # Iteration helpers (used by the engine)
+    # ------------------------------------------------------------------
+
+    def iter_enabled(self) -> Iterator[ScanSchedule]:
+        """Yield all enabled schedules across all tenants."""
+        for schedule in list(self._schedules.values()):
+            if schedule.enabled:
+                yield schedule
+
+    def __len__(self) -> int:
+        return len(self._schedules)
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton (for CLI access)
+# ---------------------------------------------------------------------------
+
+_store_singleton: ScheduleStore | None = None
+
+
+def get_store() -> ScheduleStore:
+    """Return the module-level :class:`ScheduleStore` singleton.
+
+    In the server context the store is managed by ``server.py``; this helper
+    is primarily useful for CLI commands that need to interact with the store
+    without importing the full server module.
+    """
+    global _store_singleton
+    if _store_singleton is None:
+        _store_singleton = ScheduleStore()
+    return _store_singleton

mannf/product/security/__init__.py

@@ -0,0 +1,21 @@
+# 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.
+
+"""Security package for OWASP API Security Top 10 testing."""
+
+from __future__ import annotations
+
+from mannf.product.security.belief_guided import prioritize_for_security
+from mannf.product.security.models import SecurityFinding, SecurityReport
+from mannf.product.security.reporter import SecurityReporter
+from mannf.product.security.scanner import SecurityScanner
+
+__all__ = [
+    "SecurityScanner",
+    "SecurityFinding",
+    "SecurityReport",
+    "SecurityReporter",
+    "prioritize_for_security",
+]

mannf/product/security/belief_guided.py

@@ -0,0 +1,143 @@
+# 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.
+
+"""Belief-guided endpoint prioritization for security scanning."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mannf.product.security.checks.base import EndpointInfo
+
+if TYPE_CHECKING:
+    from mannf.core.agents.belief_state import BeliefState
+    from mannf.core.prioritization.risk_scorer import RiskScorer
+
+_HIGH_VALUE_PATH_KEYWORDS = (
+    "admin", "payment", "user", "account", "auth", "token",
+    "secret", "key", "password", "config", "management", "internal",
+)
+
+_CHECK_HINTS: dict[str, list[str]] = {
+    "admin": ["API5:2023", "API2:2023"],
+    "payment": ["API6:2023", "API4:2023", "API10:2023"],
+    "user": ["API1:2023", "API2:2023", "API3:2023"],
+    "account": ["API1:2023", "API2:2023"],
+    "auth": ["API2:2023"],
+    "token": ["API2:2023"],
+    "password": ["API2:2023", "API6:2023"],
+    "config": ["API5:2023", "API8:2023"],
+    "management": ["API5:2023"],
+    "internal": ["API5:2023", "API8:2023"],
+}
+
+_DEFAULT_CHECKS = [
+    "API1:2023", "API2:2023", "API3:2023", "API4:2023", "API5:2023",
+    "API6:2023", "API7:2023", "API8:2023", "API9:2023", "API10:2023",
+]
+
+
+def prioritize_for_security(
+    endpoints: list[EndpointInfo],
+    risk_report: list[dict] | None = None,
+    belief_states: list[BeliefState] | None = None,
+    risk_scorer: RiskScorer | None = None,
+    fp_rates: dict[str, float] | None = None,
+) -> list[tuple[EndpointInfo, float, list[str], float, float]]:
+    """Return ``(endpoint, priority_score, check_ids, belief_score, risk_score)`` tuples sorted by descending priority.
+
+    Priority logic:
+    - Base score 0.5 for all endpoints
+    - If *belief_states* are provided, average ``fault_likelihood`` across agents is used as the primary score
+    - If *risk_scorer* is provided, its composite score is used as the primary score (overrides belief_states base)
+    - If *risk_report* is provided (legacy), use ``risk_score`` from the matching report entry
+    - Endpoints with high-value keywords in the path get +0.2
+    - POST/PUT/DELETE methods get +0.1 over GET
+    - If *fp_rates* is provided, the FP rate for the endpoint is used as a downward modifier:
+      ``score *= (1 - fp_rate)``
+    - ``check_ids`` lists the OWASP IDs most relevant for this endpoint
+    - ``belief_score`` is the raw belief-derived score (0.5 if not available)
+    - ``risk_score`` is the raw risk-scorer composite score (0.5 if not available)
+    """
+    risk_map: dict[str, float] = {}
+    if risk_report:
+        for entry in risk_report:
+            path = entry.get("path") or entry.get("endpoint", "")
+            score = entry.get("risk_score", 0.5)
+            if path:
+                risk_map[path] = float(score)
+
+    results: list[tuple[EndpointInfo, float, list[str], float, float]] = []
+
+    for ep in endpoints:
+        endpoint_key = ep.path
+
+        # Compute belief score: average fault_likelihood across all BeliefState agents
+        belief_score = 0.5
+        if belief_states:
+            likelihoods = []
+            for bs in belief_states:
+                fl = bs.fault_likelihood.get(endpoint_key)
+                if fl is None:
+                    # Try matching by method+path key format
+                    method_key = f"{ep.method.upper()} {endpoint_key}"
+                    fl = bs.fault_likelihood.get(method_key)
+                if fl is not None:
+                    likelihoods.append(fl)
+            if likelihoods:
+                belief_score = sum(likelihoods) / len(likelihoods)
+
+        # Compute risk scorer composite score
+        risk_score_val = 0.5
+        if risk_scorer is not None:
+            try:
+                risk_score_val = risk_scorer.score(endpoint_key, belief_states or [])
+            except Exception:
+                pass
+
+        # Determine the primary base score:
+        # 1. risk_scorer (highest fidelity composite) if available
+        # 2. belief_states (direct BDI signal) if available
+        # 3. legacy risk_report
+        # 4. default 0.5
+        if risk_scorer is not None and risk_score_val != 0.5:
+            score = risk_score_val
+        elif belief_states:
+            score = belief_score
+        else:
+            score = risk_map.get(ep.path, 0.5)
+
+        lower_path = ep.path.lower()
+        matched_keywords = [kw for kw in _HIGH_VALUE_PATH_KEYWORDS if kw in lower_path]
+        if matched_keywords:
+            score = min(1.0, score + 0.2)
+
+        if ep.method.upper() in ("POST", "PUT", "DELETE"):
+            score = min(1.0, score + 0.1)
+
+        # Apply FP rate as a downward modifier: score *= (1 - fp_rate)
+        if fp_rates:
+            ep_fp_rate = fp_rates.get(endpoint_key)
+            if ep_fp_rate is None:
+                method_key = f"{ep.method.upper()} {endpoint_key}"
+                ep_fp_rate = fp_rates.get(method_key)
+            if ep_fp_rate is not None:
+                fp_rate_clamped = max(0.0, min(1.0, float(ep_fp_rate)))
+                score = max(0.0, score * (1.0 - fp_rate_clamped))
+
+        check_ids: list[str] = []
+        seen: set[str] = set()
+        for kw in matched_keywords:
+            for cid in _CHECK_HINTS.get(kw, []):
+                if cid not in seen:
+                    check_ids.append(cid)
+                    seen.add(cid)
+        if not check_ids:
+            check_ids = list(_DEFAULT_CHECKS)
+
+        results.append((ep, score, check_ids, belief_score, risk_score_val))
+
+    results.sort(key=lambda t: t[1], reverse=True)
+    return results

mannf/product/security/checks/__init__.py

@@ -0,0 +1,55 @@
+# 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.
+
+"""Security checks package — all 10 OWASP API Security Top 10 checks."""
+
+from __future__ import annotations
+
+from mannf.product.security.checks.base import EndpointInfo, SecurityCheck
+from mannf.product.security.checks.bfla import BFLACheck
+from mannf.product.security.checks.bola import BOLACheck
+from mannf.product.security.checks.bopla import BOPLACheck
+from mannf.product.security.checks.broken_auth import BrokenAuthCheck
+from mannf.product.security.checks.graphql_security import (
+    GraphQLAliasDoSCheck,
+    GraphQLBatchQueryCheck,
+    GraphQLDepthAttackCheck,
+    GraphQLFieldSuggestionCheck,
+    GraphQLIntrospectionCheck,
+)
+from mannf.product.security.checks.inventory import InventoryCheck
+from mannf.product.security.checks.misconfig import MisconfigCheck
+from mannf.product.security.checks.resource_consumption import ResourceConsumptionCheck
+from mannf.product.security.checks.sensitive_flows import SensitiveFlowsCheck
+from mannf.product.security.checks.ssrf import SSRFCheck
+from mannf.product.security.checks.unsafe_consumption import UnsafeConsumptionCheck
+from mannf.product.security.plugin_loader import (
+    load_all_plugins,
+    load_plugins_from_directory,
+    load_plugins_from_entry_points,
+)
+
+__all__ = [
+    "SecurityCheck",
+    "EndpointInfo",
+    "BOLACheck",
+    "BrokenAuthCheck",
+    "BOPLACheck",
+    "ResourceConsumptionCheck",
+    "BFLACheck",
+    "SensitiveFlowsCheck",
+    "SSRFCheck",
+    "MisconfigCheck",
+    "InventoryCheck",
+    "UnsafeConsumptionCheck",
+    "GraphQLIntrospectionCheck",
+    "GraphQLDepthAttackCheck",
+    "GraphQLBatchQueryCheck",
+    "GraphQLFieldSuggestionCheck",
+    "GraphQLAliasDoSCheck",
+    "load_plugins_from_directory",
+    "load_plugins_from_entry_points",
+    "load_all_plugins",
+]

mannf/product/security/checks/base.py

@@ -0,0 +1,69 @@
+# 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.
+
+"""Abstract base for OWASP security checks."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+import httpx
+
+from mannf.product.security.models import SecurityFinding
+
+
+@dataclass
+class EndpointInfo:
+    """Lightweight endpoint descriptor for security checks."""
+
+    method: str
+    path: str
+    base_url: str
+    parameters: list[dict] = field(default_factory=list)
+    request_body: dict | None = None
+
+    @property
+    def full_url(self) -> str:
+        base = self.base_url.rstrip("/")
+        path = self.path if self.path.startswith("/") else f"/{self.path}"
+        return f"{base}{path}"
+
+
+class SecurityCheck(ABC):
+    owasp_id: str
+    name: str
+    description: str
+    severity_default: str
+
+    @abstractmethod
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        ...
+
+    def _make_finding(
+        self,
+        endpoint: EndpointInfo,
+        title: str,
+        description: str,
+        evidence: str,
+        remediation: str,
+        cwe_id: str,
+        severity: str | None = None,
+        confidence: float = 0.8,
+    ) -> SecurityFinding:
+        return SecurityFinding(
+            check_id=self.owasp_id,
+            check_name=self.name,
+            severity=severity if severity is not None else self.severity_default,
+            endpoint=f"{endpoint.method.upper()} {endpoint.path}",
+            title=title,
+            description=description,
+            evidence=evidence,
+            remediation=remediation,
+            cwe_id=cwe_id,
+            confidence=confidence,
+        )

mannf/product/security/checks/bfla.py

@@ -0,0 +1,77 @@
+# 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.
+
+"""API5:2023 — Broken Function Level Authorization (BFLA)."""
+
+from __future__ import annotations
+
+import httpx
+
+from mannf.product.security.checks.base import EndpointInfo, SecurityCheck
+from mannf.product.security.models import SecurityFinding
+
+_ADMIN_PATH_HINTS = (
+    "/admin", "/management", "/internal", "/config",
+    "/settings", "/users", "/roles",
+)
+
+_PRIVILEGED_METHODS = {"DELETE", "PUT"}
+
+
+def _is_admin_like(path: str) -> bool:
+    lower = path.lower()
+    return any(hint in lower for hint in _ADMIN_PATH_HINTS)
+
+
+class BFLACheck(SecurityCheck):
+    owasp_id = "API5:2023"
+    name = "Broken Function Level Authorization"
+    description = "Tests whether function-level access controls are enforced."
+    severity_default = "high"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        method = endpoint.method.upper()
+        is_admin = _is_admin_like(endpoint.path)
+        is_privileged_method = method in _PRIVILEGED_METHODS
+
+        if not is_admin and not is_privileged_method:
+            return []
+
+        url = endpoint.full_url
+        headers = {}  # no auth header intentionally
+
+        try:
+            resp = await client.request(method, url, headers=headers)
+        except httpx.RequestError:
+            return []
+
+        if resp.status_code not in (200, 201):
+            return []
+
+        label_parts = []
+        if is_admin:
+            label_parts.append("admin-like path")
+        if is_privileged_method:
+            label_parts.append(f"privileged method ({method})")
+
+        return [
+            self._make_finding(
+                endpoint,
+                title="Admin/privileged endpoint accessible without authorization",
+                description=(
+                    f"The endpoint ({', '.join(label_parts)}) returned "
+                    f"HTTP {resp.status_code} without an Authorization header."
+                ),
+                evidence=f"{method} {url} (no auth) → {resp.status_code}",
+                remediation=(
+                    "Enforce role-based access control (RBAC) on all admin and "
+                    "privileged endpoints. Reject unauthorized access with HTTP 401/403."
+                ),
+                cwe_id="CWE-285",
+                confidence=0.7,
+            )
+        ]

mannf/product/security/checks/bola.py

@@ -0,0 +1,77 @@
+# 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.
+
+"""API1:2023 — Broken Object Level Authorization (BOLA)."""
+
+from __future__ import annotations
+
+import re
+
+import httpx
+
+from mannf.product.security.checks.base import EndpointInfo, SecurityCheck
+from mannf.product.security.models import SecurityFinding
+
+_UUID_RE = re.compile(
+    r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", re.IGNORECASE
+)
+_NUM_RE = re.compile(r"/(\d+)(?=/|$)")
+_ALT_UUID = "00000000-0000-0000-0000-000000000099"
+
+
+class BOLACheck(SecurityCheck):
+    owasp_id = "API1:2023"
+    name = "Broken Object Level Authorization"
+    description = "Tests whether object-level access controls are enforced per request."
+    severity_default = "high"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        findings: list[SecurityFinding] = []
+        path = endpoint.path
+
+        has_uuid = bool(_UUID_RE.search(path))
+        has_num = bool(_NUM_RE.search(path))
+        if not has_uuid and not has_num:
+            return findings
+
+        probes: list[str] = []
+        if has_uuid:
+            probes.append(_UUID_RE.sub(_ALT_UUID, path))
+
+        if has_num:
+            for replacement in ("2", "99999", "0", "-1"):
+                probes.append(_NUM_RE.sub(f"/{replacement}", path, count=1))
+
+        for probe_path in probes:
+            if probe_path == path:
+                continue
+            url = f"{endpoint.base_url.rstrip('/')}{probe_path}"
+            try:
+                resp = await client.request(endpoint.method.upper(), url)
+            except httpx.RequestError:
+                continue
+            if resp.status_code == 200:
+                findings.append(
+                    self._make_finding(
+                        endpoint,
+                        title="Possible BOLA: Resource accessible with alternate ID",
+                        description=(
+                            "A request to a modified resource ID returned HTTP 200. "
+                            "This may indicate missing object-level authorization checks."
+                        ),
+                        evidence=f"GET {url} → {resp.status_code}",
+                        remediation=(
+                            "Validate that the authenticated user owns or has permission "
+                            "to access the requested resource ID on every request."
+                        ),
+                        cwe_id="CWE-639",
+                        confidence=0.5,
+                    )
+                )
+                break  # one finding per endpoint is enough
+
+        return findings