Build one useful command-line tool, understand its source, and produce a reproducible observation report. This lesson and source are free under the included MIT license. Release 1.0.0 uses only Python's standard library.
1. The professional problem
A network-support technician may need to check whether a known service accepts a TCP connection from a particular machine. A defensive analyst may need a timestamped observation during incident triage. A forensic examiner may use the resulting report as contextual material, with appropriate authorization and preservation. These jobs need a small repeatable procedure and an explanation of what the procedure actually measured.
Our tool resolves one host to one IPv4 address, tries 1–64 ports sequentially, and writes a JSON report plus a SHA-256 sidecar. A TCP connection attempt may be logged by endpoint security and may consume service resources. Use loopback for this lesson. Use another person's systems only with permission and a defined scope.
A connection succeeds when the operating system completes the TCP handshake. It does not tell us which application accepted it, whether that application is vulnerable, or whether authentication would succeed. A refusal is an active rejection. A timeout means the deadline expired; several explanations are possible. We deliberately never label a timeout as proof of a firewall.
2. Your deliverable and success criteria
You will produce a JSON file with the requested host, resolved IPv4 address, start/end UTC timestamps, interpreter and platform details, timeout, and a list of connection observations. Each observation contains a port, status, elapsed milliseconds, and an optional OS error number. A second file contains the hexadecimal SHA-256 digest of the exact JSON bytes.
Success means a local listening socket is reported as connected, the JSON parses, the independently calculated digest matches its sidecar, and you can explain the limitations. The tests create their own ephemeral local listener so they do not depend on a public host or on port 8765 being free.
This supports network support, network administration, security analysis, and forensic scripting practice. It is one portfolio artifact, not a professional qualification. See Careers & Pay for dated occupational references and broad-category proxy caveats.
3. Before you begin: files, terminals, and Python
A terminal is a window for entering commands. The shell interprets those commands: PowerShell on Windows, Bash in this Linux walkthrough. Python is a separate program called an interpreter; it reads and executes a source file ending in .py. Opening that file in an editor does not run it.
The current working directory is the folder a command starts from. Relative paths such as results/report.json are interpreted from that folder. A path with spaces must be quoted. Do not type a displayed shell prompt such as PS C:\> or $. If you see >>>, you are inside Python's interactive prompt; enter exit() to return to your shell.
PATH is the list of folders the shell searches for executable programs. Installing Python or uv may update PATH only for newly opened terminals. Reopening a terminal is a sensible first step when a just-installed command is not found.
Download the ZIP using this page's Download Project link. Extract the entire archive first. Do not run files from inside the ZIP viewer. Use VS Code, VSCodium, Notepad, or another plain-text editor to inspect network_triage.py. A word processor may insert formatting that breaks source files. No editor account is required.
4. Windows setup: PowerShell and folders
Open Start, search for PowerShell, and open it as an ordinary user. Administrator access is not needed for this loopback lab. In File Explorer, extract the download and locate the folder containing network_triage.py. Copy that folder's full path from the address bar.
Set-Location "C:\Users\YOUR_NAME\Downloads\PP-001-1.0.0"
Get-Location
Get-ChildItem
Replace YOUR_NAME and the folder path with your actual extracted location. Get-Location should show that folder; Get-ChildItem should include network_triage.py and test_network_triage.py. These commands only change or inspect your terminal's folder.
The recommended environment method is uv. Verify Windows Package Manager first; then install uv from its documented WinGet identifier.
winget --version
winget install --id=astral-sh.uv -e
Reopen PowerShell after installation, return to the project folder, then run:
uv --version
uv python install 3.14
uv run --python 3.14 network_triage.py --help
The expected help lists --host, --ports, --timeout, --output, and --authorized. Version strings vary. uv run selects the requested interpreter; it does not require a project account or external packages here. If WinGet is missing, use the official uv installation options. Follow your organization's installation policy.
The standard alternative is an installed CPython interpreter. Install Python from python.org using its official installer if needed. Verify the launcher before proceeding:
py --version
py -m venv .venv
.\.venv\Scripts\python.exe network_triage.py --help
The virtual environment is a disposable local interpreter environment. This project has no external dependencies, so it is optional; we introduce it because it is useful for later projects. Directly invoking its Python avoids PowerShell activation-policy changes. If py is missing but python --version works, substitute python for py in the first two commands. Check the reported version rather than assuming which interpreter a command selects.
5. Linux setup: Bash and folders
Open your distribution's terminal. Extract the ZIP using the file manager and locate the directory containing network_triage.py. Example commands below assume that directory is under Downloads; adjust the path to match your machine.
cd "$HOME/Downloads/PP-001-1.0.0"
pwd
ls
cd changes directory, pwd prints it, and ls lists files. Quoting a path preserves embedded spaces. Linux filenames are case-sensitive. The $HOME expression is expanded by Bash to your own home directory.
For uv, download the official installer to a file for inspection before executing it:
curl -LsSf https://astral.sh/uv/install.sh -o install-uv.sh
less install-uv.sh
sh install-uv.sh
Press q to leave less. Read the script and its source before deciding to run it. If curl or less is unavailable, use your distribution's documented package manager or another installer option from the official uv documentation. Do not run the installer with sudo to solve PATH problems. Reopen the terminal, return to the extracted folder, and verify:
uv --version
uv python install 3.14
uv run --python 3.14 network_triage.py --help
For the standard alternative:
python3 --version
python3 -m venv .venv
./.venv/bin/python network_triage.py --help
Some Debian/Ubuntu installations need the distribution's python3-venv package before the second command works. Consult the distro documentation for your actual version and permissions. Never use sudo pip to modify a system-managed interpreter. Do not copy a Windows .venv into Linux; recreate it there.
WSL is a Linux environment hosted on Windows, with distinct networking and filesystem behavior. It is useful additional evidence, but it is not equivalent to testing every standalone Linux distribution. The release matrix states which environment was actually used.
6. First result: the controlled loopback lab
An IP address identifies a network endpoint. The address 127.0.0.1 refers back to this machine in the current network environment. A TCP port identifies a destination within that endpoint. We will temporarily run Python's HTTP server as a known listener on port 8765, bound only to loopback.
Open two terminals in the project directory. Terminal A runs the fixture until you stop it. Terminal B runs the scanner. Select the command variants in the command panel above this article, or use these standard-interpreter commands.
Windows, terminal A:
.\.venv\Scripts\python.exe -m http.server 8765 --bind 127.0.0.1
Windows, terminal B:
.\.venv\Scripts\python.exe network_triage.py --ports 8765,8766 --output results/lab-before.json
Get-Content .\results\lab-before.json
Linux, terminal A:
./.venv/bin/python -m http.server 8765 --bind 127.0.0.1
Linux, terminal B:
./.venv/bin/python network_triage.py --ports 8765,8766 --output results/lab-before.json
cat results/lab-before.json
Port 8765 should show connected while that server is listening. If it cannot start because the address is in use, another program may already own that port. Stop your lab and choose an unused high port consistently in both terminals. Do not kill an unfamiliar system service.
Port 8766 may be refused, time out, or even connect if another service is there. Record what you observed instead of forcing the output to match a screenshot. This release's non-listener test produced a timeout on Windows and a refusal on Ubuntu WSL during development.
Press Ctrl+C in terminal A to stop the HTTP server. Repeat the scan in terminal B with --output results/lab-after.json. Compare the observations. Use a new filename because exclusive creation prevents overwriting previous evidence. The stopped listener should no longer provide the earlier successful connection, but another process or local policy can change the outcome.
7. Checkpoint A: one ordinary TCP connection
Create checkpoint_a.py with the following code. Run it while terminal A's local service is active. The code deliberately lets exceptions reach the terminal so you can see a real failure.
import socket
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as connection:
connection.settimeout(0.5)
connection.connect(("127.0.0.1", 8765))
print("connected")
The import binds the socket module to a name. The call socket.socket(...) returns a socket object. AF_INET chooses IPv4; SOCK_STREAM chooses TCP's stream interface. The as clause binds that object to connection. Four spaces indent the statements inside the with block; its context manager closes the socket when control leaves that block, including after an exception.
The dot accesses an attribute or method. Parentheses call a function, commas separate arguments, and the inner parentheses construct the address tuple. The string supplies the address and the integer supplies the port. A timeout is a float measured in seconds. connect returns None on success and raises an exception on failure.
Expected result with the fixture active: connected. Stop the service and rerun. The error details depend on the OS and local policy. Restart the fixture before continuing. The final scanner adds explicit classification and reporting around this same kind of operation.
8. Checkpoint B: reuse the reviewed connection function
Create checkpoint_b.py next to the final source:
from network_triage import check_tcp_port
for port in [8765, 8766]:
observation = check_tcp_port("127.0.0.1", port, 0.5)
print(observation)
The import guard in network_triage.py keeps importing from starting a scan. A list uses square brackets. The for statement binds port to each element in order, and indentation selects the repeated body. Each call returns a dictionary: a mapping from named keys to values. Strings carry labels; integers carry ports and error numbers; a float carries duration; None indicates that no OS error number was recorded.
Predict whether every returned dictionary will have the same keys. Answer: yes, because the function constructs one common return dictionary after its branches. Predict whether status and elapsed_ms will be identical. Answer: no; connection outcomes and timing are observations.
9. Checkpoint C: arguments, reports, and the final program
Run network_triage.py --help with your selected interpreter, then run the final lab command. Compare this progression: checkpoint A makes one raw connection; checkpoint B reuses classification for two ports; the final program validates options, resolves a target, gathers observations, records provenance, writes bytes, and hashes those exact bytes.
The source explorer below displays the exact downloaded source and its revision hash. Inline comments explain each important operation; this section supplies the language and operating-system context those comments refer to.
def introduces a function. Parameters name its inputs, return hands a value to the caller, and local variables exist within that call. main(argv=None) accepts an optional argument list for tests; ordinary CLI use reads the real process arguments. The __name__ guard runs main only when Python executes this file directly.
argparse stores named option values in an object. A type function such as parse_ports transforms and validates a string before collection begins. Defaults supplied as strings pass through argparse's conversion too. action="store_true" creates a Boolean flag. Validation errors use exit status 2, successful collection uses 0, and operational failures use 1.
parse_ports splits on commas, strips surrounding whitespace, checks ASCII decimal notation, converts to integers, deduplicates with a set, and sorts the result. A set uses braces and contains unique values; a dictionary also uses braces but has key:value pairs. A generator expression supplies values to any without constructing another list. A comprehension expresses a compact loop. The input is limited to 64 tokens before deduplication.
and requires both conditions; or accepts either. not reverses truth. The comparisons <, >, and <= test ordering; == compares values. = assigns a name. A colon ends a compound statement header or separates dictionary keys from values. Quotes create strings; \n represents a newline inside a string. The multiplication by 1000 converts seconds to milliseconds; round(..., 3) limits decimal representation without increasing timing accuracy.
try encloses operations that may fail. except selects an exception type. raise propagates a failure; raise ... from exc preserves its cause. Connection timeouts, OS errors, DNS failures, and output failures mean different things and should not be silently collapsed into "closed". The Windows refusal code 10061 is handled alongside errno.ECONNREFUSED.
socket.gethostbyname resolves once, then the scanner uses that resolved address for all attempts. Hostnames can resolve to several addresses; this tool chooses one IPv4 result and records it. DNS resolution is outside the per-connection timeout. A non-loopback address requires --authorized, which is a reminder of scope, not a mechanism that grants permission.
The list comprehension in main calls check_tcp_port sequentially. With 64 ports and a 10-second timeout, connection waiting can approach 640 seconds; resolution and filesystem operations add overhead. There is no multi-host range, UDP, IPv6, banner retrieval, credential testing, stealth technique, or vulnerability detection.
10. Timestamps, output bytes, and integrity
UTC timestamps answer when the machine's wall clock said an event happened. They contain +00:00 to make the timezone explicit. They depend on the system clock and are not independently certified time. time.monotonic measures a duration; it is useful for elapsed time even when the wall clock changes.
Path builds filesystem paths independently of slash conventions. The output parent is created if needed. JSON is serialized with sorted keys and indentation, followed by a newline, then encoded once as UTF-8 bytes. Binary writing preserves those bytes across Windows and Linux. Changing indentation, line endings, or encoding changes the digest.
Exclusive modes xb and x fail if their destination already exists. This protects earlier outputs. The JSON and sidecar are separate writes: if the second write fails, a JSON file may remain. An interrupted or disk-full write may also leave an incomplete file. A failed command means you must inspect its artifacts and rerun to fresh paths. Do not treat a leftover file as a completed collection.
Verify independently on Windows:
Get-FileHash -Algorithm SHA256 .\results\lab-before.json
Get-Content .\results\lab-before.sha256
.\.venv\Scripts\python.exe -m json.tool .\results\lab-before.json
Verify independently on Linux:
sha256sum results/lab-before.json
cat results/lab-before.sha256
./.venv/bin/python -m json.tool results/lab-before.json
Compare the hexadecimal digests ignoring letter case. json.tool parses the file and prints a readable version; do not redirect it over the original evidence file. The package sidecar is a raw digest, not the filename-bearing format expected by sha256sum --check.
A matching digest demonstrates agreement with that particular baseline. Anyone who can replace both colocated files can generate a matching new pair. Independent authenticity, original acquisition, and chain of custody require additional controlled records and procedures. Record who collected the data, why, from which machine, with what scope, and where the baseline was preserved.
11. Run the tests
From the extracted project folder, use your chosen interpreter:
.\.venv\Scripts\python.exe -m unittest -v
./.venv/bin/python -m unittest -v
The suite exercises a real temporary loopback listener, a reserved non-listener, JSON parsing, independent hashing, tamper detection, invalid ports/timeouts, existing files, output path failures, help, and the authorization guard. DNS, timeouts, and some OS errors use mocks so those failures can be reproduced without scanning third parties. Mock success is not evidence that a real network produced that condition.
Tests use temporary directories and ephemeral ports assigned by the OS. Their expected result is an OK summary. Their execution time varies. The release matrix below reports actual runs, including the distinction between native Windows and Linux under WSL.
12. Troubleshooting clinic
python or py is not recognized: confirm the interpreter installation, reopen the terminal, and run its version command. On Linux, try python3. Do not type Python source into PowerShell.
uv: command not found: reopen the shell and inspect the installer's PATH guidance. Check the official installation documentation. Avoid adding untrusted directories to PATH.
Cannot open network_triage.py: run Get-Location/Get-ChildItem or pwd/ls. Enter the extracted folder. Check the exact filename; Windows may hide extensions, producing a mistaken .py.txt file.
Address already in use: the lab server could not bind the selected port. Choose another unused high port in both fixture and scanner commands. Confirm the bind address remains 127.0.0.1.
Invalid ports: use 1–64 comma-separated decimal integers from 1 to 65535. Ranges, blank tokens, signed numbers, and arbitrary strings are rejected.
Invalid timeout: use a finite number between 0.01 and 10. NaN and infinity are not usable deadlines.
Name resolution failure: confirm the hostname and network context. For this lab, use the literal 127.0.0.1 to avoid DNS. Do not interpret DNS failure as evidence about a port.
File exists or permission denied: choose a new output filename in a writable project folder. Inspect both JSON and sidecar destinations. Do not change system-wide permissions or run as administrator as a blanket fix.
Execution policy blocks activation: use the direct .venv interpreter path shown here. Activation is optional; this lab never requires disabling PowerShell protections.
JSONDecodeError or mismatched digest: preserve the suspect files, check whether collection failed or a text editor changed the file, and repeat with fresh paths. Do not edit a digest to make an altered report appear verified.
13. Exercises and worked solutions
Exercise 1 — duplicates: predict the parsed order for 8766,8765,8765. Solution: [8765, 8766]. The set removes repeats and sorted establishes numeric order. Add a unit test using assertEqual if you change the parser.
Exercise 2 — one byte: copy a lab report, append one space to the copy, and hash both files. Solution: digests should differ although both files may still parse as JSON. A hash covers bytes rather than a chosen interpretation of JSON.
Exercise 3 — report reasoning: after stopping the fixture, explain why timeout does not prove that the host is offline. Solution: local filtering, an unresponsive path, scheduling, and the short deadline are alternative explanations. The report should describe the observation and the conditions under which it was made.
Exercise 4 — timeout budget: estimate the connection-wait budget for 20 ports at 0.5 seconds. Solution: approximately 10 seconds in the worst case where every attempt waits to its deadline, plus other overhead; successful or refused attempts often finish sooner. DNS has no bound from this option.
Exercise 5 — refusal classification: explain why the suite mocks both errno.ECONNREFUSED and 10061. Solution: the operating-system interface may express the same kind of failure using different numeric values. The test validates classification independently of whether the host actually returns a refusal today.
Challenge — portfolio summary: collect before/after reports, verify their digests independently, and write a short comparison. Correctness requires scope, command, tool revision, environment, timestamps, observations, uncertainty, and limitations. Claiming a vulnerability merely because connected appears is incorrect.
14. Professional handoff
Include source revision, exact commands, original reports and sidecars, independent verification notes, and a findings summary. A sample template is included in the ZIP. If you share a real report, review hostnames, paths, and environment details for private information. The supplied fixture report is a development lab capture, not customer data.
Next, explore Network Engineering, Digital Forensics, the Network Snapshot Differ preview, and the Network Field Manual proposal. The other paid products remain planned.
15. References and version record
Release 1.0.0 introduces the scanner, bounded parser, loopback lab, tests, source annotations, and offline package. The release JSON records source SHA-256 and actual test environments.
References: Python socket, argparse, venv, hashlib, and official uv installation. Setup instructions were reviewed against these primary references on November 7, 2026; the installation commands themselves are not all claimed as executed on fresh machines.
Exact source · line explorer
Release 1.0.0. Every executable source line has an explanation. Repeated language constructs are explained in chapters 7–10 above. Expand a line to read its role.
2import argparse # Parse named command-line options and report usage errors.
Parse named command-line options and report usage errors.
3import errno # Translate operating-system error numbers without guessing vulnerabilities.
Translate operating-system error numbers without guessing vulnerabilities.
4import hashlib # Compute a SHA-256 digest of the exact report bytes.
Compute a SHA-256 digest of the exact report bytes.
5import ipaddress # Identify loopback addresses for the authorization guard.
Identify loopback addresses for the authorization guard.
6import json # Serialize dictionaries and lists into portable structured text.
Serialize dictionaries and lists into portable structured text.
7import math # Reject NaN and infinite timeout values.
Reject NaN and infinite timeout values.
8import platform # Record the environment that produced the observations.
Record the environment that produced the observations.
9import socket # Ask the operating system to make ordinary TCP connections.
Ask the operating system to make ordinary TCP connections.
10import sys # Send operational failures to stderr and return an exit status.
Send operational failures to stderr and return an exit status.
11import time # Measure elapsed durations with a clock that cannot jump backwards.
Measure elapsed durations with a clock that cannot jump backwards.
12from datetime import datetime, timezone # Use explicit UTC wall-clock timestamps.
Use explicit UTC wall-clock timestamps.
13from pathlib import Path # Build filesystem paths without shell-specific separators.
Build filesystem paths without shell-specific separators.
15VERSION = "1.0.0" # Identify the source and report format release.
Identify the source and report format release.
16DEFAULT_PORTS = "8765,8766" # Use a small local lab rather than a public target.
Use a small local lab rather than a public target.
19def utc_now():
Define utc_now(). Parameters bind caller inputs; the indented body runs when called, not when defined.
20 return datetime.now(timezone.utc).isoformat() # Return an aware UTC timestamp string.
Return an aware UTC timestamp string.
23def parse_ports(text):
Define parse_ports(text). Parameters bind caller inputs; the indented body runs when called, not when defined.
24 parts = text.split(",") # Split a comma-separated string into individual tokens.
Split a comma-separated string into individual tokens.
25 if len(parts) > 64: # Bound the request before constructing connection attempts.
Bound the request before constructing connection attempts.
26 raise argparse.ArgumentTypeError("provide at most 64 ports")
Convert validation failure to ArgumentTypeError so argparse can show help context and exit with status 2.
27 try:
Start a block whose failures are handled by the following except clauses. Successful statements continue in order.
28 if any(not part.strip().isascii() or not part.strip().isdecimal() for part in parts): # Reject blanks, signs, ranges, and non-ASCII numerals.
Reject blanks, signs, ranges, and non-ASCII numerals.
29 raise ValueError("use comma-separated decimal integers")
Reject the invalid input with the specific message shown here. The surrounding except converts this ValueError to a CLI type error.
30 ports = sorted({int(part.strip()) for part in parts}) # Convert, deduplicate with a set, and sort for stable order.
Convert, deduplicate with a set, and sort for stable order.
31 if not ports or any(port < 1 or port > 65535 for port in ports): # TCP port numbers must fit the valid nonzero range.
TCP port numbers must fit the valid nonzero range.
32 raise ValueError("ports must be between 1 and 65535")
Reject the invalid input with the specific message shown here. The surrounding except converts this ValueError to a CLI type error.
33 return ports # Hand a list of integers back to argparse and the caller.
Hand a list of integers back to argparse and the caller.
34 except ValueError as exc: # Convert a conversion/range failure into a friendly CLI diagnostic.
Convert a conversion/range failure into a friendly CLI diagnostic.
35 raise argparse.ArgumentTypeError(str(exc)) from exc # Preserve the original cause for debugging.
Preserve the original cause for debugging.
38def parse_timeout(text):
Define parse_timeout(text). Parameters bind caller inputs; the indented body runs when called, not when defined.
39 try:
Start a block whose failures are handled by the following except clauses. Successful statements continue in order.
40 value = float(text) # Accept fractional seconds such as 0.5.
Accept fractional seconds such as 0.5.
41 if not math.isfinite(value) or not 0.01 <= value <= 10: # NaN bypasses ordinary comparisons unless checked explicitly.
NaN bypasses ordinary comparisons unless checked explicitly.
42 raise ValueError("timeout must be finite and between 0.01 and 10 seconds")
Reject the invalid input with the specific message shown here. The surrounding except converts this ValueError to a CLI type error.
43 return value
Return the validated floating-point timeout to the caller; no further statements in this function run.
44 except ValueError as exc:
Handle this exception class from the preceding try block. The as clause binds the exception so its message can become a useful CLI diagnostic.
45 raise argparse.ArgumentTypeError(str(exc)) from exc
Convert validation failure to ArgumentTypeError so argparse can show help context and exit with status 2.
48def check_tcp_port(address, port, timeout):
Define check_tcp_port(address, port, timeout). Parameters bind caller inputs; the indented body runs when called, not when defined.
49 started = time.monotonic() # Duration is measured independently of wall-clock adjustments.
Duration is measured independently of wall-clock adjustments.
50 error = None # None becomes JSON null when no OS error was recorded.
None becomes JSON null when no OS error was recorded.
51 try:
Start a block whose failures are handled by the following except clauses. Successful statements continue in order.
52 with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as connection: # Create an IPv4 TCP socket; with closes it on every exit.
Create an IPv4 TCP socket; with closes it on every exit.
53 connection.settimeout(timeout) # Bound this connection attempt, not DNS or total filesystem work.
Bound this connection attempt, not DNS or total filesystem work.
54 connection.connect((address, port)) # A tuple identifies one destination; success returns None.
A tuple identifies one destination; success returns None.
55 status = "connected" # A completed TCP handshake is an observation, not application identification.
A completed TCP handshake is an observation, not application identification.
56 except (TimeoutError, socket.timeout): # Timeout means the deadline expired; it does not prove filtering.
Timeout means the deadline expired; it does not prove filtering.
57 status = "timeout"
Classify only the expired deadline. This label does not infer a firewall or whether the host is offline.
58 except OSError as exc: # Preserve other failures, including refusals and unreachable hosts.
Preserve other failures, including refusals and unreachable hosts.
59 error = exc.errno
Read the numeric operating-system error code from the caught exception. Preserve it in the returned observation.
60 status = "refused" if exc.errno in (errno.ECONNREFUSED, 10061) else "error" # Windows and Unix may use different numeric codes.
Windows and Unix may use different numeric codes.
61 return {"port": port, "status": status, "error_code": error, "elapsed_ms": round((time.monotonic() - started) * 1000, 3)} # Values vary with the host and network.
Values vary with the host and network.
64def main(argv=None):
Define main(argv=None). Parameters bind caller inputs; the indented body runs when called, not when defined.
65 parser = argparse.ArgumentParser(description=__doc__) # argv=None uses the real CLI; tests can supply a list.
argv=None uses the real CLI; tests can supply a list.
66 parser.add_argument("--host", default="127.0.0.1", help="one IPv4 address or hostname")
Register this named CLI option, its default/conversion or Boolean action, and help text. parse_args later validates the supplied value.
67 parser.add_argument("--ports", type=parse_ports, default=DEFAULT_PORTS, help="1–64 comma-separated ports")
Register this named CLI option, its default/conversion or Boolean action, and help text. parse_args later validates the supplied value.
68 parser.add_argument("--timeout", type=parse_timeout, default=0.5, help="seconds per connection, 0.01–10")
Register this named CLI option, its default/conversion or Boolean action, and help text. parse_args later validates the supplied value.
69 parser.add_argument("--output", type=Path, help="new JSON path; existing files are never overwritten")
Register this named CLI option, its default/conversion or Boolean action, and help text. parse_args later validates the supplied value.
70 parser.add_argument("--authorized", action="store_true", help="confirm authorization for a non-loopback destination")
Register this named CLI option, its default/conversion or Boolean action, and help text. parse_args later validates the supplied value.
71 args = parser.parse_args(argv) # Invalid arguments cause argparse to exit with status 2 before scanning.
Invalid arguments cause argparse to exit with status 2 before scanning.
72 try:
Start a block whose failures are handled by the following except clauses. Successful statements continue in order.
73 address = socket.gethostbyname(args.host) # Resolve once to one IPv4 address; DNS time is not bounded by --timeout.
Resolve once to one IPv4 address; DNS time is not bounded by --timeout.
74 if not ipaddress.IPv4Address(address).is_loopback and not args.authorized: # The resolved address is also the address we connect to.
The resolved address is also the address we connect to.
75 parser.error("non-loopback targets require --authorized and permission from their owner")
Stop before scanning a resolved non-loopback destination without the explicit scope confirmation. argparse prints usage and exits with status 2.
76 started = utc_now()
Capture the UTC start string before making connection attempts.
77 observations = [check_tcp_port(address, port, args.timeout) for port in args.ports] # Run sequentially, with no banner requests or concurrency.
Run sequentially, with no banner requests or concurrency.
78 report = {"schema_version": 1, "tool_version": VERSION, "started_utc": started, "finished_utc": utc_now(), "requested_host": args.host, "resolved_ipv4": address, "timeout_seconds": args.timeout, "python": platform.python_version(), "platform": platform.platform(), "observations": observations}
Assemble provenance and observations into a dictionary. Keys are strings; values include strings, numbers, and the observation list. No claim of clock authenticity is implied.
79 payload = (json.dumps(report, indent=2, sort_keys=True) + "\n").encode("utf-8") # Encode once so the hash and saved bytes agree.
Encode once so the hash and saved bytes agree.
80 output = args.output or Path("results") / (datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ") + ".json")
Use the requested Path when supplied; otherwise construct a UTC microsecond filename under results. Exclusive creation handles any filename collision.
81 output.parent.mkdir(parents=True, exist_ok=True) # Create missing parent directories; permission errors remain errors.
Create missing parent directories; permission errors remain errors.
82 with output.open("xb") as handle: # Exclusive binary creation prevents silently overwriting an earlier report.
Exclusive binary creation prevents silently overwriting an earlier report.
83 handle.write(payload)
Write the exact encoded bytes to the exclusively created JSON file. A disk failure can leave a partial file.
84 sidecar = output.with_suffix(".sha256") # Replace .json with .sha256, keeping the same base name.
Replace .json with .sha256, keeping the same base name.
85 with sidecar.open("x", encoding="utf-8", newline="\n") as handle: # Exclusive text creation also protects an existing sidecar.
Exclusive text creation also protects an existing sidecar.
86 handle.write(hashlib.sha256(payload).hexdigest() + "\n") # Store a digest only, not proof of independent authenticity.
Store a digest only, not proof of independent authenticity.
87 print("Report:", output)
Print the path of the saved JSON for the operator. This does not independently verify its contents.
88 print("SHA-256:", sidecar)
Print the separate digest path after its write succeeds.
89 for item in observations:
Iterate over the collected dictionaries in port order, binding item to each observation.
90 print(str(item["port"]) + "/tcp", item["status"]) # Human summary; the JSON retains the detailed observations.
Human summary; the JSON retains the detailed observations.
91 return 0 # Successful collection may include refused, timeout, or error observations.
Successful collection may include refused, timeout, or error observations.
92 except (OSError, ValueError) as exc: # DNS and file failures produce an operational error; a JSON file may remain if sidecar creation fails.
DNS and file failures produce an operational error; a JSON file may remain if sidecar creation fails.
93 print("Collection failed:", exc, file=sys.stderr)
Write the operational failure and original exception text to stderr so collection failure is visible to callers.
94 return 1
Return an operational-failure exit code. Inspect stderr and any partial files before rerunning.
97if __name__ == "__main__": # Importing the file for tests does not execute a scan.
Importing the file for tests does not execute a scan.
98 raise SystemExit(main()) # Pass the main function's status to the invoking shell.
Pass the main function's status to the invoking shell.