nat-engine 1__py3-none-any.whl

mannf/product/exporters/pagerduty_exporter.py

@@ -0,0 +1,363 @@
+# 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.
+
+"""PagerDuty exporter plugin — creates PagerDuty incidents from NAT security findings.
+
+Implements the PagerDuty Events API v2 (https://events.pagerduty.com/v2/enqueue).
+Only findings at severity >= High are posted as incidents by default; this
+threshold is configurable via the ``min_severity`` config key.
+
+Usage
+-----
+Export high/critical findings to PagerDuty via the CLI::
+
+    nat security-scan --spec api.yaml --base-url http://localhost \\
+      --export pagerduty \\
+      --export-config routing_key=$PD_ROUTING_KEY \\
+      --export-min-severity high
+
+Required config keys
+--------------------
+routing_key:
+    PagerDuty *integration key* (also called *routing key*).  Created by
+    adding a new **Events API v2** integration on a PagerDuty service.
+
+Optional config keys
+--------------------
+service_id:
+    PagerDuty service ID.  Included in incident details for reference.
+escalation_policy:
+    Escalation policy name.  Included in incident details for reference.
+source:
+    The ``source`` field in the PagerDuty event payload (default
+    ``"nat-security-scan"``).
+component:
+    The ``component`` field in the PagerDuty event payload.  Useful for
+    grouping incidents (e.g., ``"api"``, ``"auth-service"``).
+group:
+    The ``group`` field in the PagerDuty event payload.
+playbook_url:
+    URL to a remediation playbook.  Included as a link in the incident body.
+artifact_url:
+    URL to a scan artifact (e.g., a report HTML or JSON link).  Included as
+    a link in the incident body.
+timeout:
+    HTTP request timeout in seconds (default ``30``).
+
+Severity mapping
+----------------
+NAT severities are mapped to the four PagerDuty severity levels as follows:
+
++------------+------------------+
+| NAT        | PagerDuty        |
++============+==================+
+| critical   | critical         |
++------------+------------------+
+| high       | error            |
++------------+------------------+
+| medium     | warning          |
++------------+------------------+
+| low        | warning          |
++------------+------------------+
+| info       | info             |
++------------+------------------+
+
+Dedup keys
+----------
+A deterministic ``dedup_key`` is generated from the scan ID and finding check
+ID so that re-running a scan never creates duplicate incidents for the same
+finding.  The key has the format ``nat-<scan_id>-<check_id>``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+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__)
+
+_PAGERDUTY_EVENTS_URL = "https://events.pagerduty.com/v2/enqueue"
+
+_SEVERITY_TO_PD: dict[str, str] = {
+    "critical": "critical",
+    "high": "error",
+    "medium": "warning",
+    "low": "warning",
+    "info": "info",
+}
+
+
+class PagerDutyExporter(ExporterPlugin):
+    """Exports NAT security findings as PagerDuty incidents via the Events API v2.
+
+    Only findings at severity >= ``high`` are posted by default.  Use the
+    ``min_severity`` parameter on :meth:`export_findings` (or the CLI flag
+    ``--export-min-severity``) to change this threshold.
+
+    Required config keys:
+        routing_key: PagerDuty integration key (Events API v2).
+
+    Optional config keys:
+        service_id:         PagerDuty service ID (included in incident details).
+        escalation_policy:  Escalation policy name (included in incident details).
+        source:             Event source label (default ``"nat-security-scan"``).
+        component:          Component label for grouping incidents.
+        group:              Group label for grouping incidents.
+        playbook_url:       URL to a remediation playbook.
+        artifact_url:       URL to a scan artifact or report.
+        timeout:            HTTP timeout in seconds (default ``30``).
+    """
+
+    name = "pagerduty"
+    display_name = "PagerDuty"
+    description = (
+        "Creates PagerDuty incidents for NAT security findings via the Events API v2."
+    )
+
+    # ------------------------------------------------------------------
+    # Config validation
+    # ------------------------------------------------------------------
+
+    def validate_config(self, config: dict) -> list[str]:
+        errors: list[str] = []
+
+        if not config.get("routing_key"):
+            errors.append("'routing_key' is required")
+
+        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")
+
+        return errors
+
+    # ------------------------------------------------------------------
+    # Connection test
+    # ------------------------------------------------------------------
+
+    async def test_connection(self, config: dict) -> TestConnectionResult:
+        """Test connection via GET /abilities with routing_key header — confirms key validity."""
+        errors = self.validate_config(config)
+        if errors:
+            return TestConnectionResult(
+                success=False,
+                message=f"Config validation failed: {'; '.join(errors)}",
+                details={"errors": errors},
+            )
+
+        routing_key = config["routing_key"]
+        timeout = self._get_timeout(config)
+
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                resp = await client.get(
+                    "https://api.pagerduty.com/abilities",
+                    headers={
+                        "Accept": "application/json",
+                        "Authorization": f"Token token={routing_key}",
+                    },
+                )
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            if status == 401:
+                msg = "PagerDuty authentication failed — check your routing_key"
+            elif status == 403:
+                msg = "PagerDuty access forbidden — routing_key may lack required permissions"
+            else:
+                msg = f"PagerDuty API error {status}: {exc.response.text}"
+            return TestConnectionResult(success=False, message=msg, details={})
+        except httpx.RequestError as exc:
+            return TestConnectionResult(
+                success=False,
+                message=f"PagerDuty network error: {exc}",
+                details={},
+            )
+
+        abilities = data.get("abilities", [])
+        return TestConnectionResult(
+            success=True,
+            message="Connected to PagerDuty — routing key is valid",
+            details={"abilities": abilities},
+        )
+
+    # ------------------------------------------------------------------
+    # Severity mapping
+    # ------------------------------------------------------------------
+
+    def _severity_to_priority(self, severity: str) -> str:
+        """Map a NAT severity to a PagerDuty severity label."""
+        return _SEVERITY_TO_PD.get(severity.lower(), "warning")
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _build_dedup_key(self, finding: SecurityFinding, report: SecurityReport) -> str:
+        """Generate a deterministic dedup key for idempotent incident creation.
+
+        The key is a short SHA-256 hex digest derived from the scan ID and the
+        finding check ID, prefixed with ``nat-`` for easy identification in
+        PagerDuty.  Identical findings from the same scan always produce the
+        same key so re-posting is idempotent.
+        """
+        raw = f"{report.scan_id}:{finding.check_id}:{finding.endpoint}"
+        digest = hashlib.sha256(raw.encode()).hexdigest()[:16]
+        return f"nat-{digest}"
+
+    def _build_payload(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> dict:
+        """Build the PagerDuty Events API v2 request payload."""
+        routing_key: str = config["routing_key"]
+        source: str = config.get("source", "nat-security-scan")
+        component: str | None = config.get("component")
+        group: str | None = config.get("group")
+        service_id: str | None = config.get("service_id")
+        escalation_policy: str | None = config.get("escalation_policy")
+        playbook_url: str | None = config.get("playbook_url")
+        artifact_url: str | None = config.get("artifact_url")
+
+        pd_severity = self._severity_to_priority(finding.severity)
+        dedup_key = self._build_dedup_key(finding, report)
+
+        summary = f"[NAT] {finding.title} — {finding.endpoint} ({finding.severity.upper()})"
+
+        custom_details: dict = {
+            "check_id": finding.check_id,
+            "check_name": finding.check_name,
+            "nat_severity": finding.severity,
+            "endpoint": finding.endpoint,
+            "description": finding.description,
+            "evidence": finding.evidence,
+            "remediation": finding.remediation,
+            "confidence": finding.confidence,
+            "scan_id": report.scan_id,
+            "target_url": report.target_url,
+            "scan_timestamp": report.timestamp,
+            "total_endpoints_scanned": report.total_endpoints_scanned,
+        }
+        if finding.cwe_id:
+            custom_details["cwe_id"] = finding.cwe_id
+            custom_details["cwe_url"] = (
+                f"https://cwe.mitre.org/data/definitions/{finding.cwe_id.replace('CWE-', '')}.html"
+            )
+        if service_id:
+            custom_details["service_id"] = service_id
+        if escalation_policy:
+            custom_details["escalation_policy"] = escalation_policy
+
+        event_payload: dict = {
+            "summary": summary,
+            "source": source,
+            "severity": pd_severity,
+            "custom_details": custom_details,
+        }
+        if component:
+            event_payload["component"] = component
+        if group:
+            event_payload["group"] = group
+
+        # Links: playbook and artifact references
+        links: list[dict] = []
+        if playbook_url:
+            links.append({"href": playbook_url, "text": "Remediation Playbook"})
+        if artifact_url:
+            links.append({"href": artifact_url, "text": "Scan Artifact / Report"})
+        # Always include a CWE reference link when available
+        if finding.cwe_id:
+            cwe_num = finding.cwe_id.replace("CWE-", "")
+            links.append({
+                "href": f"https://cwe.mitre.org/data/definitions/{cwe_num}.html",
+                "text": f"CWE Reference: {finding.cwe_id}",
+            })
+
+        body: dict = {
+            "routing_key": routing_key,
+            "event_action": "trigger",
+            "dedup_key": dedup_key,
+            "payload": event_payload,
+        }
+        if links:
+            body["links"] = links
+
+        return body
+
+    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:
+        timeout = self._get_timeout(config)
+
+        payload = self._build_payload(finding, report, config)
+        dedup_key: str = payload["dedup_key"]
+
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+        try:
+            async with httpx.AsyncClient(headers=headers, timeout=timeout) as client:
+                resp = await client.post(
+                    _PAGERDUTY_EVENTS_URL,
+                    json=payload,
+                )
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            error_msg = f"PagerDuty API error {status}: {exc.response.text}"
+            if status == 401:
+                error_msg = "PagerDuty API error 401: invalid routing_key / unauthorized"
+            elif status == 429:
+                error_msg = "PagerDuty API error 429: rate limit exceeded — retry later"
+            logger.warning("PagerDutyExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+        except httpx.RequestError as exc:
+            error_msg = f"PagerDuty network error: {exc}"
+            logger.warning("PagerDutyExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+
+        # PagerDuty Events API v2 returns {"status": "success", "dedup_key": "..."}
+        incident_key = data.get("dedup_key", dedup_key)
+        external_url = (
+            f"https://app.pagerduty.com/incidents?service_id={config['service_id']}"
+            if config.get("service_id")
+            else "https://app.pagerduty.com/incidents"
+        )
+        return ExportResult(
+            finding=finding,
+            success=True,
+            external_id=incident_key,
+            external_url=external_url,
+        )

mannf/product/exporters/sentry_exporter.py

@@ -0,0 +1,322 @@
+# 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.
+
+"""Sentry exporter plugin — creates Sentry 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__)
+
+# NAT severity → Sentry event level
+_SEVERITY_TO_SENTRY_LEVEL: dict[str, str] = {
+    "critical": "fatal",
+    "high": "error",
+    "medium": "warning",
+    "low": "info",
+    "info": "debug",
+}
+
+
+class SentryExporter(ExporterPlugin):
+    """Exports NAT security findings as Sentry issues via the Sentry Issues API.
+
+    Required config keys:
+        dsn:           Sentry DSN (includes project ID, public key, and host).
+                       Either ``dsn`` **or** both ``auth_token`` + ``org_slug`` +
+                       ``project_slug`` must be provided.
+
+    Optional config keys (alternative auth path):
+        auth_token:    Sentry auth token (alternative to DSN-based creation).
+        org_slug:      Sentry organisation slug (required when using auth_token).
+        project_slug:  Sentry project slug (required when using auth_token for
+                       ``test_connection``).
+
+    Optional config keys (tagging / grouping):
+        environment:   Environment tag attached to each event (default ``"nat-scan"``).
+        release:       Release string to associate with events.
+    """
+
+    name = "sentry"
+    display_name = "Sentry"
+    description = "Creates Sentry issues for NAT security findings via the Sentry Issues API."
+
+    def validate_config(self, config: dict) -> list[str]:
+        errors: list[str] = []
+        has_dsn = bool(config.get("dsn"))
+        has_token = bool(config.get("auth_token"))
+        if not has_dsn and not has_token:
+            errors.append(
+                "Either 'dsn' or 'auth_token' is required"
+            )
+        if has_token:
+            if not config.get("org_slug"):
+                errors.append("'org_slug' is required when using 'auth_token'")
+            if not config.get("project_slug"):
+                errors.append("'project_slug' is required when using 'auth_token'")
+        return errors
+
+    async def test_connection(self, config: dict) -> TestConnectionResult:
+        """Test connection via GET /api/0/projects/{org_slug}/{project_slug}/ — confirms token + project access."""
+        errors = self.validate_config(config)
+        if errors:
+            return TestConnectionResult(
+                success=False,
+                message=f"Config validation failed: {'; '.join(errors)}",
+                details={"errors": errors},
+            )
+
+        auth_token = config.get("auth_token")
+        org_slug = config.get("org_slug")
+        project_slug = config.get("project_slug")
+
+        if not (auth_token and org_slug and project_slug):
+            # DSN-only config — no API-based connection test is possible without
+            # the org/project slugs; fall back to config-valid success.
+            return TestConnectionResult(
+                success=True,
+                message="Sentry config is valid (DSN-only mode — live connection test requires auth_token + org_slug + project_slug).",
+                details={"mode": "dsn"},
+            )
+
+        url = f"https://sentry.io/api/0/projects/{org_slug}/{project_slug}/"
+        headers = {
+            "Authorization": f"Bearer {auth_token}",
+            "Content-Type": "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 = "Sentry authentication failed — check your auth_token"
+            elif status == 403:
+                msg = "Sentry access forbidden — check auth_token scopes (project:read required)"
+            elif status == 404:
+                msg = f"Sentry project '{org_slug}/{project_slug}' not found — check org_slug and project_slug"
+            else:
+                msg = f"Sentry API error {status}: {exc.response.text}"
+            return TestConnectionResult(success=False, message=msg, details={})
+        except httpx.RequestError as exc:
+            return TestConnectionResult(
+                success=False,
+                message=f"Sentry network error: {exc}",
+                details={},
+            )
+
+        project_name = data.get("name", project_slug)
+        return TestConnectionResult(
+            success=True,
+            message=f"Connected to Sentry — project '{project_name}' is accessible",
+            details={"project": project_name, "org": org_slug},
+        )
+
+    def _severity_to_priority(self, severity: str) -> str:
+        """Map NAT severity to a Sentry event level string."""
+        return _SEVERITY_TO_SENTRY_LEVEL.get(severity.lower(), "error")
+
+    def _parse_dsn(self, dsn: str) -> tuple[str, str, str]:
+        """Parse a Sentry DSN into (store_url, public_key, project_id).
+
+        A Sentry DSN has the form::
+
+            https://<public_key>@<host>/api/<project_id>/store/
+            or
+            https://<public_key>@<host>/<project_id>
+
+        Returns (store_url, public_key, project_id).
+        Raises ValueError if the DSN cannot be parsed.
+        """
+        # Normalise: strip trailing slash, split scheme
+        dsn = dsn.strip().rstrip("/")
+        if "://" not in dsn:
+            raise ValueError(f"Invalid Sentry DSN (missing scheme): {dsn!r}")
+        scheme, rest = dsn.split("://", 1)
+
+        if "@" not in rest:
+            raise ValueError(f"Invalid Sentry DSN (missing '@'): {dsn!r}")
+        public_key, hostpath = rest.split("@", 1)
+
+        # Extract host and path
+        if "/" not in hostpath:
+            raise ValueError(f"Invalid Sentry DSN (missing project path): {dsn!r}")
+        slash_idx = hostpath.index("/")
+        host = hostpath[:slash_idx]
+        path = hostpath[slash_idx + 1:]
+
+        # The path might be just the project_id (legacy) or already api/<id>
+        parts = [p for p in path.split("/") if p]
+        if not parts:
+            raise ValueError(f"Invalid Sentry DSN (missing project ID): {dsn!r}")
+        project_id = parts[-1]
+
+        store_url = f"{scheme}://{host}/api/{project_id}/store/"
+        return store_url, public_key, project_id
+
+    def _build_event_payload(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> dict:
+        """Build the Sentry store-endpoint event payload."""
+        level = self._severity_to_priority(finding.severity)
+        environment = config.get("environment", "nat-scan")
+        body_text = self._format_finding_body(finding, report)
+
+        tags: list[dict] = [
+            {"key": "severity", "value": finding.severity},
+            {"key": "check_id", "value": finding.check_id},
+            {"key": "scan_id", "value": report.scan_id},
+        ]
+        if finding.cwe_id:
+            tags.append({"key": "cwe", "value": finding.cwe_id})
+
+        payload: dict = {
+            "message": f"[NAT] {finding.title}",
+            "level": level,
+            "environment": environment,
+            "tags": tags,
+            "extra": {
+                "check_id": finding.check_id,
+                "check_name": finding.check_name,
+                "endpoint": finding.endpoint,
+                "confidence": finding.confidence,
+                "remediation": finding.remediation,
+                "scan_id": report.scan_id,
+                "target_url": report.target_url,
+                "body": body_text,
+            },
+            "fingerprint": [
+                "nat",
+                report.scan_id,
+                finding.check_id,
+                finding.endpoint or "",
+            ],
+        }
+
+        if config.get("release"):
+            payload["release"] = config["release"]
+
+        return payload
+
+    async def export_finding(
+        self,
+        finding: SecurityFinding,
+        report: SecurityReport,
+        config: dict,
+    ) -> ExportResult:
+        dsn = config.get("dsn", "")
+        auth_token = config.get("auth_token")
+        environment = config.get("environment", "nat-scan")
+        payload = self._build_event_payload(finding, report, config)
+
+        if dsn:
+            # DSN-based submission via the store endpoint
+            try:
+                store_url, public_key, project_id = self._parse_dsn(dsn)
+            except ValueError as exc:
+                error_msg = f"Invalid Sentry DSN: {exc}"
+                logger.warning("SentryExporter: %s", error_msg)
+                return ExportResult(finding=finding, success=False, error=error_msg)
+
+            headers = {
+                "Content-Type": "application/json",
+                "X-Sentry-Auth": (
+                    f"Sentry sentry_version=7, sentry_key={public_key}, "
+                    f"sentry_client=nat-sentry-exporter/1.0"
+                ),
+            }
+
+            try:
+                async with httpx.AsyncClient(timeout=30) as client:
+                    resp = await client.post(store_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 = "Sentry authentication failed — check your auth_token or DSN"
+                elif status == 429:
+                    error_msg = "Sentry rate limit exceeded — try again later"
+                else:
+                    error_msg = f"Sentry API error {status}: {exc.response.text}"
+                logger.warning("SentryExporter: %s", error_msg)
+                return ExportResult(finding=finding, success=False, error=error_msg)
+            except httpx.RequestError as exc:
+                error_msg = f"Sentry network error: {exc}"
+                logger.warning("SentryExporter: %s", error_msg)
+                return ExportResult(finding=finding, success=False, error=error_msg)
+
+            event_id: str = data.get("id", "")
+            return ExportResult(
+                finding=finding,
+                success=True,
+                external_id=event_id or None,
+                external_url=None,
+            )
+
+        # auth_token-based submission via the Issues API
+        org_slug = config.get("org_slug", "")
+        project_slug = config.get("project_slug", "")
+
+        # Build an issue via the Issues API (POST /api/0/projects/{org}/{proj}/issues/)
+        # For creating new events we use the store endpoint if available; otherwise
+        # we submit a synthetic issue payload.
+        issue_payload = {
+            "title": f"[NAT] {finding.title}",
+            "culprit": finding.endpoint or "",
+            "level": self._severity_to_priority(finding.severity),
+            "environment": environment,
+            "tags": {t["key"]: t["value"] for t in payload.get("tags", [])},
+            "extra": payload.get("extra", {}),
+        }
+        if config.get("release"):
+            issue_payload["release"] = config["release"]
+
+        url = f"https://sentry.io/api/0/projects/{org_slug}/{project_slug}/issues/"
+        headers = {
+            "Authorization": f"Bearer {auth_token}",
+            "Content-Type": "application/json",
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=30) as client:
+                resp = await client.post(url, json=issue_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 = "Sentry authentication failed — check your auth_token"
+            elif status == 429:
+                error_msg = "Sentry rate limit exceeded — try again later"
+            else:
+                error_msg = f"Sentry API error {status}: {exc.response.text}"
+            logger.warning("SentryExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+        except httpx.RequestError as exc:
+            error_msg = f"Sentry network error: {exc}"
+            logger.warning("SentryExporter: %s", error_msg)
+            return ExportResult(finding=finding, success=False, error=error_msg)
+
+        issue_id: str = str(data.get("id", ""))
+        issue_url: str | None = data.get("permalink")
+        return ExportResult(
+            finding=finding,
+            success=True,
+            external_id=issue_id or None,
+            external_url=issue_url,
+        )