From 054dc45cd5b772d5ed7bbc471f7c2960dcb9dea4 Mon Sep 17 00:00:00 2001 From: n0mad1k Date: Mon, 6 Apr 2026 09:15:40 -0400 Subject: [PATCH] Document comprehensive fix plan for daemon initialization failures --- IMPLEMENTATION_PLAN.md | 209 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 IMPLEMENTATION_PLAN.md diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..5dca90a --- /dev/null +++ b/IMPLEMENTATION_PLAN.md @@ -0,0 +1,209 @@ +# 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