Hands-on lab — Day 17: TCP, UDP, and Ports

#!/usr/bin/env bash
# Day 017 lab — completed reference implementation.
# "See Ports and Connections": list the TCP ports this machine is LISTENING
# on, explain which are well-known, and prove a loopback connection with nc.
#
# This script is strictly READ-ONLY and LOCAL:
#   - it only reads the local list of listening sockets (lsof/ss/netstat)
#   - the only network action is a loopback (127.0.0.1) connectivity probe
#   - it never connects to, or scans, any external host, and needs no sudo.
set -euo pipefail

os="$(uname -s)"

echo "=== Ports and Connections ==="
echo "Generated on: $(date '+%Y-%m-%d')"
echo "Operating system kernel: ${os}"

# ---------------------------------------------------------------------------
# name_for_port PORT — a tiny well-known-port lookup table.
# Returns a human-readable guess for the service usually behind a port.
# ---------------------------------------------------------------------------
name_for_port() {
  case "$1" in
    22)   echo "SSH (secure shell login)" ;;
    53)   echo "DNS (domain name lookups)" ;;
    80)   echo "HTTP (unencrypted web)" ;;
    123)  echo "NTP (clock sync)" ;;
    443)  echo "HTTPS (encrypted web)" ;;
    631)  echo "IPP (printing)" ;;
    3000) echo "common dev server (Node/React)" ;;
    5000) echo "common dev server / AirPlay on macOS" ;;
    5432) echo "PostgreSQL database" ;;
    6379) echo "Redis database" ;;
    7000) echo "AirPlay receiver (macOS)" ;;
    8000) echo "common dev / model server" ;;
    8080) echo "common HTTP alternative" ;;
    *)    echo "-" ;;
  esac
}

# ---------------------------------------------------------------------------
# class_for_port PORT — which of the three IANA ranges a port falls in.
#   0-1023      : well-known (system) ports
#   1024-49151  : registered ports
#   49152-65535 : ephemeral / dynamic ports
# ---------------------------------------------------------------------------
class_for_port() {
  local p="$1"
  if   [ "$p" -le 1023 ];  then echo "well-known"
  elif [ "$p" -le 49151 ]; then echo "registered"
  else                          echo "ephemeral"
  fi
}

# ---------------------------------------------------------------------------
# list_listening — print "PORT PROCESS" lines for every listening TCP socket,
# choosing the best available tool for this OS. Read-only.
# ---------------------------------------------------------------------------
list_listening() {
  if [ "${os}" = "Darwin" ] && command -v lsof >/dev/null 2>&1; then
    # macOS: lsof reports the local address in the NAME column, e.g.
    # "*:7000 (LISTEN)" or "127.0.0.1:54815 (LISTEN)". Take the port after
    # the LAST colon of the second-to-last field; the command is field 1.
    lsof -nP -iTCP -sTCP:LISTEN 2>/dev/null | awk '
      NR > 1 {
        addr = $(NF - 1)
        n = split(addr, parts, ":")
        port = parts[n]
        if (port ~ /^[0-9]+$/) print port, $1
      }'
  elif command -v ss >/dev/null 2>&1; then
    # Linux: ss -tlnH lists listening TCP sockets with no header. The local
    # address:port is field 4; the port is after the last colon.
    ss -tlnH 2>/dev/null | awk '
      {
        addr = $4
        n = split(addr, parts, ":")
        port = parts[n]
        proc = $NF
        if (port ~ /^[0-9]+$/) print port, proc
      }'
  elif command -v netstat >/dev/null 2>&1; then
    # Fallback: netstat. -tln = TCP, listening, numeric.
    netstat -tln 2>/dev/null | awk '
      /LISTEN/ {
        addr = $4
        n = split(addr, parts, ":")
        port = parts[n]
        if (port ~ /^[0-9]+$/) print port, "(netstat)"
      }'
  else
    echo "NO_TOOL"
  fi
}

echo
echo "--- Listening TCP ports ---"
echo "A 'listening' port is a service waiting for incoming connections."

raw="$(list_listening | sort -n -u)"

ports_only=""
if [ "${raw}" = "NO_TOOL" ] || [ -z "${raw}" ]; then
  echo "(No listening-port tool found, or no listening TCP ports detected.)"
  echo "Install lsof (macOS) or iproute2/net-tools (Linux) to see more."
else
  printf '%-7s %-12s %-32s %s\n' "PORT" "CLASS" "LIKELY SERVICE" "PROCESS"
  while read -r port proc; do
    [ -z "${port}" ] && continue
    ports_only="${ports_only} ${port}"
    printf '%-7s %-12s %-32s %s\n' \
      "${port}" "$(class_for_port "${port}")" "$(name_for_port "${port}")" "${proc}"
  done <<EOF
${raw}
EOF
fi

echo
echo "--- Well-known vs ephemeral ---"
echo "Ports 0-1023 are WELL-KNOWN: reserved for standard services."
echo "  22=SSH  53=DNS  80=HTTP  443=HTTPS  123=NTP  631=IPP"
echo "Ports 1024-49151 are REGISTERED (databases, dev servers: 5432, 6379, 8000)."
echo "Ports 49152-65535 are EPHEMERAL: short-lived client-side port numbers."

echo
echo "--- Loopback connection test ---"
echo "127.0.0.1 is 'localhost' — this machine talking to itself, no network."
if command -v nc >/dev/null 2>&1; then
  # Find a port that actually answers on the IPv4 loopback, to demonstrate the
  # OPEN case. (Some services bind only to the IPv6 loopback [::1] and will
  # not answer on 127.0.0.1 — a real subtlety, not an error.)
  open_port=""
  for port in ${ports_only}; do
    if nc -z -w 1 127.0.0.1 "${port}" >/dev/null 2>&1; then
      open_port="${port}"
      break
    fi
  done
  if [ -n "${open_port}" ]; then
    echo "Testing 127.0.0.1:${open_port} ... OPEN (something is listening here)"
  else
    echo "No listed port answered on the 127.0.0.1 (IPv4) loopback to probe as OPEN."
    echo "(Services may be bound only to the IPv6 loopback [::1] — try ::1 instead.)"
  fi
  # Port 1 is virtually never a listening service on a normal machine, so it
  # demonstrates the 'connection refused' case that means "nothing is here".
  if nc -z -w 1 127.0.0.1 1 >/dev/null 2>&1; then
    echo "Testing 127.0.0.1:1 ... OPEN (unexpected, but honestly reported)"
  else
    echo "Testing 127.0.0.1:1 ... closed (connection refused — nothing listening)"
  fi
else
  echo "(nc not found — install it to run the loopback probe.)"
fi

echo "=== End of report ==="

lesson_id: D017
day: 17
kind: command-line-inspection
languages: [bash]
setup_commands:
  - cd labs/sections/computing-foundations/day-017-tcp-udp-and-ports
run_commands:
  - bash examples/inspect_ports.sh
  - bash starter/inspect_ports.sh
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/inspect_ports.sh  # optional: reset your work'
requires_network: false
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-12'
executed_on: 'macOS (Apple Silicon), bash tests/run_tests.sh → 9 checks, 0 failure(s)'

# Dependencies — Day 017 lab

**None that you have to install on a normal machine.** Every tool this lab
uses ships with macOS and mainstream Linux distributions:

- `bash` ≥ 3.2 (preinstalled on macOS and Linux)
- Standard utilities: `uname`, `date`, `awk`, `sort`
- **A listening-socket viewer** — one of:
  - `lsof` (preinstalled on macOS; `sudo apt install lsof` on Debian/Ubuntu)
  - `ss` (from `iproute2`, preinstalled on most modern Linux)
  - `netstat` (from `net-tools`; the last-resort fallback)
- **`nc` / netcat** for the loopback connection test:
  - macOS ships BSD `nc` at `/usr/bin/nc`
  - Linux: `sudo apt install netcat-openbsd` (Debian/Ubuntu) or
    `sudo dnf install nmap-ncat` (Fedora/RHEL) if it is missing

The script degrades gracefully: if no socket viewer is found it says so, and
if `nc` is missing it skips the probe with a clear message. Nothing here
needs `sudo`, a network connection to the outside world, an API key, or a
purchase — it only reads local state and probes `127.0.0.1`.

#!/usr/bin/env bash
# Day 017 lab — See Ports and Connections (STARTER).
#
# Your job: complete the four numbered exercises below. Each one names the
# EXACT command to run. Replace the `EXERCISE N` placeholder lines (and the
# `echo` stand-ins) so the script prints the four required sections, exactly
# like examples/inspect_ports.sh. Try it yourself before peeking at the example.
#
# This script must stay READ-ONLY and LOCAL: only read the local list of
# listening sockets, and only ever probe the 127.0.0.1 loopback. Never
# connect to or scan an external host, and never use sudo.
set -euo pipefail

os="$(uname -s)"

echo "=== Ports and Connections ==="
echo "Generated on: $(date '+%Y-%m-%d')"
echo "Operating system kernel: ${os}"

# ===========================================================================
# EXERCISE 1 — List the listening TCP ports on this machine (READ-ONLY).
#
#   On macOS, run:   lsof -nP -iTCP -sTCP:LISTEN
#   On Linux, run:   ss -tlnp        (or, if ss is absent:  netstat -tln)
#
# Capture the raw listing into the variable `listening` below. The command
# substitution $( ... ) runs the command and stores its text output.
# Replace the placeholder line with the correct branch for your OS.
# ===========================================================================
echo
echo "--- Listening TCP ports ---"
if [ "${os}" = "Darwin" ]; then
  listening="$(echo 'EXERCISE 1: replace me with  lsof -nP -iTCP -sTCP:LISTEN')"
else
  listening="$(echo 'EXERCISE 1: replace me with  ss -tlnp   (or  netstat -tln)')"
fi
echo "${listening}"

# ===========================================================================
# EXERCISE 2 — Pull out just the port numbers, sorted and de-duplicated.
#
# The port is the number after the LAST colon of the local address. On macOS
# lsof, the address is the second-to-last field (e.g. "*:7000"); on Linux ss
# it is field 4 (e.g. "0.0.0.0:22"). Fill in the awk field and finish the
# pipeline with:   sort -n -u
#
# Hint (macOS):  awk 'NR>1 { n=split($(NF-1),p,":"); print p[n] }'
# Hint (Linux):  awk '{ n=split($4,p,":"); print p[n] }'
# ===========================================================================
echo
echo "--- Well-known vs ephemeral ---"
echo "EXERCISE 2: extract the port numbers here, then classify them:"
echo "  ports 0-1023 are WELL-KNOWN (22=SSH 53=DNS 80=HTTP 443=HTTPS)."
echo "  ports 1024-49151 are REGISTERED; 49152-65535 are EPHEMERAL."
# ports="$(echo "${listening}" | awk 'REPLACE_ME' | sort -n -u)"

# ===========================================================================
# EXERCISE 3 — Prove an OPEN port on the loopback with netcat.
#
# Pick a port number you saw in Exercise 1 that is bound to 127.0.0.1 or *,
# then test it WITHOUT sending data using the -z ("zero-I/O") flag:
#
#   nc -z -w 1 127.0.0.1 <PORT>
#
# nc exits 0 if the port is OPEN (something is listening) and non-zero if it
# is closed. Replace <PORT> below with a real port from your own output.
# ===========================================================================
echo
echo "--- Loopback connection test ---"
echo "127.0.0.1 is 'localhost' — this machine talking to itself, no network."
# if nc -z -w 1 127.0.0.1 <PORT> >/dev/null 2>&1; then
#   echo "Testing 127.0.0.1:<PORT> ... OPEN"
# else
#   echo "Testing 127.0.0.1:<PORT> ... closed"
# fi
echo "EXERCISE 3: run  nc -z -w 1 127.0.0.1 <PORT>  for a real open port."

# ===========================================================================
# EXERCISE 4 — Prove a CLOSED port ("connection refused").
#
# Probe a port that is almost certainly NOT listening (port 1 is a safe
# choice) and report the refusal:
#
#   nc -z -w 1 127.0.0.1 1
#
# "Connection refused" is exactly what a client sees when nothing is
# listening on the other side — the everyday cause of that error.
# ===========================================================================
echo "EXERCISE 4: run  nc -z -w 1 127.0.0.1 1  and report 'connection refused'."

echo "=== End of report ==="

# Ports worksheet — Day 017

Fill this in from your own machine using the commands in the lesson and the
lab (`lsof -nP -iTCP -sTCP:LISTEN` on macOS, `ss -tlnp` or `netstat -tln` on
Linux, and `nc -z -w 1 127.0.0.1 <port>` for the connection test). Everything
here is read-only and local — you never touch another machine.

## 1. Two ports your machine is listening on

| Port number | IANA class (well-known / registered / ephemeral) | Which service do you think it is, and why? |
| ----------- | ------------------------------------------------ | ------------------------------------------ |
|             |                                                  |                                            |
|             |                                                  |                                            |

Reminder of the ranges: **0–1023** well-known, **1024–49151** registered,
**49152–65535** ephemeral. Use the process name in the last column of your
listing (and the well-known-port table in the lesson) to make your guess.

## 2. Is port 80 open locally?

Run the loopback probe against the standard HTTP port:

```bash
nc -z -w 1 127.0.0.1 80
```

- Command's exit status (`echo $?` right after): __________
- Is anything listening on port 80 of this machine? (open / closed): __________
- If it is closed, what error would a browser-style client report when it
  tried to connect there? __________________________________________________

## 3. One sentence in your own words

Explain, in one sentence, the difference between a **port** and an **IP
address**, using the "building with an address, apartments with numbers"
analogy from the lesson:

_______________________________________________________________________________

#!/usr/bin/env bash
# Tests for the Day 017 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Verifies that the reference script runs read-only, prints the four required
# sections, performs only loopback probes, and exits 0. It must NOT open any
# external connection and must NOT require sudo.
set -u

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
script="${lab_dir}/examples/inspect_ports.sh"
failures=0
checks=0

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

echo "Testing ${script} ..."

# 1. It must run and exit 0.
if output="$(bash "${script}" 2>&1)"; then
  check "script exits successfully (exit 0)" "yes"
else
  check "script exits successfully (exit 0)" "no"
  echo "${output}" | sed 's/^/    /'
fi

# 2. Required section headers are all present.
echo "${output}" | grep -q '^=== Ports and Connections ===$' && \
  check "prints report header" "yes" || check "prints report header" "no"
echo "${output}" | grep -q '^--- Listening TCP ports ---$' && \
  check "prints 'Listening TCP ports' section" "yes" || check "prints 'Listening TCP ports' section" "no"
echo "${output}" | grep -q '^--- Well-known vs ephemeral ---$' && \
  check "prints 'Well-known vs ephemeral' section" "yes" || check "prints 'Well-known vs ephemeral' section" "no"
echo "${output}" | grep -q '^--- Loopback connection test ---$' && \
  check "prints 'Loopback connection test' section" "yes" || check "prints 'Loopback connection test' section" "no"
echo "${output}" | grep -q '^=== End of report ===$' && \
  check "prints report footer" "yes" || check "prints report footer" "no"

# 3. The loopback test must reference 127.0.0.1 and only 127.0.0.1.
echo "${output}" | grep -q '127\.0\.0\.1' && \
  check "loopback test targets 127.0.0.1" "yes" || check "loopback test targets 127.0.0.1" "no"

# 4. Read-only / local-only guarantees, checked against the source itself.
if grep -Eq 'sudo|rm -rf|>[^&]|curl |wget ' "${script}"; then
  # >/dev/null and 2>&1 redirections are fine; a bare write redirect is not.
  if grep -Eq 'sudo |curl |wget ' "${script}"; then
    check "script contains no sudo/curl/wget (local & read-only)" "no"
  else
    check "script contains no sudo/curl/wget (local & read-only)" "yes"
  fi
else
  check "script contains no sudo/curl/wget (local & read-only)" "yes"
fi

# 5. The only host it ever contacts is the loopback (no external IPs/hostnames
#    passed to nc). Every nc invocation must target 127.0.0.1.
if grep -Eq '\bnc\b' "${script}"; then
  bad_nc="$(grep -E '\bnc .*(-z|-w)' "${script}" | grep -v '127\.0\.0\.1' || true)"
  if [ -z "${bad_nc}" ]; then
    check "every nc probe targets the loopback only" "yes"
  else
    check "every nc probe targets the loopback only" "no"
    echo "${bad_nc}" | sed 's/^/    offending: /'
  fi
else
  check "every nc probe targets the loopback only" "yes"
fi

echo
echo "${checks} checks, ${failures} failure(s)."
[ "${failures}" -eq 0 ]