Network Audit Suite

Automated LAN Traffic Audit Trail for ISP Security Alert Response

Project Overview

Objective: Design and implement a self-documenting audit trail system that proves authorized development activity on a private LAN, automatically responding to ISP security classifiers (such as Spectrum's "Secure Traffic" advisory) that flag high-concurrency encrypted sessions and modern development runtimes as suspicious.

Problem Context: Modern software engineering environments routinely generate traffic patterns — persistent WebSocket connections, SSH tunnels for QA automation, Jupyter and database loopback sessions, concurrent encrypted package pulls — that superficially resemble the fingerprint of compromised hosts. Automated ISP monitoring cannot distinguish a QA engineer running a Selenium grid from a botnet beacon. The operational burden falls on the customer to justify normal activity.

Solution: A distributed audit system that continuously documents which processes, ports, and outbound sessions are expected, cross-references them against a blocklist of ISP-flagged indicators, surfaces anomalies via cross-platform watchdog agents, and produces a timestamped record that can be provided to an ISP on demand.

3
Platform Agents
Hourly
Watchdog Cadence
Shell +
Python
Implementation
RFC 1918
LAN Scope

System Architecture

Central Audit Vault Aggregates node reports Runs incident detection (Debian host, SSD-backed storage) Linux Nodes Collect process snapshots netstat / ss / journalctl macOS Watchdog LaunchAgent plist Hourly vault check Android Watchdog Termux + cron Push notifications Audit Pipeline Process & Port Capture listening sockets, PIDs Blocklist Cross-Reference ISP-flagged IPs/hosts Incident Detection ALERT marker scan Notification Fan-Out desktop + mobile alerts Nodes push audit snapshots → Vault aggregates → Pipeline detects & notifies

🛡 Authorized Activity Documentation

  • Process Socket Audit: Captures persistent listeners for development runtimes (application servers, notebook kernels, local databases) with process names and parent PIDs so that each port is tied to a named, expected workload.
  • Encrypted Tunnel Inventory: Records concurrent SSH, SCP, and MCP-over-SSH sessions used for QA automation, distinguishing legitimate outbound connections from anomalous ones.
  • Maintenance Windows: Documents scheduled firmware update (fwupd) and package update (apt) cycles as system-legitimate traffic rather than malware update channels.
  • Per-Node Logs: Each node publishes its audit snapshot to the vault on a regular cadence, producing a tamper-evident history.

📡 Cross-Platform Watchdog Agents

  • macOS LaunchAgent: User-scope agent polls the vault hourly; raises native system notifications when a security incident is posted.
  • Android / Termux: Mobile agent uses termux-api to surface high-priority alerts with vibration, ensuring off-desk awareness.
  • Linux Nodes: Any Linux device on the LAN can act as a reporting node by running the collection script — there is no special node requirement.
  • Failure Modes: Agents degrade silently when offline and resume polling when connectivity returns, avoiding noisy false alarms.

🔍 Incident Detection & Reporting

  • ALERT-marker scan: A report generator traverses all node audit files each run, looking for ALERT markers produced by the blocklist cross-reference step.
  • Incident file: When any ALERT is found, a human-readable incident log is produced and the watchdogs fire notifications on the next polling interval.
  • SSH surface monitoring: Each run enumerates outbound port-22 connections and validates that the remote peers are inside the LAN or in a known-good list.
  • Deterministic output: Report output is newline-delimited and grep-friendly so that additional tools can subscribe to the audit stream without a parser.

⚙️ Automation Discipline

  • No manual steps: Audit collection, aggregation, incident detection, and notification dispatch all run on timers — no human action required for steady-state operation.
  • Secret hygiene: SSH key-based authentication end-to-end, no passwords in scripts, vault-side authorized_keys under a dedicated low-privilege service account.
  • Separation of concerns: Collection script, transport, aggregation, detection, and notification are each their own component — each can be tested and replaced independently.
  • Offline-tolerant: Each node is authoritative for its own audit file; vault unavailability never blocks local collection.

🔐 Collection Layer

  • Bash + POSIX tools: ss, netstat, ps, journalctl
  • OpenSSH: Key-based node → vault transport
  • systemd timers / cron: Scheduled collection cadence
  • WDBLACK SSD: Vault log storage for longevity

📱 Watchdog Layer

  • macOS: launchd LaunchAgent plist, user-session scope
  • Android: Termux, termux-api, cronie
  • Notification APIs: Native macOS notification center, Termux push
  • Environment-driven config: Plist / env vars only; no hardcoded secrets

📈 Aggregation Layer

  • Debian-based vault host: Refurbished enterprise-class workstation, SSD-backed
  • Shell-based aggregator: generate_report.sh pipeline
  • Blocklist integration: spectrum_blocklist.conf cross-reference
  • Daily SSH auth review: journalctl + pattern matchers

📊 Observability

  • Named ALERT markers: Plain-text, machine-parseable incident signals
  • Per-run status: Each collection cycle recomputes the current verdict
  • Integrity check: Audit files validated before aggregation
  • Retention: Long-lived incident history for ISP correspondence

🔧 Engineering Highlights

🧠 Problem Reframing

  • Inverts the default posture — instead of reacting to ISP alerts one at a time, the system maintains a continuous, evidentiary record of expected activity
  • Positions the customer with documentation in hand at the moment an inquiry arrives
  • Reusable template for any development environment subject to automated ISP classifiers

🔗 Composable Design

  • Five independent concerns — collect, transport, aggregate, detect, notify — each implemented in isolation
  • Adding a new platform agent is a single plist or cron entry; no changes to the vault
  • Adding a new detection rule is a single shell function in the report generator

📡 Cross-Platform Reach

  • Linux, macOS, and Android all participate as first-class agents
  • Mobile notification path ensures alerts surface even when the primary workstation is unattended
  • Termux+cron on Android demonstrates that serious automation can live outside traditional desktop OSes

🛡 Security Posture

  • Key-only SSH, dedicated service account, principle-of-least-privilege on the vault
  • No inline credentials in scripts — all secrets via environment or key material
  • Blocklist file is version-controlled and diff-reviewable

🎯 Project Impact

Operational Readiness: Transforms ad-hoc responses to ISP security advisories into a bounded, repeatable workflow. When a customer receives a "Secure Traffic" notice, the relevant incident-free audit history is already on disk and ready to reference.

Portable Methodology: The architecture — central vault, node reporters, cross-platform watchdogs, blocklist cross-reference, incident fan-out — is implementation-independent. The same pattern applies to any LAN where a mix of encrypted tunnels, modern development runtimes, and automated updates would otherwise trigger false-positive alerts from external classifiers.

Engineering Ethos: Demonstrates systems thinking: observing a recurring operational problem, identifying its root cause (asymmetric visibility between ISP and customer), and closing the loop with automation rather than manual effort.