TCP Port Scanner + Evidence Logger

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.