nat-engine 1__py3-none-any.whl

mannf/product/security/reporter.py

@@ -0,0 +1,92 @@
+# 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.
+
+"""Security report output formatters."""
+
+from __future__ import annotations
+
+import json
+
+from mannf.product.security.models import SecurityFinding, SecurityReport, _severity_order
+
+_SEVERITY_EMOJI = {
+    "critical": "🔴",
+    "high": "🟠",
+    "medium": "🟡",
+    "low": "🔵",
+    "info": "ℹ️",
+}
+
+
+class SecurityReporter:
+    def to_json(self, report: SecurityReport) -> str:
+        return json.dumps(report.to_dict(), indent=2)
+
+    def to_markdown(self, report: SecurityReport) -> str:
+        lines: list[str] = []
+
+        lines.append("# NAT Security Scan Report")
+        lines.append("")
+        lines.append(f"**Scan ID:** `{report.scan_id}`  ")
+        lines.append(f"**Timestamp:** {report.timestamp}  ")
+        lines.append(f"**Target:** {report.target_url}  ")
+        lines.append(f"**Endpoints scanned:** {report.total_endpoints_scanned}  ")
+        lines.append(f"**Belief-guided:** {report.belief_guided}  ")
+        lines.append("")
+
+        lines.append("## Summary")
+        lines.append("")
+        lines.append("| Severity | Count |")
+        lines.append("|----------|-------|")
+        for sev in sorted(_severity_order, key=lambda s: _severity_order[s]):
+            count = report.summary.get(sev, 0)
+            emoji = _SEVERITY_EMOJI.get(sev, "")
+            lines.append(f"| {emoji} {sev.capitalize()} | {count} |")
+        lines.append("")
+
+        total = len(report.findings)
+        lines.append(f"**Total findings:** {total}")
+        lines.append("")
+
+        if not report.findings:
+            lines.append("_No findings above threshold._")
+            return "\n".join(lines)
+
+        lines.append("## Findings")
+        lines.append("")
+
+        by_severity: dict[str, list[SecurityFinding]] = {}
+        for f in report.findings:
+            by_severity.setdefault(f.severity, []).append(f)
+
+        for sev in sorted(_severity_order, key=lambda s: _severity_order[s]):
+            group = by_severity.get(sev, [])
+            if not group:
+                continue
+            emoji = _SEVERITY_EMOJI.get(sev, "")
+            lines.append(f"### {emoji} {sev.capitalize()} ({len(group)})")
+            lines.append("")
+
+            for finding in group:
+                lines.append(f"#### {finding.title}")
+                lines.append("")
+                lines.append(f"- **Check:** {finding.check_id} — {finding.check_name}")
+                lines.append(f"- **Endpoint:** `{finding.endpoint}`")
+                lines.append(f"- **CWE:** {finding.cwe_id}")
+                lines.append(f"- **Confidence:** {finding.confidence:.0%}")
+                lines.append("")
+                lines.append(f"**Description:** {finding.description}")
+                lines.append("")
+                lines.append("**Evidence:**")
+                lines.append("```")
+                lines.append(finding.evidence)
+                lines.append("```")
+                lines.append("")
+                lines.append(f"**Remediation:** {finding.remediation}")
+                lines.append("")
+                lines.append("---")
+                lines.append("")
+
+        return "\n".join(lines)

mannf/product/security/scanner.py

@@ -0,0 +1,183 @@
+# 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.
+
+"""Main SecurityScanner orchestrator."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+import httpx
+
+from mannf.product.security.belief_guided import prioritize_for_security
+from mannf.product.security.checks import (
+    BFLACheck,
+    BOLACheck,
+    BOPLACheck,
+    BrokenAuthCheck,
+    EndpointInfo,
+    InventoryCheck,
+    MisconfigCheck,
+    ResourceConsumptionCheck,
+    SecurityCheck,
+    SensitiveFlowsCheck,
+    SSRFCheck,
+    UnsafeConsumptionCheck,
+)
+from mannf.product.security.models import EndpointSecurityPriority, SecurityFinding, SecurityReport, _severity_order
+
+if TYPE_CHECKING:
+    from mannf.core.agents.belief_state import BeliefState
+    from mannf.core.prioritization.risk_scorer import RiskScorer
+
+_ALL_CHECKS: list[SecurityCheck] = [
+    BOLACheck(),
+    BrokenAuthCheck(),
+    BOPLACheck(),
+    ResourceConsumptionCheck(),
+    BFLACheck(),
+    SensitiveFlowsCheck(),
+    SSRFCheck(),
+    MisconfigCheck(),
+    InventoryCheck(),
+    UnsafeConsumptionCheck(),
+]
+
+_HIGH_RISK_THRESHOLD = 0.7
+
+
+class SecurityScanner:
+    def __init__(
+        self,
+        base_url: str,
+        enabled_checks: list[str] | None = None,
+        severity_threshold: str = "low",
+        timeout: float = 10.0,
+        belief_guided: bool = True,
+        adaptive_checks: bool = True,
+        extra_checks: list[SecurityCheck] | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.severity_threshold = severity_threshold
+        self.timeout = timeout
+        self.belief_guided = belief_guided
+        self.adaptive_checks = adaptive_checks
+
+        all_checks = list(_ALL_CHECKS) + list(extra_checks or [])
+
+        if enabled_checks is None:
+            self._checks = all_checks
+        else:
+            prefixes = [c.upper() for c in enabled_checks]
+            self._checks = [
+                c for c in all_checks
+                if any(c.owasp_id.upper().startswith(p) for p in prefixes)
+            ]
+
+    def _checks_for_ids(self, check_ids: list[str]) -> list[SecurityCheck]:
+        """Return the subset of enabled checks matching the given OWASP IDs."""
+        id_set = {cid.upper() for cid in check_ids}
+        return [c for c in self._checks if c.owasp_id.upper() in id_set]
+
+    async def scan(
+        self,
+        endpoints: list[EndpointInfo],
+        risk_report: list[dict] | None = None,
+        belief_states: list[BeliefState] | None = None,
+        risk_scorer: RiskScorer | None = None,
+    ) -> SecurityReport:
+        scan_id = str(uuid.uuid4())
+        timestamp = datetime.now(timezone.utc).isoformat()
+
+        prioritization_entries: list[EndpointSecurityPriority] = []
+
+        if self.belief_guided:
+            prioritized = prioritize_for_security(
+                endpoints,
+                risk_report=risk_report,
+                belief_states=belief_states,
+                risk_scorer=risk_scorer,
+            )
+            ordered_endpoints = [ep for ep, _score, _ids, _bs, _rs in prioritized]
+        else:
+            prioritized = []
+            ordered_endpoints = endpoints
+
+        all_findings: list[SecurityFinding] = []
+
+        async with httpx.AsyncClient(
+            timeout=self.timeout, follow_redirects=True
+        ) as client:
+            for i, endpoint in enumerate(ordered_endpoints):
+                if self.belief_guided and self.adaptive_checks and i < len(prioritized):
+                    _, priority_score, check_ids, belief_score, risk_score_val = prioritized[i]
+                    # High-risk endpoints get all enabled checks as a safety net
+                    if priority_score > _HIGH_RISK_THRESHOLD:
+                        checks_to_run = self._checks
+                    else:
+                        checks_to_run = self._checks_for_ids(check_ids) or self._checks
+                    checks_run = [c.owasp_id for c in checks_to_run]
+                    prioritization_entries.append(
+                        EndpointSecurityPriority(
+                            endpoint=f"{endpoint.method} {endpoint.path}",
+                            priority_score=priority_score,
+                            belief_score=belief_score,
+                            risk_score=risk_score_val,
+                            check_ids=check_ids,
+                            checks_run=checks_run,
+                        )
+                    )
+                else:
+                    checks_to_run = self._checks
+                    if self.belief_guided and i < len(prioritized):
+                        _, priority_score, check_ids, belief_score, risk_score_val = prioritized[i]
+                        prioritization_entries.append(
+                            EndpointSecurityPriority(
+                                endpoint=f"{endpoint.method} {endpoint.path}",
+                                priority_score=priority_score,
+                                belief_score=belief_score,
+                                risk_score=risk_score_val,
+                                check_ids=check_ids,
+                                checks_run=[c.owasp_id for c in checks_to_run],
+                            )
+                        )
+
+                results = await asyncio.gather(
+                    *[check.run(endpoint, client) for check in checks_to_run],
+                    return_exceptions=True,
+                )
+                for result in results:
+                    if isinstance(result, list):
+                        all_findings.extend(result)
+
+        filtered = self._filter_by_severity(all_findings)
+        filtered.sort(key=lambda f: _severity_order.get(f.severity, 99))
+
+        summary: dict[str, int] = {s: 0 for s in _severity_order}
+        for f in filtered:
+            summary[f.severity] = summary.get(f.severity, 0) + 1
+
+        return SecurityReport(
+            scan_id=scan_id,
+            timestamp=timestamp,
+            target_url=self.base_url,
+            total_endpoints_scanned=len(ordered_endpoints),
+            findings=filtered,
+            summary=summary,
+            belief_guided=self.belief_guided,
+            prioritization=prioritization_entries,
+        )
+
+    def _filter_by_severity(
+        self, findings: list[SecurityFinding]
+    ) -> list[SecurityFinding]:
+        threshold_order = _severity_order.get(self.severity_threshold, 99)
+        return [
+            f for f in findings
+            if _severity_order.get(f.severity, 99) <= threshold_order
+        ]