Network Attack Visualiser

Network Attack Visualiser is a graduate-level portfolio project built to demonstrate real networking, cybersecurity, and software-engineering competence rather than to ship a production intrusion-detection system. It ingests network traffic through three interchangeable paths, synthetic events, PCAP replay, and an authenticated live sensor inside a Docker lab, runs two transparent heuristic detectors over that traffic, and presents every detection on a live dashboard with the exact evidence and thresholds that triggered it.

The project's stated priorities, in order, are correctness and honesty (detections are heuristics, never asserted as certainty, confidence is explicitly capped at 0.95), security and privacy by design (only metadata is ever retained; payloads and credentials cannot flow through the system even by accident), clean architecture (capture, detection, alerting, storage, API, and presentation are independent modules with narrow interfaces), and reproducibility (the whole system runs deterministically from a single Docker Compose lab with demonstration scenarios built in).

The heuristic detection engine is the source of truth for every alert. The optional AI layer only ever explains an alert after the fact; it never creates, suppresses, or re-grades one.

Shared principles. Neither detector ever calls a wall-clock function; both receive now explicitly. Both partition state by source_type so evidence from synthetic, replayed, and live traffic never contaminates the same detection window. Both run periodic expire() sweeps to bound memory, and both reject non-finite configuration values (NaN, ±Infinity) on load rather than failing silently later. Every threshold below is a configurable environment value, these are the shipped defaults.

Five services split across two Docker bridge networks. The lab network (172.28.0.0/24, internal: true) has no route to the host or the internet and holds the victim (unprivileged Nginx, no published ports), the generator (a Scapy-based traffic tool), and the backend's lab-facing interface. The management network is a standard bridge carrying operator-facing traffic between the frontend and backend over Docker service-name DNS.

The sensor does not join either network directly. It runs as network_mode: "service:victim", sharing the victim's network namespace outright, which gives it complete visibility into victim-directed traffic without relying on bridge promiscuous mode or unknown-unicast flooding. Only two ports ever reach the host, and both are bound to loopback only: the backend at 127.0.0.1:8000 and the dashboard at 127.0.0.1:5173. The victim itself is never published to the host at all.

A provider-abstracted explanation layer can turn an already-persisted alert's sanitised metadata into a plain-language write-up, but it is disabled by default and the application works completely without it. The design is deliberately conservative: the sanitiser sends only allow-listed numeric and enumerated fields to a provider, addresses, alert IDs, raw timestamps, and anything credential-shaped are stripped before the call ever leaves the process. The annotator runs as a single bounded worker with a finite queue that drops on overflow rather than queuing without limit, and it writes back exactly two fields, ai_status and ai_explanation, after the alert already exists. It cannot create an alert, suppress one, or change a severity the heuristic engine already assigned.

The React and Vite dashboard opens a WebSocket immediately and begins collecting live deltas while an initial REST fetch populates the alert table, a two-phase reconciliation that means a page reload never floods the feed with replayed history. Traffic-source tabs (All, Synthetic, Replayed, Live-Lab) and filters by severity, detector, and category sit above summary tiles for alert count, trigger count, packets observed, and traffic volume, all explicitly scoped as provenance-wide so they are not silently affected by the table's own filters.

Recharts-driven protocol distribution and traffic timeline charts sit below the live feed, with each traffic provenance rendered on its own independent event-time axis rather than mixed onto one wall-clock timeline. Clicking any alert row opens the investigation pane on the right: the exact event facts, the raw evidence counters the detector saw (SYN count, completion ratio, distinct source count), the threshold snapshot that was active when it fired, and, when enabled, the AI layer's explanation, clearly separated from the deterministic facts above it.

The single most load-bearing testability decision in the project is that detectors take an injected clock and perform no I/O. That makes every time-dependent behaviour, window expiry, TTLs, cooldowns, testable by advancing a FakeClock to an exact boundary instead of sleeping and hoping. Backend tests run on pytest; the frontend on Vitest and React Testing Library, with an optional Playwright smoke test.