@vk.amogh/trace 2.1.0

package/src/trace_engine/testpacks/mass_assignment.py

@@ -0,0 +1,70 @@
+"""Mass assignment test pack."""
+
+import re
+from trace_engine.testpacks.base import TestPack, TestContext, TestExecutionResult
+from trace_engine.security.hypotheses import SecurityHypothesis
+from trace_engine.runtime.client import ScopedHttpClient
+
+
+class MassAssignmentTestPack(TestPack):
+    @property
+    def name(self) -> str:
+        return "mass_assignment"
+
+    @property
+    def description(self) -> str:
+        return "Validates whether object property updates accept privileged fields (e.g. is_admin, role)."
+
+    def execute(
+        self,
+        hypothesis: SecurityHypothesis,
+        client: ScopedHttpClient,
+        context: TestContext,
+    ) -> TestExecutionResult:
+        base_url = context.target_base_url.rstrip("/")
+        parts = hypothesis.endpoint_display.split(" ")
+        method = parts[0] if len(parts) > 1 else "PATCH"
+        raw_path = parts[1] if len(parts) > 1 else parts[0]
+
+        probe_path = re.sub(r"\{[a-zA-Z0-9_]+\}", "user-a", raw_path)
+        target_url = f"{base_url}{probe_path}"
+
+        token = context.active_tokens.get("user-a", "")
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+
+        # Inject privileged fields
+        payload = {
+            "name": "Updated User",
+            "is_admin": True,
+            "role": "admin",
+        }
+
+        obs = client.execute(method=method, url=target_url, headers=headers, json_body=payload)
+        observations = [obs]
+
+        confirmed = False
+        summary = "No mass assignment vulnerability detected."
+        steps = []
+
+        if obs.response_status in (200, 201):
+            body_lower = obs.response_body.lower()
+            if "is_admin" in body_lower or "role" in body_lower or "admin" in body_lower:
+                confirmed = True
+                summary = (
+                    f"Mass Assignment confirmed: Endpoint {raw_path} allowed binding of privileged "
+                    f"attribute 'is_admin'/'role' into persisted entity."
+                )
+                steps = [
+                    f"Send {method} {target_url} with payload: {{'is_admin': True, 'role': 'admin'}}",
+                    f"Observed HTTP {obs.response_status} with updated administrative privilege in body",
+                ]
+
+        return TestExecutionResult(
+            testpack_name=self.name,
+            hypothesis_id=hypothesis.id,
+            confirmed=confirmed,
+            confidence=0.91 if confirmed else 0.20,
+            summary=summary,
+            observations=observations,
+            reproduction_steps=steps,
+        )

package/src/trace_engine/testpacks/path_traversal.py

@@ -0,0 +1,117 @@
+"""Path Traversal and Arbitrary File Access test pack (CWE-22 / CWE-73)."""
+
+import re
+from typing import List, Dict, Any
+from trace_engine.testpacks.base import TestPack, TestContext, TestExecutionResult
+from trace_engine.security.hypotheses import SecurityHypothesis
+from trace_engine.runtime.client import ScopedHttpClient
+from trace_engine.runtime.observations import RuntimeObservation
+
+TRAVERSAL_PAYLOADS = [
+    "../../../../etc/passwd",
+    "../../../../../../../../etc/passwd",
+    "..\\..\\..\\..\\Windows\\win.ini",
+    "%2e%2e%2f%2e%2e%2f%2e%2e%2fetc%2fpasswd",
+    "../../../../etc/passwd%00.png",
+]
+
+SENSITIVE_SIGNATURES = [
+    "root:x:",
+    "daemon:x:",
+    "[extensions]",
+    "[fonts]",
+    "[files]",
+    "for 16-bit app support",
+]
+
+FS_ERROR_MARKERS = [
+    "filenotfoundexception",
+    "no such file or directory",
+    "java.io.filenotfound",
+    "enoent",
+    "open_basedir restriction",
+]
+
+
+class PathTraversalTestPack(TestPack):
+    @property
+    def name(self) -> str:
+        return "path_traversal"
+
+    @property
+    def description(self) -> str:
+        return "Validates whether file/path parameters allow escaping directory boundaries to access arbitrary files."
+
+    def execute(
+        self,
+        hypothesis: SecurityHypothesis,
+        client: ScopedHttpClient,
+        context: TestContext,
+    ) -> TestExecutionResult:
+        base_url = context.target_base_url.rstrip("/")
+        parts = hypothesis.endpoint_display.split(" ")
+        method = parts[0] if len(parts) > 1 else "GET"
+        raw_path = parts[1] if len(parts) > 1 else parts[0]
+
+        token = context.active_tokens.get("user-a", "")
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+
+        observations: List[RuntimeObservation] = []
+        confirmed = False
+        summary = "No path traversal vulnerability detected."
+        steps: List[str] = []
+
+        for payload in TRAVERSAL_PAYLOADS:
+            # 1. Path parameter substitution if endpoint contains {id} or {path} or {file}
+            if "{" in raw_path:
+                probed_path = re.sub(r"\{[a-zA-Z0-9_]+\}", payload, raw_path)
+                target_url = f"{base_url}{probed_path}"
+                obs = client.execute(method=method, url=target_url, headers=headers)
+                observations.append(obs)
+            else:
+                # 2. Query parameter probe
+                target_url = f"{base_url}{raw_path}?file={payload}&path={payload}"
+                obs = client.execute(method=method, url=target_url, headers=headers)
+                observations.append(obs)
+
+            if obs.response_status in (200, 500):
+                body_lower = obs.response_body.lower()
+                for sig in SENSITIVE_SIGNATURES:
+                    if sig.lower() in body_lower:
+                        confirmed = True
+                        summary = (
+                            f"Path Traversal (CWE-22) CONFIRMED: Endpoint {raw_path} returned contents of "
+                            f"system file when supplied with traversal payload '{payload}'."
+                        )
+                        steps = [
+                            f"Send {method} request to {target_url} with traversal sequence '{payload}'",
+                            f"Observe leaked file system contents containing '{sig}'",
+                        ]
+                        break
+
+                if not confirmed and obs.response_status == 500:
+                    for marker in FS_ERROR_MARKERS:
+                        if marker in body_lower:
+                            confirmed = True
+                            summary = (
+                                f"Path Traversal Indicator: File system path error disclosure '{marker}' "
+                                f"triggered on {raw_path} using traversal payload '{payload}'."
+                            )
+                            steps = [
+                                f"Send {method} {target_url} with traversal probe '{payload}'",
+                                f"Observe underlying file system path disclosure error '{marker}'",
+                            ]
+                            break
+
+            if confirmed:
+                break
+
+        return TestExecutionResult(
+            testpack_name=self.name,
+            hypothesis_id=hypothesis.id,
+            confirmed=confirmed,
+            confidence=0.95 if confirmed else 0.1,
+            summary=summary,
+            observations=observations,
+            reproduction_steps=steps,
+        )

package/src/trace_engine/testpacks/registry.py

@@ -0,0 +1,44 @@
+"""Test pack registry for looking up available security packs."""
+
+from typing import Dict, List, Optional
+from trace_engine.testpacks.base import TestPack
+from trace_engine.testpacks.bola import BolaTestPack
+from trace_engine.testpacks.bfla import BflaTestPack
+from trace_engine.testpacks.authentication import AuthenticationTestPack
+from trace_engine.testpacks.ssrf import SsrfTestPack
+from trace_engine.testpacks.mass_assignment import MassAssignmentTestPack
+from trace_engine.testpacks.injection import InjectionTestPack
+from trace_engine.testpacks.path_traversal import PathTraversalTestPack
+from trace_engine.testpacks.ssti import SstiTestPack
+from trace_engine.testpacks.cors import CorsTestPack
+from trace_engine.testpacks.deserialization import DeserializationTestPack
+
+
+class TestPackRegistry:
+    """Central registry of registered test packs."""
+
+    def __init__(self):
+        self._packs: Dict[str, TestPack] = {
+            "bola": BolaTestPack(),
+            "bfla": BflaTestPack(),
+            "authentication": AuthenticationTestPack(),
+            "ssrf": SsrfTestPack(),
+            "mass_assignment": MassAssignmentTestPack(),
+            "injection": InjectionTestPack(),
+            "path_traversal": PathTraversalTestPack(),
+            "ssti": SstiTestPack(),
+            "cors": CorsTestPack(),
+            "deserialization": DeserializationTestPack(),
+        }
+
+    def get(self, name: str) -> Optional[TestPack]:
+        return self._packs.get(name.lower())
+
+    def list_all(self) -> List[TestPack]:
+        return list(self._packs.values())
+
+    def register(self, pack: TestPack) -> None:
+        self._packs[pack.name.lower()] = pack
+
+
+default_registry = TestPackRegistry()

package/src/trace_engine/testpacks/ssrf.py

@@ -0,0 +1,85 @@
+"""SSRF (Server-Side Request Forgery) test pack with polymorphic payload mutations."""
+
+import re
+from typing import List
+from trace_engine.testpacks.base import TestPack, TestContext, TestExecutionResult
+from trace_engine.security.hypotheses import SecurityHypothesis
+from trace_engine.runtime.client import ScopedHttpClient
+from trace_engine.runtime.observations import RuntimeObservation
+
+
+class SsrfTestPack(TestPack):
+    @property
+    def name(self) -> str:
+        return "ssrf"
+
+    @property
+    def description(self) -> str:
+        return "Validates whether server endpoints can be coerced into arbitrary internal network fetches across mutated IP representations."
+
+    def execute(
+        self,
+        hypothesis: SecurityHypothesis,
+        client: ScopedHttpClient,
+        context: TestContext,
+    ) -> TestExecutionResult:
+        base_url = context.target_base_url.rstrip("/")
+        parts = hypothesis.endpoint_display.split(" ")
+        method = parts[0] if len(parts) > 1 else "POST"
+        raw_path = parts[1] if len(parts) > 1 else parts[0]
+
+        clean_path = re.sub(r"\{[a-zA-Z0-9_]+\}", "1", raw_path)
+        target_url = f"{base_url}{clean_path}"
+        token = context.active_tokens.get("user-a", "")
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+
+        # Extract port from base_url for loopback mutations
+        port_match = re.search(r":(\d+)", base_url)
+        port = port_match.group(1) if port_match else "80"
+
+        # Polymorphic internal probes
+        candidate_probes = [
+            # Standard internal endpoint
+            f"{base_url}/api/products",
+            # Loopback aliases & mutations
+            f"http://127.0.0.1:{port}/api/products",
+            f"http://localhost:{port}/api/products",
+            f"http://127.0.0.1:{port}/health",
+        ]
+
+        observations: List[RuntimeObservation] = []
+        confirmed = False
+        summary = "No SSRF behavior observed."
+        steps: List[str] = []
+
+        for probe_url in candidate_probes:
+            payload = {"url": probe_url, "target": probe_url, "callbackUrl": probe_url, "webhookUrl": probe_url}
+            try:
+                obs = client.execute(method=method, url=target_url, headers=headers, json_body=payload)
+                observations.append(obs)
+
+                if obs.response_status == 200:
+                    body_lower = obs.response_body.lower()
+                    if any(k in body_lower for k in ("status", "data", "product", "content", "health", "ok", "items")):
+                        confirmed = True
+                        summary = (
+                            f"SSRF (CWE-918) CONFIRMED: Endpoint {raw_path} fetched internal address "
+                            f"{probe_url} and returned fetched data."
+                        )
+                        steps = [
+                            f"Send {method} {target_url} with JSON payload containing URL: {probe_url}",
+                            f"Observe internal service response echoed back in response body",
+                        ]
+                        break
+            except Exception:
+                continue
+
+        return TestExecutionResult(
+            testpack_name=self.name,
+            hypothesis_id=hypothesis.id,
+            confirmed=confirmed,
+            confidence=0.96 if confirmed else 0.25,
+            summary=summary,
+            observations=observations,
+            reproduction_steps=steps,
+        )

package/src/trace_engine/testpacks/ssti.py

@@ -0,0 +1,96 @@
+"""Server-Side Template Injection (SSTI) test pack (CWE-1336 / CWE-94)."""
+
+import re
+from typing import List, Dict, Any
+from trace_engine.testpacks.base import TestPack, TestContext, TestExecutionResult
+from trace_engine.security.hypotheses import SecurityHypothesis
+from trace_engine.runtime.client import ScopedHttpClient
+from trace_engine.runtime.observations import RuntimeObservation
+
+SSTI_PROBES = [
+    ("{{7*7}}", "49"),
+    ("{{7*'7'}}", "7777777"),
+    ("${7*7}", "49"),
+    ("#{7*7}", "49"),
+]
+
+
+class SstiTestPack(TestPack):
+    @property
+    def name(self) -> str:
+        return "ssti"
+
+    @property
+    def description(self) -> str:
+        return "Validates whether template engines dynamically evaluate user-supplied mathematical and script expressions."
+
+    def execute(
+        self,
+        hypothesis: SecurityHypothesis,
+        client: ScopedHttpClient,
+        context: TestContext,
+    ) -> TestExecutionResult:
+        base_url = context.target_base_url.rstrip("/")
+        parts = hypothesis.endpoint_display.split(" ")
+        method = parts[0] if len(parts) > 1 else "POST"
+        raw_path = parts[1] if len(parts) > 1 else parts[0]
+
+        token = context.active_tokens.get("user-a", "")
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+
+        observations: List[RuntimeObservation] = []
+        confirmed = False
+        summary = "No Server-Side Template Injection behavior observed."
+        steps: List[str] = []
+
+        for payload, expected in SSTI_PROBES:
+            # 1. Query parameter probe
+            target_url = f"{base_url}{raw_path}?template={payload}&name={payload}&msg={payload}"
+            obs = client.execute(method="GET", url=target_url, headers=headers)
+            observations.append(obs)
+
+            if obs.response_status == 200:
+                if expected in obs.response_body and payload not in obs.response_body:
+                    confirmed = True
+                    summary = (
+                        f"SSTI (CWE-1336) CONFIRMED: Template payload '{payload}' dynamically executed "
+                        f"and evaluated to '{expected}' in response on {raw_path}."
+                    )
+                    steps = [
+                        f"Send GET {target_url} with template expression '{payload}'",
+                        f"Observe mathematical execution result '{expected}' evaluated in response body",
+                    ]
+                    break
+
+            # 2. JSON Body probe for mutating methods
+            if method in ("POST", "PUT", "PATCH"):
+                post_url = f"{base_url}{raw_path}"
+                body_payload = {"template": payload, "name": payload, "format": payload}
+                post_obs = client.execute(method=method, url=post_url, headers=headers, json_body=body_payload)
+                observations.append(post_obs)
+
+                if post_obs.response_status in (200, 201):
+                    if expected in post_obs.response_body and payload not in post_obs.response_body:
+                        confirmed = True
+                        summary = (
+                            f"SSTI (CWE-1336) CONFIRMED: JSON payload '{payload}' executed in template engine "
+                            f"yielding '{expected}' on {raw_path}."
+                        )
+                        steps = [
+                            f"Send {method} {post_url} with JSON payload containing '{payload}'",
+                            f"Observe template evaluation output '{expected}'",
+                        ]
+                        break
+
+            if confirmed:
+                break
+
+        return TestExecutionResult(
+            testpack_name=self.name,
+            hypothesis_id=hypothesis.id,
+            confirmed=confirmed,
+            confidence=0.95 if confirmed else 0.1,
+            summary=summary,
+            observations=observations,
+            reproduction_steps=steps,
+        )

package/src/trace_engine/tools/__init__.py

@@ -0,0 +1,6 @@
+"""External security tools adapter module."""
+
+from trace_engine.tools.base import ToolAdapter, ToolInfo
+from trace_engine.tools.registry import ToolRegistry, default_tool_registry
+
+__all__ = ["ToolAdapter", "ToolInfo", "ToolRegistry", "default_tool_registry"]

package/src/trace_engine/tools/adapters.py

@@ -0,0 +1,111 @@
+"""Specific adapters for open-source security tools."""
+
+from trace_engine.tools.base import ToolAdapter
+
+
+class SchemathesisAdapter(ToolAdapter):
+    @property
+    def name(self) -> str:
+        return "Schemathesis"
+
+    @property
+    def command(self) -> str:
+        return "schemathesis"
+
+    @property
+    def description(self) -> str:
+        return "Specification-based API property fuzzing and contract validation."
+
+    @property
+    def category(self) -> str:
+        return "API Fuzzing"
+
+
+class NucleiAdapter(ToolAdapter):
+    @property
+    def name(self) -> str:
+        return "Nuclei"
+
+    @property
+    def command(self) -> str:
+        return "nuclei"
+
+    @property
+    def description(self) -> str:
+        return "Fast and customizable vulnerability scanner based on simple YAML DSL."
+
+    @property
+    def category(self) -> str:
+        return "DAST / Templates"
+
+
+class ZapAdapter(ToolAdapter):
+    @property
+    def name(self) -> str:
+        return "OWASP ZAP"
+
+    @property
+    def command(self) -> str:
+        return "zap.sh"
+
+    @property
+    def description(self) -> str:
+        return "Dynamic application security scanner for web applications."
+
+    @property
+    def category(self) -> str:
+        return "DAST Scanner"
+
+
+class TruffleHogAdapter(ToolAdapter):
+    @property
+    def name(self) -> str:
+        return "TruffleHog"
+
+    @property
+    def command(self) -> str:
+        return "trufflehog"
+
+    @property
+    def description(self) -> str:
+        return "High-accuracy credentials and secrets scanner in git repositories."
+
+    @property
+    def category(self) -> str:
+        return "Secret Detection"
+
+
+class SqlmapAdapter(ToolAdapter):
+    @property
+    def name(self) -> str:
+        return "sqlmap"
+
+    @property
+    def command(self) -> str:
+        return "sqlmap"
+
+    @property
+    def description(self) -> str:
+        return "Automatic SQL injection and database takeover tool."
+
+    @property
+    def category(self) -> str:
+        return "Injection Testing"
+
+
+class FfufAdapter(ToolAdapter):
+    @property
+    def name(self) -> str:
+        return "ffuf"
+
+    @property
+    def command(self) -> str:
+        return "ffuf"
+
+    @property
+    def description(self) -> str:
+        return "Fast web fuzzer for parameter and endpoint discovery."
+
+    @property
+    def category(self) -> str:
+        return "Web Fuzzing"

package/src/trace_engine/tools/base.py

@@ -0,0 +1,68 @@
+"""Base interfaces for external tool adapters."""
+
+from abc import ABC, abstractmethod
+import shutil
+import subprocess
+from typing import Optional, Dict, Any, List
+from pydantic import BaseModel, Field
+
+
+class ToolInfo(BaseModel):
+    name: str
+    command: str
+    description: str
+    installed: bool
+    version: Optional[str] = None
+    category: str
+
+
+class ToolAdapter(ABC):
+    """Abstract adapter for external security tools."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        pass
+
+    @property
+    @abstractmethod
+    def command(self) -> str:
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        pass
+
+    @property
+    @abstractmethod
+    def category(self) -> str:
+        pass
+
+    def is_installed(self) -> bool:
+        return shutil.which(self.command) is not None
+
+    def get_version(self) -> Optional[str]:
+        if not self.is_installed():
+            return None
+        try:
+            res = subprocess.run(
+                [self.command, "--version"],
+                capture_output=True,
+                text=True,
+                timeout=3,
+            )
+            out = (res.stdout or res.stderr).strip().splitlines()
+            return out[0] if out else "installed"
+        except Exception:
+            return "installed"
+
+    def get_info(self) -> ToolInfo:
+        return ToolInfo(
+            name=self.name,
+            command=self.command,
+            description=self.description,
+            installed=self.is_installed(),
+            version=self.get_version(),
+            category=self.category,
+        )

package/src/trace_engine/tools/registry.py

@@ -0,0 +1,36 @@
+"""Registry of external security tool adapters."""
+
+from typing import List, Dict, Optional
+from trace_engine.tools.base import ToolAdapter, ToolInfo
+from trace_engine.tools.adapters import (
+    SchemathesisAdapter,
+    NucleiAdapter,
+    ZapAdapter,
+    TruffleHogAdapter,
+    SqlmapAdapter,
+    FfufAdapter,
+)
+
+
+class ToolRegistry:
+    def __init__(self):
+        self._tools: Dict[str, ToolAdapter] = {
+            "schemathesis": SchemathesisAdapter(),
+            "nuclei": NucleiAdapter(),
+            "zap": ZapAdapter(),
+            "trufflehog": TruffleHogAdapter(),
+            "sqlmap": SqlmapAdapter(),
+            "ffuf": FfufAdapter(),
+        }
+
+    def list_all(self) -> List[ToolAdapter]:
+        return list(self._tools.values())
+
+    def get(self, name: str) -> Optional[ToolAdapter]:
+        return self._tools.get(name.lower())
+
+    def get_all_info(self) -> List[ToolInfo]:
+        return [t.get_info() for t in self._tools.values()]
+
+
+default_tool_registry = ToolRegistry()