create nc clone in golang

thabeta commented

2026-05-02 01:09:19 +00:00

Owner

No description provided.

thabeta commented

2026-05-02 08:57:33 +00:00

Author

Owner

Implementation Specification

Objective

Build a functional netcat clone in Go from scratch that provides basic network connectivity and data transfer capabilities.

Requirements

TCP Connect Mode: connect to remote host:port, pipe stdin/stdout
TCP Listen Mode: listen on local port, accept connections
UDP Support: send/receive UDP datagrams
Port Specification: specify local or remote ports
Timeout Control: optional connection/listen timeout
stdin/stdout Piping: bidirectional data flow
Hex Dump Mode: optional hex dump output (-x flag)
Execute Command: run shell command and pipe I/O (-e flag)
Verbose Output: show connection status (-v flag)
Zero-I/O Mode: port scanning (-z flag)

Flags

Flag	Description
`-l`	Listen mode (server)
`-p`	Local port
`-n`	Numeric-only output
`-v`	Verbose output
`-x`	Hex dump mode
`-e`	Execute command
`-u`	UDP mode
`-w`	Timeout in seconds
`-z`	Zero-I/O mode (scan only)

Files to Create

File	Description
`go.mod`	Go module definition
`main.go`	Entry point, flag parsing, mode selection
`cmd/connect.go`	TCP/UDP client connection logic
`cmd/listen.go`	TCP/UDP server listening logic
`net/connection.go`	Core connection handling, I/O piping
`net/resolve.go`	DNS resolution utilities
`util/hexdump.go`	Hex dump formatting utility
`util/timeout.go`	Timeout handling utilities
`main_test.go`	Unit tests for core functionality

Step-by-Step Implementation Plan

Step 1: Initialize Go module, create directory structure, stub main.go
Step 2: Implement flag parsing and entry point with validation
Step 3: Implement core connection logic (dial, pipe I/O)
Step 4: Implement connect mode (TCP/UDP client)
Step 5: Implement listen mode (TCP/UDP server)
Step 6: Implement DNS resolution
Step 7: Implement hex dump utility
Step 8: Implement timeout utilities
Step 9: Add unit tests

Acceptance Criteria

nc -h displays usage message with all flags documented
nc -l -p 8080 listens on port 8080 and accepts one connection
nc host 80 connects to remote host on port 80
Data flows correctly stdin to remote and remote to stdout
nc -e /bin/sh -l -p 8080 spawns a shell on incoming connection
nc -v host 80 shows verbose connection info
nc -x host 80 outputs hex dump of transmitted data
nc -u host 53 uses UDP instead of TCP
nc -w 5 host 80 times out after 5 seconds
nc -z -l -p 8080 scans port (accepts and closes immediately)
Program exits cleanly with appropriate exit codes
All tests pass (go test ./...)

Notes

Stdlib only — no external dependencies
Security note: the -e flag creates a remote shell; document this
Listening on ports < 1024 requires root privileges
Timeout of 0 means no timeout (infinite wait)

## Implementation Specification ### Objective Build a functional netcat clone in Go from scratch that provides basic network connectivity and data transfer capabilities. --- ### Requirements - TCP Connect Mode: connect to remote host:port, pipe stdin/stdout - TCP Listen Mode: listen on local port, accept connections - UDP Support: send/receive UDP datagrams - Port Specification: specify local or remote ports - Timeout Control: optional connection/listen timeout - stdin/stdout Piping: bidirectional data flow - Hex Dump Mode: optional hex dump output (-x flag) - Execute Command: run shell command and pipe I/O (-e flag) - Verbose Output: show connection status (-v flag) - Zero-I/O Mode: port scanning (-z flag) ### Flags | Flag | Description | |------|-------------| | `-l` | Listen mode (server) | | `-p` | Local port | | `-n` | Numeric-only output | | `-v` | Verbose output | | `-x` | Hex dump mode | | `-e` | Execute command | | `-u` | UDP mode | | `-w` | Timeout in seconds | | `-z` | Zero-I/O mode (scan only) | ### Files to Create | File | Description | |------|-------------| | `go.mod` | Go module definition | | `main.go` | Entry point, flag parsing, mode selection | | `cmd/connect.go` | TCP/UDP client connection logic | | `cmd/listen.go` | TCP/UDP server listening logic | | `net/connection.go` | Core connection handling, I/O piping | | `net/resolve.go` | DNS resolution utilities | | `util/hexdump.go` | Hex dump formatting utility | | `util/timeout.go` | Timeout handling utilities | | `main_test.go` | Unit tests for core functionality | ### Step-by-Step Implementation Plan **Step 1**: Initialize Go module, create directory structure, stub main.go **Step 2**: Implement flag parsing and entry point with validation **Step 3**: Implement core connection logic (dial, pipe I/O) **Step 4**: Implement connect mode (TCP/UDP client) **Step 5**: Implement listen mode (TCP/UDP server) **Step 6**: Implement DNS resolution **Step 7**: Implement hex dump utility **Step 8**: Implement timeout utilities **Step 9**: Add unit tests ### Acceptance Criteria - [ ] `nc -h` displays usage message with all flags documented - [ ] `nc -l -p 8080` listens on port 8080 and accepts one connection - [ ] `nc host 80` connects to remote host on port 80 - [ ] Data flows correctly stdin to remote and remote to stdout - [ ] `nc -e /bin/sh -l -p 8080` spawns a shell on incoming connection - [ ] `nc -v host 80` shows verbose connection info - [ ] `nc -x host 80` outputs hex dump of transmitted data - [ ] `nc -u host 53` uses UDP instead of TCP - [ ] `nc -w 5 host 80` times out after 5 seconds - [ ] `nc -z -l -p 8080` scans port (accepts and closes immediately) - [ ] Program exits cleanly with appropriate exit codes - [ ] All tests pass (`go test ./...`) ### Notes - Stdlib only — no external dependencies - Security note: the `-e` flag creates a remote shell; document this - Listening on ports < 1024 requires root privileges - Timeout of 0 means no timeout (infinite wait)

thabeta commented

2026-05-02 09:01:49 +00:00

Author

Owner

Test Results

All tests pass:

=== RUN   TestHexDump
--- PASS: TestHexDump (0.00s)
=== RUN   TestHexDumpEmpty
--- PASS: TestHexDumpEmpty (0.00s)
=== RUN   TestHexDumpFullLine
--- PASS: TestHexDumpFullLine (0.00s)
=== RUN   TestResolveHostLocalhost
--- PASS: TestResolveHostLocalhost (0.00s)
=== RUN   TestParseTimeout
--- PASS: TestParseTimeout (0.00s)
=== RUN   TestParseTimeoutZero
--- PASS: TestParseTimeoutZero (0.00s)
PASS
ok  	nc  0.002s

Binary builds successfully (go build -o nc .).

## Test Results All tests pass: ``` === RUN TestHexDump --- PASS: TestHexDump (0.00s) === RUN TestHexDumpEmpty --- PASS: TestHexDumpEmpty (0.00s) === RUN TestHexDumpFullLine --- PASS: TestHexDumpFullLine (0.00s) === RUN TestResolveHostLocalhost --- PASS: TestResolveHostLocalhost (0.00s) === RUN TestParseTimeout --- PASS: TestParseTimeout (0.00s) === RUN TestParseTimeoutZero --- PASS: TestParseTimeoutZero (0.00s) PASS ok nc 0.002s ``` Binary builds successfully (`go build -o nc .`).