blank-is-open

Showcase:

cursorful-video-1768667780334.mp4

Production-grade port scanner CLI built with Effect

A fast, reliable, and type-safe port scanning tool that leverages Effect for functional error handling and resource management.

Features

• ✅ Single Port Scanning - Check specific ports quickly
• ✅ Range Scanning - Scan continuous port ranges efficiently
• ✅ Common Ports - Pre-configured list of common service ports
• ✅ Service Detection - Automatically identifies known services
• ✅ Concurrent Scanning - Configurable concurrency for optimal performance
• ✅ Type-Safe - Full TypeScript with Effect error handling
• ✅ Multiple Output Formats - Pretty terminal output or JSON for scripting
• ✅ Progress Indicators - Real-time scanning progress with spinners
• ✅ Robust Error Handling - Gracefully handles network issues, timeouts, and DNS failures
• ✅ Retry Logic - Automatic retries with exponential backoff for transient failures

Installation

npm install
npm run build

For global installation:

npm install -g .

Usage

Basic Examples

Scan a single port:

blank-is-open example.com -p 8080

Scan a port range:

blank-is-open example.com -r 8000-9000

Scan common ports:

blank-is-open example.com --common

Scan localhost:

blank-is-open localhost -p 3000
blank-is-open 127.0.0.1 -r 80-443

Advanced Options

Custom timeout (3 seconds):

blank-is-open example.com --common -t 3000

Control concurrency (50 simultaneous connections):

blank-is-open example.com -r 1-1000 -c 50

JSON output for scripting:

blank-is-open example.com --common --json > results.json

Verbose mode (shows closed ports):

blank-is-open example.com --common --verbose

Combined options:

blank-is-open example.com -r 1-10000 -c 100 -t 2000 --verbose

Options

Option	Description	Default
-p, --port <number>	Single port to scan	-
-r, --range <start-end>	Port range (e.g., 8000-9000)	-
--common	Scan common ports	false
-t, --timeout <ms>	Connection timeout (ms)	3000
-c, --concurrency <number>	Concurrent scans	50
--json	JSON output format	false
-v, --verbose	Show detailed information	false

Common Services Detected

The tool automatically identifies these common services:

• FTP (21), SSH (22), Telnet (23)
• SMTP (25), DNS (53)
• HTTP (80), HTTPS (443)
• POP3 (110), IMAP (143)
• MySQL (3306), PostgreSQL (5432)
• Redis (6379), MongoDB (27017)
• Development servers (3000, 8000, 8080, 8443)
• And many more...

Architecture

src/
├── index.ts              # CLI entry point with Commander.js
├── core/
│   ├── scanner.ts        # Port scanning orchestration
│   ├── errors.ts         # Tagged error types
│   └── config.ts         # Configuration types
├── services/
│   ├── port-checker.ts   # Low-level port checking
│   └── service-detector.ts # Service identification
├── ui/
│   ├── formatter.ts      # Output formatting
│   └── spinner.ts        # Progress indicators
└── utils/
    └── validation.ts     # Input validation

Technical Highlights

Effect Integration

• Type-safe errors using tagged unions (NetworkError, TimeoutError, ValidationError, etc.)
• Resource management with Effect.async for proper socket cleanup
• Concurrent scanning using Effect.all with concurrency control
• Retry logic with exponential backoff for network resilience
• Composable effects for clean, maintainable code

Error Handling

The tool gracefully handles:

• Invalid hostname/IP formats
• Invalid port numbers and ranges
• DNS resolution failures
• Network timeouts and connection issues
• Permission errors for privileged ports
• Common network errors (ECONNREFUSED, ETIMEDOUT, EHOSTUNREACH)

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run the CLI
npm start -- example.com --common

# Development mode (rebuild and run)
npm run dev -- localhost -p 3000

Performance Tips

• Use appropriate concurrency limits (default 50 is balanced)
• Lower timeout for faster scans of unresponsive hosts
• Use --json for parsing in scripts (no formatting overhead)
• Scan specific ranges instead of all 65535 ports

Examples

Quick health check:

blank-is-open localhost -p 3000

Full web service scan:

blank-is-open example.com -p 80 -p 443 -p 8080 --verbose

Database port scan:

blank-is-open db.example.com -r 3000-3500

Export results to JSON:

blank-is-open example.com --common --json | jq '.openPorts'

License

MIT

Requirements

• Node.js >= 18.0.0
• No sudo required for ports > 1024

---

Built with TypeScript, Effect, and attention to detail.