Cygor

General Overview

Cygor is a modular asset discovery framework that brings scanning, parsing, and service enumeration together in one workflow. It replaces the patchwork of separate tools with an automated process that handles discovery, enrichment, and targeted enumeration seamlessly — reducing manual overhead and letting you focus on results instead of tool management.

Cygor’s Web UI takes the chaos of raw scan data and organizes it into a single, visual command center. Instead of combing through endless XML, JSON, or flat text, results are automatically parsed, enriched, and displayed in one space that’s built for fast triage and decision-making.

Powered by FastAPI and Bootstrap 5, the dashboard makes it easy to:

• See the big picture at a glance — counters and summaries reveal service distributions, status code trends, and OS fingerprints.
• Dive deep instantly — pivot from high-level metrics into per-host details, ports, and module results with just a click.
• Visualize exposure — One of Cygor's modules called Lockon takes screenshots of active web services and outputs are embedded directly, giving immediate context without leaving the dashboard.
• Stay organized during triage — mark reviewed vs. unreviewed findings, filter and sort results, and zero in on the highest-value targets.

The Web UI isn’t just for presentation — it’s about efficiency and clarity. By bringing all collected data into a single, interactive workspace, it cuts down the time spent parsing files or reconciling outputs and lets testers focus on what matters: understanding the environment and acting on it.

Why is it Called Cygor?

A lot of tools, techniques, and tradecrafts that I create are inspired from the Spawn Universe. If you have never read a Spawn comic, it's okay as I will share some information as to why I selected the character to be the name of this tool.

The name Cygor draws from Cy-Gor, a tragic anti-hero in the Spawn universe. Once Michael Konieczny — a government operative and close friend of Al Simmons — he tried to expose corruption after Simmons’s murder. However, he was captured and forced into Project Sim, the Simian experiments of Dr. Frederick Willheim, where a gorilla’s body was merged with Konieczny’s mind through invasive cybernetics. The result was the beast known as Cy-Gor — short for Cybernetic Gorilla.

After escaping captivity, Cy-Gor went on violent rampages, even tearing through government data centers in fits of confusion and rage. Though hunted and recaptured multiple times, he eventually fought back against the systems that sought to control him — removing tracking implants and breaking free to forge his own path, torn between machine, beast, and man.

• Reference: https://www.spawnworld.com/encyclopedia/cygor.htm

Who Should Use Cygor?

• Red Teams & Pentesters – Automate discovery, streamline enumeration, and maintain context across large engagements
• Blue Teams & System Administrators – Uncover unknown assets, validate inventories, and spot misconfigurations that expand attack surface.
• Security Researchers – Rapidly parse and analyze scan data to identify trends, overlooked services, and identify patterned anomalies.
• Students & Instructors – Learn real-world recon and enumeration techniques in a structured, repeatable environment.

Tools that Cygor uses:

• Nmap – Reliable service and version detection; XML output is parsed into structured host/service data.
• Masscan – High-speed port scanning for rapid discovery across large networks.
• Naabu – Simple, fast TCP port scanner that complements Masscan/Nmap workflows.
• Playwright – Browser automation engine leveraged by Lockon to capture web screenshots.
• Web content discovery – ffuf, feroxbuster, gobuster, and dirsearch are orchestrated in parallel by the webenum module (only the installed tools run).
• Service enumeration tooling – rpcclient/polenum (MSRPC), ldapsearch/ldapdomaindump (LDAP), snmpwalk/onesixtyone (SNMP), dig/dnsrecon (DNS), and showmount (NFS) back the explorer modules; each module skips cleanly if its tool is absent.
• Python libraries – (requests, colorama, SQLModel, etc.) for parsing, enrichment, output formatting, and database handling.

Installing Cygor

There are a few methods that are supported to install Cygor: pip, pipx, uv, and docker.

Installing With pipx

Some dependencies (e.g. gssapi for Kerberos/WinRM) build C extensions, so install the build toolchain and Kerberos headers first:

# Debian/Ubuntu/Kali:
sudo apt install -y build-essential python3-dev libkrb5-dev

# Stable version:
pipx install cygor

# Install from source:
git clone https://github.com/tjnull/cygor
cd cygor
pipx install .

Deploying Cygor Using Docker

Cygor's Docker setup includes both the application and a PostgreSQL database service. The system automatically falls back to SQLite if PostgreSQL is unavailable.

Quick Start

Production (recommended):

# Option 1: Use the wrapper script (automatically handles port conflicts)
./docker-compose-up.sh up --build

# Option 2: Direct docker compose (uses default ports)
docker compose up --build

Development (with source code mounted):

# Option 1: Use the wrapper script (automatically handles port conflicts)
./docker-compose-up.sh dev up --build

# Option 2: Direct docker compose (uses default ports)
docker compose -f docker-compose-dev.yaml up --build

Docker Compose Services

The Docker Compose setup includes:

• PostgreSQL Service: Automatically configured database (falls back to SQLite if unavailable)
• Cygor Service: Web UI and application
• Automatic Port Detection: Checks for port conflicts and uses alternative ports if needed
• Persistent Volumes:
  • results/: Scan outputs, credrecon results, and database files
  • cygor-config/: Local config volume (created automatically)

Port Configuration

By default:

• Production: PostgreSQL exposed on host port 5432 (if available)
• Development: PostgreSQL exposed on host port 5434 (if available)
• Internal: Containers always use port 5432 internally (Docker network)

If ports are in use, you can:

1. Use the wrapper script (recommended - auto-detects available ports):

   ./docker-compose-up.sh up --build
   

2. Set port manually:

   export POSTGRES_HOST_PORT=5435
   docker compose up --build
   

3. Remove port mapping (if you don't need external PostgreSQL access): Comment out the ports: section in docker-compose.yaml

Manual Docker Build

To build the Docker image manually:

docker build -t cygor .

Run a single container (without PostgreSQL service):

docker run --rm -v ./results:/opt/cygor/results \
  -e CYGOR_RESULTS_DIR=/opt/cygor/results \
  cygor web --host 0.0.0.0 --port 8080 --load-dir /opt/cygor/results

Database Behavior

• With Docker Compose: Uses PostgreSQL service (automatically configured)
• If PostgreSQL fails: Automatically falls back to SQLite
• Standalone container: Uses SQLite by default (unless CYGOR_DB_URL is set)

Environment Variables

Key environment variables for Docker:

Data & Workspace:

• CYGOR_RESULTS_DIR: Results directory (default: /opt/cygor/results)
• CYGOR_WORKSPACE: Workspace directory (default: /opt/cygor/results)
• CYGOR_RESULTS_PATH: Host path for results volume (default: ./results)
• CYGOR_CONFIG_PATH: Host path for authentication config volume (default: ./cygor-config)