openhack 0.1.0__py3-none-any.whl

openhack/tools/filesystem.py

@@ -0,0 +1,404 @@
+"""
+File system tools for vulnerability scanning.
+Provides safe, jailed access to the target directory.
+"""
+
+import fnmatch
+import inspect
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+_GREP_EXCLUDE_DIRS = [
+    ".git", "node_modules", "__pycache__", ".venv", "venv",
+    "dist", "build", ".next", ".nuxt", ".output",
+    "vendor", "target", "coverage", ".mypy_cache",
+    ".pytest_cache", ".tox", "eggs", "*.egg-info",
+]
+
+_GREP_SOURCE_INCLUDES = [
+    "*.py", "*.js", "*.ts", "*.tsx", "*.jsx",
+    "*.rb", "*.go", "*.rs", "*.java", "*.php",
+    "*.c", "*.cpp", "*.h",
+    "*.vue", "*.svelte",
+]
+
+
+class FileSystemTools:
+    """File system tools with path safety enforcement."""
+
+    def __init__(self, jail_dir: Path):
+        self.jail_dir = jail_dir.resolve()
+
+    def _resolve_safe_path(self, path: str) -> Path:
+        """Resolve a path safely within the jail directory."""
+        requested = (self.jail_dir / path).resolve()
+        if not str(requested).startswith(str(self.jail_dir)):
+            raise PermissionError(f"Access denied: {path} is outside the allowed directory")
+        return requested
+
+    BINARY_EXTENSIONS = frozenset({
+        ".zip", ".gz", ".tar", ".bz2", ".xz", ".7z", ".rar",
+        ".jar", ".war", ".ear", ".class",
+        ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".webp", ".svg",
+        ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
+        ".woff", ".woff2", ".ttf", ".eot", ".otf",
+        ".exe", ".dll", ".so", ".dylib", ".o", ".a",
+        ".pyc", ".pyo", ".wasm",
+        ".sqlite", ".db", ".sqlite3",
+        ".mp3", ".mp4", ".avi", ".mov", ".wav", ".flac",
+        ".bin", ".dat", ".iso", ".img",
+        ".sql", ".csv", ".tsv", ".log", ".dump",
+    })
+    MAX_FILE_SIZE = 200_000  # 200KB — files larger than this are truncated
+    MAX_LINES_DEFAULT = 1000
+
+    def read_file(self, path: str, offset: int = 0, limit: Optional[int] = None) -> dict:
+        """Read the contents of a file with line numbers."""
+        try:
+            resolved = self._resolve_safe_path(path)
+            if not resolved.exists():
+                return {"error": f"File not found: {path}"}
+            if not resolved.is_file():
+                return {"error": f"Not a file: {path}"}
+
+            if resolved.suffix.lower() in self.BINARY_EXTENSIONS:
+                size = resolved.stat().st_size
+                return {
+                    "path": str(resolved.relative_to(self.jail_dir)),
+                    "content": f"[Binary file: {resolved.suffix}, {size:,} bytes — cannot read]",
+                    "total_lines": 0,
+                    "binary": True,
+                }
+
+            file_size = resolved.stat().st_size
+            if file_size > self.MAX_FILE_SIZE:
+                effective_limit = limit or self.MAX_LINES_DEFAULT
+            else:
+                effective_limit = limit
+
+            if effective_limit and file_size > self.MAX_FILE_SIZE:
+                with open(resolved, "r", encoding="utf-8", errors="replace") as f:
+                    lines = []
+                    for _ in range(offset):
+                        if not f.readline():
+                            break
+                    for _ in range(effective_limit):
+                        line = f.readline()
+                        if not line:
+                            break
+                        lines.append(line)
+                    remaining = sum(1 for _ in f)
+                total_lines = offset + len(lines) + remaining
+                was_truncated = remaining > 0
+            else:
+                with open(resolved, "r", encoding="utf-8", errors="replace") as f:
+                    lines = f.readlines()
+                total_lines = len(lines)
+                if effective_limit:
+                    lines = lines[offset : offset + effective_limit]
+                    was_truncated = (offset + effective_limit) < total_lines
+                else:
+                    lines = lines[offset:]
+                    was_truncated = False
+
+            numbered_lines = []
+            for i, line in enumerate(lines, start=offset + 1):
+                numbered_lines.append(f"{i:6}\t{line.rstrip()}")
+
+            if was_truncated and file_size > self.MAX_FILE_SIZE:
+                numbered_lines.append(f"\n[... file truncated: {total_lines:,} total lines, {file_size:,} bytes — use offset/limit to read more ...]")
+
+            return {
+                "path": str(resolved.relative_to(self.jail_dir)),
+                "content": "\n".join(numbered_lines),
+                "total_lines": total_lines,
+                "offset": offset,
+                "lines_returned": len(numbered_lines),
+            }
+        except PermissionError as e:
+            return {"error": str(e)}
+        except Exception as e:
+            return {"error": f"Error reading file: {e}"}
+
+    def list_dir(self, path: str = ".", ignore: Optional[list[str]] = None) -> dict:
+        """List contents of a directory."""
+        try:
+            resolved = self._resolve_safe_path(path)
+            if not resolved.exists():
+                return {"error": f"Directory not found: {path}"}
+            if not resolved.is_dir():
+                return {"error": f"Not a directory: {path}"}
+
+            ignore = ignore or []
+            entries = []
+            for entry in sorted(resolved.iterdir()):
+                rel_path = str(entry.relative_to(self.jail_dir))
+                if any(fnmatch.fnmatch(rel_path, pat) or fnmatch.fnmatch(entry.name, pat) for pat in ignore):
+                    continue
+                entry_type = "dir" if entry.is_dir() else "file"
+                size = entry.stat().st_size if entry.is_file() else None
+                entries.append({"name": entry.name, "type": entry_type, "size": size})
+
+            return {
+                "path": str(resolved.relative_to(self.jail_dir)),
+                "entries": entries,
+            }
+        except PermissionError as e:
+            return {"error": str(e)}
+        except Exception as e:
+            return {"error": f"Error listing directory: {e}"}
+
+    def _expand_braces(self, pattern: str) -> list[str]:
+        """Expand brace patterns like {js,jsx,ts,tsx} into multiple patterns."""
+        import re
+        brace_pattern = re.compile(r'\{([^}]+)\}')
+        match = brace_pattern.search(pattern)
+        if not match:
+            return [pattern]
+        
+        prefix = pattern[:match.start()]
+        suffix = pattern[match.end():]
+        alternatives = match.group(1).split(',')
+        
+        expanded = []
+        for alt in alternatives:
+            expanded.extend(self._expand_braces(prefix + alt.strip() + suffix))
+        return expanded
+
+    def glob(self, pattern: str, path: str = ".") -> dict:
+        """Find files matching a glob pattern recursively.
+
+        Supports brace expansion like {js,jsx,ts,tsx}.
+        Skips known non-source directories for performance.
+        """
+        try:
+            resolved = self._resolve_safe_path(path)
+            if not resolved.exists():
+                return {"error": f"Directory not found: {path}"}
+
+            matches = set()
+            skip_dirs = {d.rstrip("*").rstrip(".") for d in _GREP_EXCLUDE_DIRS}
+
+            expanded_patterns = self._expand_braces(pattern)
+
+            for exp_pattern in expanded_patterns:
+                search_pattern = exp_pattern
+                recursive = False
+                if search_pattern.startswith("**/"):
+                    search_pattern = search_pattern[3:]
+                    recursive = True
+
+                match_path = "/" in search_pattern
+
+                for root, dirs, files in os.walk(resolved):
+                    dirs[:] = [d for d in dirs if d not in skip_dirs]
+                    for f in files:
+                        matched = False
+                        if match_path:
+                            full = Path(root) / f
+                            rel_from_base = str(full.relative_to(resolved))
+                            # Check exact match or any path suffix
+                            if fnmatch.fnmatch(rel_from_base, search_pattern):
+                                matched = True
+                            elif recursive:
+                                parts = rel_from_base.split("/")
+                                for i in range(len(parts)):
+                                    suffix = "/".join(parts[i:])
+                                    if fnmatch.fnmatch(suffix, search_pattern):
+                                        matched = True
+                                        break
+                        else:
+                            matched = fnmatch.fnmatch(f, search_pattern)
+
+                        if matched:
+                            full = Path(root) / f if not match_path else full
+                            rel_path = str(full.relative_to(self.jail_dir))
+                            matches.add(rel_path)
+                            if len(matches) >= 500:
+                                return {"pattern": pattern, "matches": sorted(matches)}
+
+            return {"pattern": pattern, "matches": sorted(matches)[:500]}
+        except PermissionError as e:
+            return {"error": str(e)}
+        except Exception as e:
+            return {"error": f"Error during glob: {e}"}
+
+    def grep(self, pattern: str, path: str = ".", include: Optional[str] = None) -> dict:
+        """Search for a regex pattern in files using system grep for speed."""
+        try:
+            resolved = self._resolve_safe_path(path)
+            if not resolved.exists():
+                return {"error": f"Path not found: {path}"}
+
+            if resolved.is_file():
+                return self._grep_single_file(resolved, pattern)
+
+            cmd = ["grep", "-rEl", "--max-count=3",
+                   "--binary-files=without-match",
+                   pattern, str(resolved)]
+            for d in _GREP_EXCLUDE_DIRS:
+                cmd.insert(1, f"--exclude-dir={d}")
+            if include:
+                cmd.insert(1, f"--include={include}")
+            else:
+                for ext in _GREP_SOURCE_INCLUDES:
+                    cmd.insert(1, f"--include={ext}")
+
+            result = subprocess.run(
+                cmd, capture_output=True, text=True, timeout=30
+            )
+            file_paths = [
+                p.strip() for p in result.stdout.strip().split("\n") if p.strip()
+            ][:100]
+
+            matches = []
+            for fp in file_paths:
+                try:
+                    rel = str(Path(fp).relative_to(self.jail_dir))
+                except ValueError:
+                    rel = fp
+                if "node_modules" in rel or "test" in rel.lower():
+                    continue
+                matches.append({"file": rel, "line": 0, "content": ""})
+                if len(matches) >= 100:
+                    break
+
+            return {"pattern": pattern, "matches": matches}
+        except subprocess.TimeoutExpired:
+            return {"pattern": pattern, "matches": []}
+        except PermissionError as e:
+            return {"error": str(e)}
+        except Exception as e:
+            return {"error": f"Error during grep: {e}"}
+
+    def _grep_single_file(self, file_path: Path, pattern: str) -> dict:
+        """Grep a single file using Python (for when we need line-level results)."""
+        regex = re.compile(pattern, re.IGNORECASE)
+        matches = []
+        try:
+            with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+                for line_num, line in enumerate(f, 1):
+                    if regex.search(line):
+                        matches.append({
+                            "file": str(file_path.relative_to(self.jail_dir)),
+                            "line": line_num,
+                            "content": line.strip()[:200],
+                        })
+                        if len(matches) >= 100:
+                            break
+        except Exception:
+            pass
+        return {"pattern": pattern, "matches": matches}
+
+    def get_tool_definitions(self) -> list[dict]:
+        """Return OpenAI-compatible tool definitions."""
+        return [
+            {
+                "name": "read_file",
+                "description": "Read the contents of a file. Returns line-numbered content.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": "Path to the file (relative to target directory)",
+                        },
+                        "offset": {
+                            "type": "integer",
+                            "description": "Line number to start reading from (0-indexed)",
+                            "default": 0,
+                        },
+                        "limit": {
+                            "type": "integer",
+                            "description": "Maximum number of lines to read",
+                        },
+                    },
+                    "required": ["path"],
+                },
+            },
+            {
+                "name": "list_dir",
+                "description": "List contents of a directory.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": "Path to directory (relative to target)",
+                            "default": ".",
+                        },
+                        "ignore": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Glob patterns to ignore",
+                        },
+                    },
+                },
+            },
+            {
+                "name": "glob",
+                "description": "Find files matching a glob pattern recursively.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "pattern": {
+                            "type": "string",
+                            "description": "Glob pattern (e.g., '*.ts', '**/*.tsx')",
+                        },
+                        "path": {
+                            "type": "string",
+                            "description": "Starting directory",
+                            "default": ".",
+                        },
+                    },
+                    "required": ["pattern"],
+                },
+            },
+            {
+                "name": "grep",
+                "description": "Search for a regex pattern in files.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "pattern": {
+                            "type": "string",
+                            "description": "Regex pattern to search for",
+                        },
+                        "path": {
+                            "type": "string",
+                            "description": "Starting path",
+                            "default": ".",
+                        },
+                        "include": {
+                            "type": "string",
+                            "description": "Glob pattern for files to include (e.g., '*.ts')",
+                        },
+                    },
+                    "required": ["pattern"],
+                },
+            },
+        ]
+
+    def execute_tool(self, name: str, arguments: dict) -> dict:
+        """Execute a tool by name with the given arguments.
+
+        Filters out unexpected keyword arguments that the LLM may hallucinate
+        (e.g., passing 'include' to glob when it only belongs on grep).
+        """
+        tools = {
+            "read_file": self.read_file,
+            "list_dir": self.list_dir,
+            "glob": self.glob,
+            "grep": self.grep,
+        }
+        if name not in tools:
+            return {"error": f"Unknown tool: {name}"}
+
+        func = tools[name]
+        sig = inspect.signature(func)
+        valid_params = set(sig.parameters.keys())
+        filtered_args = {k: v for k, v in arguments.items() if k in valid_params}
+        return func(**filtered_args)

openhack/tools/nextjs.py

@@ -0,0 +1,258 @@
+"""
+Next.js specific analysis tools for vulnerability scanning.
+"""
+
+import json
+import re
+from pathlib import Path
+from typing import Optional
+
+from .filesystem import FileSystemTools
+
+
+class NextJSTools:
+    """Tools for analyzing Next.js application structure and patterns."""
+
+    def __init__(self, fs_tools: FileSystemTools):
+        self.fs = fs_tools
+        self._route_cache: Optional[dict] = None
+        self._project_info_cache: Optional[dict] = None
+
+    def get_project_info(self) -> dict:
+        """Get Next.js project information including router type, TypeScript usage, and version."""
+        if self._project_info_cache:
+            return self._project_info_cache
+
+        info = {
+            "framework": "nextjs",
+            "router_type": None,
+            "has_src_dir": False,
+            "typescript": False,
+            "nextjs_version": None,
+            "has_middleware": False,
+            "has_app_dir": False,
+            "has_pages_dir": False,
+        }
+
+        pkg_result = self.fs.read_file("package.json")
+        if "content" in pkg_result:
+            try:
+                lines = pkg_result["content"].split("\n")
+                content = "\n".join(line.split("\t", 1)[1] if "\t" in line else line for line in lines)
+                pkg = json.loads(content)
+                deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+                if "next" in deps:
+                    info["nextjs_version"] = deps["next"]
+                info["typescript"] = "typescript" in deps
+            except (json.JSONDecodeError, IndexError):
+                pass
+
+        src_check = self.fs.list_dir("src")
+        info["has_src_dir"] = "error" not in src_check
+
+        base = "src" if info["has_src_dir"] else "."
+
+        app_check = self.fs.list_dir(f"{base}/app")
+        info["has_app_dir"] = "error" not in app_check
+
+        pages_check = self.fs.list_dir(f"{base}/pages")
+        info["has_pages_dir"] = "error" not in pages_check
+
+        if info["has_app_dir"]:
+            info["router_type"] = "app"
+        elif info["has_pages_dir"]:
+            info["router_type"] = "pages"
+
+        mw_ts = self.fs.read_file("middleware.ts")
+        mw_js = self.fs.read_file("middleware.js")
+        src_mw_ts = self.fs.read_file("src/middleware.ts")
+        src_mw_js = self.fs.read_file("src/middleware.js")
+        info["has_middleware"] = any(
+            "error" not in r for r in [mw_ts, mw_js, src_mw_ts, src_mw_js]
+        )
+
+        self._project_info_cache = info
+        return info
+
+    def get_route_map(self) -> dict:
+        """Extract all routes from the Next.js application (pages, API routes, route handlers)."""
+        if self._route_cache:
+            return self._route_cache
+
+        info = self.get_project_info()
+        routes = {"app_routes": [], "page_routes": [], "api_routes": []}
+
+        base = "src" if info["has_src_dir"] else "."
+
+        if info["has_app_dir"]:
+            app_files = self.fs.glob("**/page.{js,jsx,ts,tsx}", f"{base}/app")
+            for f in app_files.get("matches", []):
+                route = self._file_to_route(f, f"{base}/app", "app")
+                routes["app_routes"].append({"file": f, "route": route, "type": "page"})
+
+            route_files = self.fs.glob("**/route.{js,ts}", f"{base}/app")
+            for f in route_files.get("matches", []):
+                route = self._file_to_route(f, f"{base}/app", "app")
+                routes["api_routes"].append({"file": f, "route": route, "type": "route_handler"})
+
+        if info["has_pages_dir"]:
+            page_files = self.fs.glob("**/*.{js,jsx,ts,tsx}", f"{base}/pages")
+            for f in page_files.get("matches", []):
+                if "/api/" in f or f.startswith("api/"):
+                    route = self._file_to_route(f, f"{base}/pages", "pages")
+                    routes["api_routes"].append({"file": f, "route": route, "type": "api_route"})
+                elif not f.startswith("_") and "/_" not in f:
+                    route = self._file_to_route(f, f"{base}/pages", "pages")
+                    routes["page_routes"].append({"file": f, "route": route, "type": "page"})
+
+        self._route_cache = routes
+        return routes
+
+    def _file_to_route(self, file_path: str, base_dir: str, router_type: str) -> str:
+        """Convert a file path to a route path."""
+        route = file_path
+        if route.startswith(base_dir):
+            route = route[len(base_dir):]
+        if route.startswith("/"):
+            route = route[1:]
+
+        route = re.sub(r"\.(js|jsx|ts|tsx)$", "", route)
+        route = re.sub(r"/(page|route|index)$", "", route)
+
+        route = re.sub(r"\[\.\.\.(\w+)\]", r"*", route)
+        route = re.sub(r"\[(\w+)\]", r":\1", route)
+
+        if not route.startswith("/"):
+            route = "/" + route
+
+        if route == "/":
+            return "/"
+        return route.rstrip("/")
+
+    def get_server_actions(self) -> dict:
+        """Find all server actions ('use server') in the codebase."""
+        actions = []
+
+        ts_files = self.fs.glob("**/*.{ts,tsx}", ".")
+        js_files = self.fs.glob("**/*.{js,jsx}", ".")
+
+        all_files = ts_files.get("matches", []) + js_files.get("matches", [])
+
+        for file_path in all_files:
+            if "node_modules" in file_path:
+                continue
+
+            content_result = self.fs.read_file(file_path)
+            if "error" in content_result:
+                continue
+
+            content = content_result["content"]
+
+            if '"use server"' in content or "'use server'" in content:
+                lines = content.split("\n")
+                for i, line in enumerate(lines):
+                    if "async function" in line or "export async function" in line:
+                        match = re.search(r"(?:export\s+)?async\s+function\s+(\w+)", line)
+                        if match:
+                            actions.append({
+                                "file": file_path,
+                                "function": match.group(1),
+                                "line": i + 1,
+                            })
+
+        return {"server_actions": actions}
+
+    def get_middleware_config(self) -> dict:
+        """Get the middleware configuration and matcher patterns."""
+        locations = ["middleware.ts", "middleware.js", "src/middleware.ts", "src/middleware.js"]
+
+        for loc in locations:
+            result = self.fs.read_file(loc)
+            if "error" not in result:
+                content = result["content"]
+                config = {"file": loc, "content": content, "matcher": None}
+
+                matcher_match = re.search(r"matcher\s*[=:]\s*(\[[\s\S]*?\]|['\"][^'\"]+['\"])", content)
+                if matcher_match:
+                    config["matcher"] = matcher_match.group(1)
+
+                return config
+
+        return {"error": "No middleware found"}
+
+    def check_dependencies(self) -> dict:
+        """Check package.json for security-relevant dependencies."""
+        result = self.fs.read_file("package.json")
+        if "error" in result:
+            return {"error": "Could not read package.json"}
+
+        try:
+            lines = result["content"].split("\n")
+            content = "\n".join(line.split("\t", 1)[1] if "\t" in line else line for line in lines)
+            pkg = json.loads(content)
+        except (json.JSONDecodeError, IndexError):
+            return {"error": "Could not parse package.json"}
+
+        deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+
+        security_relevant = {
+            "auth": ["next-auth", "@auth/core", "lucia", "clerk", "@clerk/nextjs", "supabase", "@supabase/supabase-js"],
+            "database": ["prisma", "@prisma/client", "drizzle-orm", "mongoose", "pg", "mysql2", "better-sqlite3"],
+            "validation": ["zod", "yup", "joi", "superstruct", "valibot"],
+            "sanitization": ["dompurify", "xss", "sanitize-html", "isomorphic-dompurify"],
+            "csrf": ["csrf", "csurf"],
+            "rate_limiting": ["rate-limiter-flexible", "express-rate-limit", "upstash"],
+        }
+
+        found = {}
+        for category, packages in security_relevant.items():
+            found[category] = [p for p in packages if p in deps]
+
+        return {
+            "all_dependencies": deps,
+            "security_relevant": found,
+        }
+
+    def get_tool_definitions(self) -> list[dict]:
+        """Return OpenAI-compatible tool definitions."""
+        return [
+            {
+                "name": "get_project_info",
+                "description": "Get Next.js project information including router type, TypeScript usage, and version.",
+                "parameters": {"type": "object", "properties": {}},
+            },
+            {
+                "name": "get_route_map",
+                "description": "Extract all routes from the Next.js application (pages, API routes, route handlers).",
+                "parameters": {"type": "object", "properties": {}},
+            },
+            {
+                "name": "get_server_actions",
+                "description": "Find all server actions ('use server') in the codebase.",
+                "parameters": {"type": "object", "properties": {}},
+            },
+            {
+                "name": "get_middleware_config",
+                "description": "Get the middleware configuration and matcher patterns.",
+                "parameters": {"type": "object", "properties": {}},
+            },
+            {
+                "name": "check_dependencies",
+                "description": "Check package.json for security-relevant dependencies.",
+                "parameters": {"type": "object", "properties": {}},
+            },
+        ]
+
+    def execute_tool(self, name: str, arguments: dict) -> dict:
+        """Execute a tool by name with the given arguments."""
+        tools = {
+            "get_project_info": self.get_project_info,
+            "get_route_map": self.get_route_map,
+            "get_server_actions": self.get_server_actions,
+            "get_middleware_config": self.get_middleware_config,
+            "check_dependencies": self.check_dependencies,
+        }
+        if name not in tools:
+            return {"error": f"Unknown tool: {name}"}
+        # These tools take no arguments - ignore any hallucinated arguments from LLM
+        return tools[name]()