trace-sec 2.1.8 → 2.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trace-sec",
-  "version": "2.1.8",
+  "version": "2.1.10",
   "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.5"
+version = "2.1.10"
 description = "Threat Reconnaissance & Attack-path Correlation Engine"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/trace_engine/cli.py

@@ -69,14 +69,10 @@ console = Console()
 
 @app.callback()
 def main(ctx: typer.Context):
-    """If no command is provided, launch interactive story mode (or show banner if non-interactive)."""
+    """If no command is provided, launch the interactive TRACE security terminal."""
     if ctx.invoked_subcommand is None:
-        if sys.stdin.isatty():
-            from trace_engine.interactive import run_interactive_story
-            run_interactive_story()
-        else:
-            print_banner()
-            print_security_notes()
+        from trace_engine.interactive import run_interactive_story
+        run_interactive_story()
 
 
 @app.command(name="interactive")

package/src/trace_engine/findings/correlate.py

@@ -67,6 +67,10 @@ class EvidenceCorrelator:
                 runtime_evidence.append(
                     f"HTTP {obs.request_method} {obs.request_url} -> Status {obs.response_status} ({obs.latency_ms}ms)"
                 )
+        else:
+            runtime_evidence.append(
+                "Static Attack-Path Model verified vulnerable control boundary. Active dynamic probe was not executed (offline scan mode or live target host not specified)."
+            )
 
         # Correlation explanation
         if test_result and test_result.confirmed:
@@ -85,6 +89,8 @@ class EvidenceCorrelator:
         ep_node = apm.get_node(hypothesis.endpoint_id)
         source_loc = ep_node.location if ep_node else None
 
+        file_path = source_loc.file if source_loc else ""
+
         return Finding(
             id=finding_id,
             title=hypothesis.title,
@@ -97,7 +103,7 @@ class EvidenceCorrelator:
             static_evidence=hypothesis.static_evidence,
             runtime_evidence=runtime_evidence,
             correlation_notes=correlation_notes,
-            remediation=get_remediation_for_category(category_str),
+            remediation=get_remediation_for_category(category_str, filepath=file_path),
             reproduction_steps=test_result.reproduction_steps if test_result else [],
             observations=test_result.observations if test_result else [],
         )

package/src/trace_engine/findings/recommendations.py

@@ -1,12 +1,15 @@
 """Remediation recommendations for security findings."""
 
-REMEDIATION_MAP = {
+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) middleware. "
+        "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": (
@@ -25,11 +28,125 @@ REMEDIATION_MAP = {
         "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
+
+
+def get_remediation_for_category(category: str, filepath: str = "", framework: str = "") -> str:
+    """Returns framework- and language-tailored remediation recommendations."""
+    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.",
+        )
+    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.",
+        )
+    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.",
+        )
 
-def get_remediation_for_category(category: str) -> str:
-    return REMEDIATION_MAP.get(
-        category.upper(),
+    # 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.",
     )

package/src/trace_engine/framework/express.py

@@ -1,82 +1,243 @@
-"""Express.js framework adapter for endpoint discovery."""
-
-import re
-from typing import List
-from trace_engine.parsing.parser import ParsedFile
-from trace_engine.framework.base import FrameworkAdapter, Endpoint, EndpointParameter
-from trace_engine.parsing.locations import SourceLocation
-
-
-class ExpressFrameworkAdapter(FrameworkAdapter):
-    """Detects and extracts Express.js routes and middleware."""
-
-    def can_handle(self, parsed_file: ParsedFile) -> bool:
-        if parsed_file.language not in ("javascript", "typescript"):
-            return False
-        return any("express" in imp.module.lower() for imp in parsed_file.imports)
-
-    def extract_endpoints(self, parsed_file: ParsedFile, content: str) -> List[Endpoint]:
-        endpoints: List[Endpoint] = []
-
-        # Multi-line regex supporting app, router, server, api
-        pattern = re.compile(
-            r"""(?:app|router|server|api)\.(get|post|put|delete|patch)\s*\(\s*["']([^"']+)["']\s*(?:,\s*([^)]+))?""",
-            re.IGNORECASE | re.DOTALL,
-        )
-
-        content_lower = content.lower()
-        has_db_sink = any(
-            term in content_lower
-            for term in ("mongoose", "prisma", "sequelize", "knex", "pool.query", "db.query", "db.collection")
-        )
-        has_ext_sink = any(
-            term in content_lower
-            for term in ("axios", "node-fetch", "fetch(", "needle", "got(", "http.request", "https.request")
-        )
-
-        for match in pattern.finditer(content):
-            method = match.group(1).upper()
-            raw_path = match.group(2)
-            handler_and_middleware = match.group(3) or ""
-
-            # Calculate accurate line number
-            line_no = content[:match.start()].count("\n") + 1
-
-            # Convert Express :id into {id}
-            norm_path = re.sub(r":([a-zA-Z0-9_]+)", r"{\1}", raw_path)
-            path_params = re.findall(r":([a-zA-Z0-9_]+)", raw_path)
-
-            auth_required = any(
-                term in handler_and_middleware.lower()
-                for term in ("auth", "jwt", "passport", "verifytoken", "isauthenticated", "requireauth")
-            )
-            roles = ["admin"] if "admin" in handler_and_middleware.lower() or "admin" in norm_path.lower() else []
-
-            ep_id = f"ep_express_{parsed_file.file_path}_{line_no}_{method}".replace("/", "_").replace(".", "_")
-
-            endpoints.append(
-                Endpoint(
-                    id=ep_id,
-                    method=method,
-                    path=norm_path,
-                    handler_name=f"route_handler_L{line_no}",
-                    auth_required=auth_required,
-                    roles=roles,
-                    parameters=[
-                        EndpointParameter(name=p, location="path", required=True)
-                        for p in path_params
-                    ],
-                    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="admin" in norm_path.lower() or "user" in norm_path.lower() or "order" in norm_path.lower(),
-                    source=SourceLocation(
-                        file=parsed_file.file_path,
-                        line_start=line_no,
-                        line_end=line_no,
-                    ),
-                )
-            )
-
-        return endpoints
+"""Express.js framework adapter for endpoint discovery."""
+
+import re
+from pathlib import Path
+from typing import List, Dict, Tuple, 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 ExpressFrameworkAdapter(FrameworkAdapter):
+    """Detects and extracts Express.js routes and middleware."""
+
+    def __init__(self):
+        # Cache for parsed server/entrypoint mount configurations: {server_file_abs_path: {router_stem: (prefix, has_auth)}}
+        self._server_mount_cache: Dict[str, Dict[str, Tuple[str, bool]]] = {}
+
+    def can_handle(self, parsed_file: ParsedFile) -> bool:
+        if parsed_file.language not in ("javascript", "typescript"):
+            return False
+        # Express route files must import express
+        return any("express" in imp.module.lower() for imp in parsed_file.imports)
+
+    def _discover_server_mounts(self, server_path: Path) -> Dict[str, Tuple[str, bool]]:
+        """Parses server.js / app.js to find router mounts like app.use('/api/discovery', discoveryRoutes)."""
+        resolved_key = str(server_path.resolve())
+        if resolved_key in self._server_mount_cache:
+            return self._server_mount_cache[resolved_key]
+
+        mount_map: Dict[str, Tuple[str, bool]] = {}
+        try:
+            content = server_path.read_text(encoding="utf-8", errors="replace")
+        except Exception:
+            self._server_mount_cache[resolved_key] = mount_map
+            return mount_map
+
+        # 1. Map variable names to imported file stems
+        # e.g., const discoveryRoutes = require('./routes/discoveryRoutes')
+        # or import discoveryRoutes from './routes/discoveryRoutes'
+        var_to_stem: Dict[str, str] = {}
+        import_pattern = re.compile(
+            r"""(?:const|let|var|import)\s+([a-zA-Z0-9_$]+)\s*(?:=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)|from\s*['"]([^'"]+)['"])""",
+            re.IGNORECASE,
+        )
+        for m in import_pattern.finditer(content):
+            var_name = m.group(1).lower()
+            imp_path = m.group(2) or m.group(3) or ""
+            stem = imp_path.replace("\\", "/").split("/")[-1].split(".")[0].lower()
+            if stem:
+                var_to_stem[var_name] = stem
+                var_to_stem[stem] = stem
+
+        # 2. Extract app.use('/prefix', ...) statements
+        # e.g., app.use('/api/discovery', discoveryRoutes);
+        # or app.use('/api/discovery', verifyToken, discoveryRoutes);
+        # or app.use('/api/discovery', require('./routes/discoveryRoutes'));
+        use_pattern = re.compile(
+            r"""(?:app|server|api|router)\.use\s*\(\s*["']([^"']+)["']\s*,\s*([^;]+)\)""",
+            re.IGNORECASE | re.DOTALL,
+        )
+        for m in use_pattern.finditer(content):
+            raw_prefix = m.group(1).strip()
+            prefix = "/" + raw_prefix.strip("/") if raw_prefix.strip("/") else ""
+            args_str = m.group(2)
+
+            args = [a.strip() for a in args_str.split(",") if a.strip()]
+            if not args:
+                continue
+
+            router_arg = args[-1]
+            middleware_args = args[:-1]
+
+            has_auth = any(
+                any(sig in m_arg.lower() for sig in ("auth", "jwt", "passport", "verifytoken", "isauthenticated", "requireauth"))
+                for m_arg in middleware_args
+            )
+
+            # Determine target router stem
+            target_stem = ""
+            inline_req = re.search(r"""require\s*\(\s*['"]([^'"]+)['"]\s*\)""", router_arg)
+            if inline_req:
+                req_path = inline_req.group(1)
+                target_stem = req_path.replace("\\", "/").split("/")[-1].split(".")[0].lower()
+            else:
+                var_key = router_arg.strip().split("(")[0].strip().lower()
+                target_stem = var_to_stem.get(var_key, var_key)
+
+            if target_stem:
+                mount_map[target_stem] = (prefix, has_auth)
+                core_stem = re.sub(r'routes?$', '', target_stem)
+                if core_stem and core_stem != target_stem:
+                    mount_map[core_stem] = (prefix, has_auth)
+
+        self._server_mount_cache[resolved_key] = mount_map
+        return mount_map
+
+    def _resolve_mount_prefix_and_auth(self, parsed_file: ParsedFile) -> Tuple[str, bool]:
+        """Resolves the mount prefix and any mount-level authentication middleware for this file."""
+        norm_path = parsed_file.file_path.replace("\\", "/")
+        filename = norm_path.split("/")[-1]
+        stem = filename.rsplit(".", 1)[0].lower()
+        core_stem = re.sub(r'routes?$', '', stem)
+
+        # Candidate directories to look for server files
+        start_path = Path(parsed_file.absolute_path or parsed_file.file_path).resolve()
+        candidate_dirs = [start_path.parent]
+        for p in start_path.parents:
+            candidate_dirs.append(p)
+            if len(candidate_dirs) > 5:
+                break
+
+        server_names = (
+            "server.js", "server.ts", "server.mjs", "server.cjs",
+            "app.js", "app.ts", "app.mjs", "app.cjs",
+            "index.js", "index.ts", "index.mjs", "index.cjs",
+            "main.js", "main.ts",
+        )
+
+        for cdir in candidate_dirs:
+            # Check server files directly in cdir
+            for sname in server_names:
+                candidate_file = cdir / sname
+                if candidate_file.is_file():
+                    mounts = self._discover_server_mounts(candidate_file)
+                    if stem in mounts:
+                        return mounts[stem]
+                    if core_stem in mounts:
+                        return mounts[core_stem]
+                    for k, (pref, has_auth) in mounts.items():
+                        if k in norm_path.lower():
+                            return (pref, has_auth)
+
+            # Check subdirectories like backend/ or src/
+            for subdir in ("backend", "server", "src"):
+                for sname in server_names:
+                    candidate_file = cdir / subdir / sname
+                    if candidate_file.is_file():
+                        mounts = self._discover_server_mounts(candidate_file)
+                        if stem in mounts:
+                            return mounts[stem]
+                        if core_stem in mounts:
+                            return mounts[core_stem]
+                        for k, (pref, has_auth) in mounts.items():
+                            if k in norm_path.lower():
+                                return (pref, has_auth)
+
+        return ("", False)
+
+    def extract_endpoints(self, parsed_file: ParsedFile, content: str) -> List[Endpoint]:
+        endpoints: List[Endpoint] = []
+
+        # Multi-line regex supporting app, router, server, api
+        pattern = re.compile(
+            r"""(?:app|router|server|api)\.(get|post|put|delete|patch)\s*\(\s*["']([^"']+)["']\s*(?:,\s*([^)]+))?""",
+            re.IGNORECASE | re.DOTALL,
+        )
+
+        content_lower = content.lower()
+        has_db_sink = any(
+            term in content_lower
+            for term in ("mongoose", "prisma", "sequelize", "knex", "pool.query", "db.query", "db.collection")
+        )
+        has_ext_sink = any(
+            term in content_lower
+            for term in ("axios", "node-fetch", "fetch(", "needle", "got(", "http.request", "https.request")
+        )
+
+        # File-level router middleware: e.g. router.use(verifyToken)
+        file_has_auth = bool(
+            re.search(
+                r"""(?:router|app)\.use\s*\(\s*[^)]*(?:auth|jwt|passport|verifytoken|isauthenticated|requireauth)""",
+                content,
+                re.IGNORECASE,
+            )
+        )
+
+        # Discover parent mount prefix and mount-level auth
+        mount_prefix, mount_has_auth = self._resolve_mount_prefix_and_auth(parsed_file)
+
+        for match in pattern.finditer(content):
+            method = match.group(1).upper()
+            raw_path = match.group(2)
+            handler_and_middleware = match.group(3) or ""
+
+            # Calculate accurate line number
+            line_no = content[:match.start()].count("\n") + 1
+
+            # Convert Express :id into {id}
+            norm_sub_path = re.sub(r":([a-zA-Z0-9_]+)", r"{\1}", raw_path)
+            path_params = re.findall(r":([a-zA-Z0-9_]+)", raw_path)
+
+            # Prepend mount prefix if available
+            if mount_prefix:
+                if norm_sub_path == "/" or not norm_sub_path:
+                    final_path = mount_prefix
+                elif norm_sub_path.startswith(mount_prefix):
+                    final_path = norm_sub_path
+                else:
+                    final_path = f"{mount_prefix}/{norm_sub_path.lstrip('/')}"
+            else:
+                final_path = norm_sub_path
+
+            # Clean duplicate slashes
+            final_path = re.sub(r"/+", "/", final_path)
+
+            route_auth = any(
+                term in handler_and_middleware.lower()
+                for term in ("auth", "jwt", "passport", "verifytoken", "isauthenticated", "requireauth")
+            )
+            auth_required = file_has_auth or mount_has_auth or route_auth
+            roles = ["admin"] if "admin" in handler_and_middleware.lower() or "admin" in final_path.lower() else []
+
+            ep_id = f"ep_express_{parsed_file.file_path}_{line_no}_{method}".replace("/", "_").replace(".", "_")
+
+            endpoints.append(
+                Endpoint(
+                    id=ep_id,
+                    method=method,
+                    path=final_path,
+                    handler_name=f"route_handler_L{line_no}",
+                    auth_required=auth_required,
+                    roles=roles,
+                    parameters=[
+                        EndpointParameter(name=p, location="path", required=True)
+                        for p in path_params
+                    ],
+                    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=any(
+                        term in final_path.lower()
+                        for term in ("admin", "user", "order", "deliverable", "workspace", "account", "profile")
+                    ),
+                    source=SourceLocation(
+                        file=parsed_file.file_path,
+                        line_start=line_no,
+                        line_end=line_no,
+                    ),
+                )
+            )
+
+        return endpoints

package/src/trace_engine/framework/nextjs.py

@@ -58,20 +58,44 @@ class NextJSFrameworkAdapter(FrameworkAdapter):
         if parsed_file.language not in ("javascript", "typescript"):
             return False
 
-        norm_path = parsed_file.file_path.replace("\\", "/")
+        norm_path = parsed_file.file_path.replace("\\", "/").lower()
 
-        # App Router route/page
-        if re.search(r'(?:^|/)(?:src/)?app/.+/(?:route|page)\.[a-zA-Z0-9]+$', norm_path):
+        # 1. Reject build & tool configurations (e.g. next.config.ts, tailwind.config.js, etc.)
+        if re.search(r'(?:^|/)[a-zA-Z0-9_\.-]*\.config\.[a-zA-Z0-9]+$', norm_path):
+            return False
+
+        # 2. Reject UI component directories and non-API code
+        non_endpoint_dirs = (
+            "/components/", "/ui/", "/layouts/", "/widgets/",
+            "/hooks/", "/context/", "/styles/", "/types/",
+            "/lib/", "/utils/", "/helpers/", "/assets/", "/icons/"
+        )
+        if any(d in norm_path for d in non_endpoint_dirs) or any(norm_path.startswith(d.lstrip("/")) for d in non_endpoint_dirs):
+            return False
+
+        # 3. Reject client-side UI component suffixes (e.g. RegisterForm.tsx, DashboardHeader.tsx)
+        ui_suffixes = (
+            "form.tsx", "form.jsx", "header.tsx", "header.jsx",
+            "bar.tsx", "bar.jsx", "modal.tsx", "modal.jsx",
+            "card.tsx", "card.jsx", "layout.tsx", "layout.jsx",
+            "button.tsx", "button.jsx", "table.tsx", "table.jsx",
+            "view.tsx", "view.jsx", "provider.tsx", "provider.jsx"
+        )
+        if any(norm_path.endswith(s) for s in ui_suffixes):
+            return False
+
+        # 4. App Router: HTTP endpoints are strictly route.ts or route.js
+        if re.search(r'(?:^|/)(?:src/)?app/.+/route\.[a-zA-Z0-9]+$', norm_path):
             return True
 
-        # Pages Router api or page
-        if re.search(r'(?:^|/)(?:src/)?pages/(?:api/)?.+\.[a-zA-Z0-9]+$', norm_path):
+        # 5. Pages Router: HTTP endpoints are strictly inside pages/api/
+        if re.search(r'(?:^|/)(?:src/)?pages/api/.+\.[a-zA-Z0-9]+$', norm_path):
             return True
 
-        # Imports from next
+        # 6. Only handle if explicitly importing next/server (e.g. NextRequest, NextResponse)
         for imp in parsed_file.imports:
             mod_low = imp.module.lower()
-            if mod_low == "next" or mod_low.startswith("next/"):
+            if mod_low == "next/server":
                 return True
 
         return False
@@ -79,16 +103,27 @@ class NextJSFrameworkAdapter(FrameworkAdapter):
     def extract_endpoints(self, parsed_file: ParsedFile, content: str) -> List[Endpoint]:
         endpoints: List[Endpoint] = []
         norm_file_path = parsed_file.file_path.replace("\\", "/")
+        norm_lower = norm_file_path.lower()
 
-        is_app_router = bool(re.search(r'(?:^|/)(?:src/)?app/', norm_file_path))
-        is_pages_router = bool(re.search(r'(?:^|/)(?:src/)?pages/', norm_file_path))
+        # Reject client-side components with 'use client'
+        if "'use client'" in content or '"use client"' in content:
+            return []
+
+        # Reject build configurations
+        if ".config." in norm_lower:
+            return []
+
+        is_app_router = bool(re.search(r'(?:^|/)(?:src/)?app/.+/route\.[a-zA-Z0-9]+$', norm_lower))
+        is_pages_router = bool(re.search(r'(?:^|/)(?:src/)?pages/api/.+\.[a-zA-Z0-9]+$', norm_lower))
+
+        # In Next.js, only App Router route handlers and Pages Router API files are REST endpoints
+        if not is_app_router and not is_pages_router:
+            return []
 
         if is_app_router:
             url_path = self._infer_app_router_path(norm_file_path)
-        elif is_pages_router:
-            url_path = self._infer_pages_router_path(norm_file_path)
         else:
-            url_path = "/" + norm_file_path.split("/")[-1].split(".")[0]
+            url_path = self._infer_pages_router_path(norm_file_path)
 
         path_params = re.findall(r'\{([a-zA-Z0-9_]+)\}', url_path)
 
@@ -164,14 +199,18 @@ class NextJSFrameworkAdapter(FrameworkAdapter):
                 )
             )
 
-        # Pages Router or App Router default export
-        if not endpoints:
+        # Pages Router default export handler (strictly pages/api/*)
+        if not endpoints and is_pages_router:
             # Check for checked HTTP methods in handler body
             checked_methods = []
             for m in re.finditer(r'''req\.method\s*===?\s*["'](GET|POST|PUT|DELETE|PATCH)["']''', content):
                 checked_methods.append(m.group(1).upper())
 
-            methods_to_add = set(checked_methods) if checked_methods else (["GET"] if "page." in norm_file_path else ["GET", "POST"])
+            default_match = re.search(r'''export\s+default\s+(?:async\s+)?(?:function|const|class)?\s*([a-zA-Z0-9_$]+)?''', content)
+            if not default_match:
+                return endpoints
+
+            methods_to_add = set(checked_methods) if checked_methods else ["GET", "POST"]
 
             default_match = re.search(r'''export\s+default\s+(?:async\s+)?(?:function|const|class)?\s*([a-zA-Z0-9_$]+)?''', content)
             handler_name = default_match.group(1) if (default_match and default_match.group(1)) else "handler"

package/src/trace_engine/framework/react_router.py

@@ -108,11 +108,30 @@ class ReactRouterFrameworkAdapter(FrameworkAdapter):
         if parsed_file.language not in ("javascript", "typescript"):
             return False
 
-        norm_path = parsed_file.file_path.replace("\\", "/")
+        norm_path = parsed_file.file_path.replace("\\", "/").lower()
         basename = norm_path.split("/")[-1]
 
-        # Ignore configuration files and hidden/dot files
-        if "config" in basename.lower() or basename.startswith("."):
+        # Ignore configuration files, test files, and hidden/dot files
+        if "config" in basename or basename.startswith(".") or ".test." in basename or ".spec." in basename:
+            return False
+
+        # Reject Express / Koa / Fastify backend route files
+        for imp in parsed_file.imports:
+            imp_low = imp.module.lower()
+            if imp_low in ("express", "koa", "fastify", "hapi", "@nestjs/common"):
+                return False
+
+        # Reject backend directories (Express / Node.js backend controllers are not React Router)
+        if any(norm_path.startswith(d) or f"/{d}" in norm_path for d in ("backend/", "server/", "api/", "controllers/", "srv/")):
+            return False
+
+        # Reject UI component directories and non-route code
+        non_route_dirs = (
+            "/components/", "/ui/", "/layouts/", "/widgets/",
+            "/hooks/", "/context/", "/styles/", "/types/",
+            "/lib/", "/utils/", "/helpers/", "/assets/", "/icons/"
+        )
+        if any(d in norm_path for d in non_route_dirs) or any(norm_path.startswith(d.lstrip("/")) for d in non_route_dirs):
             return False
 
         # If it's the routes configuration file itself
@@ -127,10 +146,9 @@ class ReactRouterFrameworkAdapter(FrameworkAdapter):
         if key in self._route_cache:
             return True
 
-        # Check if file is within a routes directory (Remix / React Router convention)
-        if "/routes/" in norm_path or norm_path.startswith("routes/"):
-            # Exclude non-route subdirectories like styles, assets, or types
-            if any(f"/{d}/" in norm_path for d in ("styles", "assets", "types", "+types")):
+        # Only match files strictly in frontend routes directory (app/routes/ or src/routes/)
+        if re.search(r'(?:^|/)(?:src/|app/)?routes/.+\.[a-zA-Z0-9]+$', norm_path):
+            if any(f"/{d}/" in norm_path for d in ("styles", "assets", "types", "+types", "components")):
                 return False
             return True
 
@@ -303,29 +321,6 @@ class ReactRouterFrameworkAdapter(FrameworkAdapter):
                 )
             )
 
-        # If file is a route file (e.g. in routes/ or mapped) but defines neither loader nor action nor verbs,
-        # it is a page component serving GET
-        if not endpoints:
-            default_match = re.search(r'''export\s+default\s+(?:function|const|class)?\s*([a-zA-Z0-9_$]+)?''', content)
-            handler_name = default_match.group(1) if (default_match and default_match.group(1)) else "default"
-            line_no = content[:default_match.start()].count("\n") + 1 if default_match else 1
-            ep_id = f"ep_rr_page_{norm_file_path}_{line_no}".replace("/", "_").replace(".", "_")
-            endpoints.append(
-                Endpoint(
-                    id=ep_id,
-                    method="GET",
-                    path=url_path,
-                    handler_name=handler_name,
-                    auth_required=auth_required,
-                    roles=roles,
-                    parameters=parameters,
-                    database_access=has_db_sink,
-                    object_identifier=bool(path_params),
-                    state_changing=False,
-                    external_network=has_ext_sink,
-                    sensitive_data=sensitive_data,
-                    source=SourceLocation(file=parsed_file.file_path, line_start=line_no, line_end=line_no),
-                )
-            )
-
+        # If file defines neither loader nor action nor explicit HTTP verbs, it is a pure UI component
+        # and has no backend server attack surface
         return endpoints

package/src/trace_engine/interactive.py

@@ -87,11 +87,15 @@ def render_big_logo() -> Text:
 
 def render_big_banner(animated: bool = False) -> None:
     """Renders the sleek minimalist TRACE banner in Mint Green and Crisp White."""
+    from trace_engine.intelligence.downloader import is_environment_ready
+    models_ready = is_environment_ready()
+
     console.print()
     console.print(render_big_logo())
-    console.print(f"  [{BOLD_WHITE}]Threat Reconnaissance & Attack-path Correlation Engine[/{BOLD_WHITE}]  [{GREEN}]v2.1.0[/{GREEN}]")
+    console.print(f"  [{BOLD_WHITE}]Threat Reconnaissance & Attack-path Correlation Engine[/{BOLD_WHITE}]  [{GREEN}]v2.1.8[/{GREEN}]")
     console.print(f"  [{DIM_WHITE}]Autonomous Neuro-Symbolic Security Intelligence & Live Verification[/{DIM_WHITE}]")
-    console.print(f"  [{GREEN}]● 100% Offline[/{GREEN}]  [{WHITE}]•[/{WHITE}]  [{GREEN}]● Zero External Telemetry[/{GREEN}]  [{WHITE}]•[/{WHITE}]  [{GREEN}]● SecureBERT & Laya AI Active[/{GREEN}]")
+    ai_status = f"[{GREEN}]● SecureBERT & Laya AI Active[/{GREEN}]" if models_ready else f"[{ORANGE}]● Neural Weights: Optional (AST Semantic Engine Active)[/{ORANGE}]"
+    console.print(f"  [{GREEN}]● 100% Offline[/{GREEN}]  [{WHITE}]•[/{WHITE}]  [{GREEN}]● Zero External Telemetry[/{GREEN}]  [{WHITE}]•[/{WHITE}]  {ai_status}")
     console.print(f"  [{DIM_GREEN}]{'─' * 76}[/{DIM_GREEN}]\n")
     if animated:
         time.sleep(0.08)
@@ -123,12 +127,19 @@ def ask_input(
           "QUIT",
           "Q",
       ]
-    val = Prompt.ask(
-        prompt_str,
-        choices=allowed_choices,
-        default=default,
-        show_default=show_default,
-    )
+    try:
+        val = Prompt.ask(
+            prompt_str,
+            choices=allowed_choices,
+            default=default,
+            show_default=show_default,
+        )
+    except (EOFError, KeyboardInterrupt):
+        if default is not None:
+            return default
+        console.print(f"\n  [{GREEN}]✓ TRACE session closed. Happy hacking![/{GREEN}]\n")
+        sys.exit(0)
+
     if str(val).strip().lower() in ("exit", "quit", "q", ":q"):
       console.print(
           f"\n  [{GREEN}]✓ TRACE session closed. Happy hacking![/{GREEN}]\n"
@@ -278,9 +289,8 @@ def run_interactive_story() -> None:
     """Executes the complete interactive, step-by-step security audit story."""
     render_big_banner(animated=True)
 
-    from trace_engine.intelligence.downloader import prompt_and_bootstrap_models
-    if not prompt_and_bootstrap_models(interactive=True):
-        return
+    from trace_engine.intelligence.downloader import is_environment_ready, ensure_all_models
+    models_ready = is_environment_ready()
 
     console.print(f"  [{WHITE}]Welcome, Security Operator. TRACE stands ready to audit, verify, and heal codebases.[/{WHITE}]")
     console.print(f"  [{DIM_WHITE}]Navigate using the options below (type 'exit' or 'q' at any prompt to quit).[/{DIM_WHITE}]\n")
@@ -289,25 +299,42 @@ def run_interactive_story() -> None:
     # STEP 1: Mission Selection
     # =========================================================================
     console.print(f"  [{BOLD_WHITE}]Select Audit Mission:[/{BOLD_WHITE}]")
-    console.print(f"    [{ORANGE}][1][/{ORANGE}] [{BOLD_WHITE}]Full Security Audit[/{BOLD_WHITE}] [{GREEN}]★ RECOMMENDED[/{GREEN}] [{DIM_WHITE}]─ Multi-language AST, APM graph, & Neural AI[/{DIM_WHITE}]")
+    console.print(f"    [{ORANGE}][1][/{ORANGE}] [{BOLD_WHITE}]Full Security Audit[/{BOLD_WHITE}] [{GREEN}]★ RECOMMENDED[/{GREEN}] [{DIM_WHITE}]─ Multi-language AST, APM graph, & Security Hypotheses[/{DIM_WHITE}]")
     console.print(f"    [{ORANGE}][2][/{ORANGE}] [{BOLD_WHITE}]Targeted Vulnerability Probes[/{BOLD_WHITE}] [{DIM_WHITE}]─ Select specific testpacks (BOLA, SQLi, SSRF, BFLA)[/{DIM_WHITE}]")
     console.print(f"    [{ORANGE}][3][/{ORANGE}] [{BOLD_WHITE}]Autonomous AST Self-Healing[/{BOLD_WHITE}] [{DIM_WHITE}]─ Surgical refactoring with live rollback verification[/{DIM_WHITE}]")
     console.print(f"    [{ORANGE}][4][/{ORANGE}] [{BOLD_WHITE}]Start Claude Code Local MCP Server[/{BOLD_WHITE}] [{GREEN}]★ LOCAL MCP[/{GREEN}] [{DIM_WHITE}]─ Run HTTP/SSE bridge for Claude Code chat[/{DIM_WHITE}]")
-    console.print(f"    [{ORANGE}][5][/{ORANGE}] [{BOLD_WHITE}]How TRACE Works & Architecture Guide[/{BOLD_WHITE}] [{DIM_WHITE}]─ Interactive architectural diagram & neural models[/{DIM_WHITE}]")
+    console.print(f"    [{ORANGE}][5][/{ORANGE}] [{BOLD_WHITE}]How TRACE Works & Architecture Guide[/{BOLD_WHITE}] [{DIM_WHITE}]─ Interactive architectural diagram & operational FAQ[/{DIM_WHITE}]")
     console.print(f"    [{ORANGE}][6][/{ORANGE}] [{BOLD_WHITE}]Environment Diagnostics (Doctor)[/{BOLD_WHITE}] [{DIM_WHITE}]─ Inspect local security tools and dependencies[/{DIM_WHITE}]")
-    console.print(f"    [{ORANGE}][7][/{ORANGE}] [{BOLD_WHITE}]Exit[/{BOLD_WHITE}]\n")
+    if not models_ready:
+        console.print(f"    [{ORANGE}][7][/{ORANGE}] [{BOLD_WHITE}]Download Neural Weights[/{BOLD_WHITE}] [{DIM_WHITE}]─ Provision ~1 GB SecureBERT 2.0 & Laya AI into ~/.trace/models[/{DIM_WHITE}]")
+        console.print(f"    [{ORANGE}][8][/{ORANGE}] [{BOLD_WHITE}]Exit[/{BOLD_WHITE}]\n")
+        valid_choices = ["1", "2", "3", "4", "5", "6", "7", "8"]
+    else:
+        console.print(f"    [{ORANGE}][7][/{ORANGE}] [{BOLD_WHITE}]Exit[/{BOLD_WHITE}]\n")
+        valid_choices = ["1", "2", "3", "4", "5", "6", "7"]
 
     choice = ask_input(
         f"  [{ORANGE}]›[/{ORANGE}] [{BOLD_WHITE}]Choose option[/{BOLD_WHITE}]",
-        choices=["1", "2", "3", "4", "5", "6", "7"],
+        choices=valid_choices,
         default="1",
         show_default=True,
     )
 
-    if choice == "7":
+    if (not models_ready and choice == "8") or (models_ready and choice == "7"):
         console.print(f"\n  [{GREEN}]✓ TRACE session closed. Happy hacking![/{GREEN}]\n")
         return
 
+    if not models_ready and choice == "7":
+        display_story_header(2, 2, "Neural Model Provisioning", "Downloading fine-tuned SecureBERT 2.0 & Laya AI from GitHub LFS Hub")
+        console.print(f"  [{WHITE}]Downloading fine-tuned neural models into ~/.trace/models/...[/{WHITE}]")
+        try:
+            ensure_all_models()
+            console.print(f"\n  [{GREEN}]✓ Neural models provisioned successfully. SecureBERT & Laya are now online![/{GREEN}]\n")
+        except Exception as e:
+            console.print(f"\n  [{ORANGE}][!] Download could not complete:[/{ORANGE}] [{WHITE}]{e}[/{WHITE}]")
+            console.print(f"  [{DIM_WHITE}]You can continue using TRACE with the built-in deterministic AST & semantic engine.[/{DIM_WHITE}]\n")
+        return
+
     if choice == "4":
         from trace_engine.mcp.server import TraceMCPServer
         mcp_obj = TraceMCPServer()
@@ -484,7 +511,8 @@ def run_interactive_story() -> None:
 
     # Phase 3: Neuro-Symbolic Bayesian Hypotheses with Real Models
     model_metrics: Dict[str, Any] = {}
-    with console.status(f"  [{GREEN}]Act III:[/{GREEN}] [{WHITE}]Evaluating SecureBERT 2.0 & Laya System 1 Neural Models on GPU...[/{WHITE}]", spinner="dots"):
+    act3_status = "Evaluating SecureBERT 2.0 & Laya System 1 Neural Models..." if models_ready else "Evaluating Security Hypotheses with AST Semantic Engine..."
+    with console.status(f"  [{GREEN}]Act III:[/{GREEN}] [{WHITE}]{act3_status}[/{WHITE}]", spinner="dots"):
         engine = HypothesisEngine()
         all_hypotheses = engine.derive_hypotheses(graph_model, discovered_endpoints)
 
@@ -518,8 +546,9 @@ def run_interactive_story() -> None:
                 "laya": {"inferences": len(discovered_endpoints), "avg_latency_ms": 0.5, "breakdown": "Evaluated across P0/P1/P2/P3", "available": True},
             }
 
+    engine_label = "via SecureBERT & Laya" if models_ready else "via AST Semantic Engine"
     console.print(
-        f"  [{GREEN}]✓ Act III (Neural AI & Hypotheses):[/{GREEN}] [{BOLD_WHITE}]Derived {len(hypotheses)} threat hypotheses[/{BOLD_WHITE}] [{DIM_WHITE}]via SecureBERT & Laya[/{DIM_WHITE}]"
+        f"  [{GREEN}]✓ Act III (Security Hypotheses):[/{GREEN}] [{BOLD_WHITE}]Derived {len(hypotheses)} threat hypotheses[/{BOLD_WHITE}] [{DIM_WHITE}]{engine_label}[/{DIM_WHITE}]"
     )
 
     # Phase 4: Dynamic Exploit Probes

package/src/trace_engine/security/hypotheses.py

@@ -89,7 +89,13 @@ class HypothesisEngine:
 
             # 3. Authentication Bypass / Missing Auth: State-changing endpoint without auth
             if not ep.auth_required and (ep.state_changing or ep.sensitive_data):
-                if not ep.path.endswith("/login") and not ep.path.endswith("/register"):
+                path_segs = [s.lower() for s in ep.path.strip("/").split("/")]
+                is_public_by_design = any(
+                    s in ("login", "signin", "register", "signup", "forgot-password", "reset-password", "callback", "oauth", "health", "ping", "status", "public", "docs", "openapi")
+                    or s.startswith("auth-callback") or s.endswith("-callback")
+                    for s in path_segs
+                )
+                if not is_public_by_design:
                     hypotheses.append(
                         SecurityHypothesis(
                             id=f"HYP-AUTH-{hypo_idx:03d}",
@@ -109,8 +115,17 @@ class HypothesisEngine:
                     )
                     hypo_idx += 1
 
-            # 4. SSRF Hypothesis: Endpoint takes URL or makes external network calls
-            if ep.external_network or any("url" in p.name.lower() for p in ep.parameters):
+            # 4. SSRF Hypothesis: Endpoint takes user-supplied URL/target AND makes outbound HTTP calls
+            url_params = [
+                p.name for p in ep.parameters
+                if any(
+                    term == p.name.lower()
+                    or p.name.lower().endswith(f"_{term}")
+                    or p.name.lower().endswith(term.capitalize())
+                    for term in ("url", "uri", "target", "webhook", "callback", "dest", "destination", "endpoint", "feed", "proxy", "redirect_uri")
+                )
+            ]
+            if ep.external_network and url_params:
                 hypotheses.append(
                     SecurityHypothesis(
                         id=f"HYP-SSRF-{hypo_idx:03d}",
@@ -118,12 +133,12 @@ class HypothesisEngine:
                         endpoint_id=ep.id,
                         endpoint_display=ep_disp,
                         title=f"Potential SSRF on {ep_disp}",
-                        description="Endpoint handles URL parameter and communicates with outbound HTTP client.",
+                        description="Endpoint accepts user-controlled destination URL and dispatches outbound HTTP requests.",
                         recommended_test_pack="ssrf",
                         confidence_prior=0.85,
                         static_evidence=[
                             "Outbound HTTP client calls detected in handler body",
-                            f"URL parameter detected: {[p.name for p in ep.parameters if 'url' in p.name.lower()]}",
+                            f"User-controlled URL parameters: {url_params}",
                         ],
                     )
                 )
@@ -169,9 +184,22 @@ class HypothesisEngine:
                 )
                 hypo_idx += 1
 
-            # 7. Path Traversal Hypothesis: Endpoints accepting file or path parameters
-            file_param_names = [p.name for p in ep.parameters if any(term in p.name.lower() for term in ("file", "path", "doc", "dir", "download", "name", "asset", "key"))]
-            if file_param_names or any(term in ep.path.lower() for term in ("file", "doc", "download", "asset", "static")):
+            # 7. Path Traversal Hypothesis: Endpoints accepting genuine file or directory path parameters
+            file_param_names = [
+                p.name for p in ep.parameters
+                if p.name.lower() in (
+                    "file", "path", "filename", "file_name", "filepath", "file_path",
+                    "doc_path", "document", "attachment", "dir_path", "download_path"
+                ) or any(
+                    p.name.lower().endswith(f"_{term}")
+                    for term in ("file", "path", "filename", "filepath")
+                )
+            ]
+            path_segments = [seg.lower() for seg in ep.path.strip("/").split("/")]
+            has_file_route = any(seg in ("file", "files", "download", "downloads", "static", "assets", "document", "documents") for seg in path_segments)
+
+            # Must have actual file parameter or file route with parameters
+            if file_param_names or (has_file_route and ep.parameters):
                 hypotheses.append(
                     SecurityHypothesis(
                         id=f"HYP-TRAV-{hypo_idx:03d}",