NullSec CrystalRecon

Network Reconnaissance Engine written in Crystal

Part of the NullSec offensive security toolkit
Discord: discord.gg/killers
Portal: bad-antics.github.io

Overview

CrystalRecon is a high-performance network reconnaissance engine featuring parallel port scanning, service fingerprinting, and risk assessment. Built with Crystal's fiber-based concurrency and compile-time metaprogramming for speed and type safety.

Crystal Features Showcased

• Fibers: Lightweight concurrent scanning
• Channels: CSP-style communication
• Macros: Compile-time code generation
• Structs: Stack-allocated value types
• Enums: Type-safe enumerations
• Union Types: Nullable types (String?)
• Named Tuples: Compile-time typed hashes
• Method Overloading: Multiple dispatch

Detection Capabilities

Installation

# Clone
git clone https://github.com/bad-antics/nullsec-crystalrecon.git
cd nullsec-crystalrecon

# Build
crystal build --release crystalrecon.cr

# Or run directly
crystal run crystalrecon.cr

Usage

# Run demo mode
./crystalrecon

# Scan single host
./crystalrecon -h 192.168.1.1

# Scan network range
./crystalrecon -r 192.168.1.0/24

# Custom ports
./crystalrecon -h 192.168.1.1 -p 22,80,443,8080

# JSON output
./crystalrecon -h 192.168.1.1 --json

Options

USAGE:
    crystalrecon [OPTIONS]

OPTIONS:
    -h, --host       Target host to scan
    -r, --range      CIDR range to scan
    -p, --ports      Comma-separated ports
    -t, --timeout    Connection timeout (seconds)
    --json           JSON output format
    -v, --verbose    Verbose output

Sample Output

╔══════════════════════════════════════════════════════════════════╗
║        NullSec CrystalRecon - Network Reconnaissance Engine      ║
╚══════════════════════════════════════════════════════════════════╝

[Demo Mode]

Simulating network reconnaissance...

═══════════════════════════════════════════════════════════════════
  Host: 192.168.1.10
  OS:   Linux/Unix
  Scan: 2.5s

  Open Ports:
    22    SSH          (12.5ms) - SSH-2.0-OpenSSH_8.2
    80    HTTP         (8.3ms) - nginx/1.18.0
    443   HTTPS        (15.2ms)
    3306  MySQL        (22.1ms) - MySQL 8.0.25

  Security Findings:

  [HIGH]     Database Exposed
      Port:        3306
      Description: Port 3306 is open on 192.168.1.10
      MITRE:       T1190
      Fix:         Restrict database access to app servers

═══════════════════════════════════════════════════════════════════
  Host: 192.168.1.20
  OS:   Linux/Unix
  Scan: 3.1s

  Open Ports:
    22    SSH          (10.2ms) - SSH-2.0-OpenSSH_7.9
    5432  PostgreSQL   (18.5ms)
    6379  Redis        (8.1ms) - Redis 6.2.3
    27017 MongoDB      (25.3ms)

  Security Findings:

  [CRITICAL] Redis Exposed
      Port:        6379
      Description: Port 6379 is open on 192.168.1.20
      MITRE:       T1190
      Fix:         Enable authentication, bind to localhost

  [CRITICAL] MongoDB Exposed
      Port:        27017
      Description: Port 27017 is open on 192.168.1.20
      MITRE:       T1190
      Fix:         Enable authentication, bind to localhost

═══════════════════════════════════════════════════════════════════

  Summary:
    Hosts Scanned:    4
    Total Open Ports: 15
    Total Findings:   10
    Critical:         2
    High:             5
    Medium:           2
    Low:              1

Code Highlights

Fiber-based Concurrent Scanning

def self.scan_host(host : String, ports : Array(UInt16)) : HostInfo
  channel = Channel(PortResult).new(ports.size)
  
  # Spawn fibers for concurrent scanning
  ports.each do |port|
    spawn do
      result = scan_port(host, port)
      channel.send(result)
    end
  end
  
  # Collect results
  results = [] of PortResult
  ports.size.times do
    results << channel.receive
  end
  
  # ...
end

Compile-time Macros

macro generate_risk_rules
  [
    {
      ports: [21_u16, 23_u16],
      severity: RiskLevel::High,
      title: "Insecure Protocol Detected",
      mitre: "T1021",
      remediation: "Disable FTP/Telnet, use SFTP/SSH"
    },
    # ... more rules generated at compile time
  ]
end

RISK_RULES = generate_risk_rules

Structs - Value Types

struct PortResult
  property port : UInt16
  property state : PortState
  property service : ServiceType
  property banner : String?      # Union type (nullable)
  property response_ms : Float64
  
  def initialize(@port, @state, @service = ServiceType::Unknown, 
                 @banner = nil, @response_ms = 0.0)
  end
end

Pattern Matching with Case

def self.identify_service(port : UInt16) : ServiceType
  case port
  when 21    then ServiceType::FTP
  when 22    then ServiceType::SSH
  when 80    then ServiceType::HTTP
  when 443   then ServiceType::HTTPS
  when 3306  then ServiceType::MySQL
  when 5432  then ServiceType::PostgreSQL
  when 6379  then ServiceType::Redis
  else            ServiceType::Unknown
  end
end

Architecture

┌────────────────────────────────────────────────────────────────┐
│               CrystalRecon Architecture                        │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│   ┌──────────────────┐                                        │
│   │  Target Hosts    │  IP addresses or CIDR ranges           │
│   └────────┬─────────┘                                        │
│            │                                                   │
│            ▼                                                   │
│   ┌──────────────────────────────────────────────────┐        │
│   │           Scanner Module (Fibers)                 │        │
│   │  ┌─────────┐ ┌─────────┐ ┌─────────┐            │        │
│   │  │ Fiber 1 │ │ Fiber 2 │ │ Fiber N │ ...        │        │
│   │  │ Port 22 │ │ Port 80 │ │ Port X  │            │        │
│   │  └────┬────┘ └────┬────┘ └────┬────┘            │        │
│   │       │           │           │                  │        │
│   │       └───────────┼───────────┘                  │        │
│   │                   ▼                              │        │
│   │           ┌───────────────┐                     │        │
│   │           │   Channel     │  CSP communication  │        │
│   │           └───────────────┘                     │        │
│   └────────────────────┬─────────────────────────────┘        │
│                        │                                       │
│                        ▼                                       │
│   ┌──────────────────────────────────────────────────┐        │
│   │         Risk Analyzer (Macro-generated rules)    │        │
│   │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │        │
│   │  │ Port Rules  │ │ Service     │ │ Banner      │ │        │
│   │  │ (compile)   │ │ Detection   │ │ Analysis    │ │        │
│   │  └─────────────┘ └─────────────┘ └─────────────┘ │        │
│   └────────────────────────┬─────────────────────────┘        │
│                            │                                   │
│                            ▼                                   │
│                   ┌──────────────────┐                        │
│                   │  Report Output   │                        │
│                   │  (JSON / Text)   │                        │
│                   └──────────────────┘                        │
│                                                                │
└────────────────────────────────────────────────────────────────┘

Why Crystal?

License

MIT License - See LICENSE for details.

Related Tools

• nullsec-cppsentry - Packet sentinel (C++)
• nullsec-nimhunter - Memory forensics (Nim)
• nullsec-zigscan - Binary analyzer (Zig)