check_ports.py

Deterministic Port and Service Validation

check_ports.py is a deterministic TCP port validation tool designed for monitoring systems, automation pipelines, and operators who require reproducible, audit‑transparent network checks.
It supports both explicit port numbers and service names, enabling flexible, operator‑friendly configuration.

Overview

check_ports.py performs deterministic reachability checks across one or more TCP ports.
It resolves service names (e.g., ssh, https, ntp) using the system’s service database and merges them with explicitly provided port numbers.
The tool is built around three principles:

1. Determinism — same inputs → same output
2. Reproducibility — no hidden state, no environment‑dependent behavior
3. Audit Transparency — explicit reporting of open/closed ports and service mappings

Key Features

1. Multi‑port TCP reachability checks
2. Service‑name resolution (e.g., ssh → 22, https → 443)
3. Deterministic merging of service‑resolved and explicit ports
4. Operator‑grade output with open/closed state per port
5. Consistent behavior across environments
6. Structured output suitable for Nagios/Icinga

Deterministic Behavior

• Service names are resolved using a canonical lookup
• Explicit ports and service‑resolved ports are tracked separately
• Output always lists ports in deterministic order
• Open/closed states are explicit and reproducible
• No reliance on system‑specific quirks or transient state

Architecture Overview

1. Input Layer

Accepts:

• Explicit port numbers (e.g., -p 2222)
• Service names (e.g., -s ssh,https)
• Mixed input (both service names and ports)

2. Resolution Layer

Service names are resolved using the system’s /etc/services database.
UDP‑only services are rejected with a deterministic error.

3. Connection Layer

Performs TCP connection attempts with strict timeouts.
Each port is evaluated independently to avoid cascading failures.

4. Output Layer

Produces deterministic, operator‑grade output:

• Open ports
• Closed ports
• Service‑resolved vs explicit ports
• Single‑line summary for NMS integration

Example Output

    Host: example-server
    Services requested: ssh, https
    Service ports:      22, 443
    Explicit ports:     2222
    All ports:          22, 443, 2222

    example-server:22   = open
    example-server:443  = open
    example-server:2222 = closed
                

Current Status

• Version: 1.0.0
• Edition: Community Edition (public)
• Platform: Linux / Python 3.x
• Dependencies: Standard library only

Roadmap

Near‑Term

• Enhanced service‑name validation
• Improved error classification
• Optional JSON output mode

Mid‑Term

• Parallelized port checks
• Banner detection for known services
• Operator‑friendly performance metrics

Long‑Term

• Integration with deterministic network baselining
• Cross‑suite correlation with check_interfaces.py

Why check_ports.py Exists

Traditional port checkers often mix service resolution, port scanning, and environment‑dependent behavior.
check_ports.py applies deterministic engineering principles:

1. explicit service‑name resolution
2. reproducible port ordering
3. audit‑transparent open/closed reporting
4. no hidden state or nondeterministic behavior

It’s not just a port checker — it’s a deterministic validation engine.

Links

• GitHub Repository
• README (Project Overview)
• Usage Guide
• Operation Guide
• Roadmap

Related Projects

• NMS Tools Index
• NMS Tools Suite
• Check Certs
• Check HTML
• Check Interfaces
• Check the Weather
• Check Ports

License

This check_ports.py is part of the NMS_Tools suite and is released under the MIT License.
See the LICENSE file in the repository for full terms.