catnet

Scriptable network scanner CLI. Part of the CatNet ecosystem.

Installation

Homebrew (macOS / Linux)

brew install catnet-io/tap/catnet

Scoop (Windows)

scoop bucket add catnet https://github.com/catnet-io/scoop-bucket
scoop install catnet

Binary Download

Download pre-built binaries from GitHub Releases.

From Source

go install github.com/catnet-io/catnet/cmd/catnet@latest

Note: Chocolatey and Winget distribution support is planned for Phase 2.

Usage

Basic scan

catnet scan 192.168.1.0/24

Multiple targets

catnet scan 192.168.1.0/24,10.0.0.1-10

JSON output (for scripting)

catnet scan 192.168.1.0/24 --format json | jq '.devices[] | select(.isAlive)'

Save and re-export

catnet scan 192.168.1.0/24 --format json -o result.json
catnet export result.json --format csv -o result.csv

Custom port scan

catnet scan 192.168.1.0/24 --ports 22,80,443,8080,3306

Default ports: 22, 80, 443, 139, 445, 3389. Use --no-ports to skip port scanning entirely.

Quiet mode (scripts/CI)

catnet scan 192.168.1.0/24 --format json --quiet

Output Reference

The JSON output contains the following structure:

Field	Type	Description
schemaVersion	string	The version of the JSON schema (e.g., "2.0.0")
startTime	string	ISO 8601 timestamp when the scan started
endTime	string	ISO 8601 timestamp when the scan completed
total	int	Total number of IP addresses scanned
alive	int	Total number of hosts found alive
devices	array	List of scanned devices with their details

Device fields:

Field	Type	Description
ip	string	IPv4 address
isAlive	boolean	True if the host responded to ping
hostname	string	Reverse DNS hostname
mac	string	MAC address (if on local subnet)
openPorts	array[int]	List of open ports discovered

Exit Codes

Code	Description
0	Success
1	Input error (invalid targets or flags)
2	Runtime error (engine failure or export failure)
130	Interrupted (cancelled by signal, e.g., Ctrl+C)

Ecosystem

	Repository	Role
⚙️	catnet-io/engine	Shared Go scanning engine
💻	catnet-io/catnet	CLI (This repository)
🖥️	catnet-io/app	Desktop app
📟	catnet-io/tui	Terminal UI

Development & Security (DevSecOps)

• Branching Policy: develop is the main collaboration branch; main only accepts signed, automated PRs from develop created by github-actions[bot].
• CI/CD: Workflows validate builds, dependencies, and SAST on both main and develop branches.

License

MIT