trace-sec 0.0.0-stage → 2.1.1

package/src/trace_engine/framework/springboot.py

@@ -0,0 +1,145 @@
+"""Spring Boot Java and Kotlin framework adapter."""
+
+import re
+from typing import List, Dict, Optional
+from trace_engine.parsing.parser import ParsedFile
+from trace_engine.framework.base import FrameworkAdapter, Endpoint, EndpointParameter
+from trace_engine.parsing.locations import SourceLocation
+
+
+class SpringBootFrameworkAdapter(FrameworkAdapter):
+    """Detects and extracts Spring Boot REST endpoints, annotations, and security policies."""
+
+    def can_handle(self, parsed_file: ParsedFile) -> bool:
+        if parsed_file.language not in ("java", "kotlin"):
+            return False
+
+        # Check imports
+        for imp in parsed_file.imports:
+            mod_low = imp.module.lower()
+            if any(term in mod_low for term in ("org.springframework", "io.ktor", "javax.ws.rs", "jakarta.ws.rs")):
+                return True
+
+        return True
+
+    def extract_endpoints(self, parsed_file: ParsedFile, content: str) -> List[Endpoint]:
+        endpoints: List[Endpoint] = []
+        norm_file_path = parsed_file.file_path.replace("\\", "/")
+        content_lower = content.lower()
+
+        # Database sinks
+        has_db_sink = any(
+            term in content_lower
+            for term in (
+                "repository", "findbyid", "findall", "save(", "deletebyid",
+                "jdbctemplate", "entitymanager", "hibernate", "jpa", "r2dbc",
+                "select ", "from "
+            )
+        )
+
+        # External network sinks
+        has_ext_sink = any(
+            term in content_lower
+            for term in (
+                "resttemplate", "webclient", "httpclient", "feignclient",
+                "openfeign", "okhttp", "httpurlconnection"
+            )
+        )
+
+        # Class-level RequestMapping
+        class_base = ""
+        class_rm = re.search(
+            r'''@RequestMapping\s*\(\s*(?:value\s*=\s*)?["']([^"']+)["']''',
+            content
+        )
+        if class_rm:
+            class_base = "/" + class_rm.group(1).strip("/")
+
+        # Method-level mappings: @GetMapping, @PostMapping, etc.
+        annot_pat = re.compile(
+            r'''@(GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping|RequestMapping)\s*(?:\(\s*(?:(?:value|path)\s*=\s*)?["']([^"']+)["']\s*\))?''',
+            re.IGNORECASE
+        )
+
+        verbs = {
+            "getmapping": "GET",
+            "postmapping": "POST",
+            "putmapping": "PUT",
+            "deletemapping": "DELETE",
+            "patchmapping": "PATCH",
+            "requestmapping": "GET",
+        }
+
+        for match in annot_pat.finditer(content):
+            annot = match.group(1).lower()
+            sub_path = match.group(2) or ""
+
+            # Skip class-level RequestMapping
+            after_snippet = content[match.end():match.end() + 100]
+            if re.search(r'\bclass\s+[a-zA-Z0-9_$]+', after_snippet):
+                continue
+
+            method = verbs.get(annot, "GET")
+            line_no = content[:match.start()].count("\n") + 1
+
+            # Extract method name and parameters following the annotation
+            after_annot = content[match.end():match.end() + 500]
+            fn_match = re.search(
+                r'''(?:fun\s+|[a-zA-Z0-9_<>,?\[\]\s]+\s+)([a-zA-Z0-9_$]+)\s*\((.*?)\)''',
+                after_annot,
+                re.DOTALL
+            )
+            fn_name = fn_match.group(1) if fn_match else f"handler_L{line_no}"
+            raw_params = fn_match.group(2) if fn_match else ""
+
+            full_path = (class_base + "/" + sub_path.strip("/")).rstrip("/")
+            if not full_path:
+                full_path = "/"
+
+            path_params = re.findall(r'\{([a-zA-Z0-9_]+)\}', full_path)
+
+            # Parameters extraction from method signature
+            parameters: List[EndpointParameter] = [
+                EndpointParameter(name=p, location="path", required=True) for p in path_params
+            ]
+
+            # Query params: @RequestParam("...")
+            for qm in re.finditer(r'''@RequestParam\s*(?:\(\s*(?:value\s*=\s*)?["']([^"']+)["']\s*\))?''', raw_params):
+                p_name = qm.group(1) or "query"
+                if not any(p.name == p_name for p in parameters):
+                    parameters.append(EndpointParameter(name=p_name, location="query", required=False))
+
+            # Auth detection
+            snippet = content[max(0, match.start() - 200) : match.end() + 200].lower()
+            auth_required = any(
+                term in snippet for term in ("preauthorize", "secured", "rolesallowed", "securitycontext", "authentication")
+            ) or ("admin" in full_path.lower())
+
+            roles = ["admin"] if "admin" in snippet or "admin" in full_path.lower() else []
+
+            sensitive = any(
+                term in full_path.lower() or term in content_lower
+                for term in ("admin", "user", "auth", "patient", "order", "billing", "payment", "token", "secret", "record")
+            )
+
+            ep_id = f"ep_jvm_{norm_file_path}_{line_no}_{method}".replace("/", "_").replace(".", "_")
+
+            endpoints.append(
+                Endpoint(
+                    id=ep_id,
+                    method=method,
+                    path=full_path,
+                    handler_name=fn_name,
+                    auth_required=auth_required,
+                    roles=roles,
+                    parameters=parameters,
+                    database_access=has_db_sink,
+                    object_identifier=bool(path_params),
+                    state_changing=method in ("POST", "PUT", "DELETE", "PATCH"),
+                    external_network=has_ext_sink,
+                    sensitive_data=sensitive,
+                    source=SourceLocation(file=parsed_file.file_path, line_start=line_no, line_end=line_no),
+                )
+            )
+
+        return endpoints

package/src/trace_engine/harness/__init__.py

@@ -0,0 +1,19 @@
+"""TRACE Agent Harness package for autonomous security auditing, benchmarking, and self-healing."""
+
+from trace_engine.harness.context import (
+    AgentRemediationPackage,
+    PatchResult,
+    HarnessExecutionReport,
+)
+from trace_engine.harness.patcher import SafePatcher
+from trace_engine.harness.remediators import AutonomousRemediator
+from trace_engine.harness.engine import AgentHarness
+
+__all__ = [
+    "AgentHarness",
+    "AgentRemediationPackage",
+    "PatchResult",
+    "HarnessExecutionReport",
+    "SafePatcher",
+    "AutonomousRemediator",
+]

package/src/trace_engine/harness/benchmark.py

@@ -0,0 +1,55 @@
+"""TRACE-Bench: Standardized Autonomous Cybersecurity Evaluation Harness for AI Coding Models."""
+
+import time
+from pathlib import Path
+from typing import Dict, Any, List, Optional
+from pydantic import BaseModel, Field
+
+from trace_engine.harness.engine import AgentHarness
+from trace_engine.harness.context import HarnessExecutionReport
+
+
+class BenchmarkScorecard(BaseModel):
+    """Standardized AI model benchmark scorecard generated by TRACE-Bench."""
+    benchmark_name: str = "TRACE-Bench v1.0"
+    model_name: str
+    target_repository: str
+    baseline_posture_score: int
+    final_posture_score: int
+    score_delta: int
+    total_security_exploits: int
+    exploits_remediated: int
+    remediation_success_rate: float
+    time_elapsed_seconds: float
+    pass_criteria_met: bool
+    findings_audit: List[Dict[str, Any]] = Field(default_factory=list)
+
+
+class TRACEBench:
+    """Evaluation harness for testing and grading AI coding agents on OWASP API security remediations."""
+
+    def __init__(self, repo_path: Path, target_url: str = "http://127.0.0.1:18080"):
+        self.repo_path = repo_path.resolve()
+        self.target_url = target_url
+        self.harness = AgentHarness(self.repo_path, target_url=self.target_url)
+
+    def evaluate(self, model_name: str = "Autonomous Agent") -> BenchmarkScorecard:
+        """Executes full benchmark evaluation run."""
+        report: HarnessExecutionReport = self.harness.run_self_healing_loop()
+
+        pass_threshold = 70.0  # 70% fix rate required to pass
+        passed = report.fix_rate_percent >= pass_threshold and report.final_score >= 80
+
+        return BenchmarkScorecard(
+            model_name=model_name,
+            target_repository=self.repo_path.name,
+            baseline_posture_score=report.baseline_score,
+            final_posture_score=report.final_score,
+            score_delta=report.score_delta,
+            total_security_exploits=report.total_findings,
+            exploits_remediated=report.fixed_findings,
+            remediation_success_rate=report.fix_rate_percent,
+            time_elapsed_seconds=report.execution_time_seconds,
+            pass_criteria_met=passed,
+            findings_audit=report.verified_patches,
+        )

package/src/trace_engine/harness/context.py

@@ -0,0 +1,49 @@
+"""Agent remediation context and task models for the TRACE Agent Harness."""
+
+from typing import List, Dict, Any, Optional
+from pydantic import BaseModel, Field
+
+
+class AgentRemediationPackage(BaseModel):
+    """Self-contained remediation context payload delivered to an autonomous coding agent."""
+    finding_id: str
+    title: str
+    category: str
+    severity: str
+    priority_rank: int
+    endpoint: str
+    source_file: str
+    line_start: int
+    line_end: int
+    code_snippet: str
+    attack_path_hops: List[str] = Field(default_factory=list)
+    runtime_exploit_proof: List[str] = Field(default_factory=list)
+    remediation_guidance: str
+    reproduction_steps: List[str] = Field(default_factory=list)
+    verification_criteria: str
+    raw_observation: Optional[Dict[str, Any]] = None
+
+
+class PatchResult(BaseModel):
+    """Result of applying a code modification via the Agent Harness."""
+    finding_id: str
+    target_file: str
+    success: bool
+    backup_file: Optional[str] = None
+    diff: Optional[str] = None
+    error: Optional[str] = None
+
+
+class HarnessExecutionReport(BaseModel):
+    """Outcome of a complete Agent Harness remediation or benchmark run."""
+    project_name: str
+    baseline_score: int
+    final_score: int
+    score_delta: int
+    total_findings: int
+    fixed_findings: int
+    remaining_findings: int
+    fix_rate_percent: float
+    verified_patches: List[Dict[str, Any]] = Field(default_factory=list)
+    unresolved_findings: List[str] = Field(default_factory=list)
+    execution_time_seconds: float

package/src/trace_engine/harness/engine.py

@@ -0,0 +1,187 @@
+"""Core Agent Harness execution engine for autonomous security auditing and self-healing."""
+
+import time
+from pathlib import Path
+from typing import List, Dict, Any, Optional, Tuple
+
+from trace_engine.findings.model import Finding, Severity
+from trace_engine.findings.store import FindingStore
+from trace_engine.verify import VerificationEngine, VerificationResult, VerificationStatus
+from trace_engine.harness.context import (
+    AgentRemediationPackage,
+    PatchResult,
+    HarnessExecutionReport,
+)
+from trace_engine.harness.patcher import SafePatcher
+from trace_engine.harness.remediators import AutonomousRemediator
+
+
+class AgentHarness:
+    """The TRACE Agent Harness provides an autonomous execution and verification environment
+
+    for AI coding models to inspect, patch, and mathematically prove security remediations.
+    """
+
+    def __init__(self, repo_path: Path, target_url: str = "http://127.0.0.1:18080"):
+        self.repo_path = repo_path.resolve()
+        self.target_url = target_url
+        self.trace_dir = self.repo_path / ".trace"
+        self.store = FindingStore(self.trace_dir)
+        self.patcher = SafePatcher(self.repo_path)
+        self.verifier = VerificationEngine(self.repo_path, target_url=target_url)
+
+    def get_findings(self) -> List[Finding]:
+        """Load currently stored findings ordered strictly by priority."""
+        raw_findings = self.store.load_findings()
+        severity_order = {
+            Severity.CRITICAL: 0,
+            Severity.HIGH: 1,
+            Severity.MEDIUM: 2,
+            Severity.LOW: 3,
+            Severity.INFO: 4,
+        }
+        return sorted(raw_findings, key=lambda f: severity_order.get(f.severity, 5))
+
+    def calculate_posture_score(self, findings: List[Finding]) -> int:
+        """Calculates 0-100 security health posture score."""
+        crit = sum(1 for f in findings if f.severity == Severity.CRITICAL)
+        high = sum(1 for f in findings if f.severity == Severity.HIGH)
+        med = sum(1 for f in findings if f.severity == Severity.MEDIUM)
+        return max(0, 100 - (crit * 20 + high * 10 + med * 3))
+
+    def build_remediation_package(self, finding: Finding, rank: int = 1) -> AgentRemediationPackage:
+        """Packages rich context, surrounding AST lines, and exploit proof for an AI agent."""
+        file_path = self.repo_path / finding.source_location.file
+        if not file_path.exists():
+            for sub in self.repo_path.iterdir():
+                if sub.is_dir() and (sub / finding.source_location.file).exists():
+                    file_path = sub / finding.source_location.file
+                    break
+
+        code_snippet = ""
+        if file_path.exists():
+            lines = file_path.read_text(encoding="utf-8", errors="replace").splitlines()
+            start = max(0, finding.source_location.line_start - 5)
+            end = min(len(lines), finding.source_location.line_end + 10)
+            code_snippet = "\n".join(lines[start:end])
+
+        return AgentRemediationPackage(
+            finding_id=finding.id,
+            title=finding.title,
+            category=finding.category,
+            severity=finding.severity.value,
+            priority_rank=rank,
+            endpoint=finding.endpoint,
+            source_file=finding.source_location.file,
+            line_start=finding.source_location.line_start,
+            line_end=finding.source_location.line_end,
+            code_snippet=code_snippet,
+            attack_path_hops=finding.attack_path,
+            runtime_exploit_proof=finding.runtime_evidence,
+            remediation_guidance=finding.remediation,
+            reproduction_steps=finding.reproduction_steps,
+            verification_criteria=(
+                f"Neutralize exploit so re-executing {finding.endpoint} receives HTTP 401/403 "
+                "or validates tenant/object authorization boundaries."
+            ),
+        )
+
+    def get_next_target(self) -> Optional[AgentRemediationPackage]:
+        """Returns the highest priority unmitigated finding packaged for agent consumption."""
+        findings = self.get_findings()
+        if not findings:
+            return None
+        return self.build_remediation_package(findings[0], rank=1)
+
+    def apply_patch(
+        self,
+        finding_id: str,
+        rel_path: str,
+        target_content: str,
+        replacement_content: str,
+    ) -> PatchResult:
+        """Applies patch with transactional backup."""
+        return self.patcher.apply_replacement(
+            finding_id=finding_id,
+            rel_path=rel_path,
+            target_content=target_content,
+            replacement_content=replacement_content,
+        )
+
+    def verify_patch(self, finding_id: str) -> VerificationResult:
+        """Verifies patch via AST re-indexing and live runtime test pack replay."""
+        return self.verifier.verify(finding_id)
+
+    def run_self_healing_loop(self) -> HarnessExecutionReport:
+        """Autonomous self-healing execution loop:
+
+        Iterates through prioritized findings, synthesizes defensive patches,
+        applies them transactionally, and verifies runtime neutralization.
+        """
+        t0 = time.perf_counter()
+        initial_findings = self.get_findings()
+        baseline_score = self.calculate_posture_score(initial_findings)
+
+        verified_patches = []
+        unresolved = []
+
+        for idx, finding in enumerate(initial_findings, 1):
+            pkg = self.build_remediation_package(finding, rank=idx)
+            synth_patch = AutonomousRemediator.generate_patch(pkg)
+
+            if not synth_patch:
+                unresolved.append(finding.id)
+                continue
+
+            target_block, replacement_block = synth_patch
+            patch_res = self.apply_patch(
+                finding_id=finding.id,
+                rel_path=finding.source_location.file,
+                target_content=target_block,
+                replacement_content=replacement_block,
+            )
+
+            if not patch_res.success:
+                unresolved.append(finding.id)
+                continue
+
+            # Verify differential impact with verification oracle
+            v_res = self.verify_patch(finding.id)
+            if v_res.status == VerificationStatus.FIXED:
+                verified_patches.append({
+                    "finding_id": finding.id,
+                    "title": finding.title,
+                    "file": finding.source_location.file,
+                    "diff": patch_res.diff,
+                    "verification": v_res.model_dump(),
+                })
+            else:
+                # Verification failed or broke runtime tests: cleanly roll back patch
+                if patch_res.backup_file:
+                    self.patcher.rollback(finding.source_location.file, Path(patch_res.backup_file))
+                unresolved.append(finding.id)
+
+        remaining_count = len(unresolved)
+        fixed_count = len(verified_patches)
+        total_count = len(initial_findings)
+        
+        # New score calculation based on neutralized findings
+        final_score = min(100, baseline_score + (fixed_count * 15))
+        if fixed_count == total_count and total_count > 0:
+            final_score = 100
+
+        elapsed = time.perf_counter() - t0
+
+        return HarnessExecutionReport(
+            project_name=self.repo_path.name,
+            baseline_score=baseline_score,
+            final_score=final_score,
+            score_delta=final_score - baseline_score,
+            total_findings=total_count,
+            fixed_findings=fixed_count,
+            remaining_findings=remaining_count,
+            fix_rate_percent=round((fixed_count / total_count * 100), 1) if total_count else 100.0,
+            verified_patches=verified_patches,
+            unresolved_findings=unresolved,
+            execution_time_seconds=round(elapsed, 2),
+        )

package/src/trace_engine/harness/patcher.py

@@ -0,0 +1,143 @@
+"""Safe code patching and rollback engine for the TRACE Agent Harness."""
+
+import difflib
+import shutil
+import time
+from pathlib import Path
+from typing import Optional, Tuple
+from trace_engine.harness.context import PatchResult
+
+
+class SafePatcher:
+    """Manages transactional file edits, backups, and rollback for AI coding agents."""
+
+    def __init__(self, workspace_root: Path):
+        self.workspace_root = workspace_root.resolve()
+        self.backup_dir = self.workspace_root / ".trace" / "backups"
+        self.backup_dir.mkdir(parents=True, exist_ok=True)
+
+    def backup(self, rel_path: str) -> Path:
+        """Create timestamped backup of the target file."""
+        target = self.workspace_root / rel_path
+        if not target.exists():
+            raise FileNotFoundError(f"Target file {rel_path} does not exist in workspace.")
+
+        timestamp = int(time.time() * 1000)
+        safe_name = rel_path.replace("/", "_").replace("\\", "_")
+        backup_path = self.backup_dir / f"{safe_name}.{timestamp}.bak"
+        shutil.copy2(target, backup_path)
+        return backup_path
+
+    def apply_replacement(
+        self,
+        finding_id: str,
+        rel_path: str,
+        target_content: str,
+        replacement_content: str,
+    ) -> PatchResult:
+        """Replace target string block with replacement content, creating a rollback backup."""
+        file_path = self.workspace_root / rel_path
+        if not file_path.exists():
+            return PatchResult(
+                finding_id=finding_id,
+                target_file=rel_path,
+                success=False,
+                error=f"File not found: {rel_path}",
+            )
+
+        try:
+            original = file_path.read_text(encoding="utf-8")
+            if target_content not in original:
+                return PatchResult(
+                    finding_id=finding_id,
+                    target_file=rel_path,
+                    success=False,
+                    error="Target content block not found in file.",
+                )
+
+            backup_file = self.backup(rel_path)
+            new_content = original.replace(target_content, replacement_content, 1)
+            file_path.write_text(new_content, encoding="utf-8")
+
+            # Generate unified diff
+            diff_lines = list(
+                difflib.unified_diff(
+                    original.splitlines(keepends=True),
+                    new_content.splitlines(keepends=True),
+                    fromfile=f"a/{rel_path}",
+                    tofile=f"b/{rel_path}",
+                )
+            )
+            diff_str = "".join(diff_lines)
+
+            return PatchResult(
+                finding_id=finding_id,
+                target_file=rel_path,
+                success=True,
+                backup_file=str(backup_file),
+                diff=diff_str,
+            )
+        except Exception as e:
+            return PatchResult(
+                finding_id=finding_id,
+                target_file=rel_path,
+                success=False,
+                error=str(e),
+            )
+
+    def apply_full_content(
+        self,
+        finding_id: str,
+        rel_path: str,
+        new_content: str,
+    ) -> PatchResult:
+        """Write entire new file content, creating a rollback backup."""
+        file_path = self.workspace_root / rel_path
+        if not file_path.exists():
+            return PatchResult(
+                finding_id=finding_id,
+                target_file=rel_path,
+                success=False,
+                error=f"File not found: {rel_path}",
+            )
+
+        try:
+            original = file_path.read_text(encoding="utf-8")
+            backup_file = self.backup(rel_path)
+            file_path.write_text(new_content, encoding="utf-8")
+
+            diff_lines = list(
+                difflib.unified_diff(
+                    original.splitlines(keepends=True),
+                    new_content.splitlines(keepends=True),
+                    fromfile=f"a/{rel_path}",
+                    tofile=f"b/{rel_path}",
+                )
+            )
+            return PatchResult(
+                finding_id=finding_id,
+                target_file=rel_path,
+                success=True,
+                backup_file=str(backup_file),
+                diff="".join(diff_lines),
+            )
+        except Exception as e:
+            return PatchResult(
+                finding_id=finding_id,
+                target_file=rel_path,
+                success=False,
+                error=str(e),
+            )
+
+    def rollback(self, rel_path: str, backup_path: Path) -> bool:
+        """Restore file from backup."""
+        target = self.workspace_root / rel_path
+        if backup_path.exists():
+            shutil.copy2(backup_path, target)
+            return True
+        return False
+
+
+TransactionalPatcher = SafePatcher
+PatchOperationResult = PatchResult
+