nat-engine 1__py3-none-any.whl

mannf/product/exporters/github_exporter.py

@@ -0,0 +1,197 @@
+# 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.
+
+"""GitHub Issues exporter plugin — creates GitHub Issues from NAT security findings."""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from mannf.product.exporters.base import ExportResult, ExporterPlugin, TestConnectionResult
+from mannf.product.exporters.dedup import AUTO_FILED_LABEL
+from mannf.product.security.models import SecurityFinding, SecurityReport
+
+logger = logging.getLogger(__name__)
+
+_GITHUB_API_BASE = "https://api.github.com"
+
+
+class GitHubIssuesExporter(ExporterPlugin):
+    """Exports NAT security findings as GitHub Issues via the REST API.
+
+    Required config keys:
+        token: GitHub personal access token or ``$GITHUB_TOKEN``.
+        repo:  Repository in ``owner/repo`` format, e.g. ``"myorg/myrepo"``.
+
+    Optional config keys:
+        labels:      Extra label names to add to every created issue.
+        assignees:   GitHub usernames to assign to every created issue.
+        deduplicate: If ``true`` (bool), search for an existing open issue
+                     with the same ``[NAT]`` title before creating a new one.
+                     Defaults to ``false``.
+    """
+
+    name = "github-issues"
+    display_name = "GitHub Issues"
+    description = "Creates GitHub Issues for NAT security findings via the REST API."
+
+    def validate_config(self, config: dict) -> list[str]:
+        errors: list[str] = []
+        if not config.get("token"):
+            errors.append("'token' is required")
+        repo = config.get("repo", "")
+        if not repo:
+            errors.append("'repo' is required")
+        elif "/" not in repo or len(repo.split("/")) != 2 or not all(repo.split("/")):
+            errors.append("'repo' must be in 'owner/repo' format")
+        return errors
+
+    async def test_connection(self, config: dict) -> TestConnectionResult:
+        """Test connection by fetching the repository metadata via GET /repos/{owner}/{repo}."""
+        errors = self.validate_config(config)
+        if errors:
+            return TestConnectionResult(
+                success=False,
+                message=f"Config validation failed: {'; '.join(errors)}",
+                details={"errors": errors},
+            )
+
+        token = config["token"]
+        owner, repo_name = config["repo"].split("/", 1)
+        url = f"{_GITHUB_API_BASE}/repos/{owner}/{repo_name}"
+
+        try:
+            async with httpx.AsyncClient(headers=self._build_headers(token), timeout=10) as client:
+                resp = await client.get(url)
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            if status == 401:
+                msg = "GitHub authentication failed — check your token"
+            elif status == 404:
+                msg = f"GitHub repo '{config['repo']}' not found or not accessible"
+            else:
+                msg = f"GitHub API error {status}: {exc.response.text}"
+            return TestConnectionResult(success=False, message=msg, details={})
+        except httpx.RequestError as exc:
+            return TestConnectionResult(
+                success=False,
+                message=f"GitHub network error: {exc}",
+                details={},
+            )
+
+        return TestConnectionResult(
+            success=True,
+            message=f"Connected to GitHub — repo '{data.get('full_name', config['repo'])}' found",
+            details={"repo": data.get("full_name"), "private": data.get("private")},
+        )
+
+    def _build_headers(self, token: str) -> dict:
+        return {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+
+    async def _find_existing_issue(
+        self,
+        client: httpx.AsyncClient,
+        owner: str,
+        repo: str,
+        title: str,
+    ) -> str | None:
+        """Search for an open issue with *title*; return its HTML URL or None."""
+        search_url = f"{_GITHUB_API_BASE}/search/issues"
+        query = f'repo:{owner}/{repo} is:issue is:open in:title "{title}"'
+        try:
+            resp = await client.get(search_url, params={"q": query, "per_page": 1})
+            resp.raise_for_status()
+            items = resp.json().get("items", [])
+            if items:
+                return items[0].get("html_url")
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("GitHubIssuesExporter: deduplication search failed: %s", exc)
+        return None
+
+    async def export_finding(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> ExportResult:
+        token = config["token"]
+        owner, repo_name = config["repo"].split("/", 1)
+        extra_labels: list[str] = config.get("labels") or []
+        assignees: list[str] = config.get("assignees") or []
+        deduplicate: bool = bool(config.get("deduplicate", False))
+        milestone: int | None = config.get("milestone")  # GitHub milestone number
+
+        title = f"[NAT] {finding.title}"
+        body = self._format_finding_body(finding, report)
+
+        # Functional findings (auto-filed from autonomous loop) use a distinct
+        # label set; security findings keep "nat-security".
+        is_functional = finding.check_id.startswith("FUNC-")
+        if is_functional:
+            base_labels = [AUTO_FILED_LABEL, finding.severity]
+        else:
+            base_labels = ["nat-security", finding.severity, finding.check_id]
+        labels = base_labels + extra_labels
+
+        headers = self._build_headers(token)
+
+        try:
+            async with httpx.AsyncClient(headers=headers, timeout=30) as client:
+                if deduplicate:
+                    existing_url = await self._find_existing_issue(
+                        client, owner, repo_name, title
+                    )
+                    if existing_url:
+                        logger.info(
+                            "GitHubIssuesExporter: skipping duplicate — existing issue: %s",
+                            existing_url,
+                        )
+                        issue_number = existing_url.rstrip("/").split("/")[-1]
+                        return ExportResult(
+                            finding=finding,
+                            success=True,
+                            external_id=issue_number,
+                            external_url=existing_url,
+                        )
+
+                payload: dict = {
+                    "title": title,
+                    "body": body,
+                    "labels": labels,
+                }
+                if assignees:
+                    payload["assignees"] = assignees
+                if milestone is not None:
+                    payload["milestone"] = milestone
+
+                resp = await client.post(
+                    f"{_GITHUB_API_BASE}/repos/{owner}/{repo_name}/issues",
+                    json=payload,
+                )
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.HTTPStatusError as exc:
+            error_msg = f"GitHub API error {exc.response.status_code}: {exc.response.text}"
+            logger.warning("GitHubIssuesExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+        except httpx.RequestError as exc:
+            error_msg = f"GitHub network error: {exc}"
+            logger.warning("GitHubIssuesExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+
+        return ExportResult(
+            finding=finding,
+            success=True,
+            external_id=str(data.get("number", "")),
+            external_url=data.get("html_url"),
+        )

mannf/product/exporters/gitlab_exporter.py

@@ -0,0 +1,215 @@
+# 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.
+
+"""GitLab Issues exporter plugin — creates GitLab issues from NAT security findings.
+
+Usage
+-----
+Export findings to a GitLab project by supplying the following config keys via
+``--export-config`` on the CLI::
+
+    nat security-scan --spec api.yaml --base-url http://localhost \\
+      --export gitlab \\
+      --export-config gitlab_url=https://gitlab.com \\
+      --export-config project_id=12345 \\
+      --export-config private_token=$GITLAB_TOKEN
+
+Obtaining a GitLab Personal Access Token
+-----------------------------------------
+1. Sign in to your GitLab instance.
+2. Go to *User Settings → Access Tokens* (or *Profile → Preferences → Access Tokens*).
+3. Create a token with the ``api`` scope.
+4. Copy the token value — it is shown only once.
+
+Required config keys
+--------------------
+gitlab_url:    GitLab instance base URL, e.g. ``https://gitlab.com`` or a
+               self-hosted URL such as ``https://gitlab.mycompany.com``.
+project_id:    Numeric GitLab project ID or ``namespace/project`` path slug,
+               e.g. ``12345`` or ``mygroup/myproject``.
+private_token: GitLab Personal Access Token with ``api`` scope.
+
+Optional config keys
+--------------------
+labels:        List of additional label strings to attach to every issue.
+assignee_ids:  List of GitLab user IDs (integers) to assign.
+confidential:  Whether issues should be confidential (default ``False``).
+min_severity:  Minimum severity to export (default ``"low"``).
+"""
+
+from __future__ import annotations
+
+import logging
+from urllib.parse import quote_plus
+
+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
+
+
+def _owasp_label(check_id: str) -> str:
+    """Convert a check_id such as ``'OWASP-API1'`` to ``'owasp:API1'``."""
+    if check_id.upper().startswith("OWASP-"):
+        return "owasp:" + check_id[len("OWASP-"):]
+    return check_id
+
+
+class GitLabExporter(ExporterPlugin):
+    """Exports NAT security findings as GitLab Issues via the GitLab REST API.
+
+    Required config keys:
+        gitlab_url:    GitLab instance base URL (e.g. ``https://gitlab.com``).
+        project_id:    Numeric project ID or ``namespace/project`` slug.
+        private_token: Personal Access Token with ``api`` scope.
+
+    Optional config keys:
+        labels:       List of extra label strings for every created issue.
+        assignee_ids: List of GitLab user IDs to assign.
+        confidential: Create issues as confidential (default ``False``).
+        min_severity: Minimum severity threshold (default ``"low"``).
+
+    Example CLI usage::
+
+        nat security-scan --spec api.yaml --base-url http://localhost \\
+          --export gitlab \\
+          --export-config gitlab_url=https://gitlab.com \\
+          --export-config project_id=12345 \\
+          --export-config private_token=$GITLAB_TOKEN
+    """
+
+    name = "gitlab"
+    display_name = "GitLab Issues"
+    description = "Export NAT findings as GitLab issues via the GitLab REST API."
+
+    def validate_config(self, config: dict) -> list[str]:
+        errors: list[str] = []
+        if not config.get("gitlab_url"):
+            errors.append("'gitlab_url' is required")
+        if not config.get("project_id"):
+            errors.append("'project_id' is required")
+        if not config.get("private_token"):
+            errors.append("'private_token' is required")
+        return errors
+
+    async def test_connection(self, config: dict) -> TestConnectionResult:
+        """Test connection via GET /api/v4/projects/{project_id} — confirms token + project."""
+        errors = self.validate_config(config)
+        if errors:
+            return TestConnectionResult(
+                success=False,
+                message=f"Config validation failed: {'; '.join(errors)}",
+                details={"errors": errors},
+            )
+
+        gitlab_url = config["gitlab_url"].rstrip("/")
+        project_id = config["project_id"]
+        private_token = config["private_token"]
+        url = f"{gitlab_url}/api/v4/projects/{self._project_path(project_id)}"
+
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                resp = await client.get(url, headers={"PRIVATE-TOKEN": private_token})
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            if status == 401:
+                msg = "GitLab authentication failed — check your private_token"
+            elif status == 404:
+                msg = f"GitLab project '{project_id}' not found or not accessible"
+            else:
+                msg = f"GitLab API error {status}: {exc.response.text}"
+            return TestConnectionResult(success=False, message=msg, details={})
+        except httpx.RequestError as exc:
+            return TestConnectionResult(
+                success=False,
+                message=f"GitLab network error: {exc}",
+                details={},
+            )
+
+        return TestConnectionResult(
+            success=True,
+            message=f"Connected to GitLab — project '{data.get('path_with_namespace', project_id)}' found",
+            details={"project": data.get("path_with_namespace"), "id": data.get("id")},
+        )
+
+    def _severity_to_priority(self, severity: str) -> str:
+        mapping = {
+            "critical": "priority::critical",
+            "high": "priority::high",
+            "medium": "priority::medium",
+            "low": "priority::low",
+            "info": "priority::info",
+        }
+        return mapping.get(severity.lower(), "priority::low")
+
+    def _build_labels(self, finding: SecurityFinding, extra_labels: list[str]) -> str:
+        """Return a comma-separated label string for the GitLab issue."""
+        labels = [
+            "nat-security",
+            f"severity:{finding.severity}",
+            _owasp_label(finding.check_id),
+        ]
+        labels.extend(extra_labels)
+        return ",".join(labels)
+
+    def _project_path(self, project_id: str | int) -> str:
+        """URL-encode the project_id for use in a GitLab API path segment."""
+        return quote_plus(str(project_id))
+
+    async def export_finding(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> ExportResult:
+        gitlab_url = config["gitlab_url"].rstrip("/")
+        project_id = config["project_id"]
+        private_token = config["private_token"]
+        extra_labels: list[str] = config.get("labels") or []
+        assignee_ids: list[int] = config.get("assignee_ids") or []
+        confidential: bool = bool(config.get("confidential", False))
+
+        raw_title = f"[NAT] {finding.title}"
+        title = raw_title[:_TITLE_MAX_LENGTH]
+        description = self._format_finding_body(finding, report)
+        labels_str = self._build_labels(finding, extra_labels)
+
+        url = f"{gitlab_url}/api/v4/projects/{self._project_path(project_id)}/issues"
+        headers = {"PRIVATE-TOKEN": private_token}
+        payload: dict = {
+            "title": title,
+            "description": description,
+            "labels": labels_str,
+            "confidential": confidential,
+        }
+        if assignee_ids:
+            payload["assignee_ids"] = assignee_ids
+
+        try:
+            async with httpx.AsyncClient(headers=headers, timeout=30) as client:
+                resp = await client.post(url, json=payload)
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.HTTPStatusError as exc:
+            error_msg = f"GitLab API error {exc.response.status_code}: {exc.response.text}"
+            logger.warning("GitLabExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+        except httpx.RequestError as exc:
+            error_msg = f"GitLab network error: {exc}"
+            logger.warning("GitLabExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+
+        return ExportResult(
+            finding=finding,
+            success=True,
+            external_id=str(data.get("iid", "")),
+            external_url=data.get("web_url"),
+        )

mannf/product/exporters/jira_exporter.py

@@ -0,0 +1,180 @@
+# 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.
+
+"""Jira Cloud exporter plugin — creates Jira issues from NAT security findings."""
+
+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__)
+
+_SEVERITY_TO_JIRA_PRIORITY: dict[str, str] = {
+    "critical": "Highest",
+    "high": "High",
+    "medium": "Medium",
+    "low": "Low",
+    "info": "Lowest",
+}
+
+
+class JiraExporter(ExporterPlugin):
+    """Exports NAT security findings as Jira Cloud issues via the REST API v3.
+
+    Required config keys:
+        base_url:    Jira Cloud base URL, e.g. ``https://myco.atlassian.net``.
+        project_key: Jira project key, e.g. ``"NAT"``.
+        email:       Atlassian account email used for Basic auth.
+        api_token:   Atlassian API token used for Basic auth.
+
+    Optional config keys:
+        issue_type:  Jira issue type name (default ``"Bug"``).
+        component:   Jira component name to assign to new issues.
+    """
+
+    name = "jira"
+    display_name = "Jira Cloud"
+    description = "Creates Jira Cloud issues for NAT security findings via the REST API v3."
+
+    def validate_config(self, config: dict) -> list[str]:
+        required = ("base_url", "project_key", "email", "api_token")
+        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/api/3/myself — confirms email + api_token + base_url."""
+        errors = self.validate_config(config)
+        if errors:
+            return TestConnectionResult(
+                success=False,
+                message=f"Config validation failed: {'; '.join(errors)}",
+                details={"errors": errors},
+            )
+
+        base_url = config["base_url"].rstrip("/")
+        email = config["email"]
+        api_token = config["api_token"]
+        credentials = base64.b64encode(f"{email}:{api_token}".encode()).decode()
+        headers = {
+            "Authorization": f"Basic {credentials}",
+            "Accept": "application/json",
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                resp = await client.get(
+                    f"{base_url}/rest/api/3/myself",
+                    headers=headers,
+                )
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            if status == 401:
+                msg = "Jira authentication failed — check your email and api_token"
+            elif status == 403:
+                msg = "Jira access forbidden — check account permissions"
+            elif status == 404:
+                msg = f"Jira instance not found at '{base_url}'"
+            else:
+                msg = f"Jira API error {status}: {exc.response.text}"
+            return TestConnectionResult(success=False, message=msg, details={})
+        except httpx.RequestError as exc:
+            return TestConnectionResult(
+                success=False,
+                message=f"Jira network error: {exc}",
+                details={},
+            )
+
+        display_name = data.get("displayName", email)
+        return TestConnectionResult(
+            success=True,
+            message=f"Connected to Jira — authenticated as '{display_name}'",
+            details={"displayName": display_name, "accountId": data.get("accountId")},
+        )
+
+    def _severity_to_priority(self, severity: str) -> str:
+        return _SEVERITY_TO_JIRA_PRIORITY.get(severity.lower(), "Low")
+
+    def _build_adf_body(self, markdown_text: str) -> dict:
+        """Wrap plain text in an Atlassian Document Format (ADF) paragraph node."""
+        return {
+            "type": "doc",
+            "version": 1,
+            "content": [
+                {
+                    "type": "paragraph",
+                    "content": [{"type": "text", "text": markdown_text}],
+                }
+            ],
+        }
+
+    async def export_finding(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> ExportResult:
+        base_url = config["base_url"].rstrip("/")
+        project_key = config["project_key"]
+        email = config["email"]
+        api_token = config["api_token"]
+        issue_type = config.get("issue_type", "Bug")
+        component = config.get("component")
+
+        priority_name = self._severity_to_priority(finding.severity)
+        body_text = self._format_finding_body(finding, report)
+
+        credentials = base64.b64encode(f"{email}:{api_token}".encode()).decode()
+        headers = {
+            "Authorization": f"Basic {credentials}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+        labels = ["nat-security", finding.check_id]
+        fields: dict = {
+            "project": {"key": project_key},
+            "summary": f"[NAT] {finding.title}",
+            "description": self._build_adf_body(body_text),
+            "issuetype": {"name": issue_type},
+            "priority": {"name": priority_name},
+            "labels": labels,
+        }
+        if component:
+            fields["components"] = [{"name": component}]
+
+        payload = {"fields": fields}
+
+        try:
+            async with httpx.AsyncClient(headers=headers, timeout=30) as client:
+                resp = await client.post(
+                    f"{base_url}/rest/api/3/issue",
+                    json=payload,
+                )
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.HTTPStatusError as exc:
+            error_msg = f"Jira API error {exc.response.status_code}: {exc.response.text}"
+            logger.warning("JiraExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+        except httpx.RequestError as exc:
+            error_msg = f"Jira network error: {exc}"
+            logger.warning("JiraExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+
+        issue_key = data.get("key", "")
+        issue_url = f"{base_url}/browse/{issue_key}" if issue_key else None
+        return ExportResult(
+            finding=finding,
+            success=True,
+            external_id=issue_key,
+            external_url=issue_url,
+        )