nat-engine 1__py3-none-any.whl

mannf/product/exporters/azuredevops_exporter.py

@@ -0,0 +1,257 @@
+# 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.
+
+"""Azure DevOps Work Items exporter plugin — creates Azure Boards work items from NAT findings.
+
+Usage
+-----
+Export findings to Azure Boards by supplying the following config keys via
+``--export-config`` on the CLI::
+
+    nat security-scan --spec api.yaml --base-url http://localhost \\
+      --export azure-devops \\
+      --export-config organization=myorg \\
+      --export-config project=MyProject \\
+      --export-config pat=$AZURE_DEVOPS_PAT
+
+Obtaining an Azure DevOps Personal Access Token
+------------------------------------------------
+1. Sign in to ``https://dev.azure.com/{organization}``.
+2. Go to *User Settings → Personal Access Tokens*.
+3. Create a token with the **Work Items (Read & Write)** scope.
+4. Copy the token value — it is shown only once.
+
+Required config keys
+--------------------
+organization:  Azure DevOps organization name (the ``{organization}`` segment
+               in ``https://dev.azure.com/{organization}``).
+project:       Azure DevOps project name.
+pat:           Personal Access Token with Work Items (Read & Write) scope.
+
+Optional config keys
+--------------------
+work_item_type: Work item type to create (default ``"Bug"``).
+area_path:      Area path for the work item.
+iteration_path: Iteration path for the work item.
+assignee:       E-mail or display name of the assignee.
+"""
+
+from __future__ import annotations
+
+import base64
+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__)
+
+_TITLE_MAX_LENGTH = 255
+
+# ADO severity label format
+_ADO_SEVERITY_MAP: dict[str, str] = {
+    "critical": "1 - Critical",
+    "high": "2 - High",
+    "medium": "3 - Medium",
+    "low": "4 - Low",
+    "info": "4 - Low",
+}
+
+# ADO priority integers (as strings to satisfy base class signature)
+_ADO_PRIORITY_MAP: dict[str, str] = {
+    "critical": "1",
+    "high": "1",
+    "medium": "2",
+    "low": "3",
+    "info": "4",
+}
+
+
+class AzureDevOpsExporter(ExporterPlugin):
+    """Exports NAT security findings as Azure DevOps work items via the Azure Boards REST API.
+
+    Required config keys:
+        organization: Azure DevOps organization name.
+        project:      Azure DevOps project name.
+        pat:          Personal Access Token with Work Items (Read & Write) scope.
+
+    Optional config keys:
+        work_item_type: Work item type (default ``"Bug"``).
+        area_path:      Area path for the work item.
+        iteration_path: Iteration path for the work item.
+        assignee:       E-mail or display name of the assignee.
+
+    Example CLI usage::
+
+        nat security-scan --spec api.yaml --base-url http://localhost \\
+          --export azure-devops \\
+          --export-config organization=myorg \\
+          --export-config project=MyProject \\
+          --export-config pat=$AZURE_DEVOPS_PAT
+    """
+
+    name = "azure-devops"
+    display_name = "Azure DevOps Work Items"
+    description = "Export NAT findings as Azure DevOps work items via the Azure Boards REST API."
+
+    def validate_config(self, config: dict) -> list[str]:
+        errors: list[str] = []
+        if not config.get("organization"):
+            errors.append("'organization' is required")
+        if not config.get("project"):
+            errors.append("'project' is required")
+        if not config.get("pat"):
+            errors.append("'pat' is required")
+        return errors
+
+    async def test_connection(self, config: dict) -> TestConnectionResult:
+        """Test connection via work item types list — confirms PAT + org + project."""
+        errors = self.validate_config(config)
+        if errors:
+            return TestConnectionResult(
+                success=False,
+                message=f"Config validation failed: {'; '.join(errors)}",
+                details={"errors": errors},
+            )
+
+        organization = config["organization"]
+        project = config["project"]
+        pat = config["pat"]
+        url = (
+            f"https://dev.azure.com/{organization}/{project}"
+            "/_apis/wit/workitemtypes?api-version=7.1"
+        )
+        headers = {
+            "Authorization": self._build_auth_header(pat),
+            "Accept": "application/json",
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                resp = await client.get(url, headers=headers)
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            if status == 401:
+                msg = "Azure DevOps authentication failed — check your PAT"
+            elif status == 404:
+                msg = f"Azure DevOps project '{project}' not found in org '{organization}'"
+            else:
+                msg = f"Azure DevOps API error {status}: {exc.response.text}"
+            return TestConnectionResult(success=False, message=msg, details={})
+        except httpx.RequestError as exc:
+            return TestConnectionResult(
+                success=False,
+                message=f"Azure DevOps network error: {exc}",
+                details={},
+            )
+
+        count = data.get("count", 0)
+        return TestConnectionResult(
+            success=True,
+            message=f"Connected to Azure DevOps — project '{project}' found ({count} work item types)",
+            details={"organization": organization, "project": project, "workItemTypeCount": count},
+        )
+
+    def _severity_to_priority(self, severity: str) -> str:
+        """Return ADO priority integer (as a string) for the given NAT severity."""
+        return _ADO_PRIORITY_MAP.get(severity.lower(), "3")
+
+    def _build_auth_header(self, pat: str) -> str:
+        """Build a Basic auth header value from an Azure DevOps PAT.
+
+        Azure DevOps Basic auth uses an empty username and the PAT as the
+        password, base64-encoded as ``:<PAT>``.
+        """
+        encoded = base64.b64encode(f":{pat}".encode()).decode()
+        return f"Basic {encoded}"
+
+    def _build_patch_document(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> list[dict]:
+        """Build the JSON Patch operations array for the Azure Boards API."""
+        severity = finding.severity.lower()
+        ado_severity = _ADO_SEVERITY_MAP.get(severity, "4 - Low")
+        ado_priority = int(self._severity_to_priority(severity))
+
+        cwe_part = finding.cwe_id if finding.cwe_id else "unknown"
+        owasp_part = finding.check_id
+        tags = f"nat-security; owasp:{owasp_part}; severity:{severity}; cwe:{cwe_part}"
+
+        raw_title = f"[NAT] {finding.title}"
+        title = raw_title[:_TITLE_MAX_LENGTH]
+
+        body_md = self._format_finding_body(finding, report)
+        description_html = f"<div>{body_md}</div>"
+
+        ops = [
+            {"op": "add", "path": "/fields/System.Title", "value": title},
+            {"op": "add", "path": "/fields/System.Description", "value": description_html},
+            {"op": "add", "path": "/fields/Microsoft.VSTS.Common.Priority", "value": ado_priority},
+            {"op": "add", "path": "/fields/Microsoft.VSTS.Common.Severity", "value": ado_severity},
+            {"op": "add", "path": "/fields/System.Tags", "value": tags},
+        ]
+
+        if config.get("area_path"):
+            ops.append({"op": "add", "path": "/fields/System.AreaPath", "value": config["area_path"]})
+        if config.get("iteration_path"):
+            ops.append({"op": "add", "path": "/fields/System.IterationPath", "value": config["iteration_path"]})
+        if config.get("assignee"):
+            ops.append({"op": "add", "path": "/fields/System.AssignedTo", "value": config["assignee"]})
+
+        return ops
+
+    async def export_finding(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> ExportResult:
+        organization = config["organization"]
+        project = config["project"]
+        pat = config["pat"]
+        work_item_type = config.get("work_item_type", "Bug")
+
+        url = (
+            f"https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/"
+            f"${work_item_type}?api-version=7.1"
+        )
+
+        headers = {
+            "Content-Type": "application/json-patch+json",
+            "Authorization": self._build_auth_header(pat),
+        }
+
+        patch_document = self._build_patch_document(finding, report, config)
+
+        try:
+            async with httpx.AsyncClient(timeout=30) as client:
+                resp = await client.post(url, json=patch_document, headers=headers)
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.HTTPStatusError as exc:
+            error_msg = f"Azure DevOps API error {exc.response.status_code}: {exc.response.text}"
+            logger.warning("AzureDevOpsExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+        except httpx.RequestError as exc:
+            error_msg = f"Azure DevOps network error: {exc}"
+            logger.warning("AzureDevOpsExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+
+        external_id = str(data.get("id", ""))
+        external_url = data.get("_links", {}).get("html", {}).get("href")
+
+        return ExportResult(
+            finding=finding,
+            success=True,
+            external_id=external_id,
+            external_url=external_url,
+        )

mannf/product/exporters/base.py

@@ -0,0 +1,307 @@
+# 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.
+
+"""Abstract base for exporter plugins that push NAT findings to external trackers."""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+from mannf.product.security.models import SecurityFinding, SecurityReport
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TestConnectionResult:
+    """Result of a lightweight connection test against an external service."""
+
+    success: bool
+    message: str  # e.g., "Connected to Jira — project SEC found"
+    details: dict = field(default_factory=dict)
+
+_SEVERITY_ORDER: dict[str, int] = {
+    "critical": 0,
+    "high": 1,
+    "medium": 2,
+    "low": 3,
+    "info": 4,
+}
+
+
+@dataclass
+class ExportResult:
+    """Result of exporting a single finding."""
+
+    finding: SecurityFinding
+    success: bool
+    external_id: str | None = None  # e.g., Jira issue key "NAT-123"
+    external_url: str | None = None  # link to the created issue
+    error: str | None = None
+
+
+@dataclass
+class ExportSummary:
+    """Summary of a batch export operation."""
+
+    total: int
+    succeeded: int
+    failed: int
+    skipped: int
+    results: list[ExportResult] = field(default_factory=list)
+
+
+class ExporterPlugin(ABC):
+    """Abstract base class for defect tracker exporter plugins.
+
+    Subclasses must define the class-level attributes ``name``,
+    ``display_name``, and ``description``, and implement the abstract
+    methods ``export_finding`` and ``validate_config``.
+
+    Example::
+
+        class MyExporter(ExporterPlugin):
+            name = "my-tracker"
+            display_name = "My Tracker"
+            description = "Export findings to My Tracker."
+
+            async def export_finding(self, finding, report, config):
+                ...
+
+            def validate_config(self, config):
+                errors = []
+                if not config.get("api_key"):
+                    errors.append("api_key is required")
+                return errors
+    """
+
+    name: str           # e.g., "jira", "linear", "github-issues"
+    display_name: str   # e.g., "Jira Cloud", "Linear", "GitHub Issues"
+    description: str    # one-line description
+
+    @abstractmethod
+    async def export_finding(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> ExportResult:
+        """Export a single finding to the external tracker.
+
+        Parameters
+        ----------
+        finding:
+            The security finding to export.
+        report:
+            The parent scan report that provides scan-level context.
+        config:
+            Exporter-specific configuration dict (keys validated by
+            :meth:`validate_config`).
+
+        Returns
+        -------
+        ExportResult
+            The result of the export attempt.
+        """
+        ...
+
+    async def export_findings(
+        self,
+        findings: list[SecurityFinding],
+        report: SecurityReport,
+        config: dict,
+        min_severity: str = "low",
+    ) -> ExportSummary:
+        """Export multiple findings, filtering by minimum severity.
+
+        The default implementation calls :meth:`export_finding` in a loop.
+        Export failures are caught and recorded in the summary rather than
+        propagated, so a single failing export never aborts the batch.
+
+        Parameters
+        ----------
+        findings:
+            All findings from the scan.
+        report:
+            The parent scan report.
+        config:
+            Exporter-specific configuration dict.
+        min_severity:
+            Minimum severity level to export (``"critical"``, ``"high"``,
+            ``"medium"``, ``"low"``, or ``"info"``).  Findings below this
+            threshold are counted as *skipped*.
+
+        Returns
+        -------
+        ExportSummary
+            Aggregated results for every finding processed.
+        """
+        min_order = _SEVERITY_ORDER.get(min_severity.lower(), _SEVERITY_ORDER["low"])
+
+        results: list[ExportResult] = []
+        succeeded = 0
+        failed = 0
+        skipped = 0
+
+        for finding in findings:
+            finding_order = _SEVERITY_ORDER.get(finding.severity.lower(), _SEVERITY_ORDER["info"])
+            if finding_order > min_order:
+                skipped += 1
+                continue
+
+            try:
+                result = await self.export_finding(finding, report, config)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning(
+                    "Exporter '%s' raised an unexpected error for finding '%s': %s",
+                    self.name,
+                    finding.check_id,
+                    exc,
+                )
+                result = ExportResult(finding=finding, success=False, error=str(exc))
+
+            results.append(result)
+            if result.success:
+                succeeded += 1
+            else:
+                failed += 1
+
+        return ExportSummary(
+            total=len(findings),
+            succeeded=succeeded,
+            failed=failed,
+            skipped=skipped,
+            results=results,
+        )
+
+    @abstractmethod
+    def validate_config(self, config: dict) -> list[str]:
+        """Validate exporter-specific config.
+
+        Parameters
+        ----------
+        config:
+            Configuration dict to validate.
+
+        Returns
+        -------
+        list[str]
+            A list of human-readable error strings.  An empty list means the
+            config is valid.
+        """
+        ...
+
+    async def test_connection(self, config: dict) -> TestConnectionResult:
+        """Test connectivity to the external service using the given config.
+
+        The default implementation validates the config and returns success if
+        there are no validation errors.  Concrete subclasses should override
+        this with a lightweight, read-only API call that verifies credentials
+        and target availability live.
+
+        Parameters
+        ----------
+        config:
+            Exporter-specific configuration dict.
+
+        Returns
+        -------
+        TestConnectionResult
+            Result indicating whether the connection was successful.
+        """
+        errors = self.validate_config(config)
+        if errors:
+            return TestConnectionResult(
+                success=False,
+                message=f"Config validation failed: {'; '.join(errors)}",
+                details={"errors": errors},
+            )
+        return TestConnectionResult(
+            success=True,
+            message=f"Config for '{self.name}' is valid (no live connection test performed).",
+            details={},
+        )
+
+    def _severity_to_priority(self, severity: str) -> str:
+        """Map a NAT severity to a generic priority label.
+
+        Concrete exporters may override this to return tracker-specific
+        priority values (e.g., ``"P1"`` for Jira, ``"urgent"`` for Linear).
+
+        Parameters
+        ----------
+        severity:
+            NAT severity string (``"critical"``, ``"high"``, ``"medium"``,
+            ``"low"``, or ``"info"``).
+
+        Returns
+        -------
+        str
+            A generic priority label.
+        """
+        mapping = {
+            "critical": "critical",
+            "high": "high",
+            "medium": "medium",
+            "low": "low",
+            "info": "info",
+        }
+        return mapping.get(severity.lower(), "low")
+
+    def _format_finding_body(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+    ) -> str:
+        """Generate a Markdown-formatted description body for a finding.
+
+        Parameters
+        ----------
+        finding:
+            The security finding to format.
+        report:
+            The parent scan report for additional context.
+
+        Returns
+        -------
+        str
+            A Markdown string suitable for use as an issue body.
+        """
+        lines = [
+            f"## {finding.title}",
+            "",
+            finding.description,
+            "",
+            "### Details",
+            "",
+            f"- **Endpoint:** `{finding.endpoint}`",
+            f"- **Severity:** {finding.severity}",
+            f"- **Confidence:** {finding.confidence:.0%}",
+        ]
+        if finding.cwe_id:
+            lines.append(f"- **CWE:** [{finding.cwe_id}](https://cwe.mitre.org/data/definitions/{finding.cwe_id.replace('CWE-', '')}.html)")
+        lines += [
+            "",
+            "### Evidence",
+            "",
+            finding.evidence,
+            "",
+            "### Remediation",
+            "",
+            finding.remediation,
+            "",
+            "### Scan Context",
+            "",
+            f"- **Scan ID:** `{report.scan_id}`",
+            f"- **Target URL:** {report.target_url}",
+            f"- **Timestamp:** {report.timestamp}",
+            f"- **Total Endpoints Scanned:** {report.total_endpoints_scanned}",
+            "",
+            "---",
+            "*Generated by [NAT (Neural Agent Testing Framework)](https://nat-testing.io)*",
+        ]
+        return "\n".join(lines)