bigbrother/BIGBROTHER_DESIGN.md

# BigBrother: Shadow SOC — Red Team Network Surveillance Platform

> **Version**: 4.0
> **Date**: 2026-03-17
> **Status**: Implementation Blueprint

---

## Table of Contents

1. [Overview](#1-overview)
2. [Architecture](#2-architecture)
3. [File Tree](#3-file-tree)
4. [Passive Modules](#4-passive-modules)
5. [Active Modules](#5-active-modules)
6. [Intelligence](#6-intelligence)
7. [Connectivity](#7-connectivity)
8. [Stealth](#8-stealth)
9. [Core Framework](#9-core-framework)
10. [Operator Workstation](#10-operator-workstation)
11. [Pre-installed Tools](#11-pre-installed-tools)
12. [Setup & Bootstrap](#12-setup--bootstrap)
13. [Configuration](#13-configuration)
14. [Hardware Tiers](#14-hardware-tiers)
15. [Implementation Phases](#15-implementation-phases)
16. [OPSEC Notes](#16-opsec-notes)

---

## 1. Overview

BigBrother is a **Shadow SOC** — it gives you the same network visibility a defensive Security Operations Center has, but deployed covertly on a target network for red team operations. SOC-grade visibility, used offensively to find the best attack paths.

The platform operates as two halves:

- **The implant** (Pi or Debian host): captures everything (tcpdump full PCAP), extracts real-time metadata to SQLite (DNS, SNI, credentials, Kerberos, hosts, flows), orchestrates attacks (bettercap, Responder, mitmproxy), and stays hidden (stealth layer).
- **The operator workstation**: runs Zeek against pulled PCAPs to get structured protocol logs (ssl.log, smb.log, http.log, kerberos.log, etc.) showing every service version, every cert, every vulnerability — then uses those findings to decide what to attack.

Custom Python exists only where no existing tool covers the need. bettercap replaces all custom MITM modules. tcpdump replaces custom packet capture. Zeek runs offline on the operator's workstation for deep protocol analysis. The implant captures and extracts; the workstation analyzes.

**Operational modes**: **Passive surveillance** runs unsupervised from deployment -- tcpdump captures everything, lightweight Python modules extract metadata (DNS queries, TLS SNI, credentials, Kerberos tickets, host inventory, traffic flows) into queryable SQLite databases. **Active surveillance** is operator-enabled -- bettercap for ARP/DNS/DHCP spoofing, Responder for hash capture, mitmproxy for HTTPS interception. Once enabled, runs unattended.

BigBrother is not an autonomous attack framework. The operator makes all decisions. For offensive tools, the operator SSHes in and runs nmap, Certipy, Impacket, BloodHound, CrackMapExec directly.

---

## 2. Architecture

### Design Principles

1. **Orchestrate, don't reimplement.** bettercap does ARP/DNS/DHCP/HTTP better than custom scapy. tcpdump captures packets more reliably than Python AF_PACKET. Use them.
2. **Custom code only for structured metadata extraction.** If the output is a row in a database (hostname, credential, SNI entry, auth event), it runs on-device. If the output is reconstructed binary content (files, audio, print jobs, emails), it runs offline from PCAPs.
3. **Subprocess management is a first-class concern.** bettercap/tcpdump/Responder crashing requires different handling than Python module crashes. `core/tool_manager.py` provides unified lifecycle management.

### What Runs Where

| On-Device (Real-Time) | Offline (Operator Workstation) |
|---|---|
| PCAP capture (tcpdump) | File carving (NetworkMiner) |
| DNS/SNI/QUIC metadata to SQLite | Email reconstruction (tshark) |
| Credential extraction + immediate exfil | Print job reconstruction (pcl2pdf) |
| Kerberos ticket extraction | VoIP audio extraction (Wireshark) |
| Host discovery + OS fingerprinting | Deep protocol analysis (Zeek/tshark) |
| Flow/beacon analysis | Engagement report generation |
| MITM orchestration (bettercap) | GPU hash cracking (hashcat) |
| Change/burn detection | Certificate chain analysis |
| Auth flow tracking, SMB metadata | Protocol analysis (Zeek logs) |

### Module Counts

| Category | Count | Notes |
|---|---|---|
| Passive | 16 | Custom metadata extraction + tcpdump wrapper |
| Active | 8 | bettercap_mgr + thin wrappers + Responder/mitmproxy/ntlmrelayx |
| Connectivity | 8 | Unchanged |
| Stealth | 12 | Unchanged, expanded scope (disguise bettercap/tcpdump) |
| Intel | 8 | Dropped report_generator, added tool_output_parser |
| Core | 8 | Added tool_manager.py |
| **Total** | **60** | Down from 67 in v3.2 |

---

## 3. File Tree

```
~/tools/bigbrother/
├── bigbrother.py                    # Main CLI + interactive menu (Click + Rich)
├── setup.sh                         # Idempotent Debian bootstrap
├── requirements.txt                 # Python dependencies
├── .gitignore
│
├── config/
│   ├── bigbrother.yaml              # Non-sensitive defaults (plaintext FS)
│   ├── modules.yaml                 # Per-module enable/disable + params
│   ├── stealth.yaml                 # OPSEC/stealth profile
│   ├── hardware_tiers.yaml          # Tier-specific limits
│   ├── scope.yaml                   # Optional scope enforcement
│   ├── caplets/                     # bettercap caplet files
│   │   ├── passive_recon.cap
│   │   ├── arp_mitm.cap
│   │   ├── dns_spoof.cap
│   │   ├── full_mitm.cap
│   │   └── wifi_recon.cap
│   ├── mitmproxy_addons/            # mitmproxy addon scripts
│   │   ├── credential_extractor.py  # Extract creds from decrypted HTTPS
│   │   ├── cloud_token_extractor.py # Extract cloud tokens (replaces cloud_token_active)
│   │   └── file_logger.py           # Log file transfer metadata
│   └── templates/
│       ├── engagement_default.yaml
│       ├── engagement_minimal.yaml
│       └── engagement_full.yaml
│
├── core/
│   ├── __init__.py
│   ├── engine.py                    # Module lifecycle manager
│   ├── capture_bus.py               # Packet demux from tcpdump PCAPs to module queues
│   ├── tool_manager.py              # Subprocess lifecycle for bettercap/tcpdump/Responder/mitmproxy
│   ├── scheduler.py                 # Task scheduler (cron-like, jitter-aware)
│   ├── bus.py                       # Internal event bus (pub/sub)
│   ├── state.py                     # Persistent state (SQLite)
│   ├── resource_monitor.py          # RAM/CPU/disk/thermal watchdog
│   └── kill_switch.py               # Manual wipe orchestrator
│
├── modules/
│   ├── __init__.py
│   ├── base.py                      # Abstract base class
│   │
│   ├── passive/                     # 16 modules — metadata extraction + tcpdump wrapper
│   │   ├── __init__.py
│   │   ├── packet_capture.py        # Wrapper: tcpdump + zstd + AES-256-GCM
│   │   ├── dns_logger.py            # Per-host DNS query log → SQLite
│   │   ├── tls_sni_extractor.py     # TLS ClientHello SNI → SQLite
│   │   ├── credential_sniffer.py    # Cleartext + NTLM cred extraction
│   │   ├── kerberos_harvester.py    # AS-REP/TGS-REP ticket extraction
│   │   ├── host_discovery.py        # ARP/DHCP/mDNS/NetBIOS host table
│   │   ├── os_fingerprint.py        # p0f-style passive TCP fingerprinting
│   │   ├── traffic_analyzer.py      # Flows, beacons, top talkers, baselines
│   │   ├── vlan_discovery.py        # 802.1Q/DTP/STP/CDP/LLDP parsing
│   │   ├── network_mapper.py        # Communication graph construction
│   │   ├── auth_flow_tracker.py     # Kerberos/NTLM/SSH auth correlation
│   │   ├── smb_monitor.py           # SMB share/file access metadata
│   │   ├── cloud_token_harvester.py # Passive AWS/JWT/OAuth from cleartext HTTP
│   │   ├── ldap_harvester.py        # LDAP query/response → AD object inventory
│   │   ├── rdp_monitor.py           # RDP NLA username/hostname extraction
│   │   ├── quic_analyzer.py         # QUIC Initial packet SNI extraction
│   │   └── db_interceptor.py        # TDS/MySQL/PostgreSQL login + query metadata
│   │
│   ├── active/                      # 8 modules — bettercap + tool wrappers
│   │   ├── __init__.py
│   │   ├── bettercap_mgr.py         # Central bettercap orchestrator (REST API)
│   │   ├── arp_spoof.py             # Thin wrapper → bettercap_mgr arp.spoof
│   │   ├── dns_poison.py            # Thin wrapper → bettercap_mgr dns.spoof
│   │   ├── dhcp_spoof.py            # Thin wrapper → bettercap_mgr dhcp6.spoof
│   │   ├── evil_twin.py             # hostapd + dnsmasq (unchanged)
│   │   ├── ipv6_slaac.py            # bettercap dhcp6.spoof + mitm6
│   │   ├── responder_mgr.py         # Responder subprocess wrapper
│   │   ├── mitmproxy_mgr.py         # mitmproxy subprocess wrapper (uses addon scripts)
│   │   └── ntlm_relay.py            # ntlmrelayx subprocess wrapper
│   │
│   ├── connectivity/                # 8 modules (unchanged)
│   │   ├── __init__.py
│   │   ├── tailscale.py
│   │   ├── wireguard.py
│   │   ├── bridge.py
│   │   ├── wifi_client.py
│   │   ├── reverse_tunnel.py
│   │   ├── cellular_backup.py
│   │   ├── ble_emergency.py
│   │   └── data_exfil.py
│   │
│   ├── stealth/                     # 12 modules (unchanged, expanded scope)
│   │   ├── __init__.py
│   │   ├── mac_manager.py           # Innocuous MAC profile database + DHCP/TCP spoofing
│   │   ├── process_disguise.py      # Disguises bettercap/tcpdump + Python processes
│   │   ├── log_suppression.py
│   │   ├── encrypted_storage.py
│   │   ├── tmpfs_manager.py
│   │   ├── watchdog.py              # Manages bettercap/tcpdump/Responder + Python modules
│   │   ├── anti_forensics.py
│   │   ├── traffic_mimicry.py
│   │   ├── ja3_spoofer.py           # Applied to bettercap + mitmproxy outbound
│   │   ├── ids_tester.py            # Also checks bettercap caplet actions vs IDS rules
│   │   ├── lkm_rootkit.py           # Hides bettercap/tcpdump binaries + Python processes
│   │   └── overlayfs_manager.py
│   │
│   └── intel/                       # 8 modules
│       ├── __init__.py
│       ├── credential_db.py         # Central cred store (bettercap/Responder/mitmproxy ingestion)
│       ├── topology_mapper.py
│       ├── net_intel.py             # Beacon/C2 detection
│       ├── user_timeline.py
│       ├── supply_chain_detect.py
│       ├── change_detector.py
│       ├── security_posture.py
│       ├── operator_audit.py
│       └── tool_output_parser.py    # Unified parsing: bettercap events, Responder logs, mitmproxy flows
│
├── utils/
│   ├── __init__.py
│   ├── crypto.py
│   ├── networking.py
│   ├── logging.py
│   ├── stealth.py
│   ├── resource.py
│   ├── permissions.py
│   ├── config_loader.py
│   └── bettercap_api.py             # bettercap REST API client
│
├── data/
│   ├── oui.db                       # MAC OUI database (SQLite)
│   ├── os_sigs.db                   # Passive OS fingerprint signatures
│   ├── dhcp_fingerprints.db         # DHCP option 55 fingerprints (Fingerbank)
│   ├── innocuous_macs.db            # Innocuous consumer device MAC profiles
│   ├── ids_rules/
│   │   ├── emerging-threats.rules
│   │   └── snort-community.rules
│   ├── ja3_fingerprints.db
│   ├── wordlists/
│   │   ├── rockyou.txt.gz
│   │   ├── top-1m-passwords.txt
│   │   └── rules/
│   │       ├── OneRuleToRuleThemAll.rule
│   │       └── dive.rule
│   └── bpf_filters/
│       ├── credentials.bpf
│       ├── dns.bpf
│       ├── discovery.bpf
│       └── full_capture.bpf
│
├── services/
│   ├── bigbrother-core.service
│   ├── bigbrother-watchdog.service
│   ├── bigbrother-capture.service
│   ├── bigbrother-passive.service
│   ├── bigbrother-bridge.service
│   └── bigbrother-tailscale.timer
│
├── templates/
│   ├── captive_portals/
│   │   ├── corporate_login.html
│   │   ├── guest_wifi.html
│   │   ├── outlook_login.html
│   │   └── vpn_portal.html
│   ├── dns_zones/
│   │   ├── redirect_all.zone
│   │   └── selective.zone.j2
│   ├── hostapd/
│   │   ├── open.conf.j2
│   │   └── wpa2.conf.j2
│   ├── responder/
│   │   └── Responder.conf.j2
│   └── lkm/
│       ├── bb_hide.c
│       └── Makefile
│
├── scripts/
│   ├── setup_bridge.sh
│   ├── teardown_bridge.sh
│   ├── build_lkm.sh
│   └── operator/                    # Operator workstation scripts
│       ├── pull_data.sh             # rsync structured data over Tailscale/WG
│       ├── extract_files.sh         # tshark + NetworkMiner batch file extraction
│       ├── extract_print_jobs.sh    # TCP/9100 → pcl2pdf reconstruction
│       ├── extract_emails.sh        # SMTP from PCAPs → tshark reconstruction
│       ├── crack_hashes.sh          # Export creds → hashcat format, run wordlists
│       └── generate_report.py       # Pull SQLite DBs, generate Markdown + HTML report
│
├── tests/
│   ├── __init__.py
│   ├── test_engine.py
│   ├── test_bus.py
│   ├── test_crypto.py
│   ├── test_modules.py
│   ├── test_resource.py
│   ├── test_tool_manager.py
│   ├── test_bettercap_mgr.py
│   └── conftest.py
│
└── storage/                         # Runtime data (gitignored, LUKS-encrypted)
    ├── config/                      # Sensitive config (inside LUKS)
    ├── pcaps/                       # tcpdump rotated captures (zstd + AES)
    ├── creds/
    ├── dns_logs/
    ├── sni_logs/
    ├── intel/
    ├── baseline/
    ├── audit/
    ├── tool_logs/                   # bettercap, Responder, mitmproxy output
    └── logs/
```

---

## 4. Passive Modules

16 modules. Custom Python for lightweight structured metadata extraction. All receive packets via capture_bus (one AF_PACKET socket, demuxed to per-module queues). Zero network noise.

---

### `packet_capture.py` -- tcpdump Wrapper

Manages tcpdump subprocess for full packet capture. tcpdump handles BPF, rotation, snap length, PcapNG. Wrapper adds post-rotation compression, encryption, disk management.

- **tcpdump flags**: `-i <bridge_if> -G 3600 -W 168 -s 65535 -w <pcap_path> --time-stamp-precision=nano`
- **Post-rotation pipeline**: zstd -19 compress -> AES-256-GCM encrypt -> `.pcap.zst.enc`
  - Pi Zero: zstd -3 (fast mode, 5-8x compression, minimal CPU)
  - Pi 4/Debian: zstd -19 (max, 10-15x compression on typical PCAPs)
- Disk monitoring: auto-purge oldest PCAPs when threshold hit (85% default)
- PcapNG format for metadata embedding
- **Managed by tool_manager.py**: auto-restart on crash within 5s, PID tracking

**Resources**: tcpdump 5MB RAM, 2-5% CPU. Compression spikes post-rotation.
**Dependencies**: tcpdump, zstandard (Python)

---

### `dns_logger.py` -- DNS Query Logger

Per-host browsing history from DNS queries. BPF filter on UDP/53, parse query/response, batch insert to SQLite.

- Per-source-IP log: timestamp, domain, response IPs, query type
- Flag DoH resolver connections (1.1.1.1, 8.8.8.8, 9.9.9.9) -- DNS blind spot indicator
- Batch: buffer 1000 records, flush every 60s

**Resources**: 15MB RAM, 2% CPU, 5MB/day disk
**Dependencies**: scapy or dpkt

---

### `tls_sni_extractor.py` -- TLS SNI Extractor

Parse TLS ClientHello on TCP/443+, extract SNI field. Correlate with DNS logs. Log: timestamp, source IP, dest IP:port, SNI hostname, TLS version. ECH/ESNI returns CDN dummy SNI (no passive mitigation). QUIC SNI handled by `quic_analyzer.py`.

**Resources**: 10MB RAM, 2% CPU, 3MB/day disk
**Dependencies**: scapy or dpkt

---

### `credential_sniffer.py` -- Credential Sniffer

Real-time credential extraction with immediate bus notification + credential_db insert. Scope: FTP USER/PASS, HTTP Basic/Digest/form POST, SNMP community, LDAP simple bind, NTLMv1/v2 challenge-response. Auto-push hashes to operator's cracking rig via data_exfil.

**Resources**: 15MB RAM, 3% CPU
**Dependencies**: scapy, impacket

---

### `kerberos_harvester.py` -- Kerberos Ticket Harvester

Extract tickets from wire for offline cracking. AS-REP (mode 18200), TGS-REP (mode 13100), AS-REQ encrypted timestamps (mode 7500). Identify DCs, realm names, UPNs. Immediate exfil -- tickets expire.

**Resources**: 15MB RAM, 3% CPU
**Dependencies**: scapy, impacket

---

### `host_discovery.py` -- Host Discovery

Build host inventory from passive observation. ARP table, DHCP request/ACK (hostname, vendor class), DHCP option 55 fingerprinting via `data/dhcp_fingerprints.db`, mDNS/Bonjour, NetBIOS, SSDP/UPnP, NBNS/LLMNR. Correlate: IP + MAC + hostname + vendor (OUI) + OS guess + DHCP fingerprint.

**Resources**: 15MB RAM, 2% CPU
**Dependencies**: scapy, data/oui.db, data/dhcp_fingerprints.db

---

### `os_fingerprint.py` -- Passive OS Fingerprinting

p0f-style: TCP SYN/SYN-ACK analysis (window size, TTL, DF, MSS, SACK, timestamps), HTTP User-Agent, DHCP vendor class, SMB dialect, SSH version strings. Confidence scoring per host.

**Resources**: 10MB RAM, 2% CPU
**Dependencies**: scapy, data/os_sigs.db

---

### `traffic_analyzer.py` -- Traffic Analyzer

Protocol distribution, flow tracking (5-tuple), top talkers, beacon detection (regular-interval C2/heartbeats), bandwidth profiling. Feeds traffic_mimicry baseline.

**Resources**: 25MB RAM (flow table), 5% CPU
**Dependencies**: scapy

---

### `vlan_discovery.py` -- VLAN Discovery

802.1Q tag detection, DTP frame capture, 802.1X/EAPOL detection, CDP/LLDP parsing (switch names, ports, VLANs), STP BPDU parsing (root bridge ID).

**Resources**: 10MB RAM, 1% CPU

---

### `network_mapper.py` -- Network Relationship Mapper

Communication graph: all pairs with protocol/volume metadata. Identify servers vs clients, admin workstations (SSH/RDP to many hosts), printer relationships. Graphviz DOT output. Periodic snapshots for change_detector.

**Resources**: 15MB RAM, 3% CPU

---

### `auth_flow_tracker.py` -- Authentication Flow Tracker

Cross-protocol auth correlation: Kerberos TGT (AS-REQ), service tickets (TGS-REQ), NTLM across SMB/HTTP/LDAP/MSSQL, SSH connections, LDAP binds. Per-user timeline. Identify service accounts.

**Resources**: 15MB RAM, 2% CPU
**Dependencies**: scapy, impacket

---

### `smb_monitor.py` -- SMB File Access Monitor

SMB2/3 tree connect + create request parsing. Track share/file access per user. Log: timestamp, user, source IP, share, file path, operation. Detect GPP/SYSVOL access patterns. SMB3 encrypted payload is opaque without MITM.

**Resources**: 15MB RAM, 2% CPU
**Dependencies**: scapy, impacket

---

### `cloud_token_harvester.py` -- Cloud Token Harvester (Passive)

Regex for AWS keys (AKIA*), JWT, OAuth tokens, SAML assertions in cleartext HTTP. Near-zero yield on most networks but zero-cost to run. Feed to credential_db.

**Resources**: 10MB RAM, 2% CPU

---

### `ldap_harvester.py` -- LDAP Query Harvester

Parse LDAP SearchRequest/SearchResponse on 389/3268. Extract: base DN, search filter, result entries. Build inventory: users, groups, computers, GPOs, SPNs. Detect LAPS password reads. Feed to topology_mapper.

**Resources**: 15MB RAM, 3% CPU
**Dependencies**: scapy, impacket

---

### `rdp_monitor.py` -- RDP Session Monitor

Parse RDP NLA headers on TCP/3389: username, domain, client hostname, keyboard layout. Parse CredSSP for NTLM/Kerberos auth. Track admin-to-server session patterns.

**Resources**: 10MB RAM, 2% CPU
**Dependencies**: scapy, impacket

---

### `quic_analyzer.py` -- QUIC/HTTP3 SNI Extractor

Parse QUIC Initial packets (RFC 9000) on UDP/443. Decrypt Initial payload using connection ID-derived keys (per RFC 9001, not secret). Extract CRYPTO frames containing TLS ClientHello, parse SNI. Feed into tls_sni_extractor log format.

**Resources**: 10MB RAM, 2% CPU

---

### `db_interceptor.py` -- Database Protocol Interceptor

Parse login packets and query metadata (not full result sets):
- **MSSQL TDS** (1433): login (username, hostname, app), SQL batch headers
- **MySQL** (3306): handshake, login, query packets
- **PostgreSQL** (5432): startup (user, database), query protocol
- **Redis** (6379): AUTH commands, key operations
- **MongoDB** (27017): OP_MSG auth and find operations

Query content analysis from PCAPs offline.

**Resources**: 20MB RAM, 3% CPU
**Dependencies**: scapy, impacket

---

## 5. Active Modules

8 modules. bettercap_mgr is the central orchestrator. Individual attack modules are thin wrappers that call bettercap's REST API. Responder, mitmproxy, and ntlmrelayx remain as direct subprocess wrappers.

---

### `bettercap_mgr.py` -- bettercap Orchestrator

Central manager for the single bettercap instance. All active MITM operations route through this.

- Start bettercap with REST API: `-api-rest-address 127.0.0.1 -api-rest-port 8083`
- Random per-session API credentials
- Health monitoring via API polling every 10s (`GET /api/session`)
- Auto-restart on crash (max 3) with caplet re-application
- **Crash recovery**: immediately send corrective gratuitous ARPs (scapy, 3 lines) if ARP spoof was active, then restart bettercap within 15s. Failsafe: disable ARP spoof after 3 crashes.
- Parse event stream (`GET /api/events`) for credential captures -> credential_db
- Parse event stream for host discoveries -> host_discovery
- Process disguise coordination with process_disguise.py
- Caplet management: load/unload/switch engagement profiles from `config/caplets/`

**bettercap REST API**:
```
POST /api/session     -- run commands (enable/disable modules, set params)
GET  /api/session     -- get session status
GET  /api/events      -- poll event stream (credentials, new hosts)
```

**Caplet files** (`config/caplets/`):
```
passive_recon.cap     -- net.recon on; net.sniff on; events.stream on
arp_mitm.cap          -- arp.spoof on; set arp.spoof.targets X; http.proxy on
dns_spoof.cap         -- dns.spoof on; set dns.spoof.domains X
full_mitm.cap         -- arp + dns + http proxy + js inject
wifi_recon.cap        -- wifi.recon on; wifi.show
```

**Resources**: bettercap 25-35MB RAM, 3-8% CPU
**Dependencies**: bettercap, utils/bettercap_api.py

---

### `arp_spoof.py` -- ARP Spoofing (bettercap wrapper)

Thin wrapper: configure targets/gateway, call `bettercap_mgr` to enable `arp.spoof`. bettercap handles rate-limiting and selective targeting.

> **OPSEC WARNING**: Most-detected active technique. DAI silently prevents it. EDR alerts within minutes. Prefer Responder + ipv6_slaac. Reserve for confirmed legacy segments. Run ids_tester DAI probe first.

---

### `dns_poison.py` -- DNS Poisoning (bettercap wrapper)

Push DNS spoofing rules via bettercap REST API. Template-driven zone files converted to `dns.spoof.domains` format.

---

### `dhcp_spoof.py` -- DHCP Spoofing (bettercap wrapper)

Configure DHCP pool via bettercap `dhcp6.spoof`. bettercap handles the DHCP race condition.

---

### `evil_twin.py` -- Evil Twin AP

hostapd-based AP matching target SSID with captive portal. Unchanged from v3.2 -- already uses external tools (hostapd + dnsmasq). Run wireless_intel WIDS detection (2-hour observation) before activation.

**Resources**: 30MB RAM, 5% CPU

---

### `ipv6_slaac.py` -- IPv6 SLAAC Spoofing

bettercap's `dhcp6.spoof` for RA injection + mitm6 for WPAD abuse. Wrapper manages both.

---

### `responder_mgr.py` -- Responder Manager

Manage Responder subprocess. Configure via Responder.conf.j2 template. Parse Responder logs for captured hashes. Feed to credential_db. Coordinate with ntlm_relay.

**Resources**: 30MB RAM, 3% CPU

---

### `mitmproxy_mgr.py` -- mitmproxy Integration

Manage mitmproxy in transparent mode. Uses addon scripts from `config/mitmproxy_addons/` for credential extraction, cloud token capture, file metadata logging. Override default CA CN to match target PKI. Pi 4+ only.

**Resources**: 100-200MB RAM, 10-20% CPU

---

### `ntlm_relay.py` -- NTLM Relay

ntlmrelayx subprocess wrapper. Relay targets: SMB, LDAP, LDAPS, HTTP, MSSQL, ADCS. Coordinates with responder_mgr and operator-run coercion tools (Coercer, PetitPotam).

**Resources**: 40MB RAM, 5% CPU

---

## 6. Intelligence

8 modules. Lightweight on-device analysis and structured data aggregation. Report generation moved offline.

---

### `credential_db.py` -- Credential Database

Central SQLite store. Schema: source_module, timestamp, source_ip, target_ip, target_service, username, domain, credential_type, credential_value, hashcat_mode, cracked_value. Dedup on (target_service, username, type, value). Ingests from: bettercap events, Responder logs, mitmproxy flows, passive modules. Export: hashcat format, CSV, JSON.

---

### `topology_mapper.py` -- Network Topology Mapper

Aggregate from host_discovery, network_mapper, vlan_discovery. Generate Graphviz DOT/SVG/PNG. Node types: workstation, server, printer, router, switch, AP. Edge colors by protocol.

---

### `net_intel.py` -- Network Intelligence

Beacon detection, communication graphing, existing C2/malware detection. Anomaly baseline for traffic_mimicry. Service dependency mapping.

---

### `user_timeline.py` -- Per-User Activity Timeline

Aggregate from dns_logger, auth_flow_tracker, smb_monitor, credential_sniffer. Per-user: login times, services, files, websites. Identify work hours, admin windows, service accounts.

---

### `supply_chain_detect.py` -- Supply Chain Detection

Passive detection: internal package repos (PyPI/npm/Maven mirrors), WSUS, internal CA, config management (SCCM/Puppet/Chef), container registries, CI/CD systems. Detection only.

---

### `change_detector.py` -- Network Change Detection

Continuous diff against baseline. Alert on: new hosts, new services, hosts disappearing, security tool traffic, scan activity targeting implant segment, unusual auth patterns. Publishes CHANGE_DETECTED events with severity. Critical for burn detection -- must run on-device.

---

### `security_posture.py` -- Security Posture Mapper

Detect: EDR update traffic (CrowdStrike, SentinelOne, Defender ATP), SIEM forwarding (Splunk HEC, Wazuh), vuln scanners, honeypots (Canary, T-Pot), NAC (802.1X/ISE/Forescout), network taps (SPAN, Gigamon). Gates active module risk assessment.

---

### `operator_audit.py` -- Operator Audit Trail

Log SSH sessions and commands to encrypted storage. PROMPT_COMMAND hook. Append-only with HMAC chain. Export for engagement reports and deconfliction.

---

### `tool_output_parser.py` -- Unified Tool Output Parser

Parse output from all managed tools into structured data:
- **bettercap** event stream (JSON): credentials, hosts, HTTP logs
- **Responder** logs (`Responder-Session.log`, `*-NTLMv2-*.txt`): NTLMv2 hashes
- **mitmproxy** flow dumps: credentials, tokens, headers
- Feed everything to credential_db and event bus

---

## 7. Connectivity

8 modules, unchanged from v3.2.

| Module | Purpose | Resources |
|---|---|---|
| `tailscale.py` | Fallback operator access via Tailscale mesh VPN. Convenient but chatty — maintains connection to coordination servers. Only use if target network already has Tailscale traffic or WireGuard is blocked. | 30MB, 2% |
| `wireguard.py` | **Primary C2.** WireGuard to operator's self-hosted endpoint. `PersistentKeepalive = 0` — tunnel exists but generates **zero traffic** until operator connects. No beacons, no heartbeats, no coordination servers. Completely silent while idle, instant access when operator sends a packet. | 5MB, 1% |
| `bridge.py` | Transparent inline bridge (USB eth + onboard). No IP on network. 802.1X bypass (silentbridge). STP/BPDU/CDP suppression via ebtables. C watchdog failsafe <15s. | 10MB, 2% |
| `wifi_client.py` | WPA2-PSK/Enterprise WiFi client. wpa_supplicant managed. | 10MB, 1% |
| `reverse_tunnel.py` | autossh reverse SSH. Must be SSH-over-WebSocket or SSH inside TLS (stunnel). Never raw SSH on 443. | 15MB, 1% |
| `cellular_backup.py` | LTE modem HAT (SIM7600/EC25). Out-of-band. Pi 4 only (2W power). | 15MB, 2% |
| `ble_emergency.py` | BLE GATT server. PSK auth. Status/kill/reboot. Disabled by default. | 5MB, 0.5% |
| `data_exfil.py` | Priority push (creds immediately), nightly sync (intel), on-demand pull (PCAPs). Respects traffic_mimicry baseline. Falls back through connectivity chain. | 15MB, 2% |

---

## 8. Stealth

12 modules. BigBrother's unique value. Expanded in v4.0 to cover bettercap/tcpdump process disguise.

### `mac_manager.py` -- Innocuous MAC Profiles

Replace generic "clone common vendor" with a curated database of consumer devices that wouldn't raise eyebrows on any network.

**`data/innocuous_macs.db`** -- SQLite database:

```sql
CREATE TABLE mac_profiles (
    id INTEGER PRIMARY KEY,
    device_type TEXT,        -- smart_tv, streaming, phone, tablet, smart_speaker, iot, gaming, printer
    vendor TEXT,             -- Amazon, Apple, Samsung, Roku, Google, Sonos, HP, Sony, Nintendo
    device_name TEXT,        -- Fire TV Stick 4K, iPhone 15, Galaxy S24, Roku Ultra
    oui TEXT,                -- FC:65:DE (Amazon), A4:83:E7 (Apple), etc.
    dhcp_hostname TEXT,      -- amazon-fire-tv, iPhone, Galaxy-S24
    dhcp_vendor_class TEXT,  -- matching vendor class for this device
    ttl INTEGER,             -- typical TTL: 64 (Android/Linux/iOS), 128 (Fire OS/Windows)
    tcp_window INTEGER,      -- typical TCP window size
    notes TEXT
);
```

**Categories** (populated with real OUIs):
- **Streaming**: Fire TV Stick, Roku, Apple TV, Chromecast, NVIDIA Shield -- on every network
- **Phones/tablets**: iPhone, Samsung Galaxy, Google Pixel, iPad -- nobody questions a new phone
- **Smart speakers**: Amazon Echo, Google Nest, Sonos -- always on, always connected
- **Smart home**: Nest thermostat, Ring doorbell, Philips Hue bridge -- ubiquitous IoT
- **Gaming**: PlayStation, Xbox, Nintendo Switch -- common on home networks
- **Printers**: HP, Brother, Canon -- invisible on business networks

**Behavior**:
1. On boot (pre-network, in initramfs), select profile from innocuous_macs.db
2. Set MAC to OUI from profile + random lower 3 bytes
3. Set DHCP hostname to match profile's `dhcp_hostname`
4. Set DHCP vendor class to match profile's `dhcp_vendor_class`
5. Tune TCP stack (TTL via sysctl, window size) to match profile
6. Log selected profile for operator reference

**Selection logic**:
- **Business network**: prefer printers, smart TVs (waiting room), IoT (thermostat)
- **Home network**: prefer streaming devices, phones, smart speakers
- **Operator override**: specify exact profile or device_type in config
- **Default**: random from streaming + smart_speaker + iot (safest -- appear everywhere)

---

### `process_disguise.py` -- Process Disguise

Rename all processes (Python + bettercap + tcpdump) to match legitimate system services. Spoof `/proc/self/cmdline`, `/proc/self/comm`. Go binaries: prctl(PR_SET_NAME) works for `ps` output. `/proc/PID/exe` still points to real binary -- same limitation as v3.2.

### `log_suppression.py` -- Log Suppression

rsyslog filter rules, auditd exclusions, journald rate-limit, clear bash history/utmp/wtmp/btmp.

### `encrypted_storage.py` -- LUKS Encrypted Storage

Boot-unlock via network-derived key (fetch from C2, combine with CPU serial via HKDF). If C2 unreachable: collect to tmpfs until reconnect. LUKS header destruction = instant unrecoverability.

### `tmpfs_manager.py` -- tmpfs for Sensitive Operations

tmpfs for active module working directories. Power loss = instant evidence destruction.

### `watchdog.py` -- Watchdog

Monitor all services: Python modules via multiprocessing, bettercap/tcpdump/Responder via tool_manager.py PID tracking. Auto-restart (max 3). OOM priority: core=-500, passive=100, active=200.

### `anti_forensics.py` -- Anti-Forensics

Timestomp to OS install date, secure deletion, no core dumps, no swap, clear journal entries. Set `$HOME` to tmpfs for bettercap (`~/.bettercap/` artifacts). `--no-history` flag for bettercap.

### `traffic_mimicry.py` -- Traffic Mimicry

Phase 1 (48h baseline): capture normal patterns. Phase 2: shape implant traffic to match. Exfil timed to upload patterns, beacon intervals matched to periodic traffic.

### `ja3_spoofer.py` -- JA3 Fingerprint Spoofing

Apply Chrome/Firefox/Edge JA3 hashes to all outbound HTTPS (C2, data transfer, bettercap, mitmproxy).

### `ids_tester.py` -- IDS Self-Testing

Load Snort/Suricata rules from `data/ids_rules/`. Check planned actions (including bettercap caplet actions) against known signatures. Rate detection risk.

### `lkm_rootkit.py` -- LKM Rootkit (Optional)

Hides processes from /proc, files from readdir, network connections from /proc/net/tcp|udp. Hides bettercap binary + tcpdump in addition to Python processes. Debian host only.

### `overlayfs_manager.py` -- overlayfs SD Card Protection

Root FS as overlayfs (read-only base + tmpfs overlay). Zero SD write activity except LUKS container. Writes vanish on reboot.

---

## 9. Core Framework

### `bigbrother.py` -- Main CLI

Click CLI + Rich TUI. Commands: start, stop, status, activate, deactivate, kill, creds, intel, triage, timeline, topology, baseline, config, selftest.

### `core/engine.py` -- Module Lifecycle Manager

Multiprocess model: each module as separate process. Dependency resolution. Resource budgeting. Hardware tier enforcement (Pi Zero: 4 passive max). Interface conflict detection. Optional scope enforcement. Engagement phase gating (passive_only for N days, then active_allowed).

### `core/capture_bus.py` -- Packet Capture Bus

Single privileged AF_PACKET socket, demux to per-module queues by BPF filter. One capture process, modules subscribe by filter expression. Queue backpressure: if module falls behind, oldest packets dropped from its queue only.

### `core/tool_manager.py` -- Subprocess Lifecycle Manager

Generic subprocess management for bettercap, tcpdump, Responder, mitmproxy, ntlmrelayx.

- Start/stop/restart with configurable retry (max 3, exponential backoff)
- stdout/stderr capture to encrypted log
- PID tracking for kill_switch integration
- Resource monitoring (RSS, CPU via `/proc/PID/stat`)
- Process disguise integration (rename via prctl)
- Health check callbacks (per-tool: bettercap API poll, Responder PID, mitmproxy API)
- Graceful shutdown (SIGTERM -> 5s timeout -> SIGKILL)
- Crash callbacks (e.g., ARP restoration on bettercap crash)

### `core/bus.py` -- Internal Event Bus

```
CREDENTIAL_FOUND    HOST_DISCOVERED     PCAP_ROTATED
MODULE_STARTED      MODULE_STOPPED      MODULE_ERROR
RESOURCE_WARNING    RESOURCE_CRITICAL   KILL_SWITCH
CONNECTIVITY_CHANGED  VLAN_DETECTED     HANDSHAKE_CAPTURED
TICKET_HARVESTED    CLOUD_TOKEN_FOUND   BEACON_DETECTED
CHANGE_DETECTED     THERMAL_WARNING     SCOPE_VIOLATION
TOOL_CRASHED        TOOL_RESTARTED
```

### `core/state.py` -- Persistent State

Single SQLite, WAL mode, dedicated async writer thread with 500ms coalesce. WAL files on tmpfs with periodic checkpoint (accept 30min data loss for SD longevity).

### `core/scheduler.py` -- Task Scheduler

Cron-like with jitter. PCAP rotation, health checks, baseline captures, data pruning.

### `core/resource_monitor.py` -- Resource Monitor

Per-module + per-subprocess RAM/CPU/disk. Hardware tier limits. OOM kill lowest priority. Thermal: THERMAL_WARNING at 55C, shed modules at 70C.

### `core/kill_switch.py` -- Kill Switch

```
1. Stop all modules + subprocesses (bettercap, tcpdump, Responder)
2. Send corrective ARP if ARP spoof was active
3. Destroy LUKS header (milliseconds)
4. Shred encryption keys + credential database
5. dd zero-fill data partition
6. Clear RAM
7. Reboot (boot flag auto-completes if interrupted)
```

### `utils/bettercap_api.py` -- bettercap REST Client

```python
class BettercapAPI:
    def __init__(self, host="127.0.0.1", port=8083, user="bb", password="..."):
    def run(self, command: str) -> dict:
    def get_session(self) -> dict:
    def get_events(self, since: int = 0) -> list:
    def is_alive(self) -> bool:
```

---

## 10. Operator Workstation — Shadow SOC

The operator's workstation is the analysis brain. The Pi captures and extracts real-time metadata. The workstation runs **SOC-grade analysis against pulled PCAPs** — giving you defender-level visibility to make better attack decisions.

### Shadow SOC Analysis Stack

The core offline tool is **Zeek**. Run it against pulled PCAPs and it produces structured protocol logs that tell you exactly what's vulnerable, what's misconfigured, and where to attack — without ever scanning the network.

| Zeek Log | What It Tells You (Offensively) |
|---|---|
| **ssl.log** | Every TLS cert on the network: expired certs (users trained to click through warnings → MITM viable), self-signed certs (same), weak ciphers (RC4, 3DES), old TLS versions (1.0/1.1 → downgrade attacks), cert SANs (internal hostnames revealed) |
| **smb.log** | SMB versions negotiated per host: SMBv1 = EternalBlue candidate, no signing = relay target, shares accessed, filenames transferred |
| **http.log** | Every cleartext HTTP request: URLs, headers, user-agents, POST bodies. Find internal apps with no TLS, default admin panels, API endpoints with hardcoded tokens |
| **kerberos.log** | Every Kerberos exchange: SPNs (Kerberoast targets), encryption types (RC4 = weak, easier to crack), auth failures (password spray opportunities) |
| **dns.log** | Complements on-device dns_logger with response analysis: NXDOMAIN patterns, internal zone structure, DNS-based service discovery |
| **conn.log** | Every connection: source, dest, port, protocol, duration, bytes. Map all communication patterns, find long-lived sessions, identify servers vs clients |
| **files.log** | Every file transferred over HTTP/SMB/FTP: filename, size, MIME type, hash. Find sensitive documents moving in cleartext |
| **x509.log** | Certificate chain details: CA hierarchy, key sizes, validity periods. Map the target's PKI |

**Also on workstation:**

| Tool | Purpose |
|---|---|
| **Wireshark/tshark** | Deep packet inspection, stream reconstruction, manual protocol analysis |
| **NetworkMiner** | Automated file/image/credential extraction from PCAPs, OS fingerprinting |

### Shadow SOC Workflow

```
Day 1-7:  BigBrother runs passive on target network
Day 7:    Operator pulls PCAPs + metadata to workstation
          └── scripts/operator/pull_data.sh

          Run Zeek offline:
          └── scripts/operator/run_zeek.sh → protocol logs from PCAPs

          Review Zeek findings for attack paths:
          - ssl.log: "10.0.1.5 — expired cert, TLS 1.0, RC4" → users click through warnings, MITM viable
          - smb.log: "10.0.1.10 negotiates SMBv1, no signing" → relay target, possible EternalBlue
          - http.log: "10.0.1.102 → 10.0.1.5:1433 cleartext SQL" → db_interceptor already has creds
          - http.log: "10.0.1.101 → 10.0.1.1:80 HTTP Basic auth" → router creds in the clear
          - kerberos.log: "SVC_BACKUP requests TGS for CIFS/DC01, RC4 encryption" → weak, crackable
          - conn.log: "10.0.1.108 → 185.x.x.x every 3600s, 2KB each" → possible existing C2 (report finding)
          - files.log: "payroll.xlsx transferred via SMB cleartext from 10.0.1.106" → sensitive data exposure

Day 8:    Use Zeek intel to pick targets + activate attack modules
          - SMBv1 + no signing on NAS → ntlm_relay target
          - Cleartext SQL → already captured via db_interceptor
          - RC4 Kerberos service account → kerberos_harvester already has the hash, weak encryption = fast crack
          - Expired cert on internal app → mitmproxy won't cause additional warnings
          - Existing beacon → document for client report (huge finding, free)
```

### Content Extraction Tools

| Tool | Purpose |
|---|---|
| **pcl2pdf / Ghostscript** | Reconstruct print jobs from TCP/9100 traffic in PCAPs |
| **hashcat + GPU** | Crack NTLMv2, Kerberos TGS, AS-REP, WPA handshakes |
| **john** | CPU cracking fallback |
| **CyberChef** | Data transformation, decoding, deobfuscation |

### Operator Scripts (`scripts/operator/`)

| Script | Purpose |
|---|---|
| `pull_data.sh` | rsync over Tailscale/WG: creds DB, DNS logs, host inventory, PCAPs |
| `run_zeek.sh` | Run Zeek offline against PCAPs → protocol logs (ssl, smb, http, kerberos, dns, conn, files, x509) |
| `extract_files.sh` | tshark + NetworkMiner batch file extraction from PCAPs |
| `extract_print_jobs.sh` | Filter TCP/9100 from PCAPs, reconstruct with pcl2pdf/Ghostscript |
| `extract_emails.sh` | Filter SMTP from PCAPs, reconstruct with tshark |
| `crack_hashes.sh` | Export from credential_db in hashcat format, run against wordlists |
| `generate_report.py` | Pull SQLite DBs + Zeek findings, generate engagement report (Markdown + HTML) |

### Workstation Requirements

- Linux or macOS (Windows works but scripts assume bash)
- Tailscale installed (same tailnet as implant)
- **Zeek** installed (offline PCAP → protocol logs)
- hashcat with GPU (NVIDIA recommended)
- 100GB+ free disk for PCAP analysis + Zeek output
- Wireshark, tshark, NetworkMiner installed

---

## 11. Pre-installed Tools

Installed by `setup.sh`. Operator runs directly via SSH. BigBrother does not wrap these.

| Tool | Purpose |
|---|---|
| **nmap** | Port scanning, service detection, NSE scripts |
| **masscan** | High-speed port scanning |
| **Certipy** | AD Certificate Services enum/attacks |
| **Impacket** | secretsdump, ntlmrelayx, smbexec, wmiexec, psexec, GetUserSPNs, GetNPUsers, etc. |
| **BloodHound.py** | AD data collection (Python ingestor) |
| **Responder** | LLMNR/NBT-NS/mDNS poisoning (also managed by BB) |
| **CrackMapExec / NetExec** | Network auth testing, enum, command execution |
| **Coercer** | All coercion methods (PetitPotam, PrinterBug, DFSCoerce, ShadowCoerce) |
| **PetitPotam.py** | Standalone MS-EFSRPC coercion |
| **Chisel** | TCP/UDP tunneling over HTTP, SOCKS proxy |
| **Ligolo-ng** | Tunneling/pivoting |
| **proxychains-ng** | Proxy chain routing |
| **socat** | Multipurpose relay |
| **sshuttle** | Transparent SSH-based VPN/pivot |
| **mitm6** | IPv6 MITM with WPAD abuse |
| **Bettercap** | Network attack and monitoring (also managed by BB) |
| **tcpdump** | Packet capture (also managed by BB) |
| **tshark** | Protocol analysis, PCAP processing |
| **mitmproxy** | HTTPS interception (also managed by BB, Pi 4+ only) |
| **iodine** | DNS tunnel |
| **autossh** | Persistent SSH tunnels |
| **aircrack-ng** | WiFi capture/cracking suite |
| **hashcat** | Password cracking (if GPU, Debian host only) |
| **evil-winrm** | WinRM shell |
| **enum4linux-ng** | SMB/NetBIOS enumeration |
| **kerbrute** | Kerberos brute-force/user enum |
| **pypykatz** | Mimikatz in Python |
| **ldapdomaindump** | AD enumeration |
| **smbmap** | SMB share enumeration |
| **ROADtools** | Azure/Entra ID recon (Pi 4+ only) |

---

## 12. Setup & Bootstrap

### `setup.sh` -- Idempotent Bootstrap

Detects platform (Pi Zero 2W / Pi 4 / Debian) and installs accordingly.

**System packages**: python3, python3-venv, python3-dev, build-essential, libssl-dev, libffi-dev, libpcap-dev, bridge-utils, ebtables, iptables, nftables, iproute2, net-tools, tcpdump, tshark, nmap, masscan, dnsutils, hostapd, dnsmasq, wireless-tools, wpasupplicant, aircrack-ng, wireguard-tools, cryptsetup, curl, wget, git, jq, tmux, screen, autossh, bluez, libbluetooth-dev, ppp, usb-modeswitch, iodine, bettercap, proxychains-ng, socat, sshuttle, stunnel4

**Python venv** (`.venv/`): click, rich, pyyaml, cryptography, scapy, impacket, certipy-ad, bloodhound, dnslib, requests, dpkt, pyjwt, python-magic, numpy, graphviz, jinja2, zstandard, mitmproxy (Pi 4+ only)

**Tools from GitHub/pipx** (to `/opt/tools/`): Responder, CrackMapExec/NetExec, Chisel, Ligolo-ng, mitm6, evil-winrm, enum4linux-ng, kerbrute, Coercer, PetitPotam.py, pypykatz, ldapdomaindump, smbmap, ROADtools (Pi 4+)

**Directories**: `storage/{config,pcaps,creds,dns_logs,sni_logs,intel,baseline,audit,tool_logs,logs}` mode 700

**Setup reliability**: Pre-bundle tool binaries with SHA256 checksums. Pin pip versions. Guard conditions for non-idempotent operations. `--reinstall` flag.

**Kernel config**: IP forwarding (v4+v6), no send_redirects.

**Pi optimizations**: gpu_mem=16, disable bluetooth/avahi, no swap.

### Systemd Services

| Service File | Visible Description | Actual Function |
|---|---|---|
| `bigbrother-core.service` | System Thermal Management Daemon | Main daemon |
| `bigbrother-watchdog.service` | System Health Monitor | Watchdog |
| `bigbrother-capture.service` | Network Interface Statistics Collector | tcpdump capture |
| `bigbrother-passive.service` | Network Device Monitor | Passive surveillance |
| `bigbrother-bridge.service` | Network Bridge Service | Transparent bridge |
| `bigbrother-tailscale.timer` | VPN Health Check Timer | Tailscale health |

---

## 13. Configuration

### `config/bigbrother.yaml` -- Master Config (Plaintext FS)

Non-sensitive defaults only. Keys, auth tokens, engagement data in `storage/config/` inside LUKS.

```yaml
device:
  platform: "auto"              # auto | pi_zero | pi4 | generic
  hostname: "iot-sensor-03"
  install_path: "/opt/.cache/bb"

network:
  primary_interface: "auto"
  bridge:
    enabled: false
    internal: "eth0"
    external: "eth1"
  wifi:
    interface: "wlan0"
  cellular:
    enabled: false
    modem_device: "/dev/ttyUSB0"

connectivity:
  primary: "wireguard"            # Zero traffic when idle, instant access on demand
  failover_chain: [wireguard, tailscale, reverse_tunnel, cellular_backup]

security:
  encryption_key_derive: "argon2id"  # argon2id | pbkdf2 (Pi Zero)
  dead_man_switch:
    enabled: false
    interval_hours: 24

capture:
  pcap_rotation_hours: 1
  pcap_compression: "zstd"
  pcap_compression_level: 19    # Pi Zero: auto-downgrade to 3
  pcap_format: "pcapng"
  snap_length: 65535
  bpf_filter: "full_capture"
  disk_max_pct: 85

stealth:
  mac_profile: "auto"            # auto | streaming | printer | iot | <specific device_name>
  mac_network_type: "auto"       # auto | business | home

baseline:
  duration_hours: 48
  auto_start: true

engagement_phase:
  mode: "passive_only"
  passive_days: 7
  auto_transition: true

bettercap:
  api_address: "127.0.0.1"
  api_port: 8083
  default_caplet: "passive_recon"
```

### `config/modules.yaml` -- Module Configuration

Active module parameters:

```yaml
active:
  bettercap_mgr:
    max_restarts: 3
    health_poll_interval_s: 10
  arp_spoof:
    targets: []
    gateway: "auto"
  dns_poison:
    domains: {}
    mode: "selective"
  dhcp_spoof:
    pool_start: ""
    pool_end: ""
  evil_twin:
    ssid: ""
    channel: 6
    portal: "corporate_login"
  responder_mgr:
    protocols: {llmnr: true, nbtns: true, mdns: true}
  mitmproxy_mgr:
    addons: [credential_extractor, cloud_token_extractor]
    ca_cn: ""                   # Override default mitmproxy CA CN
  ntlm_relay:
    targets: []
    attack: "smb"
```

### `config/scope.yaml` -- Optional Scope Enforcement

```yaml
enabled: false
networks: [10.10.0.0/16, 10.0.0.0/24]
hosts: [dc01.corp.local, 10.10.1.50]
domains: [corp.local]
exclude: [10.10.99.0/24]       # OT segment
```

---

## 14. Hardware Tiers

**Minimum SD card**: 128GB high-endurance industrial. With zstd -19 (10-15x on PCAPs), effective ~1.2TB PCAP storage. tmpfs for SQLite WAL files, buffer writes through tmpfs with async flush.

**Power**: Minimum 5V/3A dedicated. Consider PoE splitter. selftest checks power source.

| Capability | Pi Zero 2W (512MB) | Pi 4 (4GB) | Debian Host |
|---|:---:|:---:|:---:|
| **Max passive modules** | 4 | All 16 | All 16 |
| **Max active modules** | 1 (bettercap only) | 6 | Unlimited |
| **bettercap** | Maybe (85MB headroom) | Yes | Yes |
| **mitmproxy** | No | Yes | Yes |
| **Snap length** | 65535 (full) | 65535 (full) | 65535 (full) |
| **PCAP compression** | zstd -3 (fast) | zstd -19 (max) | zstd -19 (max) |
| **Key derivation** | pbkdf2 | argon2id | argon2id |
| **LKM rootkit** | No | No | Yes |
| **Cellular modem** | No (power) | Yes | Yes |
| **overlayfs** | Yes (30MB) | Yes (200MB) | N/A |
| **ROADtools** | No | Yes | Yes |

### Pi Zero 2W Memory Budget (Passive Mode)

| Component | RAM (MB) |
|---|---|
| OS + kernel | ~110 |
| Python interpreter + libs | ~55 |
| Core framework + capture_bus | ~25 |
| tcpdump | ~5 |
| dns_logger | ~15 |
| credential_sniffer | ~15 |
| host_discovery | ~15 |
| stealth modules | ~20 |
| encrypted_storage | ~10 |
| overlayfs overhead | ~30 |
| connectivity | ~25 |
| **TOTAL** | **~325** |
| **Headroom** | **~85** |

Extra 85MB headroom (vs 35MB in v3.2) means bettercap could potentially run for a single active capability (ARP spoof) on Pi Zero.

### Pi 4 Memory Budget (Full Active)

| Component | RAM (MB) |
|---|---|
| OS + kernel | ~110 |
| Python interpreter + libs | ~55 |
| Core framework + tool_manager | ~25 |
| tcpdump | ~5 |
| bettercap | ~30 |
| 16 passive Python modules | ~200 |
| Responder | ~30 |
| mitmproxy | ~150 |
| Stealth modules | ~50 |
| Connectivity | ~55 |
| Intel modules | ~55 |
| **TOTAL** | **~765** |
| **Headroom** | **~3.3GB** |

---

## 15. Implementation Phases

### Phase 1: Foundation + Stealth (Weeks 1-2)

Core infrastructure, multiprocess lifecycle, capture bus, tool_manager, stealth layer, innocuous MAC database.

```
Files:
- bigbrother.py (CLI skeleton)
- core/ (engine, capture_bus, tool_manager, bus, state, scheduler, resource_monitor, kill_switch)
- modules/base.py
- modules/stealth/ (all 12 modules)
- utils/ (all 8 modules incl. bettercap_api.py)
- config/ (bigbrother.yaml, modules.yaml, stealth.yaml, hardware_tiers.yaml, scope.yaml)
- config/caplets/ (passive_recon.cap, arp_mitm.cap, dns_spoof.cap, full_mitm.cap)
- services/ (all systemd units)
- setup.sh (packages, tools, bettercap install)
- data/innocuous_macs.db, data/dhcp_fingerprints.db, data/wordlists/
- tests/ (engine, bus, crypto, resource, tool_manager)

Validation: Module lifecycle works. tool_manager starts/stops/restarts bettercap
and tcpdump. MAC profile selected from innocuous_macs.db with matching DHCP
hostname/vendor class and TCP stack tuning. LUKS encryption working. Kill switch
wipes all data. Watchdog restarts crashed subprocesses. Overlayfs on Pi.
```

### Phase 2: Passive Surveillance (Weeks 3-5)

All 16 passive modules + intel modules. tcpdump capture wrapper. Zero network noise.

```
Files:
- modules/passive/ (all 16 modules)
- modules/intel/ (credential_db, topology_mapper, net_intel, user_timeline,
  change_detector, security_posture, operator_audit, tool_output_parser,
  supply_chain_detect)
- data/ (oui.db, os_sigs.db, bpf_filters/)

Validation: tcpdump captures with rotation + zstd + AES pipeline. All hosts
discovered (DHCP fingerprinting). Credentials captured. DNS logged per host.
TLS SNI extracted (TCP + QUIC). LDAP parsed, AD objects inventoried. RDP
sessions tracked. DB queries intercepted. Kerberos tickets harvested. SMB
metadata logged. Network map generated. Change detection operational.
Zero IDS alerts.
```

### Phase 3: Connectivity + Baseline (Weeks 6-7)

All connectivity modules + data exfil pipeline. Bridge hardening. Traffic baseline.

```
Files:
- modules/connectivity/ (all 8 modules)
- modules/stealth/traffic_mimicry.py (baseline phase)
- scripts/setup_bridge.sh, teardown_bridge.sh

Validation: Failover chain works. Bridge transparent with STP/CDP suppression.
C watchdog <15s failsafe. 48h baseline captured. Data exfil pipeline pushes
creds on capture, nightly intel sync.
```

### Phase 4: Active Surveillance (Weeks 8-9)

bettercap_mgr + all active modules. Operator workstation scripts.

```
Files:
- modules/active/ (all 8 modules)
- config/mitmproxy_addons/ (credential_extractor, cloud_token_extractor, file_logger)
- templates/ (captive_portals, dns_zones, hostapd, responder)
- scripts/operator/ (all 6 scripts)

Validation: bettercap_mgr starts bettercap, monitors health, auto-restarts on
crash with ARP correction. ARP spoof via bettercap REST API. DNS poisoning.
Responder captures NTLMv2. ntlmrelayx relays to ADCS. mitmproxy with addon
scripts. Operator workstation scripts pull data and run analysis.
```

### Phase 5: Polish + Hardening (Weeks 10-12)

```
Tasks:
- Full integration on Pi Zero (4 passive + tcpdump), Pi 4 (all 16 + bettercap), Debian
- 72-hour soak test (memory leaks, disk, thermal, bettercap stability)
- Pi Zero: verify 325MB budget, thermal under 55C, bettercap feasibility test
- Capture bus stress test (throughput, backpressure)
- SQLite contention test (16 modules + tool_output_parser writing concurrently)
- bettercap crash/restart cycle test (ARP restoration timing)
- tool_manager subprocess lifecycle test (all 5 managed tools)
- LUKS unlock test (C2 reachable and unreachable)
- setup.sh clean OS image validation (all tools + bettercap install)
- Innocuous MAC profile validation (DHCP fingerprint matches, TCP stack matches)
- Operator workstation script validation (pull, extract, crack, report pipeline)
- zstd PCAP compression on 128GB storage
- Error handling audit
```

---

## 16. OPSEC Notes

### Pre-Deployment

1. **Sanitize hardware** -- Remove labels. Generic enclosure.
2. **MAC profile** -- Select innocuous device profile from innocuous_macs.db BEFORE connecting. Match DHCP hostname + vendor class + TCP stack to profile.
3. **Hostname** -- Matches selected MAC profile (e.g., "amazon-fire-tv", not "kali").
4. **SSH keys** -- Fresh per engagement. Neutral key comment.
5. **Tailscale** -- Per-engagement auth key. Hostname matches profile.
6. **SD card** -- 128GB minimum, high-endurance. Enable overlayfs.
7. **Pre-bundle everything** -- Zero package installs on target network.
8. **Test kill switch** -- Verify wipe before field deployment.
9. **bettercap binary** -- Optionally compile from source (`go build`) for unique hash.

### During Operation

10. **Passive-only phase** -- Enforce 1-2 week minimum. New device + active attacks within hours = highest-confidence SIEM correlation.
11. **Working hours** -- Active modules during business hours only.
12. **Traffic blending** -- traffic_mimicry shapes implant traffic to baseline.
13. **JA3** -- All outbound HTTPS uses ja3_spoofer (including bettercap, mitmproxy).
14. **Rate limiting** -- All active modules use jitter. No fixed intervals.
15. **Selective targeting** -- ARP spoof specific hosts via bettercap, not subnets.
16. **IDS self-test** -- Run ids_tester (including caplet actions) before activation.
17. **bettercap signatures** -- Custom caplets strip/modify proxy headers. Set user-agent to Chrome.

### Host Forensics

18. **Process names** -- All processes (Python + bettercap + tcpdump) disguised as system services.
19. **File paths** -- Installed in `/opt/.cache/bb/`.
20. **Log suppression** -- rsyslog filters, auditd exclusions, no bash history.
21. **Encrypted storage** -- LUKS for all sensitive data. bettercap `$HOME` set to tmpfs.
22. **tmpfs** -- Active operations in RAM. Power loss = instant destruction.
23. **overlayfs** -- SD card sees zero writes except LUKS container.
24. **Timestamps** -- All files timestomped to OS install date.

### Kill Switch

25. **Manual only** -- Operator's decision.
26. **Corrective ARP** -- Kill switch sends ARP correction before wipe if spoof was active.
27. **CLI / SSH / BLE / Dead man's switch** -- Multiple trigger methods.
28. **LUKS header destruction** -- Milliseconds. Data instantly unrecoverable.
29. **Resilient** -- Boot flag auto-completes if interrupted.

### Network Footprint

30. **Bridge mode** -- No IP, no MAC on network. Physical inspection only.
31. **MAC profile** -- Device appears as consumer electronics (Fire TV, Roku, etc.), not Raspberry Pi.
32. **WireGuard primary** -- Zero traffic when idle (`PersistentKeepalive = 0`). Self-hosted endpoint, no third-party coordination servers. Tailscale only as fallback if WireGuard is blocked or target already has Tailscale traffic.
33. **Reverse SSH** -- SSH-over-WebSocket or inside TLS (stunnel). Never raw SSH on 443.
34. **Data exfil** -- Timed to match baseline upload patterns via traffic_mimicry.
35. **bettercap REST API** -- Bound to 127.0.0.1 only. Not network-visible.