nat-engine 1__py3-none-any.whl

mannf/product/exporters/webhook_exporter.py

@@ -0,0 +1,383 @@
+# 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.
+
+"""Generic Webhook exporter plugin — POSTs NAT findings as JSON to any HTTP endpoint.
+
+This exporter enables integration with Zapier, n8n, Make, or any custom HTTP
+endpoint without needing a dedicated plugin.
+
+Usage
+-----
+Export findings to a webhook endpoint by supplying the following config keys
+via ``--export-config`` on the CLI::
+
+    nat security-scan --spec api.yaml --base-url http://localhost \\
+      --export webhook \\
+      --export-config webhook_url=https://hooks.example.com/nat \\
+      --export-config hmac_secret=$WEBHOOK_SECRET
+
+Example with batch mode::
+
+    nat security-scan --spec api.yaml --base-url http://localhost \\
+      --export webhook \\
+      --export-config webhook_url=https://hooks.zapier.com/hooks/catch/... \\
+      --export-config batch_mode=true
+
+Required config keys
+--------------------
+webhook_url:  The HTTP(S) URL to POST findings to.
+
+Optional config keys
+--------------------
+auth_header:            Value for the ``Authorization`` header (e.g.,
+                        ``"Bearer mytoken"`` or ``"Basic abc123"``).
+custom_headers:         Dict of additional HTTP headers to include in every
+                        request.
+hmac_secret:            If provided, compute HMAC-SHA256 of the JSON payload
+                        body and include it as ``X-NAT-Signature: sha256=<hex>``
+                        header.  Use this to verify the webhook origin on the
+                        receiving end.
+include_report_context: Whether to include scan-level context (scan_id,
+                        timestamp, target_url) in each finding payload.
+                        Defaults to ``true``.
+batch_mode:             If ``true``, send all findings in a single POST as a
+                        JSON array.  If ``false`` (default), send one POST per
+                        finding.
+timeout:                HTTP request timeout in seconds (default ``30``).
+
+Security considerations
+-----------------------
+* Always use HTTPS webhook URLs so payloads are encrypted in transit.
+* Use ``hmac_secret`` to authenticate the source of the webhook.  On the
+  receiving end, recompute HMAC-SHA256 of the raw body with the shared secret
+  and compare it to the ``X-NAT-Signature`` header value.
+* Store the HMAC secret in an environment variable rather than hard-coding it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import logging
+from datetime import datetime, timezone
+
+import httpx
+
+from mannf.product.exporters.base import ExportResult, ExportSummary, ExporterPlugin, TestConnectionResult
+from mannf.product.security.models import SecurityFinding, SecurityReport
+
+logger = logging.getLogger(__name__)
+
+
+class WebhookExporter(ExporterPlugin):
+    """Exports NAT security findings as JSON payloads to any HTTP webhook endpoint.
+
+    Required config keys:
+        webhook_url: The HTTP(S) URL to POST findings to.
+
+    Optional config keys:
+        auth_header:            ``Authorization`` header value.
+        custom_headers:         Dict of additional HTTP headers.
+        hmac_secret:            Shared secret for HMAC-SHA256 request signing.
+        include_report_context: Include scan-level context in each payload
+                                (default ``true``).
+        batch_mode:             Send all findings in one POST as a JSON array
+                                (default ``false``).
+        timeout:                HTTP timeout in seconds (default ``30``).
+
+    Example CLI usage::
+
+        nat security-scan --spec api.yaml --base-url http://localhost \\
+          --export webhook \\
+          --export-config webhook_url=https://hooks.example.com/nat \\
+          --export-config hmac_secret=$WEBHOOK_SECRET
+    """
+
+    name = "webhook"
+    display_name = "Generic Webhook"
+    description = "Export NAT findings as JSON payloads to any HTTP webhook endpoint."
+
+    # ------------------------------------------------------------------
+    # Config validation
+    # ------------------------------------------------------------------
+
+    def validate_config(self, config: dict) -> list[str]:
+        errors: list[str] = []
+
+        webhook_url = config.get("webhook_url", "")
+        if not webhook_url:
+            errors.append("'webhook_url' is required")
+        elif not (webhook_url.startswith("http://") or webhook_url.startswith("https://")):
+            errors.append("'webhook_url' must start with 'http://' or 'https://'")
+
+        timeout = config.get("timeout")
+        if timeout is not None:
+            try:
+                t = float(timeout)
+                if t <= 0:
+                    errors.append("'timeout' must be a positive number")
+            except (TypeError, ValueError):
+                errors.append("'timeout' must be a positive number")
+
+        custom_headers = config.get("custom_headers")
+        if custom_headers is not None and not isinstance(custom_headers, dict):
+            errors.append("'custom_headers' must be a dict")
+
+        return errors
+
+    # ------------------------------------------------------------------
+    # Connection test
+    # ------------------------------------------------------------------
+
+    async def test_connection(self, config: dict) -> TestConnectionResult:
+        """Test connectivity via HEAD (or OPTIONS) on the webhook_url — confirms URL is reachable."""
+        errors = self.validate_config(config)
+        if errors:
+            return TestConnectionResult(
+                success=False,
+                message=f"Config validation failed: {'; '.join(errors)}",
+                details={"errors": errors},
+            )
+
+        webhook_url = config["webhook_url"]
+        timeout = self._get_timeout(config)
+
+        # Build minimal headers (auth only — no HMAC needed for a probe)
+        probe_headers: dict[str, str] = {}
+        if config.get("auth_header"):
+            probe_headers["Authorization"] = config["auth_header"]
+        if isinstance(config.get("custom_headers"), dict):
+            probe_headers.update(config["custom_headers"])
+
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                # Try HEAD first; fall back to OPTIONS if HEAD is not allowed
+                resp = await client.head(webhook_url, headers=probe_headers)
+                if resp.status_code == 405:
+                    resp = await client.options(webhook_url, headers=probe_headers)
+                # Treat any 2xx or 3xx as reachable; even 4xx means the URL exists
+                reachable = resp.status_code < 500
+        except httpx.RequestError as exc:
+            return TestConnectionResult(
+                success=False,
+                message=f"Webhook URL unreachable: {exc}",
+                details={"webhook_url": webhook_url},
+            )
+
+        if not reachable:
+            return TestConnectionResult(
+                success=False,
+                message=f"Webhook URL returned server error {resp.status_code}",
+                details={"webhook_url": webhook_url, "status_code": resp.status_code},
+            )
+
+        return TestConnectionResult(
+            success=True,
+            message=f"Webhook URL is reachable (HTTP {resp.status_code})",
+            details={"webhook_url": webhook_url, "status_code": resp.status_code},
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _build_headers(self, body_bytes: bytes, config: dict) -> dict[str, str]:
+        """Build the full HTTP headers dict for a webhook request."""
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+
+        auth_header = config.get("auth_header")
+        if auth_header:
+            headers["Authorization"] = auth_header
+
+        custom_headers = config.get("custom_headers")
+        if isinstance(custom_headers, dict):
+            headers.update(custom_headers)
+
+        hmac_secret = config.get("hmac_secret")
+        if hmac_secret:
+            secret_bytes = (
+                hmac_secret.encode() if isinstance(hmac_secret, str) else hmac_secret
+            )
+            digest = hmac.new(secret_bytes, body_bytes, hashlib.sha256).hexdigest()
+            headers["X-NAT-Signature"] = f"sha256={digest}"
+
+        return headers
+
+    def _build_finding_payload(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> dict:
+        """Build the JSON payload dict for a single finding."""
+        include_context = str(config.get("include_report_context", "true")).lower() not in (
+            "false",
+            "0",
+            "no",
+        )
+
+        payload: dict = {
+            "check_id": finding.check_id,
+            "check_name": finding.check_name,
+            "severity": finding.severity,
+            "endpoint": finding.endpoint,
+            "title": finding.title,
+            "description": finding.description,
+            "evidence": finding.evidence,
+            "remediation": finding.remediation,
+            "cwe_id": finding.cwe_id,
+            "confidence": finding.confidence,
+            "exported_at": datetime.now(tz=timezone.utc).isoformat(),
+        }
+
+        if include_context:
+            payload["scan_id"] = report.scan_id
+            payload["timestamp"] = report.timestamp
+            payload["target_url"] = report.target_url
+
+        return payload
+
+    def _get_timeout(self, config: dict) -> float:
+        """Return the configured timeout, falling back to 30 seconds."""
+        timeout = config.get("timeout", 30)
+        try:
+            return float(timeout)
+        except (TypeError, ValueError):
+            return 30.0
+
+    # ------------------------------------------------------------------
+    # Single-finding export
+    # ------------------------------------------------------------------
+
+    async def export_finding(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> ExportResult:
+        webhook_url = config["webhook_url"]
+        timeout = self._get_timeout(config)
+
+        payload = self._build_finding_payload(finding, report, config)
+        body_bytes = json.dumps(payload).encode()
+        headers = self._build_headers(body_bytes, config)
+
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                resp = await client.post(
+                    webhook_url,
+                    content=body_bytes,
+                    headers=headers,
+                )
+                resp.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            error_msg = f"Webhook error {exc.response.status_code}: {exc.response.text}"
+            logger.warning("WebhookExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+        except httpx.RequestError as exc:
+            error_msg = f"Webhook network error: {exc}"
+            logger.warning("WebhookExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+
+        return ExportResult(
+            finding=finding,
+            success=True,
+            external_id=str(resp.status_code),
+            external_url=webhook_url,
+        )
+
+    # ------------------------------------------------------------------
+    # Batch export override
+    # ------------------------------------------------------------------
+
+    async def export_findings(
+        self,
+        findings: list[SecurityFinding],
+        report: SecurityReport,
+        config: dict,
+        min_severity: str = "low",
+    ) -> ExportSummary:
+        """Override to support batch_mode: send all findings in one POST."""
+        batch_mode = str(config.get("batch_mode", "false")).lower() in ("true", "1", "yes")
+
+        if not batch_mode:
+            return await super().export_findings(findings, report, config, min_severity)
+
+        # --- batch mode: filter by severity, then POST once as a JSON array ---
+        from mannf.product.exporters.base import _SEVERITY_ORDER  # noqa: PLC0415
+
+        min_order = _SEVERITY_ORDER.get(min_severity.lower(), _SEVERITY_ORDER["low"])
+
+        eligible: list[SecurityFinding] = []
+        skipped = 0
+        for f in findings:
+            f_order = _SEVERITY_ORDER.get(f.severity.lower(), _SEVERITY_ORDER["info"])
+            if f_order > min_order:
+                skipped += 1
+            else:
+                eligible.append(f)
+
+        if not eligible:
+            return ExportSummary(
+                total=len(findings),
+                succeeded=0,
+                failed=0,
+                skipped=skipped,
+                results=[],
+            )
+
+        webhook_url = config["webhook_url"]
+        timeout = self._get_timeout(config)
+
+        payloads = [self._build_finding_payload(f, report, config) for f in eligible]
+        body_bytes = json.dumps(payloads).encode()
+        headers = self._build_headers(body_bytes, config)
+
+        results: list[ExportResult] = []
+        succeeded = 0
+        failed = 0
+
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                resp = await client.post(
+                    webhook_url,
+                    content=body_bytes,
+                    headers=headers,
+                )
+                resp.raise_for_status()
+
+            for f in eligible:
+                results.append(
+                    ExportResult(
+                        finding=f,
+                        success=True,
+                        external_id=str(resp.status_code),
+                        external_url=webhook_url,
+                    )
+                )
+            succeeded = len(eligible)
+
+        except httpx.HTTPStatusError as exc:
+            error_msg = f"Webhook batch error {exc.response.status_code}: {exc.response.text}"
+            logger.warning("WebhookExporter: %s", error_msg)
+            for f in eligible:
+                results.append(ExportResult(finding=f, success=False, error=error_msg))
+            failed = len(eligible)
+
+        except httpx.RequestError as exc:
+            error_msg = f"Webhook batch network error: {exc}"
+            logger.warning("WebhookExporter: %s", error_msg)
+            for f in eligible:
+                results.append(ExportResult(finding=f, success=False, error=error_msg))
+            failed = len(eligible)
+
+        return ExportSummary(
+            total=len(findings),
+            succeeded=succeeded,
+            failed=failed,
+            skipped=skipped,
+            results=results,
+        )

mannf/product/formatters/__init__.py

@@ -0,0 +1,18 @@
+# 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.
+
+"""NAT output formatters package.
+
+Provides pluggable report formatters beyond the built-in text/json/html/junit
+formats.  Current formatters:
+
+- :mod:`allure_formatter` — Allure JSON result files (one per test case)
+- :mod:`ctrf_formatter` — Common Test Results Format (CTRF) JSON report
+"""
+
+from mannf.product.formatters.allure_formatter import write_allure_results
+from mannf.product.formatters.ctrf_formatter import build_ctrf_report
+
+__all__ = ["write_allure_results", "build_ctrf_report"]

mannf/product/formatters/allure_formatter.py

@@ -0,0 +1,161 @@
+# 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.
+
+"""Allure JSON result formatter for NAT scan output.
+
+Converts a NAT :class:`~mannf.core.testing.models.TestSuite` and its
+accompanying report dict into Allure's ``*-result.json`` file format (one
+JSON file per test case), written to a caller-specified output directory.
+
+Usage::
+
+    from mannf.product.formatters.allure_formatter import write_allure_results
+
+    write_allure_results(report, suite, output_dir="/tmp/allure-results")
+
+The produced files are compatible with ``allure generate`` and the Allure
+GitHub Actions step (``simple-elf/allure-report-action``).
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mannf.core.testing.models import TestSuite
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+_ALLURE_STATUS_MAP = {
+    True: "passed",
+    False: "failed",
+}
+
+
+def _allure_timestamp_ms() -> int:
+    """Return the current UTC time as milliseconds since epoch."""
+    return int(datetime.now(timezone.utc).timestamp() * 1000)
+
+
+def _result_to_allure(
+    result: Any,
+    suite_name: str,
+    base_url: str,
+    start_ms: int,
+) -> dict[str, Any]:
+    """Convert a single :class:`~mannf.core.testing.models.TestResult` to an
+    Allure result dict.
+
+    Parameters
+    ----------
+    result:
+        The :class:`TestResult` object from a :class:`TestSuite`.
+    suite_name:
+        Human-readable name of the containing test suite.
+    base_url:
+        Base URL of the API under test — used to build a full URL label.
+    start_ms:
+        Suite start timestamp in milliseconds since epoch (used when the
+        result does not carry its own timestamp).
+    """
+    tc_id = getattr(result, "test_case_id", None) or "unknown"
+    passed = getattr(result, "passed", True)
+    error = getattr(result, "error", None)
+    exec_ms = getattr(result, "execution_time_ms", None) or 0.0
+
+    stop_ms = start_ms + int(exec_ms)
+
+    status: str
+    if getattr(result, "error", None) and not passed:
+        status = "broken"
+    elif not passed:
+        status = "failed"
+    else:
+        status = "passed"
+
+    doc: dict[str, Any] = {
+        "uuid": str(uuid.uuid4()),
+        "historyId": tc_id,
+        "testCaseId": tc_id,
+        "fullName": f"{suite_name}.{tc_id}",
+        "name": tc_id,
+        "status": status,
+        "start": start_ms,
+        "stop": stop_ms,
+        "labels": [
+            {"name": "suite", "value": suite_name},
+            {"name": "framework", "value": "NAT"},
+            {"name": "language", "value": "Python"},
+        ],
+        "links": [],
+        "parameters": [],
+        "attachments": [],
+        "statusDetails": {},
+    }
+
+    if base_url:
+        doc["labels"].append({"name": "host", "value": base_url})
+
+    if error:
+        doc["statusDetails"] = {
+            "message": str(error),
+            "trace": str(error),
+            "known": False,
+            "muted": False,
+            "flaky": False,
+        }
+
+    return doc
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def write_allure_results(
+    report: dict[str, Any],
+    suite: "TestSuite",
+    output_dir: str,
+) -> list[str]:
+    """Write Allure ``*-result.json`` files for every test case in *suite*.
+
+    Parameters
+    ----------
+    report:
+        The NAT scan report dict (as produced by ``_run_scan``).
+    suite:
+        The :class:`~mannf.core.testing.models.TestSuite` that ran the tests.
+    output_dir:
+        Directory to write result files into.  Will be created if it does not
+        exist.
+
+    Returns
+    -------
+    list[str]
+        Absolute paths to the written result files.
+    """
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    suite_name = getattr(suite, "name", report.get("spec", "NAT Scan"))
+    base_url = report.get("base_url", report.get("endpoint", ""))
+    start_ms = _allure_timestamp_ms()
+
+    written: list[str] = []
+    for result in getattr(suite, "results", []):
+        allure_doc = _result_to_allure(result, suite_name, base_url, start_ms)
+        filename = f"{allure_doc['uuid']}-result.json"
+        dest = out / filename
+        dest.write_text(json.dumps(allure_doc, indent=2, ensure_ascii=False), encoding="utf-8")
+        written.append(str(dest))
+
+    return written