From d3d1deb99cff765de280d2b907d3472c0603aff4 Mon Sep 17 00:00:00 2001 From: n0mad1k Date: Tue, 17 Mar 2026 10:57:51 -0400 Subject: [PATCH] v3.1: Incorporate security tribe review findings into design doc Add 7 new modules: ldap_harvester, rdp_monitor, quic_analyzer, db_interceptor (passive), change_detector, security_posture, operator_audit (intel). Add capture_bus for single AF_PACKET demux to per-module queues (multiprocess architecture). Fix Pi Zero memory budget (70MB interpreter, 4 passive modules max). Move sensitive config inside LUKS with network-derived boot key. Require 128GB SD card with zstd PCAP compression. Add coercion tools (Coercer, PetitPotam), proxychains-ng, socat, sshuttle, pypykatz, ldapdomaindump, smbmap, ROADtools. Add thermal monitoring, SQLite contention fix (single DB + async writer), bridge STP/CDP suppression, DHCP fingerprinting, wireless interface conflict detection, optional scope.yaml, DoH/ECH awareness, triage CLI command. Update implementation phases and hardware tier matrix. --- BIGBROTHER_DESIGN.md | 401 +++++++++++++++++++++++++++++++++---------- 1 file changed, 310 insertions(+), 91 deletions(-) diff --git a/BIGBROTHER_DESIGN.md b/BIGBROTHER_DESIGN.md index 862ec90..cd8becd 100644 --- a/BIGBROTHER_DESIGN.md +++ b/BIGBROTHER_DESIGN.md @@ -1,6 +1,6 @@ # BigBrother: Total Network Surveillance Platform + Operator Jump Box -> **Version**: 3.0 +> **Version**: 3.1 > **Date**: 2026-03-17 > **Status**: Implementation Blueprint @@ -31,7 +31,7 @@ The platform has two operational modes. **Passive surveillance** runs unsupervis BigBrother is not an autonomous attack framework. There is no decision engine, no state machine, no automated attack chaining. The operator makes all decisions. When the operator needs to run offensive tools, they SSH into the box and use the pre-installed toolkit directly: nmap, Certipy, Impacket, BloodHound, CrackMapExec, Chisel, Ligolo-ng. These tools are installed by `setup.sh`, not wrapped in Python. The operator runs them, interprets the results, and decides what to do next. -Scope is the operator's responsibility. There is no hard scope enforcement layer or OT lockout mechanism in the code. The operator knows their engagement boundaries and operates within them. +Scope is the operator's responsibility. An optional `scope.yaml` can be loaded to validate active module targets against in-scope ranges, but this is not mandatory — there is no hard scope enforcement or OT lockout mechanism forced on the operator. --- @@ -45,10 +45,11 @@ Scope is the operator's responsibility. There is no hard scope enforcement layer ├── .gitignore │ ├── config/ -│ ├── bigbrother.yaml # Master config (engagement, device, network) +│ ├── bigbrother.yaml # Non-sensitive defaults only (plaintext FS) │ ├── modules.yaml # Per-module enable/disable + params │ ├── stealth.yaml # OPSEC/stealth profile config │ ├── hardware_tiers.yaml # Pi Zero 2W vs Pi 4 vs Debian host limits +│ ├── scope.yaml # Optional scope enforcement (IP ranges, domains) │ └── templates/ │ ├── engagement_default.yaml # Template for new engagements │ ├── engagement_minimal.yaml # Minimal config for Pi Zero 2W @@ -57,10 +58,11 @@ Scope is the operator's responsibility. There is no hard scope enforcement layer ├── core/ │ ├── __init__.py │ ├── engine.py # Module lifecycle manager (load, start, stop, status) +│ ├── capture_bus.py # Single AF_PACKET capture, demux to per-module queues │ ├── scheduler.py # Task scheduler (cron-like, jitter-aware) │ ├── bus.py # Internal event bus (pub/sub between modules) │ ├── state.py # Persistent state manager (SQLite) -│ ├── resource_monitor.py # RAM/CPU/disk watchdog, throttle enforcement +│ ├── resource_monitor.py # RAM/CPU/disk/thermal watchdog, throttle enforcement │ └── kill_switch.py # Manual wipe orchestrator │ ├── modules/ @@ -86,7 +88,11 @@ Scope is the operator's responsibility. There is no hard scope enforcement layer │ │ ├── wireless_intel.py # Probe requests, BLE scanning, WPA handshakes, WIDS │ │ ├── protocol_analyzer.py # Zeek-style protocol dissection, service ID, cert analysis │ │ ├── cloud_token_harvester.py # Passive AWS keys, Azure tokens, JWT, OAuth, SAML -│ │ └── email_sniffer.py # Capture email content + attachments from cleartext SMTP/IMAP/POP3 +│ │ ├── email_sniffer.py # Capture email content + attachments from cleartext SMTP/IMAP/POP3 +│ │ ├── ldap_harvester.py # LDAP search query/response parsing, AD object inventory +│ │ ├── rdp_monitor.py # RDP NLA/CredSSP header parsing, session tracking +│ │ ├── quic_analyzer.py # QUIC Initial packet SNI extraction (UDP/443) +│ │ └── db_interceptor.py # MSSQL/MySQL/PostgreSQL/Redis/MongoDB protocol parsing │ │ │ ├── active/ # Operator-enabled, then runs unattended │ │ ├── __init__.py @@ -137,7 +143,10 @@ Scope is the operator's responsibility. There is no hard scope enforcement layer │ ├── report_generator.py # Engagement summary, timeline, findings │ ├── net_intel.py # Beacon detection, communication graphing │ ├── user_timeline.py # Per-user activity timeline (DNS + auth + traffic) -│ └── supply_chain_detect.py # Passive detection of internal repos, WSUS, CI/CD, registries +│ ├── supply_chain_detect.py # Passive detection of internal repos, WSUS, CI/CD, registries +│ ├── change_detector.py # Continuous network state diffing, burn detection +│ ├── security_posture.py # Map target defenses (EDR, SIEM, honeypots) +│ └── operator_audit.py # Encrypted operator session/command audit trail │ ├── services/ │ ├── bigbrother-core.service # Main daemon (disguised name in production) @@ -180,6 +189,7 @@ Scope is the operator's responsibility. There is no hard scope enforcement layer ├── data/ │ ├── oui.db # MAC OUI database (SQLite, compressed) │ ├── os_sigs.db # Passive OS fingerprint signatures +│ ├── dhcp_fingerprints.db # DHCP option 55 fingerprints (Fingerbank dataset) │ ├── ids_rules/ # Snort/Suricata rule snapshots for self-testing │ │ ├── emerging-threats.rules │ │ └── snort-community.rules @@ -204,8 +214,9 @@ Scope is the operator's responsibility. There is no hard scope enforcement layer │ ├── teardown_bridge.sh # Bridge interface teardown │ └── build_lkm.sh # Compile rootkit LKM for target kernel │ -└── storage/ # Runtime data (gitignored, encrypted) - ├── pcaps/ # Rotated packet captures +└── storage/ # Runtime data (gitignored, LUKS-encrypted) + ├── config/ # Sensitive config (keys, auth, engagement details) + ├── pcaps/ # Rotated packet captures (zstd compressed) ├── creds/ # Extracted credentials ├── dns_logs/ # DNS query logs per host ├── sni_logs/ # TLS SNI destination logs @@ -215,6 +226,7 @@ Scope is the operator's responsibility. There is no hard scope enforcement layer ├── print_jobs/ # Intercepted print spool data ├── intel/ # Analysis outputs, topology graphs ├── baseline/ # Traffic baseline data (48h capture) + ├── audit/ # Operator session/command audit trail └── logs/ # Encrypted operation logs ``` @@ -224,7 +236,7 @@ Scope is the operator's responsibility. There is no hard scope enforcement layer ### 3.1 Passive Surveillance (24/7, zero noise, unsupervised) -These modules start at deployment and run continuously without generating any network traffic. +22 passive modules. These start at deployment and run continuously without generating any network traffic. All receive packets via the capture bus (one AF_PACKET socket, demuxed to per-module queues). --- @@ -253,6 +265,9 @@ These modules start at deployment and run continuously without generating any ne - Aggregate into browsing profiles per host - Detect internal DNS servers, split-horizon configurations - Flag interesting domains: cloud services, security tools, update servers, webmail +- Flag hosts connecting to known DoH resolvers (1.1.1.1, 8.8.8.8, 9.9.9.9) — indicates DNS blind spot for that host +- When in MITM position: option to block DoH resolver IPs and strip HTTPS DNS records (type 65) to force plaintext DNS +- Batch inserts: buffer 1000 records, flush every 60s (reduces SQLite write contention) **Resources**: RAM 15MB, CPU 2%, disk 5MB/day typical **Dependencies**: scapy or dpkt @@ -267,7 +282,9 @@ These modules start at deployment and run continuously without generating any ne - Extract Server Name Indication field — reveals destination even when encrypted - Correlate with DNS logs for complete web activity picture - Detect certificate pinning, TLS 1.3 encrypted SNI (ESNI/ECH) gaps +- **ECH limitation**: Encrypted Client Hello (Cloudflare, Google, Firefox) returns CDN dummy SNI — no passive mitigation. When in MITM position, blocking DoH forces DNS fallback but ECH requires full TLS interception. - Log: timestamp, source IP, destination IP:port, SNI hostname, TLS version +- QUIC/HTTP3 SNI handled by separate `quic_analyzer.py` module **Resources**: RAM 10MB, CPU 2%, disk 3MB/day typical **Dependencies**: scapy or dpkt @@ -311,14 +328,15 @@ These modules start at deployment and run continuously without generating any ne - ARP table monitoring (new MACs) - DHCP request/ACK sniffing (hostname, vendor class, requested IP) +- DHCP option 55 (Parameter Request List) parsing for device fingerprinting via `data/dhcp_fingerprints.db` (Fingerbank dataset) - mDNS/Bonjour service announcements - NetBIOS name queries and responses - SSDP/UPnP discovery traffic - NBNS and LLMNR queries (hostname resolution attempts) -- Correlate: IP + MAC + hostname + vendor (OUI) + OS guess +- Correlate: IP + MAC + hostname + vendor (OUI) + OS guess + DHCP fingerprint **Resources**: RAM 15MB, CPU 2%, disk 5MB -**Dependencies**: scapy, data/oui.db +**Dependencies**: scapy, data/oui.db, data/dhcp_fingerprints.db --- @@ -514,6 +532,69 @@ These modules start at deployment and run continuously without generating any ne --- +#### `modules/passive/ldap_harvester.py` — LDAP Query Harvester + +**Purpose**: Parse LDAP search queries and responses to build a passive AD object inventory. + +- Parse LDAP SearchRequest/SearchResponse on ports 389 (LDAP) and 3268 (Global Catalog) +- Extract: base DN, search filter, requested attributes, result entries +- Build inventory: users, groups, computers, GPOs, SPNs, delegation attributes +- Detect LAPS password reads (ms-Mcs-AdmPwd attribute requests) +- Identify enumeration patterns that reveal admin tools (BloodHound, ADFind, PowerView queries) +- Feed extracted objects into topology_mapper and credential_db (service account descriptions often contain passwords) + +**Resources**: RAM 20MB, CPU 3%, disk 10MB +**Dependencies**: scapy, impacket (for LDAP parsing) + +--- + +#### `modules/passive/rdp_monitor.py` — RDP Session Monitor + +**Purpose**: Extract intelligence from RDP connection negotiation without decryption. + +- Parse RDP NLA (Network Level Authentication) negotiation headers on TCP/3389 +- Extract: username, domain, client hostname, keyboard layout, client build number +- Parse CredSSP to capture NTLM/Kerberos auth (feed to kerberos_harvester and credential_sniffer) +- Track admin-to-server session patterns: who RDPs where and when +- Identify jump boxes (hosts receiving many RDP sessions) and admin workstations (hosts initiating many) + +**Resources**: RAM 15MB, CPU 2%, disk 5MB +**Dependencies**: scapy, impacket + +--- + +#### `modules/passive/quic_analyzer.py` — QUIC/HTTP3 SNI Extractor + +**Purpose**: Extract TLS SNI from QUIC Initial packets on UDP/443, covering the 30-40% of web traffic invisible to TCP-based TLS extraction. + +- Parse QUIC Initial packets (RFC 9000) from UDP/443 traffic +- Decrypt Initial packet payload using connection ID-derived keys (standard per RFC 9001, not secret) +- Extract CRYPTO frames containing TLS ClientHello +- Parse SNI from embedded ClientHello — same format as TCP TLS +- Feed results into tls_sni_extractor's log format for unified SNI visibility + +**Resources**: RAM 10MB, CPU 2%, disk 3MB/day +**Dependencies**: scapy + +--- + +#### `modules/passive/db_interceptor.py` — Database Protocol Interceptor + +**Purpose**: Parse database wire protocols to extract login sequences, queries, and credential-containing statements. + +- **MSSQL TDS** (TCP/1433): login packets (username, hostname, app name), SQL batch queries +- **MySQL** (TCP/3306): handshake (server version, auth plugin), login, query packets +- **PostgreSQL** (TCP/5432): startup (user, database), simple/extended query protocol +- **Redis** (TCP/6379): AUTH commands, key operations (detect credential storage patterns) +- **MongoDB** (TCP/27017): OP_MSG/OP_QUERY for auth, find, and aggregate operations +- Flag credential-containing queries (`INSERT INTO users`, `SET password`, connection strings) +- Extract result metadata (row counts, column names) without storing full result sets + +**Resources**: RAM 25MB, CPU 3%, disk 10MB +**Dependencies**: scapy, impacket + +--- + ### 3.2 Active Surveillance (operator-enabled, then runs unattended) These modules require explicit operator activation. Once configured and started, they run without further interaction. @@ -842,6 +923,56 @@ These modules require explicit operator activation. Once configured and started, --- +#### `modules/intel/change_detector.py` — Network Change Detection + +**Purpose**: Continuously diff network state against baseline. Early warning system for IR activity and burn detection. + +- After baseline period, snapshot network state hourly: hosts, services, connection patterns +- Alert on: new hosts appearing, new services on existing hosts, hosts disappearing +- Alert on: security tool traffic (connections to known EDR/SIEM update domains) +- Alert on: scan activity targeting the implant's segment (port sweeps, ARP scans) +- Alert on: unusual auth patterns (new admin accounts, bulk password changes) +- Publishes CHANGE_DETECTED events on bus with severity (INFO/WARN/CRITICAL) +- Critical changes (potential IR activity, new security tools) logged for operator triage + +**Resources**: RAM 15MB, CPU 2%, disk 5MB +**Dependencies**: sqlite3 (stdlib) + +--- + +#### `modules/intel/security_posture.py` — Security Posture Mapper + +**Purpose**: Passively map the target's defensive infrastructure. Know what you're up against before going active. + +- Detect EDR update traffic: CrowdStrike (ts01-b.cloudsink.net), SentinelOne, Carbon Black, Defender ATP +- Detect SIEM log forwarding: syslog to collectors, Splunk HEC (TCP/8088), Wazuh agent traffic +- Detect vulnerability scanners: Nessus, Qualys, Rapid7 scan patterns +- Detect honeypots: Thinkst Canary traffic patterns, HoneyComb, T-Pot signatures +- Detect network taps: SPAN port indicators, packet broker traffic (Gigamon, Keysight) +- Detect NAC infrastructure: 802.1X RADIUS, Forescout, ISE traffic patterns +- Output: defense inventory with confidence scores, gates active module risk assessment + +**Resources**: RAM 10MB, CPU 2%, disk 5MB +**Dependencies**: scapy + +--- + +#### `modules/intel/operator_audit.py` — Operator Audit Trail + +**Purpose**: Log operator SSH sessions and commands to encrypted storage for engagement reporting and legal protection. + +- Hook via PROMPT_COMMAND to capture shell commands when operator SSHes in +- Log: timestamp, SSH session ID, username, command, working directory +- Log BigBrother CLI invocations with arguments +- All audit data written to LUKS-encrypted `storage/audit/` — never to system logs +- Tamper-evident: append-only log with HMAC chain +- Export: timeline format for engagement reports and deconfliction + +**Resources**: RAM 5MB, CPU 0.5%, disk varies +**Dependencies**: sqlite3 (stdlib) + +--- + ## 4. Connectivity ### `modules/connectivity/tailscale.py` — Tailscale (Primary) @@ -884,7 +1015,9 @@ These modules require explicit operator activation. Once configured and started, - EAP/EAPOL passthrough for 802.1X environments - All traffic passes through — available for passive capture - Clone victim MAC for implant's own traffic -- Failsafe: if bridge fails, fall back to passive tap (promiscuous without bridge) +- Disable STP on bridge, suppress BPDU frame emission via ebtables +- Filter CDP/LLDP emission from bridge interfaces (receive only, never transmit) +- Failsafe: lightweight C watchdog checks bridge forwarding every 5s, direct passthrough if down >10s **Resources**: RAM 10MB, CPU 2% **Dependencies**: bridge-utils, ebtables, scripts/setup_bridge.sh @@ -914,10 +1047,10 @@ These modules require explicit operator activation. Once configured and started, - Operator connects: ssh -J jumphost -p tunnel_port implant - Dynamic port forwarding (SOCKS proxy) option - Multiple tunnel endpoints for redundancy -- Disguise: SSH over port 443 looks like HTTPS +- SSH-over-WebSocket or SSH tunneled inside TLS (stunnel/ncat --ssl) — never raw SSH on 443 (DPI detects SSH banner on non-SSH ports) **Resources**: RAM 15MB, CPU 1% -**Dependencies**: autossh, openssh-client +**Dependencies**: autossh, openssh-client, stunnel4 or ncat --- @@ -982,11 +1115,13 @@ These modules require explicit operator activation. Once configured and started, ### `modules/stealth/encrypted_storage.py` — LUKS Encrypted Storage -- LUKS container for all sensitive data (pcaps, creds, logs) -- Operator-provided passphrase at deployment -- LUKS header destruction = instant data unrecoverability -- Optional: network-derived key component (C2 beacon value required to unlock) -- If physically seized without key: encrypted data is unrecoverable +- LUKS container for all sensitive data (pcaps, creds, logs, sensitive config) +- Boot-unlock via network-derived key: fetch value from C2 server, combine with device CPU serial via HKDF +- If C2 unreachable on boot: collect to tmpfs until operator reconnects, then flush to LUKS +- ALL config with sensitive data (WG keys, Tailscale auth, engagement name) stored inside LUKS at `storage/config/` +- Only `config/bigbrother.yaml` with non-sensitive defaults remains on plaintext filesystem +- LUKS header destruction = instant data unrecoverability (config, creds, pcaps — everything) +- If physically seized without C2 access + device serial: encrypted data is unrecoverable --- @@ -1077,8 +1212,13 @@ These are installed by `setup.sh`. The operator runs them directly via SSH. BigB | **BloodHound.py** | AD data collection (Python ingestor) | | **Responder** | LLMNR/NBT-NS/mDNS poisoning (also managed by BB for unattended mode) | | **CrackMapExec / NetExec** | Network authentication testing, enumeration, command execution | +| **Coercer** | All coercion methods (PetitPotam, PrinterBug, DFSCoerce, ShadowCoerce) | +| **PetitPotam.py** | Standalone MS-EFSRPC coercion (backup for Coercer) | | **Chisel** | TCP/UDP tunneling over HTTP, SOCKS proxy | | **Ligolo-ng** | Tunneling/pivoting (agent on target, proxy on implant) | +| **proxychains-ng** | Proxy chain routing for tool traffic | +| **socat** | Multipurpose relay (TCP/UDP/Unix sockets) | +| **sshuttle** | Transparent SSH-based VPN/pivot | | **mitm6** | IPv6 MITM with WPAD abuse | | **Bettercap** | Network attack and monitoring (ARP, DNS, WiFi, BLE) | | **tcpdump** | Packet capture CLI | @@ -1091,6 +1231,10 @@ These are installed by `setup.sh`. The operator runs them directly via SSH. BigB | **evil-winrm** | WinRM shell with upload/download | | **enum4linux-ng** | SMB/NetBIOS enumeration | | **kerbrute** | Kerberos brute-force / user enumeration | +| **pypykatz** | Mimikatz in Python (LSASS, DPAPI, registry) | +| **ldapdomaindump** | Fast AD enumeration after first credential | +| **smbmap** | SMB share enumeration and access | +| **ROADtools** | Azure/Entra ID recon (Pi 4 and Debian host only) | --- @@ -1110,6 +1254,7 @@ Click Commands: kill — Execute kill switch (manual wipe) creds — Query credential database intel — Generate intelligence report + triage — Delta view since last check-in (new creds, hosts, anomalies, errors) timeline — Show per-user activity timeline topology — Generate network topology map baseline — Run 48h traffic baseline capture @@ -1130,12 +1275,25 @@ Interactive Menu (Rich-based): ### `core/engine.py` — Module Lifecycle Manager -- Discover, load, start, stop, and monitor all modules +- **Multiprocess model**: each module runs as a separate process — one crash does not kill capture or other modules +- Discover, load, start, stop, and monitor all modules via process supervision - Dependency resolution: modules declare dependencies, engine starts in order - Resource budgeting: check remaining RAM/CPU before starting module -- Hardware tier enforcement: Pi Zero 2W gets hard module limits +- Hardware tier enforcement: Pi Zero 2W gets hard module limits (4 passive max) +- Interface conflict detection: prevents two modules from claiming the same interface in incompatible modes (e.g., monitor mode vs managed mode on wlan0) - Graceful degradation: if module fails, others continue -- Thread safety: all state access through locks +- Optional scope enforcement: when `config/scope.yaml` is loaded, active modules validate targets against in-scope IP ranges/hostnames/domains before acting + +### `core/capture_bus.py` — Packet Capture Bus + +Single privileged AF_PACKET socket captures all traffic, demultiplexes to per-module queues by protocol/port. Reduces kernel socket overhead from N modules to 1. + +- One capture process with CAP_NET_RAW opens promiscuous socket on bridge/tap interface +- Modules subscribe to packet queues by BPF filter expression (e.g., "tcp port 389" for ldap_harvester) +- Packets dispatched to per-module multiprocessing queues via shared memory +- Module crash does not affect capture process or other modules +- Queue backpressure: if a module falls behind, oldest packets dropped from its queue (not others) +- Stats: per-module packet count, queue depth, drop count ### `core/bus.py` — Internal Event Bus @@ -1147,11 +1305,12 @@ 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 ``` ### `core/state.py` — Persistent State -SQLite with WAL mode. Stores module states, discovered hosts, running configuration. Survives reboots. +Single SQLite database with schema-separated tables (not multiple DB files). WAL mode with dedicated async writer thread — all modules submit writes to a queue, writer batches with 500ms coalesce window. PRAGMA synchronous=NORMAL, busy_timeout=30s. WAL files on tmpfs with periodic checkpoint to SD card (accept up to 30 minutes data loss on power failure for SD longevity). Stores module states, discovered hosts, running configuration. Survives reboots. ### `core/scheduler.py` — Task Scheduler @@ -1159,7 +1318,7 @@ Cron-like scheduler with jitter support. Used for: PCAP rotation, periodic healt ### `core/resource_monitor.py` — Resource Monitor -Tracks per-module RAM/CPU/disk. Enforces hardware tier limits. Kills lowest-priority module on OOM. Alerts on disk space threshold. +Tracks per-module RAM/CPU/disk. Enforces hardware tier limits. Kills lowest-priority module on OOM. Alerts on disk space threshold. Reads `/sys/class/thermal/thermal_zone0/temp` every 30s — publishes THERMAL_WARNING at 55C, sheds non-essential modules at 70C (Pi Zero throttles at 60C, Pi 4 at 80C). ### `core/kill_switch.py` — Kill Switch @@ -1210,14 +1369,22 @@ mitmproxy (Pi 4+ only) ``` Responder (git clone), CrackMapExec/NetExec (pipx), Chisel (binary), Ligolo-ng (binary), mitm6 (pipx), evil-winrm, enum4linux-ng (pipx), -kerbrute (binary) +kerbrute (binary), Coercer (pipx), PetitPotam.py (git clone), +pypykatz (pipx), ldapdomaindump (pipx), smbmap (pipx), +ROADtools (pipx, Pi 4+ only) +``` + +**System packages (additional):** + +``` +proxychains-ng socat sshuttle ``` **Kernel config:** IP forwarding (v4+v6), no send_redirects. **Pi optimizations:** gpu_mem=16, disable bluetooth/avahi, no swap. -**Directories:** `storage/{pcaps,creds,dns_logs,sni_logs,emails,files,voip,print_jobs,intel,baseline,logs}` with mode 700. +**Directories:** `storage/{config,pcaps,creds,dns_logs,sni_logs,emails,files,voip,print_jobs,intel,baseline,audit,logs}` with mode 700. ### Systemd Services @@ -1242,13 +1409,11 @@ Resource limits via systemd: ## 9. Configuration -### `config/bigbrother.yaml` — Master Config +### `config/bigbrother.yaml` — Master Config (Plaintext FS) + +Contains ONLY non-sensitive defaults. All keys, auth tokens, and engagement-identifying data live in `storage/config/` inside the LUKS container. ```yaml -engagement: - name: "op-example" - client: "" - device: platform: "auto" # auto | pi_zero | pi4 | generic hostname: "iot-sensor-03" @@ -1262,8 +1427,6 @@ network: external: "eth1" wifi: interface: "wlan0" - client_ssid: "" - client_passphrase: "" cellular: enabled: false modem_device: "/dev/ttyUSB0" @@ -1276,21 +1439,8 @@ connectivity: - wireguard - reverse_tunnel - cellular_backup - tailscale: - auth_key: "" - hostname: "iot-sensor-03" - wireguard: - private_key: "" - peer_public_key: "" - endpoint: "" - allowed_ips: "10.100.0.0/24" - reverse_tunnel: - server: "" - port: 443 - key_path: "" security: - kill_passphrase_hash: "" encryption_key_derive: "argon2id" # argon2id | pbkdf2 (Pi Zero) dead_man_switch: enabled: false @@ -1300,10 +1450,11 @@ security: capture: pcap_rotation_mb: 100 pcap_rotation_hours: 1 + pcap_compression: "zstd" # zstd compression on rotation (local CPU, zero network signature) snap_length: "auto" # auto (by hardware tier) | 96 | 65535 bpf_filter: "full_capture" # full_capture | credentials | dns | custom custom_bpf: "" - disk_max_pct: 80 # Purge oldest PCAPs above this + disk_max_pct: 85 # Purge oldest PCAPs above this (128GB+ gives headroom) operating_hours: enabled: false @@ -1317,6 +1468,35 @@ baseline: auto_start: true ``` +### `storage/config/` — Sensitive Config (Inside LUKS) + +Created at deployment, populated before first network connection. Destroyed with LUKS header. + +```yaml +# storage/config/engagement.yaml +engagement: + name: "op-example" + client: "" + +# storage/config/connectivity.yaml +tailscale: + auth_key: "tskey-..." + hostname: "iot-sensor-03" +wireguard: + private_key: "" + peer_public_key: "" + endpoint: "" + allowed_ips: "10.100.0.0/24" +reverse_tunnel: + server: "" + port: 443 + key_path: "" +wifi: + client_ssid: "" + client_passphrase: "" +kill_passphrase_hash: "" +``` + ### `config/modules.yaml` — Module Configuration All passive modules default to `enabled: true, autostart: true` (except `wireless_intel` which requires a monitor mode adapter). All active modules default to `enabled: false` and require operator activation. @@ -1355,17 +1535,41 @@ active: attack: "smb" # smb | ldap | ldaps | http | adcs ``` +### `config/scope.yaml` — Optional Scope Enforcement + +Not mandatory. When loaded, active modules validate targets before acting. Operator's choice to use it. + +```yaml +# scope.yaml — optional, loaded via `bigbrother.py config --scope scope.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 + - subsidiary.local +exclude: + - 10.10.99.0/24 # OT segment — do not touch +``` + +When enabled: ARP spoof validates each target IP, DHCP spoof only responds to in-scope MACs, dns_poison only redirects in-scope domains. Passive modules are never scope-restricted — they observe everything. + --- ## 10. Hardware Tiers +**Minimum SD card**: 128GB (high-endurance industrial). Provides ample PCAP storage with zstd compression on rotation. + | Capability | Pi Zero 2W (512MB) | Pi 4 (4GB) | Debian Host | |---|:---:|:---:|:---:| -| **Max passive modules** | 6 | All 18 | All 18 | +| **Max passive modules** | 4 | All 22 | All 22 | | **Max active modules** | 1 | 6 | Unlimited | | **Snap length** | 96 bytes | 65535 | 65535 | | **Flow table max** | 5,000 | 50,000 | 100,000 | -| **Compression** | zlib | lzma | lzma | +| **PCAP compression** | zstd | zstd | zstd | | **Key derivation** | pbkdf2 | argon2id | argon2id | | **mitmproxy** | No | Yes | Yes | | **file_extractor** | No | Yes | Yes | @@ -1374,29 +1578,29 @@ active: | **Cellular modem** | No (power) | Yes | Yes | | **BLE** | Yes | Yes | Adapter needed | | **overlayfs** | Yes (30MB) | Yes (200MB) | N/A | +| **ROADtools** | No | Yes | Yes | ### Pi Zero 2W Memory Budget (Passive Mode) +Python 3 + scapy + impacket + cryptography runs 60-80MB for the interpreter, not 25MB. Budget corrected accordingly. Only 4 passive modules on Pi Zero. + | Component | RAM (MB) | |---|---| | OS + kernel | ~110 | -| Python interpreter | ~25 | -| Core framework | ~15 | +| Python interpreter + libs | ~70 | +| Core framework + capture_bus | ~20 | | packet_capture (96B snap) | ~30 | | dns_logger | ~15 | -| tls_sni_extractor | ~10 | | credential_sniffer | ~20 | -| kerberos_harvester | ~15 | | host_discovery | ~15 | -| os_fingerprint | ~10 | | stealth modules | ~20 | | encrypted_storage | ~10 | | overlayfs overhead | ~30 | | connectivity | ~25 | -| **TOTAL** | **~350** | -| **Headroom** | **~50** | +| **TOTAL** | **~365** | +| **Headroom** | **~35** | -Active module on Pi Zero takes from headroom. Only one active module at a time. +Active module on Pi Zero takes from headroom. Only one active module at a time. Modules like tls_sni_extractor, os_fingerprint, traffic_analyzer, and the new passive modules (ldap_harvester, rdp_monitor, quic_analyzer, db_interceptor) require Pi 4 or Debian host. --- @@ -1404,44 +1608,53 @@ Active module on Pi Zero takes from headroom. Only one active module at a time. ### Phase 1: Foundation + Stealth (Weeks 1-2) -Core infrastructure, module lifecycle, stealth layer. OPSEC before any network activity. +Core infrastructure, multiprocess module lifecycle, capture bus, stealth layer. OPSEC before any network activity. ``` Files: -- bigbrother.py (CLI skeleton, Click groups, basic menu) -- core/ (engine, bus, state, scheduler, resource_monitor, kill_switch) +- bigbrother.py (CLI skeleton, Click groups, basic menu, triage command) +- core/ (engine, capture_bus, bus, state, scheduler, resource_monitor, kill_switch) - modules/base.py - modules/stealth/ (all 12 modules) - utils/ (all 7 utility modules) -- config/ (bigbrother.yaml, modules.yaml, stealth.yaml, hardware_tiers.yaml) +- config/ (bigbrother.yaml, modules.yaml, stealth.yaml, hardware_tiers.yaml, scope.yaml) - services/ (all systemd units) -- setup.sh (core packages, tool installation) +- setup.sh (core packages, tool installation incl. Coercer, proxychains-ng, etc.) +- data/dhcp_fingerprints.db - tests/ (engine, bus, crypto, resource) -Validation: Module lifecycle works. Encrypted storage. Process disguised. -Kill switch wipes all data. Watchdog restarts crashed module. Overlayfs on Pi. -Hardware tier detection accurate. +Validation: Module lifecycle works (multiprocess). Capture bus demuxes packets. +Encrypted storage with LUKS network-derived unlock. Sensitive config inside LUKS. +Process disguised. Kill switch wipes all data. Watchdog restarts crashed module. +Overlayfs on Pi. Hardware tier detection accurate. Thermal monitoring active. +SQLite single-DB with async writer. Interface conflict detection works. ``` -### Phase 2: Passive Surveillance (Weeks 3-4) +### Phase 2: Passive Surveillance (Weeks 3-5) -All 18 passive modules. Zero network noise. 24/7 unsupervised collection. +All 22 passive modules. Zero network noise. 24/7 unsupervised collection. ``` Files: -- modules/passive/ (all 18 modules) -- modules/intel/ (credential_db, topology_mapper, user_timeline) -- data/ (oui.db, os_sigs.db, bpf_filters/) +- modules/passive/ (all 22 modules incl. ldap_harvester, rdp_monitor, + quic_analyzer, db_interceptor) +- modules/intel/ (credential_db, topology_mapper, user_timeline, + change_detector, security_posture, operator_audit) +- data/ (oui.db, os_sigs.db, dhcp_fingerprints.db, bpf_filters/) -Validation: All hosts discovered. Credentials captured from test services. -DNS queries logged per host. TLS SNI extracted. Kerberos tickets harvested. +Validation: All hosts discovered (with DHCP fingerprinting). Credentials +captured from test services. DNS queries logged per host (DoH hosts flagged). +TLS SNI extracted (TCP + QUIC). LDAP queries parsed, AD objects inventoried. +RDP sessions tracked. Database queries intercepted. Kerberos tickets harvested. Email captured from cleartext SMTP. SMB file access logged. VoIP metadata -captured. Print jobs intercepted. Network map generated. Zero IDS alerts. +captured. Print jobs intercepted. Network map generated. Change detection +operational. Security posture mapped. Operator audit trail logging. +Zero IDS alerts. ``` -### Phase 3: Connectivity + Baseline (Weeks 5-6) +### Phase 3: Connectivity + Baseline (Weeks 6-7) -All connectivity modules. Traffic baseline capture. Reliable operator access. +All connectivity modules. Bridge hardening (STP/CDP suppression, watchdog failsafe). Traffic baseline capture. Reliable operator access. ``` Files: @@ -1450,13 +1663,14 @@ Files: - scripts/setup_bridge.sh, teardown_bridge.sh Validation: Failover chain works: Tailscale > WireGuard > SSH > Cellular. -Bridge transparent. WiFi client connected. 48h baseline captured. +Bridge transparent with STP/BPDU/CDP/LLDP suppression. C watchdog failsafe +triggers passthrough in <15s. WiFi client connected. 48h baseline captured. BLE emergency access functional. ``` -### Phase 4: Active Surveillance (Weeks 7-8) +### Phase 4: Active Surveillance (Weeks 8-9) -All 14 active modules. MITM capabilities. Credential harvesting at scale. +All 14 active modules. MITM capabilities. Credential harvesting at scale. Scope enforcement integration. ``` Files: @@ -1464,26 +1678,31 @@ Files: - modules/intel/ (report_generator, net_intel, supply_chain_detect) - templates/ (captive_portals, dns_zones, hostapd, responder, beef) -Validation: ARP spoof + HTTP logging chain works. DNS poisoning redirects. -Evil twin captures credentials. Responder captures NTLMv2 hashes. -ntlmrelayx relays to ADCS. mitmproxy decrypts HTTPS. File extraction -from traffic. JS injection into HTTP. Session tokens captured. +Validation: ARP spoof + HTTP logging chain works (scope-validated when enabled). +DNS poisoning redirects. DHCP spoof respects scope. Evil twin captures credentials. +Responder captures NTLMv2 hashes. ntlmrelayx relays to ADCS (Coercer integration +tested). mitmproxy decrypts HTTPS. File extraction from traffic. JS injection +into HTTP. Session tokens captured. DoH blocking forces plaintext DNS when in MITM. ``` -### Phase 5: Polish + Hardening (Weeks 9-10) +### Phase 5: Polish + Hardening (Weeks 10-12) -Integration testing, Pi Zero optimization, soak testing, TUI polish. +Integration testing, Pi Zero optimization (4-module limit), soak testing, TUI polish. ``` Tasks: -- Full integration test on Pi Zero 2W, Pi 4, Debian -- 72-hour soak test (memory leaks, disk usage, stability) -- Pi Zero performance optimization pass -- Rich TUI interactive menu polish -- setup.sh validation on clean OS images +- Full integration test on Pi Zero 2W (4 passive modules), Pi 4 (all 22), Debian +- 72-hour soak test (memory leaks, disk usage, thermal, stability) +- Pi Zero performance optimization pass (verify 365MB budget, thermal under 55C) +- Capture bus stress test (packet throughput, queue backpressure) +- SQLite contention test (22 modules writing concurrently) +- LUKS network-derived unlock test (C2 reachable and unreachable scenarios) +- Rich TUI interactive menu polish (triage command) +- setup.sh validation on clean OS images (all new tools install correctly) - Crypto implementation review - LKM rootkit compile and test on target kernels - IDS tester validation against current rulesets +- zstd PCAP compression verification on 128GB storage - Error handling audit ``` @@ -1498,7 +1717,7 @@ Tasks: 3. **Hostname** — Generic IoT name. Never "kali", "attack", "pentest". 4. **SSH keys** — Fresh per engagement. Neutral key comment. 5. **Tailscale** — Per-engagement auth key. Hostname matches device disguise. -6. **SD card** — High-endurance industrial card. Enable overlayfs. +6. **SD card** — 128GB minimum, high-endurance industrial card. Enable overlayfs. 7. **Pre-bundle everything** — All tools, databases, signatures installed before deployment. Zero package installs on target network. 8. **Test kill switch** — Verify wipe works before deploying in the field. @@ -1538,6 +1757,6 @@ Tasks: 31. **Bridge mode** — No IP, no MAC on network. Physical inspection only detection. 32. **Tailscale** — Looks like HTTPS to Derp servers. 33. **WireGuard** — Encrypted UDP on single port. Looks like noise. -34. **Reverse SSH** — Over port 443 looks like HTTPS. +34. **Reverse SSH** — Must be SSH-over-WebSocket or SSH tunneled inside TLS (stunnel/ncat --ssl). Never raw SSH on 443 — DPI detects SSH banner. 35. **Cellular** — Completely out-of-band. Bypasses target network entirely. 36. **DNS tunneling** — Low rate, randomized, multiple domains.