Inspector Gadget State Machine

One detail I would like to give more attention to is the idle state behavior. A traditional state machine would either spin in idle (wasting CPU) or sleep for a fixed interval (wasting latency on a quiet network). This implementation does neither. Instead, it performs a single-packet blocking sniff. The first packet that arrives instantly wakes the machine back into monitor mode and is put into the packet queue so it isn't lost:

def on_enter_idle(self):
	sniffer = AsyncSniffer(iface=self.model.interface, count=1)
	sniffer.start()
	sniffer.join()
	for result in sniffer.results:
		self.model.add_packet(result)
	self.send('start')

The monitor state itself transitions back to idle after two consecutive empty-queue seconds. The machine smarlty transitions between idle and monitor automatically based on network activity. It's a small piece of control-flow design that I wanted to automate for efficiency.

def monitor_thread():
	self.packet_capture.start_capture(self.interface)
	self.inference_engine.start_inference(self.traffic_analyzer.feature_queue)
	self.alert_system.send_alerts(self.inference_engine.alert_queue)

	count = 0
	while not self.monitoring_event.is_set():
		try:
			packet = self.packet_capture.packet_queue.get(timeout=1)
			count = 0
			self.traffic_analyzer.analyze_packet(packet)
		except queue.Empty:
			count += 1
			if count > 1:
				self.request_wait.set()
				return
			continue

	self.packet_capture.stop()

This enhancement shows my ability to design and evaluate a computing solution while managing the trade-offs involved in design choices. Every deliberate decision I made about queue sizing, flow-table management, and thread coordination was a trade-off between throughput, memory, and resilience on constrained hardware. I applied algorithmic principles and industry-standard practices to a real problem. Throughout the project I maintained a security mindset that anticipates adversarial exploits. The HTTPS-plus-bearer-token path between the Pi and the server, a bounded flow table that closes a denial-of-service hole in my own monitor, and the NaN and malformed-packet guards are all the product of thinking like an attacker.

Deployment also surfaced a subtle but critical bug in the state machine class signature. The python-statemachine documentation shows a generic type parameter: NetworkMonitorMachine(StateMachine[ 'NetworkMonitorModel']) which looks reasonable on paper. At runtime, however, python-statemachine 3.x does not implement a true generic. The subscript is type-hint only. Python raised aTypeError the moment the class body was evaluated, before a single packet was ever seen. The fix was simply removing the subscript and writing class NetworkMonitorMachine(StateMachine):. It was a good reminder that type annotations and runtime behavior are not the same thing, and that reading library documentation is not a substitute for running the code.

The most significant structural lesson came from a threading mistake I made in the monitor loop. Initially I forgot to follow the controller-worker design pattern. I placed state-change logic inside monitor_thread, which called machine.send('wait') directly. Because send()is synchronous and immediately re-enters the state machine, it spawned a newmonitor_thread before the old one returned, creating an infinite threading loop that crashed with TransitionNotAllowed. I remembered to keep controlling logic separate from working logic. I then created a run() method on the state machine itself so it can drive all state transitions. I made NetworkMonitorModel a supervisor that only delegates and coordinates work to the other classes. It signals readiness via a threading.Event and returns. The state machine'srun() loop waits on that signal, then decides what to do next:

def run(self):
	try:
		while self.configuration != self.hibernate:
			self.model.request_wait.wait()
			self.model.request_wait.clear()
			self.send('wait')
	except KeyboardInterrupt:
		self.send('stop')

After letting the monitor run against a tcpreplay loop for 24 hours, it had analyzed over 12,000 flows and posted zero alerts. That result needed explaining.

The first problem was in flow tracking. The flow tracker discarded any flow that lacked a captured SYN handshake. With tcpreplay replaying a historical pcap, that's most flows. The fix assigns direction metadata to those flows instead of deleting them. The model doesn't need to know which side initiated the connection. It needs consistent feature values.

Not every flow accumulates 25 packets or reaches a clean FIN exchange. For those, I added an hourly cleanup pass to the Traffic Analyzer. Flows inactive for more than an hour get their features extracted and queued for inference. They're then removed from the flow table. The sweep uses packet.time from the pcap, not the system clock. Replayed timestamps work correctly as a result.

Every flow now has a path to inference: 25 or more packets, both FINs observed, or the stale sweep after an hour of inactivity. The monitor was architecturally sound. It just wasn't seeing most of its traffic.