CyGuide

TUI-Based Guided Cybersecurity Learning and Terminal Tool Orchestration Platform.

CyGuide transforms penetration testing and security learning from disorganized terminal tabs into an integrated, stateful terminal workstation. It orchestrates industry-standard security tools (nmap, gobuster, nikto, whois, subfinder), normalizes their outputs into a live entity graph, resolves contextual target variables dynamically, and provides real-time explanations through local (Ollama) or cloud AI models.

For an interactive overview and project showcase, visit the official webpage at https://h45sh.com/portfolio/cyguide/.

🎬 Watch the Full Terminal Workstation Video Walkthrough (assets/demo.mp4)

Why CyGuide?

• No More Terminal Tab Chaos: Run multiple reconnaissance tools concurrently with dedicated tabs, active job monitoring, and instant output review.
• Stateful Entity Graph: Discoveries (hosts, open ports, endpoints, DNS records, vulnerabilities) automatically link together in a deterministic graph using SHA-256 Primary Identity Keys (PIKs).
• Universal Variable Injection: Click any node in your target tree to bind variables ($TARGET, $PORT, $SERVICE) into subsequent commands without retyping IP addresses.
• Offline-First AI Tutor: Get immediate, structured breakdowns of scan results and security recommendations powered by local Ollama models or cloud APIs.
• Portable Engagement Archives: Export investigations into standalone .db archives and Markdown reports (cyg export). Instructors can import (cyg import) and replay a student's exact methodology step-by-step.

Workstation Interface

CyGuide features two distinct terminal operational modes and an integrated diagnostic suite:

1. Power Mode (Multi-Tab Concurrent Workbench)

Run multiple asynchronous security tools concurrently, interact with live target graphs, and resolve $TARGET, $PORT, and $SERVICE variables on the fly:

2. Dashboard Hub (Workspace & Session Management)

Organize complex penetration tests and CTFs into discrete workspaces and isolated sessions with full archive, rename, and export support (Ctrl+N, Ctrl+S):

3. Guided Learning Mode & Interactive Tool Browser

Explore tool recipes, inspect command flags before execution, and receive AI-guided security breakdowns and hardening steps:

4. In-App Diagnostics & Unified Command Palette

Inspect security binary availability on $PATH in real time with Ctrl+P -> Tool Health, and configure AI providers, database paths, and custom plugins:

Architecture Overview

CyGuide is built on a Smart Adapter / Stupid Framework model:

┌────────────────────────────────────────────────────────────────────────┐
│                        Textual TUI Workstation                         │
│  [ Dashboard Hub ]   [ Guided Learning Mode ]   [ Power Mode Workbench]│
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Actions / Context
┌───────────────────────────────────▼────────────────────────────────────┐
│                       Deterministic Core Engine                        │
│  • ActionGateway (SSRF & Scope Policy)  • ExecutionSession (PTY Spool) │
│  • GraphStore (PIK Deduplication)       • ActionTimelineRepository     │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Event Streaming
┌───────────────────────────────────▼────────────────────────────────────┐
│                         Security Tool Adapters                         │
│   nmap  •  gobuster  •  nikto  •  whois  •  subfinder  •  custom...    │
└────────────────────────────────────────────────────────────────────────┘

• Core Engine (cyguide/engine): Asynchronous process execution sessions with disk spooling, policy gateway, action timeline repository, workspace repository, and SQLite graph store.
• Unified Schemas (cyguide/schemas): 15 standard Pydantic models defining shared security entities with declarative canonicalization.
• Smart Adapters (tools/): Isolated plugins that construct commands and parse streaming output.
• Textual TUI (cyguide/ui): Fast, keyboard-driven terminal interface with split panes and scratchpad.

Installation & Getting Started

CyGuide can be run or installed through several methods depending on your workflow:

Option 1: Instant Evaluation via Docker (Zero Setup)

Run CyGuide immediately with Python 3.11+ and all 5 security tools pre-installed inside an isolated container:

docker run -it --rm --net=host -v ~/.cyguide:/root/.cyguide ghcr.io/h45sh/cyguide

Option 2: Install via pipx (Recommended for Python CLI Users)

Install CyGuide into an isolated application environment:

pipx install cyguide

(Ensure system security tools are installed via the Universal Installer or native package managers below).

Option 3: Install from PyPI or Source

If working inside a virtual environment or contributing to CyGuide:

# Install from PyPI
pip install cyguide

# OR clone and install editable for development
git clone https://github.com/h45sh/cyguide.git
cd cyguide
pip install -e .

Installing Security Tools & Dependencies

CyGuide orchestrates standard CLI security tools. You can install them automatically using our universal installer, or manually with your package manager:

A. Automated Universal Installer (Recommended)

CyGuide includes an intelligent dependency installer that auto-detects your OS and package manager, installs dependencies, handles fallbacks (e.g. downloading official binaries if a tool isn't in your distro repos), and verifies the setup:

# Install system-wide (requires sudo)
./scripts/install_deps.sh

# Install standalone binaries into ~/.local/bin (no root/sudo needed)
./scripts/install_deps.sh --user

# Verify currently installed tools without making changes
./scripts/install_deps.sh --check

B. Native Package Manager Commands

If you prefer to install packages manually using your distribution's native package manager:

sudo apt update
sudo apt install -y nmap gobuster nikto whois libxml-writer-perl curl unzip

# Install subfinder (official ProjectDiscovery binary release)
curl -fsSL https://github.com/projectdiscovery/subfinder/releases/download/v2.6.6/subfinder_2.6.6_linux_amd64.zip -o /tmp/subfinder.zip
unzip -q /tmp/subfinder.zip -d /tmp && sudo mv /tmp/subfinder /usr/local/bin/ && rm /tmp/subfinder.zip

# All tools are natively available in official Kali & Parrot repositories
sudo apt update
sudo apt install -y nmap gobuster nikto whois subfinder libxml-writer-perl

sudo pacman -Syu --needed nmap gobuster nikto whois subfinder perl-xml-writer

sudo dnf install -y nmap whois perl-XML-Writer curl unzip
# Gobuster / Nikto / Subfinder (or run ./scripts/install_deps.sh for automated binaries)
sudo dnf install -y gobuster nikto 2>/dev/null || ./scripts/install_deps.sh

sudo zypper install -y nmap whois perl-XML-Writer curl unzip
./scripts/install_deps.sh

sudo apk add nmap gobuster nikto whois perl-xml-writer curl unzip
./scripts/install_deps.sh

brew install nmap gobuster nikto whois subfinder

Launching CyGuide

# Launch with default centralized database (~/.cyguide/cyguide.db)
cyg

# Launch with a custom data directory
cyg --data-dir ~/.my_cyguide

# Launch with a custom SQLite database
cyg --db engagement.db

AI Configuration (Ollama & Cloud)

CyGuide supports both local, privacy-preserving LLMs and cloud APIs:

Local LLM (Ollama)

Launch with the --ollama flag and specify an optional model (defaults to gemma):

cyg --ollama --ollama-model llama3

Cloud LLM Providers

Set your API key via environment variable or in the in-app settings dialog (Ctrl+P -> Configuration):

export CYGUIDE_API_KEY="your_api_key_here"

# Optional overrides (defaults to OpenAI / gpt-4o)
export CYGUIDE_API_TYPE="openai"       # Options: openai, anthropic
export CYGUIDE_API_BASE="https://api.openai.com/v1" # E.g., OpenRouter, Groq, DeepSeek
export CYGUIDE_API_MODEL="gpt-4o"

Diagnostic Health Check

Verify your Python runtime, database write permissions, installed security tools, and AI backends:

cyg check

(Use cyg check --json for scriptable JSON output in CI/CD pipelines).

Session Portability & Reporting

• Export Session (cyg export): Creates a portable .db archive of findings, relationships, and raw commands:

  cyg export <session_id> exports/my_session.db
  

• Generate Technical Report: Produces a structured executive Markdown summary:

  cyg export <session_id> exports/my_session.db --report reports/investigation.md
  

• Import Session (cyg import): Restores an archive into your local workspace:

  cyg import exports/my_session.db
  

Documentation Hub

Our complete documentation is organized using the Diátaxis Framework:

• Project Webpage: Interactive project overview, features, and showcase.
• Documentation Master Hub: Central portal with role-based reading paths.
• User Manual: Navigation guide, hotkeys master table, and UI workflows.
• Architecture & Domain Context: Subsystem pipelines, ADRs, and facade contracts.
• Database Architecture & Specification: Relational schema, PIK hashing, and ER diagrams.
• Schema Registry: Standard 15-schema finding models and identity keys.
• Roadmap & Progress Tracker: Project phases, active tasks, and historical milestones.
• Autonomous Agent Harness Vision: Architecture for autonomous ReAct loops and safety gates.
• Developer Performance Notes: Real-time streaming, event loops, and lessons learned.
• Security Policy: Vulnerability disclosure channels, response SLAs, and threat model scope.
• Contributing Guide: Step-by-step guide for creating new tool plugins, code standards, and PR templates.

Contributing

Contributions are warmly welcomed! Please read our Contributing Guide to learn how to create new tool plugins, configure pre-commit hooks, and run the verification pipeline:

./scripts/verify.sh

License

This project is licensed under the MIT License - see the LICENSE file for details.