nat-engine 1__py3-none-any.whl

mannf/product/orchestration/ingest_scan_orchestrator.py

@@ -0,0 +1,339 @@
+# 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.
+
+"""IngestScanOrchestrator — closed-loop Ingest → Prioritize → Scan → Export → Learn pipeline.
+
+This module extends :class:`~mannf.product.orchestrator.IngestOrchestrator` with:
+
+1. **Direct IngestResult intake** — :meth:`IngestScanOrchestrator.orchestrate_from_result`
+   accepts a pre-built :class:`~mannf.product.ingestors.models.IngestResult` produced by
+   any ingestor plugin, bypassing the file/URL ingest phase entirely.  This is the primary
+   entry point when the caller already holds the ingestor output.
+
+2. **Exporter integration** — after scanning, the orchestrator dispatches findings to all
+   configured :class:`~mannf.product.exporters.base.ExporterPlugin` instances and records
+   the export summaries in :class:`OrchestrationResult`.
+
+Usage::
+
+    from mannf.product.orchestration import IngestScanOrchestrator
+    from mannf.product.orchestrator_models import OrchestrationConfig
+
+    # Run from a file source (same as IngestOrchestrator)
+    config = OrchestrationConfig(
+        source_path="openapi.yaml",
+        scan_config={"base_url": "http://localhost:8080"},
+        exporter_config={"exporter_name": "github-issues", "repo": "org/repo"},
+    )
+    orch = IngestScanOrchestrator(config)
+    result = await orch.orchestrate()
+
+    # --- OR ---
+
+    # Run from a pre-built IngestResult (e.g., from a custom ingestor)
+    from mannf.product.ingestors.openapi_ingestor import OpenAPIIngestor
+    from mannf.product.ingestors.models import IngestorSource
+
+    ingestor = OpenAPIIngestor()
+    source = IngestorSource(format="openapi", path="api.yaml")
+    ingest_result = await ingestor.ingest(source, {})
+
+    result = await orch.orchestrate_from_result(ingest_result)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from mannf.product.exporters import BUILTIN_EXPORTERS, get_exporter_by_name
+from mannf.product.exporters.base import ExportSummary, ExporterPlugin
+from mannf.product.ingestors.models import IngestResult
+from mannf.product.orchestrator import IngestOrchestrator
+from mannf.product.orchestrator_models import (
+    OrchestrationConfig,
+    OrchestrationResult,
+    ScanPlan,
+)
+from mannf.product.security.models import SecurityReport
+
+logger = logging.getLogger(__name__)
+
+
+class IngestScanOrchestrator(IngestOrchestrator):
+    """Extended orchestrator that adds direct IngestResult intake and exporter dispatch.
+
+    Inherits the full Ingest → Prioritize → Scan → Learn pipeline from
+    :class:`~mannf.product.orchestrator.IngestOrchestrator` and adds:
+
+    * :meth:`orchestrate_from_result` — bypass the file/URL ingest phase when
+      the caller already has an :class:`~mannf.product.ingestors.models.IngestResult`.
+    * Exporter dispatch — automatically calls configured exporter plugins on the
+      scan report after scanning completes.
+
+    Parameters
+    ----------
+    config:
+        Orchestration configuration.  The ``exporter_config`` dict controls
+        exporter dispatch:
+        - ``"exporter_name"`` — name of the built-in exporter to use
+          (e.g. ``"github-issues"``, ``"jira"``).
+        - ``"min_severity"`` — minimum finding severity to export
+          (default ``"low"``).
+        - All remaining keys are passed verbatim to the exporter.
+    extra_exporters:
+        Optional list of additional :class:`~mannf.product.exporters.base.ExporterPlugin`
+        instances to invoke alongside the built-in ones.  Useful for tests or
+        custom plug-ins that are not registered in ``BUILTIN_EXPORTERS``.
+    """
+
+    def __init__(
+        self,
+        config: OrchestrationConfig,
+        extra_exporters: list[ExporterPlugin] | None = None,
+    ) -> None:
+        super().__init__(config)
+        self._extra_exporters: list[ExporterPlugin] = extra_exporters or []
+
+    # ------------------------------------------------------------------
+    # Public API — direct IngestResult entry point
+    # ------------------------------------------------------------------
+
+    async def orchestrate_from_result(
+        self,
+        ingest_result: IngestResult,
+    ) -> OrchestrationResult:
+        """Run the full prioritize → scan → export → learn pipeline from an existing result.
+
+        This method is the primary entry point when the caller has already
+        obtained an :class:`~mannf.product.ingestors.models.IngestResult` from
+        any ingestor plugin.  It skips the file/URL ingest phase entirely.
+
+        Parameters
+        ----------
+        ingest_result:
+            A completed ingest result produced by any
+            :class:`~mannf.product.ingestors.base.IngestorPlugin` implementation.
+
+        Returns
+        -------
+        OrchestrationResult
+            Complete pipeline result including scan findings, export summaries,
+            and feedback for the next run.
+        """
+        result = OrchestrationResult(config=self.config)
+
+        if not ingest_result.success:
+            for err in ingest_result.errors:
+                result.errors.append(f"Ingest error: {err}")
+            return result
+
+        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. "
+                "Build the scan plan with plan() / plan_from_result() for a dry run."
+            )
+            return result
+
+        # Phase 4: Scan
+        scan_report = await self._scan(scan_plan, base_url, result)
+        result.scan_results = scan_report
+
+        # Phase 4b: Export
+        if scan_report is not None:
+            export_summaries = await self._export(scan_report, result)
+            result.export_summaries = export_summaries
+
+        # 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_from_result(
+        self,
+        ingest_result: IngestResult,
+    ) -> OrchestrationResult:
+        """Dry-run mode: prioritize but do not scan.
+
+        Useful for inspecting the prioritized scan plan before committing to
+        a full scan.
+
+        Parameters
+        ----------
+        ingest_result:
+            A completed ingest result.
+
+        Returns
+        -------
+        OrchestrationResult
+            Pipeline result with ``scan_plan`` populated but ``scan_results``
+            and ``feedback`` left as ``None``.
+        """
+        result = OrchestrationResult(config=self.config)
+
+        if not ingest_result.success:
+            for err in ingest_result.errors:
+                result.errors.append(f"Ingest error: {err}")
+            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
+
+    # Override orchestrate() to add exporter dispatch
+    async def orchestrate(self) -> OrchestrationResult:
+        """Run the full ingest → prioritize → scan → export → learn pipeline.
+
+        Extends :meth:`~mannf.product.orchestrator.IngestOrchestrator.orchestrate`
+        by also dispatching scan results to configured exporter plugins.
+
+        Returns
+        -------
+        OrchestrationResult
+            Complete pipeline result including scan findings, export summaries,
+            and feedback.
+        """
+        result = await super().orchestrate()
+
+        # Export findings if a scan was performed
+        if result.scan_results is not None and not result.errors:
+            export_summaries = await self._export(result.scan_results, result)
+            result.export_summaries = export_summaries
+
+        return result
+
+    # ------------------------------------------------------------------
+    # Phase 4b: Export
+    # ------------------------------------------------------------------
+
+    async def _export(
+        self,
+        scan_report: SecurityReport,
+        result: OrchestrationResult,
+    ) -> list[ExportSummary]:
+        """Dispatch findings to configured exporter plugins.
+
+        Parameters
+        ----------
+        scan_report:
+            The completed security scan report.
+        result:
+            Mutable :class:`OrchestrationResult` for recording warnings.
+
+        Returns
+        -------
+        list[ExportSummary]
+            One :class:`~mannf.product.exporters.base.ExportSummary` per
+            exporter that was invoked.  Empty if no exporter is configured.
+        """
+        exporter_cfg = self.config.exporter_config
+        if not exporter_cfg:
+            return []
+
+        exporter_name = exporter_cfg.get("exporter_name")
+        if not exporter_name:
+            return []
+
+        # Resolve the exporter: check extra_exporters first, then built-ins
+        all_exporters = self._extra_exporters + BUILTIN_EXPORTERS
+        exporter = get_exporter_by_name(exporter_name, all_exporters)
+        if exporter is None:
+            result.warnings.append(
+                f"Exporter '{exporter_name}' not found. "
+                f"Available: {[e.name for e in all_exporters]}"
+            )
+            return []
+
+        # Validate exporter config
+        # Build the config to pass — everything except exporter_name
+        export_call_config = {k: v for k, v in exporter_cfg.items() if k != "exporter_name"}
+
+        config_errors = exporter.validate_config(export_call_config)
+        if config_errors:
+            for err in config_errors:
+                result.warnings.append(f"Exporter '{exporter_name}' config warning: {err}")
+
+        min_severity = exporter_cfg.get("min_severity", "low")
+
+        logger.info(
+            "Exporting %d finding(s) via '%s' (min_severity=%s).",
+            len(scan_report.findings),
+            exporter_name,
+            min_severity,
+        )
+
+        try:
+            summary = await exporter.export_findings(
+                findings=scan_report.findings,
+                report=scan_report,
+                config=export_call_config,
+                min_severity=min_severity,
+            )
+        except Exception as exc:  # noqa: BLE001
+            result.warnings.append(
+                f"Exporter '{exporter_name}' raised an exception: {exc}"
+            )
+            logger.exception("Exporter '%s' raised an exception", exporter_name)
+            return []
+
+        logger.info(
+            "Export complete via '%s': %d succeeded, %d failed, %d skipped.",
+            exporter_name,
+            summary.succeeded,
+            summary.failed,
+            summary.skipped,
+        )
+        return [summary]
+
+    # ------------------------------------------------------------------
+    # Factory
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_cli_args(cls, args: Any) -> "IngestScanOrchestrator":  # type: ignore[override]
+        """Construct an :class:`IngestScanOrchestrator` from parsed CLI arguments.
+
+        Delegates to :meth:`~mannf.product.orchestrator.IngestOrchestrator.from_cli_args`
+        and returns an :class:`IngestScanOrchestrator` instance.
+
+        Parameters
+        ----------
+        args:
+            Namespace object as returned by ``argparse.ArgumentParser.parse_args()``.
+            See :meth:`~mannf.product.orchestrator.IngestOrchestrator.from_cli_args`
+            for the full list of expected attributes.
+
+        Returns
+        -------
+        IngestScanOrchestrator
+        """
+        base = IngestOrchestrator.from_cli_args(args)
+        return cls(base.config)