Output Reference

Output Reference

Human Output (default)

catnet separates progress and results across two output streams:

• stderr: progress bar (\r updates), lifecycle messages, warnings
• stdout: results table (tabwriter-aligned)

Table columns:

Column	Description
IP	IPv4 address of the scanned host
HOSTNAME	Reverse DNS result, or — if none
MAC	MAC address, or — if not on local subnet
STATUS	ALIVE or DEAD
PORTS	Comma-separated open TCP ports, or —

Colour coding:

• ALIVE → green (\033[32m)
• DEAD → grey (\033[90m)

Colours are disabled when --no-color is set or when stdout is not a TTY.

---

JSON Output

Schema version: "2.0.0"

Top-level fields

Field	Type	Description
schemaVersion	string	Always "2.0.0"
startTime	string	ISO 8601 UTC
endTime	string	ISO 8601 UTC
total	integer	IPs submitted for scanning
alive	integer	Hosts that responded to ICMP
devices	array	One entry per scanned host

Device object fields

Field	Type	Description
ip	string	IPv4 address
isAlive	boolean	true if host responded to ping
hostname	string	Reverse DNS result ("" if none)
mac	string	MAC address ("" if not on local subnet)
openPorts	array[int]	Sorted list of open TCP ports

Full example

{
  "schemaVersion": "2.0.0",
  "startTime": "2026-06-06T12:00:00Z",
  "endTime": "2026-06-06T12:00:05Z",
  "total": 1,
  "alive": 1,
  "devices": [
    {
      "ip": "127.0.0.1",
      "mac": "",
      "hostname": "",
      "isAlive": true,
      "openPorts": [
        22,
        80
      ]
    }
  ]
}

Forward compatibility

Consumers MUST NOT fail on unknown fields. New fields may appear in future minor versions of catnet-core. If the schemaVersion major digit changes, re-export may be necessary.

---

CSV Output

Header row:

IP,Hostname,MAC,Status,Open Ports

Status values: Alive | Dead

Open Ports: semicolon-separated integers ("80;443")

Security note: fields starting with =, +, -, @, \t, or \r are prefixed with a single quote to prevent formula injection in spreadsheet applications (OWASP CSV Injection guidance).

---

XML Output

Root element: <results>

Child element: <device> — repeated per host

Sub-elements: <ip>, <hostname>, <mac>, <status>

Note: openPorts are not included in XML output. Use JSON or CSV for full data.

---

Stderr vs Stdout Contract

This contract is important for pipeline use:

Stream	Content
stdout	Machine-readable data (JSON, CSV, XML, human table)
stderr	Human-readable progress, warnings, lifecycle events

Pipeline example:

catnet scan 192.168.1.0/24 --format json 2>/dev/null | jq '.devices[]'