nat-engine 1__py3-none-any.whl

mannf/product/orchestrator.py

@@ -0,0 +1,987 @@
+# 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.
+
+"""Orchestration: Ingest → Transform → Prioritize → Scan → Learn.
+
+The :class:`IngestOrchestrator` is the glue layer that connects NAT's ingestor
+plugins to the belief-guided prioritizer and security scan engine, closing the
+end-to-end loop:
+
+    ingest specs/test plans
+        → transform to scan targets
+            → prioritize with belief-guided scorer
+                → scan endpoints
+                    → learn from results (smarter next scan)
+
+Usage::
+
+    from mannf.product.orchestrator import IngestOrchestrator
+    from mannf.product.orchestrator_models import OrchestrationConfig
+
+    config = OrchestrationConfig(
+        source_path="openapi.yaml",
+        source_format="openapi",
+        scan_config={"base_url": "http://localhost:8080"},
+    )
+    orch = IngestOrchestrator(config)
+
+    # Dry run — inspect the plan before scanning
+    plan = await orch.plan()
+
+    # Full run
+    result = await orch.orchestrate()
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from mannf.product.ingestors import (
+    BUILTIN_INGESTORS,
+    get_ingestor_by_name,
+    get_ingestor_for_source,
+)
+from mannf.product.ingestors.models import (
+    IngestedEndpoint,
+    IngestedTestCase,
+    IngestorSource,
+    IngestResult,
+)
+from mannf.product.orchestrator_models import (
+    OrchestrationConfig,
+    OrchestrationResult,
+    ScanFeedback,
+    ScanPlan,
+    ScanTarget,
+)
+from mannf.product.security.belief_guided import prioritize_for_security
+from mannf.product.security.checks.base import EndpointInfo
+from mannf.product.security.models import SecurityReport
+from mannf.product.security.scanner import SecurityScanner
+
+logger = logging.getLogger(__name__)
+
+# Priority string → initial belief hint used as a risk_report score seed.
+_PRIORITY_TO_SCORE: dict[str, float] = {
+    "critical": 0.9,
+    "high": 0.7,
+    "medium": 0.5,
+    "low": 0.3,
+}
+
+
+class IngestOrchestrator:
+    """End-to-end orchestrator that bridges ingestor plugins to the scan engine.
+
+    The orchestrator does **not** re-implement ingestor or scan logic — it
+    connects them.  All heavy lifting (parsing, HTTP probing, belief scoring)
+    is delegated to the existing subsystems.
+
+    Parameters
+    ----------
+    config:
+        Orchestration configuration.  The most important fields are
+        ``source_path`` / ``source_url``, ``source_format`` (or
+        ``ingestor_name``), and ``scan_config["base_url"]``.
+    """
+
+    def __init__(self, config: OrchestrationConfig) -> None:
+        self.config = config
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def orchestrate(self) -> OrchestrationResult:
+        """Run the full ingest → prioritize → scan → learn pipeline.
+
+        Returns
+        -------
+        OrchestrationResult
+            Complete pipeline result including scan findings and feedback.
+        """
+        result = OrchestrationResult(config=self.config)
+
+        # Phase 1: Ingest
+        ingest_result = await self._ingest(result)
+        if ingest_result is None:
+            return result  # fatal ingest error — errors already recorded
+
+        result.ingest_stats = ingest_result.stats
+        result.warnings.extend(ingest_result.warnings)
+
+        # Phase 2 & 3: Transform + Prioritize
+        scan_plan = self._build_scan_plan(ingest_result, result)
+
+        # Phase 3b: LLM edge-case augmentation (optional)
+        scan_plan = await self._augment_scan_plan_with_llm(scan_plan, result)
+
+        result.scan_plan = scan_plan
+
+        if not scan_plan.targets:
+            result.warnings.append("No scan targets produced after transform phase — skipping scan.")
+            return result
+
+        base_url = self.config.scan_config.get("base_url", "")
+        if not base_url:
+            result.errors.append(
+                "scan_config['base_url'] is required to run a scan. "
+                "Use plan() for a dry-run without base_url."
+            )
+            return result
+
+        # Phase 4: Scan
+        scan_report = await self._scan(scan_plan, base_url, result)
+        result.scan_results = scan_report
+
+        # Phase 4b: Root cause analysis for high-severity findings (Phase 10.3)
+        if scan_report is not None and scan_report.findings:
+            await self._run_root_cause_analysis(scan_report, result)
+
+        # Phase 5: Learn
+        if scan_report is not None:
+            feedback = self._compute_feedback(scan_plan, scan_report)
+            result.feedback = feedback
+            await self._persist_feedback(feedback, result)
+
+        return result
+
+    async def plan(self) -> OrchestrationResult:
+        """Dry-run mode: ingest + transform + prioritize, but do not scan.
+
+        Returns
+        -------
+        OrchestrationResult
+            Pipeline result with ``scan_plan`` populated but
+            ``scan_results`` and ``feedback`` left as ``None``.
+        """
+        result = OrchestrationResult(config=self.config)
+
+        ingest_result = await self._ingest(result)
+        if ingest_result is None:
+            return result
+
+        result.ingest_stats = ingest_result.stats
+        result.warnings.extend(ingest_result.warnings)
+
+        scan_plan = self._build_scan_plan(ingest_result, result)
+        # Phase 3b: LLM edge-case augmentation (optional)
+        scan_plan = await self._augment_scan_plan_with_llm(scan_plan, result)
+        result.scan_plan = scan_plan
+        return result
+
+    @classmethod
+    def from_cli_args(cls, args: Any) -> "IngestOrchestrator":
+        """Construct an :class:`IngestOrchestrator` from parsed CLI arguments.
+
+        Parameters
+        ----------
+        args:
+            Namespace object as returned by ``argparse.ArgumentParser.parse_args()``.
+            Expected attributes (all optional unless noted):
+
+            - ``ingest`` — source file path or URL *(required)*
+            - ``ingest_format`` — format hint (e.g. ``"openapi"``)
+            - ``ingestor`` — ingestor name override
+            - ``base_url`` — API base URL
+            - ``auth_token`` — Bearer token
+            - ``api_key`` — API key value
+            - ``api_key_header`` — API key header name (default ``X-API-Key``)
+            - ``severity_threshold`` — minimum severity to report
+            - ``belief_guided`` — bool, enable belief-guided prioritization
+            - ``export`` — exporter plugin name
+            - ``export_config`` — list of ``key=value`` strings
+            - ``feedback_save_path`` — file path to persist feedback JSON
+
+        Returns
+        -------
+        IngestOrchestrator
+        """
+        source = getattr(args, "ingest", None) or ""
+        source_format = getattr(args, "ingest_format", None)
+        ingestor_name = getattr(args, "ingestor", None)
+
+        scan_config: dict = {}
+        base_url = getattr(args, "base_url", None)
+        if base_url:
+            scan_config["base_url"] = base_url
+
+        auth_token = getattr(args, "auth_token", None)
+        if auth_token:
+            scan_config["auth_token"] = auth_token
+
+        api_key = getattr(args, "api_key", None)
+        if api_key:
+            scan_config["api_key"] = api_key
+            scan_config["api_key_header"] = getattr(args, "api_key_header", "X-API-Key")
+
+        severity = getattr(args, "severity_threshold", "low")
+        if severity:
+            scan_config["severity_threshold"] = severity
+
+        belief_guided = getattr(args, "belief_guided", True)
+        scan_config["belief_guided"] = bool(belief_guided)
+
+        # Parse exporter config key=value pairs
+        exporter_config: dict = {}
+        export_name = getattr(args, "export", None)
+        if export_name:
+            exporter_config["exporter_name"] = export_name
+        for pair in (getattr(args, "export_config", None) or []):
+            if "=" in pair:
+                k, _, v = pair.partition("=")
+                exporter_config[k.strip()] = v.strip()
+
+        feedback_config: dict = {}
+        feedback_path = getattr(args, "feedback_save_path", None)
+        if feedback_path:
+            feedback_config["save_path"] = feedback_path
+
+        # Determine if source is a path or a URL
+        source_path: str | None = None
+        source_url: str | None = None
+        if source.startswith("http://") or source.startswith("https://"):
+            source_url = source
+        elif source:
+            source_path = source
+
+        config = OrchestrationConfig(
+            ingestor_name=ingestor_name,
+            source_path=source_path,
+            source_url=source_url,
+            source_format=source_format,
+            scan_config=scan_config,
+            exporter_config=exporter_config,
+            feedback_config=feedback_config,
+        )
+        return cls(config)
+
+    # ------------------------------------------------------------------
+    # Phase 1: Ingest
+    # ------------------------------------------------------------------
+
+    async def _ingest(self, result: OrchestrationResult) -> IngestResult | None:
+        """Run the ingest phase and return the :class:`IngestResult`.
+
+        Returns ``None`` and records an error in *result* on failure.
+        """
+        source = self._build_source()
+
+        # Find the right ingestor
+        ingestor = None
+        if self.config.ingestor_name:
+            ingestor = get_ingestor_by_name(self.config.ingestor_name, BUILTIN_INGESTORS)
+            if ingestor is None:
+                result.errors.append(
+                    f"No ingestor found with name '{self.config.ingestor_name}'. "
+                    f"Available: {[i.name for i in BUILTIN_INGESTORS]}"
+                )
+                return None
+        else:
+            ingestor = get_ingestor_for_source(source, BUILTIN_INGESTORS)
+            if ingestor is None:
+                result.errors.append(
+                    f"Could not auto-detect an ingestor for source format="
+                    f"{source.format!r}, path={source.path!r}, url={source.url!r}. "
+                    "Set ingestor_name in config or provide a source_format hint."
+                )
+                return None
+
+        logger.info("Using ingestor '%s' (%s)", ingestor.name, ingestor.display_name)
+
+        # Validate config
+        config_errors = ingestor.validate_config(self.config.ingestor_config)
+        if config_errors:
+            for err in config_errors:
+                logger.warning("Ingestor config warning: %s", err)
+            result.warnings.extend(config_errors)
+
+        # Run ingestion
+        try:
+            ingest_result: IngestResult = await ingestor.ingest(source, self.config.ingestor_config)
+        except Exception as exc:  # noqa: BLE001
+            result.errors.append(f"Ingestor '{ingestor.name}' raised an exception: {exc}")
+            logger.exception("Ingestor '%s' raised an exception", ingestor.name)
+            return None
+
+        if not ingest_result.success:
+            for err in ingest_result.errors:
+                result.errors.append(f"Ingest error: {err}")
+            return None
+
+        logger.info(
+            "Ingested %d endpoint(s) and %d test case(s) from '%s'.",
+            len(ingest_result.endpoints),
+            len(ingest_result.test_cases),
+            ingestor.name,
+        )
+        if ingest_result.errors:
+            # Partial errors — not fatal
+            result.warnings.extend(
+                f"Ingest partial error: {e}" for e in ingest_result.errors
+            )
+
+        return ingest_result
+
+    # ------------------------------------------------------------------
+    # Phase 2: Transform
+    # ------------------------------------------------------------------
+
+    def _transform_endpoint(self, ep: IngestedEndpoint, base_url: str) -> EndpointInfo:
+        """Convert an :class:`IngestedEndpoint` to an :class:`EndpointInfo`.
+
+        Parameters
+        ----------
+        ep:
+            Ingested endpoint.
+        base_url:
+            API base URL to attach (from ``scan_config`` or ``ingestor_config``).
+
+        Returns
+        -------
+        EndpointInfo
+        """
+        return EndpointInfo(
+            method=ep.method.upper(),
+            path=ep.path,
+            base_url=base_url,
+            parameters=list(ep.parameters),
+            request_body=ep.request_body,
+        )
+
+    def _build_risk_report(
+        self,
+        endpoints: list[IngestedEndpoint],
+        test_cases: list[IngestedTestCase],
+    ) -> list[dict]:
+        """Build a legacy-style risk report that seeds belief scores from ingestor priorities.
+
+        ``IngestedTestCase.priority`` values (``"critical"``, ``"high"``,
+        ``"medium"``, ``"low"``) are translated to float scores and attached to
+        the endpoint paths they appear to relate to.  Auth-required endpoints get
+        a +0.1 boost.
+
+        Parameters
+        ----------
+        endpoints:
+            All ingested endpoints.
+        test_cases:
+            All ingested test cases.
+
+        Returns
+        -------
+        list[dict]
+            Dicts with ``"path"`` and ``"risk_score"`` keys, as consumed by
+            :func:`~mannf.product.security.belief_guided.prioritize_for_security`.
+        """
+        # Aggregate priority hints per path: take the max score across test cases
+        path_scores: dict[str, float] = {}
+
+        for tc in test_cases:
+            score = _PRIORITY_TO_SCORE.get(tc.priority, 0.5)
+            # Match test cases to endpoints by checking tags or source_ref
+            for ep in endpoints:
+                ep_key = ep.path.lower()
+                tc_lower = (tc.name + " " + tc.description + " " + tc.source_ref).lower()
+                tags_match = bool(set(tc.tags) & set(ep.tags))
+                path_in_tc = ep_key in tc_lower or ep.path in tc.source_ref
+                if tags_match or path_in_tc:
+                    existing = path_scores.get(ep.path, 0.0)
+                    path_scores[ep.path] = max(existing, score)
+
+        # For endpoints without any matched test case, use the highest priority
+        # across all test cases as a fallback baseline (or 0.5 if no test cases).
+        fallback = max(
+            (_PRIORITY_TO_SCORE.get(tc.priority, 0.5) for tc in test_cases),
+            default=0.5,
+        )
+
+        report: list[dict] = []
+        for ep in endpoints:
+            base_score = path_scores.get(ep.path, fallback)
+            # Auth-required endpoints are higher risk
+            if ep.auth_requirements:
+                base_score = min(1.0, base_score + 0.1)
+            # source_hint=ai-suggestion → exploratory tag → slight boost
+            if ep.metadata.get("source_hint") == "ai-suggestion":
+                base_score = min(1.0, base_score + 0.05)
+            report.append({"path": ep.path, "risk_score": base_score})
+
+        return report
+
+    # ------------------------------------------------------------------
+    # Phase 2 + 3: Build prioritized ScanPlan
+    # ------------------------------------------------------------------
+
+    def _build_scan_plan(
+        self,
+        ingest_result: IngestResult,
+        result: OrchestrationResult,
+    ) -> ScanPlan:
+        """Transform ingested data into a prioritized :class:`ScanPlan`.
+
+        1. Resolves the base URL from config.
+        2. Converts each :class:`IngestedEndpoint` to an :class:`EndpointInfo`.
+        3. Builds a seed risk report from ingestor priority hints.
+        4. Calls :func:`~mannf.product.security.belief_guided.prioritize_for_security`
+           to order endpoints.
+        5. Associates :class:`IngestedTestCase` objects with their endpoints.
+
+        Parameters
+        ----------
+        ingest_result:
+            Result of the ingest phase.
+        result:
+            Mutable :class:`OrchestrationResult` for recording warnings.
+
+        Returns
+        -------
+        ScanPlan
+        """
+        base_url = (
+            self.config.scan_config.get("base_url")
+            or self.config.ingestor_config.get("base_url")
+            or ""
+        )
+
+        endpoints = ingest_result.endpoints
+        test_cases = ingest_result.test_cases
+
+        if not endpoints:
+            result.warnings.append("Ingestor produced no endpoints — scan plan will be empty.")
+            return ScanPlan(
+                ingest_stats=ingest_result.stats,
+                metadata={"ingestor_name": self.config.ingestor_name or "auto"},
+            )
+
+        # Build EndpointInfo objects for the prioritizer
+        endpoint_infos = [self._transform_endpoint(ep, base_url) for ep in endpoints]
+
+        # Seed the prioritizer with priority hints from the ingestor
+        risk_report = self._build_risk_report(endpoints, test_cases)
+
+        # Allow the orchestration config to override/extend the seed report
+        config_risk_report = self.config.prioritizer_config.get("risk_report")
+        if config_risk_report:
+            risk_report = config_risk_report
+
+        # Belief score overrides from config
+        seed_scores: dict[str, float] = self.config.prioritizer_config.get("seed_belief_scores", {})
+
+        # Run prioritization
+        prioritized = prioritize_for_security(
+            endpoint_infos,
+            risk_report=risk_report,
+        )
+
+        # Apply any explicit seed_belief_scores overrides on top
+        if seed_scores:
+            reordered = []
+            for ep_info, score, check_ids, belief_score, risk_score_val in prioritized:
+                override = seed_scores.get(ep_info.path) or seed_scores.get(
+                    f"{ep_info.method.upper()} {ep_info.path}"
+                )
+                if override is not None:
+                    score = min(1.0, max(0.0, float(override)))
+                reordered.append((ep_info, score, check_ids, belief_score, risk_score_val))
+            reordered.sort(key=lambda t: t[1], reverse=True)
+            prioritized = reordered
+
+        # Build a path → IngestedEndpoint lookup for test case association
+        path_to_ingest: dict[str, IngestedEndpoint] = {ep.path: ep for ep in endpoints}
+
+        # Associate test cases with their best-match endpoint
+        path_to_tcs: dict[str, list[IngestedTestCase]] = {ep.path: [] for ep in endpoints}
+        for tc in test_cases:
+            matched = False
+            for ep in endpoints:
+                tc_lower = (tc.name + " " + tc.description + " " + tc.source_ref).lower()
+                tags_match = bool(set(tc.tags) & set(ep.tags))
+                path_in_tc = ep.path.lower() in tc_lower or ep.path in tc.source_ref
+                if tags_match or path_in_tc:
+                    path_to_tcs[ep.path].append(tc)
+                    matched = True
+                    break
+            if not matched:
+                # Attach unmatched test cases to the first (highest-priority) endpoint
+                if endpoints:
+                    first_path = prioritized[0][0].path if prioritized else endpoints[0].path
+                    path_to_tcs.setdefault(first_path, []).append(tc)
+
+        # Build ScanTarget list
+        targets: list[ScanTarget] = []
+        for ep_info, score, check_ids, _belief_score, _risk_score in prioritized:
+            ingest_ep = path_to_ingest.get(ep_info.path)
+            if ingest_ep is None:
+                continue
+            associated_tcs = path_to_tcs.get(ep_info.path, [])
+            target = ScanTarget(
+                endpoint=ingest_ep,
+                test_cases=associated_tcs,
+                priority_score=score,
+                check_ids=check_ids,
+                metadata={
+                    "ingestor_name": self.config.ingestor_name or "auto",
+                    "auth_required": bool(ingest_ep.auth_requirements),
+                    "tags": ingest_ep.tags,
+                },
+            )
+            targets.append(target)
+
+        return ScanPlan(
+            targets=targets,
+            total_endpoints=len(targets),
+            total_test_cases=sum(len(t.test_cases) for t in targets),
+            ingest_stats=ingest_result.stats,
+            metadata={
+                "ingestor_name": self.config.ingestor_name or "auto",
+                "source_path": self.config.source_path,
+                "source_url": self.config.source_url,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            },
+        )
+
+    # ------------------------------------------------------------------
+    # Phase 3b: LLM edge-case augmentation (optional)
+    # ------------------------------------------------------------------
+
+    async def _augment_scan_plan_with_llm(
+        self,
+        scan_plan: ScanPlan,
+        result: OrchestrationResult,
+    ) -> ScanPlan:
+        """Optionally augment high-priority scan targets with LLM-generated edge cases.
+
+        When ``llm_config`` is set and ``enabled`` is not ``False``, this method
+        invokes the configured LLM provider to generate additional test cases for
+        every target whose ``priority_score`` meets or exceeds the configured
+        ``priority_threshold`` (default ``0.7``).
+
+        The LLM-generated test cases are appended to the target's ``test_cases``
+        list and tagged with ``source_ref="llm-generated"``.
+
+        Errors from the LLM (missing API key, network failures, etc.) are recorded
+        as non-fatal warnings so they never abort a scan.
+
+        Parameters
+        ----------
+        scan_plan:
+            The prioritized scan plan to augment.
+        result:
+            Mutable :class:`OrchestrationResult` for recording warnings.
+
+        Returns
+        -------
+        ScanPlan
+            The (potentially augmented) scan plan.  Returns *scan_plan* unchanged
+            when LLM generation is disabled or encounters an unrecoverable error.
+        """
+        llm_cfg = self.config.llm_config
+        if not llm_cfg:
+            return scan_plan
+
+        if not llm_cfg.get("enabled", True):
+            return scan_plan
+
+        try:
+            from mannf.product.llm.config import LLMConfig
+            from mannf.product.llm.factory import get_provider
+        except ImportError:
+            result.warnings.append(
+                "LLM augmentation requested but the 'llm' module is not available."
+            )
+            return scan_plan
+
+        # Build LLMConfig from the llm_config dict, ignoring orchestration-specific keys
+        skip_keys = {"enabled", "priority_threshold", "n_cases"}
+        llm_init_kwargs = {k: v for k, v in llm_cfg.items() if k not in skip_keys}
+        try:
+            llm_config_obj = LLMConfig(**llm_init_kwargs)
+            provider = get_provider(llm_config_obj)
+        except Exception as exc:  # noqa: BLE001
+            result.warnings.append(f"LLM augmentation: failed to initialise provider: {exc}")
+            return scan_plan
+
+        if not provider.is_available():
+            result.warnings.append(
+                f"LLM provider '{llm_config_obj.provider}' is not available "
+                "(API key missing?).  Skipping edge-case generation."
+            )
+            return scan_plan
+
+        threshold: float = float(llm_cfg.get("priority_threshold", 0.7))
+        n_cases: int = int(llm_cfg.get("n_cases", 3))
+
+        added_total = 0
+        for target in scan_plan.targets:
+            if target.priority_score < threshold:
+                continue
+
+            ep = target.endpoint
+            endpoint_info = {
+                "method": ep.method,
+                "path": ep.path,
+                "description": ep.description or ep.summary,
+                "parameters": ep.parameters,
+                "schema": ep.request_body or {},
+            }
+
+            try:
+                generated = await provider.generate_test_cases(endpoint_info, {}, n=n_cases)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning(
+                    "LLM edge-case generation failed for %s %s: %s",
+                    ep.method,
+                    ep.path,
+                    exc,
+                )
+                result.warnings.append(
+                    f"LLM edge-case generation failed for {ep.method} {ep.path}: {exc}"
+                )
+                continue
+
+            for tc_dict in generated:
+                if not isinstance(tc_dict, dict):
+                    continue
+                tc = IngestedTestCase(
+                    name=tc_dict.get(
+                        "expected_behavior",
+                        f"LLM-generated test case for {ep.path}",
+                    ),
+                    description=str(tc_dict.get("inputs", "")),
+                    expected_result=tc_dict.get("expected_behavior", ""),
+                    priority="high",
+                    tags=["llm-generated", tc_dict.get("test_type", "edge_case")],
+                    source_ref="llm-generated",
+                    metadata={
+                        "generated_by": "llm",
+                        "test_type": tc_dict.get("test_type", "edge_case"),
+                        "inputs": tc_dict.get("inputs", {}),
+                    },
+                )
+                target.test_cases.append(tc)
+                added_total += 1
+
+        if added_total > 0:
+            scan_plan.total_test_cases = sum(len(t.test_cases) for t in scan_plan.targets)
+            logger.info(
+                "LLM augmentation added %d edge-case test case(s) across %d high-priority endpoint(s).",
+                added_total,
+                sum(1 for t in scan_plan.targets if t.priority_score >= threshold),
+            )
+
+        return scan_plan
+
+    # ------------------------------------------------------------------
+    # Phase 4: Scan
+    # ------------------------------------------------------------------
+
+    async def _scan(
+        self,
+        scan_plan: ScanPlan,
+        base_url: str,
+        result: OrchestrationResult,
+    ) -> SecurityReport | None:
+        """Execute the security scan against the prioritized targets.
+
+        Parameters
+        ----------
+        scan_plan:
+            The prioritized scan plan.
+        base_url:
+            API base URL.
+        result:
+            Mutable :class:`OrchestrationResult` for recording errors.
+
+        Returns
+        -------
+        SecurityReport | None
+        """
+        scan_cfg = self.config.scan_config
+        enabled_checks = scan_cfg.get("enabled_checks")
+        severity_threshold = scan_cfg.get("severity_threshold", "low")
+        timeout = float(scan_cfg.get("timeout", 10.0))
+        belief_guided = bool(scan_cfg.get("belief_guided", True))
+
+        scanner = SecurityScanner(
+            base_url=base_url,
+            enabled_checks=enabled_checks,
+            severity_threshold=severity_threshold,
+            timeout=timeout,
+            belief_guided=belief_guided,
+        )
+
+        # Build EndpointInfo list preserving the plan's ordering
+        endpoint_infos = [
+            self._transform_endpoint(t.endpoint, base_url) for t in scan_plan.targets
+        ]
+
+        # Re-use the plan's risk scores as a risk_report seed so the scanner's
+        # own prioritization remains consistent with our plan ordering.
+        risk_report = [
+            {"path": t.endpoint.path, "risk_score": t.priority_score}
+            for t in scan_plan.targets
+        ]
+
+        try:
+            report: SecurityReport = await scanner.scan(
+                endpoints=endpoint_infos,
+                risk_report=risk_report,
+            )
+        except Exception as exc:  # noqa: BLE001
+            result.errors.append(f"Scanner raised an exception: {exc}")
+            logger.exception("SecurityScanner raised an exception")
+            return None
+
+        logger.info(
+            "Scan complete: %d finding(s) across %d endpoint(s).",
+            len(report.findings),
+            report.total_endpoints_scanned,
+        )
+        return report
+
+    # ------------------------------------------------------------------
+    # Phase 4b: Root cause analysis (Phase 10.3)
+    # ------------------------------------------------------------------
+
+    async def _run_root_cause_analysis(
+        self,
+        scan_report: SecurityReport,
+        result: OrchestrationResult,
+    ) -> None:
+        """Best-effort root cause analysis for high/critical security findings.
+
+        Reads LLM config from ``self.config.llm_config``.  Silently skips
+        when no LLM is configured or when there are no high/critical findings.
+        """
+        llm_cfg = self.config.llm_config
+        if not llm_cfg:
+            return
+
+        # Only analyze high/critical findings
+        high_severity = {"critical", "high"}
+        findings_to_analyze = [
+            f for f in scan_report.findings if f.severity in high_severity
+        ]
+        if not findings_to_analyze:
+            return
+
+        try:
+            from mannf.product.llm.config import LLMConfig  # noqa: PLC0415
+            from mannf.product.llm.factory import get_provider  # noqa: PLC0415
+            from mannf.product.llm.root_cause_service import ScanRootCauseAnalyzer  # noqa: PLC0415
+
+            config = LLMConfig(
+                provider=llm_cfg.get("provider", "openai"),
+                model=llm_cfg.get("model", ""),
+                api_key=llm_cfg.get("api_key"),
+            )
+            llm = get_provider(config)
+            quota = int(llm_cfg.get("root_cause_quota", -1))
+            analyzer = ScanRootCauseAnalyzer(llm_provider=llm, quota=quota)
+
+            failures = [
+                {
+                    "id": f.check_id,
+                    "type": "security",
+                    "url": f.endpoint,
+                    "error": f.description,
+                    "severity": f.severity,
+                    "check_id": f.check_id,
+                    "title": f.title,
+                    "cwe_id": f.cwe_id,
+                    "evidence": f.evidence,
+                    "remediation": f.remediation,
+                }
+                for f in findings_to_analyze
+            ]
+
+            suggestions = await analyzer.analyze_failures(
+                failures,
+                {"scan_id": scan_report.scan_id, "scan_type": "security"},
+            )
+            result.root_cause_suggestions = [s.model_dump() for s in suggestions]
+            logger.info(
+                "IngestOrchestrator: root cause analysis produced %d suggestion(s)",
+                len(suggestions),
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("IngestOrchestrator: root cause analysis skipped — %s", exc)
+
+    # ------------------------------------------------------------------
+    # Phase 5: Learn (feedback)
+    # ------------------------------------------------------------------
+
+    def _compute_feedback(
+        self,
+        scan_plan: ScanPlan,
+        scan_report: SecurityReport,
+    ) -> ScanFeedback:
+        """Compute learning feedback from scan results.
+
+        Calculates priority accuracy — did the high-priority endpoints
+        yield more findings than the low-priority ones?
+
+        Parameters
+        ----------
+        scan_plan:
+            The scan plan used.
+        scan_report:
+            The security report from the scan.
+
+        Returns
+        -------
+        ScanFeedback
+        """
+        # Build a map from endpoint key (METHOD /path) → finding count
+        findings_by_endpoint: dict[str, int] = {}
+        for finding in scan_report.findings:
+            findings_by_endpoint[finding.endpoint] = (
+                findings_by_endpoint.get(finding.endpoint, 0) + 1
+            )
+
+        per_target: list[dict] = []
+        suggested_adjustments: dict[str, str] = {}
+
+        for target in scan_plan.targets:
+            ep_key = target.endpoint_key()
+            finding_count = findings_by_endpoint.get(ep_key, 0)
+
+            # Check if any test case expected an outcome that was found/missed
+            outcome_matched = False
+            if target.test_cases:
+                for tc in target.test_cases:
+                    expected = tc.expected_result.lower()
+                    if expected and finding_count > 0 and any(
+                        kw in expected for kw in ("fail", "error", "vulnerability", "issue", "finding")
+                    ):
+                        outcome_matched = True
+                        break
+                    elif not expected and finding_count == 0:
+                        outcome_matched = True
+
+            per_target.append({
+                "endpoint": ep_key,
+                "priority_score": target.priority_score,
+                "findings_count": finding_count,
+                "matched_test_cases": [tc.name for tc in target.test_cases],
+                "outcome_matched": outcome_matched,
+            })
+
+            # Suggest a boost for endpoints that had unexpected findings
+            # (high findings but low priority → should be ranked higher next time)
+            if finding_count > 0 and target.priority_score < 0.5:
+                suggested_adjustments[ep_key] = "increase_priority"
+            # Suggest a decrease for high-priority endpoints with no findings
+            elif finding_count == 0 and target.priority_score > 0.7:
+                suggested_adjustments[ep_key] = "decrease_priority"
+
+        # Priority accuracy: fraction of total findings from the top-50% priority targets
+        total_findings = len(scan_report.findings)
+        if total_findings > 0 and scan_plan.targets:
+            n_top_half = max(1, len(scan_plan.targets) // 2)
+            top_half_keys = {
+                t.endpoint_key() for t in scan_plan.targets[:n_top_half]
+            }
+            top_half_findings = sum(
+                count
+                for ep_key, count in findings_by_endpoint.items()
+                if ep_key in top_half_keys
+            )
+            priority_accuracy = top_half_findings / total_findings
+        else:
+            priority_accuracy = 1.0 if total_findings == 0 else 0.0
+
+        return ScanFeedback(
+            scan_id=scan_report.scan_id,
+            total_targets=len(scan_plan.targets),
+            findings_count=total_findings,
+            per_target=per_target,
+            priority_accuracy=priority_accuracy,
+            suggested_adjustments=suggested_adjustments,
+        )
+
+    async def _persist_feedback(
+        self,
+        feedback: ScanFeedback,
+        result: OrchestrationResult,
+    ) -> None:
+        """Optionally save feedback JSON to disk.
+
+        Parameters
+        ----------
+        feedback:
+            The feedback to persist.
+        result:
+            Mutable :class:`OrchestrationResult` for recording warnings.
+        """
+        save_path = self.config.feedback_config.get("save_path")
+        enabled = self.config.feedback_config.get("enabled", True)
+        if not save_path or not enabled:
+            return
+
+        try:
+            path = Path(save_path)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with path.open("w", encoding="utf-8") as fh:
+                json.dump(feedback.to_dict(), fh, indent=2)
+            logger.info("Feedback saved to %s", save_path)
+        except Exception as exc:  # noqa: BLE001
+            result.warnings.append(f"Could not save feedback to '{save_path}': {exc}")
+            logger.warning("Could not save feedback: %s", exc)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _build_source(self) -> IngestorSource:
+        """Build an :class:`IngestorSource` from config."""
+        fmt = (
+            self.config.source_format
+            or self.config.ingestor_name
+            or _guess_format(self.config.source_path or self.config.source_url or "")
+        )
+        return IngestorSource(
+            format=fmt or "",
+            path=self.config.source_path,
+            url=self.config.source_url,
+        )
+
+
+def _guess_format(source: str) -> str | None:
+    """Heuristically guess the ingestor format from a file path or URL.
+
+    Parameters
+    ----------
+    source:
+        A file path or URL string.
+
+    Returns
+    -------
+    str | None
+        A format string (e.g. ``"openapi"``, ``"har"``) or ``None``.
+    """
+    lower = source.lower()
+    if lower.endswith(".har"):
+        return "har"
+    if lower.endswith(".feature"):
+        return "gherkin"
+    if lower.endswith(".bgstm"):
+        return "bgstm"
+    if "postman" in lower or lower.endswith("collection.json"):
+        return "postman"
+    if lower.endswith(".graphql") or lower.endswith(".gql") or "graphql" in lower:
+        return "graphql"
+    if lower.endswith(".mitmproxy") or lower.endswith(".pcap"):
+        return "traffic"
+    if lower.endswith(".yaml") or lower.endswith(".yml") or lower.endswith(".json"):
+        return "openapi"
+    return None