nat-engine 1__py3-none-any.whl

mannf/product/exporters/linear_exporter.py

@@ -0,0 +1,195 @@
+# 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.
+
+"""Linear exporter plugin — creates Linear 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.security.models import SecurityFinding, SecurityReport
+
+logger = logging.getLogger(__name__)
+
+_LINEAR_API_URL = "https://api.linear.app/graphql"
+
+# Linear priority values: 0=no priority, 1=urgent, 2=high, 3=medium, 4=low
+_SEVERITY_TO_LINEAR_PRIORITY: dict[str, int] = {
+    "critical": 1,
+    "high": 2,
+    "medium": 3,
+    "low": 4,
+    "info": 0,
+}
+
+_ISSUE_CREATE_MUTATION = """
+mutation IssueCreate($input: IssueCreateInput!) {
+  issueCreate(input: $input) {
+    success
+    issue {
+      id
+      identifier
+      url
+    }
+  }
+}
+"""
+
+
+class LinearExporter(ExporterPlugin):
+    """Exports NAT security findings as Linear issues via the GraphQL API.
+
+    Required config keys:
+        api_key:  Linear personal API key.
+        team_id:  Linear team ID to create issues in.
+
+    Optional config keys:
+        project_id:  Linear project ID to assign issues to.
+        assignee_id: Linear user ID to assign issues to.
+        label_ids:   List of Linear label IDs to attach to every issue.
+    """
+
+    name = "linear"
+    display_name = "Linear"
+    description = "Creates Linear issues for NAT security findings via the GraphQL API."
+
+    def validate_config(self, config: dict) -> list[str]:
+        required = ("api_key", "team_id")
+        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 POST /graphql with viewer query — confirms api_key."""
+        errors = self.validate_config(config)
+        if errors:
+            return TestConnectionResult(
+                success=False,
+                message=f"Config validation failed: {'; '.join(errors)}",
+                details={"errors": errors},
+            )
+
+        api_key = config["api_key"]
+        headers = {
+            "Authorization": api_key,
+            "Content-Type": "application/json",
+        }
+        payload = {"query": "{ viewer { id name } }"}
+
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                resp = await client.post(_LINEAR_API_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:
+                msg = "Linear authentication failed — check your api_key"
+            else:
+                msg = f"Linear API error {status}: {exc.response.text}"
+            return TestConnectionResult(success=False, message=msg, details={})
+        except httpx.RequestError as exc:
+            return TestConnectionResult(
+                success=False,
+                message=f"Linear network error: {exc}",
+                details={},
+            )
+
+        gql_errors = data.get("errors")
+        if gql_errors:
+            return TestConnectionResult(
+                success=False,
+                message=f"Linear GraphQL error: {gql_errors[0].get('message', str(gql_errors))}",
+                details={},
+            )
+
+        viewer = data.get("data", {}).get("viewer", {})
+        name = viewer.get("name", "unknown")
+        return TestConnectionResult(
+            success=True,
+            message=f"Connected to Linear — authenticated as '{name}'",
+            details={"id": viewer.get("id"), "name": name},
+        )
+
+    def _severity_to_priority(self, severity: str) -> str:
+        # Return a string representation for the base class contract;
+        # use _severity_to_linear_priority() for the numeric value.
+        return str(_SEVERITY_TO_LINEAR_PRIORITY.get(severity.lower(), 0))
+
+    def _severity_to_linear_priority(self, severity: str) -> int:
+        return _SEVERITY_TO_LINEAR_PRIORITY.get(severity.lower(), 0)
+
+    async def export_finding(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> ExportResult:
+        api_key = config["api_key"]
+        team_id = config["team_id"]
+        project_id = config.get("project_id")
+        assignee_id = config.get("assignee_id")
+        label_ids: list[str] = config.get("label_ids") or []
+
+        priority = self._severity_to_linear_priority(finding.severity)
+        description = self._format_finding_body(finding, report)
+
+        issue_input: dict = {
+            "teamId": team_id,
+            "title": f"[NAT] {finding.title}",
+            "description": description,
+            "priority": priority,
+        }
+        if project_id:
+            issue_input["projectId"] = project_id
+        if assignee_id:
+            issue_input["assigneeId"] = assignee_id
+        if label_ids:
+            issue_input["labelIds"] = label_ids
+
+        headers = {
+            "Authorization": api_key,
+            "Content-Type": "application/json",
+        }
+
+        payload = {
+            "query": _ISSUE_CREATE_MUTATION,
+            "variables": {"input": issue_input},
+        }
+
+        try:
+            async with httpx.AsyncClient(headers=headers, timeout=30) as client:
+                resp = await client.post(_LINEAR_API_URL, json=payload)
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.HTTPStatusError as exc:
+            error_msg = f"Linear API error {exc.response.status_code}: {exc.response.text}"
+            logger.warning("LinearExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+        except httpx.RequestError as exc:
+            error_msg = f"Linear network error: {exc}"
+            logger.warning("LinearExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+
+        errors = data.get("errors")
+        if errors:
+            error_msg = f"Linear GraphQL errors: {errors}"
+            logger.warning("LinearExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+
+        issue_create = data.get("data", {}).get("issueCreate", {})
+        if not issue_create.get("success"):
+            error_msg = "Linear issueCreate returned success=false"
+            logger.warning("LinearExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+
+        issue = issue_create.get("issue", {})
+        return ExportResult(
+            finding=finding,
+            success=True,
+            external_id=issue.get("identifier"),
+            external_url=issue.get("url"),
+        )

mannf/product/exporters/loader.py

@@ -0,0 +1,233 @@
+# 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.
+
+"""Plugin loader for custom ExporterPlugin implementations.
+
+Provides two discovery mechanisms:
+  - Directory scanning: load .py files from a directory path.
+  - Entry-point discovery: use importlib.metadata to find registered exporters.
+
+Both mechanisms validate that each discovered class has the required attributes
+and the callable methods before instantiating it.  Invalid exporters are skipped
+with a warning — they will never cause the scanner to crash.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import inspect
+import logging
+import sys
+from importlib.metadata import entry_points
+from pathlib import Path
+
+from mannf.product.exporters.base import ExporterPlugin
+
+logger = logging.getLogger(__name__)
+
+_REQUIRED_ATTRS = ("name", "display_name", "description")
+
+
+def _is_valid_exporter(cls: type) -> bool:
+    """Return True if *cls* is a valid, concrete ExporterPlugin subclass."""
+    if not (isinstance(cls, type) and issubclass(cls, ExporterPlugin) and cls is not ExporterPlugin):
+        return False
+    for attr in _REQUIRED_ATTRS:
+        if not hasattr(cls, attr):
+            logger.warning(
+                "Exporter %s is missing required attribute '%s' — skipping.",
+                cls.__name__,
+                attr,
+            )
+            return False
+    if not callable(getattr(cls, "export_finding", None)):
+        logger.warning(
+            "Exporter %s has no callable 'export_finding' method — skipping.",
+            cls.__name__,
+        )
+        return False
+    if not callable(getattr(cls, "validate_config", None)):
+        logger.warning(
+            "Exporter %s has no callable 'validate_config' method — skipping.",
+            cls.__name__,
+        )
+        return False
+    return True
+
+
+def _instantiate(cls: type) -> ExporterPlugin | None:
+    """Try to instantiate *cls*; log a warning and return None on failure."""
+    try:
+        return cls()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning(
+            "Exporter %s raised %s during __init__ — skipping.", cls.__name__, exc
+        )
+        return None
+
+
+def load_exporters_from_directory(path: str) -> list[ExporterPlugin]:
+    """Discover and load ExporterPlugin subclasses from all ``.py`` files in *path*.
+
+    Parameters
+    ----------
+    path:
+        Filesystem path to a directory containing exporter ``.py`` files.
+
+    Returns
+    -------
+    list[ExporterPlugin]
+        Instantiated exporter objects for every valid exporter found.
+    """
+    exporters: list[ExporterPlugin] = []
+    directory = Path(path)
+
+    if not directory.exists():
+        logger.warning(
+            "Exporter directory '%s' does not exist — no exporters loaded.", path
+        )
+        return exporters
+
+    if not directory.is_dir():
+        logger.warning(
+            "Exporter path '%s' is not a directory — no exporters loaded.", path
+        )
+        return exporters
+
+    for py_file in sorted(directory.glob("*.py")):
+        module_name = f"_nat_exporter_{py_file.stem}"
+        try:
+            spec = importlib.util.spec_from_file_location(module_name, py_file)
+            if spec is None or spec.loader is None:
+                logger.warning(
+                    "Could not create module spec for '%s' — skipping.", py_file
+                )
+                continue
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module
+            spec.loader.exec_module(module)  # type: ignore[union-attr]
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "Failed to import exporter file '%s': %s — skipping.", py_file, exc
+            )
+            continue
+
+        for _name, obj in inspect.getmembers(module, inspect.isclass):
+            if obj.__module__ != module_name:
+                # Avoid re-processing imported base classes
+                continue
+            if _is_valid_exporter(obj):
+                instance = _instantiate(obj)
+                if instance is not None:
+                    exporters.append(instance)
+
+    return exporters
+
+
+def load_exporters_from_entry_points(
+    group: str = "nat.exporters",
+) -> list[ExporterPlugin]:
+    """Discover and load ExporterPlugin subclasses registered as package entry points.
+
+    Parameters
+    ----------
+    group:
+        The entry-point group name to scan (default ``"nat.exporters"``).
+
+    Returns
+    -------
+    list[ExporterPlugin]
+        Instantiated exporter objects for every valid entry point found.
+    """
+    exporters: list[ExporterPlugin] = []
+
+    try:
+        eps = entry_points(group=group)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning(
+            "Failed to query entry points for group '%s': %s", group, exc
+        )
+        return exporters
+
+    for ep in eps:
+        try:
+            obj = ep.load()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "Failed to load entry point '%s': %s — skipping.", ep.name, exc
+            )
+            continue
+
+        if _is_valid_exporter(obj):
+            instance = _instantiate(obj)
+            if instance is not None:
+                exporters.append(instance)
+        else:
+            logger.warning(
+                "Entry point '%s' does not point to a valid ExporterPlugin subclass — skipping.",
+                ep.name,
+            )
+
+    return exporters
+
+
+def load_all_exporters(
+    exporters_dir: str | None = None,
+    entry_point_group: str = "nat.exporters",
+) -> list[ExporterPlugin]:
+    """Load exporters from both a directory and registered entry points, deduplicating by class name.
+
+    Parameters
+    ----------
+    exporters_dir:
+        Optional filesystem path to a directory of exporter ``.py`` files.
+    entry_point_group:
+        Entry-point group to scan (default ``"nat.exporters"``).
+
+    Returns
+    -------
+    list[ExporterPlugin]
+        Merged, deduplicated list of instantiated exporter objects.
+    """
+    seen_class_names: set[str] = set()
+    combined: list[ExporterPlugin] = []
+
+    dir_exporters = (
+        load_exporters_from_directory(exporters_dir) if exporters_dir else []
+    )
+    ep_exporters = load_exporters_from_entry_points(entry_point_group)
+
+    for exporter in dir_exporters + ep_exporters:
+        class_name = type(exporter).__name__
+        if class_name not in seen_class_names:
+            seen_class_names.add(class_name)
+            combined.append(exporter)
+
+    return combined
+
+
+def get_exporter_by_name(
+    name: str,
+    exporters: list[ExporterPlugin],
+) -> ExporterPlugin | None:
+    """Look up an exporter by its ``name`` attribute.
+
+    Parameters
+    ----------
+    name:
+        The exporter name to search for (e.g., ``"jira"``, ``"linear"``).
+    exporters:
+        List of instantiated exporter objects to search.
+
+    Returns
+    -------
+    ExporterPlugin | None
+        The first matching exporter, or ``None`` if not found.
+    """
+    for exporter in exporters:
+        if exporter.name == name:
+            return exporter
+    return None