nat-engine 1__py3-none-any.whl

mannf/core/browser/reflection_analyzer.py

@@ -0,0 +1,442 @@
+# 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.
+
+"""Reflection and canary analysis for browser-level security scenarios.
+
+After the :class:`~mannf.core.functional_orchestrator.FunctionalTestOrchestrator`
+executes a security scenario, this module inspects the task results to detect:
+
+1. **XSS reflection** — the raw payload appears in the DOM response.
+2. **SQL/error-pattern detection** — database error strings (reusing
+   ``_STACK_TRACE_MARKERS`` from ``unsafe_consumption.py``) appear in the page.
+3. **Canary token reflection** — the unique canary embedded alongside the
+   payload appears in unexpected response locations (headers, body, error text).
+4. **SSRF indicators** — internal service response signatures in the output.
+
+Results are returned as :class:`~mannf.product.security.models.SecurityFinding`
+instances so they slot directly into the existing security report pipeline.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Error / stack-trace markers (mirrors unsafe_consumption._STACK_TRACE_MARKERS)
+# ---------------------------------------------------------------------------
+
+_STACK_TRACE_MARKERS: list[str] = [
+    "Traceback",
+    "at line",
+    "Exception in thread",
+    "NullPointerException",
+    "stack trace",
+    "ORA-",
+    "SQL syntax",
+    "mysql_fetch",
+    "pg_query",
+    "SQLiteException",
+    "SQLSTATE",
+    "syntax error",
+    "unterminated quoted string",
+]
+
+# DOM patterns that signal successful XSS execution
+_XSS_EXECUTION_INDICATORS: list[str] = [
+    "alert(",
+    "onerror=",
+    "onload=",
+    "<script>",
+    "javascript:",
+    "eval(",
+]
+
+# Patterns that suggest SSRF success
+_SSRF_RESPONSE_MARKERS: list[str] = [
+    "instance-id",
+    "ami-id",
+    "169.254.169.254",
+    "localhost responded",
+    "127.0.0.1",
+    "Connection refused",
+]
+
+
+# ---------------------------------------------------------------------------
+# ReflectionAnalyzer
+# ---------------------------------------------------------------------------
+
+
+class ReflectionAnalyzer:
+    """Inspect orchestrator task results for security payload execution evidence.
+
+    Parameters
+    ----------
+    security_scenarios:
+        The list of security scenario task dicts that were executed (each
+        should have a ``metadata`` key with ``canary``, ``payload_value``,
+        ``payload_type``, ``target_field``, ``cwe_id``, and
+        ``owasp_category``).
+    task_results:
+        The raw result items from the orchestrator report (list of dicts with
+        at least ``task_id``, ``passed``, ``error``, and optionally ``dom_snapshot``
+        and ``page_url``).
+    """
+
+    def __init__(
+        self,
+        security_scenarios: list[dict[str, Any]],
+        task_results: list[dict[str, Any]],
+    ) -> None:
+        self._scenarios = security_scenarios
+        self._results = task_results
+        # Index results by task_id for fast lookup
+        self._result_map: dict[str, dict[str, Any]] = {
+            r.get("task_id", ""): r for r in task_results
+        }
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def analyze(self) -> list[dict[str, Any]]:
+        """Run all reflection checks and return a list of finding dicts.
+
+        Each finding dict matches the :class:`~mannf.product.security.models.SecurityFinding`
+        dataclass field layout so it can be instantiated directly.
+
+        Returns
+        -------
+        list[dict]
+            Zero or more security finding dicts, each with fields:
+            ``check_id``, ``check_name``, ``severity``, ``endpoint``,
+            ``title``, ``description``, ``evidence``, ``remediation``,
+            ``cwe_id``, ``confidence``.
+        """
+        findings: list[dict[str, Any]] = []
+
+        for scenario in self._scenarios:
+            meta = scenario.get("metadata", {})
+            if meta.get("scenario_type") != "security":
+                continue
+
+            canary = meta.get("canary", "")
+            payload_value = meta.get("payload_value", "")
+            payload_type = meta.get("payload_type", "")
+            target_field = meta.get("target_field", "")
+            cwe_id = meta.get("cwe_id", "CWE-74")
+            owasp_category = meta.get("owasp_category", "")
+            check_id = meta.get("check_id", "BROWSER-SECURITY")
+            page_url = scenario.get("url", "")
+
+            # Find the matching result (match by url + target_field or by order)
+            result = self._find_result(scenario)
+            if result is None:
+                continue
+
+            dom = result.get("dom_snapshot", "")
+            error_text = result.get("error", "") or ""
+            combined_text = f"{dom}\n{error_text}"
+
+            finding = self._check_scenario(
+                check_id=check_id,
+                page_url=page_url,
+                target_field=target_field,
+                payload_type=payload_type,
+                payload_value=payload_value,
+                canary=canary,
+                cwe_id=cwe_id,
+                owasp_category=owasp_category,
+                combined_text=combined_text,
+                result=result,
+            )
+            if finding:
+                findings.append(finding)
+
+        return findings
+
+    # ------------------------------------------------------------------
+    # Internal checks
+    # ------------------------------------------------------------------
+
+    def _check_scenario(
+        self,
+        check_id: str,
+        page_url: str,
+        target_field: str,
+        payload_type: str,
+        payload_value: str,
+        canary: str,
+        cwe_id: str,
+        owasp_category: str,
+        combined_text: str,
+        result: dict[str, Any],
+    ) -> dict[str, Any] | None:
+        """Evaluate a single scenario result for security evidence."""
+        evidence_parts: list[str] = []
+        confidence = 0.0
+        severity = "medium"
+
+        # 1. Canary reflection check
+        if canary and canary in combined_text:
+            evidence_parts.append(f"Canary token '{canary}' reflected in DOM/error output")
+            confidence = max(confidence, 0.7)
+
+        # 2. Raw payload reflection
+        if payload_value and payload_value in combined_text:
+            evidence_parts.append(f"Payload reflected verbatim: {payload_value[:80]!r}")
+            confidence = max(confidence, 0.75)
+
+        # 3. XSS execution indicators
+        if payload_type.startswith("xss"):
+            for indicator in _XSS_EXECUTION_INDICATORS:
+                if indicator.lower() in combined_text.lower():
+                    evidence_parts.append(
+                        f"XSS execution indicator found: {indicator!r}"
+                    )
+                    confidence = max(confidence, 0.85)
+                    severity = "high"
+                    break
+
+        # 4. SQL / stack-trace error detection
+        if payload_type.startswith("sql") or payload_type.startswith("nosql"):
+            for marker in _STACK_TRACE_MARKERS:
+                if marker.lower() in combined_text.lower():
+                    evidence_parts.append(f"Database error marker: {marker!r}")
+                    confidence = max(confidence, 0.80)
+                    severity = "high"
+                    break
+
+        # 5. SSRF indicators
+        if payload_type.startswith("ssrf"):
+            for marker in _SSRF_RESPONSE_MARKERS:
+                if marker.lower() in combined_text.lower():
+                    evidence_parts.append(f"SSRF response marker: {marker!r}")
+                    confidence = max(confidence, 0.90)
+                    severity = "critical"
+                    break
+
+        # 6. HTTP 500 on injection payload
+        status_code = result.get("status_code")
+        if status_code == 500 and payload_type.startswith(("sql", "nosql", "xss")):
+            evidence_parts.append("HTTP 500 returned after injection payload")
+            confidence = max(confidence, 0.60)
+
+        if not evidence_parts:
+            return None
+
+        label_hint = target_field or page_url
+        title = _make_title(payload_type, label_hint)
+        description = _make_description(payload_type, target_field, page_url, owasp_category)
+        remediation = _make_remediation(payload_type)
+
+        return {
+            "check_id": check_id,
+            "check_name": _check_name(payload_type),
+            "severity": severity,
+            "endpoint": f"BROWSER {page_url}#{target_field}",
+            "title": title,
+            "description": description,
+            "evidence": "; ".join(evidence_parts),
+            "remediation": remediation,
+            "cwe_id": cwe_id,
+            "confidence": round(confidence, 2),
+        }
+
+    # ------------------------------------------------------------------
+    # Result lookup
+    # ------------------------------------------------------------------
+
+    def _find_result(self, scenario: dict[str, Any]) -> dict[str, Any] | None:
+        """Find the task result that corresponds to *scenario*."""
+        task_id = scenario.get("task_id", "")
+        if task_id and task_id in self._result_map:
+            return self._result_map[task_id]
+
+        # Fall back to matching by url + target_field metadata
+        meta = scenario.get("metadata", {})
+        target_field = meta.get("target_field", "")
+        page_url = scenario.get("url", "")
+
+        for result in self._results:
+            r_url = result.get("page_url", result.get("url", ""))
+            r_field = result.get("target_field", "")
+            if r_url == page_url and r_field == target_field:
+                return result
+
+        # Last resort: return first result if only one scenario was run
+        if len(self._results) == 1:
+            return self._results[0]
+
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Text-generation helpers
+# ---------------------------------------------------------------------------
+
+
+def _check_name(payload_type: str) -> str:
+    """Return a human-readable check name for a payload type."""
+    names: dict[str, str] = {
+        "xss": "Cross-Site Scripting (XSS)",
+        "sql": "SQL Injection",
+        "nosql": "NoSQL Injection",
+        "path_traversal": "Path Traversal",
+        "crlf": "CRLF Injection",
+        "proto_pollution": "Prototype Pollution",
+        "unicode": "Unicode Normalization Attack",
+        "ssrf": "Server-Side Request Forgery (SSRF)",
+        "llm_security": "LLM-Generated Security Test",
+    }
+    for prefix, name in names.items():
+        if payload_type.startswith(prefix):
+            return name
+    return "Security Injection Test"
+
+
+def _make_title(payload_type: str, label_hint: str) -> str:
+    """Return a short finding title."""
+    name = _check_name(payload_type)
+    hint = label_hint[:60] if label_hint else "unknown field"
+    return f"Possible {name} in '{hint}'"
+
+
+def _make_description(
+    payload_type: str, target_field: str, page_url: str, owasp_category: str
+) -> str:
+    """Return a detailed finding description."""
+    descriptions: dict[str, str] = {
+        "xss": (
+            "An XSS payload injected into the form field was reflected in the page "
+            "DOM without sanitization. An attacker could use this to execute arbitrary "
+            "JavaScript in the context of other users' browsers."
+        ),
+        "sql": (
+            "A SQL injection payload triggered an observable difference (reflection, "
+            "error message, or status code change). The application may be passing "
+            "user input directly to a database query without parameterization."
+        ),
+        "nosql": (
+            "A NoSQL injection payload produced an observable response change, "
+            "suggesting the application may be vulnerable to operator injection attacks."
+        ),
+        "path_traversal": (
+            "A path traversal sequence was accepted by the form and may have been "
+            "processed by the server, potentially allowing unauthorized file access."
+        ),
+        "crlf": (
+            "A CRLF injection sequence was reflected in the response, which could "
+            "allow header injection, HTTP response splitting, or log injection."
+        ),
+        "proto_pollution": (
+            "A prototype pollution payload was submitted via the form. If the server "
+            "merges user-supplied objects without sanitization, this could modify "
+            "shared object prototypes and affect application logic."
+        ),
+        "unicode": (
+            "A Unicode normalization or homoglyph attack payload was reflected without "
+            "normalization. This can be used to bypass security filters or cause "
+            "unexpected behavior in string comparison operations."
+        ),
+        "ssrf": (
+            "An SSRF payload submitted via a URL-accepting field returned response "
+            "content indicating the server made an outbound request to an internal "
+            "or metadata endpoint."
+        ),
+    }
+    for prefix, desc in descriptions.items():
+        if payload_type.startswith(prefix):
+            return (
+                f"{desc}\n\nField: {target_field}, Page: {page_url}, "
+                f"Category: {owasp_category}"
+            )
+    return (
+        f"A security payload in '{target_field}' on {page_url} produced evidence "
+        f"of a potential vulnerability. Category: {owasp_category}"
+    )
+
+
+def _make_remediation(payload_type: str) -> str:
+    """Return remediation advice for a payload type."""
+    remediations: dict[str, str] = {
+        "xss": (
+            "Encode all user-supplied data before rendering it in HTML (use "
+            "context-aware output encoding). Implement a strict Content-Security-Policy "
+            "header. Validate and sanitize input server-side."
+        ),
+        "sql": (
+            "Use parameterized queries or prepared statements for all database access. "
+            "Never concatenate user input into SQL strings. Apply the principle of "
+            "least privilege to database accounts."
+        ),
+        "nosql": (
+            "Validate and sanitize input before passing to database queries. "
+            "Use an allowlist for operator keys. Avoid directly deserializing user "
+            "input into query objects."
+        ),
+        "path_traversal": (
+            "Canonicalize file paths before use and validate they reside within the "
+            "expected directory. Reject paths containing '..' sequences. Use an "
+            "allowlist of permitted file names."
+        ),
+        "crlf": (
+            "Sanitize all user-supplied input before including it in HTTP headers or "
+            "log entries. Strip or encode CR (\\r) and LF (\\n) characters."
+        ),
+        "proto_pollution": (
+            "Avoid using Object.assign or spread operators with user-supplied objects "
+            "without sanitization. Use Object.create(null) for lookup maps. Freeze "
+            "Object.prototype in security-sensitive contexts."
+        ),
+        "unicode": (
+            "Normalize all user input to a canonical Unicode form (NFC/NFKC) before "
+            "comparison or storage. Apply security-aware string comparisons that are "
+            "not susceptible to homoglyph attacks."
+        ),
+        "ssrf": (
+            "Validate and allowlist URLs accepted from user input. Block requests to "
+            "loopback, link-local, and metadata service addresses. Use a dedicated "
+            "egress proxy that enforces network-level controls."
+        ),
+    }
+    for prefix, rem in remediations.items():
+        if payload_type.startswith(prefix):
+            return rem
+    return (
+        "Validate, sanitize, and encode all user-supplied input. Follow OWASP "
+        "Top 10 guidelines for the relevant vulnerability category."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Convenience function for quick analysis
+# ---------------------------------------------------------------------------
+
+
+def analyze_security_results(
+    security_scenarios: list[dict[str, Any]],
+    task_results: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Convenience wrapper around :class:`ReflectionAnalyzer`.
+
+    Parameters
+    ----------
+    security_scenarios:
+        Security scenario task dicts (with security ``metadata``).
+    task_results:
+        Orchestrator result items.
+
+    Returns
+    -------
+    list[dict]
+        Security finding dicts ready for use with
+        :class:`~mannf.product.security.models.SecurityFinding`.
+    """
+    return ReflectionAnalyzer(security_scenarios, task_results).analyze()