netcheck

One command to diagnose any network target. Ping, traceroute, DNS lookup, port scan, SSL certificate check, HTTP probe, and WHOIS lookup -- all in one tool with clean human-readable or JSON output.

Installation

pip (recommended)

pip install netcheck-cli

pipx (isolated install)

pipx install netcheck-cli

From source

git clone https://github.com/jonathancaruso/netcheck.git
cd netcheck
pip install -e .

Quick Start

# Run all checks against a target
netcheck example.com

# Specific checks only
netcheck example.com --checks ping,dns,ssl

# Port scan
netcheck --ports 80,443,3389 10.0.0.1

# SSL certificate expiry warning
netcheck example.com --ssl --alert-days 30

# JSON output (pipe-friendly)
netcheck example.com --json
netcheck example.com --json | jq .dns

# Subnet scan
netcheck --scan 10.0.0.0/24 --ports 22,80

# Custom timeout
netcheck example.com --timeout 10

Checks

Ping

ICMP ping using the system ping command. Reports RTT (min/avg/max), packet loss, and resolved IP.

netcheck example.com --checks ping

DNS

DNS resolution for multiple record types: A, AAAA, MX, NS, TXT, CNAME, SOA.

netcheck example.com --checks dns

Port Scan

TCP port scanning with service identification and banner grabbing. Supports custom port lists and ranges.

netcheck example.com --checks ports
netcheck example.com --ports 80,443,8000-8080

Default ports scanned: 21, 22, 25, 53, 80, 110, 143, 443, 993, 995, 3306, 3389, 5432, 8080, 8443.

SSL Certificate

SSL/TLS certificate validation including subject, issuer, SANs, expiry, protocol version, and cipher details.

netcheck example.com --ssl
netcheck example.com --ssl --alert-days 60

HTTP Probe

HTTP/HTTPS endpoint probing with status codes, headers, server identification, redirect chain tracking, and response timing.

netcheck example.com --checks http

Traceroute

Network path tracing with per-hop IP addresses and RTT measurements.

netcheck example.com --checks traceroute

WHOIS

Domain registration lookup including registrar, creation/expiry dates, nameservers, and registrant info.

netcheck example.com --checks whois

JSON Output

All checks support JSON output for scripting and automation:

netcheck example.com --json

Example output:

{
  "target": "example.com",
  "checks": {
    "ping": {
      "check": "ping",
      "target": "example.com",
      "success": true,
      "rtt_avg_ms": 11.234,
      "rtt_min_ms": 10.5,
      "rtt_max_ms": 12.1,
      "packet_loss_percent": 0.0
    },
    "dns": {
      "check": "dns",
      "target": "example.com",
      "success": true,
      "records": {
        "A": ["93.184.216.34"],
        "AAAA": ["2606:2800:220:1:248:1893:25c8:1946"],
        "MX": ["0 ."]
      }
    }
  },
  "summary": {
    "total_checks": 7,
    "succeeded": 7,
    "failed": 0
  }
}

Filter specific checks with jq:

netcheck example.com --json | jq '.checks.ssl'
netcheck example.com --json | jq '.checks.dns.records.A'

Subnet Scanning

Scan entire subnets for open ports or reachable hosts:

# Scan for open web ports
netcheck --scan 10.0.0.0/24 --ports 80,443

# Ping sweep
netcheck --scan 192.168.1.0/24 --checks ping

# Custom checks on subnet
netcheck --scan 10.0.0.0/24 --checks ports --ports 22,3389

# JSON output for automation
netcheck --scan 10.0.0.0/24 --ports 22 --json

Options

Option	Description	Default
target	Hostname, IP, or CIDR range	(required)
--checks	Comma-separated check list	all checks
--json	JSON output	human-readable
--ports	Port list/ranges to scan	common ports
--ssl	SSL-only mode	-
--alert-days	SSL expiry warning threshold	30 days
--timeout	Per-check timeout	5 seconds
--scan	Subnet CIDR to scan	-
--threads	Max concurrent threads	10
--no-private	Block private/internal IPs	allow all
--version	Show version	-

Comparison with Alternatives

Feature	netcheck	nmap	mtr	mylg
Ping	Yes	Yes	Yes	Yes
Traceroute	Yes	Yes	Yes	Yes
DNS	Yes	Yes	No	Yes
Port scan	Yes	Yes	No	No
SSL check	Yes	Partial	No	No
HTTP probe	Yes	Partial	No	Yes
WHOIS	Yes	No	No	Yes
JSON output	Yes	Yes	No	No
No root required	Yes*	No	No	No
Pure Python	Yes	No	No	No
Single command	Yes	No	No	No

* Ping and traceroute use system commands which may require elevated privileges on some systems.

Security

netcheck is designed with security as a priority:

• No command injection -- all subprocess calls use argument arrays, never shell=True
• Input validation -- all hostnames, IPs, ports, and CIDR ranges are validated before use
• SSRF protection -- private/internal IP ranges can be blocked with --no-private
• Timeout enforcement -- every network operation has a configurable timeout
• Rate limiting -- subnet scans use configurable thread concurrency
• Minimal dependencies -- only dnspython and cryptography, no requests

See SECURITY.md for the full security policy and responsible disclosure instructions.

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

License

MIT License. See LICENSE for details.