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

v4.0 design rewrite: orchestrator architecture, operator workstation, innocuous MACs

Browse Source 
Major rewrite of BIGBROTHER_DESIGN.md incorporating three architectural changes:

1. Orchestrator model: BigBrother wraps proven tools instead of reimplementing.
   - bettercap replaces 5+ custom active modules (ARP/DNS/DHCP/HTTP/SSL)
   - tcpdump replaces custom scapy packet capture
   - 11 modules deleted (file_extractor, email_sniffer, print_interceptor,
     voip_capture, protocol_analyzer, session_hijacker, http_logger,
     ssl_downgrade, js_injector, cloud_token_active, report_generator)
   - New: bettercap_mgr, tool_manager, tool_output_parser, bettercap_api
   - Module count: 67 -> 60

2. Operator workstation section: offline analysis tools and pull scripts
   for file carving, email/print reconstruction, GPU hash cracking, and
   report generation from PCAPs and SQLite DBs.

3. Innocuous MAC database: curated consumer device profiles (Fire TV,
   iPhone, Roku, etc.) with matching DHCP hostname, vendor class, TTL,
   and TCP window size for complete device impersonation.

Deleted ARCHITECTURE_RETHINK.md (merged into design doc).
This commit is contained in:
n0mad1k
2026-03-17 12:35:47 -04:00
parent 0a62b805f4
commit 0a80f8bed8
2 changed files with 853 additions and 2000 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ARCHITECTURE_RETHINK.md
-540
View File
@@ -1,540 +0,0 @@
# BigBrother v4.0: Architecture Rethink — Orchestrator Model
> **Date**: 2026-03-17
> **Status**: Architecture Decision Record
> **Evaluators**: Security Analyst, OPSEC Analyst, Blue Team Analyst, APT Threat Actor, Red Team Professional, Infra/Reliability Analyst
---
## Executive Summary
The v3.2 design has 22 passive modules, 14 active modules, and 9 intel modules — 45 custom Python modules reimplementing what proven tools already do better. The proposed change is correct. BigBrother should be an **orchestrator of proven tools** with custom Python only where no existing tool covers the need.
bettercap alone replaces 10+ custom modules (ARP spoof, DNS poison, DHCP spoof, HTTP proxy, JS injection, credential sniffing, SSL strip). tcpdump replaces the custom PCAP capture. tshark handles protocol dissection better than any scapy reimplementation. The custom code that remains is lightweight structured data extraction, stealth/connectivity (BigBrother's actual unique value), and intel aggregation.
---
## 1. Modules to DELETE (Processing Belongs Offline)
These modules perform heavy processing that should happen on the operator's workstation from PCAPs, not on a resource-constrained Pi.
| Module | Justification |
|--------|--------------|
| `passive/print_interceptor.py` | Print job reconstruction + Ghostscript PDF conversion is CPU-heavy. TCP/9100 streams are in the full PCAPs. Run NetworkMiner or `tshark -z follow,tcp` on your workstation. Capture is free; reconstruction is expensive. |
| `passive/email_sniffer.py` | MIME parsing, Base64 decoding, attachment extraction — all CPU/RAM intensive. Yields near-zero on modern networks (STARTTLS everywhere). The 1-2 cleartext SMTP sessions/day from printers are in the PCAPs. Reconstruct offline with `tshark -z follow,tcp` or NetworkMiner. |
| `passive/voip_capture.py` | RTP audio capture to WAV is storage-intensive. SIP metadata is trivially extracted from PCAPs offline. RTP reassembly belongs on a workstation. |
| `passive/protocol_analyzer.py` | Zeek-style deep protocol dissection is exactly what tshark/Zeek do. Banner extraction, cert analysis, service ID — run tshark offline on the PCAPs. This module reimplements Zeek poorly in Python. |
| `active/file_extractor.py` | File carving from HTTP/SMB/FTP streams is CPU/RAM intensive (40MB+ RAM, 5% CPU). NetworkMiner does this better from PCAPs. On a Pi, this competes with capture for resources. |
| `active/session_hijacker.py` | Cookie/JWT extraction from MITM traffic — bettercap's http.proxy already logs all headers. Parse cookies from bettercap logs or mitmproxy output offline. |
| `active/http_logger.py` | Full HTTP transaction logging — bettercap's http.proxy module does this natively. Every URL, header, POST body, cookie. Redundant custom code. |
| `active/ssl_downgrade.py` | sslstrip is built into bettercap (`http.proxy.sslstrip`). Writing a custom Python sslstrip in 2026 is pointless. |
| `active/js_injector.py` | bettercap's `http.proxy` supports JavaScript injection natively via caplets. `hstshijack` caplet handles HSTS bypass + injection. Custom Python reimplementation adds nothing. |
| `active/cloud_token_active.py` | Token extraction from decrypted HTTPS — this is a mitmproxy script, not a standalone module. Write a 50-line mitmproxy addon, not a module. |
| `intel/report_generator.py` | Engagement reporting should happen on the operator's workstation with full data access, not on the Pi. Export structured data (JSON/SQLite); render reports offline. |
**Total deleted: 11 modules** (5 passive, 5 active, 1 intel)
---
## 2. Modules to Become Tool Wrappers
These modules should be thin Python wrappers that configure, start, monitor, and parse output from proven tools.
### Active Module Wrappers
| Module | Wraps | How the Wrapper Works |
|--------|-------|----------------------|
| `active/arp_spoof.py` | **bettercap** `arp.spoof` | Configure targets/gateway in bettercap REST API. Start/stop via API. Monitor ARP table restoration on crash. Wrapper handles the crash-recovery cron (send corrective gratuitous ARPs if bettercap dies). Bettercap's arp.spoof already does rate-limiting and selective targeting. |
| `active/dns_poison.py` | **bettercap** `dns.spoof` | Push DNS spoofing rules via bettercap REST API or caplet. Template-driven zone files converted to bettercap dns.spoof.domains format. |
| `active/dhcp_spoof.py` | **bettercap** `dhcp6.spoof` | Configure DHCP pool via bettercap. bettercap handles the DHCP race condition. |
| `active/ipv6_slaac.py` | **bettercap** `dhcp6.spoof` + **mitm6** | bettercap's dhcp6.spoof does RA injection. mitm6 adds WPAD abuse. Wrapper manages both. |
| `active/responder_mgr.py` | **Responder** (no change) | Already a wrapper. Keep as-is. Parse Responder logs, feed to credential_db. |
| `active/mitmproxy_mgr.py` | **mitmproxy** (no change) | Already a wrapper. Keep as-is. Add custom addon scripts for credential/token extraction instead of separate modules. |
| `active/ntlm_relay.py` | **ntlmrelayx** (no change) | Already a wrapper around Impacket. Keep as-is. |
| `active/evil_twin.py` | **hostapd + dnsmasq** (no change) | Already uses external tools. Keep as-is. |
### Passive Module Wrappers
| Module | Wraps | How the Wrapper Works |
|--------|-------|----------------------|
| `passive/packet_capture.py` | **tcpdump** | Replace custom AF_PACKET + scapy capture with tcpdump subprocess. tcpdump handles BPF, rotation (`-G 3600 -W 168`), snap length, PcapNG. Wrapper adds: post-rotation zstd compression, AES-256-GCM encryption, disk monitoring, oldest-PCAP purge. tcpdump is more reliable and uses less RAM than a Python PCAP writer. |
| `passive/wireless_intel.py` | **bettercap** `wifi.recon` + **airodump-ng** | bettercap's wifi module handles probe collection, handshake capture, BLE scanning. Wrapper parses output, stores to DB. |
### New bettercap Orchestrator (replaces 5+ modules)
A single `active/bettercap_mgr.py` module manages one bettercap instance that replaces arp_spoof, dns_poison, dhcp_spoof, ssl_downgrade, js_injector, and http_logger. Individual wrapper modules become thin facades that call into bettercap_mgr.
**How bettercap_mgr works**:
1. Start bettercap with REST API enabled (`-api-rest-address 127.0.0.1 -api-rest-port 8083`)
2. Authenticate with random per-session API credentials
3. Individual module wrappers call bettercap_mgr to enable/disable capabilities
4. bettercap_mgr monitors bettercap health via API `/api/session`
5. On crash: auto-restart bettercap, re-apply active caplet configuration
6. Parse bettercap event stream for credentials, push to credential_db
7. Caplet files stored in `config/caplets/` for engagement-specific configs
---
## 3. Modules That Stay as Custom Python
These modules are genuinely lightweight, do something no existing tool covers for unattended operation, or are BigBrother's unique value.
### Passive — Lightweight Structured Data Extraction
| Module | Justification | RAM |
|--------|--------------|-----|
| `passive/dns_logger.py` | Per-host DNS log with SQLite storage, DoH blind spot detection, domain categorization. tcpdump captures DNS packets; this module extracts and structures the data for real-time querying. tshark could parse DNS but not maintain a live queryable per-host database. **Lightweight**: BPF filter on UDP/53, parse 2 fields per packet, batch SQLite insert. | 15MB |
| `passive/tls_sni_extractor.py` | SNI extraction + correlation with DNS logs for unified web activity view. Same argument — tshark can extract SNI but not maintain a live correlated database. **Lightweight**: parse TLS ClientHello, extract 1 field, batch insert. | 10MB |
| `passive/credential_sniffer.py` | Real-time credential extraction with immediate bus notification + credential_db insert. The real-time alerting (CREDENTIAL_FOUND event -> data_exfil priority push) is the value — offline extraction from PCAPs introduces hours of delay. Cleartext protocols + NTLM from wire. **Keep scope narrow**: FTP, HTTP Basic, HTTP POST, SNMP community, NTLM. Drop SMTP/POP3/IMAP parsing (STARTTLS makes them useless). | 15MB |
| `passive/kerberos_harvester.py` | Kerberos ticket extraction must happen in real-time for timely cracking. AS-REP roasting and Kerberoasting from wire are high-value, time-sensitive (tickets expire). Immediate push to operator's cracking rig. impacket already does the hard parsing. | 15MB |
| `passive/host_discovery.py` | ARP/DHCP/mDNS/NetBIOS correlation into a live host table. This is lightweight event-driven processing that no single tool does as an aggregated view. Core to every other module's context. | 15MB |
| `passive/os_fingerprint.py` | p0f-style fingerprinting from TCP SYN analysis. Lightweight, enriches host_discovery. Could wrap p0f binary instead, but p0f is unmaintained since 2014. The custom Python is small and correct. | 10MB |
| `passive/traffic_analyzer.py` | Flow tracking, top talkers, beacon detection. The beacon detection (regular-interval C2 identification) is custom analysis that no existing tool does in real-time for this use case. Feeds traffic_mimicry baseline. | 25MB |
| `passive/vlan_discovery.py` | 802.1Q/DTP/STP/CDP/LLDP parsing. Lightweight, event-driven, no existing tool aggregates this for an implant. | 10MB |
| `passive/network_mapper.py` | Communication graph construction from live traffic. Feeds topology_mapper. Lightweight directed graph in memory. | 15MB |
| `passive/auth_flow_tracker.py` | Kerberos + NTLM + SSH auth event correlation into per-user timelines. Cross-protocol correlation is custom logic. | 15MB |
| `passive/smb_monitor.py` | SMB share/file access tracking. Which users access which shares. impacket parsing, lightweight metadata extraction. | 15MB |
| `passive/cloud_token_harvester.py` | Passive cloud token extraction (AWS keys, JWT, OAuth). Lightweight regex + JWT decode on cleartext HTTP. Near-zero yield on most networks but zero-cost to run. | 10MB |
| `passive/ldap_harvester.py` | LDAP search/response parsing for passive AD inventory. impacket handles parsing. High-value on AD networks. | 15MB |
| `passive/rdp_monitor.py` | RDP NLA header parsing for username/hostname extraction. Lightweight, enriches auth_flow_tracker. | 10MB |
| `passive/quic_analyzer.py` | QUIC Initial SNI extraction. No existing tool does this as a live feed. Covers 7-8% of web traffic invisible to TCP TLS extraction. | 10MB |
| `passive/db_interceptor.py` | TDS/MySQL/PostgreSQL/Redis/MongoDB protocol parsing. Real-time SQL query logging + credential extraction from TDS login packets (XOR-encoded passwords). High-value, time-sensitive. The sa password from TDS needs immediate exfil. | 20MB |
### Stealth — BigBrother's Unique Value (all stay)
| Module | Notes |
|--------|-------|
| `stealth/mac_manager.py` | No existing tool. Custom. |
| `stealth/process_disguise.py` | No existing tool. Custom. Now also disguises bettercap/tcpdump process names. |
| `stealth/log_suppression.py` | No existing tool. Custom. |
| `stealth/encrypted_storage.py` | LUKS management. Custom. |
| `stealth/tmpfs_manager.py` | Custom. |
| `stealth/watchdog.py` | Now manages bettercap/tcpdump/Responder/mitmproxy subprocesses in addition to Python modules. Expanded role. |
| `stealth/anti_forensics.py` | Custom. |
| `stealth/traffic_mimicry.py` | Custom. |
| `stealth/ja3_spoofer.py` | Custom. Applied to bettercap + mitmproxy outbound connections. |
| `stealth/ids_tester.py` | Custom. Now also checks bettercap caplet actions against IDS rules. |
| `stealth/lkm_rootkit.py` | Custom. Hides bettercap binary + tcpdump in addition to Python processes. |
| `stealth/overlayfs_manager.py` | Custom. |
### Connectivity (all stay)
All 8 connectivity modules remain. These are BigBrother's unique value — reliable unattended remote access, failover chain, data exfil pipeline. No changes.
### Intel — Lightweight On-Device Analysis (keep most)
| Module | Status | Notes |
|--------|--------|-------|
| `intel/credential_db.py` | **Keep** | Central credential store. All tool outputs (bettercap, Responder, mitmproxy) feed into this. |
| `intel/topology_mapper.py` | **Keep** | Graphviz from structured data. Lightweight. |
| `intel/net_intel.py` | **Keep** | Beacon detection, C2 detection. Custom analysis. |
| `intel/user_timeline.py` | **Keep** | Per-user activity aggregation from structured data. |
| `intel/supply_chain_detect.py` | **Keep** | Passive infra detection. Lightweight. |
| `intel/change_detector.py` | **Keep** | Network state diffing. Critical for burn detection. Must be on-device (can't wait for offline analysis to detect IR activity). |
| `intel/security_posture.py` | **Keep** | Defense mapping. Must be on-device to gate active module risk. |
| `intel/operator_audit.py` | **Keep** | Audit trail. Must be on-device. |
| `intel/report_generator.py` | **DELETE** | Generate reports on operator's workstation from exported data. |
---
## 4. New Modules Needed
### `active/bettercap_mgr.py` — bettercap Orchestrator (NEW, CRITICAL)
Central manager for the bettercap subprocess. All active MITM operations route through this.
**Responsibilities**:
- Start bettercap with REST API + specific caplet
- Health monitoring via API polling (every 10s)
- Auto-restart on crash with caplet re-application (max 3 restarts)
- Credential event stream parsing -> credential_db
- ARP restoration on crash (gratuitous ARP correction within 15s)
- Process name disguise coordination with process_disguise.py
- Caplet management: load, unload, switch engagement profiles
- Resource monitoring: bettercap RAM/CPU tracking
**bettercap REST API usage**:
```
POST /api/session — run commands
GET /api/session — get status
GET /api/events — poll event stream (credentials, new hosts)
```
**Caplet structure** (`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
```
### `active/tool_output_parser.py` — Unified Tool Output Parser (NEW)
Parses output from all managed tools into structured data for credential_db and event bus.
**Parsers**:
- bettercap event stream (JSON) -> credentials, hosts, HTTP logs
- Responder logs (`Responder-Session.log`, `*-NTLMv2-*.txt`) -> NTLMv2 hashes
- mitmproxy flow dumps -> credentials, tokens, headers
- tcpdump (not parsed directly — PCAPs processed by passive modules)
### `core/subprocess_manager.py` — Subprocess Lifecycle Manager (NEW)
Generic subprocess management for Go binaries and Python tools. Replaces ad-hoc subprocess handling.
**Features**:
- 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, Responder PID, mitmproxy API)
- Graceful shutdown (SIGTERM -> 5s timeout -> SIGKILL)
- Crash callback (e.g., ARP restoration on bettercap crash)
### `utils/bettercap_api.py` — bettercap REST API Client (NEW)
Thin HTTP client for bettercap's REST API.
```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:
```
---
## 5. Revised File Tree
```
~/tools/bigbrother/
├── bigbrother.py # Main CLI + interactive menu (Click + Rich)
├── setup.sh # Idempotent Debian bootstrap
├── requirements.txt # Python dependencies (lighter — no scapy for PCAP capture)
├── .gitignore
│
├── config/
│ ├── bigbrother.yaml # Non-sensitive defaults
│ ├── 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 (NEW)
│ │ ├── passive_recon.cap
│ │ ├── arp_mitm.cap
│ │ ├── dns_spoof.cap
│ │ ├── full_mitm.cap
│ │ └── wifi_recon.cap
│ ├── mitmproxy_addons/ # mitmproxy addon scripts (NEW)
│ │ ├── credential_extractor.py # Extract creds from decrypted HTTPS
│ │ ├── cloud_token_extractor.py # Extract cloud tokens (replaces cloud_token_active.py)
│ │ └── file_logger.py # Log file transfers (lightweight metadata only)
│ └── 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
│ ├── subprocess_manager.py # Generic subprocess lifecycle (NEW)
│ ├── scheduler.py # Task scheduler
│ ├── bus.py # Internal event bus
│ ├── 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 (was 22, deleted 6)
│ │ ├── __init__.py
│ │ ├── packet_capture.py # Wrapper: tcpdump + zstd + AES-256-GCM
│ │ ├── dns_logger.py # Custom: per-host DNS log
│ │ ├── tls_sni_extractor.py # Custom: SNI extraction + correlation
│ │ ├── credential_sniffer.py # Custom: real-time cred extraction
│ │ ├── kerberos_harvester.py # Custom: ticket extraction for cracking
│ │ ├── host_discovery.py # Custom: ARP/DHCP/mDNS host table
│ │ ├── os_fingerprint.py # Custom: p0f-style TCP fingerprinting
│ │ ├── traffic_analyzer.py # Custom: flows, beacons, baselines
│ │ ├── vlan_discovery.py # Custom: 802.1Q/DTP/STP/CDP/LLDP
│ │ ├── network_mapper.py # Custom: communication graph
│ │ ├── auth_flow_tracker.py # Custom: auth event correlation
│ │ ├── smb_monitor.py # Custom: share/file access tracking
│ │ ├── cloud_token_harvester.py # Custom: passive token extraction
│ │ ├── ldap_harvester.py # Custom: LDAP query/response parsing
│ │ ├── rdp_monitor.py # Custom: RDP NLA header parsing
│ │ ├── quic_analyzer.py # Custom: QUIC Initial SNI
│ │ └── db_interceptor.py # Custom: database protocol parsing
│ │
│ ├── active/ # 8 modules (was 14, deleted 5, merged 1)
│ │ ├── __init__.py
│ │ ├── bettercap_mgr.py # NEW: central bettercap orchestrator
│ │ ├── arp_spoof.py # Thin wrapper -> bettercap_mgr
│ │ ├── dns_poison.py # Thin wrapper -> bettercap_mgr
│ │ ├── dhcp_spoof.py # Thin wrapper -> bettercap_mgr
│ │ ├── evil_twin.py # hostapd + dnsmasq (unchanged)
│ │ ├── ipv6_slaac.py # bettercap dhcp6.spoof + mitm6
│ │ ├── responder_mgr.py # Responder subprocess (unchanged)
│ │ ├── mitmproxy_mgr.py # mitmproxy subprocess (unchanged, uses addon scripts)
│ │ └── ntlm_relay.py # ntlmrelayx subprocess (unchanged)
│ │
│ ├── connectivity/ # 8 modules (unchanged)
│ │ └── ...
│ │
│ ├── stealth/ # 12 modules (unchanged, expanded scope)
│ │ └── ...
│ │
│ └── intel/ # 8 modules (was 9, deleted report_generator)
│ ├── __init__.py
│ ├── credential_db.py # Central cred store (+ bettercap/Responder ingestion)
│ ├── topology_mapper.py
│ ├── net_intel.py
│ ├── user_timeline.py
│ ├── supply_chain_detect.py
│ ├── change_detector.py
│ ├── security_posture.py
│ ├── operator_audit.py
│ └── tool_output_parser.py # NEW: unified tool output parsing
│
├── utils/
│ ├── __init__.py
│ ├── crypto.py
│ ├── networking.py
│ ├── logging.py
│ ├── stealth.py
│ ├── resource.py
│ ├── permissions.py
│ ├── config_loader.py
│ └── bettercap_api.py # NEW: bettercap REST API client
│
├── data/ # (unchanged)
├── services/ # (unchanged)
├── templates/ # (unchanged, minus beef hook — bettercap handles injection)
├── scripts/ # (unchanged)
├── tests/ # (add bettercap_mgr, subprocess_manager tests)
└── storage/ # Remove: emails/, voip/, print_jobs/ directories
├── config/
├── pcaps/
├── creds/
├── dns_logs/
├── sni_logs/
├── files/ # Only metadata now, not carved files
├── intel/
├── baseline/
├── audit/
├── tool_logs/ # NEW: bettercap, Responder, mitmproxy output
└── logs/
```
**Module count: 45 -> 36** (16 passive + 8 active + 8 connectivity + 12 stealth + 8 intel + core/utils)
---
## 6. Resource Impact
### RAM Comparison
| Component | v3.2 (Current) | v4.0 (Proposed) | Notes |
|-----------|:--------------:|:---------------:|-------|
| **OS + kernel** | 110 MB | 110 MB | Same |
| **Python interpreter + libs** | 70 MB | 55 MB | Lighter — fewer scapy-heavy modules |
| **Core framework** | 20 MB | 25 MB | subprocess_manager adds slight overhead |
| **tcpdump (PCAP capture)** | — | 5 MB | Replaces 30-80MB Python PCAP writer |
| **packet_capture.py (v3.2)** | 30-80 MB | — | Replaced by tcpdump |
| **bettercap** | — | 25-35 MB | Single Go binary, all active MITM |
| **16 passive Python modules** | ~250 MB | ~200 MB | 6 heavy modules deleted |
| **5 deleted active modules** | ~105 MB | — | Gone (bettercap handles it) |
| **Responder** | 30 MB | 30 MB | Same |
| **mitmproxy** | 100-200 MB | 100-200 MB | Same (Pi 4+ only) |
| **Stealth modules** | 50 MB | 50 MB | Same |
| **Connectivity** | 55 MB | 55 MB | Same |
| **Intel modules** | 60 MB | 55 MB | Dropped report_generator |
| **TOTAL (passive only, Pi 4)** | ~650-750 MB | ~500-550 MB | ~150-200 MB savings |
| **TOTAL (full active, Pi 4)** | ~900-1100 MB | ~700-850 MB | ~200-250 MB savings |
### Pi Zero 2W Impact
| Component | v3.2 | v4.0 |
|-----------|:----:|:----:|
| OS + kernel | 110 MB | 110 MB |
| Python + libs | 70 MB | 55 MB |
| Core + capture_bus | 20 MB | 25 MB |
| tcpdump | — | 5 MB |
| packet_capture.py | 30 MB | — |
| dns_logger | 15 MB | 15 MB |
| credential_sniffer | 20 MB | 15 MB |
| host_discovery | 15 MB | 15 MB |
| Stealth + connectivity | 45 MB | 45 MB |
| overlayfs | 30 MB | 30 MB |
| **TOTAL** | **355 MB** | **315 MB** |
| **Headroom** | **45 MB** | **85 MB** |
The extra 40MB headroom on Pi Zero is significant — it means bettercap could potentially run for a single active capability (ARP spoof), which was impossible in v3.2.
### CPU Impact
- **tcpdump**: 2-5% CPU for packet capture vs 5-15% for Python AF_PACKET + scapy. Clear win.
- **bettercap**: 3-8% CPU for active MITM vs 15-25% combined CPU of 5 custom Python active modules. Go is more efficient.
- **Compression**: zstd compression remains the same — still done by Python wrapper post-rotation.
- **Net CPU savings**: 10-20% on Pi 4 during active operations.
### Disk Impact
- **Removed storage directories**: `emails/`, `voip/`, `print_jobs/` — no longer stored on device.
- **Added**: `tool_logs/` for bettercap/Responder/mitmproxy output (~5-20MB/day).
- **Net**: Slight savings. PCAPs still dominate disk usage.
---
## 7. Risks and Tradeoffs
### Red Team Professional Assessment
**This is the right call.** In real engagements, I already use bettercap for MITM and tcpdump for capture. Writing custom Python ARP spoofing when bettercap exists is engineering vanity. The workflow with bettercap as the MITM engine is proven on thousands of engagements.
**Things bettercap CANNOT do that need custom code**:
- Kerberos ticket extraction from wire (bettercap parses HTTP/NTLM, not Kerberos AS-REQ/TGS-REP)
- TDS (SQL Server) protocol password decoding (bettercap doesn't understand TDS XOR encoding)
- LDAP query/response parsing for AD object inventory
- RDP NLA header parsing for username extraction
- QUIC Initial packet SNI extraction (bettercap's net.sniff captures packets but doesn't parse QUIC crypto)
- Database protocol parsing (MSSQL/MySQL/PostgreSQL wire protocols)
- Beacon detection and traffic analysis (bettercap has net.sniff but no statistical analysis)
- Per-host DNS database with DoH blind spot detection
These are all niche protocol parsers that justify custom Python. Everything else bettercap handles.
### APT Threat Actor Assessment
**For 2-week unattended deployment, what MUST run on-device:**
1. **PCAP capture** (tcpdump) — ground truth, cannot be reconstructed
2. **DNS logging** — real-time per-host database, immediate value for recon
3. **SNI extraction** — combined with DNS, complete web activity picture
4. **Credential extraction** — time-sensitive, must push immediately to operator
5. **Kerberos harvesting** — tickets expire, must extract and exfil promptly
6. **Host discovery** — live network inventory, feeds all other modules
7. **Change detection** — burn detection must be real-time on-device
8. **Security posture mapping** — must gate active module decisions
**What can happen offline from PCAPs:**
- Print job reconstruction (PCL/PostScript -> PDF)
- Email reconstruction (MIME parsing)
- File carving (HTTP/SMB/FTP streams)
- VoIP audio extraction (RTP reassembly)
- Deep protocol analysis (Zeek/tshark)
- Certificate chain analysis
- Full report generation
- SMB file content extraction (metadata tracking stays on-device)
**Structured data extraction on-device**: Only what produces a row in a database (hostname, credential, SNI entry, auth event). Never reconstruction of binary content (files, audio, print jobs, emails).
### Infra/Reliability Assessment
**Subprocess management is the critical new challenge.** Python modules crashing are handled by multiprocessing. bettercap/tcpdump/Responder crashing requires different handling:
1. **tcpdump crash**: PCAP capture stops. Auto-restart within 5s. Gap in capture is acceptable (5s of missed packets vs. hours of good capture).
2. **bettercap crash during ARP spoof**: Network disruption for spoofed targets. Recovery plan:
- subprocess_manager detects death within 10s (PID poll)
- Immediately send corrective gratuitous ARPs (Python + scapy, 3 lines of code)
- Restart bettercap, re-apply caplet within 15s
- Total disruption window: 10-25 seconds
- Failsafe: if bettercap fails 3 times, disable ARP spoof and send final ARP correction
3. **Responder crash**: No network disruption. Just stops capturing hashes. Auto-restart is safe.
4. **mitmproxy crash**: HTTPS interception stops. Clients may see connection resets. Auto-restart, re-apply config.
**bettercap is more reliable than custom Python**: Go binary, single process, no GIL, no memory leaks from scapy packet accumulation. In practice, bettercap runs for days without issues. The custom Python modules in v3.2 are more likely to leak memory or deadlock.
### Blue Team Assessment
**Detection surface changes with bettercap**:
1. **ARP spoofing**: Identical detection signature whether bettercap or custom scapy. ARP gratuitous replies look the same on the wire. DAI detects both equally.
2. **DNS spoofing**: Identical. Forged DNS response is a forged DNS response regardless of tool.
3. **HTTP proxy**: bettercap's http.proxy sets a default `X-Forwarded-For` header and has a known proxy fingerprint. **Mitigation**: custom caplet that strips/modifies proxy headers. mitmproxy has the same issue.
4. **Process forensics**: bettercap binary on disk is a known tool. Defender/CrowdStrike would flag it by hash on a corporate endpoint. **Mitigation**: This is a dedicated implant Pi, not a compromised workstation. No EDR on the Pi. Binary hash detection is irrelevant for implant-on-own-hardware.
5. **Network signatures**: Suricata has rules for bettercap's default user-agent and some default caplet behaviors. **Mitigation**: custom caplets, modified user-agent via bettercap config.
**Net assessment**: Detection surface is roughly equivalent. The ARP/DNS/DHCP attacks look identical on the wire regardless of implementation. bettercap's HTTP proxy fingerprint is a minor additional risk, mitigated by configuration.
### OPSEC Assessment
**bettercap signature mitigations**:
1. **Binary hash**: Compile bettercap from source with `go build` — unique hash, not in any signature database. Or use the standard binary — it's on the Pi, not on a target host. EDR on the Pi is not a concern.
2. **REST API**: Bound to 127.0.0.1 only. Not network-visible.
3. **Default user-agent**: bettercap's HTTP proxy uses a configurable user-agent. Set it to match Chrome via caplet: `set http.proxy.ua "Mozilla/5.0 ..."`.
4. **Process names**: bettercap binary can be renamed before execution. Copy to `/usr/local/bin/thermal-mgr` or similar. process_disguise.py handles `/proc/PID/cmdline` spoofing. **Note**: Go binaries are harder to disguise than Python scripts because the binary name is embedded, but prctl(PR_SET_NAME) still works for `ps` output. `/proc/PID/exe` still points to the real binary — same limitation as Python in v3.2.
5. **Disk artifacts**: bettercap creates a local database (`~/.bettercap/`). **Mitigation**: Set `$HOME` to tmpfs for bettercap process. Use `--no-history` flag. Anti-forensics module handles cleanup.
6. **Network fingerprint**: bettercap's ARP packets have no distinguishing characteristics vs. custom scapy. ARP is ARP. DNS is DNS. The attack traffic is protocol-correct.
### Security Analyst — Summary of Architecture Changes
**Net module changes**:
- **Deleted**: 11 modules (5 passive, 5 active, 1 intel)
- **Converted to wrappers**: 5 modules (packet_capture, arp_spoof, dns_poison, dhcp_spoof, wireless_intel)
- **Unchanged custom Python**: 31 modules
- **New modules**: 4 (bettercap_mgr, tool_output_parser, subprocess_manager, bettercap_api)
- **New config directories**: 2 (caplets/, mitmproxy_addons/)
**Dependency changes**:
- **Added runtime**: bettercap (Go binary, ~15MB on disk)
- **Reduced Python**: No longer need scapy for PCAP writing, HTTP proxying, ARP crafting, DNS crafting, SSL stripping, JS injection, file carving, email parsing, print job parsing, VoIP parsing
- **Still need scapy**: For passive packet parsing in dns_logger, tls_sni_extractor, credential_sniffer, kerberos_harvester, host_discovery, etc. Scapy remains for packet parsing; it's no longer used for packet generation or capture.
- **Still need impacket**: For NTLM/Kerberos/LDAP/TDS/SMB parsing in passive modules.
---
## 8. What MUST Happen On-Device vs Offline
### MUST Run On-Device (Real-Time, Unattended)
| Capability | Why On-Device |
|------------|---------------|
| PCAP capture (tcpdump) | Ground truth. Cannot be reconstructed after the fact. |
| DNS logging to per-host DB | Real-time recon intelligence. Hours of delay from offline processing defeats purpose. |
| SNI extraction to DB | Same — real-time web activity view. |
| Credential extraction + exfil | Credentials are perishable (password changes, session expiry). Immediate push to operator enables exploitation within the credential's validity window. |
| Kerberos ticket extraction + exfil | Kerberos tickets expire (TGT: 10h, TGS: variable). Must extract and push for cracking before expiry. |
| Host discovery | Live network inventory. Every other module depends on knowing what hosts exist. |
| Flow/beacon analysis | Beacon detection for existing compromise identification. Cannot wait for offline analysis. |
| Change detection | Burn detection is time-critical. If IR responds, operator needs to know in minutes, not days. |
| Security posture mapping | Must gate active module risk decisions in real-time. |
| MITM operations (bettercap) | Active attacks must run on-device. Cannot be done offline. |
| Credential DB aggregation | Single queryable view of all creds from all sources. Enables operator triage via SSH. |
| Data exfil pipeline | Automated credential push, nightly intel sync. Critical for resilience against seizure. |
| Auth flow tracking | Real-time user-to-service mapping. Feeds user_timeline and operator recon. |
| SMB metadata tracking | Share/file access patterns (not content). Lightweight, informs attack paths. |
| Network mapping | Communication graph. Feeds topology and operator understanding. |
### Process Offline on Operator's Workstation
| Capability | Tool | Input |
|------------|------|-------|
| Print job reconstruction | NetworkMiner, Ghostscript | PCAPs (filter: tcp port 9100) |
| Email reconstruction | NetworkMiner, tshark | PCAPs (filter: tcp port 25 or 143 or 110) |
| File carving (HTTP/SMB/FTP) | NetworkMiner, foremost, tshark | PCAPs |
| VoIP audio extraction | Wireshark RTP player | PCAPs (filter: sip or rtp) |
| Deep protocol analysis | Wireshark, Zeek, tshark | PCAPs |
| Certificate chain analysis | tshark, openssl | PCAPs or exported certs |
| Full engagement report | Custom script + Jinja2 | Exported SQLite DBs + PCAPs |
| Hash cracking | hashcat (GPU) | Exported hashes from credential_db |
| PCAP search/replay | Wireshark | Decrypted PCAPs |
| Network forensics | Zeek + RITA | PCAPs |
BIGBROTHER_DESIGN.md
+853 -1460
View File
File diff suppressed because it is too large Load Diff