nat-engine 1__py3-none-any.whl

mannf/product/security/checks/bopla.py

@@ -0,0 +1,80 @@
+# 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.
+
+"""API3:2023 — Broken Object Property Level Authorization (BOPLA / Mass Assignment)."""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+
+from mannf.product.security.checks.base import EndpointInfo, SecurityCheck
+from mannf.product.security.models import SecurityFinding
+
+_SENSITIVE_FIELDS = [
+    "isAdmin", "role", "permissions", "admin", "verified", "active",
+    "is_admin", "is_verified", "is_active", "superuser",
+]
+
+_WRITE_METHODS = {"POST", "PUT", "PATCH"}
+
+
+class BOPLACheck(SecurityCheck):
+    owasp_id = "API3:2023"
+    name = "Broken Object Property Level Authorization"
+    description = "Tests for mass-assignment vulnerabilities by injecting unexpected fields."
+    severity_default = "high"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        if endpoint.method.upper() not in _WRITE_METHODS:
+            return []
+
+        payload = {field: True for field in _SENSITIVE_FIELDS}
+        payload["role"] = "admin"
+
+        url = endpoint.full_url
+        try:
+            resp = await client.request(
+                endpoint.method.upper(),
+                url,
+                content=json.dumps(payload),
+                headers={"Content-Type": "application/json"},
+            )
+        except httpx.RequestError:
+            return []
+
+        if resp.status_code not in range(200, 300):
+            return []
+
+        try:
+            body = resp.text
+        except Exception:
+            return []
+
+        echoed = [f for f in _SENSITIVE_FIELDS if f in body]
+        if not echoed:
+            return []
+
+        return [
+            self._make_finding(
+                endpoint,
+                title="Possible mass assignment: sensitive fields echoed in response",
+                description=(
+                    "The endpoint accepted and echoed back privilege-sensitive field(s) "
+                    f"injected in the request body: {echoed}. "
+                    "This may indicate a mass-assignment vulnerability."
+                ),
+                evidence=f"Injected fields: {echoed}; Response snippet: {body[:300]}",
+                remediation=(
+                    "Use an explicit allow-list (DTO/schema) for accepted request fields. "
+                    "Never bind request data directly to internal models."
+                ),
+                cwe_id="CWE-915",
+                confidence=0.7,
+            )
+        ]

mannf/product/security/checks/broken_auth.py

@@ -0,0 +1,86 @@
+# 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.
+
+"""API2:2023 — Broken Authentication."""
+
+from __future__ import annotations
+
+import httpx
+
+from mannf.product.security.checks.base import EndpointInfo, SecurityCheck
+from mannf.product.security.models import SecurityFinding
+
+_AUTH_PATH_HINTS = (
+    "/user", "/account", "/profile", "/order", "/payment",
+    "/admin", "/me", "/session", "/private",
+)
+
+_INVALID_TOKENS = [
+    None,  # no Authorization header
+    "Bearer invalid",
+    "Bearer ",
+    "",
+]
+
+
+def _path_suggests_auth(path: str) -> bool:
+    lower = path.lower()
+    return any(hint in lower for hint in _AUTH_PATH_HINTS)
+
+
+class BrokenAuthCheck(SecurityCheck):
+    owasp_id = "API2:2023"
+    name = "Broken Authentication"
+    description = "Tests whether authentication is properly enforced on protected endpoints."
+    severity_default = "critical"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        if not _path_suggests_auth(endpoint.path):
+            return []
+
+        findings: list[SecurityFinding] = []
+        url = endpoint.full_url
+
+        for token in _INVALID_TOKENS:
+            headers: dict[str, str] = {}
+            if token is None:
+                label = "no Authorization header"
+            elif token == "":
+                headers["Authorization"] = ""
+                label = "empty Authorization header"
+            else:
+                headers["Authorization"] = token
+                label = f"Authorization: {token}"
+
+            try:
+                resp = await client.request(
+                    endpoint.method.upper(), url, headers=headers
+                )
+            except httpx.RequestError:
+                continue
+
+            if resp.status_code == 200:
+                findings.append(
+                    self._make_finding(
+                        endpoint,
+                        title="Endpoint accessible without valid authentication",
+                        description=(
+                            f"The endpoint returned HTTP 200 with {label}. "
+                            "Protected endpoints should reject unauthenticated requests."
+                        ),
+                        evidence=f"{endpoint.method.upper()} {url} ({label}) → {resp.status_code}",
+                        remediation=(
+                            "Ensure all protected endpoints validate authentication tokens "
+                            "and return 401 for missing or invalid credentials."
+                        ),
+                        cwe_id="CWE-306",
+                        confidence=0.7,
+                    )
+                )
+                break
+
+        return findings

mannf/product/security/checks/graphql_security.py

@@ -0,0 +1,299 @@
+# 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.
+
+"""GraphQL-specific OWASP security checks.
+
+Each check is a read-only probe that detects a common GraphQL security
+misconfiguration without making any destructive or state-mutating requests.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from mannf.product.security.checks.base import EndpointInfo, SecurityCheck
+from mannf.product.security.models import SecurityFinding
+
+_INTROSPECTION_QUERY = '{ __schema { types { name } } }'
+
+_DEPTH_QUERY = (
+    "{ a { a { a { a { a { a { a { a { a { a { id } } } } } } } } } } }"
+)
+
+_ALIAS_QUERY = (
+    "{ "
+    + " ".join(f"f{i}: __typename" for i in range(20))
+    + " }"
+)
+
+
+class GraphQLIntrospectionCheck(SecurityCheck):
+    """GRAPHQL-1: Check if introspection is enabled in production."""
+
+    owasp_id = "GRAPHQL-1"
+    name = "GraphQL Introspection Exposure"
+    description = (
+        "GraphQL introspection allows clients to query the entire schema. "
+        "Enabling it in production exposes implementation details."
+    )
+    severity_default = "medium"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        try:
+            resp = await client.post(
+                endpoint.full_url,
+                json={"query": _INTROSPECTION_QUERY},
+            )
+        except httpx.RequestError:
+            return []
+
+        try:
+            body = resp.json()
+        except Exception:
+            return []
+
+        if isinstance(body, dict) and "data" in body and body["data"]:
+            schema_data = body["data"].get("__schema")
+            if schema_data:
+                return [
+                    self._make_finding(
+                        endpoint,
+                        title="GraphQL introspection is enabled",
+                        description=(
+                            "The GraphQL endpoint responds to introspection queries, "
+                            "exposing the full schema including all types, fields, and "
+                            "queries to any client."
+                        ),
+                        evidence=(
+                            f"POST {endpoint.full_url} with introspection query "
+                            f"returned schema data (HTTP {resp.status_code})"
+                        ),
+                        remediation=(
+                            "Disable GraphQL introspection in production environments. "
+                            "Most GraphQL frameworks provide a configuration option to "
+                            "disable introspection (e.g. `introspection: false`)."
+                        ),
+                        cwe_id="CWE-200",
+                    )
+                ]
+
+        return []
+
+
+class GraphQLDepthAttackCheck(SecurityCheck):
+    """GRAPHQL-2: Test for query depth limiting."""
+
+    owasp_id = "GRAPHQL-2"
+    name = "GraphQL Query Depth Attack"
+    description = (
+        "GraphQL servers without depth limits are vulnerable to deeply nested "
+        "queries that can exhaust server resources."
+    )
+    severity_default = "high"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        try:
+            resp = await client.post(
+                endpoint.full_url,
+                json={"query": _DEPTH_QUERY},
+            )
+        except httpx.RequestError:
+            return []
+
+        # Server should reject this with 400 or return errors; 200 without
+        # errors suggests no depth limiting is in place.
+        if resp.status_code == 200:
+            try:
+                body = resp.json()
+            except Exception:
+                body = {}
+
+            if isinstance(body, dict):
+                errors = body.get("errors") or []
+                depth_rejected = any(
+                    "depth" in str(e).lower() or "complex" in str(e).lower()
+                    for e in errors
+                )
+                if not depth_rejected:
+                    return [
+                        self._make_finding(
+                            endpoint,
+                            title="GraphQL query depth limiting not enforced",
+                            description=(
+                                "The server accepted a 10-level deeply nested query "
+                                "without returning a depth-limit error. This can be "
+                                "exploited to cause excessive CPU/memory usage."
+                            ),
+                            evidence=(
+                                f"10-level nested query returned HTTP {resp.status_code} "
+                                f"without a depth-limit error"
+                            ),
+                            remediation=(
+                                "Implement query depth limiting (e.g. graphql-depth-limit). "
+                                "A maximum depth of 5–7 is recommended for most APIs."
+                            ),
+                            cwe_id="CWE-400",
+                        )
+                    ]
+
+        return []
+
+
+class GraphQLBatchQueryCheck(SecurityCheck):
+    """GRAPHQL-3: Test for batch query limiting."""
+
+    owasp_id = "GRAPHQL-3"
+    name = "GraphQL Batch Query Attack"
+    description = (
+        "GraphQL batch queries allow multiple operations in a single request. "
+        "Without limits this can be abused to amplify attack impact."
+    )
+    severity_default = "medium"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        batch = [{"query": "{ __typename }"} for _ in range(10)]
+        try:
+            resp = await client.post(endpoint.full_url, json=batch)
+        except httpx.RequestError:
+            return []
+
+        if resp.status_code == 200:
+            try:
+                body = resp.json()
+            except Exception:
+                body = None
+
+            if isinstance(body, list) and len(body) > 1:
+                return [
+                    self._make_finding(
+                        endpoint,
+                        title="GraphQL batch queries accepted without limits",
+                        description=(
+                            "The server processed a batch of 10 GraphQL operations in "
+                            "a single request without rejecting or limiting the batch size."
+                        ),
+                        evidence=(
+                            f"Batch of 10 queries returned HTTP {resp.status_code} "
+                            f"with {len(body)} results"
+                        ),
+                        remediation=(
+                            "Disable batching or enforce a maximum batch size. "
+                            "Consider using persisted queries to prevent arbitrary batching."
+                        ),
+                        cwe_id="CWE-400",
+                    )
+                ]
+
+        return []
+
+
+class GraphQLFieldSuggestionCheck(SecurityCheck):
+    """GRAPHQL-4: Check if field suggestions are exposed."""
+
+    owasp_id = "GRAPHQL-4"
+    name = "GraphQL Field Suggestion Exposure"
+    description = (
+        "Field suggestions in GraphQL error messages disclose valid field names, "
+        "aiding attackers in schema enumeration without introspection."
+    )
+    severity_default = "low"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        # Use a deliberately misspelled field name likely to trigger a suggestion
+        typo_query = "{ ussers { id } }"
+        try:
+            resp = await client.post(endpoint.full_url, json={"query": typo_query})
+        except httpx.RequestError:
+            return []
+
+        try:
+            body = resp.json()
+        except Exception:
+            body = {}
+
+        if isinstance(body, dict):
+            errors = body.get("errors") or []
+            suggestion_text = " ".join(str(e) for e in errors)
+            if "did you mean" in suggestion_text.lower():
+                return [
+                    self._make_finding(
+                        endpoint,
+                        title="GraphQL field suggestions exposed in errors",
+                        description=(
+                            "The server returns 'Did you mean ...' suggestions in error "
+                            "messages, which discloses valid field names and aids schema "
+                            "enumeration even when introspection is disabled."
+                        ),
+                        evidence=f"Error message contained suggestion text: {suggestion_text[:300]}",
+                        remediation=(
+                            "Disable field suggestions in production (e.g. set "
+                            "`suggestions: false` in your GraphQL server configuration)."
+                        ),
+                        cwe_id="CWE-209",
+                    )
+                ]
+
+        return []
+
+
+class GraphQLAliasDoSCheck(SecurityCheck):
+    """GRAPHQL-5: Test for alias-based DoS."""
+
+    owasp_id = "GRAPHQL-5"
+    name = "GraphQL Alias-Based DoS"
+    description = (
+        "Attackers can use GraphQL aliases to repeat the same expensive field "
+        "many times in a single query, multiplying server load."
+    )
+    severity_default = "medium"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        try:
+            resp = await client.post(endpoint.full_url, json={"query": _ALIAS_QUERY})
+        except httpx.RequestError:
+            return []
+
+        if resp.status_code == 200:
+            try:
+                body = resp.json()
+            except Exception:
+                body = {}
+
+            if isinstance(body, dict) and "data" in body and body["data"]:
+                # Server processed 20 aliases successfully
+                aliases_returned = len(body["data"])
+                if aliases_returned > 5:
+                    return [
+                        self._make_finding(
+                            endpoint,
+                            title="GraphQL alias-based DoS not mitigated",
+                            description=(
+                                "The server processed a query with 20 aliases of the same "
+                                "field without rejecting it. Aliases can be used to amplify "
+                                "the cost of expensive resolvers."
+                            ),
+                            evidence=(
+                                f"Query with 20 aliases returned HTTP {resp.status_code} "
+                                f"with {aliases_returned} fields in data"
+                            ),
+                            remediation=(
+                                "Implement query cost analysis or field-level rate limiting. "
+                                "Consider using a library such as graphql-query-complexity."
+                            ),
+                            cwe_id="CWE-400",
+                        )
+                    ]
+
+        return []

mannf/product/security/checks/inventory.py

@@ -0,0 +1,70 @@
+# 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.
+
+"""API9:2023 — Improper Inventory Management."""
+
+from __future__ import annotations
+
+import httpx
+
+from mannf.product.security.checks.base import EndpointInfo, SecurityCheck
+from mannf.product.security.models import SecurityFinding
+
+_SHADOW_PATHS = [
+    "/api/v1/docs",
+    "/swagger",
+    "/swagger-ui",
+    "/swagger-ui.html",
+    "/api-docs",
+    "/openapi.json",
+    "/.git/HEAD",
+    "/api/v2/",
+    "/health",
+    "/metrics",
+    "/actuator",
+    "/actuator/health",
+]
+
+
+class InventoryCheck(SecurityCheck):
+    owasp_id = "API9:2023"
+    name = "Improper Inventory Management"
+    description = "Probes for undocumented/shadow endpoints that should not be exposed."
+    severity_default = "medium"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        base = endpoint.base_url.rstrip("/")
+        findings: list[SecurityFinding] = []
+
+        for shadow_path in _SHADOW_PATHS:
+            url = f"{base}{shadow_path}"
+            try:
+                resp = await client.get(url)
+            except httpx.RequestError:
+                continue
+
+            if resp.status_code == 200:
+                findings.append(
+                    self._make_finding(
+                        endpoint,
+                        title=f"Shadow/undocumented endpoint found: {shadow_path}",
+                        description=(
+                            f"The path {shadow_path} returned HTTP 200, indicating an "
+                            "undocumented or shadow API endpoint is publicly accessible."
+                        ),
+                        evidence=f"GET {url} → {resp.status_code}",
+                        remediation=(
+                            "Remove or restrict access to undocumented endpoints, "
+                            "debug paths, and outdated API versions in production. "
+                            "Maintain an up-to-date API inventory."
+                        ),
+                        cwe_id="CWE-1059",
+                        confidence=0.9,
+                    )
+                )
+
+        return findings

mannf/product/security/checks/misconfig.py

@@ -0,0 +1,158 @@
+# 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.
+
+"""API8:2023 — Security Misconfiguration."""
+
+from __future__ import annotations
+
+import httpx
+
+from mannf.product.security.checks.base import EndpointInfo, SecurityCheck
+from mannf.product.security.models import SecurityFinding
+
+_SECURITY_HEADERS = [
+    "X-Content-Type-Options",
+    "X-Frame-Options",
+    "X-XSS-Protection",
+    "Content-Security-Policy",
+]
+_HSTS_HEADER = "Strict-Transport-Security"
+
+_DEBUG_PATHS = ["/_debug", "/debug", "/api/debug", "/.env"]
+
+_STACK_TRACE_MARKERS = [
+    "Traceback", "at line", "Exception in thread",
+    "NullPointerException", "stack trace", "at com.", "at org.",
+]
+
+
+class MisconfigCheck(SecurityCheck):
+    owasp_id = "API8:2023"
+    name = "Security Misconfiguration"
+    description = "Tests for common security misconfigurations in HTTP responses."
+    severity_default = "medium"
+
+    async def run(
+        self, endpoint: EndpointInfo, client: httpx.AsyncClient
+    ) -> list[SecurityFinding]:
+        findings: list[SecurityFinding] = []
+        method = endpoint.method.upper()
+        url = endpoint.full_url
+
+        try:
+            resp = await client.request(method, url)
+        except httpx.RequestError:
+            return []
+
+        # --- Missing security headers ---
+        resp_headers = {k.lower(): v for k, v in resp.headers.items()}
+        missing = [h for h in _SECURITY_HEADERS if h.lower() not in resp_headers]
+        if url.startswith("https://") and _HSTS_HEADER.lower() not in resp_headers:
+            missing.append(_HSTS_HEADER)
+        if missing:
+            findings.append(
+                self._make_finding(
+                    endpoint,
+                    title="Missing security response headers",
+                    description=f"The following security headers are absent: {missing}.",
+                    evidence=f"Response headers: {dict(resp.headers)}",
+                    remediation=(
+                        "Configure the server/framework to include all recommended "
+                        "security headers on every response."
+                    ),
+                    cwe_id="CWE-16",
+                    severity="low",
+                    confidence=0.9,
+                )
+            )
+
+        # --- Overly permissive CORS ---
+        evil_origin = "https://evil.example.com"
+        try:
+            cors_resp = await client.request(
+                method, url, headers={"Origin": evil_origin}
+            )
+            acao = cors_resp.headers.get("Access-Control-Allow-Origin", "")
+            if acao == evil_origin or acao == "*":
+                findings.append(
+                    self._make_finding(
+                        endpoint,
+                        title="Overly permissive CORS policy",
+                        description=(
+                            "The server echoes back an arbitrary Origin or uses wildcard "
+                            f"'*' in Access-Control-Allow-Origin (got: '{acao}')."
+                        ),
+                        evidence=(
+                            f"Request Origin: {evil_origin}; "
+                            f"Response Access-Control-Allow-Origin: {acao}"
+                        ),
+                        remediation=(
+                            "Restrict Access-Control-Allow-Origin to a known allowlist "
+                            "of trusted origins. Never reflect arbitrary Origin values."
+                        ),
+                        cwe_id="CWE-942",
+                        severity="medium",
+                        confidence=0.9,
+                    )
+                )
+        except httpx.RequestError:
+            pass
+
+        # --- Verbose error / stack trace exposure ---
+        try:
+            malformed_url = url + "/%00invalid%00"
+            err_resp = await client.request(method, malformed_url)
+            body = err_resp.text
+            exposed = [m for m in _STACK_TRACE_MARKERS if m in body]
+            if exposed:
+                findings.append(
+                    self._make_finding(
+                        endpoint,
+                        title="Verbose error / stack trace exposed in response",
+                        description=(
+                            "The server returned a response containing stack-trace markers "
+                            f"({exposed}), which may disclose internal implementation details."
+                        ),
+                        evidence=f"Markers found: {exposed}; snippet: {body[:300]}",
+                        remediation=(
+                            "Configure error handling to return generic error messages in "
+                            "production. Log stack traces server-side only."
+                        ),
+                        cwe_id="CWE-209",
+                        severity="medium",
+                        confidence=0.8,
+                    )
+                )
+        except httpx.RequestError:
+            pass
+
+        # --- Debug endpoints ---
+        base = endpoint.base_url.rstrip("/")
+        for debug_path in _DEBUG_PATHS:
+            try:
+                d_resp = await client.get(f"{base}{debug_path}")
+                if d_resp.status_code == 200:
+                    findings.append(
+                        self._make_finding(
+                            endpoint,
+                            title=f"Debug endpoint accessible: {debug_path}",
+                            description=(
+                                f"The path {debug_path} returned HTTP 200, "
+                                "suggesting a debug or configuration endpoint is exposed."
+                            ),
+                            evidence=f"GET {base}{debug_path} → {d_resp.status_code}",
+                            remediation=(
+                                "Disable or restrict access to debug and internal endpoints "
+                                "in production environments."
+                            ),
+                            cwe_id="CWE-215",
+                            severity="high",
+                            confidence=0.8,
+                        )
+                    )
+            except httpx.RequestError:
+                continue
+
+        return findings