diff --git a/ARCHITECTURE_RETHINK.md b/ARCHITECTURE_RETHINK.md deleted file mode 100644 index cf72caa..0000000 --- a/ARCHITECTURE_RETHINK.md +++ /dev/null @@ -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 | diff --git a/BIGBROTHER_DESIGN.md b/BIGBROTHER_DESIGN.md index fec2a43..0a72bd4 100644 --- a/BIGBROTHER_DESIGN.md +++ b/BIGBROTHER_DESIGN.md @@ -1,1358 +1,773 @@ -# BigBrother: Total Network Surveillance Platform + Operator Jump Box +# BigBrother: Network Surveillance Orchestrator + Operator Jump Box -> **Version**: 3.2 +> **Version**: 4.0 > **Date**: 2026-03-17 -> **Status**: Implementation Blueprint (Security Review Integrated) +> **Status**: Implementation Blueprint --- ## Table of Contents 1. [Overview](#1-overview) -2. [File Tree](#2-file-tree) -3. [Surveillance Modules](#3-surveillance-modules) -4. [Connectivity](#4-connectivity) -5. [Stealth](#5-stealth) -6. [Pre-installed Tools](#6-pre-installed-tools) -7. [Core Framework](#7-core-framework) -8. [Setup & Bootstrap](#8-setup--bootstrap) -9. [Configuration](#9-configuration) -10. [Hardware Tiers](#10-hardware-tiers) -11. [Implementation Phases](#11-implementation-phases) -12. [OPSEC Notes](#12-opsec-notes) +2. [Architecture](#2-architecture) +3. [File Tree](#3-file-tree) +4. [Passive Modules](#4-passive-modules) +5. [Active Modules](#5-active-modules) +6. [Intelligence](#6-intelligence) +7. [Connectivity](#7-connectivity) +8. [Stealth](#8-stealth) +9. [Core Framework](#9-core-framework) +10. [Operator Workstation](#10-operator-workstation) +11. [Pre-installed Tools](#11-pre-installed-tools) +12. [Setup & Bootstrap](#12-setup--bootstrap) +13. [Configuration](#13-configuration) +14. [Hardware Tiers](#14-hardware-tiers) +15. [Implementation Phases](#15-implementation-phases) +16. [OPSEC Notes](#16-opsec-notes) --- ## 1. Overview -BigBrother is a total network surveillance platform and operator jump box designed for authorized red team engagements. It deploys on Raspberry Pi (Zero 2W through Pi 4) or full Debian hosts, operating as an inline transparent bridge or passive tap. Once deployed, its passive surveillance runs 24/7 with zero operator interaction — capturing every packet, logging every DNS query, extracting every credential that crosses the wire, and mapping every relationship on the network. +BigBrother is an **orchestrator of proven tools** combined with lightweight custom metadata extraction, designed for authorized red team engagements. It deploys on Raspberry Pi (Zero 2W through Pi 4) or full Debian hosts, operating as an inline transparent bridge or passive tap. -The platform has two operational modes. **Passive surveillance** runs unsupervised from the moment of deployment, collecting full packet captures, DNS query logs, TLS SNI data, cleartext credentials, Kerberos tickets, host information, traffic patterns, and protocol metadata. **Active surveillance** is operator-enabled when deeper collection is needed — ARP spoofing to become the man-in-the-middle, DNS poisoning, DHCP spoofing, Responder for hash capture, mitmproxy for HTTPS interception. Once the operator enables an active module and configures its targets, it runs unattended. +The v4.0 architecture follows a strict division of labor: -**Reality check**: Modern corporate networks are 85-95% encrypted. Passive value is primarily metadata — DNS, TLS SNI, Kerberos wire capture, flow analysis. Cleartext credential sniffer and email sniffer yield near-zero on modern networks. Kerberos from wire is the single highest-value passive capability. Active MITM is required for anything beyond metadata. +- **On-device**: packet capture (tcpdump), lightweight metadata extraction to SQLite (DNS, SNI, credentials, hosts, flows), MITM orchestration (bettercap), stealth, connectivity, structured data aggregation +- **Offline on operator workstation**: file carving, email reconstruction, print job reconstruction, VoIP audio extraction, deep protocol analysis, report generation, GPU hash cracking -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. +Custom Python exists only where no existing tool covers the need. bettercap replaces all custom ARP/DNS/DHCP/HTTP/SSL active modules. tcpdump replaces custom scapy packet capture. Processing-heavy operations move to the operator's workstation, run against PCAPs pulled from the device. -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. +**Operational modes**: **Passive surveillance** runs unsupervised from deployment -- tcpdump captures everything, lightweight Python modules extract metadata (DNS queries, TLS SNI, credentials, Kerberos tickets, host inventory, traffic flows) into queryable SQLite databases. **Active surveillance** is operator-enabled -- bettercap for ARP/DNS/DHCP spoofing, Responder for hash capture, mitmproxy for HTTPS interception. Once enabled, runs unattended. + +BigBrother is not an autonomous attack framework. The operator makes all decisions. For offensive tools, the operator SSHes in and runs nmap, Certipy, Impacket, BloodHound, CrackMapExec directly. --- -## 2. File Tree +## 2. Architecture + +### Design Principles + +1. **Orchestrate, don't reimplement.** bettercap does ARP/DNS/DHCP/HTTP better than custom scapy. tcpdump captures packets more reliably than Python AF_PACKET. Use them. +2. **Custom code only for structured metadata extraction.** If the output is a row in a database (hostname, credential, SNI entry, auth event), it runs on-device. If the output is reconstructed binary content (files, audio, print jobs, emails), it runs offline from PCAPs. +3. **Subprocess management is a first-class concern.** bettercap/tcpdump/Responder crashing requires different handling than Python module crashes. `core/tool_manager.py` provides unified lifecycle management. + +### What Runs Where + +| On-Device (Real-Time) | Offline (Operator Workstation) | +|---|---| +| PCAP capture (tcpdump) | File carving (NetworkMiner) | +| DNS/SNI/QUIC metadata to SQLite | Email reconstruction (tshark) | +| Credential extraction + immediate exfil | Print job reconstruction (pcl2pdf) | +| Kerberos ticket extraction | VoIP audio extraction (Wireshark) | +| Host discovery + OS fingerprinting | Deep protocol analysis (Zeek/tshark) | +| Flow/beacon analysis | Engagement report generation | +| MITM orchestration (bettercap) | GPU hash cracking (hashcat) | +| Change/burn detection | Certificate chain analysis | +| Auth flow tracking, SMB metadata | Network forensics (Zeek + RITA) | + +### Module Counts + +| Category | Count | Notes | +|---|---|---| +| Passive | 16 | Custom metadata extraction + tcpdump wrapper | +| Active | 8 | bettercap_mgr + thin wrappers + Responder/mitmproxy/ntlmrelayx | +| Connectivity | 8 | Unchanged | +| Stealth | 12 | Unchanged, expanded scope (disguise bettercap/tcpdump) | +| Intel | 8 | Dropped report_generator, added tool_output_parser | +| Core | 8 | Added tool_manager.py | +| **Total** | **60** | Down from 67 in v3.2 | + +--- + +## 3. File Tree ``` ~/tools/bigbrother/ ├── bigbrother.py # Main CLI + interactive menu (Click + Rich) -├── setup.sh # Idempotent Debian bootstrap (packages + tools) +├── setup.sh # Idempotent Debian bootstrap ├── requirements.txt # Python dependencies ├── .gitignore │ ├── config/ -│ ├── bigbrother.yaml # Non-sensitive defaults only (plaintext FS) +│ ├── bigbrother.yaml # Non-sensitive defaults (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) +│ ├── stealth.yaml # OPSEC/stealth profile +│ ├── hardware_tiers.yaml # Tier-specific limits +│ ├── scope.yaml # Optional scope enforcement +│ ├── caplets/ # bettercap caplet files +│ │ ├── passive_recon.cap +│ │ ├── arp_mitm.cap +│ │ ├── dns_spoof.cap +│ │ ├── full_mitm.cap +│ │ └── wifi_recon.cap +│ ├── mitmproxy_addons/ # mitmproxy addon scripts +│ │ ├── credential_extractor.py # Extract creds from decrypted HTTPS +│ │ ├── cloud_token_extractor.py # Extract cloud tokens (replaces cloud_token_active) +│ │ └── file_logger.py # Log file transfer metadata │ └── templates/ -│ ├── engagement_default.yaml # Template for new engagements -│ ├── engagement_minimal.yaml # Minimal config for Pi Zero 2W -│ └── engagement_full.yaml # Full config for Pi 4 / Debian host +│ ├── engagement_default.yaml +│ ├── engagement_minimal.yaml +│ └── engagement_full.yaml │ ├── core/ │ ├── __init__.py -│ ├── engine.py # Module lifecycle manager (load, start, stop, status) -│ ├── capture_bus.py # Single AF_PACKET capture, demux to per-module queues +│ ├── engine.py # Module lifecycle manager +│ ├── capture_bus.py # Packet demux from tcpdump PCAPs to module queues +│ ├── tool_manager.py # Subprocess lifecycle for bettercap/tcpdump/Responder/mitmproxy │ ├── scheduler.py # Task scheduler (cron-like, jitter-aware) -│ ├── bus.py # Internal event bus (pub/sub between modules) -│ ├── state.py # Persistent state manager (SQLite) -│ ├── resource_monitor.py # RAM/CPU/disk/thermal watchdog, throttle enforcement +│ ├── bus.py # Internal event bus (pub/sub) +│ ├── state.py # Persistent state (SQLite) +│ ├── resource_monitor.py # RAM/CPU/disk/thermal watchdog │ └── kill_switch.py # Manual wipe orchestrator │ ├── modules/ │ ├── __init__.py -│ ├── base.py # Abstract base class for all modules +│ ├── base.py # Abstract base class │ │ -│ ├── passive/ # 24/7 unsupervised collection +│ ├── passive/ # 16 modules — metadata extraction + tcpdump wrapper │ │ ├── __init__.py -│ │ ├── packet_capture.py # Full PCAP rotation, BPF filters, promiscuous mode -│ │ ├── dns_logger.py # Per-host DNS query log, every domain resolved -│ │ ├── tls_sni_extractor.py # HTTPS destinations from ClientHello SNI field -│ │ ├── credential_sniffer.py # Cleartext FTP/HTTP/SMTP/POP3/IMAP/Telnet/SNMP + NTLM -│ │ ├── kerberos_harvester.py # AS-REQ/AS-REP/TGS-REQ/TGS-REP from traffic -│ │ ├── host_discovery.py # ARP table, DHCP sniffing, mDNS, NetBIOS -│ │ ├── os_fingerprint.py # Passive OS fingerprinting (p0f-style) -│ │ ├── traffic_analyzer.py # Protocol distribution, flows, bandwidth, beacons, comm graphs -│ │ ├── vlan_discovery.py # 802.1Q tags, DTP frames, 802.1X detection -│ │ ├── network_mapper.py # Who talks to whom, protocol, volume — visual graph -│ │ ├── auth_flow_tracker.py # Map user-to-service authentication, build timelines -│ │ ├── smb_monitor.py # File share access patterns (users, shares, files) -│ │ ├── voip_capture.py # SIP metadata, call records, RTP audio (if unencrypted) -│ │ ├── print_interceptor.py # PCL/PostScript print spool from network print traffic -│ │ ├── 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 -│ │ ├── 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 +│ │ ├── packet_capture.py # Wrapper: tcpdump + zstd + AES-256-GCM +│ │ ├── dns_logger.py # Per-host DNS query log → SQLite +│ │ ├── tls_sni_extractor.py # TLS ClientHello SNI → SQLite +│ │ ├── credential_sniffer.py # Cleartext + NTLM cred extraction +│ │ ├── kerberos_harvester.py # AS-REP/TGS-REP ticket extraction +│ │ ├── host_discovery.py # ARP/DHCP/mDNS/NetBIOS host table +│ │ ├── os_fingerprint.py # p0f-style passive TCP fingerprinting +│ │ ├── traffic_analyzer.py # Flows, beacons, top talkers, baselines +│ │ ├── vlan_discovery.py # 802.1Q/DTP/STP/CDP/LLDP parsing +│ │ ├── network_mapper.py # Communication graph construction +│ │ ├── auth_flow_tracker.py # Kerberos/NTLM/SSH auth correlation +│ │ ├── smb_monitor.py # SMB share/file access metadata +│ │ ├── cloud_token_harvester.py # Passive AWS/JWT/OAuth from cleartext HTTP +│ │ ├── ldap_harvester.py # LDAP query/response → AD object inventory +│ │ ├── rdp_monitor.py # RDP NLA username/hostname extraction +│ │ ├── quic_analyzer.py # QUIC Initial packet SNI extraction +│ │ └── db_interceptor.py # TDS/MySQL/PostgreSQL login + query metadata │ │ -│ ├── active/ # Operator-enabled, then runs unattended +│ ├── active/ # 8 modules — bettercap + tool wrappers │ │ ├── __init__.py -│ │ ├── arp_spoof.py # ARP cache poisoning, become MITM gateway -│ │ ├── dns_poison.py # DNS response injection, redirect queries -│ │ ├── dhcp_spoof.py # Rogue DHCP to set implant as gateway/DNS -│ │ ├── evil_twin.py # Rogue AP with captive portal -│ │ ├── ipv6_slaac.py # IPv6 SLAAC spoofing, become IPv6 gateway -│ │ ├── responder_mgr.py # Manage Responder process (LLMNR/NBT-NS/mDNS poisoning) -│ │ ├── ssl_downgrade.py # sslstrip for legacy apps (opt-in, HSTS warning) -│ │ ├── http_logger.py # Log every URL, header, POST body, cookie (requires MITM) -│ │ ├── file_extractor.py # Carve files from HTTP/SMB/FTP traffic in real-time -│ │ ├── session_hijacker.py # Capture cookies, session tokens, JWT from intercepted traffic -│ │ ├── js_injector.py # Inject keyloggers or BeEF hooks into HTTP responses -│ │ ├── mitmproxy_mgr.py # Full HTTPS interception with generated certs -│ │ ├── ntlm_relay.py # ntlmrelayx integration, coordinated with Responder -│ │ └── cloud_token_active.py # Extract tokens from MITM'd HTTPS traffic +│ │ ├── bettercap_mgr.py # Central bettercap orchestrator (REST API) +│ │ ├── arp_spoof.py # Thin wrapper → bettercap_mgr arp.spoof +│ │ ├── dns_poison.py # Thin wrapper → bettercap_mgr dns.spoof +│ │ ├── dhcp_spoof.py # Thin wrapper → bettercap_mgr dhcp6.spoof +│ │ ├── evil_twin.py # hostapd + dnsmasq (unchanged) +│ │ ├── ipv6_slaac.py # bettercap dhcp6.spoof + mitm6 +│ │ ├── responder_mgr.py # Responder subprocess wrapper +│ │ ├── mitmproxy_mgr.py # mitmproxy subprocess wrapper (uses addon scripts) +│ │ └── ntlm_relay.py # ntlmrelayx subprocess wrapper │ │ -│ ├── connectivity/ +│ ├── connectivity/ # 8 modules (unchanged) │ │ ├── __init__.py -│ │ ├── tailscale.py # Tailscale lifecycle, auth, health -│ │ ├── wireguard.py # WireGuard tunnel management -│ │ ├── bridge.py # Transparent inline bridge (USB eth + onboard) -│ │ ├── wifi_client.py # WiFi client mode, network selection -│ │ ├── reverse_tunnel.py # SSH reverse tunnel fallback -│ │ ├── cellular_backup.py # LTE modem HAT for out-of-band access (optional) -│ │ ├── ble_emergency.py # BLE emergency access channel (optional) -│ │ └── data_exfil.py # Automated data exfiltration pipeline +│ │ ├── tailscale.py +│ │ ├── wireguard.py +│ │ ├── bridge.py +│ │ ├── wifi_client.py +│ │ ├── reverse_tunnel.py +│ │ ├── cellular_backup.py +│ │ ├── ble_emergency.py +│ │ └── data_exfil.py │ │ -│ ├── stealth/ +│ ├── stealth/ # 12 modules (unchanged, expanded scope) │ │ ├── __init__.py -│ │ ├── mac_manager.py # MAC randomization / cloning -│ │ ├── process_disguise.py # Process name/cmdline spoofing -│ │ ├── log_suppression.py # Syslog filtering, audit rule injection -│ │ ├── encrypted_storage.py # LUKS container management -│ │ ├── tmpfs_manager.py # tmpfs mounts for sensitive ops -│ │ ├── watchdog.py # Health monitoring, auto-restart services -│ │ ├── anti_forensics.py # Timestomp, secure deletion -│ │ ├── traffic_mimicry.py # 48h baseline + behavioral blending -│ │ ├── ja3_spoofer.py # JA3/JA3S TLS fingerprint matching -│ │ ├── ids_tester.py # Test actions against known IDS rulesets -│ │ ├── lkm_rootkit.py # Optional LKM for process/file/net hiding (compromised host only) -│ │ └── overlayfs_manager.py # SD card wear protection via overlayfs +│ │ ├── mac_manager.py # Innocuous MAC profile database + DHCP/TCP spoofing +│ │ ├── process_disguise.py # Disguises bettercap/tcpdump + Python processes +│ │ ├── log_suppression.py +│ │ ├── encrypted_storage.py +│ │ ├── tmpfs_manager.py +│ │ ├── watchdog.py # Manages bettercap/tcpdump/Responder + Python modules +│ │ ├── anti_forensics.py +│ │ ├── traffic_mimicry.py +│ │ ├── ja3_spoofer.py # Applied to bettercap + mitmproxy outbound +│ │ ├── ids_tester.py # Also checks bettercap caplet actions vs IDS rules +│ │ ├── lkm_rootkit.py # Hides bettercap/tcpdump binaries + Python processes +│ │ └── overlayfs_manager.py │ │ -│ └── intel/ +│ └── intel/ # 8 modules │ ├── __init__.py -│ ├── credential_db.py # SQLite credential store (all captured creds organized) -│ ├── topology_mapper.py # Network graph construction, Graphviz export -│ ├── 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 -│ ├── 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) -│ ├── bigbrother-watchdog.service # Watchdog / auto-recovery -│ ├── bigbrother-capture.service # Packet capture (passive) -│ ├── bigbrother-passive.service # All passive surveillance modules -│ ├── bigbrother-bridge.service # Transparent bridge -│ └── bigbrother-tailscale.timer # Tailscale health check timer -│ -├── templates/ -│ ├── captive_portals/ -│ │ ├── corporate_login.html # Corporate WiFi login mimic -│ │ ├── guest_wifi.html # Guest WiFi terms page -│ │ ├── outlook_login.html # O365 login clone -│ │ └── vpn_portal.html # VPN portal clone -│ ├── dns_zones/ -│ │ ├── redirect_all.zone # Wildcard DNS redirect -│ │ └── selective.zone.j2 # Jinja2 template for targeted DNS -│ ├── hostapd/ -│ │ ├── open.conf.j2 # Open AP config -│ │ └── wpa2.conf.j2 # WPA2 AP config -│ ├── responder/ -│ │ └── Responder.conf.j2 # Responder config template -│ ├── beef/ -│ │ └── hook.js.j2 # BeEF hook injection template -│ └── lkm/ -│ ├── bb_hide.c # Kernel module source -│ └── Makefile # Build for target kernel version +│ ├── credential_db.py # Central cred store (bettercap/Responder/mitmproxy ingestion) +│ ├── topology_mapper.py +│ ├── net_intel.py # Beacon/C2 detection +│ ├── user_timeline.py +│ ├── supply_chain_detect.py +│ ├── change_detector.py +│ ├── security_posture.py +│ ├── operator_audit.py +│ └── tool_output_parser.py # Unified parsing: bettercap events, Responder logs, mitmproxy flows │ ├── utils/ │ ├── __init__.py -│ ├── crypto.py # AES-256-GCM encryption, key derivation, wipe -│ ├── networking.py # Interface enumeration, IP helpers, raw sockets -│ ├── logging.py # Encrypted rotating log, memory-only option -│ ├── stealth.py # OPSEC helpers (timing jitter, traffic shaping) -│ ├── resource.py # Memory/CPU profiling, Pi Zero limits -│ ├── permissions.py # Capability checks, privilege escalation -│ └── config_loader.py # YAML config parser with validation + defaults +│ ├── crypto.py +│ ├── networking.py +│ ├── logging.py +│ ├── stealth.py +│ ├── resource.py +│ ├── permissions.py +│ ├── config_loader.py +│ └── bettercap_api.py # bettercap REST API client │ ├── data/ -│ ├── oui.db # MAC OUI database (SQLite, compressed) +│ ├── oui.db # MAC OUI database (SQLite) │ ├── 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 +│ ├── dhcp_fingerprints.db # DHCP option 55 fingerprints (Fingerbank) +│ ├── innocuous_macs.db # Innocuous consumer device MAC profiles +│ ├── ids_rules/ │ │ ├── emerging-threats.rules │ │ └── snort-community.rules -│ ├── ja3_fingerprints.db # Known JA3 hashes for common browsers -│ ├── wordlists/ # Pre-bundled for on-device cracking -│ │ ├── rockyou.txt.gz # Classic password list -│ │ ├── top-1m-passwords.txt # SecLists top-1M -│ │ └── rules/ # Hashcat rules +│ ├── ja3_fingerprints.db +│ ├── wordlists/ +│ │ ├── rockyou.txt.gz +│ │ ├── top-1m-passwords.txt +│ │ └── rules/ │ │ ├── OneRuleToRuleThemAll.rule │ │ └── dive.rule │ └── bpf_filters/ -│ ├── credentials.bpf # BPF for credential protocols -│ ├── dns.bpf # BPF for DNS traffic -│ ├── discovery.bpf # BPF for discovery traffic -│ └── full_capture.bpf # BPF for full capture (minus noise) +│ ├── credentials.bpf +│ ├── dns.bpf +│ ├── discovery.bpf +│ └── full_capture.bpf +│ +├── services/ +│ ├── bigbrother-core.service +│ ├── bigbrother-watchdog.service +│ ├── bigbrother-capture.service +│ ├── bigbrother-passive.service +│ ├── bigbrother-bridge.service +│ └── bigbrother-tailscale.timer +│ +├── templates/ +│ ├── captive_portals/ +│ │ ├── corporate_login.html +│ │ ├── guest_wifi.html +│ │ ├── outlook_login.html +│ │ └── vpn_portal.html +│ ├── dns_zones/ +│ │ ├── redirect_all.zone +│ │ └── selective.zone.j2 +│ ├── hostapd/ +│ │ ├── open.conf.j2 +│ │ └── wpa2.conf.j2 +│ ├── responder/ +│ │ └── Responder.conf.j2 +│ └── lkm/ +│ ├── bb_hide.c +│ └── Makefile +│ +├── scripts/ +│ ├── setup_bridge.sh +│ ├── teardown_bridge.sh +│ ├── build_lkm.sh +│ └── operator/ # Operator workstation scripts +│ ├── pull_data.sh # rsync structured data over Tailscale/WG +│ ├── extract_files.sh # tshark + NetworkMiner batch file extraction +│ ├── extract_print_jobs.sh # TCP/9100 → pcl2pdf reconstruction +│ ├── extract_emails.sh # SMTP from PCAPs → tshark reconstruction +│ ├── crack_hashes.sh # Export creds → hashcat format, run wordlists +│ └── generate_report.py # Pull SQLite DBs, generate Markdown + HTML report │ ├── tests/ │ ├── __init__.py -│ ├── test_engine.py # Module lifecycle tests -│ ├── test_bus.py # Event bus tests -│ ├── test_crypto.py # Encryption/wipe tests -│ ├── test_modules.py # Module interface compliance tests -│ ├── test_resource.py # Resource constraint tests -│ └── conftest.py # Pytest fixtures -│ -├── scripts/ -│ ├── setup_bridge.sh # Bridge interface setup -│ ├── teardown_bridge.sh # Bridge interface teardown -│ └── build_lkm.sh # Compile rootkit LKM for target kernel +│ ├── test_engine.py +│ ├── test_bus.py +│ ├── test_crypto.py +│ ├── test_modules.py +│ ├── test_resource.py +│ ├── test_tool_manager.py +│ ├── test_bettercap_mgr.py +│ └── conftest.py │ └── storage/ # Runtime data (gitignored, LUKS-encrypted) - ├── config/ # Sensitive config (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 - ├── emails/ # Captured email content + attachments - ├── files/ # Carved files from traffic - ├── voip/ # SIP metadata + RTP audio captures - ├── 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 + ├── config/ # Sensitive config (inside LUKS) + ├── pcaps/ # tcpdump rotated captures (zstd + AES) + ├── creds/ + ├── dns_logs/ + ├── sni_logs/ + ├── intel/ + ├── baseline/ + ├── audit/ + ├── tool_logs/ # bettercap, Responder, mitmproxy output + └── logs/ ``` --- -## 3. Surveillance Modules +## 4. Passive Modules -### 3.1 Passive Surveillance (24/7, zero noise, unsupervised) - -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). +16 modules. Custom Python for lightweight structured metadata extraction. All receive packets via capture_bus (one AF_PACKET socket, demuxed to per-module queues). Zero network noise. --- -#### `modules/passive/packet_capture.py` — Full Packet Capture +### `packet_capture.py` -- tcpdump Wrapper -**Purpose**: Capture all network traffic to encrypted rotating PCAPs for offline analysis. +Manages tcpdump subprocess for full packet capture. tcpdump handles BPF, rotation, snap length, PcapNG. Wrapper adds post-rotation compression, encryption, disk management. -- Promiscuous mode on bridge or tap interface -- BPF filters: full capture, credentials-only, DNS-only, or custom -- PCAP rotation: size-based (100MB uncompressed default) or time-based (1h default) -- **Max compression pipeline on rotation**: zstd level 19 (max) → AES-256-GCM encrypt → .pcap.zst.enc - - zstd -19 achieves 10-15x compression on typical network PCAPs (100MB → 7-10MB) - - On 128GB SD: ~1.2TB effective PCAP storage (days of full capture on busy networks) - - Compressed files dramatically faster to exfil when operator pulls data over Tailscale/WG - - Decompression on operator's workstation: `zstd -d` then open in Wireshark - - CPU cost: zstd -19 on Pi 4 compresses at ~5-10MB/s (runs as background task after rotation, not inline) - - Pi Zero: use zstd -3 (fast mode, still 5-8x compression, minimal CPU) -- **Full packet capture (snap_length=65535) on all tiers.** With 128GB+ SD and zstd -19 compression (10-15x), effective storage is ~1.2TB. Full payloads are required for file carving, email reconstruction, print job extraction, database query capture, and credential extraction from protocol payloads. Headers-only would blind most surveillance modules. -- Pi Zero 2W: full capture still applies but with fewer concurrent modules to stay within memory budget. Compression downgraded to zstd -3 to reduce CPU load. -- Disk usage monitoring — auto-purge oldest PCAPs when threshold hit (bulk first, credential ring preserved) -- PcapNG format support for metadata embedding (interface info, comments, timestamps) +- **tcpdump flags**: `-i -G 3600 -W 168 -s 65535 -w --time-stamp-precision=nano` +- **Post-rotation pipeline**: zstd -19 compress -> AES-256-GCM encrypt -> `.pcap.zst.enc` + - Pi Zero: zstd -3 (fast mode, 5-8x compression, minimal CPU) + - Pi 4/Debian: zstd -19 (max, 10-15x compression on typical PCAPs) +- Disk monitoring: auto-purge oldest PCAPs when threshold hit (85% default) +- PcapNG format for metadata embedding +- **Managed by tool_manager.py**: auto-restart on crash within 5s, PID tracking -**Resources**: RAM 30-80MB (snap length dependent), CPU 5-15% capture + compression spikes on rotation, disk varies -**Dependencies**: libpcap, scapy, zstandard (Python binding) +**Resources**: tcpdump 5MB RAM, 2-5% CPU. Compression spikes post-rotation. +**Dependencies**: tcpdump, zstandard (Python) --- -#### `modules/passive/dns_logger.py` — DNS Query Logger +### `dns_logger.py` -- DNS Query Logger -**Purpose**: Build per-host browsing history from DNS queries. Every domain every host resolves, timestamped. +Per-host browsing history from DNS queries. BPF filter on UDP/53, parse query/response, batch insert to SQLite. -- Capture DNS queries and responses (UDP/53, TCP/53) -- Per-source-IP log: timestamp, queried domain, response IPs, query type -- 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) +- Per-source-IP log: timestamp, domain, response IPs, query type +- Flag DoH resolver connections (1.1.1.1, 8.8.8.8, 9.9.9.9) -- DNS blind spot indicator +- Batch: buffer 1000 records, flush every 60s -**Resources**: RAM 15MB, CPU 2%, disk 5MB/day typical +**Resources**: 15MB RAM, 2% CPU, 5MB/day disk **Dependencies**: scapy or dpkt --- -#### `modules/passive/tls_sni_extractor.py` — TLS SNI Extractor +### `tls_sni_extractor.py` -- TLS SNI Extractor -**Purpose**: Log every HTTPS destination without decryption, from the ClientHello SNI field. +Parse TLS ClientHello on TCP/443+, extract SNI field. Correlate with DNS logs. Log: timestamp, source IP, dest IP:port, SNI hostname, TLS version. ECH/ESNI returns CDN dummy SNI (no passive mitigation). QUIC SNI handled by `quic_analyzer.py`. -- Parse TLS ClientHello from TCP/443 (and other TLS ports) -- 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. ECH requires full TLS interception to defeat. -- **DoH blind spot**: DNS-over-HTTPS to hardcoded resolvers (1.1.1.1, 8.8.8.8) bypasses dns_logger entirely — 30-70% of endpoint DNS may be encrypted. Internal AD DNS to domain controllers remains visible on UDP/53. When in MITM position, block DoH resolver IPs and strip HTTPS DNS records (type 65) to force plaintext fallback. -- **TLS 1.3**: Server certificates encrypted during handshake — passive cert extraction impossible. Rely on SNI (while available) and CT logs. -- 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**: 10MB RAM, 2% CPU, 3MB/day disk **Dependencies**: scapy or dpkt --- -#### `modules/passive/credential_sniffer.py` — Credential Sniffer +### `credential_sniffer.py` -- Credential Sniffer -**Purpose**: Extract credentials from cleartext protocols and NTLM/Kerberos authentication. +Real-time credential extraction with immediate bus notification + credential_db insert. Scope: FTP USER/PASS, HTTP Basic/Digest/form POST, SNMP community, LDAP simple bind, NTLMv1/v2 challenge-response. Auto-push hashes to operator's cracking rig via data_exfil. -- **Cleartext**: FTP (USER/PASS), HTTP Basic/Digest, HTTP form POST, SMTP AUTH, POP3 USER/PASS, IMAP LOGIN, Telnet, SNMP community strings, LDAP simple bind -- **NTLM**: Extract NTLMv1/v2 challenge-response from SMB, HTTP NTLM, LDAP NTLM, MSSQL NTLM -- **Kerberos**: Extract encrypted timestamps from AS-REQ (password spray targets) -- **Realistic yield**: On modern networks (85-95% encrypted), cleartext protocols yield near-zero in passive mode. SMTP is universally STARTTLS. Primary passive value is NTLM/Kerberos from wire. Cleartext sniffer becomes high-value only with active MITM position. -- Output: hashcat-compatible format, stored in credential_db -- Publishes CREDENTIAL_FOUND events on bus -- Auto-queue captured hashes for CPU-mode john/hashcat in low-priority cgroup; push hashes immediately to operator's cracking rig via data_exfil for GPU cracking - -**Resources**: RAM 20MB, CPU 3%, disk 5MB -**Dependencies**: scapy, impacket (for NTLM/Kerberos parsing) - ---- - -#### `modules/passive/kerberos_harvester.py` — Kerberos Ticket Harvester - -**Purpose**: Extract Kerberos tickets from network traffic for offline cracking. - -- **AS-REQ**: Extract encrypted timestamps (hashcat mode 7500) -- **AS-REP**: Extract hashes for accounts without pre-auth (hashcat mode 18200) — AS-REP roasting from the wire -- **TGS-REQ**: Log SPN requests — reveals what services users access -- **TGS-REP**: Extract service ticket hashes (hashcat mode 13100) — Kerberoasting from the wire -- Identify domain controllers, realm names, user principal names -- Feed all hashes into credential_db - -**Resources**: RAM 15MB, CPU 3%, disk 10MB +**Resources**: 15MB RAM, 3% CPU **Dependencies**: scapy, impacket --- -#### `modules/passive/host_discovery.py` — Host Discovery +### `kerberos_harvester.py` -- Kerberos Ticket Harvester -**Purpose**: Build complete host inventory from passive network observation. +Extract tickets from wire for offline cracking. AS-REP (mode 18200), TGS-REP (mode 13100), AS-REQ encrypted timestamps (mode 7500). Identify DCs, realm names, UPNs. Immediate exfil -- tickets expire. -- 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 + DHCP fingerprint +**Resources**: 15MB RAM, 3% CPU +**Dependencies**: scapy, impacket -**Resources**: RAM 15MB, CPU 2%, disk 5MB +--- + +### `host_discovery.py` -- Host Discovery + +Build host inventory from passive observation. ARP table, DHCP request/ACK (hostname, vendor class), DHCP option 55 fingerprinting via `data/dhcp_fingerprints.db`, mDNS/Bonjour, NetBIOS, SSDP/UPnP, NBNS/LLMNR. Correlate: IP + MAC + hostname + vendor (OUI) + OS guess + DHCP fingerprint. + +**Resources**: 15MB RAM, 2% CPU **Dependencies**: scapy, data/oui.db, data/dhcp_fingerprints.db --- -#### `modules/passive/os_fingerprint.py` — Passive OS Fingerprinting +### `os_fingerprint.py` -- Passive OS Fingerprinting -**Purpose**: Identify operating systems without sending any probes. p0f-style. +p0f-style: TCP SYN/SYN-ACK analysis (window size, TTL, DF, MSS, SACK, timestamps), HTTP User-Agent, DHCP vendor class, SMB dialect, SSH version strings. Confidence scoring per host. -- TCP SYN/SYN-ACK analysis: window size, TTL, DF flag, MSS, window scaling, SACK, timestamps -- HTTP User-Agent header extraction -- DHCP vendor class identifier -- SMB dialect negotiation -- SSH version strings -- Confidence scoring per host, multiple evidence sources - -**Resources**: RAM 10MB, CPU 2%, disk 2MB +**Resources**: 10MB RAM, 2% CPU **Dependencies**: scapy, data/os_sigs.db --- -#### `modules/passive/traffic_analyzer.py` — Traffic Analyzer +### `traffic_analyzer.py` -- Traffic Analyzer -**Purpose**: Protocol distribution, flow analysis, bandwidth monitoring, beacon detection. +Protocol distribution, flow tracking (5-tuple), top talkers, beacon detection (regular-interval C2/heartbeats), bandwidth profiling. Feeds traffic_mimicry baseline. -- Protocol breakdown: percentage by packet count and bytes -- Flow tracking: 5-tuple flows, duration, bytes transferred -- Top talkers: hosts by volume, connections, protocol diversity -- Beacon detection: regular-interval communications that suggest C2, heartbeats, or update checks -- Bandwidth profiling: hourly/daily patterns, anomaly detection -- Communication graphs: source-destination pairs with protocol and volume edges - -**Resources**: RAM 25-60MB (flow table size), CPU 5%, disk 10MB +**Resources**: 25MB RAM (flow table), 5% CPU **Dependencies**: scapy --- -#### `modules/passive/vlan_discovery.py` — VLAN Discovery +### `vlan_discovery.py` -- VLAN Discovery -**Purpose**: Map VLAN topology from passive observation. +802.1Q tag detection, DTP frame capture, 802.1X/EAPOL detection, CDP/LLDP parsing (switch names, ports, VLANs), STP BPDU parsing (root bridge ID). -- 802.1Q tag detection — identify VLANs in use -- DTP frame capture — detect trunk negotiation -- 802.1X/EAPOL frame detection — identify NAC-protected ports -- CDP/LLDP frame parsing — switch names, port IDs, VLAN assignments -- STP BPDU parsing — switch topology, root bridge identification - -**Resources**: RAM 10MB, CPU 1%, disk 2MB -**Dependencies**: scapy +**Resources**: 10MB RAM, 1% CPU --- -#### `modules/passive/network_mapper.py` — Network Relationship Mapper +### `network_mapper.py` -- Network Relationship Mapper -**Purpose**: Build a comprehensive map of who talks to whom, how much, and over what protocols. Visual graph output. +Communication graph: all pairs with protocol/volume metadata. Identify servers vs clients, admin workstations (SSH/RDP to many hosts), printer relationships. Graphviz DOT output. Periodic snapshots for change_detector. -- Track all communication pairs with protocol and volume metadata -- Identify servers (many inbound connections) vs clients (many outbound) -- Detect admin workstations (SSH/RDP to many hosts) -- Map printer relationships, file server access patterns -- Graphviz DOT output for topology visualization -- Periodic snapshots for change detection - -**Resources**: RAM 20MB, CPU 3%, disk 5MB -**Dependencies**: scapy, graphviz (for rendering) +**Resources**: 15MB RAM, 3% CPU --- -#### `modules/passive/auth_flow_tracker.py` — Authentication Flow Tracker +### `auth_flow_tracker.py` -- Authentication Flow Tracker -**Purpose**: Map who authenticates to what services and when, building per-user activity timelines. +Cross-protocol auth correlation: Kerberos TGT (AS-REQ), service tickets (TGS-REQ), NTLM across SMB/HTTP/LDAP/MSSQL, SSH connections, LDAP binds. Per-user timeline. Identify service accounts. -- Track Kerberos TGT requests (AS-REQ) — user login events -- Track Kerberos service ticket requests (TGS-REQ) — service access -- Track NTLM authentication across protocols (SMB, HTTP, LDAP, MSSQL) -- Track SSH connection establishment -- Track LDAP binds -- Build per-user timeline: login time, services accessed, duration patterns -- Identify service accounts (authenticate to many hosts, regular intervals) - -**Resources**: RAM 15MB, CPU 2%, disk 5MB +**Resources**: 15MB RAM, 2% CPU **Dependencies**: scapy, impacket --- -#### `modules/passive/smb_monitor.py` — SMB File Access Monitor +### `smb_monitor.py` -- SMB File Access Monitor -**Purpose**: Track file share access patterns — which users access which shares and files. +SMB2/3 tree connect + create request parsing. Track share/file access per user. Log: timestamp, user, source IP, share, file path, operation. Detect GPP/SYSVOL access patterns. SMB3 encrypted payload is opaque without MITM. -- Parse SMB2/3 tree connect requests — which shares are accessed -- Parse SMB2/3 create requests — which files are opened -- Track read/write operations per user per share -- Identify sensitive shares (SYSVOL, NETLOGON, C$, ADMIN$, custom shares) -- Log: timestamp, user, source IP, share name, file path, operation -- Detect GPP/Group Policy access patterns -- **SMB3 limitation**: Windows Server 2022 and Windows 11 default to SMB 3.1.1 with AES encryption. Negotiate/session setup (capabilities, NTLM) is visible but encrypted payload is opaque. File access monitoring requires active MITM with SMB downgrade. - -**Resources**: RAM 15MB, CPU 2%, disk 5MB +**Resources**: 15MB RAM, 2% CPU **Dependencies**: scapy, impacket --- -#### `modules/passive/voip_capture.py` — VoIP/SIP Metadata Capture +### `cloud_token_harvester.py` -- Cloud Token Harvester (Passive) -**Purpose**: Capture call records, participants, duration. Optionally capture RTP audio if unencrypted. +Regex for AWS keys (AKIA*), JWT, OAuth tokens, SAML assertions in cleartext HTTP. Near-zero yield on most networks but zero-cost to run. Feed to credential_db. -- Parse SIP INVITE/BYE/CANCEL — call setup and teardown -- Extract: caller, callee, call-ID, codec, duration -- Track RTP streams associated with SIP sessions -- If RTP is unencrypted: capture audio to WAV files -- If SRTP: log metadata only (cannot decrypt) -- Detect VoIP infrastructure (PBX, SBC, trunks) - -**Resources**: RAM 20MB + audio storage, CPU 3%, disk varies (audio intensive) -**Dependencies**: scapy, wave (stdlib) +**Resources**: 10MB RAM, 2% CPU --- -#### `modules/passive/print_interceptor.py` — Print Job Interceptor +### `ldap_harvester.py` -- LDAP Query Harvester -**Purpose**: Capture print spool data from network print traffic. +Parse LDAP SearchRequest/SearchResponse on 389/3268. Extract: base DN, search filter, result entries. Build inventory: users, groups, computers, GPOs, SPNs. Detect LAPS password reads. Feed to topology_mapper. -- Capture RAW print data (TCP/9100 — JetDirect/AppSocket) -- Capture LPD print data (TCP/515) -- Capture IPP print data (TCP/631) -- Extract PCL and PostScript content -- Convert to PDF where possible (Ghostscript) -- Log: timestamp, source IP, printer IP, job size, content preview - -**Resources**: RAM 15MB, CPU 2%, disk varies (print job size) -**Dependencies**: scapy, ghostscript (optional, for PDF conversion) - ---- - -#### `modules/passive/wireless_intel.py` — Wireless Intelligence - -**Purpose**: Probe request collection, BLE scanning, WPA handshake capture, WIDS detection. - -- Monitor mode on WiFi interface (requires capable adapter) -- Probe request collection — reveals client preferred network history -- BLE scanning — identify phones, badges, IoT devices -- WPA 4-way handshake passive capture from legitimate connections -- WIDS detection — identify wireless IDS by monitoring for correlation patterns (run 2-hour observation before allowing evil_twin) -- Publishes HANDSHAKE_CAPTURED events -- **Interface conflict**: Monitor mode on wlan0 and wifi_client managed mode are mutually exclusive on same interface. Requires explicit second USB WiFi adapter for concurrent monitor+client. engine.py detects and prevents conflicting modes. - -**Resources**: RAM 20MB, CPU 3%, disk 10MB -**Dependencies**: scapy, aircrack-ng (for monitor mode), bluez (for BLE) - ---- - -#### `modules/passive/protocol_analyzer.py` — Protocol Deep Analyzer - -**Purpose**: Zeek-style protocol dissection, service identification, certificate analysis. - -- Protocol identification beyond port numbers (payload heuristics) -- Service banner extraction: version strings, server headers -- TLS certificate analysis: SANs, issuers, expiry, chain validation -- OT protocol detection: Modbus (502), DNP3 (20000), OPC UA (4840), S7comm, BACnet, EtherNet/IP -- HTTP/2 and QUIC identification -- Anomaly flagging: unusual protocols, new services, version changes - -**Resources**: RAM 40MB, CPU 5%, disk 20MB -**Dependencies**: scapy, dpkt - ---- - -#### `modules/passive/cloud_token_harvester.py` — Cloud Token Harvester (Passive) - -**Purpose**: Passively extract cloud credentials and tokens from observed traffic. - -- AWS: Access keys (AKIA*), secret keys, session tokens in HTTP headers/bodies -- Azure: Bearer tokens, refresh tokens in HTTP Authorization headers -- GCP: OAuth tokens, service account key patterns -- Generic: JWT tokens (decode header + claims), SAML assertions, OAuth authorization codes -- Only from cleartext protocols or already-decrypted MITM traffic -- Feed into credential_db with cloud provider context - -**Resources**: RAM 15MB, CPU 2%, disk 5MB -**Dependencies**: scapy, pyjwt (for JWT decoding) - ---- - -#### `modules/passive/email_sniffer.py` — Email Sniffer - -**Purpose**: Capture email content and attachments from unencrypted SMTP/IMAP/POP3. - -- Parse SMTP (TCP/25, 587) conversations — extract sender, recipients, subject, body, attachments -- Parse IMAP (TCP/143) FETCH responses — extract email content -- Parse POP3 (TCP/110) RETR responses — extract email content -- Decode MIME multipart, Base64 attachments, quoted-printable -- Store: per-email directory with headers, body text, and attachment files -- Only captures cleartext — encrypted (STARTTLS, SSL) requires MITM position -- **Realistic yield**: SMTP is universally STARTTLS in 2026. Expect near-zero cleartext email capture on modern networks without active MITM. - -**Resources**: RAM 20MB, CPU 3%, disk varies (attachment size) -**Dependencies**: scapy, email (stdlib) - ---- - -#### `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 +**Resources**: 15MB RAM, 3% CPU **Dependencies**: scapy, impacket --- -#### `modules/passive/quic_analyzer.py` — QUIC/HTTP3 SNI Extractor +### `rdp_monitor.py` -- RDP Session Monitor -**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 RDP NLA headers on TCP/3389: username, domain, client hostname, keyboard layout. Parse CredSSP for NTLM/Kerberos auth. Track admin-to-server session patterns. -- 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 +**Resources**: 10MB RAM, 2% CPU **Dependencies**: scapy, impacket --- -### 3.2 Active Surveillance (operator-enabled, then runs unattended) +### `quic_analyzer.py` -- QUIC/HTTP3 SNI Extractor -These modules require explicit operator activation. Once configured and started, they run without further interaction. +Parse QUIC Initial packets (RFC 9000) on UDP/443. Decrypt Initial payload using connection ID-derived keys (per RFC 9001, not secret). Extract CRYPTO frames containing TLS ClientHello, parse SNI. Feed into tls_sni_extractor log format. + +**Resources**: 10MB RAM, 2% CPU --- -#### `modules/active/arp_spoof.py` — ARP Spoofing +### `db_interceptor.py` -- Database Protocol Interceptor -**Purpose**: Become the man-in-the-middle by poisoning ARP caches. All target traffic flows through the implant. +Parse login packets and query metadata (not full result sets): +- **MSSQL TDS** (1433): login (username, hostname, app), SQL batch headers +- **MySQL** (3306): handshake, login, query packets +- **PostgreSQL** (5432): startup (user, database), query protocol +- **Redis** (6379): AUTH commands, key operations +- **MongoDB** (27017): OP_MSG auth and find operations -> **OPSEC WARNING**: ARP spoofing is the most-detected active technique. DAI on managed switches silently prevents it. EDR agents (CrowdStrike, SentinelOne, Defender ATP) alert on ARP cache anomalies within minutes. ARPwatch and Wazuh agents generate immediate alerts. Even with rate-limiting and jitter, ARP spoof against EDR-protected endpoints is detected. **Prefer Responder + ipv6_slaac as primary credential capture.** Reserve ARP spoof for confirmed legacy segments with no DAI/EDR. Run ids_tester DAI probe before activation. +Query content analysis from PCAPs offline. -- Gratuitous ARP replies to targets, impersonating gateway -- Gratuitous ARP replies to gateway, impersonating targets -- IP forwarding enabled to maintain connectivity -- Target list: specific hosts (not full subnet — less noise) -- Rate-limited ARP replies with jitter -- Restore original ARP entries on stop -- **Crash recovery**: Kernel-level ARP restoration — cron job every 30s checks arp_spoof PID, sends gratuitous ARP corrections if process is dead. Prevents spoofed targets from losing gateway connectivity (1-5 min ARP timeout) on crash. - -**Resources**: RAM 10MB, CPU 2% -**Dependencies**: scapy, iptables +**Resources**: 20MB RAM, 3% CPU +**Dependencies**: scapy, impacket --- -#### `modules/active/dns_poison.py` — DNS Poisoning +## 5. Active Modules -**Purpose**: Redirect DNS queries to capture credentials or redirect users to cloned sites. - -- DNS response injection — race legitimate DNS server -- Selective targeting: specific domains only, forward everything else -- Redirect to captive portal (credential capture) -- Redirect to cloned services (phishing) -- Wildcard mode (redirect all) or targeted mode (redirect specific domains) -- Jinja2 zone templates for flexible configuration - -**Resources**: RAM 10MB, CPU 2% -**Dependencies**: scapy, dnslib +8 modules. bettercap_mgr is the central orchestrator. Individual attack modules are thin wrappers that call bettercap's REST API. Responder, mitmproxy, and ntlmrelayx remain as direct subprocess wrappers. --- -#### `modules/active/dhcp_spoof.py` — DHCP Spoofing +### `bettercap_mgr.py` -- bettercap Orchestrator -**Purpose**: Rogue DHCP server to set implant as gateway and/or DNS server for new clients. +Central manager for the single bettercap instance. All active MITM operations route through this. -- Respond to DHCP DISCOVER before legitimate server (race condition) -- Set implant IP as default gateway — all traffic routes through implant -- Set implant IP as DNS server — all DNS queries visible -- Configurable lease time, subnet mask, DNS settings -- Target specific MACs or respond to all (when scope.yaml loaded, only responds to in-scope MACs) - -**Resources**: RAM 10MB, CPU 1% -**Dependencies**: scapy - ---- - -#### `modules/active/evil_twin.py` — Evil Twin AP - -**Purpose**: Rogue access point with captive portal for credential harvesting. - -> **OPSEC WARNING**: Enterprise WIDS (Cisco, Aruba, Meraki) alerts immediately on any AP advertising a corporate SSID from an unknown BSSID. No evasion is possible — this is structural. Deauth floods are separately detected. 802.11w (protected management frames) prevents deauth entirely. Only viable in environments confirmed to have no WIDS. Run wireless_intel WIDS detection check (2-hour observation) before allowing evil_twin activation. - -- hostapd-based AP matching target SSID -- Open or WPA2 mode -- Captive portal serving credential harvesting pages (corporate login, O365, guest WiFi) -- Optional deauth of target AP to force client migration -- Captured credentials fed to credential_db -- Channel selection to minimize interference - -**Resources**: RAM 30MB, CPU 5% -**Dependencies**: hostapd, dnsmasq, iptables, USB WiFi adapter - ---- - -#### `modules/active/ipv6_slaac.py` — IPv6 SLAAC Spoofing - -**Purpose**: Become IPv6 default gateway via Router Advertisements. Bypasses IPv4-only defenses like DAI. - -- Send Router Advertisement messages with implant as default gateway -- Targets automatically configure IPv6 address and route through implant -- DNS via Router Advertisement — set implant as IPv6 DNS -- Most networks have no IPv6 RA Guard deployed -- Combine with DNS poisoning for credential capture -- Works alongside mitm6 (pre-installed tool) - -**Resources**: RAM 10MB, CPU 2% -**Dependencies**: scapy - ---- - -#### `modules/active/responder_mgr.py` — Responder Manager - -**Purpose**: Manage the Responder process for LLMNR/NBT-NS/mDNS poisoning and NTLMv2 hash capture. - -> **OPSEC WARNING**: Responder poisoning has mature detection coverage. Microsoft Defender for Identity has dedicated LLMNR/NBT-NS poisoning alerts. Suricata ET POLICY rules match poisoning responses. CrowdStrike/SentinelOne alert on NTLM auth to unexpected destinations. Advanced SOCs deploy honeypot LLMNR names. Implement selective targeting: only respond to hostnames never seen in legitimate DNS. Avoid responses during known SOC shift changes. - -- Start/stop/monitor Responder subprocess -- Configure via Responder.conf.j2 template (enable/disable protocols) -- Parse Responder output for captured hashes -- Feed hashes into credential_db automatically -- Coordinate with ntlm_relay for relay attacks -- This manages Responder — operator can also run Responder directly - -**Resources**: RAM 30MB (Responder process), CPU 3% -**Dependencies**: Responder (installed by setup.sh) - ---- - -#### `modules/active/ssl_downgrade.py` — SSL Downgrade - -**Purpose**: sslstrip for legacy applications. Opt-in only. - -- Disabled by default — requires explicit enable in modules.yaml -- Warning on activation about HSTS rendering this mostly ineffective -- Strip HTTPS redirects from HTTP responses -- Only useful against legacy internal apps without HSTS -- For modern HTTPS interception, use mitmproxy_mgr instead - -**Resources**: RAM 15MB, CPU 2% -**Dependencies**: iptables, scapy - ---- - -#### `modules/active/http_logger.py` — HTTP Transaction Logger - -**Purpose**: When in MITM position, log every HTTP transaction: URL, headers, POST body, cookies. - -- Requires active MITM (arp_spoof, dhcp_spoof, or ipv6_slaac running) -- Log full URL including query parameters -- Log request and response headers -- Log POST/PUT body content (form data, JSON, XML) -- Extract and log cookies (session tokens, auth cookies) -- Configurable: log all or filter by content-type/URL pattern - -**Resources**: RAM 20MB, CPU 3%, disk varies -**Dependencies**: scapy or mitmproxy - ---- - -#### `modules/active/file_extractor.py` — File Extractor - -**Purpose**: Carve files from HTTP/SMB/FTP traffic in real-time. - -- Requires MITM position for HTTPS content -- HTTP: reconstruct files from chunked/gzip responses -- SMB: extract files from SMB2/3 read responses -- FTP: capture files from data connections -- Detect file type by magic bytes, store with metadata -- Filter: all files or specific types (documents, executables, archives) - -**Resources**: RAM 40MB, CPU 5%, disk varies heavily -**Dependencies**: scapy, python-magic - ---- - -#### `modules/active/session_hijacker.py` — Session Hijacker - -**Purpose**: Capture cookies, session tokens, and JWT from intercepted traffic. - -- Requires MITM position -- Extract Set-Cookie and Cookie headers from HTTP -- Extract Authorization headers (Bearer tokens, Basic auth) -- Extract JWT tokens from headers, URL parameters, POST bodies -- Parse JWT claims (expiry, scope, user info) -- Store in credential_db with service context and expiry - -**Resources**: RAM 15MB, CPU 2%, disk 5MB -**Dependencies**: scapy, pyjwt - ---- - -#### `modules/active/js_injector.py` — JavaScript/HTML Injection - -**Purpose**: Inject keyloggers or BeEF hooks into HTTP responses when in MITM position. - -- Requires MITM position (HTTP only — HTTPS needs mitmproxy_mgr) -- Inject `