n0mad1k/bigbrother
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v3.1: Incorporate security tribe review findings into design doc

Browse Source 
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.
This commit is contained in:
n0mad1k
2026-03-17 10:57:51 -04:00
parent 7915ef17de
commit d3d1deb99c
1 changed files with 310 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BIGBROTHER_DESIGN.md
+310 -91
View File
@@ -1,6 +1,6 @@
# BigBrother: Total Network Surveillance Platform + Operator Jump Box # BigBrother: Total Network Surveillance Platform + Operator Jump Box
> **Version**: 3.0 > **Version**: 3.1
> **Date**: 2026-03-17 > **Date**: 2026-03-17
> **Status**: Implementation Blueprint > **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. 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 ├── .gitignore
│ │
├── config/ ├── config/
│ ├── bigbrother.yaml # Master config (engagement, device, network) │ ├── bigbrother.yaml # Non-sensitive defaults only (plaintext FS)
│ ├── modules.yaml # Per-module enable/disable + params │ ├── modules.yaml # Per-module enable/disable + params
│ ├── stealth.yaml # OPSEC/stealth profile config │ ├── stealth.yaml # OPSEC/stealth profile config
│ ├── hardware_tiers.yaml # Pi Zero 2W vs Pi 4 vs Debian host limits │ ├── hardware_tiers.yaml # Pi Zero 2W vs Pi 4 vs Debian host limits
│ ├── scope.yaml # Optional scope enforcement (IP ranges, domains)
│ └── templates/ │ └── templates/
│ ├── engagement_default.yaml # Template for new engagements │ ├── engagement_default.yaml # Template for new engagements
│ ├── engagement_minimal.yaml # Minimal config for Pi Zero 2W │ ├── 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/ ├── core/
│ ├── __init__.py │ ├── __init__.py
│ ├── engine.py # Module lifecycle manager (load, start, stop, status) │ ├── 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) │ ├── scheduler.py # Task scheduler (cron-like, jitter-aware)
│ ├── bus.py # Internal event bus (pub/sub between modules) │ ├── bus.py # Internal event bus (pub/sub between modules)
│ ├── state.py # Persistent state manager (SQLite) │ ├── 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 │ └── kill_switch.py # Manual wipe orchestrator
│ │
├── modules/ ├── 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 │ │ ├── wireless_intel.py # Probe requests, BLE scanning, WPA handshakes, WIDS
│ │ ├── protocol_analyzer.py # Zeek-style protocol dissection, service ID, cert analysis │ │ ├── protocol_analyzer.py # Zeek-style protocol dissection, service ID, cert analysis
│ │ ├── cloud_token_harvester.py # Passive AWS keys, Azure tokens, JWT, OAuth, SAML │ │ ├── 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 │ ├── active/ # Operator-enabled, then runs unattended
│ │ ├── __init__.py │ │ ├── __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 │ ├── report_generator.py # Engagement summary, timeline, findings
│ ├── net_intel.py # Beacon detection, communication graphing │ ├── net_intel.py # Beacon detection, communication graphing
│ ├── user_timeline.py # Per-user activity timeline (DNS + auth + traffic) │ ├── 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/ ├── services/
│ ├── bigbrother-core.service # Main daemon (disguised name in production) │ ├── 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/ ├── data/
│ ├── oui.db # MAC OUI database (SQLite, compressed) │ ├── oui.db # MAC OUI database (SQLite, compressed)
│ ├── os_sigs.db # Passive OS fingerprint signatures │ ├── 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 │ ├── ids_rules/ # Snort/Suricata rule snapshots for self-testing
│ │ ├── emerging-threats.rules │ │ ├── emerging-threats.rules
│ │ └── snort-community.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 │ ├── teardown_bridge.sh # Bridge interface teardown
│ └── build_lkm.sh # Compile rootkit LKM for target kernel │ └── build_lkm.sh # Compile rootkit LKM for target kernel
│ │
└── storage/ # Runtime data (gitignored, encrypted) └── storage/ # Runtime data (gitignored, LUKS-encrypted)
├── pcaps/ # Rotated packet captures ├── config/ # Sensitive config (keys, auth, engagement details)
├── pcaps/ # Rotated packet captures (zstd compressed)
├── creds/ # Extracted credentials ├── creds/ # Extracted credentials
├── dns_logs/ # DNS query logs per host ├── dns_logs/ # DNS query logs per host
├── sni_logs/ # TLS SNI destination logs ├── 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 ├── print_jobs/ # Intercepted print spool data
├── intel/ # Analysis outputs, topology graphs ├── intel/ # Analysis outputs, topology graphs
├── baseline/ # Traffic baseline data (48h capture) ├── baseline/ # Traffic baseline data (48h capture)
├── audit/ # Operator session/command audit trail
└── logs/ # Encrypted operation logs └── 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) ### 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 - Aggregate into browsing profiles per host
- Detect internal DNS servers, split-horizon configurations - Detect internal DNS servers, split-horizon configurations
- Flag interesting domains: cloud services, security tools, update servers, webmail - 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 **Resources**: RAM 15MB, CPU 2%, disk 5MB/day typical
**Dependencies**: scapy or dpkt **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 - Extract Server Name Indication field — reveals destination even when encrypted
- Correlate with DNS logs for complete web activity picture - Correlate with DNS logs for complete web activity picture
- Detect certificate pinning, TLS 1.3 encrypted SNI (ESNI/ECH) gaps - 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 - 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 **Resources**: RAM 10MB, CPU 2%, disk 3MB/day typical
**Dependencies**: scapy or dpkt **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) - ARP table monitoring (new MACs)
- DHCP request/ACK sniffing (hostname, vendor class, requested IP) - 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 - mDNS/Bonjour service announcements
- NetBIOS name queries and responses - NetBIOS name queries and responses
- SSDP/UPnP discovery traffic - SSDP/UPnP discovery traffic
- NBNS and LLMNR queries (hostname resolution attempts) - 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 **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) ### 3.2 Active Surveillance (operator-enabled, then runs unattended)
These modules require explicit operator activation. Once configured and started, they run without further interaction. 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 ## 4. Connectivity
### `modules/connectivity/tailscale.py` — Tailscale (Primary) ### `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 - EAP/EAPOL passthrough for 802.1X environments
- All traffic passes through — available for passive capture - All traffic passes through — available for passive capture
- Clone victim MAC for implant's own traffic - 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% **Resources**: RAM 10MB, CPU 2%
**Dependencies**: bridge-utils, ebtables, scripts/setup_bridge.sh **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 - Operator connects: ssh -J jumphost -p tunnel_port implant
- Dynamic port forwarding (SOCKS proxy) option - Dynamic port forwarding (SOCKS proxy) option
- Multiple tunnel endpoints for redundancy - 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% **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 ### `modules/stealth/encrypted_storage.py` — LUKS Encrypted Storage
- LUKS container for all sensitive data (pcaps, creds, logs) - LUKS container for all sensitive data (pcaps, creds, logs, sensitive config)
- Operator-provided passphrase at deployment - Boot-unlock via network-derived key: fetch value from C2 server, combine with device CPU serial via HKDF
- LUKS header destruction = instant data unrecoverability - If C2 unreachable on boot: collect to tmpfs until operator reconnects, then flush to LUKS
- Optional: network-derived key component (C2 beacon value required to unlock) - ALL config with sensitive data (WG keys, Tailscale auth, engagement name) stored inside LUKS at `storage/config/`
- If physically seized without key: encrypted data is unrecoverable - 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) | | **BloodHound.py** | AD data collection (Python ingestor) |
| **Responder** | LLMNR/NBT-NS/mDNS poisoning (also managed by BB for unattended mode) | | **Responder** | LLMNR/NBT-NS/mDNS poisoning (also managed by BB for unattended mode) |
| **CrackMapExec / NetExec** | Network authentication testing, enumeration, command execution | | **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 | | **Chisel** | TCP/UDP tunneling over HTTP, SOCKS proxy |
| **Ligolo-ng** | Tunneling/pivoting (agent on target, proxy on implant) | | **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 | | **mitm6** | IPv6 MITM with WPAD abuse |
| **Bettercap** | Network attack and monitoring (ARP, DNS, WiFi, BLE) | | **Bettercap** | Network attack and monitoring (ARP, DNS, WiFi, BLE) |
| **tcpdump** | Packet capture CLI | | **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 | | **evil-winrm** | WinRM shell with upload/download |
| **enum4linux-ng** | SMB/NetBIOS enumeration | | **enum4linux-ng** | SMB/NetBIOS enumeration |
| **kerbrute** | Kerberos brute-force / user 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) kill — Execute kill switch (manual wipe)
creds — Query credential database creds — Query credential database
intel — Generate intelligence report intel — Generate intelligence report
triage — Delta view since last check-in (new creds, hosts, anomalies, errors)
timeline — Show per-user activity timeline timeline — Show per-user activity timeline
topology — Generate network topology map topology — Generate network topology map
baseline — Run 48h traffic baseline capture baseline — Run 48h traffic baseline capture
@@ -1130,12 +1275,25 @@ Interactive Menu (Rich-based):
### `core/engine.py` — Module Lifecycle Manager ### `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 - Dependency resolution: modules declare dependencies, engine starts in order
- Resource budgeting: check remaining RAM/CPU before starting module - 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 - 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 ### `core/bus.py` — Internal Event Bus
@@ -1147,11 +1305,12 @@ MODULE_STARTED MODULE_STOPPED MODULE_ERROR
RESOURCE_WARNING RESOURCE_CRITICAL KILL_SWITCH RESOURCE_WARNING RESOURCE_CRITICAL KILL_SWITCH
CONNECTIVITY_CHANGED VLAN_DETECTED HANDSHAKE_CAPTURED CONNECTIVITY_CHANGED VLAN_DETECTED HANDSHAKE_CAPTURED
TICKET_HARVESTED CLOUD_TOKEN_FOUND BEACON_DETECTED TICKET_HARVESTED CLOUD_TOKEN_FOUND BEACON_DETECTED
CHANGE_DETECTED THERMAL_WARNING SCOPE_VIOLATION
``` ```
### `core/state.py` — Persistent State ### `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 ### `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 ### `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 ### `core/kill_switch.py` — Kill Switch
@@ -1210,14 +1369,22 @@ mitmproxy (Pi 4+ only)
``` ```
Responder (git clone), CrackMapExec/NetExec (pipx), Chisel (binary), Responder (git clone), CrackMapExec/NetExec (pipx), Chisel (binary),
Ligolo-ng (binary), mitm6 (pipx), evil-winrm, enum4linux-ng (pipx), 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. **Kernel config:** IP forwarding (v4+v6), no send_redirects.
**Pi optimizations:** gpu_mem=16, disable bluetooth/avahi, no swap. **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 ### Systemd Services
@@ -1242,13 +1409,11 @@ Resource limits via systemd:
## 9. Configuration ## 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 ```yaml
engagement:
name: "op-example"
client: ""
device: device:
platform: "auto" # auto | pi_zero | pi4 | generic platform: "auto" # auto | pi_zero | pi4 | generic
hostname: "iot-sensor-03" hostname: "iot-sensor-03"
@@ -1262,8 +1427,6 @@ network:
external: "eth1" external: "eth1"
wifi: wifi:
interface: "wlan0" interface: "wlan0"
client_ssid: ""
client_passphrase: ""
cellular: cellular:
enabled: false enabled: false
modem_device: "/dev/ttyUSB0" modem_device: "/dev/ttyUSB0"
@@ -1276,21 +1439,8 @@ connectivity:
- wireguard - wireguard
- reverse_tunnel - reverse_tunnel
- cellular_backup - 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: security:
kill_passphrase_hash: ""
encryption_key_derive: "argon2id" # argon2id | pbkdf2 (Pi Zero) encryption_key_derive: "argon2id" # argon2id | pbkdf2 (Pi Zero)
dead_man_switch: dead_man_switch:
enabled: false enabled: false
@@ -1300,10 +1450,11 @@ security:
capture: capture:
pcap_rotation_mb: 100 pcap_rotation_mb: 100
pcap_rotation_hours: 1 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 snap_length: "auto" # auto (by hardware tier) | 96 | 65535
bpf_filter: "full_capture" # full_capture | credentials | dns | custom bpf_filter: "full_capture" # full_capture | credentials | dns | custom
custom_bpf: "" 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: operating_hours:
enabled: false enabled: false
@@ -1317,6 +1468,35 @@ baseline:
auto_start: true 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 ### `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. 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 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 ## 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 | | 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 | | **Max active modules** | 1 | 6 | Unlimited |
| **Snap length** | 96 bytes | 65535 | 65535 | | **Snap length** | 96 bytes | 65535 | 65535 |
| **Flow table max** | 5,000 | 50,000 | 100,000 | | **Flow table max** | 5,000 | 50,000 | 100,000 |
| **Compression** | zlib | lzma | lzma | | **PCAP compression** | zstd | zstd | zstd |
| **Key derivation** | pbkdf2 | argon2id | argon2id | | **Key derivation** | pbkdf2 | argon2id | argon2id |
| **mitmproxy** | No | Yes | Yes | | **mitmproxy** | No | Yes | Yes |
| **file_extractor** | No | Yes | Yes | | **file_extractor** | No | Yes | Yes |
@@ -1374,29 +1578,29 @@ active:
| **Cellular modem** | No (power) | Yes | Yes | | **Cellular modem** | No (power) | Yes | Yes |
| **BLE** | Yes | Yes | Adapter needed | | **BLE** | Yes | Yes | Adapter needed |
| **overlayfs** | Yes (30MB) | Yes (200MB) | N/A | | **overlayfs** | Yes (30MB) | Yes (200MB) | N/A |
| **ROADtools** | No | Yes | Yes |
### Pi Zero 2W Memory Budget (Passive Mode) ### 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) | | Component | RAM (MB) |
|---|---| |---|---|
| OS + kernel | ~110 | | OS + kernel | ~110 |
| Python interpreter | ~25 | | Python interpreter + libs | ~70 |
| Core framework | ~15 | | Core framework + capture_bus | ~20 |
| packet_capture (96B snap) | ~30 | | packet_capture (96B snap) | ~30 |
| dns_logger | ~15 | | dns_logger | ~15 |
| tls_sni_extractor | ~10 |
| credential_sniffer | ~20 | | credential_sniffer | ~20 |
| kerberos_harvester | ~15 |
| host_discovery | ~15 | | host_discovery | ~15 |
| os_fingerprint | ~10 |
| stealth modules | ~20 | | stealth modules | ~20 |
| encrypted_storage | ~10 | | encrypted_storage | ~10 |
| overlayfs overhead | ~30 | | overlayfs overhead | ~30 |
| connectivity | ~25 | | connectivity | ~25 |
| **TOTAL** | **~350** | | **TOTAL** | **~365** |
| **Headroom** | **~50** | | **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) ### 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: Files:
- bigbrother.py (CLI skeleton, Click groups, basic menu) - bigbrother.py (CLI skeleton, Click groups, basic menu, triage command)
- core/ (engine, bus, state, scheduler, resource_monitor, kill_switch) - core/ (engine, capture_bus, bus, state, scheduler, resource_monitor, kill_switch)
- modules/base.py - modules/base.py
- modules/stealth/ (all 12 modules) - modules/stealth/ (all 12 modules)
- utils/ (all 7 utility 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) - 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) - tests/ (engine, bus, crypto, resource)
Validation: Module lifecycle works. Encrypted storage. Process disguised. Validation: Module lifecycle works (multiprocess). Capture bus demuxes packets.
Kill switch wipes all data. Watchdog restarts crashed module. Overlayfs on Pi. Encrypted storage with LUKS network-derived unlock. Sensitive config inside LUKS.
Hardware tier detection accurate. 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: Files:
- modules/passive/ (all 18 modules) - modules/passive/ (all 22 modules incl. ldap_harvester, rdp_monitor,
- modules/intel/ (credential_db, topology_mapper, user_timeline) quic_analyzer, db_interceptor)
- data/ (oui.db, os_sigs.db, bpf_filters/) - 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. Validation: All hosts discovered (with DHCP fingerprinting). Credentials
DNS queries logged per host. TLS SNI extracted. Kerberos tickets harvested. 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 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: Files:
@@ -1450,13 +1663,14 @@ Files:
- scripts/setup_bridge.sh, teardown_bridge.sh - scripts/setup_bridge.sh, teardown_bridge.sh
Validation: Failover chain works: Tailscale > WireGuard > SSH > Cellular. 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. 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: Files:
@@ -1464,26 +1678,31 @@ Files:
- modules/intel/ (report_generator, net_intel, supply_chain_detect) - modules/intel/ (report_generator, net_intel, supply_chain_detect)
- templates/ (captive_portals, dns_zones, hostapd, responder, beef) - templates/ (captive_portals, dns_zones, hostapd, responder, beef)
Validation: ARP spoof + HTTP logging chain works. DNS poisoning redirects. Validation: ARP spoof + HTTP logging chain works (scope-validated when enabled).
Evil twin captures credentials. Responder captures NTLMv2 hashes. DNS poisoning redirects. DHCP spoof respects scope. Evil twin captures credentials.
ntlmrelayx relays to ADCS. mitmproxy decrypts HTTPS. File extraction Responder captures NTLMv2 hashes. ntlmrelayx relays to ADCS (Coercer integration
from traffic. JS injection into HTTP. Session tokens captured. 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: Tasks:
- Full integration test on Pi Zero 2W, Pi 4, Debian - Full integration test on Pi Zero 2W (4 passive modules), Pi 4 (all 22), Debian
- 72-hour soak test (memory leaks, disk usage, stability) - 72-hour soak test (memory leaks, disk usage, thermal, stability)
- Pi Zero performance optimization pass - Pi Zero performance optimization pass (verify 365MB budget, thermal under 55C)
- Rich TUI interactive menu polish - Capture bus stress test (packet throughput, queue backpressure)
- setup.sh validation on clean OS images - 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 - Crypto implementation review
- LKM rootkit compile and test on target kernels - LKM rootkit compile and test on target kernels
- IDS tester validation against current rulesets - IDS tester validation against current rulesets
- zstd PCAP compression verification on 128GB storage
- Error handling audit - Error handling audit
``` ```
@@ -1498,7 +1717,7 @@ Tasks:
3. **Hostname** — Generic IoT name. Never "kali", "attack", "pentest". 3. **Hostname** — Generic IoT name. Never "kali", "attack", "pentest".
4. **SSH keys** — Fresh per engagement. Neutral key comment. 4. **SSH keys** — Fresh per engagement. Neutral key comment.
5. **Tailscale** — Per-engagement auth key. Hostname matches device disguise. 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. 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. 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. 31. **Bridge mode** — No IP, no MAC on network. Physical inspection only detection.
32. **Tailscale** — Looks like HTTPS to Derp servers. 32. **Tailscale** — Looks like HTTPS to Derp servers.
33. **WireGuard** — Encrypted UDP on single port. Looks like noise. 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. 35. **Cellular** — Completely out-of-band. Bypasses target network entirely.
36. **DNS tunneling** — Low rate, randomized, multiple domains. 36. **DNS tunneling** — Low rate, randomized, multiple domains.