Skip to content

Building 70 Projects ranging from beginner to advanced so anyone can β€” learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company πŸ‘‡

14.6 KB
Raw Blame

System Architecture

High-Level Overview

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                     main.cpp                                β”‚
β”‚  β€’ arg parsing        β€’ thread coordination                 β”‚
β”‚  β€’ offline vs live    β€’ CSV/JSON export on exit             β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
            β”‚                             β”‚
     β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”             β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”
     β”‚ PcapCapture β”‚             β”‚   FTXUI screen  β”‚
     β”‚ (libpcap)   β”‚             β”‚   (main thread) β”‚
     β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜             β””β”€β”€β”€β”€β”€β”€β”€β”€β–²β”€β”€β”€β”€β”€β”€β”€β”€β”˜
            β”‚ got_packet()                β”‚ PostEvent()
            β”‚                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”
     β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”             β”‚ application_    β”‚
     β”‚  IPv4/IPv6  β”‚             β”‚ thread          β”‚
     β”‚  (parser)   β”‚             β”‚ (UI update loop)β”‚
     β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜             β””β”€β”€β”€β”€β”€β”€β”€β”€β–²β”€β”€β”€β”€β”€β”€β”€β”€β”˜
            β”‚ Packet                      β”‚ get_snapshot()
     β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”‚
     β”‚           Stats                 β”‚β”€β”€β”˜
     β”‚  add_packet()  push()           β”‚
     β”‚  transport_map  application_map β”‚
     β”‚  ip_map  pairs  packets deque   β”‚
     β”‚  bandwidth_history              β”‚
     β”‚  StatsSnapshot (under mutex)    β”‚
     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Threading Model

There are three concurrent execution contexts:

Capture thread β€” spawned by PcapCapture::start() at pcapCapture.cpp:80. Runs pcap_loop() which calls callback() β†’ got_packet() for each packet. Calls Stats::add_packet() and Stats::push(). Never touches the UI.

UI update thread (application_thread, main.cpp:107) β€” runs a loop that:

  1. Advances the elapsed timer
  2. Checks stop conditions (time limit, capture finished)
  3. Calls all Stats::update_*() methods to rebuild snapshot tables
  4. Calls view.render(stats.get_snapshot(), ...) to build a new FTXUI element tree
  5. Stores the element in current_render under render_mtx
  6. Posts a Custom event to the FTXUI screen to trigger a repaint

FTXUI event loop β€” runs on the main thread via screen.Loop(component) at main.cpp:139. The Renderer lambda (main.cpp:92) reads current_render under render_mtx and returns it. The CatchEvent lambda handles q and Escape to set ui_running = false and call screen.Exit().

Synchronization Points

Shared resource Protector Access pattern
Stats internal maps Stats::mtx Capture thread writes; UI thread reads via update_* methods
StatsSnapshot inside Stats Stats::mtx Both threads; snapshot is updated in place under lock
current_render render_mtx UI thread writes; FTXUI renderer reads
capture_finished, ui_running std::atomic<bool> Multiple threads read/write
timer std::atomic<std::chrono::seconds> UI thread writes; render lambda reads

Components

PcapCapture (include/capture/pcapCapture.hpp, src/capture/pcapCapture.cpp)

Wraps the entire libpcap lifecycle. Owns the pcap handle as a unique_ptr<pcap_t, decltype(&pcap_close)> so it's released on destruction regardless of how the object exits.

Key responsibilities:

  • initialize() β€” discover all network interfaces via pcap_findalldevs()
  • datalink_type() β€” detect the link-layer header type and set the byte offset + EtherType extractor
  • start() β€” open device in promiscuous mode, compile and install BPF filter, spawn capture thread
  • start_offline() β€” open pcap file, process synchronously (no extra thread)
  • got_packet() β€” parse each raw frame: extract EtherType, construct IPv4 or IPv6, build Packet, forward to Stats
  • ~PcapCapture() β€” calls stop(): breaks pcap loop, joins thread, frees filter program and interface list

The C-style pcap_loop callback requires a static function. callback() (line 132) uses the user pointer (which holds this cast to u_char*) to forward to the instance method got_packet().

IP_class / IPv4 / IPv6 (include/packet/IP.hpp, src/packet/IP.cpp)

Polymorphic IP header parser. IP_class is an abstract base declaring pure virtual transport handlers (handle_tcp(), handle_udp(), etc.). Both IPv4 and IPv6 inherit from it.

Parsing is constructor-based: both IPv4(const u_char *data) and IPv6(const u_char *data) accept a pointer to the IP header (already offset past the link-layer header) and complete all parsing in the constructor. After construction, the object exposes only pure accessors: get_source(), get_dest(), get_src_port(), get_dest_port(), get_protocol(), get_payload_len(), get_payload_ptr().

IPv4 transport dispatch: switch(ip_hdr->ip_p) at line 28, dispatching to handle_tcp/udp/icmp/icmpv6/igmp.

IPv6 transport dispatch: a while(true) loop at line 94 that either handles a transport protocol (and returns) or walks past a known extension header and continues.

Packet (include/packet/packet.hpp, src/packet/packet.cpp)

A value type holding everything extracted from a single frame:

  • ip_version β€” v4 or v6 (enum IPVersion)
  • transport_protocol β€” TCP/UDP/ICMP/ICMP6/IGMP/UNKNOWN (enum class TransportProtocol)
  • application_protocol β€” HTTP/HTTPS/DNS/SSH/etc (enum class ApplicationProtocol)
  • src, dst β€” IP addresses as strings
  • src_port, dst_port β€” port numbers
  • total_len β€” full frame length from pcap header
  • payload_len β€” transport payload length
  • payload_ptr β€” pointer into pcap's buffer, nulled after get_application_protocol() runs

The constructor computes application_protocol via get_application_protocol() (packet.cpp:4) then immediately nulls payload_ptr. This prevents callers from dereferencing a pointer that's only valid during the callback.

get_application_protocol() uses payload inspection first (HTTP verbs, TLS record header bytes), then falls back to port-based identification.

Stats (include/stats/protocolStats.hpp, src/stats/protocolStats.cpp)

Thread-safe statistics engine. Internal state:

  • transport_map β€” unordered_map<TransportProtocol, protocolStats>
  • application_map β€” unordered_map<ApplicationProtocol, protocolStats>
  • ip_map β€” unordered_map<string, IPStats> (per-IP bidirectional counters)
  • pairs β€” map<pair<string,string>, protocolStats> (per srcβ†’dst pair)
  • packets β€” deque<Packet> (bounded ring of recent packets)
  • snapshot β€” StatsSnapshot (pre-built display rows, updated by update_* methods)
  • bandwidth_history β€” vector<BandwidthPoint> (time-series)

add_packet() (line 19) takes a lock and updates all raw maps in a single critical section. The update_*() methods take the lock, sort/format the data, and rebuild the corresponding snapshot.*_rows vectors. get_snapshot() returns a copy of the snapshot under the lock.

View (include/TUI/view.hpp, src/TUI/view.cpp)

Stateless FTXUI layout composer. render() (view.cpp:5) builds the full terminal layout from a StatsSnapshot:

β”Œβ”€β”€β”€β”€β”€β”€β”€ header ──────────────────────────────────────┐
β”‚ title | interface | filter  β”‚  traffic summary       β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ transport table β”‚ app table β”‚ pairs table            β”‚  ← hbox, bordered
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ IP table (scrollable)  β”‚  bandwidth graph            β”‚  ← hbox
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ packets table (right panel, scrollable, width=100)   β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ footer: timer + exit hint                            β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

render_bandwidth() (line 138) defines a GraphFunction β€” a lambda that receives the graph widget's pixel dimensions and returns a vector<int> mapping each x-pixel to a y-height. It interpolates between the last 50 bandwidth samples and scales by max_bandwidth.

All table sections use ftxui::Table with header row styling (DOUBLE border on row 0, LIGHT on rest).

Filter (include/cli/filter.hpp, src/cli/filter.cpp)

Two-function module:

parse(str) (filter.cpp:5) β€” splits a key:value string at the first :. Maps known key names (protocol, port, src, dst, ip) to the filter_type enum. Throws std::invalid_argument if no : is present.

get_bpf_filter(filters) (filter.cpp:27) β€” groups multiple filters by type into a map<filter_type, vector<string>>. Maps user-facing values to BPF syntax (e.g., protocol:dns β†’ port 53, ip:v4 β†’ ip). Combines same-type filters with or, different types with and. Returns the resulting BPF expression string.

argsParser (include/cli/argsParse.hpp, src/cli/argsParse.cpp)

Thin wrapper around Boost.Program_options. Defines all CLI options in the constructor and stores parsed results in a public po::variables_map vm. Options:

Flag Default Description
-i, --interface wlan0 Network interface
-c, --count 0 (unlimited) Packet count limit
--time, -t INT_MAX Capture duration (seconds)
-r, --offline β€” Read from pcap file
-f, --filter β€” Filter expressions (composing, multiple)
-n, --limit 43 Max displayed entries
--csv / --json β€” Export paths

Data Flow

Live Capture

User: just run -i eth0 -f protocol:tcp
  ↓
main.cpp:33-47   Parse args, build filter vector
main.cpp:49      get_bpf_filter() β†’ "tcp" BPF string
main.cpp:54      capture.set_capabilities(interface, count, "tcp", limit, &stats)
main.cpp:73      capture.start()
  ↓
pcapCapture.cpp:52-64  pcap_lookupnet β†’ pcap_open_live (promiscuous, SNAP_LEN=1518)
pcapCapture.cpp:64     datalink_type() β†’ set offset + get_ether_type lambda
pcapCapture.cpp:68-75  pcap_compile + pcap_setfilter (BPF "tcp" installed in kernel)
pcapCapture.cpp:80-87  spawn thread β†’ pcap_loop(callback)
  ↓
[Capture thread: per-packet]
pcapCapture.cpp:132-136  callback() β†’ got_packet()
pcapCapture.cpp:158      get_ether_type(packet) β†’ ETHERTYPE_IP or ETHERTYPE_IPV6
pcapCapture.cpp:162      IPv4 ip(packet + offset)  β€” constructor parses headers
  IP.cpp:18-50              extract src/dst, walk to TCP/UDP handler
  IP.cpp:52-61              handle_tcp: ports, payload_ptr, payload_len
pcapCapture.cpp:165-168  Packet packetView(...) β€” constructor runs get_application_protocol()
  packet.cpp:4-57            memcmp payload bytes, port-based fallback
                             payload_ptr = nullptr
pcapCapture.cpp:167      stats->add_packet(packetView) β€” lock, update all maps
pcapCapture.cpp:168      stats->push(packetView)       β€” lock, push to deque
  ↓
[UI update thread: every loop iteration]
main.cpp:117-121  update_transport_stats(), update_application_stats(),
                  update_ip_stats(10), update_pairs(), update_bandwidth()
main.cpp:124-126  view.render(stats.get_snapshot(), ...) β†’ Element
main.cpp:127-130  store in current_render under render_mtx, PostEvent to FTXUI
  ↓
[FTXUI main thread: on Custom event]
main.cpp:92-95  Renderer lambda reads current_render under render_mtx β†’ display

Offline Analysis

main.cpp:61-70   capture.start_offline(pcap_file)   β€” runs synchronously
  pcapCapture.cpp:199-211  pcap_open_offline β†’ pcap_loop (no thread)
  [same per-packet flow as above]
main.cpp:64-69   stats.update_packets() + update_application_stats() + ...
  ↓
main.cpp:86-88   view.render(stats.get_snapshot(), ...) β†’ initial current_render
screen.Loop()    FTXUI displays static result (no UI update thread spawned)

Design Decisions

Decision: Constructor-Based Parsing vs Lazy Getters

The original IP_class design had get_protocol() as the entry point to all parsing β€” a getter with side effects. This creates hidden order dependencies: get_src_port() before get_protocol() returns 0 on IPv4 or garbage on IPv6.

The merged code (visible in the current IPv4/IPv6 constructors) parses everything at construction time. Getters return already-computed values. No ordering requirements for callers.

Decision: StatsSnapshot as Value Type

StatsSnapshot holds the pre-formatted display data as vector<vector<string>> rows. The UI thread calls get_snapshot() which copies this struct out under the mutex. The FTXUI renderer then works from its own copy with no need to hold any lock.

The alternative β€” having the renderer lock Stats directly β€” would mean the render mutex and the stats mutex interact, risking deadlock or blocking the capture thread on UI work.

Decision: RAII Handle for pcap_t

pcap_t* is a C resource with pcap_close() as its destructor. Storing it as unique_ptr<pcap_t, decltype(&pcap_close)> means it's released automatically when PcapCapture is destroyed, even if exceptions fly. handle.reset() in stop() explicitly releases it early when the capture ends.

Decision: Offset + Lambda for Link Types

Rather than if-chains scattered across got_packet(), the datalink_type() method sets both the offset integer and the get_ether_type function object once when the device opens. got_packet() stays clean: uint16_t ether_type = get_ether_type(packet).

This makes adding a new link type a single case addition in datalink_type() rather than a change to the hot path.