Sequential Port Scanner

A command-line network port scanner built in Go that demonstrates fundamental networking concepts and sequential programming patterns. This tool scans TCP ports on specified IP addresses without using goroutines, making it an excellent showcase of basic networking I/O and loop structures.

🎯 Project Purpose

This project was designed as a sequential implementation to focus on:

• Core networking concepts using Go's net package
• Proper error handling patterns
• Clean command-line interface design
• Structured code organization

Why Sequential? This implementation intentionally avoids concurrency (goroutines) to highlight fundamental networking concepts without the complexity of concurrent programming. While this makes it slower than concurrent alternatives, it provides a clear, educational demonstration of network I/O operations.

✨ Features

• TCP Port Scanning: Uses net.DialTimeout for reliable TCP connection testing
• Flexible Input: Support for multiple IP addresses and port ranges
• Configurable Timeouts: Prevent hanging on unresponsive ports
• Progress Tracking: Real-time feedback during long scans
• Clear Output: Structured, easy-to-read results
• Input Validation: Comprehensive validation of IPs and ports
• Cross-platform: Compiles to single binary for different operating systems

🚀 Installation

Prerequisites

• Go 1.16 or higher

Build from Source

# Clone or download the source code
# Navigate to the project directory
make all

Cross-platform Builds " haven't executed any cross0build yet :) "

# Windows
GOOS=windows GOARCH=amd64 go build -o port-scanner.exe main.go

# Linux
GOOS=linux GOARCH=amd64 go build -o port-scanner-linux main.go

# macOS
GOOS=darwin GOARCH=amd64 go build -o port-scanner-macos main.go

📖 Usage

Basic Syntax

./port-scanner -ips="IP1,IP2,IP3" -ports="PORT_RANGE" -timeout=SECONDS

Command-line Options

Flag	Description	Default	Example
-ips	Comma-separated list of IP addresses	Required	"192.168.1.1,8.8.8.8"
-ports	Port range or specific ports	"1-1000"	"22-80" or "22,80,443"
-timeout	Connection timeout in seconds	2	3
-help	Show help message	-	-

Examples

Scan Common Ports on Local Router

./port-scanner -ips="192.168.1.1" -ports="22,23,53,80,443,8080"

Scan Port Range on Multiple Hosts

./port-scanner -ips="8.8.8.8,1.1.1.1" -ports="53-80" -timeout=3

Quick DNS Server Check

./port-scanner -ips="8.8.8.8,8.8.4.4,1.1.1.1" -ports="53"

Web Server Discovery

./port-scanner -ips="example.com,google.com" -ports="80,443,8080,8443"

Sample Output

Configuration:
  IPs: 8.8.8.8, 1.1.1.1
  Port range: 53-80
  Timeout: 2s
  Scan type: Sequential (no concurrency)

Starting sequential port scan...
Scanning 2 IPs, ports 53-80 (total: 56 scans)

Scanning 8.8.8.8...
  [OPEN] Port 53
Completed 8.8.8.8: 1 open ports found

Scanning 1.1.1.1...
  [OPEN] Port 53
Completed 1.1.1.1: 1 open ports found

=== SCAN RESULTS ===

8.8.8.8:
  Open ports (1): 53

1.1.1.1:
  Open ports (1): 53

=== SCAN SUMMARY ===
Total scan time: 12.34s
Total open ports found: 2
IPs scanned: 2
Ports per IP: 28

🏗️ Architecture

Core Components

1. PortScanner Struct: Main scanner configuration and methods
2. ScanResult Type: Structured result representation
3. Input Validation: Comprehensive validation for IPs and ports
4. Error Handling: Go's explicit error handling throughout

Key Functions

• ScanPort(): Core scanning logic using net.DialTimeout
• ScanAll(): Sequential scanning with progress tracking
• parsePortRange(): Flexible port range parsing
• validateIP() / validatePort(): Input validation

🔧 Technical Implementation

Networking

• Uses Go's standard net package for TCP connections
• Implements proper timeout handling with net.DialTimeout
• Graceful connection closure to prevent resource leaks

Sequential Design

for _, ip := range ps.IPs {
    for port := ps.MinPort; port <= ps.MaxPort; port++ {
        result := ps.ScanPort(ip, port)
        // Process result...
    }
}

This nested loop structure ensures:

• Complete scan of each IP before moving to the next
• Predictable resource usage
• Clear debugging and error tracking
• Educational clarity of the scanning process

⚡ Performance Characteristics

Trade-offs

• Speed: Sequential scanning is slower than concurrent approaches
• Resource Usage: Low memory and CPU usage
• Network Load: Controlled, non-aggressive scanning
• Reliability: Predictable behavior, easier debugging

Typical Performance

• ~500-1000 ports per minute (depending on network latency)
• Suitable for small to medium scan ranges
• Memory usage: minimal (~1-5MB)

🛠️ Development

Project Structure

port-scanner/
├── README.md
├── go.mod
├── go.sum (will be created automatically)
├── main.go
├── cmd/
│   └── port-scanner/
│       └── main.go (alternative structure)
├── pkg/
│   └── scanner/
│       ├── scanner.go
│       └── scanner_test.go
├── internal/
│   └── validator/
│       └── validator.go
├── examples/
│   └── basic_usage.md
├── scripts/
│   └── build.sh
├── .gitignore
└── Makefile

Code Quality Features

• Comprehensive error handling
• Input validation
• Clean separation of concerns
• Descriptive variable names
• Proper documentation

🚨 Ethical Usage

This tool is intended for:

• Educational purposes: Learning network programming
• Network administration: Checking your own infrastructure
• Security auditing: Testing systems you own or have permission to test

Important: Only scan networks and systems you own or have explicit permission to test. Unauthorized port scanning may violate terms of service or local laws.

🤝 Contributing

This is a learning project, but suggestions for improvements are welcome:

• Better error messages
• Additional output formats (JSON, CSV)
• Service detection capabilities
• IPv6 support

📝 License

This project is provided as-is for educational purposes. Feel free to use and modify as needed.

🎓 Learning Outcomes

This project demonstrates:

• Go Fundamentals: Structs, methods, error handling
• Networking: TCP connections, timeouts, address parsing
• CLI Development: Flag parsing, user input validation