nat-engine 1__py3-none-any.whl

mannf/core/browser/security_scenario_generator.py

@@ -0,0 +1,695 @@
+# 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.
+
+"""Browser-level security scenario generator.
+
+Produces task dicts compatible with
+:meth:`~mannf.core.functional_orchestrator.FunctionalTestOrchestrator.run`
+that exercise XSS, SQL injection, path traversal, CRLF injection, prototype
+pollution, Unicode normalization attacks, and SSRF payloads through the
+browser form submission path.
+
+Reuses existing payload sets from the API-level security checks
+(``mannf.product.security.checks``) and adds new browser-specific categories.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Payload catalogues
+# ---------------------------------------------------------------------------
+
+# XSS payloads — various bypass vectors
+_XSS_PAYLOADS: list[tuple[str, str]] = [
+    ("xss_basic", "<script>alert('xss')</script>"),
+    ("xss_img", "<img src=x onerror=alert(1)>"),
+    ("xss_svg", "<svg onload=alert(1)>"),
+    ("xss_javascript_uri", "javascript:alert(document.domain)"),
+    ("xss_event", "\" onmouseover=\"alert(1)"),
+    ("xss_template", "{{7*7}}"),  # server-side template injection probe
+    ("xss_html_entity", "&lt;script&gt;alert(1)&lt;/script&gt;"),
+]
+
+# SQL injection payloads
+_SQL_PAYLOADS: list[tuple[str, str]] = [
+    ("sql_or", "' OR '1'='1"),
+    ("sql_drop", "'; DROP TABLE users; --"),
+    ("sql_union", "' UNION SELECT null,null,null--"),
+    ("sql_time", "' OR SLEEP(5)--"),
+    ("sql_blind", "' AND 1=1--"),
+    ("nosql", '{"$gt": ""}'),
+]
+
+# Path traversal payloads
+_PATH_TRAVERSAL_PAYLOADS: list[tuple[str, str]] = [
+    ("path_traversal_unix", "../../etc/passwd"),
+    ("path_traversal_win", "..\\..\\windows\\system32\\drivers\\etc\\hosts"),
+    ("path_traversal_url", "%2e%2e%2f%2e%2e%2fetc%2fpasswd"),
+    ("path_traversal_null", "../../etc/passwd\x00.jpg"),
+]
+
+# CRLF injection payloads
+_CRLF_PAYLOADS: list[tuple[str, str]] = [
+    ("crlf_basic", "foo\r\nSet-Cookie: injected=1"),
+    ("crlf_url_encoded", "foo%0d%0aSet-Cookie:%20injected=1"),
+    ("crlf_header_split", "value\r\nX-Injected: header"),
+]
+
+# Prototype pollution payloads (relevant for JSON-consuming endpoints)
+_PROTOTYPE_POLLUTION_PAYLOADS: list[tuple[str, str]] = [
+    ("proto_pollution_proto", '__proto__[admin]=true'),
+    ("proto_pollution_constructor", 'constructor[prototype][admin]=true'),
+    ("proto_pollution_json", '{"__proto__":{"admin":true}}'),
+]
+
+# Unicode normalization attack payloads
+_UNICODE_PAYLOADS: list[tuple[str, str]] = [
+    ("unicode_rtl", "\u202e\u0041\u202c"),  # RTL override
+    ("unicode_fullwidth", "\uff1cscript\uff1ealert(1)\uff1c/script\uff1e"),  # fullwidth
+    ("unicode_zero_width", "adm\u200bin"),  # zero-width space inside "admin"
+    ("unicode_homoglyph", "\u0430\u0440\u0433"),  # Cyrillic lookalikes
+]
+
+# SSRF payloads (for URL-like fields)
+_SSRF_PAYLOADS: list[tuple[str, str]] = [
+    ("ssrf_localhost", "http://localhost:80"),
+    ("ssrf_127", "http://127.0.0.1"),
+    ("ssrf_metadata", "http://169.254.169.254/latest/meta-data/"),
+    ("ssrf_ipv6", "http://[::1]"),
+    ("ssrf_0000", "http://0.0.0.0"),
+]
+
+# Mapping of OWASP categories to payload groups
+_OWASP_CATEGORIES: dict[str, str] = {
+    "xss": "A03:2021 — Injection / CWE-79",
+    "sql": "A03:2021 — Injection / CWE-89",
+    "nosql": "A03:2021 — Injection / CWE-943",
+    "path_traversal": "A01:2021 — Path Traversal / CWE-22",
+    "crlf": "A03:2021 — CRLF Injection / CWE-93",
+    "proto_pollution": "A08:2021 — Prototype Pollution / CWE-1321",
+    "unicode": "A03:2021 — Unicode Attack / CWE-116",
+    "ssrf": "A10:2021 — SSRF / CWE-918",
+    "grpc_malformed": "A03:2021 — Injection / CWE-20 (gRPC Malformed Protobuf)",
+    "grpc_oversized": "A05:2021 — Resource Exhaustion / CWE-400 (gRPC Oversized Message)",
+    "grpc_missing": "A03:2021 — Input Validation / CWE-20 (gRPC Missing Required Fields)",
+    "grpc_type_confusion": "A03:2021 — Type Confusion / CWE-843 (gRPC Type Mismatch)",
+}
+
+# CWE IDs per payload category prefix
+_CWE_MAP: dict[str, str] = {
+    "xss": "CWE-79",
+    "sql": "CWE-89",
+    "nosql": "CWE-943",
+    "path_traversal": "CWE-22",
+    "crlf": "CWE-93",
+    "proto_pollution": "CWE-1321",
+    "unicode": "CWE-116",
+    "ssrf": "CWE-918",
+    "grpc_malformed": "CWE-20",
+    "grpc_oversized": "CWE-400",
+    "grpc_missing": "CWE-20",
+    "grpc_type_confusion": "CWE-843",
+}
+
+# ---------------------------------------------------------------------------
+# gRPC-specific fuzz payloads
+# ---------------------------------------------------------------------------
+
+# Malformed protobuf wire bytes — truncated, invalid wire types, etc.
+_GRPC_MALFORMED_PAYLOADS: list[tuple[str, bytes]] = [
+    ("grpc_malformed_truncated", b"\x0a\x05he"),            # truncated length-delimited
+    ("grpc_malformed_invalid_wire", b"\xff\xff\xff\xff"),   # invalid wire type
+    ("grpc_malformed_varint_overflow", b"\x80\x80\x80\x80\x80\x80\x80\x80\x80\x02"),  # overlong varint
+    ("grpc_malformed_empty", b""),                           # empty payload
+    ("grpc_malformed_random", bytes(range(256))),            # all byte values
+]
+
+# Oversized message payloads (serialised as JSON-encoded strings for the dynamic stub)
+_GRPC_OVERSIZED_PAYLOADS: list[tuple[str, str]] = [
+    ("grpc_oversized_string", "A" * 1024 * 1024),          # 1 MB string field
+    ("grpc_oversized_nested", '{"nested": ' + '{"a":1}' * 10000 + '}'),  # deep nesting
+    ("grpc_oversized_array", str(list(range(100_000)))),    # large repeated field
+]
+
+# Missing required fields — empty dict triggers server-side validation
+_GRPC_MISSING_FIELD_PAYLOAD = {}
+
+# Type confusion payloads — send wrong types for fields
+_GRPC_TYPE_CONFUSION_PAYLOADS: list[tuple[str, dict]] = [
+    ("grpc_type_confusion_string_as_int", {"id": "not_an_integer"}),
+    ("grpc_type_confusion_bool_as_string", {"active": "yes"}),
+    ("grpc_type_confusion_null_required", {"name": None}),
+    ("grpc_type_confusion_array_as_scalar", {"count": [1, 2, 3]}),
+]
+
+
+# URL-like field names that should receive SSRF payloads
+_URL_FIELD_HINTS = {
+    "url", "uri", "href", "link", "src", "source", "redirect",
+    "callback", "webhook", "endpoint", "target", "host", "domain", "website",
+}
+
+# Fields that should NOT receive injection payloads (hidden, file, etc.)
+_SKIP_TYPES = {"hidden", "file", "submit", "button", "reset", "image"}
+
+
+def _payload_category(payload_type: str) -> str:
+    """Return the OWASP category label for a given payload type prefix."""
+    for prefix, category in _OWASP_CATEGORIES.items():
+        if payload_type.startswith(prefix):
+            return category
+    return "A03:2021 — Injection"
+
+
+def _cwe_for(payload_type: str) -> str:
+    """Return the CWE identifier for a given payload type prefix."""
+    for prefix, cwe in _CWE_MAP.items():
+        if payload_type.startswith(prefix):
+            return cwe
+    return "CWE-74"
+
+
+def _is_url_field(field: Any) -> bool:
+    """Return True when a field appears to accept URLs (for SSRF probing)."""
+    if field.type in ("url",):
+        return True
+    # Check if any hint keyword appears as a substring in the field metadata
+    candidates = [
+        (field.name or "").lower(),
+        (field.label or "").lower(),
+        (field.placeholder or "").lower(),
+    ]
+    for candidate in candidates:
+        for hint in _URL_FIELD_HINTS:
+            if hint in candidate:
+                return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# SecurityScenarioGenerator
+# ---------------------------------------------------------------------------
+
+
+class SecurityScenarioGenerator:
+    """Generate browser-level security test scenarios from a :class:`DiscoveryModel`.
+
+    Each scenario targets a single form field with a specific attack payload.
+    After the form is submitted the :class:`~mannf.core.browser.reflection_analyzer.ReflectionAnalyzer`
+    post-processes the result to determine whether the payload executed, was
+    reflected, or triggered an error pattern.
+
+    Parameters
+    ----------
+    discovery_model:
+        The structured page graph produced by :class:`WebCrawlerAgent`.
+    llm_provider:
+        Optional LLM provider for adaptive payload generation.  When set,
+        additional field-specific payloads are generated via
+        ``UI_SECURITY_PAYLOAD_PROMPT``.
+    max_payloads_per_field:
+        Maximum number of attack payloads to inject into a single field.
+    include_ssrf:
+        Whether to include SSRF payloads for URL-like fields.
+    include_path_traversal:
+        Whether to include path traversal payloads.
+    include_crlf:
+        Whether to include CRLF injection payloads.
+    include_proto_pollution:
+        Whether to include prototype pollution payloads.
+    include_unicode:
+        Whether to include Unicode normalization attack payloads.
+    """
+
+    def __init__(
+        self,
+        discovery_model: Any,
+        *,
+        llm_provider: Any | None = None,
+        max_payloads_per_field: int = 5,
+        include_ssrf: bool = True,
+        include_path_traversal: bool = True,
+        include_crlf: bool = True,
+        include_proto_pollution: bool = True,
+        include_unicode: bool = True,
+    ) -> None:
+        self._model = discovery_model
+        self._llm = llm_provider
+        self._max_per_field = max_payloads_per_field
+        self._include_ssrf = include_ssrf
+        self._include_path_traversal = include_path_traversal
+        self._include_crlf = include_crlf
+        self._include_proto_pollution = include_proto_pollution
+        self._include_unicode = include_unicode
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def generate(self) -> list[dict[str, Any]]:
+        """Generate security test scenarios from the discovery model.
+
+        Returns
+        -------
+        list[dict]
+            Task dicts compatible with
+            :meth:`~mannf.core.functional_orchestrator.FunctionalTestOrchestrator.run`.
+        """
+        scenarios: list[dict[str, Any]] = []
+        for page in self._model.pages:
+            for form in page.forms:
+                scenarios.extend(self._generate_form_security_scenarios(page, form))
+        return scenarios
+
+    async def generate_async(self) -> list[dict[str, Any]]:
+        """Generate security scenarios, optionally augmented with LLM payloads.
+
+        LLM calls are best-effort — failures fall back to heuristic payloads.
+        """
+        scenarios = self.generate()
+
+        if self._llm is None or not self._llm.is_available():
+            return scenarios
+
+        llm_scenarios: list[dict[str, Any]] = []
+        for page in self._model.pages:
+            for form in page.forms:
+                try:
+                    extra = await self._llm_security_payloads(page, form)
+                    if extra:
+                        llm_scenarios.extend(
+                            self._convert_llm_security_to_scenarios(page, form, extra)
+                        )
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning(
+                        "LLM security-payload call failed for %s: %s", page.url, exc
+                    )
+
+        return scenarios + llm_scenarios
+
+    # ------------------------------------------------------------------
+    # Coverage helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def coverage_categories() -> list[str]:
+        """Return all OWASP categories covered by this generator."""
+        return list(_OWASP_CATEGORIES.values())
+
+    # ------------------------------------------------------------------
+    # Internal — form-level security scenarios
+    # ------------------------------------------------------------------
+
+    def _generate_form_security_scenarios(
+        self, page: Any, form: Any
+    ) -> list[dict[str, Any]]:
+        """Produce security scenarios for every injectable field in *form*."""
+        scenarios: list[dict[str, Any]] = []
+        fillable = [f for f in form.fields if f.type not in _SKIP_TYPES]
+
+        for field in fillable:
+            payloads = self._payloads_for_field(field)
+            for payload_type, payload_value in payloads[: self._max_per_field]:
+                canary = self._make_canary()
+                scenario = self._make_security_scenario(
+                    page=page,
+                    form=form,
+                    fillable=fillable,
+                    target_field=field,
+                    payload_type=payload_type,
+                    payload_value=payload_value,
+                    canary=canary,
+                )
+                scenarios.append(scenario)
+
+        return scenarios
+
+    def _payloads_for_field(self, field: Any) -> list[tuple[str, str]]:
+        """Return the list of (payload_type, payload_value) pairs for *field*."""
+        payloads: list[tuple[str, str]] = []
+
+        # XSS and SQL are broadly applicable to text-like fields
+        if field.type not in ("number", "date", "time", "month", "week", "color"):
+            payloads.extend(_XSS_PAYLOADS)
+            payloads.extend(_SQL_PAYLOADS)
+
+        # SSRF for URL-like fields
+        if self._include_ssrf and _is_url_field(field):
+            payloads.extend(_SSRF_PAYLOADS)
+
+        # Path traversal for fields that might accept file paths or names
+        if self._include_path_traversal and field.type in (
+            "text", "textarea", "search", "url"
+        ):
+            payloads.extend(_PATH_TRAVERSAL_PAYLOADS)
+
+        # CRLF for all text-like fields
+        if self._include_crlf and field.type in ("text", "textarea", "search", "email"):
+            payloads.extend(_CRLF_PAYLOADS)
+
+        # Prototype pollution for text fields that might feed JSON
+        if self._include_proto_pollution and field.type in ("text", "textarea", "search"):
+            payloads.extend(_PROTOTYPE_POLLUTION_PAYLOADS)
+
+        # Unicode attacks for all text-like fields
+        if self._include_unicode and field.type in (
+            "text", "textarea", "search", "email", "password"
+        ):
+            payloads.extend(_UNICODE_PAYLOADS)
+
+        return payloads
+
+    # ------------------------------------------------------------------
+    # Internal — scenario construction
+    # ------------------------------------------------------------------
+
+    def _make_security_scenario(
+        self,
+        page: Any,
+        form: Any,
+        fillable: list[Any],
+        target_field: Any,
+        payload_type: str,
+        payload_value: str,
+        canary: str,
+    ) -> dict[str, Any]:
+        """Build a single security test scenario task dict."""
+        steps: list[dict[str, Any]] = [
+            {"action": "navigate", "selector": page.url, "value": ""},
+        ]
+
+        for field in fillable:
+            if field.selector == target_field.selector:
+                # Embed canary inside the payload so reflection detection is reliable
+                value = f"{payload_value}<!--{canary}-->"
+            else:
+                value = _safe_fill_value(field)
+            if value:
+                steps.append({"action": "fill", "selector": field.selector, "value": value})
+
+        steps.append({"action": "click", "selector": form.submit_selector})
+
+        label_hint = target_field.label or target_field.name or target_field.selector
+        cwe = _cwe_for(payload_type)
+        owasp = _payload_category(payload_type)
+
+        return {
+            "url": page.url,
+            "steps": steps,
+            "metadata": {
+                "scenario_type": "security",
+                "source_page": page.url,
+                "source_form_action": form.action,
+                "description": (
+                    f"Security: {payload_type} payload in '{label_hint}' "
+                    f"({owasp})"
+                ),
+                "generator": "security",
+                "payload_type": payload_type,
+                "payload_value": payload_value,
+                "canary": canary,
+                "target_field": target_field.selector,
+                "cwe_id": cwe,
+                "owasp_category": owasp,
+                "check_id": f"BROWSER-{payload_type.upper().split('_')[0]}",
+            },
+        }
+
+    # ------------------------------------------------------------------
+    # Internal — canary tokens
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _make_canary() -> str:
+        """Generate a unique canary token for reflection detection."""
+        return f"NAT-CANARY-{uuid.uuid4().hex[:12].upper()}"
+
+    # ------------------------------------------------------------------
+    # Internal — LLM adaptive payload generation
+    # ------------------------------------------------------------------
+
+    async def _llm_security_payloads(
+        self, page: Any, form: Any, n: int = 3
+    ) -> list[dict[str, Any]] | None:
+        """Call the LLM for field-specific attack payloads."""
+        if self._llm is None:
+            return None
+        from mannf.product.llm.prompts import UI_SECURITY_PAYLOAD_PROMPT  # noqa: PLC0415
+
+        fields_desc = _format_fields_for_llm(form.fields)
+        prompt = UI_SECURITY_PAYLOAD_PROMPT.format(
+            n=n,
+            page_url=page.url,
+            form_action=form.action,
+            form_method=form.method,
+            fields_description=fields_desc,
+        )
+        import json  # noqa: PLC0415
+        try:
+            raw = await self._llm.generate(prompt)
+            return json.loads(raw)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("LLM security-payload call failed: %s", exc)
+            return None
+
+    def _convert_llm_security_to_scenarios(
+        self, page: Any, form: Any, results: list[dict[str, Any]]
+    ) -> list[dict[str, Any]]:
+        """Convert LLM-generated security payload dicts to scenario task dicts."""
+        scenarios: list[dict[str, Any]] = []
+        fillable = [f for f in form.fields if f.type not in _SKIP_TYPES]
+        field_map = {f.selector: f for f in fillable}
+
+        for item in results:
+            if not isinstance(item, dict):
+                continue
+            inputs = item.get("inputs", {})
+            payload_type = item.get("payload_type", "llm_security")
+            if not inputs:
+                continue
+
+            steps: list[dict[str, Any]] = [
+                {"action": "navigate", "selector": page.url, "value": ""},
+            ]
+            canary = self._make_canary()
+            target_selector = ""
+
+            for selector, value in inputs.items():
+                if selector not in field_map:
+                    continue
+                if not target_selector:
+                    target_selector = selector
+                    value = f"{value}<!--{canary}-->"
+                steps.append({"action": "fill", "selector": selector, "value": str(value)})
+
+            if not target_selector:
+                continue
+
+            steps.append({"action": "click", "selector": form.submit_selector})
+            cwe = _cwe_for(payload_type)
+            owasp = _payload_category(payload_type)
+
+            scenarios.append({
+                "url": page.url,
+                "steps": steps,
+                "metadata": {
+                    "scenario_type": "security",
+                    "source_page": page.url,
+                    "source_form_action": form.action,
+                    "description": (
+                        f"LLM-security: {payload_type} — "
+                        f"{item.get('description', '')}"
+                    ),
+                    "generator": "llm_security",
+                    "payload_type": payload_type,
+                    "canary": canary,
+                    "target_field": target_selector,
+                    "cwe_id": cwe,
+                    "owasp_category": owasp,
+                    "check_id": f"BROWSER-{payload_type.upper().split('_')[0]}",
+                },
+            })
+
+        return scenarios
+
+    # ------------------------------------------------------------------
+    # gRPC-specific fuzz scenario generation
+    # ------------------------------------------------------------------
+
+    def generate_grpc_fuzz_scenarios(
+        self,
+        grpc_method: str,
+        rpc_type: str = "unary",
+        include_malformed: bool = True,
+        include_oversized: bool = True,
+        include_missing_fields: bool = True,
+        include_type_confusion: bool = True,
+        max_per_category: int = 3,
+    ) -> list[dict[str, Any]]:
+        """Generate gRPC-specific security fuzz scenarios for a single RPC method.
+
+        Produces test case dicts compatible with :class:`GrpcSUT.execute` that
+        exercise malformed protobuf bytes, oversized messages, missing required
+        fields, and type-confused payloads.
+
+        Parameters
+        ----------
+        grpc_method:
+            Full gRPC method path (e.g. ``"/helloworld.Greeter/SayHello"``).
+        rpc_type:
+            RPC type: ``"unary"``, ``"server_streaming"``,
+            ``"client_streaming"``, or ``"bidi_streaming"`` (default: unary).
+        include_malformed:
+            Include malformed protobuf wire-byte payloads.
+        include_oversized:
+            Include oversized message payloads.
+        include_missing_fields:
+            Include empty/missing-required-field payloads.
+        include_type_confusion:
+            Include type-confused field payloads.
+        max_per_category:
+            Maximum payloads per category (default: 3).
+
+        Returns
+        -------
+        list of dict
+            Scenario dicts with ``grpc_method``, ``request``, and ``metadata``.
+        """
+        scenarios: list[dict[str, Any]] = []
+
+        if include_malformed:
+            for payload_type, raw_bytes in _GRPC_MALFORMED_PAYLOADS[:max_per_category]:
+                cwe = _cwe_for(payload_type)
+                owasp = _payload_category(payload_type)
+                scenarios.append({
+                    "grpc_method": grpc_method,
+                    "rpc_type": rpc_type,
+                    "request_raw": list(raw_bytes),  # JSON-serialisable
+                    "metadata": {
+                        "scenario_type": "grpc_security",
+                        "generator": "security",
+                        "payload_type": payload_type,
+                        "description": (
+                            f"gRPC security: {payload_type} — malformed protobuf bytes "
+                            f"for {grpc_method}"
+                        ),
+                        "grpc_method": grpc_method,
+                        "cwe_id": cwe,
+                        "owasp_category": owasp,
+                        "check_id": f"GRPC-{payload_type.upper().split('_')[0]}",
+                    },
+                })
+
+        if include_oversized:
+            for payload_type, oversized_value in _GRPC_OVERSIZED_PAYLOADS[:max_per_category]:
+                cwe = _cwe_for(payload_type)
+                owasp = _payload_category(payload_type)
+                scenarios.append({
+                    "grpc_method": grpc_method,
+                    "rpc_type": rpc_type,
+                    "request": {"data": oversized_value},
+                    "metadata": {
+                        "scenario_type": "grpc_security",
+                        "generator": "security",
+                        "payload_type": payload_type,
+                        "description": (
+                            f"gRPC security: {payload_type} — oversized message "
+                            f"for {grpc_method}"
+                        ),
+                        "grpc_method": grpc_method,
+                        "cwe_id": cwe,
+                        "owasp_category": owasp,
+                        "check_id": "GRPC-OVERSIZED",
+                    },
+                })
+
+        if include_missing_fields:
+            cwe = _cwe_for("grpc_missing")
+            owasp = _payload_category("grpc_missing")
+            scenarios.append({
+                "grpc_method": grpc_method,
+                "rpc_type": rpc_type,
+                "request": _GRPC_MISSING_FIELD_PAYLOAD,
+                "metadata": {
+                    "scenario_type": "grpc_security",
+                    "generator": "security",
+                    "payload_type": "grpc_missing_fields",
+                    "description": (
+                        f"gRPC security: missing required fields for {grpc_method}"
+                    ),
+                    "grpc_method": grpc_method,
+                    "cwe_id": cwe,
+                    "owasp_category": owasp,
+                    "check_id": "GRPC-MISSING-FIELDS",
+                },
+            })
+
+        if include_type_confusion:
+            for payload_type, request_dict in _GRPC_TYPE_CONFUSION_PAYLOADS[:max_per_category]:
+                cwe = _cwe_for(payload_type)
+                owasp = _payload_category(payload_type)
+                scenarios.append({
+                    "grpc_method": grpc_method,
+                    "rpc_type": rpc_type,
+                    "request": request_dict,
+                    "metadata": {
+                        "scenario_type": "grpc_security",
+                        "generator": "security",
+                        "payload_type": payload_type,
+                        "description": (
+                            f"gRPC security: {payload_type} — type confusion "
+                            f"for {grpc_method}"
+                        ),
+                        "grpc_method": grpc_method,
+                        "cwe_id": cwe,
+                        "owasp_category": owasp,
+                        "check_id": "GRPC-TYPE-CONFUSION",
+                    },
+                })
+
+        return scenarios
+
+
+
+
+def _safe_fill_value(field: Any) -> str:
+    """Return a safe, benign fill value for a non-target field."""
+    type_defaults: dict[str, str] = {
+        "email": "test@example.com",
+        "password": "TestP@ss123!",
+        "tel": "555-0100",
+        "number": "1",
+        "date": "2024-01-01",
+        "url": "https://example.com",
+        "checkbox": "true",
+        "select": "",
+        "textarea": "test input",
+    }
+    return type_defaults.get(field.type, "test")
+
+
+def _format_fields_for_llm(fields: list[Any]) -> str:
+    """Format field descriptors for LLM prompts."""
+    lines: list[str] = []
+    for f in fields:
+        parts = [
+            f"  - selector={f.selector!r}",
+            f"type={f.type!r}",
+            f"required={f.required}",
+        ]
+        if f.label:
+            parts.append(f"label={f.label!r}")
+        if f.name:
+            parts.append(f"name={f.name!r}")
+        if f.pattern:
+            parts.append(f"pattern={f.pattern!r}")
+        lines.append(", ".join(parts))
+    return "\n".join(lines)