nat-engine 1__py3-none-any.whl

mannf/product/security/checks/resource_consumption.py

@@ -0,0 +1,70 @@
+# 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.
+
+"""API4:2023 — Unrestricted Resource Consumption (rate limiting)."""
+
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+
+from mannf.product.security.checks.base import EndpointInfo, SecurityCheck
+from mannf.product.security.models import SecurityFinding
+
+_PROBE_COUNT = 10
+
+
+class ResourceConsumptionCheck(SecurityCheck):
+    owasp_id = "API4:2023"
+    name = "Unrestricted Resource Consumption"
+    description = "Tests whether the endpoint enforces rate limiting."
+    severity_default = "medium"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        url = endpoint.full_url
+        method = endpoint.method.upper()
+
+        async def _probe() -> int:
+            try:
+                resp = await client.request(method, url)
+                return resp.status_code
+            except httpx.RequestError:
+                return -1
+
+        results = await asyncio.gather(*[_probe() for _ in range(_PROBE_COUNT)])
+
+        rate_limited = any(s == 429 for s in results)
+        if rate_limited:
+            return []
+
+        successful = sum(1 for s in results if 200 <= s < 300)
+        if successful < _PROBE_COUNT:
+            return []
+
+        return [
+            self._make_finding(
+                endpoint,
+                title="No rate limiting detected",
+                description=(
+                    f"All {_PROBE_COUNT} rapid consecutive requests to this endpoint "
+                    "succeeded without receiving a 429 Too Many Requests response. "
+                    "This may indicate missing rate limiting controls."
+                ),
+                evidence=(
+                    f"{_PROBE_COUNT}/{_PROBE_COUNT} requests returned success "
+                    f"(status codes: {list(results)})"
+                ),
+                remediation=(
+                    "Implement rate limiting (e.g., token bucket, sliding window) "
+                    "at the API gateway or application layer. Return HTTP 429 with "
+                    "Retry-After header when limits are exceeded."
+                ),
+                cwe_id="CWE-770",
+                confidence=0.5,
+            )
+        ]

mannf/product/security/checks/sensitive_flows.py

@@ -0,0 +1,80 @@
+# 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.
+
+"""API6:2023 — Unrestricted Access to Sensitive Business Flows."""
+
+from __future__ import annotations
+
+import httpx
+
+from mannf.product.security.checks.base import EndpointInfo, SecurityCheck
+from mannf.product.security.models import SecurityFinding
+
+_SENSITIVE_KEYWORDS = (
+    "password-reset", "forgot-password", "forgot_password", "reset-password",
+    "reset_password", "payment", "checkout", "transfer", "withdraw",
+    "register", "signup", "sign-up", "login", "sign-in",
+)
+
+_RATE_LIMIT_INDICATORS = ("x-ratelimit", "x-rate-limit", "retry-after")
+_CAPTCHA_INDICATORS = ("captcha", "recaptcha", "hcaptcha", "cf-turnstile")
+
+
+class SensitiveFlowsCheck(SecurityCheck):
+    owasp_id = "API6:2023"
+    name = "Unrestricted Access to Sensitive Business Flows"
+    description = "Detects sensitive business flows that may lack adequate protections."
+    severity_default = "low"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        lower_path = endpoint.path.lower()
+        matched = [kw for kw in _SENSITIVE_KEYWORDS if kw in lower_path]
+        if not matched:
+            return []
+
+        url = endpoint.full_url
+        method = endpoint.method.upper()
+
+        try:
+            resp = await client.request(method, url)
+        except httpx.RequestError:
+            return []
+
+        response_headers_lower = {k.lower(): v for k, v in resp.headers.items()}
+        body_lower = resp.text.lower()
+
+        has_rate_limit = any(h in response_headers_lower for h in _RATE_LIMIT_INDICATORS)
+        has_captcha = any(ind in body_lower for ind in _CAPTCHA_INDICATORS)
+
+        if has_rate_limit or has_captcha:
+            return []
+
+        protection_hints = []
+        if not has_rate_limit:
+            protection_hints.append("no rate-limit headers detected")
+        if not has_captcha:
+            protection_hints.append("no CAPTCHA indicators detected")
+
+        return [
+            self._make_finding(
+                endpoint,
+                title=f"Sensitive business flow may lack bot/abuse protections",
+                description=(
+                    f"The endpoint path matches sensitive keyword(s): {matched}. "
+                    "No rate-limiting headers or CAPTCHA indicators were found in "
+                    "the response, suggesting it may be susceptible to automated abuse."
+                ),
+                evidence=f"{method} {url} → {resp.status_code}; {'; '.join(protection_hints)}",
+                remediation=(
+                    "Add rate limiting, CAPTCHA challenges, and/or account lockout "
+                    "mechanisms to protect sensitive flows from automated abuse."
+                ),
+                cwe_id="CWE-799",
+                severity="low",
+                confidence=0.5,
+            )
+        ]

mannf/product/security/checks/ssrf.py

@@ -0,0 +1,101 @@
+# 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.
+
+"""API7:2023 — Server Side Request Forgery (SSRF)."""
+
+from __future__ import annotations
+
+import httpx
+
+from mannf.product.security.checks.base import EndpointInfo, SecurityCheck
+from mannf.product.security.models import SecurityFinding
+
+_URL_PARAM_NAMES = {
+    "url", "uri", "href", "link", "src", "source", "redirect",
+    "callback", "webhook", "endpoint", "target", "host", "domain",
+}
+
+_SSRF_PAYLOADS = [
+    "http://localhost:80",
+    "http://127.0.0.1",
+    "http://169.254.169.254/latest/meta-data/",
+    "http://[::1]",
+    "http://0.0.0.0",
+]
+
+
+def _url_params(endpoint: EndpointInfo) -> list[dict]:
+    return [
+        p for p in endpoint.parameters
+        if p.get("name", "").lower() in _URL_PARAM_NAMES
+    ]
+
+
+class SSRFCheck(SecurityCheck):
+    owasp_id = "API7:2023"
+    name = "Server Side Request Forgery"
+    description = "Tests for SSRF by injecting internal URLs into URL-like parameters."
+    severity_default = "high"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        ssrf_params = _url_params(endpoint)
+        if not ssrf_params:
+            return []
+
+        method = endpoint.method.upper()
+        findings: list[SecurityFinding] = []
+
+        for param in ssrf_params:
+            param_name = param["name"]
+            param_in = param.get("in", "query")
+
+            for payload in _SSRF_PAYLOADS:
+                try:
+                    if param_in == "query":
+                        resp = await client.request(
+                            method, endpoint.full_url, params={param_name: payload}
+                        )
+                    elif param_in == "path":
+                        # replace placeholder in path
+                        path = endpoint.path.replace(
+                            "{" + param_name + "}", payload
+                        )
+                        url = f"{endpoint.base_url.rstrip('/')}{path}"
+                        resp = await client.request(method, url)
+                    else:
+                        continue
+                except httpx.RequestError:
+                    continue
+
+                if resp.status_code == 200 and resp.text.strip():
+                    findings.append(
+                        self._make_finding(
+                            endpoint,
+                            title="Possible SSRF: internal URL payload returned data",
+                            description=(
+                                f"Injecting '{payload}' into parameter '{param_name}' "
+                                f"returned HTTP 200 with a non-empty body, which may "
+                                "indicate the server is fetching the provided URL."
+                            ),
+                            evidence=(
+                                f"param={param_name}, payload={payload}, "
+                                f"status={resp.status_code}, "
+                                f"body_snippet={resp.text[:200]}"
+                            ),
+                            remediation=(
+                                "Validate and sanitize all URL parameters against an "
+                                "allowlist of permitted domains/schemes. Use a dedicated "
+                                "HTTP client with no access to internal networks for "
+                                "outbound requests."
+                            ),
+                            cwe_id="CWE-918",
+                            confidence=0.7,
+                        )
+                    )
+                    break  # one finding per param is enough
+
+        return findings

mannf/product/security/checks/unsafe_consumption.py

@@ -0,0 +1,120 @@
+# 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.
+
+"""API10:2023 — Unsafe Consumption of APIs (injection)."""
+
+from __future__ import annotations
+
+import httpx
+
+from mannf.product.security.checks.base import EndpointInfo, SecurityCheck
+from mannf.product.security.models import SecurityFinding
+
+_INJECTION_PAYLOADS: list[tuple[str, str]] = [
+    ("sql", "' OR '1'='1"),
+    ("sql_drop", "'; DROP TABLE users; --"),
+    ("nosql", '{"$gt": ""}'),
+    ("xss", "<script>alert(1)</script>"),
+    ("cmd", "; ls -la"),
+]
+
+_STACK_TRACE_MARKERS = [
+    "Traceback", "at line", "Exception in thread",
+    "NullPointerException", "stack trace", "ORA-", "SQL syntax",
+]
+
+
+class UnsafeConsumptionCheck(SecurityCheck):
+    owasp_id = "API10:2023"
+    name = "Unsafe Consumption of APIs"
+    description = "Tests for injection vulnerabilities in string parameters."
+    severity_default = "high"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        string_params = [
+            p for p in endpoint.parameters
+            if p.get("schema", {}).get("type", "string") == "string"
+            or "type" not in p.get("schema", {})
+        ]
+
+        if not string_params:
+            return []
+
+        method = endpoint.method.upper()
+        findings: list[SecurityFinding] = []
+        seen_endpoints: set[str] = set()
+
+        for param in string_params:
+            param_name = param.get("name", "")
+            param_in = param.get("in", "query")
+            if not param_name:
+                continue
+
+            for payload_type, payload in _INJECTION_PAYLOADS:
+                try:
+                    if param_in == "query":
+                        resp = await client.request(
+                            method,
+                            endpoint.full_url,
+                            params={param_name: payload},
+                        )
+                    elif param_in == "path":
+                        path = endpoint.path.replace(
+                            "{" + param_name + "}", payload
+                        )
+                        url = f"{endpoint.base_url.rstrip('/')}{path}"
+                        resp = await client.request(method, url)
+                    else:
+                        continue
+                except httpx.RequestError:
+                    continue
+
+                body = resp.text
+                reflected = payload in body
+                has_trace = any(m in body for m in _STACK_TRACE_MARKERS)
+                is_500 = resp.status_code == 500
+
+                if not (reflected or has_trace or is_500):
+                    continue
+
+                key = f"{param_name}:{payload_type}"
+                if key in seen_endpoints:
+                    continue
+                seen_endpoints.add(key)
+
+                reasons = []
+                if reflected:
+                    reasons.append("payload reflected in response")
+                if has_trace:
+                    reasons.append("stack trace detected")
+                if is_500:
+                    reasons.append("HTTP 500 returned")
+
+                findings.append(
+                    self._make_finding(
+                        endpoint,
+                        title=f"Possible {payload_type.upper()} injection in parameter '{param_name}'",
+                        description=(
+                            f"Injecting a {payload_type} payload into parameter "
+                            f"'{param_name}' triggered: {', '.join(reasons)}."
+                        ),
+                        evidence=(
+                            f"param={param_name}, payload={payload!r}, "
+                            f"status={resp.status_code}, reasons={reasons}, "
+                            f"snippet={body[:200]}"
+                        ),
+                        remediation=(
+                            "Use parameterized queries and prepared statements for database "
+                            "access. Validate and sanitize all input. Encode output before "
+                            "rendering. Never pass user input to shell commands."
+                        ),
+                        cwe_id="CWE-74",
+                        confidence=0.7 if (reflected or has_trace) else 0.5,
+                    )
+                )
+
+        return findings

mannf/product/security/models.py

@@ -0,0 +1,92 @@
+# 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 finding and report dataclasses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+_severity_order: dict[str, int] = {
+    "critical": 0,
+    "high": 1,
+    "medium": 2,
+    "low": 3,
+    "info": 4,
+}
+
+
+@dataclass
+class SecurityFinding:
+    check_id: str
+    check_name: str
+    severity: str
+    endpoint: str
+    title: str
+    description: str
+    evidence: str
+    remediation: str
+    cwe_id: str
+    confidence: float
+
+
+@dataclass
+class EndpointSecurityPriority:
+    """Per-endpoint prioritization metadata produced by the belief-guided scorer."""
+
+    endpoint: str
+    priority_score: float
+    belief_score: float
+    risk_score: float
+    check_ids: list[str]
+    checks_run: list[str]
+
+    def to_dict(self) -> dict:
+        return {
+            "endpoint": self.endpoint,
+            "priority_score": self.priority_score,
+            "belief_score": self.belief_score,
+            "risk_score": self.risk_score,
+            "check_ids": self.check_ids,
+            "checks_run": self.checks_run,
+        }
+
+
+@dataclass
+class SecurityReport:
+    scan_id: str
+    timestamp: str
+    target_url: str
+    total_endpoints_scanned: int
+    findings: list[SecurityFinding] = field(default_factory=list)
+    summary: dict = field(default_factory=dict)
+    belief_guided: bool = False
+    prioritization: list[EndpointSecurityPriority] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "scan_id": self.scan_id,
+            "timestamp": self.timestamp,
+            "target_url": self.target_url,
+            "total_endpoints_scanned": self.total_endpoints_scanned,
+            "findings": [
+                {
+                    "check_id": f.check_id,
+                    "check_name": f.check_name,
+                    "severity": f.severity,
+                    "endpoint": f.endpoint,
+                    "title": f.title,
+                    "description": f.description,
+                    "evidence": f.evidence,
+                    "remediation": f.remediation,
+                    "cwe_id": f.cwe_id,
+                    "confidence": f.confidence,
+                }
+                for f in self.findings
+            ],
+            "summary": self.summary,
+            "belief_guided": self.belief_guided,
+            "prioritization": [p.to_dict() for p in self.prioritization],
+        }

mannf/product/security/plugin_loader.py

@@ -0,0 +1,182 @@
+# 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.
+
+"""Plugin loader for custom SecurityCheck implementations.
+
+Provides two discovery mechanisms:
+  - Directory scanning: load .py files from a directory path.
+  - Entry-point discovery: use importlib.metadata to find registered plugins.
+
+Both mechanisms validate that each discovered class has the required attributes
+and the ``run`` method before instantiating it.  Invalid plugins are skipped
+with a warning — they will never cause the scanner to crash.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import inspect
+import logging
+import sys
+from importlib.metadata import entry_points
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+from mannf.product.security.checks.base import SecurityCheck
+
+logger = logging.getLogger(__name__)
+
+_REQUIRED_ATTRS = ("owasp_id", "name", "description", "severity_default")
+
+
+def _is_valid_plugin(cls: type) -> bool:
+    """Return True if *cls* is a valid, concrete SecurityCheck subclass."""
+    if not (isinstance(cls, type) and issubclass(cls, SecurityCheck) and cls is not SecurityCheck):
+        return False
+    for attr in _REQUIRED_ATTRS:
+        if not hasattr(cls, attr):
+            logger.warning("Plugin %s is missing required attribute '%s' — skipping.", cls.__name__, attr)
+            return False
+    if not callable(getattr(cls, "run", None)):
+        logger.warning("Plugin %s has no callable 'run' method — skipping.", cls.__name__)
+        return False
+    return True
+
+
+def _instantiate(cls: type) -> SecurityCheck | None:
+    """Try to instantiate *cls*; log a warning and return None on failure."""
+    try:
+        return cls()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Plugin %s raised %s during __init__ — skipping.", cls.__name__, exc)
+        return None
+
+
+def load_plugins_from_directory(path: str) -> list[SecurityCheck]:
+    """Discover and load SecurityCheck subclasses from all ``.py`` files in *path*.
+
+    Parameters
+    ----------
+    path:
+        Filesystem path to a directory containing plugin ``.py`` files.
+
+    Returns
+    -------
+    list[SecurityCheck]
+        Instantiated check objects for every valid plugin found.
+    """
+    plugins: list[SecurityCheck] = []
+    directory = Path(path)
+
+    if not directory.exists():
+        logger.warning("Plugin directory '%s' does not exist — no plugins loaded.", path)
+        return plugins
+
+    if not directory.is_dir():
+        logger.warning("Plugin path '%s' is not a directory — no plugins loaded.", path)
+        return plugins
+
+    for py_file in sorted(directory.glob("*.py")):
+        module_name = f"_nat_plugin_{py_file.stem}"
+        try:
+            spec = importlib.util.spec_from_file_location(module_name, py_file)
+            if spec is None or spec.loader is None:
+                logger.warning("Could not create module spec for '%s' — skipping.", py_file)
+                continue
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module
+            spec.loader.exec_module(module)  # type: ignore[union-attr]
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Failed to import plugin file '%s': %s — skipping.", py_file, exc)
+            continue
+
+        for _name, obj in inspect.getmembers(module, inspect.isclass):
+            if obj.__module__ != module_name:
+                # Avoid re-processing imported base classes
+                continue
+            if _is_valid_plugin(obj):
+                instance = _instantiate(obj)
+                if instance is not None:
+                    plugins.append(instance)
+
+    return plugins
+
+
+def load_plugins_from_entry_points(group: str = "nat.security_checks") -> list[SecurityCheck]:
+    """Discover and load SecurityCheck subclasses registered as package entry points.
+
+    Parameters
+    ----------
+    group:
+        The entry-point group name to scan (default ``"nat.security_checks"``).
+
+    Returns
+    -------
+    list[SecurityCheck]
+        Instantiated check objects for every valid entry point found.
+    """
+    plugins: list[SecurityCheck] = []
+
+    try:
+        eps = entry_points(group=group)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Failed to query entry points for group '%s': %s", group, exc)
+        return plugins
+
+    for ep in eps:
+        try:
+            obj = ep.load()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Failed to load entry point '%s': %s — skipping.", ep.name, exc)
+            continue
+
+        if _is_valid_plugin(obj):
+            instance = _instantiate(obj)
+            if instance is not None:
+                plugins.append(instance)
+        else:
+            logger.warning(
+                "Entry point '%s' does not point to a valid SecurityCheck subclass — skipping.",
+                ep.name,
+            )
+
+    return plugins
+
+
+def load_all_plugins(
+    plugins_dir: str | None = None,
+    entry_point_group: str = "nat.security_checks",
+) -> list[SecurityCheck]:
+    """Load plugins from both a directory and registered entry points, deduplicating by class name.
+
+    Parameters
+    ----------
+    plugins_dir:
+        Optional filesystem path to a directory of plugin ``.py`` files.
+    entry_point_group:
+        Entry-point group to scan (default ``"nat.security_checks"``).
+
+    Returns
+    -------
+    list[SecurityCheck]
+        Merged, deduplicated list of instantiated check objects.
+    """
+    seen_class_names: set[str] = set()
+    combined: list[SecurityCheck] = []
+
+    dir_plugins = load_plugins_from_directory(plugins_dir) if plugins_dir else []
+    ep_plugins = load_plugins_from_entry_points(entry_point_group)
+
+    for plugin in dir_plugins + ep_plugins:
+        class_name = type(plugin).__name__
+        if class_name not in seen_class_names:
+            seen_class_names.add(class_name)
+            combined.append(plugin)
+
+    return combined