trace-sec 2.1.13 → 2.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trace-sec",
-  "version": "2.1.13",
+  "version": "2.1.14",
   "description": "Threat Reconnaissance & Attack-path Correlation Engine — Security Verification Layer for Coding Agents with Fine-Tuned SecureBERT 2.0 & Laya AI",
   "type": "module",
   "main": "bin/trace.js",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "trace-sec"
-version = "2.1.13"
+version = "2.1.14"
 description = "Threat Reconnaissance & Attack-path Correlation Engine"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/trace_engine/__init__.py

@@ -3,6 +3,6 @@
 Local-first application security analysis and runtime validation engine.
 """
 
-__version__ = "2.1.13"
+__version__ = "2.1.14"
 __app_name__ = "TRACE"
 __description__ = "Threat Reconnaissance & Attack-path Correlation Engine"

package/src/trace_engine/findings/__init__.py

@@ -3,7 +3,7 @@
 from trace_engine.findings.model import Finding, Severity, FindingConfidence
 from trace_engine.findings.correlate import EvidenceCorrelator
 from trace_engine.findings.store import FindingStore
-from trace_engine.findings.recommendations import get_remediation_for_category
+from trace_engine.findings.recommendations import get_remediation_for_category, get_detailed_remediation_and_root_cause
 
 __all__ = [
     "Finding",
@@ -12,4 +12,5 @@ __all__ = [
     "EvidenceCorrelator",
     "FindingStore",
     "get_remediation_for_category",
+    "get_detailed_remediation_and_root_cause",
 ]

package/src/trace_engine/findings/correlate.py

@@ -4,7 +4,7 @@ from typing import List, Optional
 from trace_engine.security.hypotheses import SecurityHypothesis
 from trace_engine.testpacks.base import TestExecutionResult
 from trace_engine.findings.model import Finding, Severity, FindingConfidence
-from trace_engine.findings.recommendations import get_remediation_for_category
+from trace_engine.findings.recommendations import get_detailed_remediation_and_root_cause, get_remediation_for_category
 from trace_engine.apm.model import AttackPathModel
 
 
@@ -91,6 +91,14 @@ class EvidenceCorrelator:
 
         file_path = source_loc.file if source_loc else ""
 
+        root_cause, remediation, short_action = get_detailed_remediation_and_root_cause(
+            title=hypothesis.title,
+            category=category_str,
+            endpoint=hypothesis.endpoint_display,
+            static_evidence=hypothesis.static_evidence,
+            filepath=file_path,
+        )
+
         return Finding(
             id=finding_id,
             title=hypothesis.title,
@@ -103,7 +111,9 @@ class EvidenceCorrelator:
             static_evidence=hypothesis.static_evidence,
             runtime_evidence=runtime_evidence,
             correlation_notes=correlation_notes,
-            remediation=get_remediation_for_category(category_str, filepath=file_path),
+            remediation=remediation,
+            root_cause=root_cause,
+            short_action=short_action,
             reproduction_steps=test_result.reproduction_steps if test_result else [],
             observations=test_result.observations if test_result else [],
         )

package/src/trace_engine/findings/model.py

@@ -38,3 +38,5 @@ class Finding(BaseModel):
     remediation: str
     reproduction_steps: List[str] = Field(default_factory=list)
     observations: List[RuntimeObservation] = Field(default_factory=list)
+    root_cause: Optional[str] = None
+    short_action: Optional[str] = None

package/src/trace_engine/findings/recommendations.py

@@ -1,152 +1,307 @@
-"""Remediation recommendations for security findings."""
-
-from typing import Optional
-
-
-REMEDIATION_MAP_PYTHON = {
-    "BOLA": (
-        "Enforce strict object ownership validation before returning records. "
-        "Query using both the object ID and the authenticated user/tenant ID (e.g. `WHERE id = :id AND user_id = :current_user.id`)."
-    ),
-    "BFLA": (
-        "Implement declarative role-based access control (RBAC) dependencies (e.g. `Security(require_role('admin'))`). "
-        "Validate user privileges on the backend for every privileged/administrative route."
-    ),
-    "AUTHENTICATION": (
-        "Protect this route with authentication dependencies (e.g. `Depends(get_current_user)` or security middleware) "
-        "to ensure unauthorized users cannot trigger state-changing or sensitive operations."
-    ),
-    "SSRF": (
-        "Avoid making arbitrary outbound HTTP requests with user-controlled URLs. "
-        "Implement a strict destination domain whitelist and block loopback/internal IP addresses (RFC 1918)."
-    ),
-    "INJECTION": (
-        "Use parameterized queries, prepared statements, or ORM abstraction for all database operations. "
-        "Never format or concatenate raw client inputs into SQL/command strings."
-    ),
-    "MASS_ASSIGNMENT": (
-        "Define explicit request DTO schemas (e.g. Pydantic models with only allowed mutable fields). "
-        "Do not allow raw dictionary binding directly into database models."
-    ),
-    "PATH_TRAVERSAL": (
-        "Sanitize file path inputs using `os.path.basename()` or `pathlib.Path.resolve()`, "
-        "and verify that the resolved path is strictly within the allowed directory. Disallow path traversal sequences (`..`)."
-    ),
-    "SSTI": (
-        "Avoid rendering untrusted user inputs directly inside template engines. "
-        "Use contextual output encoding or sandbox template evaluation environments."
-    ),
-    "CORS": (
-        "Do not reflect arbitrary Origin headers or use wildcard `*` with credentials. "
-        "Configure an explicit allowlist of trusted origins."
-    ),
-    "DESERIALIZATION": (
-        "Avoid deserializing untrusted payloads (e.g. `pickle.loads`). "
-        "Use safe serialization formats like standard JSON with strict schema validation."
-    ),
-}
-
-REMEDIATION_MAP_NODE = {
-    "BOLA": (
-        "Enforce strict object ownership validation before returning or modifying records. "
-        "Scope queries using both the object ID and the authenticated user/tenant identity (e.g. `findByIdAndUserId(req.params.id, req.user.id)` or `WHERE id = ? AND tenant_id = ?`)."
-    ),
-    "BFLA": (
-        "Implement role-based access control (RBAC) middleware (e.g. `requireRole('admin')` or `checkPermission(...)`). "
-        "Validate `req.user.role` on the backend before executing privileged operations."
-    ),
-    "AUTHENTICATION": (
-        "Mount authentication middleware (e.g. `router.use(verifyToken)` or `app.use('/api/...', verifyToken, router)`) "
-        "to ensure unauthorized users cannot trigger state-changing or sensitive operations."
-    ),
-    "SSRF": (
-        "Avoid making outbound HTTP requests (e.g. with `axios` or `fetch`) using user-controlled URLs. "
-        "Implement a strict destination domain allowlist and block loopback (`127.0.0.1`, `localhost`) and private RFC-1918 IP addresses."
-    ),
-    "INJECTION": (
-        "Use parameterized queries, prepared statements, or ORM abstractions (e.g. Prisma, Mongoose, TypeORM, Knex). "
-        "Never concatenate or interpolate raw `req.body` or `req.query` into database queries or shell commands."
-    ),
-    "MASS_ASSIGNMENT": (
-        "Define explicit request DTO schemas (e.g. using Zod, Joi, or TypeScript DTOs) and pick allowlisted fields from `req.body`. "
-        "Never pass raw `req.body` directly into database creation or update functions."
-    ),
-    "PATH_TRAVERSAL": (
-        "Sanitize file path inputs using `path.basename()` or `path.resolve()`, "
-        "and verify that the target path strictly resides within the intended root directory (e.g. `resolvedPath.startsWith(BASE_DIR)`). Disallow directory traversal sequences (`..`)."
-    ),
-    "SSTI": (
-        "Avoid rendering untrusted user inputs directly inside template engines. "
-        "Use contextual output encoding or sandbox template evaluation environments."
-    ),
-    "CORS": (
-        "Do not reflect the `Origin` request header or allow `Access-Control-Allow-Origin: *` with `Access-Control-Allow-Credentials: true`. "
-        "Configure an explicit allowlist of trusted origins."
-    ),
-    "DESERIALIZATION": (
-        "Avoid deserializing untrusted payloads (e.g. `node-serialize`). "
-        "Use safe data serialization formats like standard `JSON.parse` with strict schema validation."
-    ),
-}
-
-REMEDIATION_MAP_GO = {
-    "BOLA": (
-        "Enforce strict tenant and user ownership validation. "
-        "Scope database queries to the authenticated user ID from context (e.g. `db.Where(\"id = ? AND user_id = ?\", id, currentUserID)`)."
-    ),
-    "BFLA": (
-        "Implement role-based authorization checks in Gin/Echo middleware. "
-        "Verify user claims from context before proceeding with administrative actions."
-    ),
-    "AUTHENTICATION": (
-        "Protect this route with authentication middleware (e.g. Gin/Echo middleware validating JWT/session token into context) "
-        "to ensure unauthorized users cannot trigger state-changing operations."
-    ),
-    "SSRF": (
-        "Validate target URLs against an allowlist and block private IP ranges before executing `http.Get` or `http.Post`."
-    ),
-    "INJECTION": (
-        "Use parameterized SQL placeholders (`?` or `$1`) with `database/sql` or GORM. Never concatenate input into raw SQL queries."
-    ),
-    "MASS_ASSIGNMENT": (
-        "Bind incoming requests to dedicated request structs with strictly permitted fields instead of raw map or model structs."
-    ),
-    "PATH_TRAVERSAL": (
-        "Use `filepath.Clean` and `filepath.Rel` to verify file paths stay within the target base directory."
-    ),
-    "SSTI": "Ensure HTML templates use context-aware escaping (`html/template`).",
-    "CORS": "Configure explicit origins in CORS middleware. Do not allow wildcard origins with credentials.",
-    "DESERIALIZATION": "Use standard `encoding/json` with typed Go structs for decoding untrusted client data.",
-}
-
-# Default backwards-compatible map
-REMEDIATION_MAP = REMEDIATION_MAP_PYTHON
+"""Remediation and Root Cause Explanation Engine for TRACE security findings.
 
+Generates precise, non-vague, technical root cause analyses, step-by-step remediation actions,
+and concise terminal action summaries tailored to the specific vulnerability pattern.
+"""
 
-def get_remediation_for_category(category: str, filepath: str = "", framework: str = "") -> str:
-    """Returns framework- and language-tailored remediation recommendations."""
+from typing import Optional, Dict, Any, List, Tuple
+
+
+def get_detailed_remediation_and_root_cause(
+    title: str,
+    category: str,
+    endpoint: str,
+    static_evidence: Optional[List[str]] = None,
+    filepath: str = "",
+) -> Tuple[str, str, str]:
+    """Generates: (root_cause_explanation, detailed_remediation_steps, short_action_summary).
+
+    All three outputs are tailored specifically to the exact finding rather than generic category templates.
+    """
+    t_lower = title.lower()
+    ep_lower = endpoint.lower()
+    ev_text = " ".join(static_evidence or []).lower()
     cat_upper = category.upper()
-    file_lower = filepath.lower()
 
-    # Detect language / framework
-    if any(file_lower.endswith(ext) for ext in (".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs")) or framework.lower() in ("express", "nextjs", "react_router", "node"):
-        return REMEDIATION_MAP_NODE.get(
-            cat_upper,
-            "Review access control, authentication middleware, and input validation on this attack path.",
+    # 1. Caller-Controlled Ownership Bypass via Optional Parameter
+    if "caller-controlled" in t_lower or "assert_coach_owns_athlete" in ev_text or ("coach_id" in ev_text and "bypass" in t_lower):
+        root_cause = (
+            f"The multi-tenant authorization assertion on `{endpoint}` is conditionally guarded by a client-supplied "
+            f"query parameter (e.g. `coach_id`). Because the parameter is optional (`Optional[int] = Query(None)`), "
+            f"an attacker can simply omit `?coach_id=` from the request URL to completely skip the ownership assertion "
+            f"and access or modify private domain records belonging to any athlete."
         )
-    elif file_lower.endswith(".go") or framework.lower() == "go":
-        return REMEDIATION_MAP_GO.get(
-            cat_upper,
-            "Review access control and input validation on this attack path.",
+        remediation = (
+            "1. Remove `coach_id` from client-supplied query parameters.\n"
+            "2. Extract the authenticated caller's identity directly from verified session state or JWT claims "
+            "(e.g., `current_user = Depends(get_current_user)`).\n"
+            "3. Enforce the tenant/coach ownership check unconditionally using the session ID: "
+            "`assert_coach_owns_athlete(current_user.id, user_id)` before querying or mutating the database.\n"
+            "4. Return HTTP 403 Forbidden or 404 Not Found if the relationship check fails."
         )
-    elif file_lower.endswith(".py") or framework.lower() in ("fastapi", "flask", "django"):
-        return REMEDIATION_MAP_PYTHON.get(
-            cat_upper,
-            "Review access control and input validation on this attack path.",
+        short_action = "Enforce caller tenant validation from session token; do not accept optional coach_id."
+        return root_cause, remediation, short_action
+
+    # 2. Public StaticFiles Directory Mount
+    if "staticfiles" in t_lower or "staticfiles" in ev_text or "/session_videos" in ep_lower:
+        root_cause = (
+            f"The directory containing stored files is mounted publicly via FastAPI's `StaticFiles` at `{endpoint}` "
+            f"without authentication or tenant authorization middleware. This completely circumvents API-level access "
+            f"controls, allowing unauthenticated callers to enumerate, stream, and download private user recordings and "
+            f"uploaded files directly via static HTTP GET requests."
+        )
+        remediation = (
+            f"1. Remove the public directory mount `app.mount('{endpoint}', StaticFiles(...))`.\n"
+            "2. Implement a protected API endpoint (e.g. `GET /api/media/{file_id}`) that validates caller authentication "
+            "and verifies that the requested media belongs to the requesting user before streaming.\n"
+            "3. Stream files securely using `FileResponse` or `StreamingResponse` after authorization.\n"
+            "4. Alternatively, store sensitive files in an S3/GCS bucket and generate short-lived, pre-signed URLs."
         )
+        short_action = "Remove public StaticFiles mount; serve files via authenticated FileResponse."
+        return root_cause, remediation, short_action
 
-    # Fallback to general remediation
-    return REMEDIATION_MAP_NODE.get(cat_upper) or REMEDIATION_MAP_PYTHON.get(
-        cat_upper,
-        "Review access control and input validation on this attack path.",
+    # 3. Broken Password Hashing & Plaintext Fallback
+    if "password hashing" in t_lower or "plaintext" in ev_text or "verify_password" in t_lower:
+        root_cause = (
+            "Password verification logic in the authentication module contains a critical plaintext equality fallback "
+            "(`if hashed_password == plain_password:`) and/or relies on a single hardcoded global salt with fast, "
+            "un-keyed SHA-256 instead of an adaptive work-factor algorithm. This permits unhashed credential logins "
+            "and leaves stored hashes susceptible to commodity GPU rainbow table recovery."
+        )
+        remediation = (
+            "1. Immediately delete the plaintext equality comparison `if hashed_password == plain_password:`.\n"
+            "2. Migrate password hashing to an adaptive, slow work-factor algorithm such as `bcrypt` or `Argon2id` "
+            "(e.g. using `passlib.context.CryptContext(schemes=['bcrypt'])`).\n"
+            "3. Ensure the hashing function automatically generates and binds a unique, cryptographically random salt per user record.\n"
+            "4. Re-hash legacy passwords transparently upon user login."
+        )
+        short_action = "Eliminate plaintext check; migrate password hashing to bcrypt/Argon2 with per-user salt."
+        return root_cause, remediation, short_action
+
+    # 4. Unauthenticated Global Session / Data Wipe with Blast Radius
+    if "blast radius" in t_lower or ("reset" in ep_lower and ("wipe" in t_lower or "global" in t_lower)):
+        root_cause = (
+            f"Calling `{endpoint}` without request parameters defaults to iterating across all connected users "
+            f"and executes bulk deletion (`shutil.rmtree` and database row deletion) across all user accounts "
+            f"without requiring authentication, session scoping, or confirmation. A single unauthenticated HTTP call "
+            f"destroys the entire system's session and telemetry data."
+        )
+        remediation = (
+            f"1. Enforce authentication dependency `Depends(get_current_user)` on `{endpoint}`.\n"
+            "2. Scope the deletion logic strictly to `user_id == current_user.id` so a caller can only reset their own session.\n"
+            "3. If a global multi-tenant reset is required for operations, isolate it to a privileged route protected by "
+            "`Depends(require_admin)` and require multi-factor or secondary token confirmation."
+        )
+        short_action = "Scope deletion strictly to current_user.id; restrict global wipes to require_admin."
+        return root_cause, remediation, short_action
+
+    # 5. Privilege Escalation via Unvalidated Role Assignment
+    if "role assignment" in t_lower or ("role" in ev_text and "privilege" in t_lower):
+        root_cause = (
+            f"The user registration/creation handler on `{endpoint}` binds a client-supplied `role` string directly "
+            f"into the new user record without server-side validation or administrative authorization checks. "
+            f"An unauthenticated attacker can submit `role='ADMIN'` to instantly create a persistent superuser account."
+        )
+        remediation = (
+            "1. Remove `role` and administrative privilege attributes from public user creation schemas.\n"
+            "2. Restrict administrative user creation (`/api/admin/users/create`) with `Depends(require_admin)`.\n"
+            "3. Enforce a strict server-side Enum allowlist (e.g. `Role.USER`, `Role.ATHLETE`) and default all new accounts "
+            "to unprivileged roles regardless of client payload."
+        )
+        short_action = "Protect with require_admin; enforce server-side role allowlist on user creation."
+        return root_cause, remediation, short_action
+
+    # 6. Account Takeover via Unauthenticated Password Reset
+    if "reset" in ep_lower and "password" in ep_lower:
+        root_cause = (
+            f"The password reset endpoint `{endpoint}` modifies user credentials without requiring current password "
+            f"validation, an authenticated session, or an out-of-band cryptographically signed reset token. An attacker "
+            f"can overwrite the password of any user account by targeting their sequential ID or username."
+        )
+        remediation = (
+            "1. Implement an out-of-band reset flow using time-limited, single-use cryptographically random tokens "
+            "delivered to the verified user email address.\n"
+            "2. For self-service password changes by logged-in users, require current password verification.\n"
+            "3. For administrative password resets, guard the route with `Depends(require_admin)`."
+        )
+        short_action = "Require verified single-use reset token or require_admin check for password resets."
+        return root_cause, remediation, short_action
+
+    # 7. Insecure CORS Configuration
+    if cat_upper == "CORS" or "cors" in t_lower:
+        root_cause = (
+            f"`CORSMiddleware` on `{endpoint}` is configured with `allow_origins=['*']` combined with "
+            f"`allow_credentials=True`. This permits arbitrary third-party websites to execute credentialed "
+            f"cross-origin requests against the backend, enabling CSRF-style data exfiltration and session riding."
+        )
+        remediation = (
+            "1. Remove wildcard `allow_origins=['*']`.\n"
+            "2. Configure an explicit array of authorized frontend domains (e.g. `allow_origins=['https://app.example.com']`).\n"
+            "3. Never dynamically reflect incoming `Origin` headers into `Access-Control-Allow-Origin` when credentials are enabled."
+        )
+        short_action = "Remove wildcard allow_origins; define explicit list of authorized frontend domains."
+        return root_cause, remediation, short_action
+
+    # 8. Unauthenticated WebSockets
+    if "websocket" in t_lower or "websocket" in ev_text:
+        root_cause = (
+            f"The WebSocket route `{endpoint}` accepts incoming streaming connections and dispatches real-time telemetry "
+            f"without authenticating the client during the handshake, allowing unauthorized eavesdropping or malicious event injection."
+        )
+        remediation = (
+            "1. Extract and validate authentication credentials (JWT ticket or session cookie) during the WebSocket connection handshake.\n"
+            "2. Reject unauthenticated handshakes before calling `await websocket.accept()` using WebSocket close code 1008 (Policy Violation).\n"
+            "3. Associate the open WebSocket connection strictly with the validated user ID."
+        )
+        short_action = "Validate authentication token during handshake before calling websocket.accept()."
+        return root_cause, remediation, short_action
+
+    # 9. Stateless ML / Inference Resource Exhaustion
+    if "scatt-analysis" in ep_lower or "inference" in t_lower or "stateless" in t_lower:
+        root_cause = (
+            f"The compute-intensive inference endpoint `{endpoint}` is exposed to the public internet without authentication "
+            f"or request rate-limiting, allowing unauthorized callers to trigger CPU/GPU exhaustion and denial-of-wallet."
+        )
+        remediation = (
+            "1. Add API key or session token verification to authenticate callers.\n"
+            "2. Implement rate-limiting middleware (e.g. `slowapi` or Redis token bucket) to throttle request frequency per client IP.\n"
+            "3. Enforce maximum payload size limits on input telemetry arrays."
+        )
+        short_action = "Add API key authentication and rate-limiting middleware (slowapi) to throttle inference."
+        return root_cause, remediation, short_action
+
+    # 10. Unauthenticated User Information Disclosure
+    if "user information disclosure" in t_lower or ("user" in ep_lower and cat_upper == "AUTHENTICATION" and "get" in ep_lower):
+        root_cause = (
+            f"Read-only endpoint `{endpoint}` discloses user profile records (ID, username, role) to unauthenticated callers, "
+            f"permitting automated enumeration of all registered users in the application."
+        )
+        remediation = (
+            f"1. Protect `{endpoint}` with `Depends(get_current_user)` or require valid session authentication.\n"
+            "2. If public user profiles are intended by design, redact internal database IDs, role assignments, and private metadata."
+        )
+        short_action = "Protect user lookup with Depends(get_current_user) to prevent user enumeration."
+        return root_cause, remediation, short_action
+
+    fp_lower = filepath.lower()
+    is_node = fp_lower.endswith((".js", ".ts", ".jsx", ".tsx", ".mjs"))
+
+    # 11. General BOLA / IDOR
+    if cat_upper == "BOLA" or "bola" in t_lower:
+        root_cause = (
+            f"The handler for `{endpoint}` looks up database records using a client-supplied object ID from the URL or query "
+            f"without verifying that the requested record belongs to the authenticated user's tenant or organization. "
+            f"An attacker can increment or replace the ID to view or modify records belonging to other tenants."
+        )
+        if is_node:
+            remediation = (
+                "1. Extract authenticated caller ID from session state (`req.user.id` or `req.user.tenantId`).\n"
+                "2. Scope database queries to verify `req.user.tenantId == record.tenantId` before returning data.\n"
+                "3. Return HTTP 403 Forbidden or 404 Not Found if the resource is not owned by the caller."
+            )
+            short_action = "Scope database query to req.user.tenantId to enforce object-level isolation."
+        else:
+            remediation = (
+                "1. Extract authenticated caller ID from the verified session context (e.g. `current_user = Depends(get_current_user)`).\n"
+                "2. Scope database queries to both the object ID and the user's tenant: "
+                "`db.query(Model).filter(Model.id == obj_id, Model.tenant_id == current_user.tenant_id).first()`.\n"
+                "3. Return HTTP 403 Forbidden or 404 Not Found if the resource is not owned by the caller."
+            )
+            short_action = "Scope database query to authenticated current_user.tenant_id to enforce isolation."
+        return root_cause, remediation, short_action
+
+    # 12. General BFLA / Admin RBAC Missing
+    if cat_upper == "BFLA" or "admin" in ep_lower or "bfla" in t_lower:
+        root_cause = (
+            f"Privileged administrative route `{endpoint}` is accessible without verifying that the caller possesses "
+            f"administrative role permissions. Any standard user or unauthenticated client can trigger administrative actions."
+        )
+        if is_node:
+            remediation = (
+                "1. Mount role-verification middleware (`requireRole('admin')`) on the route.\n"
+                "2. Verify `req.user && req.user.role === 'admin'` before executing privileged operations."
+            )
+            short_action = "Mount requireRole('admin') middleware on privileged administrative route."
+        else:
+            remediation = (
+                "1. Implement declarative role-based access control (RBAC) dependencies (e.g. `Security(require_role('admin'))`).\n"
+                "2. Verify that `current_user.role == 'ADMIN'` on the backend before executing privileged state changes."
+            )
+            short_action = "Implement declarative RBAC dependency (require_admin) on privileged administrative route."
+        return root_cause, remediation, short_action
+
+    # 13. General Authentication Missing on Sensitive Route
+    if cat_upper == "AUTHENTICATION":
+        root_cause = (
+            f"Sensitive or state-modifying endpoint `{endpoint}` does not enforce authentication. Unauthorized callers "
+            f"can trigger operations or retrieve private data without providing credentials or session tokens."
+        )
+        if is_node:
+            remediation = (
+                f"1. Mount authentication middleware `verifyToken` or `router.use(authMiddleware)` on `{endpoint}`.\n"
+                "2. Reject unauthenticated requests with HTTP 401 Unauthorized."
+            )
+            short_action = "Mount verifyToken middleware on Express route."
+        else:
+            remediation = (
+                f"1. Mount authentication dependency `Depends(get_current_user)` or security middleware on `{endpoint}`.\n"
+                "2. Reject unauthenticated requests with HTTP 401 Unauthorized."
+            )
+            short_action = "Protect route with Depends(get_current_user) to block unauthenticated callers."
+        return root_cause, remediation, short_action
+
+    # 14. Path Traversal
+    if cat_upper == "PATH_TRAVERSAL":
+        root_cause = (
+            f"Endpoint `{endpoint}` accepts file or path parameters without verifying that the resolved path resides "
+            f"strictly within the intended base directory. Attackers can use path traversal sequences (`..`) to access arbitrary system files."
+        )
+        remediation = (
+            "1. Sanitize file path inputs using `os.path.basename()` or `pathlib.Path.resolve()`.\n"
+            "2. Verify that `resolved_path.is_relative_to(base_dir)` before opening or reading files."
+        )
+        short_action = "Sanitize file input with basename() and verify resolved directory containment."
+        return root_cause, remediation, short_action
+
+    # 15. SSRF
+    if cat_upper == "SSRF":
+        root_cause = (
+            f"Endpoint `{endpoint}` accepts a user-controlled destination URL and dispatches outbound HTTP requests without "
+            f"validating the host against an allowlist, allowing attackers to probe internal cloud metadata and RFC-1918 networks."
+        )
+        remediation = (
+            "1. Validate target URLs against a strict allowlist of authorized hostnames.\n"
+            "2. Resolve DNS names and reject loopback (`127.0.0.1`, `localhost`) and private RFC-1918 IP addresses before dispatching HTTP calls."
+        )
+        short_action = "Enforce domain allowlist and block loopback/private RFC-1918 IPs on outbound HTTP."
+        return root_cause, remediation, short_action
+
+    # 16. SQL / NoSQL Injection
+    if cat_upper == "INJECTION":
+        root_cause = (
+            f"Endpoint `{endpoint}` routes user-supplied query parameters to the database layer without verified parameterization, "
+            f"permitting SQL syntax injection and unauthorized database manipulation."
+        )
+        remediation = (
+            "1. Use parameterized queries, prepared statements, or ORM abstraction methods for all database operations.\n"
+            "2. Never concatenate or format raw client inputs into SQL query strings."
+        )
+        short_action = "Use parameterized SQL queries or ORM models; never concatenate raw user input."
+        return root_cause, remediation, short_action
+
+    # Default fallback
+    root_cause = f"Security vulnerability of category `{category}` identified in `{endpoint}`."
+    remediation = "Apply strict authentication, tenant authorization boundaries, and input validation to this attack path."
+    short_action = f"Apply strict access control and input validation on {category} attack path."
+    return root_cause, remediation, short_action
+
+
+def get_remediation_for_category(category: str, filepath: str = "", framework: str = "") -> str:
+    """Backwards-compatible remediation accessor."""
+    _, rem, _ = get_detailed_remediation_and_root_cause(
+        title=category,
+        category=category,
+        endpoint="endpoint",
+        filepath=filepath,
     )
+    return rem

package/src/trace_engine/findings/store.py

@@ -14,12 +14,24 @@ class FindingStore:
         self.store_file = trace_dir / "findings.json"
 
     def save_findings(self, findings: List[Finding]) -> None:
-        """Save a list of findings to JSON."""
+        """Save a list of findings to JSON and generate markdown reports."""
         self.trace_dir.mkdir(parents=True, exist_ok=True)
         data = [f.model_dump() for f in findings]
         with open(self.store_file, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=2)
 
+        try:
+            from trace_engine.output.markdown import generate_markdown_report
+            project_name = self.trace_dir.parent.name if self.trace_dir.parent else "Application"
+            md_content = generate_markdown_report(findings, project_name=project_name)
+            (self.trace_dir / "findings.md").write_text(md_content, encoding="utf-8")
+
+            workspace_root = self.trace_dir.parent
+            if workspace_root and workspace_root.exists() and workspace_root != self.trace_dir:
+                (workspace_root / "findings.md").write_text(md_content, encoding="utf-8")
+        except Exception:
+            pass
+
     def load_findings(self) -> List[Finding]:
         """Load findings from JSON file."""
         if not self.store_file.exists():

package/src/trace_engine/interactive.py

@@ -624,53 +624,57 @@ def run_interactive_story() -> None:
     )
 
     # =========================================================================
-    # STEP 7: Autonomous AST Self-Healing Opportunity
+    # STEP 7: AI Coding Agent Handoff & Export Options
     # =========================================================================
-    if findings:
-        console.print(f"\n  [{DIM_GREEN}]{'─' * 76}[/{DIM_GREEN}]")
-        console.print(f"  [{GREEN}]◆ AUTONOMOUS AST SELF-HEALING OPPORTUNITY:[/{GREEN}]")
-        console.print(f"    [{WHITE}]TRACE can synthesize surgical AST patches for detected flaws in {project_dir.name}.[/{WHITE}]")
-        console.print(f"    [{DIM_WHITE}]Includes transactional rollback protection and verification oracle testing.[/{DIM_WHITE}]\n")
-
-        heal_ans = ask_input(
-            f"  [{ORANGE}]›[/{ORANGE}] [{BOLD_WHITE}]Autonomously remediate verified vulnerabilities now? (y/n)[/{BOLD_WHITE}]",
-            choices=["y", "n", "yes", "no"],
-            default="n",
-        )
-        should_heal = heal_ans.lower() in ("y", "yes")
-
-        if should_heal:
-            from trace_engine.harness.engine import AgentHarness
-            with console.status(f"  [{GREEN}]Autonomous Harness:[/{GREEN}] [{WHITE}]Refactoring AST nodes & running verification...[/{WHITE}]", spinner="dots"):
-                harness = AgentHarness(project_dir, target_url=target_url)
-                report = harness.run_self_healing_loop()
-            print_harness_report(report)
-
-    # =========================================================================
-    # STEP 8: Post-Audit Export
-    # =========================================================================
-    console.print(f"\n  [{BOLD_WHITE}]Export Options:[/{BOLD_WHITE}]")
-    console.print(f"    [{ORANGE}][1][/{ORANGE}] [{BOLD_WHITE}]Export OASIS SARIF v2.1.0[/{BOLD_WHITE}] [{DIM_WHITE}](GitHub Code Scanning / CI Integration)[/{DIM_WHITE}]")
-    console.print(f"    [{ORANGE}][2][/{ORANGE}] [{BOLD_WHITE}]Export Markdown Report[/{BOLD_WHITE}] [{DIM_WHITE}](Executive summary document)[/{DIM_WHITE}]")
-    console.print(f"    [{ORANGE}][3][/{ORANGE}] [{BOLD_WHITE}]Finish Session[/{BOLD_WHITE}]\n")
-
-    post_choice = ask_input(
-        f"  [{ORANGE}]›[/{ORANGE}] [{BOLD_WHITE}]Select export option[/{BOLD_WHITE}]",
-        choices=["1", "2", "3"],
-        default="1",
+    console.print(f"\n  [{DIM_GREEN}]{'─' * 76}[/{DIM_GREEN}]")
+    console.print(f"  [{GREEN}]◆ TRACE AUDIT COMPLETE — AI AGENT & REMEDIATION HANDOFF:[/{GREEN}]")
+    console.print(f"    [{WHITE}]TRACE has generated precise root causes and concrete remediation plans for all {len(findings)} findings.[/{WHITE}]")
+    console.print(f"    [{DIM_WHITE}]Executive report automatically saved to:[/{DIM_WHITE}] [{BOLD_WHITE}]{project_dir / 'findings.md'}[/{BOLD_WHITE}]\n")
+
+    console.print(f"  [{BOLD_WHITE}]Next Action / Integration Options:[/{BOLD_WHITE}]")
+    console.print(f"    [{ORANGE}][1][/{ORANGE}] [{BOLD_WHITE}]Inspect Detailed Root Cause & Exploit Mechanics in Terminal[/{BOLD_WHITE}]")
+    console.print(f"    [{ORANGE}][2][/{ORANGE}] [{BOLD_WHITE}]Launch TRACE MCP Server[/{BOLD_WHITE}] [{DIM_WHITE}](Connect Claude Code / Cursor as skill)[/{DIM_WHITE}]")
+    console.print(f"    [{ORANGE}][3][/{ORANGE}] [{BOLD_WHITE}]Export OASIS SARIF v2.1.0[/{BOLD_WHITE}] [{DIM_WHITE}](GitHub Code Scanning / CI)[/{DIM_WHITE}]")
+    console.print(f"    [{ORANGE}][4][/{ORANGE}] [{BOLD_WHITE}]Finish Session[/{BOLD_WHITE}]\n")
+
+    handoff_choice = ask_input(
+        f"  [{ORANGE}]›[/{ORANGE}] [{BOLD_WHITE}]Select action[/{BOLD_WHITE}]",
+        choices=["1", "2", "3", "4"],
+        default="4",
         show_default=True,
     )
 
-    if post_choice == "1":
+    if handoff_choice == "1":
+        while True:
+            console.print(f"\n  [{BOLD_WHITE}]Available Findings to Inspect:[/{BOLD_WHITE}]")
+            for f in findings:
+                action_text = f.short_action or f.title
+                console.print(f"    [{GREEN}]• {f.id:<14}[/{GREEN}] [{WHITE}]{f.endpoint:<28}[/{WHITE}] [{DIM_WHITE}]{action_text}[/{DIM_WHITE}]")
+            f_id = ask_input(f"\n  [{ORANGE}]›[/{ORANGE}] [{BOLD_WHITE}]Enter Finding ID to inspect (or 'back')[/{BOLD_WHITE}]", default="back")
+            if f_id.lower() in ("back", "exit", "q"):
+                break
+            matched = next((f for f in findings if f.id.lower() == f_id.lower()), None)
+            if matched:
+                console.print()
+                print_finding_detail(matched)
+            else:
+                console.print(f"  [{ORANGE}]Finding '{f_id}' not found.[/{ORANGE}]")
+
+    elif handoff_choice == "2":
+        console.print(f"\n  [{GREEN}]Starting TRACE MCP Server on port 8765...[/{GREEN}]")
+        console.print(f"  [{DIM_WHITE}]Connect Claude Code or Cursor to: [bold white]http://127.0.0.1:8765/sse[/bold white][/{DIM_WHITE}]")
+        console.print(f"  [{DIM_WHITE}]Press Ctrl+C to stop the MCP server when finished.[/{DIM_WHITE}]\n")
+        from trace_engine.mcp.server import run_server
+        try:
+            run_server(host="127.0.0.1", port=8765)
+        except KeyboardInterrupt:
+            console.print(f"\n  [{GREEN}]✓ TRACE MCP Server stopped.[/{GREEN}]")
+
+    elif handoff_choice == "3":
         sarif_file = project_dir / "trace-results.sarif"
         sarif_data = generate_sarif_report(findings, project_name=project_dir.name, workspace_root=str(project_dir))
         import json
         sarif_file.write_text(json.dumps(sarif_data, indent=2), encoding="utf-8")
         console.print(f"  [{GREEN}]✓ Exported SARIF v2.1.0:[/{GREEN}] [{WHITE}]{sarif_file}[/{WHITE}]\n")
-    elif post_choice == "2":
-        md_file = project_dir / "TRACE_SECURITY_REPORT.md"
-        md_content = generate_markdown_report(findings, project_name=project_dir.name)
-        md_file.write_text(md_content, encoding="utf-8")
-        console.print(f"  [{GREEN}]✓ Exported Markdown Report:[/{GREEN}] [{WHITE}]{md_file}[/{WHITE}]\n")
 
     console.print(f"  [{GREEN}]✓ TRACE Audit Session Complete. System Verified.[/{GREEN}]\n")

package/src/trace_engine/mcp/server.py

@@ -218,6 +218,8 @@ class TraceMCPServer:
                     "severity": f.severity.value,
                     "confidence": f.confidence.value,
                     "endpoint": f.endpoint,
+                    "root_cause": f.root_cause,
+                    "short_action": f.short_action,
                     "remediation": f.remediation,
                     "source": str(f.source_location) if f.source_location else None,
                 }
@@ -239,6 +241,8 @@ class TraceMCPServer:
                 "endpoint": finding.endpoint,
                 "source": str(finding.source_location),
                 "attack_path": finding.attack_path,
+                "root_cause": finding.root_cause,
+                "short_action": finding.short_action,
                 "static_evidence": finding.static_evidence,
                 "runtime_evidence": finding.runtime_evidence,
                 "correlation_notes": finding.correlation_notes,

package/src/trace_engine/output/markdown.py

@@ -10,16 +10,18 @@ def generate_markdown_report(findings: List[Finding], project_name: str = "Appli
         f"# TRACE Security Assessment Report — {project_name}",
         "Threat Reconnaissance & Attack-path Correlation Engine",
         "",
-        "## Summary",
-        f"- Total Correlated Findings: **{len(findings)}**",
+        "## Executive Summary",
+        f"- **Target Application:** `{project_name}`",
+        f"- **Total Correlated Findings:** **{len(findings)}**",
         "",
-        "| ID | Severity | Confidence | Category | Endpoint | Title |",
+        "| ID | Severity | Confidence | Category | Endpoint | Remediation Action |",
         "|---|---|---|---|---|---|",
     ]
 
     for f in findings:
+        action_summary = f.short_action or f.title
         lines.append(
-            f"| {f.id} | {f.severity.value} | {f.confidence.value} | {f.category} | `{f.endpoint}` | {f.title} |"
+            f"| `{f.id}` | **{f.severity.value}** | {f.confidence.value} | {f.category} | `{f.endpoint}` | {action_summary} |"
         )
 
     lines.extend(["", "---", "", "## Finding Details", ""])
@@ -33,9 +35,13 @@ def generate_markdown_report(findings: List[Finding], project_name: str = "Appli
         if f.source_location:
             lines.append(f"- **Source:** `{f.source_location}`")
         lines.append("")
-        
+
+        if f.root_cause:
+            lines.append("#### Root Cause & Exploit Mechanics")
+            lines.append(f"{f.root_cause}\n")
+
         if f.attack_path:
-            lines.append("#### Attack Path Hops")
+            lines.append("#### Attack Path Hops (APM Traversal)")
             for hop in f.attack_path:
                 lines.append(f"1. `{hop}`")
             lines.append("")
@@ -58,7 +64,8 @@ def generate_markdown_report(findings: List[Finding], project_name: str = "Appli
                 lines.append(f"{idx}. {step}")
             lines.append("")
 
-        lines.append(f"#### Remediation Guidance\n{f.remediation}\n")
+        lines.append("#### Concrete Remediation Plan")
+        lines.append(f"{f.remediation}\n")
         lines.append("---")
         lines.append("")
 

package/src/trace_engine/output/terminal.py

@@ -220,6 +220,10 @@ def print_finding_detail(f: Finding) -> None:
             prefix = "  +- "
             content.append(f"{prefix}{hop}\n", style="dim white")
 
+    if f.root_cause:
+        content.append("\nRoot Cause & Exploit Mechanics:\n", style="bold green")
+        content.append(f"  {f.root_cause}\n", style="bright_white")
+
     if f.static_evidence:
         content.append("\nStatic Code Evidence:\n", style="bold green")
         for ev in f.static_evidence:
@@ -235,8 +239,10 @@ def print_finding_detail(f: Finding) -> None:
         for idx, step in enumerate(f.reproduction_steps, 1):
             content.append(f"  {idx}. {step}\n", style="white")
 
-    content.append("\nRemediation Guidance:\n", style="bold green")
-    content.append(f"  {f.remediation}\n", style="dim white")
+    content.append("\nConcrete Remediation Action Plan:\n", style="bold green")
+    for line in f.remediation.split("\n"):
+        if line.strip():
+            content.append(f"  {line}\n", style="white")
 
     console.print(
         Panel(
@@ -351,7 +357,7 @@ def print_test_all_report(
     for idx, f in enumerate(sorted_findings, 1):
         prio = priority_labels.get(f.severity, str(f.severity.value))
         loc_str = str(f.source_location) if f.source_location else "-"
-        remediation_snippet = f.remediation.strip().split(".")[0] + "." if f.remediation else "Apply strict authorization check."
+        remediation_snippet = f.short_action or (f.remediation.strip().split(".")[0] + "." if f.remediation else "Apply strict authorization check.")
 
         table.add_row(
             f"#{idx}",