openhack 0.1.0__py3-none-any.whl

openhack/framework_detection.py

@@ -0,0 +1,269 @@
+"""
+Deterministic framework detection for vulnerability scanning.
+
+Detects the tech stack of a target repository by reading indicator files
+(package.json, manage.py, requirements.txt, etc.) and returns a list of
+detected frameworks with their root directories. Supports monorepos where
+multiple frameworks live in different subdirectories.
+
+No LLM calls -- pure file existence + content checks.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from openhack.tools.filesystem import FileSystemTools
+
+
+SKIP_DIRS = {
+    "node_modules", ".git", "__pycache__", "venv", ".venv",
+    "dist", "build", ".next", "coverage", ".nyc_output",
+    "vendor", ".tox", "egg-info", ".eggs",
+}
+
+
+def _read_raw(fs: FileSystemTools, path: str) -> str | None:
+    """Read a file via FileSystemTools and return raw content (no line numbers)."""
+    result = fs.read_file(path)
+    if "error" in result:
+        return None
+    lines = result["content"].split("\n")
+    return "\n".join(
+        line.split("\t", 1)[1] if "\t" in line else line for line in lines
+    )
+
+
+def _parse_json(fs: FileSystemTools, path: str) -> dict | None:
+    raw = _read_raw(fs, path)
+    if raw is None:
+        return None
+    try:
+        return json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+
+def _dir_of(path: str) -> str:
+    """Return the parent directory of a file path, or '.' for root-level files."""
+    parent = str(Path(path).parent)
+    return "." if parent == "." or parent == "" else parent
+
+
+def _glob_no_skip(fs: FileSystemTools, pattern: str) -> list[str]:
+    """Glob for files, filtering out matches inside SKIP_DIRS."""
+    result = fs.glob(pattern)
+    if "error" in result:
+        return []
+    matches = []
+    for m in result.get("matches", []):
+        parts = Path(m).parts
+        if not SKIP_DIRS.intersection(parts):
+            matches.append(m)
+    return matches
+
+
+def _detect_nextjs(fs: FileSystemTools) -> list[dict]:
+    """Detect Next.js projects by next.config.* or 'next' in package.json deps."""
+    found: list[dict] = []
+    seen_roots: set[str] = set()
+
+    for config_name in ("next.config.js", "next.config.ts", "next.config.mjs"):
+        for match in _glob_no_skip(fs, f"**/{config_name}"):
+            root = _dir_of(match)
+            if root not in seen_roots:
+                seen_roots.add(root)
+                found.append({"framework": "nextjs", "root": root})
+
+    for pkg_path in _glob_no_skip(fs, "**/package.json"):
+        root = _dir_of(pkg_path)
+        if root in seen_roots:
+            continue
+        pkg = _parse_json(fs, pkg_path)
+        if pkg is None:
+            continue
+        deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+        if "next" in deps:
+            seen_roots.add(root)
+            found.append({"framework": "nextjs", "root": root})
+
+    return found
+
+
+def _detect_express(fs: FileSystemTools) -> list[dict]:
+    """Detect Express.js projects by 'express' in package.json deps."""
+    found: list[dict] = []
+    seen_roots: set[str] = set()
+
+    for pkg_path in _glob_no_skip(fs, "**/package.json"):
+        root = _dir_of(pkg_path)
+        if root in seen_roots:
+            continue
+        pkg = _parse_json(fs, pkg_path)
+        if pkg is None:
+            continue
+        deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+        if "express" in deps:
+            seen_roots.add(root)
+            found.append({"framework": "express", "root": root})
+
+    return found
+
+
+def _detect_django(fs: FileSystemTools) -> list[dict]:
+    """Detect Django by manage.py + django in Python dependency files."""
+    found: list[dict] = []
+    seen_roots: set[str] = set()
+
+    for manage_path in _glob_no_skip(fs, "**/manage.py"):
+        root = _dir_of(manage_path)
+        if root in seen_roots:
+            continue
+
+        content = _read_raw(fs, manage_path)
+        if content and "django" not in content.lower():
+            continue
+
+        has_django_dep = False
+        for dep_file in ("requirements.txt", "Pipfile", "pyproject.toml", "setup.cfg"):
+            dep_path = f"{root}/{dep_file}" if root != "." else dep_file
+            dep_content = _read_raw(fs, dep_path)
+            if dep_content and re.search(r"django", dep_content, re.IGNORECASE):
+                has_django_dep = True
+                break
+
+        if not has_django_dep:
+            settings_matches = _glob_no_skip(fs, f"{'**/' if root == '.' else root + '/'}**/settings.py")
+            if settings_matches:
+                has_django_dep = True
+
+        if has_django_dep:
+            seen_roots.add(root)
+            found.append({"framework": "django", "root": root})
+
+    return found
+
+
+def _detect_flask(fs: FileSystemTools) -> list[dict]:
+    """Detect Flask by dependency files or app = Flask( pattern."""
+    found: list[dict] = []
+    seen_roots: set[str] = set()
+
+    for dep_file in ("requirements.txt", "Pipfile", "pyproject.toml", "setup.cfg"):
+        for dep_path in _glob_no_skip(fs, f"**/{dep_file}"):
+            root = _dir_of(dep_path)
+            if root in seen_roots:
+                continue
+            content = _read_raw(fs, dep_path)
+            if content and re.search(r"(?:^|\s|['\"])flask(?:\s|['\"><=,\[]|$)", content, re.IGNORECASE | re.MULTILINE):
+                seen_roots.add(root)
+                found.append({"framework": "flask", "root": root})
+
+    return found
+
+
+def _detect_rails(fs: FileSystemTools) -> list[dict]:
+    """Detect Rails by Gemfile with 'rails' or config/routes.rb."""
+    found: list[dict] = []
+    seen_roots: set[str] = set()
+
+    for gemfile_path in _glob_no_skip(fs, "**/Gemfile"):
+        root = _dir_of(gemfile_path)
+        if root in seen_roots:
+            continue
+        content = _read_raw(fs, gemfile_path)
+        if content and re.search(r"['\"]rails['\"]", content):
+            seen_roots.add(root)
+            found.append({"framework": "rails", "root": root})
+
+    for routes_path in _glob_no_skip(fs, "**/config/routes.rb"):
+        root = str(Path(_dir_of(routes_path)).parent)
+        if root == "":
+            root = "."
+        if root not in seen_roots:
+            seen_roots.add(root)
+            found.append({"framework": "rails", "root": root})
+
+    return found
+
+
+def _detect_spring(fs: FileSystemTools) -> list[dict]:
+    """Detect Spring Boot by pom.xml or build.gradle with spring-boot."""
+    found: list[dict] = []
+    seen_roots: set[str] = set()
+
+    for pom_path in _glob_no_skip(fs, "**/pom.xml"):
+        root = _dir_of(pom_path)
+        if root in seen_roots:
+            continue
+        content = _read_raw(fs, pom_path)
+        if content and "spring-boot" in content:
+            seen_roots.add(root)
+            found.append({"framework": "spring", "root": root})
+
+    for gradle_path in _glob_no_skip(fs, "**/build.gradle"):
+        root = _dir_of(gradle_path)
+        if root in seen_roots:
+            continue
+        content = _read_raw(fs, gradle_path)
+        if content and "spring" in content.lower():
+            seen_roots.add(root)
+            found.append({"framework": "spring", "root": root})
+
+    return found
+
+
+def _detect_laravel(fs: FileSystemTools) -> list[dict]:
+    """Detect Laravel by artisan + composer.json with laravel."""
+    found: list[dict] = []
+    seen_roots: set[str] = set()
+
+    for artisan_path in _glob_no_skip(fs, "**/artisan"):
+        root = _dir_of(artisan_path)
+        if root in seen_roots:
+            continue
+        composer_path = f"{root}/composer.json" if root != "." else "composer.json"
+        composer = _parse_json(fs, composer_path)
+        if composer is None:
+            continue
+        require = {**composer.get("require", {}), **composer.get("require-dev", {})}
+        if any("laravel" in k for k in require):
+            seen_roots.add(root)
+            found.append({"framework": "laravel", "root": root})
+
+    return found
+
+
+def detect_frameworks(fs: FileSystemTools) -> list[dict]:
+    """Detect all frameworks in the target repository.
+
+    Returns a list of dicts, each with:
+        - framework: str  (e.g. "nextjs", "django", "express", "flask")
+        - root: str       (directory path relative to repo root, or "." for root)
+
+    Supports monorepos: a single repo can yield multiple entries.
+    """
+    results: list[dict] = []
+
+    results.extend(_detect_nextjs(fs))
+    results.extend(_detect_django(fs))
+    results.extend(_detect_express(fs))
+    results.extend(_detect_flask(fs))
+    results.extend(_detect_rails(fs))
+    results.extend(_detect_spring(fs))
+    results.extend(_detect_laravel(fs))
+
+    # Deduplicate: if both nextjs and express are detected at the same root
+    # (common for Next.js apps that also list express as a dep), keep nextjs
+    # since it's more specific.
+    nextjs_roots = {r["root"] for r in results if r["framework"] == "nextjs"}
+    results = [
+        r for r in results
+        if not (r["framework"] == "express" and r["root"] in nextjs_roots)
+    ]
+
+    return results

openhack/headless_scan.py

@@ -0,0 +1,179 @@
+"""
+Headless scan — runs the full pipeline without the TUI.
+
+Uses the same coordinator pipeline as the TUI (recon → hunters →
+feature deep dive → validation) with checkpoint support for resume.
+"""
+
+import json
+import logging
+import os
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from .agents.coordinator import CoordinatorAgent
+from .agents.checkpoint import CheckpointManager
+from .agents.llm import LLMClient
+from .agents.session import Session, Finding, TraceEntry
+from .tools.registry import ToolRegistry
+from .config import reload_settings, settings
+from .prompts.project_context import build_project_context
+
+logger = logging.getLogger(__name__)
+
+SCANS_DIR = Path.home() / ".openhack" / "scans"
+
+
+def _on_trace(entry: TraceEntry):
+    agent = entry.agent or "?"
+    event = entry.event_type or ""
+    if event == "tool_call":
+        pass
+    elif "finding" in event.lower():
+        print(f"    [{agent}] FINDING: {entry.content}")
+    elif event in ("status", "step_start", "step_complete", "resume"):
+        snippet = str(entry.content or "")[:120]
+        print(f"    [{agent}] {event}: {snippet}")
+
+
+def _write_report(
+    session: Session,
+    target_dir: str,
+    status: str,
+    start_time: float,
+) -> Path:
+    SCANS_DIR.mkdir(parents=True, exist_ok=True)
+    report_path = SCANS_DIR / f"{session.id}.json"
+    elapsed = time.time() - start_time
+
+    report = {
+        "version": 2,
+        "scan_id": session.id,
+        "target_dir": target_dir,
+        "provider": settings.llm_provider,
+        "status": status,
+        "pid": os.getpid(),
+        "started_at": datetime.fromtimestamp(start_time).isoformat(),
+        "duration_seconds": round(elapsed, 2),
+        "cost": session.get_cost_breakdown(),
+        "findings": [f.to_dict() for f in session.findings],
+    }
+
+    tmp_path = report_path.with_suffix(".json.tmp")
+    with open(tmp_path, "w") as fp:
+        json.dump(report, fp, indent=2, default=str, ensure_ascii=False)
+    tmp_path.rename(report_path)
+
+    return report_path
+
+
+async def run_headless_scan(
+    target_dir: str,
+    resume_from_checkpoint: Optional[str] = None,
+):
+    """Run a headless scan using the same coordinator pipeline as the TUI.
+
+    If resume_from_checkpoint is a checkpoint step name (e.g. "recon",
+    "hunter", "feature_hunt"), the coordinator skips completed steps.
+    If it's a session ID, we look up the latest checkpoint for that session.
+    """
+    reload_settings()
+    provider = settings.llm_provider
+    start_time = time.time()
+
+    print(f"\n{'='*60}")
+    if resume_from_checkpoint:
+        print(f"  RESUMING SCAN — {target_dir}")
+    else:
+        print(f"  SCANNING — {target_dir}")
+    print(f"  Provider: {provider}")
+    print(f"{'='*60}\n")
+
+    # Resolve resume: if given a session ID, find its latest checkpoint
+    resume_step = None
+    reuse_id = None
+    if resume_from_checkpoint:
+        mgr = CheckpointManager(resume_from_checkpoint)
+        latest = mgr.get_latest_step()
+        if latest:
+            reuse_id = resume_from_checkpoint
+            resume_step = latest
+            print(f"  Resuming from checkpoint: {latest}")
+        elif resume_from_checkpoint in ("recon", "hunter", "feature_hunt"):
+            resume_step = resume_from_checkpoint
+        else:
+            reuse_id = resume_from_checkpoint
+            print(f"  No checkpoint found — starting fresh on same session")
+
+    project_context = build_project_context(target_dir)
+    session = Session(
+        target_dir=target_dir,
+        on_trace=_on_trace,
+        project_context=project_context,
+        scan_id=reuse_id,
+    )
+    tools = ToolRegistry(target_dir=Path(target_dir))
+
+    if project_context and project_context.get("openhack_md"):
+        print(f"  Loaded .openhack.md project context ({len(project_context['openhack_md'])} chars)")
+
+    # Write initial report so --list-sessions shows a running scan
+    _write_report(session, target_dir, "running", start_time)
+
+    llm = LLMClient(
+        provider=provider,
+        temperature=0.0,
+        max_tokens=8192,
+        prompt_cache_key=session.id,
+    )
+    coordinator = CoordinatorAgent(
+        llm, tools, session,
+        resume_from=resume_step,
+    )
+
+    try:
+        result = await coordinator.run_full_scan()
+
+        # Print results
+        findings = session.findings
+        print(f"\n{'='*60}")
+        print(f"  RESULTS")
+        print(f"{'='*60}")
+
+        if not findings:
+            print("  No vulnerabilities confirmed.")
+        else:
+            print(f"  {len(findings)} vulnerability(ies) confirmed:\n")
+            for i, f in enumerate(findings, 1):
+                sev = f.severity.upper()
+                print(f"  {i}. [{sev}] {f.category} — {f.file_path}")
+                desc = f.description or ""
+                if desc:
+                    print(f"     {desc}")
+                print()
+
+        cost = session.get_cost_breakdown()
+        elapsed = time.time() - start_time
+        m, s = divmod(int(elapsed), 60)
+        print(f"  Cost:     ${session.total_cost:.4f}")
+        print(f"  Duration: {m}m {s:02d}s")
+
+        report_path = _write_report(session, target_dir, "completed", start_time)
+        print(f"  Report:   {report_path}")
+        print(f"  Session:  {session.id}\n")
+
+    except KeyboardInterrupt:
+        print("\n  Scan interrupted.")
+        _write_report(session, target_dir, "cancelled", start_time)
+        mgr = CheckpointManager(session.id)
+        if mgr.get_latest_step():
+            print(f"  Resume from checkpoint: openhack --resume {session.id}")
+        else:
+            print(f"  Retry: openhack --resume {session.id}")
+    except Exception as exc:
+        logger.debug(f"Scan failed: {exc}", exc_info=True)
+        _write_report(session, target_dir, "failed", start_time)
+        print(f"\n  Scan failed: {exc}")
+        print(f"  Retry: openhack --resume {session.id}")

openhack/prompts/__init__.py

@@ -0,0 +1,108 @@
+"""
+Prompt templates for vulnerability scanning agents.
+
+All prompts are organized as one prompt per file for easy maintenance.
+Framework-specific prompts live under prompts/<framework>/<attack_type>.py.
+"""
+
+from .project_context import format_project_context, load_openhack_md, build_project_context
+from .coordinator import COORDINATOR_PROMPT
+from .recon import RECON_PROMPT
+from .hunter import HUNTER_PROMPT
+from .validator import VALIDATOR_PROMPT
+from .reporter import REPORTER_PROMPT
+from .pr_analysis_system import PR_ANALYSIS_SYSTEM_PROMPT
+from .pr_analysis_user import PR_ANALYSIS_USER_TEMPLATE
+from .hunter_tool_instructions import HUNTER_TOOL_INSTRUCTIONS
+from .hunter_continuation_no_findings import HUNTER_CONTINUATION_NO_FINDINGS
+from .hunter_continuation_loop import HUNTER_CONTINUATION_LOOP
+from .hunter_continuation_no_progress import HUNTER_CONTINUATION_NO_PROGRESS
+from .validator_tool_instructions import VALIDATOR_TOOL_INSTRUCTIONS
+from .validator_continuation_incomplete import VALIDATOR_CONTINUATION_INCOMPLETE
+from .sandbox_verifier import SANDBOX_VERIFIER_PROMPT, SANDBOX_VERIFIER_TOOL_INSTRUCTIONS
+from .browser_verifier import BROWSER_VERIFIER_PROMPT, BROWSER_VERIFIER_TOOL_INSTRUCTIONS
+from .feature_hunter import FEATURE_HUNTER_PROMPT, FEATURE_EXTRACTION_PROMPT
+from .nextjs import (
+    NEXTJS_PROMPTS,
+    NEXTJS_IDOR_PROMPT,
+    NEXTJS_XSS_PROMPT,
+    NEXTJS_CSRF_PROMPT,
+    NEXTJS_SSRF_PROMPT,
+    NEXTJS_INJECTION_PROMPT,
+    NEXTJS_AUTH_BYPASS_PROMPT,
+    NEXTJS_DATA_EXPOSURE_PROMPT,
+    NEXTJS_MIDDLEWARE_BYPASS_PROMPT,
+    NEXTJS_SERVER_ACTIONS_PROMPT,
+    NEXTJS_MISCONFIGURATION_PROMPT,
+)
+from .supabase import (
+    SUPABASE_PROMPTS,
+    SUPABASE_RLS_PROMPT,
+    SUPABASE_POSTGREST_PROMPT,
+    SUPABASE_RPC_PROMPT,
+    SUPABASE_STORAGE_PROMPT,
+    SUPABASE_REALTIME_PROMPT,
+    SUPABASE_GRAPHQL_PROMPT,
+    SUPABASE_AUTH_PROMPT,
+    SUPABASE_EDGE_FUNCTIONS_PROMPT,
+    SUPABASE_TENANT_ISOLATION_PROMPT,
+)
+from .django import DJANGO_PROMPTS
+from .express import EXPRESS_PROMPTS
+from .flask import FLASK_PROMPTS
+
+# Unified registry: framework name -> prompt dict.
+# Used by HunterAgent to look up the correct prompts for its assigned framework.
+ALL_FRAMEWORK_PROMPTS: dict[str, dict[str, str]] = {
+    "nextjs": NEXTJS_PROMPTS,
+    "django": DJANGO_PROMPTS,
+    "express": EXPRESS_PROMPTS,
+    "flask": FLASK_PROMPTS,
+    "supabase": SUPABASE_PROMPTS,
+}
+
+__all__ = [
+    "format_project_context",
+    "COORDINATOR_PROMPT",
+    "RECON_PROMPT",
+    "HUNTER_PROMPT",
+    "VALIDATOR_PROMPT",
+    "REPORTER_PROMPT",
+    "PR_ANALYSIS_SYSTEM_PROMPT",
+    "PR_ANALYSIS_USER_TEMPLATE",
+    "HUNTER_TOOL_INSTRUCTIONS",
+    "HUNTER_CONTINUATION_NO_FINDINGS",
+    "HUNTER_CONTINUATION_LOOP",
+    "HUNTER_CONTINUATION_NO_PROGRESS",
+    "VALIDATOR_TOOL_INSTRUCTIONS",
+    "VALIDATOR_CONTINUATION_INCOMPLETE",
+    "SANDBOX_VERIFIER_PROMPT",
+    "SANDBOX_VERIFIER_TOOL_INSTRUCTIONS",
+    "BROWSER_VERIFIER_PROMPT",
+    "BROWSER_VERIFIER_TOOL_INSTRUCTIONS",
+    "ALL_FRAMEWORK_PROMPTS",
+    "NEXTJS_PROMPTS",
+    "NEXTJS_IDOR_PROMPT",
+    "NEXTJS_XSS_PROMPT",
+    "NEXTJS_CSRF_PROMPT",
+    "NEXTJS_SSRF_PROMPT",
+    "NEXTJS_INJECTION_PROMPT",
+    "NEXTJS_AUTH_BYPASS_PROMPT",
+    "NEXTJS_DATA_EXPOSURE_PROMPT",
+    "NEXTJS_MIDDLEWARE_BYPASS_PROMPT",
+    "NEXTJS_SERVER_ACTIONS_PROMPT",
+    "NEXTJS_MISCONFIGURATION_PROMPT",
+    "SUPABASE_PROMPTS",
+    "SUPABASE_RLS_PROMPT",
+    "SUPABASE_POSTGREST_PROMPT",
+    "SUPABASE_RPC_PROMPT",
+    "SUPABASE_STORAGE_PROMPT",
+    "SUPABASE_REALTIME_PROMPT",
+    "SUPABASE_GRAPHQL_PROMPT",
+    "SUPABASE_AUTH_PROMPT",
+    "SUPABASE_EDGE_FUNCTIONS_PROMPT",
+    "SUPABASE_TENANT_ISOLATION_PROMPT",
+    "DJANGO_PROMPTS",
+    "EXPRESS_PROMPTS",
+    "FLASK_PROMPTS",
+]