openhack 0.1.0__py3-none-any.whl

openhack/__init__.py

@@ -0,0 +1,2 @@
+"""OpenHack Agent - Interactive TUI for vulnerability scanning."""
+__version__ = "0.1.0"

openhack/__main__.py

@@ -0,0 +1,225 @@
+"""
+Entry point for OpenHack.
+
+Usage:
+  openhack                          Launch interactive TUI
+  openhack scan [path]              Scan a repository (headless, defaults to .)
+  openhack sessions                 List all saved scan sessions
+  openhack resume <id>              Resume a previous scan session
+  openhack classify [path]          Classify frameworks and detect entry points
+  openhack login                    Log in to your OpenHack account
+  openhack setup                    Run the setup wizard
+  openhack --help                   Show usage
+"""
+
+import sys
+
+
+def _cmd_scan():
+    """Run a headless scan on a directory."""
+    from pathlib import Path
+
+    target_arg = sys.argv[2] if len(sys.argv) > 2 else "."
+    target = Path(target_arg).resolve()
+
+    if not target.is_dir():
+        print(f"Error: '{target_arg}' is not a directory.")
+        print("Usage: openhack scan [path]")
+        return
+
+    from openhack.config import settings
+    if not settings.openhack_api_key:
+        print("Error: not logged in.")
+        print("Run 'openhack login' to set up your account, or set OPENHACK_API_KEY.")
+        return
+
+    import asyncio
+    from openhack.headless_scan import run_headless_scan
+    try:
+        asyncio.run(run_headless_scan(str(target)))
+    except KeyboardInterrupt:
+        print()
+    except Exception:
+        pass
+
+
+def _cmd_sessions():
+    """List all saved scan sessions."""
+    import json
+    from pathlib import Path
+
+    scans_dir = Path.home() / ".openhack" / "scans"
+    if not scans_dir.exists():
+        print("\nNo saved scans yet.")
+        return
+
+    reports = []
+    for p in sorted(scans_dir.glob("*.json"), reverse=True):
+        try:
+            data = json.loads(p.read_text())
+            reports.append(data)
+        except (OSError, json.JSONDecodeError):
+            continue
+
+    print(f"\nSaved scans: {len(reports)}")
+    for r in reports:
+        scan_id = (r.get("scan_id") or "?")[:8]
+        target = r.get("target_dir", "?")
+        status = r.get("status", "?")
+        findings = r.get("findings", [])
+        started = r.get("started_at", "")[:16]
+        print(f"  {scan_id}  {target}  [{status}]  {len(findings)} findings  {started}")
+
+
+def _cmd_resume():
+    """Resume a previous scan session."""
+    import json
+    from pathlib import Path
+    from openhack.agents.checkpoint import CheckpointManager
+
+    session_id = sys.argv[2] if len(sys.argv) > 2 else None
+    if not session_id:
+        print("Usage: openhack resume <session_id>")
+        return
+
+    scans_dir = Path.home() / ".openhack" / "scans"
+    report_path = scans_dir / f"{session_id}.json"
+    if not report_path.exists():
+        matches = list(scans_dir.glob(f"{session_id}*.json"))
+        if matches:
+            report_path = matches[0]
+
+    if not report_path.exists():
+        print(f"Session {session_id} not found in ~/.openhack/scans/")
+        return
+
+    try:
+        report = json.loads(report_path.read_text())
+    except (json.JSONDecodeError, OSError):
+        print(f"Could not read session report: {report_path}")
+        return
+
+    target_dir = report.get("target_dir")
+    if not target_dir or not Path(target_dir).is_dir():
+        print(f"Target directory no longer exists: {target_dir}")
+        return
+
+    status = report.get("status", "")
+    if status == "completed":
+        findings = report.get("findings", [])
+        print(f"Session {session_id} already completed ({len(findings)} findings).")
+        return
+
+    mgr = CheckpointManager(session_id)
+    latest = mgr.get_latest_step()
+    if latest:
+        print(f"Resuming session {session_id} from checkpoint: {latest}")
+    else:
+        print(f"Resuming session {session_id} (no checkpoint — starting fresh)")
+
+    from openhack.config import settings
+    if not settings.openhack_api_key:
+        print("Error: not logged in.")
+        print("Run 'openhack login' to set up your account, or set OPENHACK_API_KEY.")
+        return
+
+    import asyncio
+    from openhack.headless_scan import run_headless_scan
+    try:
+        asyncio.run(run_headless_scan(target_dir, resume_from_checkpoint=session_id))
+    except KeyboardInterrupt:
+        print()
+    except Exception:
+        pass
+
+
+def _cmd_classify():
+    """Classify frameworks and detect entry points."""
+    from pathlib import Path
+    from openhack.tools.registry import ToolRegistry
+    from openhack.framework_classifier import classify_frameworks
+    from openhack.entry_points import detect_entry_points
+    from openhack.scan_session import ScanSession
+    import uuid
+
+    target = sys.argv[2] if len(sys.argv) > 2 else "."
+    tools = ToolRegistry(target_dir=Path(target))
+
+    print(f"\nClassifying {target}...\n")
+    classifications = classify_frameworks(tools.fs_tools)
+    for c in classifications:
+        print(f"  {c['root']} → {c['language']} [{', '.join(c['frameworks'])}]")
+
+    print(f"\nDetecting entry points...")
+    entry_points = detect_entry_points(tools.fs_tools, classifications)
+    print(f"  {len(entry_points)} entry points found\n")
+
+    sid = str(uuid.uuid4())[:8]
+    session = ScanSession(sid, target)
+    session.classifications = classifications
+    session.entry_points = entry_points
+    session.save()
+    print(f"  Session saved: {sid}")
+    print(f"  Run 'openhack resume {sid}' to scan\n")
+
+
+def _cmd_login():
+    """Run the device login flow."""
+    from openhack.setup import run_first_time_setup
+    run_first_time_setup()
+
+
+def _cmd_setup():
+    """Run the setup wizard."""
+    from openhack.setup import run_first_time_setup
+    run_first_time_setup()
+
+
+COMMANDS = {
+    "scan": _cmd_scan,
+    "sessions": _cmd_sessions,
+    "resume": _cmd_resume,
+    "classify": _cmd_classify,
+    "login": _cmd_login,
+    "setup": _cmd_setup,
+}
+
+
+def main():
+    if len(sys.argv) > 1:
+        cmd = sys.argv[1]
+
+        if cmd in ("--help", "-h", "help"):
+            print(__doc__)
+            return
+
+        if cmd in ("--version", "-v", "version"):
+            from openhack import __version__
+            print(f"openhack {__version__}")
+            return
+
+        if cmd in COMMANDS:
+            COMMANDS[cmd]()
+            return
+
+        print(f"Unknown command: {cmd}")
+        print("Run 'openhack --help' for usage.")
+        return
+
+    # Default: launch TUI
+    from openhack.setup import needs_first_time_setup, run_first_time_setup
+
+    try:
+        if needs_first_time_setup():
+            completed = run_first_time_setup()
+            if not completed:
+                print("\nSetup skipped. Run openhack again or use /setup inside the TUI.\n")
+
+        from openhack.tui import main as tui_main
+        tui_main()
+    except KeyboardInterrupt:
+        print()
+
+
+if __name__ == "__main__":
+    main()

openhack/agents/__init__.py

@@ -0,0 +1,30 @@
+"""OpenHack agents."""
+
+from .session import Session, SessionStatus, Finding, TraceEntry
+from .llm import LLMClient, Message, ToolCall, ToolResult, LLMResponse
+from .base import BaseAgent
+from .recon import ReconAgent
+from .hunter import HunterAgent
+from .hunter_swarm import HunterSwarmAgent
+from .validator import ValidatorAgent
+from .validator_swarm import ValidatorSwarmAgent
+from .coordinator import CoordinatorAgent
+
+__all__ = [
+    "Session",
+    "SessionStatus",
+    "Finding",
+    "TraceEntry",
+    "LLMClient",
+    "Message",
+    "ToolCall",
+    "ToolResult",
+    "LLMResponse",
+    "BaseAgent",
+    "ReconAgent",
+    "HunterAgent",
+    "HunterSwarmAgent",
+    "ValidatorAgent",
+    "ValidatorSwarmAgent",
+    "CoordinatorAgent",
+]

openhack/agents/base.py

@@ -0,0 +1,230 @@
+"""
+Base agent class for the multi-agent vulnerability scanning system.
+"""
+
+import json
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+import openai
+
+from .llm import LLMClient, Message, ToolCall, ToolResult
+from .session import Session
+from .context_manager import ContextWindowManager, MODEL_CONTEXT_LIMITS, DEFAULT_CONTEXT_LIMIT
+from openhack.tools.registry import ToolRegistry
+from openhack.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+class BaseAgent(ABC):
+    """Base class for all scanning agents."""
+
+    name: str = "base"
+    description: str = "Base agent"
+
+    def __init__(self, llm: LLMClient, tools: ToolRegistry, session: Session):
+        self.llm = llm
+        self.tools = tools
+        self.session = session
+        self.messages: list[Message] = []
+        self._instructions_watermark: int = 0
+
+        context_limit = MODEL_CONTEXT_LIMITS.get(llm.model, DEFAULT_CONTEXT_LIMIT)
+        self.context_manager = ContextWindowManager(
+            context_window_limit=context_limit,
+            compaction_threshold=settings.compaction_threshold,
+            tool_result_max_lines=settings.tool_result_max_lines,
+        )
+
+    @abstractmethod
+    def get_system_prompt(self, context: dict) -> str:
+        pass
+
+    def get_tools(self) -> list[dict]:
+        return self.tools.get_all_tool_definitions()
+
+    def _inject_pending_instructions(self) -> None:
+        """Pull any new user instructions from the session and append them to messages."""
+        new, version = self.session.get_new_instructions(self._instructions_watermark)
+        self._instructions_watermark = version
+        for instruction in new:
+            self.messages.append(Message(
+                role="user",
+                content=(
+                    f"[USER INSTRUCTION]: {instruction}\n"
+                    "Take this into account for the remainder of your analysis."
+                ),
+            ))
+
+    def _seed_existing_instructions(self) -> None:
+        """Inject any instructions that were given before this agent was created."""
+        existing = self.session.get_all_instructions()
+        self._instructions_watermark = len(existing)
+        if existing:
+            combined = "\n".join(f"- {inst}" for inst in existing)
+            self.messages.append(Message(
+                role="user",
+                content=(
+                    f"[USER INSTRUCTIONS (given earlier in this scan)]:\n{combined}\n"
+                    "Take these into account throughout your analysis."
+                ),
+            ))
+
+    def _estimate_tokens(self, messages: list[Message], system: str) -> int:
+        """Rough token estimate: ~4 chars per token for English text."""
+        total_chars = len(system)
+        for msg in messages:
+            if msg.content:
+                total_chars += len(msg.content)
+            if msg.tool_calls:
+                total_chars += len(json.dumps(msg.tool_calls))
+        return total_chars // 4
+
+    def _preflight_compact(self, system_prompt: str) -> None:
+        """Compact messages before sending to LLM if estimated tokens exceed limit."""
+        estimated = self._estimate_tokens(self.messages, system_prompt)
+        limit = self.context_manager.context_window_limit
+
+        if estimated > limit * 0.85:
+            logger.warning(
+                f"[{self.name}] Pre-flight: estimated {estimated} tokens vs {limit} limit — compacting"
+            )
+            self.messages = self.context_manager.compact_messages(self.messages, keep_recent_turns=3)
+            estimated = self._estimate_tokens(self.messages, system_prompt)
+
+            if estimated > limit * 0.85:
+                logger.warning(
+                    f"[{self.name}] Still {estimated} tokens after normal compaction — emergency compaction"
+                )
+                self.messages = self.context_manager.emergency_compact(self.messages)
+
+    async def run(self, task: str, context: Optional[dict] = None) -> dict:
+        context = context or {}
+        self.session.current_agent = self.name
+
+        system_prompt = self.get_system_prompt(context)
+        self.messages = [Message(role="user", content=task)]
+        self._seed_existing_instructions()
+
+        max_iterations = 50
+        iteration = 0
+
+        while iteration < max_iterations:
+            if self.session.cancelled:
+                break
+            # Block here while the session is paused (no-op when running).
+            await self.session.wait_if_paused()
+            if self.session.cancelled:
+                break
+            iteration += 1
+
+            self._inject_pending_instructions()
+
+            self._preflight_compact(system_prompt)
+
+            try:
+                response = await self.llm.chat(
+                    messages=self.messages,
+                    tools=self.get_tools(),
+                    system=system_prompt,
+                )
+            except openai.BadRequestError as e:
+                err_msg = str(e)
+                if "too long" in err_msg or "too many tokens" in err_msg.lower() or "context length" in err_msg:
+                    logger.warning(f"[{self.name}] Context overflow on LLM call — compacting and retrying")
+                    self.messages = self.context_manager.compact_messages(self.messages, keep_recent_turns=2)
+                    estimated = self._estimate_tokens(self.messages, system_prompt)
+                    if estimated > self.context_manager.context_window_limit * 0.85:
+                        self.messages = self.context_manager.emergency_compact(self.messages)
+
+                    try:
+                        response = await self.llm.chat(
+                            messages=self.messages,
+                            tools=self.get_tools(),
+                            system=system_prompt,
+                        )
+                    except openai.BadRequestError as e2:
+                        err_msg2 = str(e2)
+                        if "too long" in err_msg2 or "context length" in err_msg2:
+                            logger.warning(f"[{self.name}] Still overflowing after emergency compaction — final attempt")
+                            self.messages = self.context_manager.emergency_compact(self.messages)
+                            response = await self.llm.chat(
+                                messages=self.messages,
+                                tools=self.get_tools(),
+                                system=system_prompt,
+                            )
+                        else:
+                            raise
+                else:
+                    raise
+
+            self.session.total_cost += response.cost
+            if response.usage:
+                self.session.total_tokens += response.usage.get("total_tokens", 0)
+                self.context_manager.update_usage(response.usage.get("input_tokens", 0))
+
+            if response.content:
+                self.session.add_trace(
+                    agent=self.name,
+                    event_type="thinking",
+                    content=response.content,
+                )
+
+            if not response.tool_calls:
+                return self._parse_final_response(response.content or "")
+
+            assistant_msg = Message(
+                role="assistant",
+                content=response.content,
+                tool_calls=[
+                    {
+                        "id": tc.id,
+                        "type": "function",
+                        "function": {"name": tc.name, "arguments": json.dumps(tc.arguments)},
+                    }
+                    for tc in response.tool_calls
+                ],
+                reasoning_content=getattr(response, 'reasoning_content', None),
+            )
+            self.messages.append(assistant_msg)
+
+            for tool_call in response.tool_calls:
+                self.session.add_trace(
+                    agent=self.name,
+                    event_type="tool_call",
+                    content=f"Calling {tool_call.name}",
+                    tool_name=tool_call.name,
+                    tool_input=tool_call.arguments,
+                )
+
+                if self.tools.is_async_tool(tool_call.name):
+                    result = await self.tools.execute_tool_async(tool_call.name, tool_call.arguments)
+                else:
+                    result = self.tools.execute_tool(tool_call.name, tool_call.arguments)
+
+                self.session.add_trace(
+                    agent=self.name,
+                    event_type="tool_result",
+                    content=f"Result from {tool_call.name}",
+                    tool_name=tool_call.name,
+                    tool_output=result,
+                )
+
+                raw_content = json.dumps(result) if isinstance(result, dict) else str(result)
+                truncated_content = self.context_manager.truncate_tool_result(tool_call.name, raw_content)
+                tool_result = ToolResult(
+                    tool_call_id=tool_call.id,
+                    content=truncated_content,
+                )
+                self.messages.append(tool_result.to_message())
+
+            if self.context_manager.needs_compaction():
+                self.messages = self.context_manager.compact_messages(self.messages)
+                logger.info(f"[{self.name}] Compacted message history ({self.context_manager.last_input_tokens} input tokens)")
+
+        return {"error": "Max iterations reached", "partial_result": self.messages[-1].content}
+
+    def _parse_final_response(self, content: str) -> dict:
+        return {"response": content}