NetCheck v2.5.0

Release Notes — NetCheck v2.5.0

Release Date: 2026-10-10
Type: Maintenance — CI Reliability, Repository Rename, Bug Fixes & Test Hardening

---

Overview

v2.5.0 is a maintenance, resilience, and stability release. It completes the repository rename from
network_access_check to netcheck across every packaging pipeline, introduces comprehensive
graceful shutdown handling for Ctrl+C (SIGINT) across all single, concurrent, and watch checks,
standardises POSIX exit codes (introducing EXIT_INTERRUPT = 130), synchronises JSON/CSV/XML output
engines for UDP and MTR checks, hardens the CI matrix by migrating the lint step from flake8 to ruff,
fixes Python 3.8/3.9 test runner syntax compatibility, and resolves timer-jitter race conditions in the cache TTL test suite.

No breaking API or CLI syntax changes. All existing commands, flags, and config formats remain
fully backward-compatible.

---

What's New

1. Repository Rename Completion (network_access_check → netcheck)

All references to the old repository name have been purged from the codebase and CI pipelines:

• .github/workflows/release.yml — Winget publish step corrected:
  • Fixed stray netcheck token that caused a PowerShell syntax error in $VERSION
    assignment.
  • Updated GitHub Releases download URL from
    farman20ali/network_access_check/releases/... to
    farman20ali/netcheck/releases/....

GitHub automatically redirects existing repository clones and web links — no action
needed for existing users.

---

2. CI Lint Step: flake8 → ruff

The CI workflow (ci.yml) was failing on all runners with:

/bin/sh: flake8: command not found
Error: Process completed with exit code 127

Root cause: flake8 was never in [project.optional-dependencies] dev, so
pip install .[dev] did not install it.

Fix: Replaced both flake8 commands with a single ruff check netcheck step.
ruff is already a dev dependency and is configured in pyproject.toml with
equivalent rule sets (E, W, F, I).

Additional ruff findings fixed at the same time:

• netcheck/post_install.py — unsorted __future__ import block (I001).
• netcheck/cli/main.py — invalid # noqa: unreachable directive (not a
  recognized rule code) converted to a plain comment.
• netcheck/cli/subcommands.py — removed unused global _metrics_registry
  declaration (F824) from _record_results_and_check_alerts; the variable is
  only read there — the actual assignment lives in _run_serve.

---

3. Python 3.8 / 3.9 Test Compatibility

tests/unit/test_mtr.py and tests/unit/test_udp.py used parenthesized
context-manager syntax introduced in Python 3.10 (PEP 617):

# Python 3.10+ ONLY — crashed with SyntaxError on 3.8 and 3.9
with (
    patch("...") as mock_a,
    patch("...") as mock_b,
):
    ...

Both files were rewritten to use nested with statements, which are valid on
all supported Python versions (3.8–3.12):

with patch("...") as mock_a:
    with patch("...") as mock_b:
        ...

---

4. Cache TTL Overwrite Race Fix + Test Hardening

Bug: tests/unit/test_cache.py::TestCacheTTL::test_overwrite_resets_ttl
failed intermittently on macOS CI runners.

Root cause (implementation): Cache.set() computed expiry with
time.time() before acquiring the lock, then called time.time() again
inside the lock for the expired-key cleanup pass. On a slow runner these two
calls could be far enough apart that the key being overwritten appeared expired
during cleanup and was evicted before the new value was stored.

Fix in netcheck/utils/cache.py:

• Compute expiry inside the lock using a single time.time() call.
• Exclude the key currently being written from the expired-key cleanup loop
  (k != key) to prevent any self-eviction race.

Root cause (test): Even with the implementation fixed, time.sleep(0.03)
on a loaded macOS runner can sleep for 0.07–0.10 s. With a TTL of 0.05 s, two
back-to-back sleeps easily exceed the new expiry window.

Fix in tests/unit/test_cache.py:

• All timing-sensitive tests now patch netcheck.utils.cache.time and advance
  time.time() return values programmatically — zero actual sleeping.
• Tests complete in < 0.1 s and are fully deterministic on any runner.
• Two additional edge-case tests added:
  • test_overwrite_expired_key_resets_ttl — overwriting an already-expired
    key still gives the new value a fresh TTL.
  • test_overwrite_does_not_count_as_new_entry — overwriting an existing key
    never triggers eviction of other cached entries.

---

5. Graceful Ctrl+C (KeyboardInterrupt) & Immediate Shutdown

Problem: Pressing Ctrl+C while checks (such as DNS resolution, multi-target TCP checks, or port scans) were in progress displayed an unhandled KeyboardInterrupt traceback dump and often caused the terminal to hang while worker threads completed blocking network sockets.

Fix:

• Added top-level signal & KeyboardInterrupt guards in netcheck.cli.main:main and netcheck.cli.subcommands:handle_subcommands.
• Pending futures in ThreadPoolExecutor are cancelled immediately on KeyboardInterrupt across batch executor, port scanner, and interface resolution.
• Standard POSIX 130 (128 + SIGINT) exit code is returned consistently.
• Interrupt message is written exclusively to sys.stderr, preserving clean stdout for pipeline tools (jq, grep).

---

6. Exit Codes Contract (EXIT_INTERRUPT = 130)

Added EXIT_INTERRUPT = 130 to netcheck/cli/exitcodes.py to complement existing codes:

• EXIT_OK = 0 (All checks passed)
• EXIT_FAIL = 1 (Target unreachable / network check failure)
• EXIT_BAD_ARGS = 2 (Invalid argument / empty targets)
• EXIT_ERROR = 3 (Runtime error)
• EXIT_INTERRUPT = 130 (Cancelled via SIGINT / Ctrl+C)

Batch targets parsing now returns EXIT_BAD_ARGS (2) when given an empty or malformed input file instead of generic failure.

---

7. Formatter Parity: UDP & MTR in JSON, CSV, and XML

v2.5.0 introduced UDP probe and MTR hops diagnostic engines. Their dispatch was missing from JSON, CSV, and XML format engines, causing -f json to fall back to generic TCP batch schemas.

• Dedicated _fmt_udp and _fmt_mtr handlers added across json_fmt.py, csv_fmt.py, and xml_fmt.py.
• Full parity between text, json, csv, and xml representations.
• Unit tests added to verify formatting accuracy.

---

Breaking Changes

None.

---

Files Changed

File	Change
netcheck/__init__.py	Version bumped to 2.5.0
pyproject.toml	Version bumped to 2.5.0
netcheck/cli/exitcodes.py	Added EXIT_INTERRUPT = 130
netcheck/cli/main.py	Top-level guarded main() entrypoint, SIGPIPE handler, graceful Ctrl+C handling
netcheck/cli/subcommands.py	Added KeyboardInterrupt handler and exit code propagation
netcheck/cli/executor.py	Cancel pending futures on interrupt; fix retry result cache
netcheck/cli/batch.py	Interrupt handling and EXIT_BAD_ARGS on empty targets
netcheck/cli/watch.py	ANSI screen clear; thread-safe rolling alert log list
netcheck/modules/port_scanner.py	Cancel pending port scan futures on KeyboardInterrupt
netcheck/modules/interfaces.py	Cancel pending public IP futures on early success and interrupt
netcheck/utils/timeout.py	Cancel future on KeyboardInterrupt in run_with_timeout
netcheck/utils/formatters/json_fmt.py	Added udp and mtr JSON formatting dispatch
netcheck/utils/formatters/csv_fmt.py	Added udp and mtr CSV formatting dispatch
netcheck/utils/formatters/xml_fmt.py	Added udp and mtr XML formatting dispatch
netcheck/utils/cache.py	set() — compute expiry inside lock; skip self-key in cleanup
tests/unit/test_cache.py	Deterministic TTL tests; 2 new edge-case tests
tests/unit/test_mtr.py	Rewritten for Python 3.8 compat — nested with
tests/unit/test_udp.py	Rewritten for Python 3.8 compat — nested with
tests/cli/test_cli_main.py	Unit test for KeyboardInterrupt exit code 130
tests/formatters/test_json_fmt.py	Unit tests for UDP and MTR JSON formatting
.github/workflows/ci.yml	Replaced flake8 lint step with ruff check netcheck
.github/workflows/release.yml	Fixed PowerShell syntax error + old repo URL in Winget step
CHANGELOG.md	Comprehensive v2.5.0 entry
README.md	Exit codes documentation table; updated badge and pkg version
packaging/vscode/src/installer.ts	Bumped REQUIRED_VERSION to 2.5.0
docs/releases/RELEASE_NOTES_V2.5.0.md	Release documentation

---

Upgrade Guide

Pip / pipx

pip install --upgrade netcheckx
# or
pipx upgrade netcheckx

Snap (Linux)

sudo snap refresh netcheck

Chocolatey (Windows)

choco upgrade netcheck

Debian package

sudo dpkg -i netcheck_2.5.0_amd64.deb

---

Release Artefacts

Artefact	Platform
netcheckx-2.5.0-py3-none-any.whl	PyPI / All platforms
netcheckx-2.5.0.tar.gz	Source distribution (PyPI)
netcheck_2.5.0_amd64.deb	Debian / Ubuntu
netcheck_2.5.0_amd64.snap	All Linux (Snap Store)
netcheck-2.5.0-setup.exe	Windows NSIS Installer
netcheck-2.5.0.nupkg	Windows Chocolatey

---

Full Changelog

See CHANGELOG.md for the complete history.

NetCheck v2.4.0

Release Notes — NetCheck v2.4.0

Release Date: 2026-08-26
Type: Feature — Security, Alerting Intelligence & Watch Mode Reliability

---

Overview

v2.4.0 is a security and reliability release focused on the watch-mode alerting engine.
It moves all sensitive credentials (SMTP passwords, Slack webhooks, Bearer tokens) to the OS
keychain (never written to disk), adds directional alert cooldowns, an --alert-on filter,
native desktop notifications on Windows/macOS/Linux, a config purge command for complete
credential wipe, a config test-alert command for instant channel verification, and a rolling
in-window alert log so history is never overwritten by the terminal refresh.

---

What's New

1. OS Keychain Credential Storage

All sensitive alerting credentials are now stored in the OS credential manager
(Windows Credential Manager, macOS Keychain, or GNOME Keyring / KWallet on Linux) instead
of plain-text config.yaml.

# Store credentials securely
netcheck config set-password email      # SMTP app-password
netcheck config set-password smtp_user  # SMTP sender address
netcheck config set-password smtp_to    # Recipient address(es)
netcheck config set-password slack      # Slack incoming webhook URL
netcheck config set-password webhook    # Generic webhook bearer token

# Remove individual credential
netcheck config clear-password email

• The config.yaml file no longer stores any secret values.
• netcheck config show displays masked previews (e.g. se...@gmail.com) alongside stored
  YAML values so you can verify what is set without exposing secrets.
• Backward-compatible: if a keyring entry is absent, the tool falls back to the YAML value.

---

2. config purge — Full Secure Wipe

netcheck config purge

Deletes config.yaml and removes all five keyring secrets in a single atomic operation.
Useful before decommissioning a machine or rotating all credentials.

---

3. config test-alert — Instant Channel Verification

netcheck config test-alert email      # Fire a test SMTP email now
netcheck config test-alert slack      # Fire a test Slack message now
netcheck config test-alert desktop    # Trigger a test desktop notification
netcheck config test-alert webhook    # POST a test webhook payload

Sends a real alert through the specified channel immediately, without needing to spin up a
watch loop or toggle a service. Reports SUCCESS or FAILED with a full error trace.

---

4. Directional Alert Cooldowns

Cooldown timers are now tracked independently per direction (UP and DOWN), so recovering
and re-failing a service each generate their own alert after the cooldown expires.

# Alert every 5 minutes per direction at most
netcheck tcp api.example.com 443 -w --alert email --alert-cooldown 300

Previously, a single shared timer could suppress a recovery alert if a DOWN alert had just
fired. Now UP and DOWN timers are decoupled.

---

5. --alert-on Trigger Filter

# Only alert when a target goes DOWN (suppress recovery notifications)
netcheck tcp api.example.com 443 -w --alert slack --alert-on down

# Alert on any state change (default)
netcheck dns google.com -w --alert email --alert-on any

# Only alert when a target recovers (UP)
netcheck http https://api.example.com -w --alert desktop --alert-on up

Value	Behaviour
any (default)	Alert on every UP to DOWN transition
down	Alert only when state transitions to DOWN
up	Alert only when state transitions to UP (recovery)

---

6. Native Desktop Notifications

--alert desktop now triggers a native OS notification on all platforms:

Platform	Mechanism
Windows 10/11	WinRT Action Center toast via PowerShell; falls back to taskbar balloon tip
macOS	osascript notification
Linux	notify-send
Any (optional)	plyer library if installed

netcheck tcp localhost 8000 -w --alert desktop --interval 2

---

7. Watch Mode Rolling Alert Log

The watch terminal window now displays a persistent Recent Alerts & Logs panel at the
bottom. Up to 8 entries are kept in a rolling buffer so that screen refreshes no longer erase
alert history.

RECENT WATCH ALERTS & LOGS:
[22:40:59] [alert] localhost:8000 is DOWN (UP to DOWN)
[22:41:02] [alert] Email sent to: user@example.com

---

8. Watch Loop Resilience

Subcommands (e.g. traceroute) that call sys.exit() internally no longer terminate the
watch loop. The SystemExit is caught and the loop continues on the next interval.

---

9. SMTP Reliability Fix

The SMTP dispatch was rewritten to match a proven reference implementation:

• Uses smtp.send_message() instead of smtp.sendmail() for robust MIME compliance.
• Calls del msg["To"] before each recipient to prevent header accumulation when sending
  to multiple addresses in a single session.
• Reuses a single SMTP connection across all recipients for efficiency.

---

Breaking Changes

None. All existing CLI flags, subcommands, and config file formats remain backward-compatible.
Secrets previously stored in config.yaml are still read as a fallback if no keyring entry
exists.

---

Files Added / Changed

File	Change
netcheck/utils/alerting.py	OS keychain credential getters; SMTP rewrite; desktop notification multi-backend engine; AlertDispatcher wired to watch log
netcheck/utils/config.py	get_smtp_user(), get_smtp_to(), get_password('slack'), get_password('webhook'); purge(); enhanced show() with masked keyring preview; init_wizard Gmail defaults
netcheck/utils/alert_state.py	Directional last_down_alert_time / last_up_alert_time per TargetState; alert_on filter in AlertStateManager.should_alert()
netcheck/cli/watch.py	Rolling _watch_logs buffer (max 8); add_watch_log(); SystemExit catch in watch loop
netcheck/cli/args.py	--alert-on {any,down,up} flag; --alert-cooldown default reduced to 60s
netcheck/cli/main.py	Legacy single-dash option normalisation (-tcp, -udp, -mtr, etc.)
netcheck/cli/subcommands.py	config purge action; config test-alert <channel> action; alert transitions piped to watch log
tests/unit/test_alerting.py	6 new tests: directional cooldown, alert_on filter, keyring getter mocks
tests/unit/test_config.py	8 new tests: purge(), show() keyring display, SMTP getters
docs/releases/RELEASE_NOTES_V2.4.0.md	New file
CHANGELOG.md	v2.4.0 entry added

---

Upgrade Guide

Pip

pip install --upgrade netcheckx

Snap (Linux)

sudo snap refresh netcheck

Debian package

sudo dpkg -i netcheck_2.4.0_amd64.deb

After upgrading — migrate credentials to keychain

netcheck config set-password email
netcheck config set-password smtp_user
netcheck config set-password smtp_to
netcheck config set-password slack
netcheck config set-password webhook
netcheck config show
netcheck config test-alert email

---

Release Artefacts

Artefact	Platform
netcheckx-2.4.0-py3-none-any.whl	PyPI / All platforms
netcheckx-2.4.0.tar.gz	Source distribution (PyPI)
netcheck_2.4.0_amd64.deb	Debian / Ubuntu
netcheck_2.4.0_amd64.snap	All Linux (Snap Store)
netcheck-2.4.0-setup.exe	Windows NSIS Installer
netcheck-2.4.0.nupkg	Windows Chocolatey

---

Full Changelog

See CHANGELOG.md for the complete history.

NetCheck v2.3.0

Release Notes — NetCheck v2.3.0

Release Date: 2026-07-30
Type: Feature — Refactor, Public IP, Output Filtering & Concurrent Ping

---

Overview

v2.3.0 is a focused feature and robustness release built on top of the v2.2.0 Tier 3 diagnostics engine. It introduces concurrent public IP resolution, output filtering for batch TCP checks, a --json shorthand flag, full IP-range concurrency for ping, and a deep module refactor that adds typed result envelopes across every diagnostic module. The formatter layer is rebuilt around a unified type-detection helper, making JSON/CSV/XML output more reliable and consistent in all code paths.

---

What's New

1. Public IP Resolution (--public)

netcheck interfaces --public          # Show public IP alongside local interfaces
netcheck --my-ip --public            # Legacy flag also supported

• Added --public flag to the interfaces subcommand and the legacy --my-ip flag.
• Queries multiple public IP APIs concurrently (race strategy — returns the first valid response) with a configurable timeout.
• APIs queried: https://api.ipify.org, https://checkip.amazonaws.com, https://icanhazip.com, and https://ifconfig.me/ip.
• Falls back gracefully to "Unknown" if all queries fail or time out.
• New public_ip_checked key is emitted in the JSON output when using -f json.

2. Output Filtering for Batch TCP / Quick Checks (--show)

netcheck tcp 192.168.1.1-50 22 --show success    # Print only successful connections
netcheck tcp 10.0.0.0/24 443 --show fail         # Print only failures
netcheck -q 192.168.1.1 80,443 --show success    # Legacy quick-mode filtering

• New --show flag accepts all (default), success, or fail.
• Works with both the tcp subcommand and the legacy -q/--quick mode.
• In text mode, only the matching result lines are printed; in JSON/CSV/XML modes, only matching records are included in the output.

3. --json Flag Alias

netcheck -q 192.168.1.1 22 --json                # Equivalent to -f json
netcheck tcp 10.0.0.1 80 --json                  # Cleaner CI syntax

• --json is now a first-class CLI flag (alias for -f json) in legacy mode.
• Eliminates the need to type -f json when piping output to jq or other JSON tools.

4. Concurrent Ping for IP Ranges

netcheck -p 192.168.1.1-20             # Pings 20 hosts concurrently
netcheck ping 10.0.0.1-50 -f json      # JSON batch envelope with typed results

• The -p / --ping legacy flag now expands IP ranges (192.168.1.1-20, 10.0.0.0/24) and executes all pings concurrently using a thread pool.
• Results are sorted by target IP for deterministic output.
• Single-host pings continue to use the simple retry path.
• New typed JSON envelope for multi-ping results:

  {
    "check_date": "2026-07-30 10:00:00",
    "type": "ping",
    "count": 20,
    "results": [
      { "target": "192.168.1.1", "success": true, "latency_ms": 1.2, ... },
      ...
    ]
  }

5. Typed Result Envelopes Across All Modules

Every diagnostic module (dns, http, ssl, ping, tcp, interfaces, traceroute, port_scanner, whois) now includes a "type" key in the result dictionary it returns. This enables downstream code (formatters, MCP tools, CI scripts) to reliably identify the result kind without heuristic metadata inspection.

Module	type value
dns.py	"dns"
http.py	"http"
ssl.py	"ssl"
ping.py	"ping"
tcp.py	"tcp"
interfaces.py	"interfaces" / "ports"
traceroute.py	"traceroute"
port_scanner.py	"scan"
whois.py	"whois"

6. Unified Result-Type Detection in Formatters

• New internal _detect_result_type(res) helper in formatters.py provides a single, authoritative dispatch path for all JSON, CSV, and XML formatting.
• Reads the "type" key first; falls back to heuristic metadata inspection for backward compatibility with pre-v2.3.0 result dicts.
• Eliminates duplicated type-sniffing logic that was previously scattered across format_json, format_csv, and format_xml.

---

Breaking Changes

None. All CLI flags, subcommands, and output formats remain fully backward-compatible.

---

Files Added / Changed

File	Change
netcheck/cli.py	Added --public, --json, --show flags; concurrent ping range dispatch; IP range handling in -p legacy mode
netcheck/modules/interfaces.py	Added get_public_ip() (concurrent multi-API fetch); get_network_interfaces emits type and public_ip_checked
netcheck/modules/ping.py	Result dict now includes "type": "ping"
netcheck/modules/dns.py	Result dict now includes "type": "dns"
netcheck/modules/http.py	Result dict now includes "type": "http"
netcheck/modules/ssl.py	Result dict now includes "type": "ssl"
netcheck/modules/tcp.py	Result dict now includes "type": "tcp"
netcheck/modules/traceroute.py	Result dict now includes "type": "traceroute"
netcheck/modules/port_scanner.py	Result dict now includes "type": "scan"
netcheck/modules/whois.py	Result dict now includes "type": "whois"
netcheck/utils/formatters.py	Added _detect_result_type(); multi-ping JSON batch envelope; unified type dispatch in format_json, format_csv, format_xml
netcheck/utils/cache.py	Minor utility improvements
netcheck/utils/normalize.py	Minor input-normalisation improvements
netcheck/utils/timeout.py	Minor utility improvements
tests/test_cli.py	Added tests for --public, --show, --quick argument validation, interfaces --public, concurrent ping range, multi-ping JSON envelope
tests/test_netcheck.py	Updated formatter tests to cover typed result detection
docs/releases/RELEASE_NOTES_V2.3.0.md	New — this file
CHANGELOG.md	v2.3.0 entry added

---

Release Artefacts

Artefact	Platform
netcheckx-2.3.0-py3-none-any.whl	PyPI / All platforms
netcheckx-2.3.0.tar.gz	Source distribution (PyPI)
netcheck_2.3.0_amd64.deb	Debian / Ubuntu
netcheck_2.3.0_amd64.snap	All Linux (Snap Store)
netcheck-2.3.0-setup.exe	Windows NSIS Installer
netcheck-2.3.0.nupkg	Windows Chocolatey

---

Upgrade Guide

Pip Install

pip install --upgrade netcheckx

Snap Package (Linux)

sudo snap refresh netcheck

Debian Package (.deb)

sudo dpkg -i netcheck_2.3.0_amd64.deb

---

Full Changelog

See CHANGELOG.md for the complete history.

NetCheck v2.2.0

Release Notes — NetCheck v2.2.0

Release Date: 2026-06-28
Type: Feature — Tier 3 Diagnostics & Advanced CLI Engine

---

Overview

v2.2.0 is a major feature update that introduces Tier 3 diagnostics (traceroute, port scan, and WHOIS/RDAP lookup), advanced SSL connection details (TLS version, cipher suite, SHA-256 fingerprint), expanded HTTP checking parameters, watch loop mode, global runtime overrides, and native shell completion support for Snap packages.

Furthermore, this release includes a premium Local Listening Ports & Services dashboard integrated directly into the interfaces subcommand, displaying active listening sockets, identifying PIDs/processes, and automatically mapping them to Docker container names.

---

What's New

1. Tier 3 Diagnostics Modules

• traceroute <host>: Identifies the network path to a target host hop-by-hop. Uses native raw ICMP sockets when run with elevated privileges, falling back automatically to standard system utilities (traceroute, tracepath, or Windows tracert).
• scan <host> [options]: Runs a high-concurrency TCP port scanner to map open ports and identify running services using an integrated services registry.
• whois <target>: Queries domain and IP registration information using modern RDAP JSON APIs, falling back to classic port 43 WHOIS lookups when needed.

2. Local Listening Ports & Services (with Docker Integration)

• The interfaces command (or -ip / --my-ip) now automatically detects local listening TCP sockets.
• Displays local address, port, and process name/PID.
• Resolves process names to active Docker container names (e.g. Docker: <container-name>) by querying Docker's port-forwarding configuration.
• Falls back to well-known service descriptions for system/hidden services when running without root privileges.

3. Advanced HTTP & SSL parameters

• Custom HTTP Execution: Subcommand http supports -X/--method (GET, HEAD, POST, PUT, DELETE, PATCH), -H/--header (custom request headers), and --auth (Basic Authentication user:pass).
• SSL Security Details: Subcommand ssl now queries and prints connection security details, including the negotiated TLS version, cipher suite, and certificate SHA-256 fingerprint.

4. Structured Machine-Readable Output for CI/CD (all formats)

• ports, scan, traceroute, and whois subcommands now emit fully-typed structured records when -f json, -f csv, or -f xml is requested — previously these fell through to the generic TCP batch format.
• JSON: type-tagged root objects ("type": "scan", "check_type": "whois"), with typed arrays (open_ports[], hops[], listening_ports[]).
• CSV: per-type column headers (e.g. Hop,IP,Hostname,Latency_MS for traceroute; Proto,Address,Port,Process,PID for ports).
• XML: per-type root elements (<port_scan>, <traceroute>, <listening_ports>, <whois_lookup>).
• Makes netcheck a fully CI/CD-ready tool: pipe JSON output directly into jq, python -c, or GitHub Actions steps.

5. Watch Loop Mode

• Any subcommand can be watched continuously by appending -w or --watch. The terminal screen clears and refreshes at a polling rate configured by -i or --interval (defaults to 2 seconds).

5. Native Snap Completions

• The Snap package configuration now declares shell completion files natively via Snapcraft's completer property, enabling tab completion for netcheck subcommands and flags out-of-the-box.

---

Breaking Changes

None. All legacy CLI flags and subcommands remain fully backward-compatible.

---

Files Added / Changed

File	Change
netcheck/modules/interfaces.py	Modified — Added listening socket parser, Docker API mapping, and --all interface filtering
netcheck/utils/formatters.py	Modified — Added formatted local listening ports table, plus JSON/CSV/XML branches for ports, scan, traceroute, whois result types
packaging/snap/snapcraft.yaml	Modified — Added native shell completer registration
tests/test_netcheck.py	Modified — Added TestFormatterTier3 (12 new tests); total suite: 60 tests
docs/releases/RELEASE_NOTES_V2.2.0.md	New — Release notes for v2.2.0
docs/examples.md	Modified — Added documentation and examples for Tier 3 commands and listening ports
CHANGELOG.md	Modified — Added comparison link and final details for v2.2.0

---

Release Artefacts

Artefact	Platform
netcheckx-2.2.0-py3-none-any.whl	PyPI / All platforms
netcheckx-2.2.0.tar.gz	Source distribution (PyPI)
netcheck_2.2.0_amd64.deb	Debian / Ubuntu
netcheck_2.2.0_amd64.snap	All Linux (Snap Store)
netcheck-2.2.0-setup.exe	Windows NSIS Installer
netcheck-2.2.0.nupkg	Windows Chocolatey

---

Upgrade Guide

Pip Install

pip install --upgrade netcheckx

Snap Package (Linux)

sudo snap refresh netcheck

Debian Package (.deb)

sudo dpkg -i netcheck_2.2.0_amd64.deb

---

Full Changelog

See CHANGELOG.md for the complete history.

NetCheck v2.1.0

Release Notes — NetCheck v2.1.0

Release Date: 2026-06-21
Type: Minor — Packaging & Tooling Modernisation

---

Overview

v2.1.0 is a packaging and tooling modernisation release. No changes were made to the netcheck runtime engine or CLI behaviour. This release reorganises the entire distribution pipeline into a clean packaging/ directory, introduces a unified version-sync tool, a new publish_packages.py publisher, and a full CI test matrix.

---

What's New

packaging/ Directory Structure

All platform-specific packaging templates are now consolidated under one top-level directory:

packaging/
├── chocolatey/         ← Windows Chocolatey (.nupkg)
│   └── tools/
├── linux/              ← install.sh / uninstall.sh
├── macos/              ← placeholder for .pkg scripts
├── snap/               ← snapcraft.yaml (version placeholder)
└── windows/            ← NSIS installer (.nsi)

Templates use a {version} placeholder that build_packages.py substitutes at build time, keeping package config separate from the build script logic.

--sync-version — Single-Command Version Bump

python3 build_packages.py --sync-version 2.2.0

Propagates the new version to every file that embeds the version string:

• netcheck/__init__.py
• pyproject.toml
• netcheck/mcp/server.py
• packaging/snap/snapcraft.yaml

publish_packages.py — Unified Publisher

A new flag-based publisher mirrors the build script interface:

python3 publish_packages.py --snap                      # push to Snap Store (stable)
python3 publish_packages.py --snap --channel edge       # push to edge channel
python3 publish_packages.py --pypi                      # upload to PyPI (production)
python3 publish_packages.py --pypi --test               # upload to TestPyPI first
python3 publish_packages.py --chocolatey                # push to Chocolatey.org
python3 publish_packages.py --check                     # verify publish tools are available

CI Workflow (.github/workflows/ci.yml)

New automated test matrix:

• Python versions: 3.8, 3.9, 3.10, 3.11, 3.12
• Platforms: Ubuntu, macOS, Windows
• Runs on every push and pull request

netcheck/__main__.py

Standard Python module entrypoint — python3 -m netcheck now works alongside the netcheck command.

---

Breaking Changes

None. All legacy CLI flags remain fully supported.

---

Files Removed

File	Reason
build-deb.sh	Superseded by python3 build_packages.py --deb
build-snap.sh	Superseded by python3 build_packages.py --snap
check_ip.py	Legacy wrapper — deleted
check_ip.sh	Legacy wrapper — deleted
PYTHON_README.md	Stub; README.md is the single source of truth
Root install.sh	Moved to packaging/linux/install.sh
Root uninstall.sh	Moved to packaging/linux/uninstall.sh
Root snap/	Moved to packaging/snap/

---

Files Added / Changed

File	Change
build_packages.py	Reads templates from packaging/; adds --sync-version
publish_packages.py	New — flag-based publisher for Snap, PyPI, Chocolatey
packaging/snap/snapcraft.yaml	Canonical Snap template
packaging/linux/install.sh	Moved from root
packaging/linux/uninstall.sh	Moved from root
packaging/windows/netcheck.nsi	NSIS installer template
packaging/chocolatey/netcheck.nuspec	Chocolatey package template
tests/test_cli.py	New — 15 CLI tests covering all subcommands
README.md	Full rewrite with accurate installation options
CHANGELOG.md	v2.1.0 entry added
pyproject.toml	License field updated to SPDX string

---

Release Artefacts

Artefact	Platform
netcheckx-2.1.0-py3-none-any.whl	PyPI / all platforms
netcheckx-2.1.0.tar.gz	Source distribution (PyPI)
netcheck_2.1.0-1_all.deb	Debian / Ubuntu
netcheck_2.1.0_amd64.snap	All Linux (Snap Store)
netcheck-2.1.0-setup.exe	Windows NSIS Installer
netcheck-2.1.0.nupkg	Windows Chocolatey

---

Upgrade Guide

From v2.0.0 (pip install)

pip install --upgrade netcheckx

From v2.0.0 (snap)

sudo snap refresh netcheck

From v2.0.0 (.deb)

sudo dpkg -i netcheck_2.1.0-1_all.deb

---

Full Changelog

See CHANGELOG.md for the complete history.

netcheck v1.2.0 - Network Diagnostics Features

Network Connectivity Checker v1.2.0

A major feature release adding comprehensive network diagnostics capabilities to netcheck.

🆕 What's New

Network Interface Display (--my-ip, -ip)

Display all your network interfaces with detailed information:

• IPv4/IPv6 addresses for each interface
• Interface status (UP/DOWN)
• Default gateway and public IP
• Smart filtering: Shows only active (UP) interfaces by default
• Use --my-ip --all to see all interfaces including inactive ones
• Clean sorted output with filtered loopback and virtual ethernet

Example:

netcheck --my-ip

HTTP Status Checking (-s, --status)

Check HTTP/HTTPS endpoints with detailed diagnostics:

• Response codes with descriptive messages (200 OK, 404 Not Found, etc.)
• Response time in milliseconds
• Content size in human-readable format
• Status categorization (success, redirect, client error, server error)
• Verbose mode shows response headers
• Comprehensive error messages

Example:

netcheck -s https://google.com
netcheck -s https://api.example.com -V  # with headers

SSL Certificate Validation (--cert)

Monitor SSL/TLS certificate expiration and validity:

• Certificate subject, issuer, and validity dates
• Days until expiry calculation
• ⚠️ Warnings for certificates expiring within 30 days
• 🚨 Critical alerts for certificates expiring within 7 days
• Verbose mode shows Subject Alternative Names (SANs)
• Supports URL or hostname:port format

Example:

netcheck --cert google.com
netcheck --cert https://github.com -V  # with SANs

Retry Logic (--retry, --retry-delay)

Automatically retry failed connections for more reliable testing:

• Configurable retry count (--retry N)
• Configurable delay between retries (--retry-delay seconds)
• Works in both file mode and quick mode
• Verbose mode shows retry attempts
• Perfect for intermittent connection issues

Example:

netcheck --retry 3 --retry-delay 2 hosts.txt
netcheck -q 192.168.1.1 80 --retry 5

📋 Full Changelog

Added

• Network Interface Display (--my-ip, -ip)

  • Show all network interfaces with IPv4/IPv6 addresses
  • Display interface status (UP/DOWN), gateway, and public IP
  • Default shows only active (UP) interfaces
  • --my-ip --all flag shows all interfaces including inactive ones
  • Sorted output with filtered loopback and virtual ethernet pairs

• HTTP Status Checking (-s, --status)

  • Check HTTP/HTTPS response codes with curl
  • Display response time in milliseconds
  • Show content size in human-readable format (bytes, KB, MB)
  • Categorize status codes (2xx success, 3xx redirect, 4xx client error, 5xx server error)
  • Verbose mode shows response headers
  • Comprehensive error messages for connection failures

• SSL Certificate Validation (--cert)

  • Check SSL/TLS certificate validity and expiration
  • Display certificate subject, issuer, and validity dates
  • Calculate days until expiry
  • Warn if certificate expires within 30 days (yellow) or 7 days (red)
  • Verbose mode shows Subject Alternative Names (SANs)
  • Support for URL or hostname:port format

• Retry Logic (--retry, --retry-delay)

  • Retry failed connections with configurable count (default: 1, no retry)
  • Configurable delay between retries in seconds (default: 1)
  • Works with both file mode and quick mode
  • Verbose mode shows retry attempts
  • Helps with intermittent connection issues

Changed

• Updated help text with all new flags and options
• Improved error messages and user guidance
• Enhanced documentation with v1.2.0 examples

Dependencies

• Added curl for HTTP status checks
• Added openssl for SSL certificate validation
• Added bc for time calculations
• Added iproute2 for network interface display

📦 Installation

Snap (Recommended - All Linux Distributions)

sudo snap install netcheck
sudo snap connect netcheck:network-observe  # For ping functionality

DEB Package (Ubuntu/Debian)

Download netcheck_1.2.0.deb from the assets below and install:

sudo dpkg -i netcheck_1.2.0.deb

From Source

git clone https://github.com/farman20ali/network_access_check.git
cd network_access_check
sudo make install

📖 Documentation

• README.md - Full documentation
• EXAMPLES.md - Comprehensive examples
• CHANGELOG.md - Complete version history

🔗 Links

• Snap Store: https://snapcraft.io/netcheck
• GitHub: https://github.com/farman20ali/network_access_check
• Issues: https://github.com/farman20ali/network_access_check/issues

💡 Quick Examples

# Check your network interfaces
netcheck --my-ip

# Check website status
netcheck -s https://google.com

# Check SSL certificate expiry
netcheck --cert github.com

# Retry failed connections
netcheck --retry 3 hosts.txt

# Combined diagnostics
netcheck --my-ip && netcheck -p 8.8.8.8 && netcheck -s https://api.example.com