cyguide 1.0.0__py3-none-any.whl

cyguide/app.py

@@ -0,0 +1,154 @@
+"""Main CyGuide TUI Application."""
+
+import os
+from textual.app import App, SystemCommand
+from cyguide.ui.screens.home import DashboardScreen
+from cyguide.ui.screens.learning import LearningModeScreen
+from cyguide.ui.screens.tool_browser import ToolBrowserScreen
+from cyguide.ui.screens.power import PowerModeScreen
+
+from typing import Optional, Dict, Any, List
+import subprocess
+
+from cyguide.engine.registry import ToolRegistry
+from cyguide.engine.store import GraphStore
+from cyguide.engine.executor import Executor
+from cyguide.engine.explainer import LearningExplainer,  OllamaBackend
+from cyguide.modes.learning import LearningModeEngine
+from cyguide.modes.power import PowerModeEngine
+from cyguide.engine.power_facade import PowerWorkspaceFacade
+
+class CyGuideApp(App):
+    """The central orchestrator for the CyGuide TUI."""
+    
+    CSS_PATH = "ui/style.css"
+    TITLE = "CyGuide"
+    
+    # Register screens so they can be switched by name
+    SCREENS = {
+        "dashboard": DashboardScreen,
+        "tool_browser": ToolBrowserScreen,
+        "learning_mode": LearningModeScreen,
+        "power_mode": PowerModeScreen,
+    }
+
+    def __init__(self, db_path: str = "data/cyguide.db", use_ollama: bool = False, ollama_model: str = "gemma", tools_dir: str = None, **kwargs):
+        super().__init__(**kwargs)
+        self.db_path = db_path
+        self.use_ollama = use_ollama
+        self.ollama_model = ollama_model
+        self.tools_dir = tools_dir
+        self.selected_session_id: Optional[str] = None
+        self.selected_workspace_id: Optional[str] = None
+        self.user_env: Dict[str, str] = os.environ.copy()
+        self.user_shell: str = "/bin/bash"
+        # Ensure the directory for the database exists
+        db_dir = os.path.dirname(os.path.abspath(self.db_path))
+        os.makedirs(db_dir, exist_ok=True)
+
+    def detect_user_shell(self) -> str:
+        """Find the user's default shell."""
+        return os.environ.get("SHELL", "/bin/bash")
+
+    def get_shell_environment(self) -> Dict[str, str]:
+        """Capture the full login shell environment."""
+        shell = self.detect_user_shell()
+        try:
+            # Run a login shell to capture the fully resolved environment
+            result = subprocess.run(
+                [shell, "-l", "-c", "env"],
+                capture_output=True, text=True, timeout=5
+            )
+            env = {}
+            for line in result.stdout.splitlines():
+                if "=" in line:
+                    key, _, val = line.partition("=")
+                    env[key] = val
+            return env if env else os.environ.copy()
+        except Exception:
+            return os.environ.copy()
+
+    async def on_mount(self) -> None:
+        """Initialize the app with core components and the dashboard."""
+        self.user_shell = self.detect_user_shell()
+        self.user_env = self.get_shell_environment()
+        
+        self.learning_mode_tool = "nmap" # Default
+        # 1. Initialize Engines
+        self.registry = ToolRegistry(tools_dir=self.tools_dir)
+        self.registry.load_tools()
+        
+        self.store = GraphStore(self.db_path)
+        await self.store.initialize()
+        
+        # Ensure singleton Learning Sandbox exists
+        self.learning_ws_id, self.learning_session_id = await self.store.get_or_create_learning_sandbox()
+
+        from cyguide.engine.recommendation import RecommendationEngine
+        self.recommendation_engine = RecommendationEngine(self.store)
+        self.store.on_upsert(self.recommendation_engine.handle_upsert)
+
+        self.executor = Executor(self.store)
+        
+        # Setup Explainer
+        from dotenv import load_dotenv
+        load_dotenv()
+        if self.use_ollama:
+            self.explainer_backend = OllamaBackend(model=self.ollama_model)
+        else:
+            api_key = os.environ.get("CYGUIDE_API_KEY") or os.environ.get("GROQ_API_KEY")
+            if api_key:
+                from cyguide.engine.explainer import CloudAPIBackend
+                api_type = os.environ.get("CYGUIDE_API_TYPE", "openai")
+                if os.environ.get("GROQ_API_KEY") and not os.environ.get("CYGUIDE_API_BASE"):
+                    api_base = "https://api.groq.com/openai/v1"
+                    api_model = os.environ.get("CYGUIDE_API_MODEL", "llama-3.3-70b-versatile")
+                else:
+                    api_base = os.environ.get("CYGUIDE_API_BASE", "https://api.openai.com/v1")
+                    api_model = os.environ.get("CYGUIDE_API_MODEL", "gpt-4o")
+                self.explainer_backend = CloudAPIBackend(api_type, api_base, api_key, api_model)
+            else:
+                # Fallback to Ollama if no API key is provided and use_ollama is false
+                self.explainer_backend = OllamaBackend(model=self.ollama_model)
+            
+        self.explainer = LearningExplainer(self.explainer_backend)
+        
+        self.learning_engine = LearningModeEngine(self.registry, self.executor, self.explainer)
+        self.power_engine = PowerModeEngine(self.registry, self.executor)
+        self.power_facade = PowerWorkspaceFacade(self.store, self.executor, self.registry)
+        self.power_facade.user_env = self.user_env
+        self.power_facade.user_shell = self.user_shell
+
+        # 2. Setup UI
+        self.push_screen("dashboard")
+        self.animations_enabled = True
+
+    async def on_unmount(self) -> None:
+        """Cleanup resources before exit."""
+        if hasattr(self, "executor"):
+            await self.executor.shutdown()
+        if hasattr(self, "store"):
+            await self.store.close()
+
+    def action_toggle_animations(self) -> None:
+        """Toggle UI animations on or off via the command palette."""
+        self.animations_enabled = not self.animations_enabled
+        if self.animations_enabled:
+            self.remove_class("no-animations")
+            self.notify("Animations Enabled")
+        else:
+            self.add_class("no-animations")
+            self.notify("Animations Disabled")
+
+    def get_system_commands(self, screen):
+        """Add custom commands to the Command Palette (Ctrl+P)."""
+        yield from super().get_system_commands(screen)
+        yield SystemCommand(
+            "Toggle Animations", 
+            "Turn sidebar animations on or off", 
+            self.action_toggle_animations
+        )
+
+if __name__ == "__main__":
+    app = CyGuideApp()
+    app.run()

cyguide/engine/adapter.py

@@ -0,0 +1,40 @@
+"""Abstract base class for all tool plugins."""
+
+from abc import ABC, abstractmethod
+from typing import AsyncIterator, List, Dict, Any
+from cyguide.schemas.base import BaseFinding
+
+
+class ToolAdapter(ABC):
+    """
+    Contract for tool contributors. 
+    Every tool in tools/ must implement this in adapter.py.
+    """
+
+    @abstractmethod
+    def validate_install(self) -> bool:
+        """Check if the tool binary is available on the system."""
+        pass
+
+    @abstractmethod
+    def build_command(self, target: BaseFinding, params: Dict[str, Any]) -> List[str]:
+        """
+        Build the command line arguments for the tool.
+        
+        Args:
+            target: The finding being scanned (e.g. a network.host)
+            params: User-provided flags or options from the TUI
+        """
+        pass
+
+    @abstractmethod
+    async def parse_output(self, raw_stdout: str, target: BaseFinding, context: Dict[str, Any] = None) -> AsyncIterator[BaseFinding]:
+        """
+        Parse tool output and yield standardized findings.
+        
+        Args:
+            raw_stdout: The raw output string from the tool
+            target: The original target finding (for context/parenting)
+            context: Optional dictionary for tracking state across lines (e.g. current host)
+        """
+        pass

cyguide/engine/canonicalize.py

@@ -0,0 +1,56 @@
+# PROTECTED FILE — See CONTRIBUTING.md before modifying.
+# Changes to this file require team agreement.
+"""Normalization filters for finding data."""
+
+import urllib.parse
+
+
+def canonicalize(value):
+    """Apply normalization rules based on the type of value."""
+    if isinstance(value, str):
+        # General string cleaning
+        value = value.strip()
+        
+        # Lowercase hostnames (heuristic: no spaces, contains dots or is localhost)
+        if "." in value or value.lower() == "localhost":
+            if " " not in value and ":" not in value:
+                return value.lower()
+
+    return value
+
+
+def canonicalize_host(ip_or_name: str) -> str:
+    """Normalize IP addresses and hostnames."""
+    val = ip_or_name.strip().lower()
+    if val in ("localhost", "127.0.0.1", "::1"):
+        return "127.0.0.1"
+    # Basic IP normalization (lowercase IPv6, etc)
+    return val
+
+
+def canonicalize_url(url: str) -> str:
+    """Normalize a URL: lowercase scheme/host, strip default ports."""
+    try:
+        parsed = urllib.parse.urlparse(url)
+        scheme = parsed.scheme.lower()
+        netloc = parsed.netloc.lower()
+
+        # Strip default ports
+        if scheme == "http" and netloc.endswith(":80"):
+            netloc = netloc[:-3]
+        elif scheme == "https" and netloc.endswith(":443"):
+            netloc = netloc[:-4]
+
+        return urllib.parse.urlunparse(
+            (scheme, netloc, parsed.path, parsed.params, parsed.query, parsed.fragment)
+        )
+    except Exception:
+        return url
+
+
+def canonicalize_port(port) -> int:
+    """Ensure port is an integer."""
+    try:
+        return int(port)
+    except (ValueError, TypeError):
+        return 0

cyguide/engine/diagnostics.py

@@ -0,0 +1,327 @@
+"""Environment and dependency diagnostic checks for CyGuide."""
+
+import os
+import sys
+import shutil
+import platform
+import asyncio
+from typing import Optional, Dict, List, Any
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, UTC
+
+import httpx
+from cyguide.engine.registry import ToolRegistry
+from cyguide.engine.store import GraphStore
+
+
+INSTALLATION_HINTS: Dict[str, str] = {
+    "nmap": "sudo apt install nmap  (or: brew install nmap)",
+    "gobuster": "sudo apt install gobuster  (or: go install github.com/OJ/gobuster/v3@v3.6.0)",
+    "nikto": "sudo apt install nikto  (or: brew install nikto)",
+    "subfinder": "go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@v2.6.6",
+    "whois": "sudo apt install whois  (or: brew install whois)",
+}
+
+
+@dataclass
+class DiagnosticCheck:
+    name: str
+    category: str
+    status: str  # "ok", "warning", "error", "info"
+    message: str
+    details: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class DiagnosticReport:
+    timestamp: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+    system_info: Dict[str, Any] = field(default_factory=dict)
+    checks: List[DiagnosticCheck] = field(default_factory=list)
+    healthy: bool = True
+    tool_counts: Dict[str, int] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "timestamp": self.timestamp,
+            "system_info": self.system_info,
+            "healthy": self.healthy,
+            "tool_counts": self.tool_counts,
+            "checks": [asdict(c) for c in self.checks]
+        }
+
+
+async def run_diagnostics(
+    db_path: str = "data/cyguide.db", 
+    tools_dir: Optional[str] = None
+) -> DiagnosticReport:
+    """Run all system, database, tool dependency, and explainer checks."""
+    report = DiagnosticReport()
+    
+    # 1. System Environment
+    py_version = sys.version_info
+    py_version_str = f"{py_version.major}.{py_version.minor}.{py_version.micro}"
+    report.system_info = {
+        "python_version": py_version_str,
+        "platform": platform.platform(),
+        "executable": sys.executable,
+    }
+    
+    if py_version >= (3, 11):
+        report.checks.append(DiagnosticCheck(
+            name="Python Version",
+            category="System",
+            status="ok",
+            message=f"Python {py_version_str} (>= 3.11 requirement satisfied)"
+        ))
+    else:
+        report.checks.append(DiagnosticCheck(
+            name="Python Version",
+            category="System",
+            status="error",
+            message=f"Python {py_version_str} is below minimum requirement 3.11"
+        ))
+        report.healthy = False
+
+    # Textual dependency check
+    try:
+        import textual
+        report.checks.append(DiagnosticCheck(
+            name="Textual TUI Framework",
+            category="System",
+            status="ok",
+            message=f"Textual v{textual.__version__} installed"
+        ))
+    except Exception as e:
+        report.checks.append(DiagnosticCheck(
+            name="Textual TUI Framework",
+            category="System",
+            status="error",
+            message=f"Failed to import textual: {str(e)}"
+        ))
+        report.healthy = False
+
+    # 2. Storage & SQLite Database Health
+    db_dir = os.path.dirname(os.path.abspath(db_path)) if db_path != ":memory:" else None
+    if db_dir:
+        os.makedirs(db_dir, exist_ok=True)
+        is_writable = os.access(db_dir, os.W_OK)
+        if is_writable:
+            report.checks.append(DiagnosticCheck(
+                name="Storage Directory",
+                category="Database",
+                status="ok",
+                message=f"Directory '{db_dir}' is writable"
+            ))
+        else:
+            report.checks.append(DiagnosticCheck(
+                name="Storage Directory",
+                category="Database",
+                status="error",
+                message=f"Directory '{db_dir}' is not writable"
+            ))
+            report.healthy = False
+
+    try:
+        store = GraphStore(db_path)
+        await store.initialize()
+        
+        async with store._get_conn() as db:
+            cursor = await db.execute("PRAGMA integrity_check")
+            row = await cursor.fetchone()
+            integrity_status = row[0] if row else "unknown"
+
+            cursor = await db.execute("SELECT name FROM sqlite_master WHERE type='table'")
+            tables = [r[0] for r in await cursor.fetchall()]
+
+        await store.close()
+
+        if integrity_status == "ok":
+            report.checks.append(DiagnosticCheck(
+                name="SQLite Integrity",
+                category="Database",
+                status="ok",
+                message=f"Database '{db_path}' integrity verified ({len(tables)} tables present)",
+                details={"tables": tables}
+            ))
+        else:
+            report.checks.append(DiagnosticCheck(
+                name="SQLite Integrity",
+                category="Database",
+                status="error",
+                message=f"Database integrity check failed: {integrity_status}"
+            ))
+            report.healthy = False
+    except Exception as e:
+        report.checks.append(DiagnosticCheck(
+            name="SQLite Database",
+            category="Database",
+            status="error",
+            message=f"Failed to connect to database '{db_path}': {str(e)}"
+        ))
+        report.healthy = False
+
+    # 3. Security Tool Dependencies
+    registry = ToolRegistry(tools_dir=tools_dir)
+    registry.load_tools()
+    tool_names = registry.list_tools()
+    
+    installed_count = 0
+    total_tools = len(tool_names)
+
+    for name in tool_names:
+        tool_data = registry.get_tool(name)
+        adapter = tool_data.get("adapter") if tool_data else None
+        manifest = tool_data.get("manifest") if tool_data else None
+        description = manifest.meta.description if manifest else ""
+        
+        is_installed = False
+        binary_path = None
+
+        if adapter:
+            try:
+                is_installed = adapter.validate_install()
+            except Exception:
+                is_installed = False
+
+        binary_path = shutil.which(name)
+
+        if is_installed:
+            installed_count += 1
+            report.checks.append(DiagnosticCheck(
+                name=f"Tool: {name}",
+                category="Tools",
+                status="ok",
+                message=f"Installed at {binary_path or 'PATH'}",
+                details={"description": description, "binary": binary_path}
+            ))
+        else:
+            hint = INSTALLATION_HINTS.get(name, f"Install '{name}' using your system package manager.")
+            report.checks.append(DiagnosticCheck(
+                name=f"Tool: {name}",
+                category="Tools",
+                status="warning",
+                message=f"Not found in PATH. Install hint: {hint}",
+                details={"description": description, "install_hint": hint}
+            ))
+
+    report.tool_counts = {
+        "installed": installed_count,
+        "total": total_tools,
+        "missing": total_tools - installed_count
+    }
+
+    # 4. Explainer & AI Backends
+    # Ollama check
+    try:
+        async with httpx.AsyncClient(timeout=1.0) as client:
+            resp = await client.get("http://localhost:11434/api/tags")
+            if resp.status_code == 200:
+                models = [m.get("name") for m in resp.json().get("models", [])]
+                report.checks.append(DiagnosticCheck(
+                    name="Ollama Local LLM",
+                    category="Explainer",
+                    status="ok",
+                    message=f"Connected to local Ollama ({len(models)} models available: {', '.join(models[:3])})",
+                    details={"models": models}
+                ))
+            else:
+                report.checks.append(DiagnosticCheck(
+                    name="Ollama Local LLM",
+                    category="Explainer",
+                    status="info",
+                    message="Ollama returned non-200 status (optional backend)"
+                ))
+    except Exception:
+        report.checks.append(DiagnosticCheck(
+            name="Ollama Local LLM",
+            category="Explainer",
+            status="info",
+            message="Ollama service is not running on http://localhost:11434 (optional backend)"
+        ))
+
+    # Cloud API Keys check
+    if os.getenv("CYGUIDE_API_KEY"):
+        report.checks.append(DiagnosticCheck(
+            name="Cloud LLM Keys",
+            category="Explainer",
+            status="ok",
+            message=(
+                f"CYGUIDE_API_KEY set (type="
+                f"{os.getenv('CYGUIDE_API_TYPE', 'openai')}, "
+                f"model={os.getenv('CYGUIDE_API_MODEL', 'gpt-4o')})"
+            )
+        ))
+    else:
+        cloud_keys = [
+            "GROQ_API_KEY",
+            "OPENAI_API_KEY",
+            "ANTHROPIC_API_KEY",
+            "OPENROUTER_API_KEY",
+            "GROK_API_KEY",
+            "GEMINI_API_KEY",
+        ]
+        configured_keys = [k for k in cloud_keys if os.getenv(k)]
+        if configured_keys:
+            report.checks.append(DiagnosticCheck(
+                name="Cloud LLM Keys",
+                category="Explainer",
+                status="ok",
+                message=f"Configured API keys: {', '.join(configured_keys)}"
+            ))
+        else:
+            report.checks.append(DiagnosticCheck(
+                name="Cloud LLM Keys",
+                category="Explainer",
+                status="info",
+                message="CYGUIDE_API_KEY is not set (optional backend)"
+            ))
+
+    return report
+
+
+def format_terminal_report(report: DiagnosticReport) -> str:
+    """Format the diagnostic report for terminal display."""
+    lines = []
+    lines.append("=" * 68)
+    lines.append("  🩺  CYGUIDE SYSTEM & ENVIRONMENT DIAGNOSTICS")
+    lines.append("=" * 68)
+    lines.append(f"  Timestamp : {report.timestamp}")
+    lines.append(f"  Platform  : {report.system_info.get('platform', 'unknown')}")
+    lines.append(f"  Python    : {report.system_info.get('python_version', 'unknown')} ({report.system_info.get('executable', '')})")
+    lines.append("-" * 68)
+
+    # Group by category
+    categories = ["System", "Database", "Tools", "Explainer"]
+    for cat in categories:
+        cat_checks = [c for c in report.checks if c.category == cat]
+        if not cat_checks:
+            continue
+
+        header_icon = {
+            "System": "🖥️ ",
+            "Database": "💾",
+            "Tools": "🛠️ ",
+            "Explainer": "🤖"
+        }.get(cat, "🔍")
+
+        lines.append(f"\n{header_icon} {cat.upper()}")
+        for c in cat_checks:
+            if c.status == "ok":
+                badge = "[✓]"
+            elif c.status == "warning":
+                badge = "[!]"
+            elif c.status == "error":
+                badge = "[✗]"
+            else:
+                badge = "[-]"
+            lines.append(f"  {badge:<4} {c.name:<24} : {c.message}")
+
+    lines.append("\n" + "=" * 68)
+    tool_stat = f"{report.tool_counts.get('installed', 0)}/{report.tool_counts.get('total', 0)} security tools installed"
+    if report.healthy:
+        lines.append(f"  STATUS: HEALTHY ({tool_stat})")
+    else:
+        lines.append(f"  STATUS: ATTENTION REQUIRED ({tool_stat})")
+    lines.append("=" * 68)
+
+    return "\n".join(lines)