How Revealr Works
Revealr is structured as four loosely coupled layers communicating through well-defined interfaces, enabling high throughput without sacrificing extensibility.
CLI Input / Config
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ REVEALR CORE (Go) │
│ │
│ ┌────────────────┐ ┌────────────────────┐ │
│ │ Concurrency │ │ State Manager │ │
│ │ Engine │◄────►│ (SQLite) │ │
│ │ (Goroutines) │ │ │ │
│ │ │ │ - Resume scans │ │
│ │ - Raw Sockets │ │ - Diff / Drift │ │
│ │ - Rate Limiter│ │ - History │ │
│ │ - Scan Profiles│ └────────────────────┘ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ Service Fingerprinter │ │
│ │ (Banner Grabbing + Built-ins) │ │
│ └───────┬──────────────────────────┘ │
│ │ IPC (stdin/stdout) │
│ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ Python Plugin Bridge │ │
│ │ - Custom fingerprinters │ │
│ │ - Offline vuln checks │ │
│ │ - User-defined scripts │ │
│ └───────┬──────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ Output Layer │ │
│ │ JSON / STDOUT / Report │ │
│ └──────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Concurrency Engine
Goroutine Pool + Raw Sockets
The scanning engine uses a bounded goroutine pool to dispatch raw TCP SYN packets via raw sockets. This bypasses the OS TCP stack for maximum throughput, allowing 50,000+ probes per minute without maintaining full socket state on every port.
Rate Limiter
A token-bucket rate limiter controls the packet dispatch rate. The --rate flag configures the burst ceiling, preventing Revealr from overwhelming the target network adapter or triggering IDS rate-based alerts prematurely.
Port Range Dispatcher
Port ranges are partitioned across workers. Each worker processes a range independently, reporting open ports back to a result collector channel, ensuring all responses are captured without lock contention.
State Manager (SQLite)
Scan Resumption
Every scan writes incremental state to a local SQLite database keyed by target IP and scan session ID. If a scan is interrupted, Revealr re-reads the last known state and continues from the last unconfirmed port range.
Network Drift Detection
Historical scan results are persisted per-host. On subsequent scans, Revealr performs a structural diff between the current result set and the stored baseline. Any new open port, service version change, or disappeared service is flagged as a [DIFF] event.
Scan Session Metadata
Each session records the timestamp, operator, target, flags used, and completion status. This creates an audit-friendly history of all scans performed from a single Revealr installation.
Service Fingerprinter
Banner Grabbing
For each confirmed open port, a secondary probe establishes a brief connection to read the initial service banner. This banner is matched against a built-in pattern library to identify common services (SSH, HTTP, FTP, SMTP, Redis, etc.) without needing an external database.
Version Extraction
Regex-based version extractors parse banners to extract software version strings where available (e.g., nginx/1.18.0, OpenSSH_8.4). Version data is persisted in SQLite for drift tracking across scans.
Python Plugin Bridge
IPC via stdin/stdout
Revealr spawns Python plugin processes and communicates via JSON-encoded messages over stdin/stdout. This allows plugins to be written in standard Python without any special runtime dependencies or custom SDK installation.
Plugin Contract
Each plugin receives a JSON payload describing the open port, service fingerprint, and host metadata. It returns a JSON response with enriched data or vulnerability findings. Plugins are isolated from the Go core and cannot crash the main scanner process.
Offline Vulnerability Checks
Plugins can ship with local CVE data files or version matching tables, enabling offline vulnerability correlation without internet access — critical for air-gapped or controlled assessment environments.