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