nat-engine 1__py3-none-any.whl

mannf/product/orchestration/pipeline.py

@@ -0,0 +1,401 @@
+# 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.
+
+"""Higher-level Pipeline builder for composing ingestor → orchestrator → exporter chains.
+
+The :class:`Pipeline` class provides a fluent builder API for constructing and
+running a complete Ingest → Prioritize → Scan → Export → Learn workflow from
+configuration or CLI arguments.
+
+Usage::
+
+    from mannf.product.orchestration import Pipeline
+
+    result = await (
+        Pipeline()
+        .with_source("openapi.yaml", format="openapi")
+        .with_base_url("http://localhost:8080")
+        .with_auth_token("Bearer eyJ...")
+        .with_severity_threshold("high")
+        .with_exporter("github-issues", repo="org/repo", token="ghp_...")
+        .with_feedback_path("/tmp/nat_feedback.json")
+        .run()
+    )
+
+    print(f"Found {len(result.scan_results.findings)} findings")
+    print(f"Exported {result.export_summaries[0].succeeded} issues")
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from mannf.product.exporters.base import ExporterPlugin
+from mannf.product.ingestors.models import IngestResult
+from mannf.product.orchestration.ingest_scan_orchestrator import IngestScanOrchestrator
+from mannf.product.orchestrator_models import (
+    OrchestrationConfig,
+    OrchestrationResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Pipeline:
+    """Fluent builder for a complete Ingest → Prioritize → Scan → Export → Learn run.
+
+    Each ``with_*`` method returns ``self`` to allow method chaining.  Call
+    :meth:`run` (or :meth:`plan`) to execute the pipeline.
+
+    Parameters
+    ----------
+    config:
+        Optional pre-built :class:`~mannf.product.orchestrator_models.OrchestrationConfig`.
+        If provided, all ``with_*`` calls merge into/override this base config.
+    extra_exporters:
+        Optional additional exporter plugin instances to make available in
+        addition to the built-in exporters.
+    """
+
+    def __init__(
+        self,
+        config: OrchestrationConfig | None = None,
+        extra_exporters: list[ExporterPlugin] | None = None,
+    ) -> None:
+        self._config = config or OrchestrationConfig()
+        self._extra_exporters: list[ExporterPlugin] = extra_exporters or []
+
+    # ------------------------------------------------------------------
+    # Builder methods
+    # ------------------------------------------------------------------
+
+    def with_source(
+        self,
+        path_or_url: str,
+        *,
+        format: str | None = None,  # noqa: A002
+        ingestor_name: str | None = None,
+        ingestor_config: dict | None = None,
+    ) -> "Pipeline":
+        """Set the ingestion source.
+
+        Parameters
+        ----------
+        path_or_url:
+            File system path or URL of the source to ingest.
+        format:
+            Optional format hint (e.g. ``"openapi"``, ``"har"``).
+        ingestor_name:
+            Optional explicit ingestor plugin name (overrides auto-detection).
+        ingestor_config:
+            Extra config dict passed to the ingestor's ``ingest()`` method.
+
+        Returns
+        -------
+        Pipeline
+        """
+        if path_or_url.startswith("http://") or path_or_url.startswith("https://"):
+            self._config.source_url = path_or_url
+            self._config.source_path = None
+        else:
+            self._config.source_path = path_or_url
+            self._config.source_url = None
+        if format is not None:
+            self._config.source_format = format
+        if ingestor_name is not None:
+            self._config.ingestor_name = ingestor_name
+        if ingestor_config is not None:
+            self._config.ingestor_config = {**self._config.ingestor_config, **ingestor_config}
+        return self
+
+    def with_base_url(self, base_url: str) -> "Pipeline":
+        """Set the API base URL for the scan engine.
+
+        Parameters
+        ----------
+        base_url:
+            The root URL of the API under test (e.g. ``"http://localhost:8080"``).
+
+        Returns
+        -------
+        Pipeline
+        """
+        self._config.scan_config = {**self._config.scan_config, "base_url": base_url}
+        return self
+
+    def with_auth_token(self, token: str) -> "Pipeline":
+        """Set a Bearer auth token for scan requests.
+
+        Parameters
+        ----------
+        token:
+            Bearer token (``"Bearer eyJ..."`` or just the token value).
+
+        Returns
+        -------
+        Pipeline
+        """
+        self._config.scan_config = {**self._config.scan_config, "auth_token": token}
+        return self
+
+    def with_api_key(self, api_key: str, header: str = "X-API-Key") -> "Pipeline":
+        """Set an API key for scan requests.
+
+        Parameters
+        ----------
+        api_key:
+            The API key value.
+        header:
+            The header name to send the key in (default ``"X-API-Key"``).
+
+        Returns
+        -------
+        Pipeline
+        """
+        self._config.scan_config = {
+            **self._config.scan_config,
+            "api_key": api_key,
+            "api_key_header": header,
+        }
+        return self
+
+    def with_severity_threshold(self, severity: str) -> "Pipeline":
+        """Set the minimum finding severity to include in the report.
+
+        Parameters
+        ----------
+        severity:
+            One of ``"critical"``, ``"high"``, ``"medium"``, ``"low"``,
+            ``"info"``.
+
+        Returns
+        -------
+        Pipeline
+        """
+        self._config.scan_config = {
+            **self._config.scan_config,
+            "severity_threshold": severity,
+        }
+        return self
+
+    def with_exporter(self, exporter_name: str, **kwargs: Any) -> "Pipeline":
+        """Configure an exporter plugin to run after scanning.
+
+        Parameters
+        ----------
+        exporter_name:
+            Name of the exporter plugin (e.g. ``"github-issues"``, ``"jira"``).
+        **kwargs:
+            Exporter-specific config (e.g. ``repo="org/repo"``, ``token="ghp_..."``).
+
+        Returns
+        -------
+        Pipeline
+        """
+        self._config.exporter_config = {
+            "exporter_name": exporter_name,
+            **kwargs,
+        }
+        return self
+
+    def with_feedback_path(self, path: str) -> "Pipeline":
+        """Set the file path to persist feedback JSON after scanning.
+
+        Parameters
+        ----------
+        path:
+            Absolute or relative path to write the feedback JSON.
+
+        Returns
+        -------
+        Pipeline
+        """
+        self._config.feedback_config = {**self._config.feedback_config, "save_path": path}
+        return self
+
+    def with_belief_guided(self, enabled: bool = True) -> "Pipeline":
+        """Enable or disable belief-guided prioritization.
+
+        Parameters
+        ----------
+        enabled:
+            Whether to use the belief-guided prioritizer (default ``True``).
+
+        Returns
+        -------
+        Pipeline
+        """
+        self._config.scan_config = {
+            **self._config.scan_config,
+            "belief_guided": enabled,
+        }
+        return self
+
+    def with_scan_config(self, **kwargs: Any) -> "Pipeline":
+        """Merge arbitrary key/value pairs into the scan config.
+
+        Parameters
+        ----------
+        **kwargs:
+            Arbitrary scan-level config overrides.
+
+        Returns
+        -------
+        Pipeline
+        """
+        self._config.scan_config = {**self._config.scan_config, **kwargs}
+        return self
+
+    def with_extra_exporters(self, *exporters: ExporterPlugin) -> "Pipeline":
+        """Register additional exporter plugin instances.
+
+        Parameters
+        ----------
+        *exporters:
+            One or more :class:`~mannf.product.exporters.base.ExporterPlugin`
+            instances to make available alongside the built-in exporters.
+
+        Returns
+        -------
+        Pipeline
+        """
+        self._extra_exporters.extend(exporters)
+        return self
+
+    def with_llm(
+        self,
+        provider: str = "openai",
+        *,
+        model: str = "",
+        api_key: str | None = None,
+        priority_threshold: float = 0.7,
+        n_cases: int = 3,
+        **kwargs: Any,
+    ) -> "Pipeline":
+        """Enable LLM-augmented edge-case generation for high-priority endpoints.
+
+        When enabled, the orchestrator will call the configured LLM to generate
+        additional test cases for every endpoint whose priority score meets or
+        exceeds *priority_threshold* before running the security scan.
+
+        Parameters
+        ----------
+        provider:
+            LLM provider name: ``"openai"`` or ``"anthropic"``
+            (default ``"openai"``).
+        model:
+            Model identifier.  Defaults to the provider's built-in default
+            (``"gpt-4o-mini"`` for OpenAI, ``"claude-3-haiku-20240307"`` for
+            Anthropic).
+        api_key:
+            API key.  When ``None``, the provider reads from the environment
+            variable (``OPENAI_API_KEY`` / ``ANTHROPIC_API_KEY``).
+        priority_threshold:
+            Minimum ``priority_score`` (0–1) for a target to receive LLM-generated
+            test cases (default ``0.7``).
+        n_cases:
+            Number of edge-case test cases to generate per qualifying endpoint
+            (default ``3``).
+        **kwargs:
+            Additional key/value pairs merged into
+            :class:`~mannf.product.llm.config.LLMConfig`.
+
+        Returns
+        -------
+        Pipeline
+        """
+        llm_cfg: dict[str, Any] = {
+            "enabled": True,
+            "provider": provider,
+            "priority_threshold": priority_threshold,
+            "n_cases": n_cases,
+            **kwargs,
+        }
+        if model:
+            llm_cfg["model"] = model
+        if api_key is not None:
+            llm_cfg["api_key"] = api_key
+        self._config.llm_config = llm_cfg
+        return self
+
+    # ------------------------------------------------------------------
+    # Execution
+    # ------------------------------------------------------------------
+
+    async def run(self) -> OrchestrationResult:
+        """Execute the full Ingest → Prioritize → Scan → Export → Learn pipeline.
+
+        Returns
+        -------
+        OrchestrationResult
+            Complete pipeline result.
+        """
+        orch = IngestScanOrchestrator(self._config, self._extra_exporters)
+        return await orch.orchestrate()
+
+    async def plan(self) -> OrchestrationResult:
+        """Dry-run mode: ingest + prioritize without scanning.
+
+        Returns
+        -------
+        OrchestrationResult
+            Pipeline result with ``scan_plan`` populated but no scan results.
+        """
+        orch = IngestScanOrchestrator(self._config, self._extra_exporters)
+        return await orch.plan()
+
+    async def run_from_result(self, ingest_result: IngestResult) -> OrchestrationResult:
+        """Run the pipeline from a pre-built :class:`~mannf.product.ingestors.models.IngestResult`.
+
+        Bypasses the file/URL ingest phase — useful when the caller already holds
+        an ``IngestResult`` from any ingestor plugin.
+
+        Parameters
+        ----------
+        ingest_result:
+            A completed ingest result.
+
+        Returns
+        -------
+        OrchestrationResult
+            Complete pipeline result.
+        """
+        orch = IngestScanOrchestrator(self._config, self._extra_exporters)
+        return await orch.orchestrate_from_result(ingest_result)
+
+    async def plan_from_result(self, ingest_result: IngestResult) -> OrchestrationResult:
+        """Dry-run from a pre-built :class:`~mannf.product.ingestors.models.IngestResult`.
+
+        Parameters
+        ----------
+        ingest_result:
+            A completed ingest result.
+
+        Returns
+        -------
+        OrchestrationResult
+            Pipeline result with ``scan_plan`` populated but no scan results.
+        """
+        orch = IngestScanOrchestrator(self._config, self._extra_exporters)
+        return await orch.plan_from_result(ingest_result)
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def config(self) -> OrchestrationConfig:
+        """The current :class:`~mannf.product.orchestrator_models.OrchestrationConfig`."""
+        return self._config
+
+    def build(self) -> IngestScanOrchestrator:
+        """Build and return the :class:`IngestScanOrchestrator` without running it.
+
+        Returns
+        -------
+        IngestScanOrchestrator
+        """
+        return IngestScanOrchestrator(self._config, self._extra_exporters)