nat-engine 1__py3-none-any.whl

mannf/product/exporters/bugzilla_exporter.py

@@ -0,0 +1,200 @@
+# 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.
+
+"""Bugzilla exporter plugin — creates bugs from NAT security findings via the Bugzilla REST API."""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from mannf.product.exporters.base import ExportResult, ExporterPlugin, TestConnectionResult
+from mannf.product.security.models import SecurityFinding, SecurityReport
+
+logger = logging.getLogger(__name__)
+
+# NAT severity → Bugzilla (severity, priority) pairs
+_SEVERITY_MAP: dict[str, tuple[str, str]] = {
+    "critical": ("critical", "P1"),
+    "high": ("major", "P2"),
+    "medium": ("normal", "P3"),
+    "low": ("minor", "P4"),
+    "info": ("trivial", "P5"),
+}
+
+
+class BugzillaExporter(ExporterPlugin):
+    """Exports NAT security findings as Bugzilla bugs via the Bugzilla REST API.
+
+    Required config keys:
+        bugzilla_url:  Bugzilla instance URL, e.g. ``https://bugzilla.example.com``.
+        api_key:       Bugzilla API key.
+        product:       Bugzilla product name to file bugs against.
+        component:     Bugzilla component name.
+
+    Optional config keys:
+        version:       Product version string (default ``"unspecified"``).
+        field_mapping: ``dict[str, Any]`` of extra field overrides merged into the
+                       bug payload before posting.
+    """
+
+    name = "bugzilla"
+    display_name = "Bugzilla"
+    description = "Creates Bugzilla bugs for NAT security findings via the Bugzilla REST API."
+
+    def validate_config(self, config: dict) -> list[str]:
+        required = ("bugzilla_url", "api_key", "product", "component")
+        return [f"'{k}' is required" for k in required if not config.get(k)]
+
+    async def test_connection(self, config: dict) -> TestConnectionResult:
+        """Test connection via GET /rest/version and GET /rest/product/{product}."""
+        errors = self.validate_config(config)
+        if errors:
+            return TestConnectionResult(
+                success=False,
+                message=f"Config validation failed: {'; '.join(errors)}",
+                details={"errors": errors},
+            )
+
+        base_url = config["bugzilla_url"].rstrip("/")
+        api_key = config["api_key"]
+        product = config["product"]
+        headers = {"Content-Type": "application/json"}
+        params_base = {"api_key": api_key}
+
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                # Step 1: confirm instance is reachable and API key works
+                version_resp = await client.get(
+                    f"{base_url}/rest/version",
+                    headers=headers,
+                    params=params_base,
+                )
+                version_resp.raise_for_status()
+                version_data = version_resp.json()
+
+                # Step 2: confirm the product exists and the API key has access
+                product_resp = await client.get(
+                    f"{base_url}/rest/product/{product}",
+                    headers=headers,
+                    params=params_base,
+                )
+                product_resp.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            if status == 401:
+                msg = "Bugzilla authentication failed — check your api_key"
+            elif status == 403:
+                msg = "Bugzilla access forbidden — check api_key permissions"
+            elif status == 404:
+                url_used = str(exc.request.url)
+                if "product" in url_used:
+                    msg = f"Bugzilla product '{product}' not found — check the product name"
+                else:
+                    msg = f"Bugzilla instance not found at '{base_url}'"
+            else:
+                msg = f"Bugzilla API error {status}: {exc.response.text}"
+            return TestConnectionResult(success=False, message=msg, details={})
+        except httpx.RequestError as exc:
+            return TestConnectionResult(
+                success=False,
+                message=f"Bugzilla network error: {exc}",
+                details={},
+            )
+
+        bz_version = version_data.get("version", "unknown")
+        return TestConnectionResult(
+            success=True,
+            message=f"Connected to Bugzilla {bz_version} — product '{product}' is accessible",
+            details={"bugzilla_version": bz_version, "product": product},
+        )
+
+    def _severity_to_priority(self, severity: str) -> str:
+        """Map NAT severity to a Bugzilla priority string."""
+        _, priority = _SEVERITY_MAP.get(severity.lower(), ("normal", "P3"))
+        return priority
+
+    def _severity_to_bugzilla_severity(self, severity: str) -> str:
+        """Map NAT severity to a Bugzilla severity string."""
+        bz_severity, _ = _SEVERITY_MAP.get(severity.lower(), ("normal", "P3"))
+        return bz_severity
+
+    def _build_payload(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> dict:
+        """Construct the Bugzilla bug creation payload."""
+        product = config["product"]
+        component = config["component"]
+        version = config.get("version", "unspecified")
+        body_text = self._format_finding_body(finding, report)
+        bz_severity = self._severity_to_bugzilla_severity(finding.severity)
+        priority = self._severity_to_priority(finding.severity)
+
+        payload: dict = {
+            "product": product,
+            "component": component,
+            "version": version,
+            "summary": f"[NAT] {finding.title}",
+            "description": body_text,
+            "severity": bz_severity,
+            "priority": priority,
+            "type": "defect",
+            "keywords": ["nat-security", finding.check_id],
+        }
+
+        # Merge any caller-supplied field overrides last so they take precedence.
+        extra: dict = config.get("field_mapping") or {}
+        payload.update(extra)
+
+        return payload
+
+    async def export_finding(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> ExportResult:
+        base_url = config["bugzilla_url"].rstrip("/")
+        api_key = config["api_key"]
+        url = f"{base_url}/rest/bug"
+        headers = {"Content-Type": "application/json"}
+        payload = self._build_payload(finding, report, config)
+        # Bugzilla REST API accepts api_key as a top-level body field
+        payload["api_key"] = api_key
+
+        try:
+            async with httpx.AsyncClient(timeout=30) as client:
+                resp = await client.post(url, json=payload, headers=headers)
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            if status == 401:
+                error_msg = "Bugzilla authentication failed — check your api_key"
+            elif status == 403:
+                error_msg = "Bugzilla access forbidden — check api_key permissions"
+            else:
+                error_msg = f"Bugzilla API error {status}: {exc.response.text}"
+            logger.warning("BugzillaExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+        except httpx.RequestError as exc:
+            error_msg = f"Bugzilla network error: {exc}"
+            logger.warning("BugzillaExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+
+        bug_id: str = str(data.get("id", ""))
+        bug_url: str | None = (
+            f"{base_url}/show_bug.cgi?id={bug_id}" if bug_id else None
+        )
+        return ExportResult(
+            finding=finding,
+            success=True,
+            external_id=bug_id or None,
+            external_url=bug_url,
+        )

mannf/product/exporters/dedup.py

@@ -0,0 +1,275 @@
+# 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.
+
+"""Deduplication helpers for the auto-bug-filing pipeline.
+
+Provides:
+
+* :func:`make_failure_fingerprint` — deterministic ``sha256`` fingerprint for
+  a failure dict.  The same failure across runs always produces the same hash,
+  enabling reliable deduplication across Jira, GitHub, and webhook targets.
+* :func:`find_existing_jira_issue` — query Jira via JQL for an open issue that
+  carries the fingerprint in its labels.
+* :func:`find_existing_github_issue` — search GitHub Issues for an open issue
+  whose title / body embeds the fingerprint.
+* :func:`add_jira_comment` / :func:`add_github_comment` — append a new-occurrence
+  comment to an existing ticket rather than creating a duplicate.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Label / tag prefix embedded in every auto-filed ticket so it can be found
+# by the dedup search queries.
+FINGERPRINT_LABEL_PREFIX = "nat-fp-"
+AUTO_FILED_LABEL = "nat-auto-filed"
+
+
+# ---------------------------------------------------------------------------
+# Fingerprint generation
+# ---------------------------------------------------------------------------
+
+
+def make_failure_fingerprint(failure: Dict[str, Any]) -> str:
+    """Return a stable ``sha256`` hex-digest fingerprint for *failure*.
+
+    The fingerprint is derived from three stable, identifying attributes:
+
+    * ``page`` — normalised page path (e.g. ``/checkout``).
+    * ``error`` — the first 200 characters of the error message, lower-cased
+      and stripped of surrounding whitespace.  Trimming prevents minor
+      formatting differences from producing different fingerprints.
+    * ``selector`` — the CSS/XPath selector that failed (empty string if absent).
+
+    Parameters
+    ----------
+    failure:
+        A failure dict from ``AutonomousRunReport.unique_failures``.
+
+    Returns
+    -------
+    str
+        A 64-character lowercase hex string (``sha256``).
+    """
+    page = (failure.get("page") or failure.get("url") or "").strip()
+    error = (failure.get("error") or "").strip().lower()[:200]
+    selector = (failure.get("selector") or "").strip()
+
+    raw = f"{page}||{error}||{selector}"
+    return hashlib.sha256(raw.encode()).hexdigest()
+
+
+def fingerprint_label(fingerprint: str) -> str:
+    """Return the label/tag string used to mark a ticket with this fingerprint.
+
+    The label is truncated to 50 characters so it fits within common tracker
+    label length limits.
+    """
+    return f"{FINGERPRINT_LABEL_PREFIX}{fingerprint[:40]}"
+
+
+# ---------------------------------------------------------------------------
+# Jira deduplication
+# ---------------------------------------------------------------------------
+
+
+async def find_existing_jira_issue(
+    fingerprint: str,
+    *,
+    base_url: str,
+    project_key: str,
+    email: str,
+    api_token: str,
+) -> Optional[str]:
+    """Search Jira for an *open* issue with the given fingerprint label.
+
+    Uses the Jira Cloud REST API v3 ``/search`` endpoint with a JQL query::
+
+        project = "<project_key>" AND labels = "nat-fp-<fingerprint>"
+        AND statusCategory != Done
+
+    Parameters
+    ----------
+    fingerprint:
+        The hex fingerprint produced by :func:`make_failure_fingerprint`.
+    base_url:
+        Jira Cloud base URL, e.g. ``https://myco.atlassian.net``.
+    project_key:
+        Jira project key, e.g. ``"NAT"``.
+    email:
+        Atlassian account email for Basic auth.
+    api_token:
+        Atlassian API token for Basic auth.
+
+    Returns
+    -------
+    str | None
+        The issue key (e.g. ``"NAT-42"``) if a matching open issue exists,
+        otherwise ``None``.
+    """
+    label = fingerprint_label(fingerprint)
+    jql = (
+        f'project = "{project_key}" AND labels = "{label}" '
+        f'AND statusCategory != Done'
+    )
+    credentials = base64.b64encode(f"{email}:{api_token}".encode()).decode()
+    headers = {
+        "Authorization": f"Basic {credentials}",
+        "Accept": "application/json",
+    }
+    url = f"{base_url.rstrip('/')}/rest/api/3/search"
+
+    try:
+        async with httpx.AsyncClient(headers=headers, timeout=15) as client:
+            resp = await client.get(url, params={"jql": jql, "maxResults": 1, "fields": "key"})
+            resp.raise_for_status()
+            data = resp.json()
+            issues = data.get("issues", [])
+            if issues:
+                return issues[0]["key"]
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Jira dedup search failed (non-fatal): %s", exc)
+    return None
+
+
+async def add_jira_comment(
+    issue_key: str,
+    comment_text: str,
+    *,
+    base_url: str,
+    email: str,
+    api_token: str,
+) -> bool:
+    """Append *comment_text* to an existing Jira issue.
+
+    Returns
+    -------
+    bool
+        ``True`` on success, ``False`` on error.
+    """
+    credentials = base64.b64encode(f"{email}:{api_token}".encode()).decode()
+    headers = {
+        "Authorization": f"Basic {credentials}",
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    url = f"{base_url.rstrip('/')}/rest/api/3/issue/{issue_key}/comment"
+    # ADF plain text paragraph
+    body = {
+        "body": {
+            "type": "doc",
+            "version": 1,
+            "content": [
+                {
+                    "type": "paragraph",
+                    "content": [{"type": "text", "text": comment_text}],
+                }
+            ],
+        }
+    }
+    try:
+        async with httpx.AsyncClient(headers=headers, timeout=15) as client:
+            resp = await client.post(url, json=body)
+            resp.raise_for_status()
+            return True
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Jira add_comment failed for %s (non-fatal): %s", issue_key, exc)
+        return False
+
+
+# ---------------------------------------------------------------------------
+# GitHub deduplication
+# ---------------------------------------------------------------------------
+
+_GITHUB_API_BASE = "https://api.github.com"
+
+
+async def find_existing_github_issue(
+    fingerprint: str,
+    *,
+    token: str,
+    repo: str,
+) -> Optional[int]:
+    """Search GitHub Issues for an open issue carrying the fingerprint label.
+
+    Uses the GitHub Search API::
+
+        repo:<owner>/<repo> is:issue is:open label:nat-fp-<fingerprint>
+
+    Parameters
+    ----------
+    fingerprint:
+        The hex fingerprint produced by :func:`make_failure_fingerprint`.
+    token:
+        GitHub personal access token.
+    repo:
+        Repository in ``owner/repo`` format.
+
+    Returns
+    -------
+    int | None
+        The issue number if a matching open issue exists, otherwise ``None``.
+    """
+    label = fingerprint_label(fingerprint)
+    query = f"repo:{repo} is:issue is:open label:{label}"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    try:
+        async with httpx.AsyncClient(headers=headers, timeout=15) as client:
+            resp = await client.get(
+                f"{_GITHUB_API_BASE}/search/issues",
+                params={"q": query, "per_page": 1},
+            )
+            resp.raise_for_status()
+            items = resp.json().get("items", [])
+            if items:
+                return int(items[0]["number"])
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("GitHub dedup search failed (non-fatal): %s", exc)
+    return None
+
+
+async def add_github_comment(
+    issue_number: int,
+    comment_body: str,
+    *,
+    token: str,
+    repo: str,
+) -> bool:
+    """Append *comment_body* to an existing GitHub issue.
+
+    Returns
+    -------
+    bool
+        ``True`` on success, ``False`` on error.
+    """
+    owner, repo_name = repo.split("/", 1)
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    url = f"{_GITHUB_API_BASE}/repos/{owner}/{repo_name}/issues/{issue_number}/comments"
+    try:
+        async with httpx.AsyncClient(headers=headers, timeout=15) as client:
+            resp = await client.post(url, json={"body": comment_body})
+            resp.raise_for_status()
+            return True
+    except Exception as exc:  # noqa: BLE001
+        logger.warning(
+            "GitHub add_comment failed for issue #%d (non-fatal): %s", issue_number, exc
+        )
+        return False

mannf/product/exporters/finding_adapter.py

@@ -0,0 +1,216 @@
+# 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.
+
+"""Adapter that converts autonomous-loop failure dicts into SecurityFinding objects.
+
+The autonomous loop records failures as plain dicts with keys:
+    ``url``, ``page``, ``error``, ``task_id`` (and optionally ``selector``,
+    ``screenshot_url``, ``dom_snapshot``, ``steps``).
+
+This module bridges that format into the ``SecurityFinding`` schema so that all
+existing exporter plugins (Jira, GitHub Issues, webhook, etc.) can handle
+functional test failures without modification.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from mannf.product.security.models import SecurityFinding, SecurityReport
+
+logger = logging.getLogger(__name__)
+
+# Mapping from simple error keywords to a NAT severity level.
+_ERROR_SEVERITY_MAP: list[tuple[str, str]] = [
+    # Critical — security-adjacent or data-loss errors
+    ("security", "critical"),
+    ("exploit", "critical"),
+    ("injection", "critical"),
+    ("xss", "critical"),
+    ("sql", "critical"),
+    ("auth", "high"),
+    ("unauthori", "high"),
+    ("forbidden", "high"),
+    ("500", "high"),
+    ("crash", "high"),
+    ("exception", "high"),
+    ("timeout", "medium"),
+    ("404", "medium"),
+    ("not found", "medium"),
+    ("assertion", "medium"),
+    ("failed", "low"),
+    ("error", "low"),
+]
+
+_DEFAULT_SEVERITY = "low"
+
+
+def _infer_severity(error: str) -> str:
+    """Infer a severity level from a free-text error message."""
+    lower = error.lower()
+    for keyword, severity in _ERROR_SEVERITY_MAP:
+        if keyword in lower:
+            return severity
+    return _DEFAULT_SEVERITY
+
+
+def _build_check_id(task_id: str) -> str:
+    """Generate a stable check ID for a functional failure."""
+    prefix = task_id[:8] if task_id else "unknown"
+    return f"FUNC-{prefix.upper()}"
+
+
+class FunctionalFindingAdapter:
+    """Converts an autonomous-loop *unique_failure* dict to a :class:`SecurityFinding`.
+
+    Each failure dict produced by the autonomous loop has the following schema::
+
+        {
+            "url":           str,              # full URL where the failure occurred
+            "page":          str,              # page path key (e.g. "/checkout")
+            "error":         str,              # error message / exception text
+            "task_id":       str,              # stable task identifier
+            # optional
+            "selector":      str | None,       # CSS / XPath selector that failed
+            "screenshot_url": str | None,      # screenshot artifact URL
+            "dom_snapshot":  str | None,       # DOM snapshot text / URL
+            "steps":         list | None,      # ordered scenario step dicts
+        }
+    """
+
+    @staticmethod
+    def from_unique_failure(
+        failure: Dict[str, Any],
+        *,
+        run_id: str = "",
+        target_url: str = "",
+        severity_override: Optional[str] = None,
+    ) -> SecurityFinding:
+        """Convert a single failure dict to a :class:`SecurityFinding`.
+
+        Parameters
+        ----------
+        failure:
+            A failure dict from ``AutonomousRunReport.unique_failures``.
+        run_id:
+            Optional autonomous run ID for additional context in the body.
+        target_url:
+            Root URL of the application under test.
+        severity_override:
+            If provided, this severity is used instead of the inferred one.
+
+        Returns
+        -------
+        SecurityFinding
+            A finding object compatible with all exporter plugins.
+        """
+        url = failure.get("url", target_url or "unknown")
+        page = failure.get("page", url)
+        error = failure.get("error", "Unknown error")
+        task_id = failure.get("task_id", "")
+        selector = failure.get("selector", "")
+        screenshot_url = failure.get("screenshot_url", "")
+        dom_snapshot = failure.get("dom_snapshot", "")
+        steps: List[Dict[str, Any]] = failure.get("steps") or []
+
+        severity = severity_override or _infer_severity(error)
+        check_id = _build_check_id(task_id)
+
+        # Build a human-readable description
+        description_parts = [
+            f"Functional test failure detected on page **{page}**.",
+            "",
+            f"**Error:** {error}",
+        ]
+        if selector:
+            description_parts.append(f"**Selector:** `{selector}`")
+        if url:
+            description_parts.append(f"**URL:** {url}")
+        description = "\n".join(description_parts)
+
+        # Build evidence block
+        evidence_parts = [f"Task ID: `{task_id}`" if task_id else ""]
+        if run_id:
+            evidence_parts.append(f"Run ID: `{run_id}`")
+        if screenshot_url:
+            evidence_parts.append(f"Screenshot: {screenshot_url}")
+        if dom_snapshot:
+            snapshot_preview = dom_snapshot[:500] + "…" if len(dom_snapshot) > 500 else dom_snapshot
+            evidence_parts.append(f"DOM Snapshot:\n```\n{snapshot_preview}\n```")
+        if steps:
+            steps_text = "\n".join(
+                f"{i + 1}. {s.get('action', s.get('type', '?'))}: {s.get('selector', s.get('value', ''))}"
+                for i, s in enumerate(steps[:10])
+            )
+            evidence_parts.append(f"Reproduction steps:\n{steps_text}")
+        evidence = "\n".join(p for p in evidence_parts if p)
+
+        return SecurityFinding(
+            check_id=check_id,
+            check_name="Autonomous Functional Test Failure",
+            severity=severity,
+            endpoint=page,
+            title=f"Functional failure on {page}: {error[:80]}",
+            description=description,
+            evidence=evidence or "No additional evidence available.",
+            remediation=(
+                "Review the reproduction steps and error message. "
+                "Investigate the affected page for broken interactions or regressions."
+            ),
+            cwe_id="",
+            confidence=0.85,
+        )
+
+    @classmethod
+    def from_unique_failures(
+        cls,
+        failures: List[Dict[str, Any]],
+        *,
+        run_id: str = "",
+        target_url: str = "",
+        severity_override: Optional[str] = None,
+    ) -> List[SecurityFinding]:
+        """Convert a list of failure dicts to a list of :class:`SecurityFinding` objects."""
+        findings: List[SecurityFinding] = []
+        for failure in failures:
+            try:
+                findings.append(
+                    cls.from_unique_failure(
+                        failure,
+                        run_id=run_id,
+                        target_url=target_url,
+                        severity_override=severity_override,
+                    )
+                )
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("FunctionalFindingAdapter: failed to convert failure dict: %s", exc)
+        return findings
+
+    @staticmethod
+    def make_report(
+        run_id: str,
+        target_url: str,
+        total_failures: int,
+    ) -> SecurityReport:
+        """Create a minimal :class:`SecurityReport` to satisfy exporter signatures.
+
+        Parameters
+        ----------
+        run_id:
+            The autonomous run ID.
+        target_url:
+            Root URL of the application under test.
+        total_failures:
+            Total number of failures in the run (used as ``total_endpoints_scanned``).
+        """
+        from datetime import datetime, timezone  # noqa: PLC0415
+
+        return SecurityReport(
+            scan_id=run_id,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            target_url=target_url,
+            total_endpoints_scanned=total_failures,
+        )