bigbrother/IMPLEMENTATION_PLAN.md

BigBrother Condo Daemon: Implementation Plan

Status Summary

The BigBrother daemon has been running since March 25 but is completely non-functional. All modules fail silently. Root cause: 5 cascading issues blocking module startup.

DevTrack Items Created

• #187: Issue 1 — Auto-detect active network interface
• #188: Issue 2 — Instantiate CaptureBus in Engine
• #189: Issue 3 — Seed database tables
• #190: Issue 4 — Track module startup state
• #191: Issue 5 — Diagnose LUKS encrypted storage

---

Issue Analysis & Fix Strategy

Issue 1: Wrong Network Interface (CRITICAL - Hard Blocker)

Current State:

• CaptureBus.__init__ defaults to "eth0"
• PacketCapture.DEFAULT_INTERFACE = "eth0"
• bigbrother.yaml has primary_interface: "auto" but auto-detection doesn't propagate
• Condo Pi is on wlan0 (10.0.0.0/24). eth0 has no carrier → capture fails

Root Cause:

• No active interface detection function exists
• Hardcoded defaults override config values
• Config "auto" value is never resolved

Files to Change:

• core/capture_bus.py — Remove hardcoded "eth0", accept interface param in init
• modules/passive/packet_capture.py — Remove DEFAULT_INTERFACE, read from config
• core/engine.py — Add detect_active_interface() call
• bigbrother.py — Resolve "auto" before passing to Engine

Parallel Capability: Independent before Issue 2.

---

Issue 2: CaptureBus Never Instantiated (CRITICAL - Hard Blocker)

Current State:

• core/capture_bus.py exists and is well-implemented
• core/engine.py has NO code to instantiate CaptureBus or inject into module configs
• 15+ passive modules call self.config.get("capture_bus") → all get None → bail

Affected Modules:

• dns_logger, host_discovery, credential_sniffer, traffic_analyzer, tls_sni_extractor, os_fingerprint, quic_analyzer, rdp_monitor, smb_monitor, ldap_harvester, kerberos_harvester, vlan_discovery, network_mapper, cloud_token_harvester, auth_flow_tracker

Files to Change:

• modules/base.py — Add requires_capture_bus = False class attribute
• modules/passive/*.py (15 files) — Set requires_capture_bus = True
• core/engine.py — Instantiate CaptureBus, start it, inject into module configs
• bigbrother.py — Document dependency

Parallel Capability: Depends on Issue 1. Module prep work (flags) can run in parallel.

---

Issue 3: Database Tables Not Seeded (CRITICAL - Blocking 2 modules)

Current State:

• ja3_spoofer reads from ja3_profiles table → doesn't exist → crashes
• mac_manager reads from mac_profiles table → doesn't exist → crashes
• scripts/build_data.py doesn't seed these tables

Files to Change:

• scripts/build_data.py — Add create_ja3_profiles_db() + create_mac_profiles_db()
• setup.sh — Ensure new functions are called

Parallel Capability: Independent. Can run in parallel with Issues 1+2.

---

Issue 4: Module Status Never Written (BLOCKING Status Checks)

Current State:

• Modules crash before calling state.set_module_status("running")
• Engine returns True (process created, not "running") before module actually initializes
• status command shows "No modules registered"

Files to Change:

• core/state.py — Ensure states: pending, starting, running, failed, stopped
• core/engine.py:start() — Write pending/starting states, catch initialization failures
• core/engine.py — Add health check loop to detect process death

Parallel Capability: Depends on Issues 1+2. Can implement state machine separately.

---

Issue 5: LUKS Encrypted Storage Module (Lower Priority)

Current State:

• encrypted_storage module fails to create LUKS container
• Requires sudo access to condo Pi to diagnose
• Storage directory is root-owned, inaccessible without sudo

Action:

• Postpone until Issues 1-4 are fixed and deployed
• Then SSH to condo with sudo and investigate

Parallel Capability: Blocked by sudo access requirement.

---

Implementation Sequence

Phase 1 — Module Prep (Parallel, independent streams)

Stream A: Interface Detection

• Create utils/network.py with detect_active_interface()
• Commit

Stream B: Module Flags

• Add requires_capture_bus = True to 15 passive modules
• Add modules/base.py class attribute
• Commit

Stream C: Database Seeding

• Update scripts/build_data.py with JA3 + MAC table seeding
• Update setup.sh to call both
• Commit

Convergence: All three streams complete independently, zero merge conflicts.

---

Phase 2 — Engine Core Changes (Sequential)

Step 1: Engine initialization

• Add interface detection call in Engine.init
• Resolve config["network"]["primary_interface"] from "auto" to actual interface
• Commit

Step 2: CaptureBus instantiation & injection

• Instantiate CaptureBus(interface=resolved_iface) in Engine.init
• Inject into configs of modules with requires_capture_bus=True
• Commit

Step 3: Graceful lifecycle

• Call capture_bus.start() before start_all()
• Call capture_bus.stop() in stop_all()
• Commit

Step 4: Module startup state tracking

• Write "pending" before proc.start()
• Write "starting" after proc.start()
• Catch exceptions and write "failed"
• Add health check loop
• Commit

---

Phase 3 — Testing & Deployment

• Run pytest suite
• Deploy to condo with setup.sh
• SSH to condo: verify bigbrother status shows all modules "running"
• Spot-check: verify dns_logger capturing DNS
• Mark DevTrack items for user approval

---

Conflict Risk Assessment

Issue	Parallel	Risk	Reason
1+2	No	HIGH	Engine init depends on interface detection
1+3	Yes	LOW	Independent file changes
1+4	No	HIGH	Status tracking needs working modules (Issue 2 first)
2+3	Yes	LOW	Independent subsystems
2+4	No	MEDIUM	Both touch engine.py, but different sections
3+4	Yes	LOW	Database seeding independent of engine state

---

File Inventory

NEW FILES

• utils/network.py — Interface detection utilities

MODIFIED FILES (Core)

• core/engine.py — Interface detection, CaptureBus instantiation, state tracking
• core/capture_bus.py — Accept interface param (minimal change)
• core/state.py — Ensure state enum (minimal change)
• bigbrother.py — Config resolution (minimal change)
• modules/base.py — Add class attributes (minimal change)

MODIFIED FILES (Module Flags)

• 15 × modules/passive/*.py — Add requires_capture_bus = True (1-line each)
• modules/active/ja3_spoofer.py — Flag (minimal)
• modules/active/mac_manager.py — Flag (minimal)

MODIFIED FILES (Data Seeding)

• scripts/build_data.py — Add JA3 + MAC seeding functions
• setup.sh — Ensure new functions called

---

Total Scope

• ~30 file edits (most are 1-line flag additions)
• 3 new functions
• 1 new file
• ~200 lines of logic in engine.py
• ~50 lines in build_data.py
• Zero new dependencies

---

Success Criteria

1. bigbrother status shows all 15+ passive modules as "running"
2. dns_logger is capturing and logging DNS queries
3. No "requires capture_bus" errors in logs
4. No database table errors from ja3_spoofer or mac_manager
5. Graceful stop_all() terminates all modules and CaptureBus cleanly