Important

Advanced parser and formatter for Nmap and RustScan outputs. Color-coded terminal reports via Rich with Catppuccin Mocha styling. Multi-format exports (JSON, CSV, HTML, XML, TXT). Interactive mode auto-detects RustScan pipe input and spawns concurrent targeted Nmap scans with live progress bars.

A deluge is an overwhelming flood of water. Felt fitting for a tool that processes massive network scan outputs and transforms raw data streams into structured, actionable intelligence.

---

§1 / Premise

Deluge is an advanced parser and formatter for network scan outputs. It auto-detects Nmap XML, Nmap stdout, and RustScan formats via a factory-pattern parser registry, then generates color-coded terminal reports with Catppuccin Mocha styling. Interactive mode spawns concurrent targeted Nmap scans with live progress bars when piped from RustScan.

Beyond parsing, Deluge provides multi-format exports (JSON, CSV, HTML, XML, TXT), HackTricks integration with direct enumeration guide links, and domain extraction from SSL certificates and host scripts. All output maintains familiar Nmap formatting while adding syntax highlighting — no reformatting, just colors on the format you already know.

Authorization Required: Designed exclusively for authorized security testing with explicit written permission.

---

§2 / Specs

KEY	VALUE
PARSING	Auto-detection · Nmap XML/stdout · RustScan · factory-pattern registry
INTERACTIVE	Concurrent Nmap · configurable workers · live progress bars · thread-safe
EXPORT	5 formats · JSON/CSV/HTML/XML/TXT · timestamped subdirs
STYLING	Catppuccin Mocha · syntax-highlighted · familiar Nmap format
INTEGRATION	HackTricks links · 40+ services · direct enumeration guides
EXTRACTION	Domain names · SSL CNs/SANs · NetBIOS · AD forest info
PLATFORM	Cross-platform · Python 3.8+ · Linux/macOS/Windows
STACK	Rich · Pydantic v2 · lxml · pytest · ruff · MIT

Architecture in §5 below.

---

§3 / Quickstart

# pipx (recommended)
pipx install git+https://github.com/Real-Fruit-Snacks/Deluge.git

# Or standard pip
pip install git+https://github.com/Real-Fruit-Snacks/Deluge.git

# Interactive mode (auto-detected from -sV flag)
rustscan -a 192.168.1.0/24 --ulimit 5000 | deluge -sV

# Parse an existing Nmap XML file
deluge --file scan.xml

# Export to all formats
rustscan -a targets.txt --ulimit 5000 | deluge -sV --export-format all

---

§4 / Reference

FLAGS

  --file <path>           Parse existing scan file (--file - for forced stdin)
  --threads <N>           Concurrent Nmap workers in interactive mode (default: 3)
  --export-format <fmt>   json csv html xml txt all
  --export-dir <path>     Export directory (creates timestamped subdirectory)
  --verbose, -v           Enable debug logging
  --no-check              Skip prerequisite and permission checks
  [nmap_args]             Nmap flags (e.g., -A, -sV, -T4) — triggers interactive mode

MODE DETECTION

  Stdin + Nmap args      Interactive (auto)
  Stdin + no args        Simple parsing
  --file <path>          File parsing
  --file -               Forced simple stdin parsing

FEATURES

  Interactive Mode       Pipe RustScan + Nmap flags → concurrent targeted scans
  Multi-Format Export    JSON/CSV/HTML/XML/TXT in timestamped subdirs
  HackTricks Links       Direct enumeration guides for 40+ services
  Domain Extraction      SSL CNs/SANs, NetBIOS, AD forest from host scripts
  Syntax Highlighting    Catppuccin Mocha on familiar Nmap format
  Safety Checks          Nmap detection, privilege warnings, input validation

EXIT CODES

  0    Success
  1    General error
  2    Input/parse error
  3    Export error
  4    Prerequisite missing (Nmap not found)

TESTING

  pytest                 All tests
  pytest --cov=deluge    With coverage
  ruff check .           Lint (matches CI)

---

§5 / Architecture

deluge/
  core/
    engine.py           Scan orchestration, interactive mode, threading
    export.py           Multi-format export manager (thread-safe)
    models.py           Pydantic v2 data models
    utils.py            Prerequisite checks, privilege detection
    logger.py           Logging configuration
  parsers/
    base.py             Abstract base parser (ABC)
    nmap_xml.py         Nmap XML parser (priority 1)
    nmap_stdout.py      Nmap stdout parser (priority 2)
    rustscan.py         RustScan output parser (priority 3)
    __init__.py         ParserFactory registry
  interface/
    cli.py              Argument handling, mode detection
    formatter.py        Rich UI — tables, panels, progress bars

Layer	Implementation
Parsing	Factory pattern · priority-ordered registry · ABC base class
Data	Pydantic v2 models · shared ScanResult schema
UI	Rich terminal UI · Catppuccin Mocha palette · progress bars
Export	Thread-safe manager · 5 formats · timestamped subdirs
Safety	Prerequisite detection · privilege warnings · input validation
Testing	pytest · coverage reporting · ruff linting

Key patterns: Parser factory tries each registered parser in priority order until one claims the input. All parsers produce a shared ScanResult Pydantic model that feeds both the Rich formatter and the export manager. Interactive mode spawns concurrent Nmap workers with live progress tracking.

---

§6 / Platform Support

Capability	Linux	macOS	Windows
File parsing	Full	Full	Full
Interactive mode	Full	Full	Full
Multi-format export	Full	Full	Full
Color output	Full	Full	Full (Windows Terminal)
Privilege detection	os.geteuid()	os.geteuid()	Admin check

---

License: MIT · Part of Real-Fruit-Snacks — building offensive security tools, one wave at a time.