🧠 SYNAPSE: Terminal Pentest State Machine & Methodology Copilot

The keyboard-driven assessment state machine, methodology copilot, and evidence engine built for penetration testers, certification candidates (eJPTv2, OSCP, CPTS, PNPT), and CTF players.

---

💡 The Problem Synapse Solves

During high-stress timed exams (eJPTv2, OSCP, CPTS) and real assessments, testers struggle with:

1. Methodology Amnesia & Blind Spots: Forgetting to check low-hanging fruit on open ports (e.g. anonymous FTP, NFS exports, SNMP community strings, Tomcat manager defaults, SMB RID cycling).
2. Rabbit-Hole Paralysis: Spending 3 hours fuzzing complex Web SQLi while overlooking an exposed backup file or weak password on port 445.
3. Credential & Lateral Movement Sprawl: Discovered passwords, hashes, and Kerberos tickets scattered across terminal tabs without tracking which targets they've been tested against.
4. Hour-23 Reporting Panic: Frantically scrolling through terminal history trying to locate required command proofs (whoami && ip a && type proof.txt) and uncropped flag screenshots.
5. Tool Bloat: Existing tools (Faraday, Dradis) require Docker, PostgreSQL, and heavy web dashboards, while AutoRecon dumps hundreds of flat text files with zero interactive state.

Synapse eliminates this friction entirely. It is a single-binary/pipx-installable terminal workbench that bridges scanner ingestion, interactive methodology checklists, lateral movement tracking, and automated exam reporting.

---

🚀 Core Capabilities

1. Multi-Source Scan Ingestor

Ingests scan outputs directly into an indexed SQLite workspace:

• Nmap XML (-oX) & Grepable (-oG): Extracts hosts, hostnames, OS detections, open ports, versions, and NSE script banners.
• NetExec (nxc) / CrackMapExec: Automatically extracts discovered domain credentials, NTLM hashes, SMB/WinRM services, and marks administrative compromise (Pwn3d!).
• Rustscan & Masscan: Ingests fast port scan JSON/list outputs.
• Plain Text Nmap (-oN): Robust regex fallback for pasted scan summaries.

1b. Initial Reconnaissance Entry Point (Target → Phase 0)

No scan output yet? Add a bare target (a) and press i in the TUI to launch host-level recon recipes (ICMP reachability, top-1000 & full TCP port scans, reverse DNS, SNMP probe). When a recipe's captured stdout is Nmap text output, Synapse automatically parses it and attaches the discovered services with their full methodology checklists — closing the loop back into the service recipe engine.

2. Built-in Methodology Copilot (45+ Services)

Contains an offline, battle-tested knowledge base covering 45+ network services (FTP, SSH, Telnet, SMTP, DNS, TFTP, HTTP, Kerberos, NFS, MSRPC, SMB, SNMP, LDAP, MSSQL, Oracle, MySQL, RDP, WinRM, Redis, MongoDB, AJP Ghostcat, Docker, etc.):

• Automatically attaches prioritized checks (Recon → Enumeration → Vulnerability Check → Exploitation → Privilege Escalation).
• Generates ready-to-run command recipes with variables auto-substituted ({IP}, {PORT}, {HOST}, {USER}, {PASS}, {DOMAIN}, {WORDLIST}).
• Status cycle on every item: [TODO] ➔ [RUNNING] ➔ [CHECKED] ➔ [FINDING] ➔ [DEAD-END].

3. Lateral Movement & Credential Vault Matrix

• Centralizes plain-text passwords, NTLM hashes (LM:NTLM and NTLM), Kerberos tickets, and SSH private keys.
• Maintains a live cross-host testing matrix showing which credentials have been tested against which target IP and protocol, with visual indicators (✔ Pwn3d, ✔ Valid, ✖ Invalid, Untested).

4. Hypotheses & Leads Board (Anti-Rabbit Hole Engine)

• Prioritized Kanban-style queue (Critical, High, Medium, Low) for tracking attack hypotheses.
• When an action item is marked as [FINDING], Synapse automatically spawns a high-priority follow-up lead.

5. Exam Evidence Ledger & Flag Validator

• Validates 32-character MD5 hashes (standard OffSec user.txt and proof.txt flags) and CTF flag formats (flag{...}, HTB{...}, THM{...}, EJPT{...}).
• Logs exact execution commands, raw terminal stdout/stderr, and timestamps.

6. Network Pivoting & Route Sentinel

• Visualizes multi-hop lab topology (Ligolo-ng, Chisel reverse SOCKS, SSH dynamic forwarding).
• Displays active local bindings and generates dynamic proxychains command prefixes.

7. Instant Notion Workspace & Report Exporter

• Notion Workspace Bundle (notion_workspace/): Generates structured, nested Markdown pages with Notion callouts, tables, and relative links ready for Notion's Import -> Markdown workflow.
• Single Markdown Report (assessment_report.md): Formatted to OffSec / INE submission guidelines (Executive summary, Credential matrix, Target machine breakdown, Port tables, Findings, and Proof logs).
• Obsidian Vault (obsidian_vault/): Generates linked Markdown notes ([[10.10.11.10]], [[Credentials]], [[Leads]]) ready to open in Obsidian.
• Full JSON Backup: 100% lossless state export and restore.

8. 100% Offline-First + Pluggable AI Advisor

• Functions completely offline without internet or API keys.
• Optionally connects to OpenAI, OpenCode, Anthropic, or local Ollama instances to provide automated banner triage and attack vector recommendations.

---

📦 Installation

Using uv (Recommended):

# Clone the repository
git clone https://github.com/Mqsirrel/cyb0x.git
cd cyb0x

# Run directly
uv run synapse

Using pip or pipx:

pip install -e .
# or
pipx install .

---

⚡ Quickstart Walkthrough

1. Ingest Sample or Real Scans

# Ingest an Nmap XML scan into a dedicated workspace
synapse --workspace exam ingest sample_scans/oscp_ad_lab.xml

# Ingest NetExec credential spray logs
synapse --workspace exam ingest sample_scans/netexec_ad_spray.log

# Check assessment metrics
synapse --workspace exam status

2. Launch the Interactive TUI

synapse --workspace exam

3. Keybindings in TUI

Key	Action
1 - 5	Switch tabs (Workbench, Cred Vault, Leads, Evidence, Pivoting)
n	State-aware Triage: what is known / unknown / tested per host + the highest-value next investigations with rationale
s	"I'm Stuck" rabbit-hole triage: separates proven dead ends from untested surface and un-sprayed credentials, and suggests state-derived escape routes (never generic command dumps)
o	Toggle the selected target in/out of engagement scope (out-of-scope hosts are dimmed and excluded from all suggestions)
t	On the Creds tab: cycle credential lifecycle against the selected target (untested → valid → invalid)
Space	Cycle status of selected checklist item or lead ([TODO] $\to$ [CHECKED] $\to$ [FINDING])
r	Launch Command Runner modal for selected recipe (Edit, execute, capture evidence). Auto-routes to Initial Recon when no service is selected yet — fresh targets never dead-end here
i	Launch Initial Reconnaissance for the selected target (phase 0: ping, top-port & full-port scans; Nmap stdout is auto-ingested back into service recipes)
a	Add target host / ports manually
c	Save discovered credential to vault
l	Record new attack lead / hypothesis
e	Capture proof flag / evidence with OffSec validation
x	Export assessment workspace (Notion, Markdown report, Obsidian vault, JSON)
? / F1	Open interactive keyboard shortcut help screen
q	Quit application

The stats banner always shows a live NEXT: hint derived from the same assessment engine that powers n, so the highest-value move is visible at a glance without opening any modal.

4. CLI Headless Mode (Pipelines & Scripts)

# Add a target manually
synapse add-target 10.10.11.50 --os Linux -p 22,80,3306

# List scope and open services
synapse list-targets

# Add discovered credentials
synapse add-cred administrator "Winter2024!" --type password --domain CORP.LOCAL --target-ip 10.10.11.50

# List credentials matrix
synapse list-creds

# Export Notion workspace bundle (Import -> Markdown in Notion)
synapse export --format notion --output ./notion_workspace

# Export publication-ready OffSec exam report
synapse export --format markdown --output ./final_report.md

---

🛠️ Custom Methodology Configuration

You can easily extend the built-in methodology by creating ~/.config/synapse/custom_methodology.yaml:

services:
  custom_api:
    ports: [9090, 9443]
    name_patterns: ["custom-api", "microservice"]
    checklists:
      - category: "enum"
        title: "Check Swagger UI & GraphQL endpoint"
        description: "Probe for exposed documentation and schema dumps"
        command_template: "curl -s -i http://{IP}:{PORT}/docs"

You can also override the phase-0 recipes by adding a top-level initial_recon: list (host-scoped variables {IP} / {HOST} only) to the same file.

---

🧪 Testing

Synapse includes a comprehensive automated test suite:

uv run pytest -v

---

📄 License

MIT License. Built for authorized security testing and education.