From f959ef89cd202c113398473c049a3c5e0ca9ef71 Mon Sep 17 00:00:00 2001 From: n0mad1k Date: Tue, 17 Mar 2026 10:04:14 -0400 Subject: [PATCH] Rewrite design doc v3.0: surveillance platform + operator jump box Complete rewrite of BIGBROTHER_DESIGN.md with new design philosophy: - Removed autonomous decision engine, state machine, hard scope enforcement - Removed lateral movement automation, tool wrappers, attack chain recipes - Removed push notifications, automated attack chaining, OT lockout - Added 8 new passive surveillance modules: DNS logger, TLS SNI extractor, network relationship mapper, auth flow tracker, SMB file access monitor, VoIP/SIP metadata capture, print job interception, email sniffer - Added 4 new active modules: HTTP transaction logger, file extractor, JS/HTML injection, mitmproxy integration - Added per-user activity timeline intelligence module - Pre-installed tools section (nmap, Certipy, Impacket, BloodHound, CrackMapExec, Chisel, Ligolo-ng, etc.) - installed not wrapped - Simplified to 5 implementation phases from 10 - Operator makes all decisions, no autonomous behavior --- BIGBROTHER_DESIGN.md | 3166 +++++++++++++++++------------------------- 1 file changed, 1237 insertions(+), 1929 deletions(-) diff --git a/BIGBROTHER_DESIGN.md b/BIGBROTHER_DESIGN.md index bb8d203..862ec90 100644 --- a/BIGBROTHER_DESIGN.md +++ b/BIGBROTHER_DESIGN.md @@ -1,95 +1,54 @@ -# BigBrother: Network Implant Architecture — Consolidated Design +# BigBrother: Total Network Surveillance Platform + Operator Jump Box -> **Version**: 2.0 — Post-Tribe Review Consolidated -> **Date**: 2025-03-17 +> **Version**: 3.0 +> **Date**: 2026-03-17 > **Status**: Implementation Blueprint -> **Classification**: OFFENSIVE TOOL — Authorized engagements only --- ## Table of Contents -1. [Architecture Overview](#1-architecture-overview) -2. [Full File Tree](#2-full-file-tree) -3. [Module Specifications](#3-module-specifications) -4. [Module Interaction Model](#4-module-interaction-model) -5. [Autonomous Decision Engine](#5-autonomous-decision-engine) -6. [Setup & Bootstrap](#6-setup--bootstrap) -7. [Systemd Services](#7-systemd-services) -8. [Configuration Schemas](#8-configuration-schemas) -9. [Implementation Phases](#9-implementation-phases) -10. [Hardware Tier Matrix](#10-hardware-tier-matrix) -11. [Detection Risk Matrix](#11-detection-risk-matrix) -12. [Attack Chain Recipes](#12-attack-chain-recipes) -13. [OPSEC Guidelines](#13-opsec-guidelines) -14. [Reliability Safeguards](#14-reliability-safeguards) -15. [Error Handling Strategy](#15-error-handling-strategy) -16. [Key Design Decisions](#16-key-design-decisions) +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) --- -## 1. Architecture Overview +## 1. Overview -BigBrother is a modular network implant 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 architecture follows a pub/sub event bus pattern with strict module isolation, resource budgeting, and layered stealth. +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. -### Core Principles +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. -1. **Stealth-first**: OPSEC layer activates before any network activity -2. **Passive by default**: Sleeper mode generates zero active traffic -3. **Operator-gated escalation**: Active modules require explicit human activation -4. **Resource-aware**: Hard memory/CPU ceilings enforced per hardware tier -5. **Kill switch as first-class citizen**: Cryptographic wipe integrated into every layer -6. **Scope enforcement**: Mandatory — active modules hard-refuse out-of-scope targets -7. **OT/SCADA is PASSIVE ONLY**: Hard lockout on any active interaction with industrial protocols +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. -### Architecture Layers - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ bigbrother.py (CLI + TUI) │ -├─────────────────────────────────────────────────────────────────┤ -│ core/engine.py │ core/bus.py │ core/state.py │ core/scheduler │ -├─────────────────────────────────────────────────────────────────┤ -│ decision/ │ scope/ │ notifications/ │ -│ state_machine.py │ enforcer.py │ push.py │ -│ env_classifier.py │ scope.yaml │ │ -├────────┬────────┬────────┬────────┬────────┬────────┬──────────┤ -│passive/│active/ │ ad/ │ l2l3/ │ exfil/ │stealth/│ intel/ │ -│ │ │ │ │ │ │ │ -│capture │arp_spf │kerbrst │stp_atk │manager │mac_mgr │cred_db │ -│hostdisc│dns_spf │asrep │hsrp │vpn_ch │proc_dis│topology │ -│credsni │ssl_dwn │adcs │ospf │dns_tun │log_sup │report │ -│osfingr │respond │dcsync │ │icmp_tn │encrypt │file_crv │ -│traffic │eviltwin│bloodh │ │http_ch │tmpfs │net_intel│ -│vlandis │dhcp_sp │coerce │ │domain_f│watchdog│ │ -│wireless│nac_byp │ │ │doh_ch │anti_for│ │ -│proto_ │scanner │ │ │stego │lkm_root│ │ -│ analyze│ntlm_rel│ │ │cell_bk │ja3_spf │ │ -│ │lateral │ │ │stager │ids_test│ │ -│ │cloud_ │ │ │ │overlayf│ │ -│ │ harvest│ │ │ │ │ │ -└────────┴────────┴────────┴────────┴────────┴────────┴──────────┘ -``` +Scope is the operator's responsibility. There is no hard scope enforcement layer or OT lockout mechanism in the code. The operator knows their engagement boundaries and operates within them. --- -## 2. Full File Tree +## 2. File Tree ``` ~/tools/bigbrother/ ├── bigbrother.py # Main CLI + interactive menu (Click + Rich) -├── setup.sh # Idempotent Debian bootstrap +├── setup.sh # Idempotent Debian bootstrap (packages + tools) ├── requirements.txt # Python dependencies ├── .gitignore │ ├── config/ │ ├── bigbrother.yaml # Master config (engagement, device, network) │ ├── modules.yaml # Per-module enable/disable + params -│ ├── exfil.yaml # Exfiltration channels config │ ├── stealth.yaml # OPSEC/stealth profile config -│ ├── scope.yaml # Engagement scope definition (MANDATORY) │ ├── hardware_tiers.yaml # Pi Zero 2W vs Pi 4 vs Debian host limits -│ ├── attack_chains.yaml # Pre-built attack chain recipes │ └── templates/ │ ├── engagement_default.yaml # Template for new engagements │ ├── engagement_minimal.yaml # Minimal config for Pi Zero 2W @@ -102,77 +61,49 @@ BigBrother is a modular network implant designed for authorized red team engagem │ ├── bus.py # Internal event bus (pub/sub between modules) │ ├── state.py # Persistent state manager (SQLite) │ ├── resource_monitor.py # RAM/CPU/disk watchdog, throttle enforcement -│ ├── kill_switch.py # Cryptographic wipe orchestrator -│ └── scope_enforcer.py # Mandatory scope validation for all active modules -│ -├── decision/ -│ ├── __init__.py -│ ├── state_machine.py # Autonomous state: DEPLOY→RECON→EXPLOIT→COLLECT→EXFIL→DORMANT -│ ├── env_classifier.py # Environment detection: AD / flat Linux / OT-SCADA / cloud-heavy -│ └── hardening_detector.py # Detect DAI, DHCP snooping, port security, WIDS before attacking +│ └── kill_switch.py # Manual wipe orchestrator │ ├── modules/ │ ├── __init__.py │ ├── base.py # Abstract base class for all modules │ │ -│ ├── passive/ +│ ├── passive/ # 24/7 unsupervised collection │ │ ├── __init__.py -│ │ ├── packet_capture.py # PCAP rotation, BPF filters, promiscuous mode -│ │ ├── host_discovery.py # ARP table, DHCP sniffing, mDNS listener -│ │ ├── credential_sniffer.py # Cleartext protocol credential extraction +│ │ ├── 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, flow analysis, beacon detection -│ │ ├── vlan_discovery.py # 802.1Q tag detection, DTP frames, 802.1X detection -│ │ ├── wireless_intel.py # Probe requests, BLE scanning, WIDS detection [NEW] -│ │ ├── kerberos_harvest.py # Kerberos ticket extraction from traffic [NEW] -│ │ └── protocol_analyzer.py # Deep protocol analysis (Zeek-style), anomaly detection [NEW] +│ │ ├── 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 │ │ -│ ├── active/ +│ ├── active/ # Operator-enabled, then runs unattended │ │ ├── __init__.py -│ │ ├── arp_spoof.py # ARP cache poisoning, gateway impersonation -│ │ ├── dns_spoof.py # DNS response injection, zone serving -│ │ ├── ssl_downgrade.py # sslstrip (OPT-IN ONLY — mostly dead, HSTS kills it) -│ │ ├── responder.py # LLMNR/NBT-NS/mDNS poisoning wrapper -│ │ ├── evil_twin.py # hostapd, captive portal, WPA capture -│ │ ├── dhcp_spoof.py # Rogue DHCP server -│ │ ├── vlan_hop.py # Double-tagging, DTP (DEPRIORITIZED — rarely works) -│ │ ├── ipv6_attack.py # SLAAC spoofing, DHCPv6 rogue -│ │ ├── scanner.py # Nmap wrapper (stealthy defaults) -│ │ ├── packet_inject.py # Raw packet injection (Scapy) -│ │ ├── ntlm_relay.py # ntlmrelayx wrapper + ADCS relay [ENHANCED] -│ │ ├── session_hijack.py # Cookie theft, session token extraction -│ │ ├── file_extractor.py # File carving from live/stored traffic -│ │ ├── email_intercept.py # SMTP/IMAP/POP3 message extraction -│ │ ├── nac_bypass.py # 802.1X/NAC bypass — inline bridge with EAP passthrough [NEW] -│ │ ├── lateral_move.py # Credential-to-access automation, pivoting [NEW] -│ │ └── cloud_harvest.py # AWS/Azure/GCP token harvesting from traffic [NEW] -│ │ -│ ├── ad/ # Active Directory attack suite [NEW] -│ │ ├── __init__.py -│ │ ├── kerberoast.py # Kerberoasting (SPN enumeration + TGS request) -│ │ ├── asrep_roast.py # AS-REP roasting (no pre-auth accounts) -│ │ ├── adcs_attack.py # ADCS/Certipy (ESC1-ESC8 template abuse) -│ │ ├── bloodhound_ingest.py # BloodHound data collection (SharpHound-style) -│ │ ├── dcsync.py # DCSync via replication rights -│ │ └── coerce.py # Authentication coercion (PetitPotam, PrinterBug, DFSCoerce) -│ │ -│ ├── l2l3/ # Layer 2/3 protocol attacks [NEW] -│ │ ├── __init__.py -│ │ ├── stp_attack.py # STP root bridge takeover -│ │ ├── hsrp_takeover.py # HSRP/VRRP/GLBP gateway takeover -│ │ └── ospf_inject.py # OSPF route injection -│ │ -│ ├── exfil/ -│ │ ├── __init__.py -│ │ ├── manager.py # Exfil orchestrator (channel selection, scheduling) -│ │ ├── vpn_channel.py # Tailscale/WireGuard direct exfil (BULK TRANSFER) -│ │ ├── dns_tunnel.py # DNS-based covert channel (iodine/dnscat2) -│ │ ├── icmp_tunnel.py # ICMP-based covert channel -│ │ ├── http_channel.py # HTTP/HTTPS C2 with domain fronting [NEW] -│ │ ├── doh_channel.py # DNS-over-HTTPS covert channel [NEW] -│ │ ├── stego_channel.py # Steganographic exfil (image/audio embedding) [NEW] -│ │ ├── dead_drop.py # Dead drop via cloud storage / paste sites [NEW] -│ │ └── stager.py # Compress, encrypt, chunk, queue +│ │ ├── 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 │ │ │ ├── connectivity/ │ │ ├── __init__.py @@ -180,43 +111,39 @@ BigBrother is a modular network implant designed for authorized red team engagem │ │ ├── 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, DNS tunnel fallback -│ │ ├── cellular_backup.py # LTE modem HAT for out-of-band C2 [NEW] -│ │ └── ble_emergency.py # BLE emergency access channel [NEW] +│ │ ├── 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) │ │ │ ├── stealth/ │ │ ├── __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 (network-derived key option) [ENHANCED] +│ │ ├── encrypted_storage.py # LUKS container management │ │ ├── tmpfs_manager.py # tmpfs mounts for sensitive ops -│ │ ├── watchdog.py # Health monitoring, auto-restart -│ │ ├── anti_forensics.py # Timestamp manipulation, secure deletion [ENHANCED] -│ │ ├── traffic_mimicry.py # 48h baseline + behavioral blending [NEW] -│ │ ├── ja3_spoofer.py # JA3/JA3S TLS fingerprint spoofing [NEW] -│ │ ├── ids_tester.py # Test against common IDS rulesets before going active [NEW] -│ │ ├── lkm_rootkit.py # Optional LKM for process/file/network hiding [NEW] -│ │ └── overlayfs_manager.py # SD card wear protection via overlayfs [NEW] +│ │ ├── 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 │ │ │ └── intel/ │ ├── __init__.py -│ ├── credential_db.py # SQLite credential store (host/service/user/pass) -│ ├── file_carver.py # PCAP file extraction (HTTP, SMB, FTP) +│ ├── 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 [ENHANCED] -│ ├── net_intel.py # Offensive network intel (beacon detect, comm graphing) [NEW] -│ └── supply_chain_detect.py # Internal repos, WSUS, PyPI mirrors (DETECT ONLY) [NEW] -│ -├── notifications/ -│ ├── __init__.py -│ └── push.py # ntfy.sh / webhook push for high-value events [NEW] +│ ├── 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 │ ├── services/ -│ ├── bigbrother-core.service # Main daemon (sleeper mode) +│ ├── bigbrother-core.service # Main daemon (disguised name in production) │ ├── bigbrother-watchdog.service # Watchdog / auto-recovery │ ├── bigbrother-capture.service # Packet capture (passive) -│ ├── bigbrother-discovery.service # Host discovery (passive) +│ ├── bigbrother-passive.service # All passive surveillance modules │ ├── bigbrother-bridge.service # Transparent bridge │ └── bigbrother-tailscale.timer # Tailscale health check timer │ @@ -234,8 +161,10 @@ BigBrother is a modular network implant designed for authorized red team engagem │ │ └── 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 (process/file/net hiding) +│ ├── bb_hide.c # Kernel module source │ └── Makefile # Build for target kernel version │ ├── utils/ @@ -251,13 +180,13 @@ BigBrother is a modular network implant designed for authorized red team engagem ├── data/ │ ├── oui.db # MAC OUI database (SQLite, compressed) │ ├── os_sigs.db # Passive OS fingerprint signatures -│ ├── default_creds.db # Common default credentials -│ ├── ids_rules/ # Snort/Suricata rule snapshots for self-testing [NEW] +│ ├── ids_rules/ # Snort/Suricata rule snapshots for self-testing │ │ ├── emerging-threats.rules │ │ └── snort-community.rules -│ ├── ja3_fingerprints.db # Known JA3 hashes for common browsers [NEW] +│ ├── ja3_fingerprints.db # Known JA3 hashes for common browsers │ └── 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) │ @@ -268,1176 +197,1050 @@ BigBrother is a modular network implant designed for authorized red team engagem │ ├── test_crypto.py # Encryption/wipe tests │ ├── test_modules.py # Module interface compliance tests │ ├── test_resource.py # Resource constraint tests -│ ├── test_scope.py # Scope enforcement tests [NEW] -│ ├── test_state_machine.py # Decision engine tests [NEW] -│ ├── test_nac_bypass.py # NAC bypass tests [NEW] │ └── 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 [NEW] -│ └── gps_geofence.py # GPS geofence checker (if GPS HAT present) [NEW] +│ └── build_lkm.sh # Compile rootkit LKM for target kernel │ └── storage/ # Runtime data (gitignored, encrypted) ├── pcaps/ # Rotated packet captures ├── creds/ # Extracted credentials - ├── exfil_staging/ # Queued exfiltration chunks - ├── intel/ # Analysis outputs - ├── baseline/ # Traffic baseline data (48h capture) [NEW] + ├── 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) └── logs/ # Encrypted operation logs ``` --- -## 3. Module Specifications - -### 3.1 Core Framework - -#### `bigbrother.py` — Main CLI and Interactive Menu - -Single entry point. Click CLI for scripting, Rich TUI for operator use. - -``` -Click Commands: - setup — Run initial configuration wizard - start — Start sleeper mode (all passive modules) - stop — Stop all modules gracefully - status — Show module status, resource usage, connectivity - activate — Activate specific active module by name - deactivate — Deactivate specific active module - exfil — Trigger exfiltration (manual or scheduled) - kill — Execute kill switch - shell — Drop into interactive operator menu - config — View/edit current configuration - creds — Query credential database - intel — Generate intelligence report - bridge — Configure/control transparent bridge - chain — Execute pre-built attack chain recipe [NEW] - baseline — Run 48h traffic baseline capture [NEW] - classify — Run environment classifier [NEW] - scope — View/edit engagement scope [NEW] - -Interactive Menu (Rich-based): - [S] Status Dashboard — Real-time module status, resource gauges - [P] Passive Modules — Sub-menu: start/stop/configure each - [A] Active Modules — Sub-menu: activate/configure/deactivate each - [D] AD Attack Suite — Kerberoast, ADCS, BloodHound, coercion [NEW] - [L] L2/L3 Attacks — STP, HSRP/VRRP, OSPF [NEW] - [E] Exfiltration — Channel status, manual trigger, queue view - [C] Credentials — Browse/search/export captured creds - [I] Intelligence — Topology map, traffic analysis, timeline - [N] Network — Interface status, bridge status, connectivity - [R] Attack Chains — Pre-built attack chain recipes [NEW] - [W] Wireless — Probe reqs, BLE scan, WPA capture [NEW] - [K] Kill Switch — Confirmation + crypto wipe - [Q] Quit - -Key Logic: - - Imports core.engine to manage module lifecycle - - Checks root/capabilities on startup - - Loads config from config/bigbrother.yaml - - VALIDATES scope.yaml exists and is non-empty before allowing active modules - - Resource check before activating modules (reject if insufficient) - - Hardware tier detection — enforces module limits per tier - - All commands are non-interactive when called via CLI (for scripting) - - Traps SIGTERM/SIGINT for graceful shutdown - - Logs all operator actions to encrypted audit trail -``` - -#### `core/engine.py` — Module Lifecycle Manager - -Discovers, loads, starts, stops, and monitors all modules. Central orchestration. - -``` -Classes: - ModuleEngine: - __init__(config, bus, state, scope_enforcer, hardware_tier) - discover_modules() -> dict[str, ModuleInfo] - load_module(name) -> BaseModule - start_module(name, **kwargs) -> bool - - Checks scope_enforcer for active modules - - Checks hardware_tier for module allowance - - Checks resource budget before starting - stop_module(name, graceful=True) -> bool - start_passive_all() -> dict[str, bool] - stop_all(graceful=True) -> dict[str, bool] - get_status() -> dict[str, ModuleStatus] - get_resource_usage() -> ResourceReport - -Key Logic: - - Dependency resolution: modules declare dependencies, engine starts in order - - Resource budgeting: before starting module, check remaining RAM/CPU - - Hardware tier enforcement: Pi Zero 2W gets max 4 passive + 1 active - - Scope validation: active modules must pass scope check - - Process isolation: each module can run in-process or as subprocess - - Graceful degradation: if module fails, others continue - - Thread safety: all state access through locks -``` - -#### `core/scope_enforcer.py` — Mandatory Scope Validation [NEW] - -``` -Classes: - ScopeEnforcer: - __init__(scope_config_path) - load_scope() -> Scope - is_in_scope(target_ip) -> bool - is_in_scope_cidr(cidr) -> bool - validate_targets(targets: list[str]) -> tuple[list[str], list[str]] - - Returns (in_scope, out_of_scope) - enforce(target_ip) -> None - - Raises ScopeViolation if out of scope - - Scope: - networks: list[IPv4Network] # Authorized CIDRs - hosts: list[str] # Individual authorized hosts - exclusions: list[str] # Explicitly excluded (e.g., critical infra) - ot_networks: list[IPv4Network] # OT/SCADA nets — PASSIVE ONLY, hard lockout - wireless_scope: list[str] # Authorized SSIDs/BSSIDs - -Key Logic: - - MANDATORY — engine refuses to start active modules without valid scope - - Every active module calls scope_enforcer.enforce() before targeting - - OT/SCADA networks: any active module targeting these raises HardLockout - - Logged: every scope check logged to audit trail - - Exclusions: critical infrastructure hosts never targeted even if in-scope CIDR -``` - -#### `core/bus.py` — Internal Event Bus - -``` -Event Types (extended): - CREDENTIAL_FOUND HOST_DISCOVERED PCAP_ROTATED - MODULE_STARTED MODULE_STOPPED MODULE_ERROR - EXFIL_READY EXFIL_COMPLETE RESOURCE_WARNING - RESOURCE_CRITICAL KILL_SWITCH CONNECTIVITY_CHANGED - VLAN_DETECTED HANDSHAKE_CAPTURED SCOPE_VIOLATION [NEW] - AD_DOMAIN_FOUND [NEW] TICKET_HARVESTED [NEW] CLOUD_TOKEN_FOUND [NEW] - NAC_DETECTED [NEW] BASELINE_COMPLETE [NEW] HIGH_VALUE_TARGET [NEW] - OT_PROTOCOL_DETECTED [NEW] SUPPLY_CHAIN_FOUND [NEW] - BEACON_DETECTED [NEW] LATERAL_MOVE_SUCCESS [NEW] - PUSH_NOTIFICATION [NEW] -``` - -### 3.2 Decision Engine [NEW] - -#### `decision/state_machine.py` — Autonomous Decision Engine - -``` -States: - DEPLOY — Initial setup, baseline capture, environment classification - RECON — Passive collection, network mapping, credential harvesting - EXPLOIT — Active modules engaged (operator-approved) - COLLECT — Data gathering, lateral movement, deeper access - EXFIL — Staged data exfiltration - DORMANT — Low-power sleep, minimal footprint, periodic check-in - -Transitions (all require operator approval except DEPLOY→RECON): - DEPLOY → RECON : Automatic after baseline + classification complete - RECON → EXPLOIT : Operator approves, sufficient intel gathered - EXPLOIT → COLLECT : Exploitation successful, credentials obtained - COLLECT → EXFIL : Collection targets met or time limit - EXFIL → DORMANT : Exfil complete, await further instructions - DORMANT → RECON : Operator reactivates - ANY → DEPLOY : Operator reset - ANY → (kill) : Kill switch from any state - -Key Logic: - - State persisted to encrypted SQLite (survives reboot) - - Each state has default module set (auto-start/stop on transition) - - Operator can override auto-module selection - - Recommendations surfaced via TUI (e.g., "AD detected, recommend Kerberoast") - - Time-in-state tracking for engagement timeline -``` - -#### `decision/env_classifier.py` — Environment Classifier - -``` -Classes: - EnvironmentClassifier: - classify() -> Environment - - Environment: - type: str # "ad_domain" | "flat_linux" | "ot_scada" | "cloud_heavy" | "mixed" - confidence: float - indicators: list[str] - -Detection Methods: - AD Domain: - - Kerberos traffic (TCP/UDP 88) - - LDAP traffic (389/636) - - DNS SRV records (_ldap._tcp, _kerberos._tcp) - - SMB/CIFS prevalence - - NetBIOS broadcast patterns - Flat Linux: - - SSH prevalence - - Lack of Kerberos/LDAP - - NFS/NIS traffic - - Linux-specific mDNS - OT/SCADA: - - Modbus (502), DNP3 (20000), OPC UA (4840), EtherNet/IP (44818) - - S7comm, BACnet, PROFINET - - *** TRIGGERS PASSIVE-ONLY LOCKOUT *** - Cloud-Heavy: - - AWS/Azure/GCP API endpoints in DNS - - OAuth/SAML/JWT tokens in HTTP traffic - - Cloud provider metadata service traffic (169.254.169.254) - -Key Logic: - - Runs during DEPLOY state on first 30 minutes of passive data - - Results inform which attack modules are recommended - - OT detection immediately locks out active modules for those subnets - - Re-runs periodically (environment can change as more hosts discovered) -``` - -#### `decision/hardening_detector.py` — Network Hardening Assessment [NEW] - -``` -Detects before you attack (avoid detection): - - Dynamic ARP Inspection (DAI): detected via ARP reply patterns - - DHCP Snooping: detected via DHCP ACK behavior - - Port Security: detected via MAC limit behavior - - 802.1X/NAC: detected via EAPOL frames - - WIDS/WIPS: detected via deauth response patterns - - IDS/IPS: inferred from network architecture (span ports, tap placement) - - IPv6 RA Guard: detected via RA response testing - -Output: dict[str, HardeningStatus] - HardeningStatus: detected (bool), confidence (float), safe_to_attack (bool) - -Key Logic: - - Runs BEFORE any active module activation - - Results displayed to operator with risk assessment - - Some detections block corresponding attack module (DAI blocks ARP spoof) - - Operator can override with explicit acknowledgment -``` - -### 3.3 Passive Modules - -#### `modules/passive/wireless_intel.py` — Wireless Intelligence [NEW] - -``` -Classes: - WirelessIntel(BaseModule): - name = "wireless_intel" - category = "passive" - resource_estimate = ResourceEstimate(ram_mb=20, cpu_pct=3, disk_mb=10) - - Methods: - get_probe_requests() -> list[ProbeRequest] - get_ble_devices() -> list[BLEDevice] - get_wpa_handshakes() -> list[Handshake] - detect_wids() -> bool - -Key Logic: - - Monitor mode on WiFi interface (requires capable adapter) - - Probe request collection: reveals client preferred networks (SSID history) - - BLE scanning: identifies phones, badges, IoT (useful for physical awareness) - - WPA handshake passive capture (4-way handshake from legitimate connections) - - WIDS detection: identifies wireless IDS by monitoring for correlation patterns - - Publishes HANDSHAKE_CAPTURED events - BATTLE-TESTED: Probe request collection and WPA capture are well-proven - THEORETICAL: BLE device fingerprinting accuracy varies significantly -``` - -#### `modules/passive/kerberos_harvest.py` — Kerberos Ticket Harvesting [NEW] - -``` -Classes: - KerberosHarvest(BaseModule): - name = "kerberos_harvest" - category = "passive" - resource_estimate = ResourceEstimate(ram_mb=15, cpu_pct=3, disk_mb=10) - -Key Logic: - - Passive extraction of Kerberos AS-REQ/AS-REP from network traffic - - Extracts AS-REP hashes for accounts without pre-auth (hashcat mode 18200) - - Extracts TGS-REP hashes for Kerberoasting (hashcat mode 13100) - - Extracts encrypted timestamps from AS-REQ for password spraying - - Publishes TICKET_HARVESTED events with hashcat-compatible output - - Feed into credential_db for consolidated storage - BATTLE-TESTED: Well-proven technique, used by pcredz and similar tools -``` - -#### `modules/passive/protocol_analyzer.py` — Deep Protocol Analysis [NEW] - -``` -Classes: - ProtocolAnalyzer(BaseModule): - name = "protocol_analyzer" - category = "passive" - resource_estimate = ResourceEstimate(ram_mb=40, cpu_pct=5, disk_mb=20) - -Key Logic: - SOC-grade traffic inspection used offensively: - - Protocol identification beyond port numbers (payload heuristics) - - Beacon detection: regular-interval communications (identifies C2, heartbeats) - - Communication graphing: who talks to whom, how often, how much - - Anomaly detection: new hosts, unusual protocols, volume spikes - - Service identification: extract versions, banners, certificates - - TLS certificate analysis: extract SANs, issuers, expiry - - OT protocol detection: Modbus, DNP3, OPC UA, S7comm, BACnet - *** OT detection triggers PASSIVE-ONLY lockout for those subnets *** - BATTLE-TESTED: Zeek does this well; our implementation is lighter-weight -``` - -### 3.4 Active Modules - -#### `modules/active/nac_bypass.py` — 802.1X/NAC Bypass [NEW — CRITICAL] - -Every review agent flagged this as the most important addition. - -``` -Classes: - NACBypass(BaseModule): - name = "nac_bypass" - category = "active" - resource_estimate = ResourceEstimate(ram_mb=15, cpu_pct=3, disk_mb=1) - - configure(config): - - mode: str ("bridge_passthrough" | "mac_clone" | "eap_relay") - - victim_mac: str (auto-detect from bridge traffic) - - interface_internal: str - - interface_external: str - -Key Logic: - bridge_passthrough (PRIMARY — most reliable): - - Inline transparent bridge between victim and switch - - EAP/EAPOL frames passed through unmodified - - Victim authenticates normally; implant piggybacks - - Implant's traffic uses victim's authenticated session - - Bridge configured to clone victim's MAC on implant frames - - Zero interaction with 802.1X — completely transparent - - mac_clone (FALLBACK): - - Clone authenticated device's MAC address - - Wait for device to go offline (or force offline via deauth) - - Take over the authenticated port - - Risky: duplicate MACs can trigger port security alerts - - eap_relay (ADVANCED): - - MitM the EAP exchange between victim and authenticator - - Relay EAP packets, inject implant traffic alongside - - Requires two interfaces + precise timing - - Research-grade, less battle-tested - - BATTLE-TESTED: Bridge passthrough is the standard field technique - THEORETICAL: EAP relay works in lab but timing-sensitive in production -``` - -#### `modules/active/lateral_move.py` — Lateral Movement Pipeline [NEW] - -``` -Classes: - LateralMove(BaseModule): - name = "lateral_move" - category = "active" - resource_estimate = ResourceEstimate(ram_mb=40, cpu_pct=10, disk_mb=20) - dependencies = ["credential_db"] - - Methods: - auto_spray() -> list[LateralResult] - - Takes all captured credentials, tries them against all discovered hosts - move_to(host, credential) -> LateralResult - setup_socks(host, port) -> SOCKSProxy - setup_port_forward(local, remote_host, remote_port) -> PortForward - create_mesh_pivot(hosts) -> MeshPivot - -Key Logic: - Credential-to-access automation: - - Takes credentials from credential_db - - Tests against discovered services (SMB, SSH, WinRM, RDP, MSSQL) - - impacket wmiexec/smbexec/psexec for Windows - - Paramiko/SSH for Linux - - Records successful accesses - - Pivoting: - - SOCKS proxy via SSH dynamic forwarding or chisel - - Port forwarding for specific services - - Mesh pivot: chain through multiple compromised hosts - - Auto-route: discovered subnets routed through pivot hosts - - BATTLE-TESTED: Credential spraying and impacket exec are standard tools - SCOPE: Every target checked against scope_enforcer before access attempt -``` - -#### `modules/active/cloud_harvest.py` — Cloud Token Harvesting [NEW] - -``` -Classes: - CloudHarvest(BaseModule): - name = "cloud_harvest" - category = "active" - resource_estimate = ResourceEstimate(ram_mb=20, cpu_pct=3, disk_mb=10) - -Key Logic: - Passive extraction from intercepted traffic (when in MITM position): - - AWS: Access keys (AKIA*), session tokens, STS responses - - Azure: Bearer tokens, refresh tokens, ADAL/MSAL responses - - GCP: OAuth tokens, service account keys - - Generic: JWT tokens, SAML assertions, OAuth authorization codes - - Active (from compromised hosts via lateral_move): - - AWS: ~/.aws/credentials, EC2 instance metadata (169.254.169.254) - - Azure: az cli token cache, managed identity endpoint - - GCP: gcloud auth, metadata server - - Publishes CLOUD_TOKEN_FOUND events - BATTLE-TESTED: Token extraction from traffic is proven; metadata server access is standard - SCOPE: Cloud accounts are in-scope only if explicitly listed in scope.yaml -``` - -#### `modules/active/ssl_downgrade.py` — SSL/TLS Stripping - -**STATUS: DEPRECATED / OPT-IN ONLY** - -Per Red Team Professional review: SSL stripping is mostly dead due to HSTS preload lists, HSTS enforcement, and browser security improvements. This module exists for legacy environments only. - -``` -Key Logic: - - DISABLED by default in modules.yaml - - Requires explicit opt-in: ssl_downgrade.explicit_enable = true - - Warning displayed on activation: "SSL stripping has <5% success rate on modern - browsers. HSTS preload lists and browser enforcement make this unreliable. - Only useful against legacy HTTP-only internal applications." - - If enabled: sslstrip mode only (mitmproxy SSL interception is separate) -``` - -#### `modules/active/vlan_hop.py` — VLAN Hopping - -**STATUS: DEPRIORITIZED** - -Per Red Team Professional review: VLAN hopping via double-tagging rarely works in modern environments. DTP is often disabled. Keep for completeness but deprioritize. - -``` -Key Logic: - - Deprioritized in implementation phases (moved to Phase 10) - - Warning on activation: "VLAN hopping via double-tagging has low success rate - on modern switches. DTP is typically disabled. Test with hardening_detector first." - - DTP mode: sends DTP frames to negotiate trunk (only works if DTP enabled) - - Double-tag mode: requires native VLAN mismatch (rare in hardened environments) -``` - -### 3.5 Active Directory Attack Suite [NEW] - -#### `modules/ad/kerberoast.py` - -``` -Classes: - Kerberoast(BaseModule): - name = "kerberoast" - category = "ad" - resource_estimate = ResourceEstimate(ram_mb=30, cpu_pct=5, disk_mb=10) - dependencies = ["credential_db"] - -Key Logic: - - Requires: valid domain credential (from passive capture or coercion) - - Step 1: LDAP query for accounts with SPNs - - Step 2: Request TGS tickets for each SPN - - Step 3: Extract ticket hashes (hashcat mode 13100) - - Step 4: Store in credential_db, queue for exfil - - Uses impacket GetUserSPNs - BATTLE-TESTED: Standard AD attack, works on every AD domain -``` - -#### `modules/ad/asrep_roast.py` - -``` -Key Logic: - - Requires: list of usernames (from LDAP enum or passive traffic) - - Queries for accounts with "Do not require Kerberos pre-authentication" - - Extracts AS-REP hashes (hashcat mode 18200) - - No credentials required for the AS-REP request itself - - Uses impacket GetNPUsers - BATTLE-TESTED: Standard AD attack -``` - -#### `modules/ad/adcs_attack.py` - -``` -Key Logic: - - Certipy integration for AD Certificate Services abuse - - ESC1: Enrollee supplies SAN (request cert as domain admin) - - ESC4: Vulnerable template ACL (modify template then ESC1) - - ESC6: EDITF_ATTRIBUTESUBJECTALTNAME2 flag on CA - - ESC8: NTLM relay to HTTP enrollment endpoint - - Full chain: coerce → relay to ADCS → domain admin cert → DCSync - - Uses certipy-ad Python library - BATTLE-TESTED: ESC1/ESC8 are the most reliable ADCS attack paths -``` - -#### `modules/ad/bloodhound_ingest.py` - -``` -Key Logic: - - SharpHound-style data collection using Python (bloodhound.py) - - Collects: users, groups, computers, sessions, ACLs, trusts - - Outputs BloodHound-compatible JSON - - Queued for exfil (large dataset, prioritize over PCAPs) - - Can run with minimal privileges (any domain user) - BATTLE-TESTED: bloodhound.py is well-maintained and reliable -``` - -#### `modules/ad/dcsync.py` - -``` -Key Logic: - - Requires: Domain Admin or Replication rights - - Uses impacket secretsdump (DRS_EXTENSIONS_INT) - - Extracts all domain password hashes (NTLM) - - High-value: immediate exfil priority - - SCOPE CHECK: only targets DCs listed in scope - BATTLE-TESTED: Standard post-exploitation technique -``` - -#### `modules/ad/coerce.py` — Authentication Coercion - -``` -Key Logic: - Coercion methods (force target to authenticate to implant): - - PetitPotam: MS-EFSRPC abuse → NTLM auth to attacker - - PrinterBug (SpoolService): MS-RPRN abuse → NTLM auth - - DFSCoerce: MS-DFSNM abuse → NTLM auth - - Chain integration: - - Coerce DC → capture NTLM → relay to ADCS (ESC8) → domain admin cert - - Coerce DC → capture NTLM → relay to LDAP → add replication rights → DCSync - - Coordinates with ntlm_relay module for automatic relay - - BATTLE-TESTED: PetitPotam + ADCS relay is the #1 domain takeover path in 2024-2025 - REQUIRES: Responder/ntlm_relay running as capture/relay endpoint -``` - -### 3.6 Layer 2/3 Protocol Attacks [NEW] - -#### `modules/l2l3/stp_attack.py` - -``` -Key Logic: - - Send BPDUs with lowest bridge priority to become root bridge - - All switch-to-switch traffic flows through implant - - Massive traffic visibility gain - - HIGH DETECTION RISK: STP topology changes generate alerts - - Run hardening_detector first (STP guard, BPDU guard) - BATTLE-TESTED: Works but very noisy, use only when stealth is secondary -``` - -#### `modules/l2l3/hsrp_takeover.py` - -``` -Key Logic: - - HSRP: send HSRP Hello with higher priority to become active gateway - - VRRP: send Advertisement with higher priority - - GLBP: send Hello to become AVG, redirect AVF assignments - - All traffic through implant without ARP spoofing - - Requires multicast group membership - - MEDIUM DETECTION RISK: protocol state change logged by managed switches - BATTLE-TESTED: HSRP takeover is proven; GLBP is more complex -``` - -#### `modules/l2l3/ospf_inject.py` - -``` -Key Logic: - - Inject OSPF LSAs to advertise routes through implant - - Requires OSPF authentication key (often plaintext or MD5) - - Can redirect specific subnets through implant - - HIGH DETECTION RISK: route changes visible to all OSPF speakers - - Useful for targeted subnet interception - THEORETICAL: Works in lab; production OSPF networks may have authentication -``` - -### 3.7 Exfiltration Channels [NEW additions] - -#### `modules/exfil/http_channel.py` — Domain Fronting C2 - -``` -Key Logic: - - HTTPS requests to high-reputation CDN (Cloudflare, Fastly, Azure CDN) - - Host header points to attacker's origin server behind CDN - - Network sees HTTPS to cloudflare.com — allowed by virtually all firewalls - - Bi-directional: POST for exfil, GET for commands - - JA3 fingerprint matches common browser (via ja3_spoofer) - BATTLE-TESTED: Domain fronting is proven but some CDNs now block it - NOTE: Cloudflare blocked domain fronting in 2024; Azure CDN still works -``` - -#### `modules/exfil/doh_channel.py` — DNS-over-HTTPS - -``` -Key Logic: - - DNS queries over HTTPS to Google/Cloudflare DoH endpoints - - Data encoded in DNS query names (same as dns_tunnel) - - But: encrypted HTTPS to trusted DoH provider, not plaintext DNS - - Virtually unblockable (blocking Google DoH breaks too many things) - - Lower throughput than raw DNS tunnel but much stealthier - BATTLE-TESTED: Proven technique used by real threat actors -``` - -#### `modules/exfil/stego_channel.py` — Steganographic Exfil - -``` -Key Logic: - - Embed data in images (LSB steganography) or audio - - Upload to legitimate platforms (Imgur, social media) - - C2 retrieves from platform - - Very low bandwidth (~1KB per image) but extremely hard to detect - - Use for high-value small data (passwords, keys, tokens) - THEORETICAL: Implementation is straightforward but operational overhead is high -``` - -#### `modules/exfil/dead_drop.py` — Dead Drop - -``` -Key Logic: - - Upload encrypted data to paste sites (Pastebin, GitHub Gist, etc.) - - C2 polls paste sites for new drops - - No direct connection between implant and C2 - - Paste content encrypted; looks like random Base64 data - - Rate limited: max 1 paste per hour - BATTLE-TESTED: Used by real APT groups; proven operational pattern -``` - -### 3.8 Connectivity [NEW additions] - -#### `modules/connectivity/cellular_backup.py` — Cellular Backup C2 - -``` -Key Logic: - - Supports LTE modem HATs (SIM7600, EC25, etc.) - - Out-of-band C2 when target network blocks all VPN/tunneling - - AT command interface for modem control - - PPP connection establishment - - GPS from LTE modem for geofence enforcement (if supported) - - Battery cost: significant power draw (~2W continuous) - - Hardware Tier: Pi 4 only (USB power budget) - BATTLE-TESTED: LTE modems on Pi are well-documented - NOTE: Requires pre-provisioned SIM card (prepaid, untraceable preferred) -``` - -#### `modules/connectivity/ble_emergency.py` — BLE Emergency Access - -``` -Key Logic: - - BLE GATT server for emergency local access - - Range: ~10m (requires physical proximity) - - Authenticated: PSK-based challenge-response - - Commands: status, kill, reboot, exfil-now - - Use case: operator physically near implant but network C2 is down - - Always-on, minimal power (~0.1W) - BATTLE-TESTED: BLE on Pi is reliable; custom GATT services are straightforward -``` - -### 3.9 Stealth [NEW additions] - -#### `modules/stealth/traffic_mimicry.py` — Traffic Pattern Mimicry - -``` -Key Logic: - Phase 1 (48h baseline): - - Capture normal traffic patterns: protocols, volumes, timing, destinations - - Build statistical model: hourly bandwidth, top destinations, protocol ratios - - Store baseline in storage/baseline/ - - Phase 2 (behavioral blending): - - Shape implant traffic to match baseline patterns - - Exfil timed to match normal upload patterns - - C2 traffic volume matched to normal HTTPS volume - - Beacon intervals matched to existing periodic traffic (update checks, etc.) - - DNS query rate matched to normal resolution rate - - BATTLE-TESTED: Traffic shaping is straightforward; statistical modeling adds value - NOTE: 48h baseline delay before active ops is an operational cost -``` - -#### `modules/stealth/ja3_spoofer.py` — JA3 Fingerprint Spoofing - -``` -Key Logic: - - Modify TLS ClientHello to match known JA3 hashes - - Targets: Chrome, Firefox, Edge (current versions) - - JA3 hash database in data/ja3_fingerprints.db - - Applied to all outbound HTTPS from implant (C2, exfil, domain fronting) - - Prevents JA3-based detection of non-browser TLS clients - BATTLE-TESTED: JA3 spoofing libraries exist (ja3transport for Go, utls) - NOTE: Python TLS stack doesn't easily allow ClientHello manipulation; - may need to shell out to Go binary or use ctypes with OpenSSL -``` - -#### `modules/stealth/ids_tester.py` — IDS Ruleset Self-Testing - -``` -Key Logic: - - Loads Snort/Suricata rule snapshots from data/ids_rules/ - - Before going active, checks if planned actions match known signatures - - Rates detection risk for each proposed action - - Suggests evasion modifications (timing, encoding, fragmentation) - - NOT a guarantee — only tests against known rulesets - THEORETICAL: Rule matching is doable; evasion suggestion quality varies - NOTE: Rule snapshots must be updated periodically (bundled at deploy time) -``` - -#### `modules/stealth/lkm_rootkit.py` — LKM Rootkit (Optional) - -``` -Key Logic: - - Loadable kernel module for Linux host concealment - - Hides: processes (from /proc), files (from readdir), network connections - (from /proc/net/tcp, /proc/net/udp), kernel module itself (from lsmod) - - OPTIONAL: only for compromised host deployment, not Pi deployment - - Compiled for target kernel (scripts/build_lkm.sh) - - Requires: matching kernel headers on target - - Detected by: kernel integrity checks, /dev/kmem analysis, rootkit hunters - - USE CASE: When BigBrother code is deployed to a compromised server - (not the Pi hardware implant), this hides its presence from sysadmins. - - BATTLE-TESTED: LKM rootkits are well-understood; detection tools exist - WARNING: Kernel module crashes = kernel panic. Test thoroughly. - HARDWARE TIER: Debian host only (not Pi — Pi has its own stealth model) -``` - -#### `modules/stealth/encrypted_storage.py` — ENHANCED - -``` -New capability: Network-derived LUKS key - - LUKS passphrase derived from combination of: - 1. Operator-provided secret (pre-deployment) - 2. Network beacon value (fetched from C2 on boot) - - If network unreachable: storage stays locked - - Anti-forensics: physically seized device cannot be unlocked without - both the secret AND the network beacon - - Fallback: BLE emergency access can provide beacon value manually - BATTLE-TESTED: LUKS with derived keys is standard; network component adds complexity -``` - -#### `modules/stealth/overlayfs_manager.py` — SD Card Reliability [NEW] - -``` -Key Logic: - - Mount root filesystem as overlayfs (read-only base + tmpfs overlay) - - All writes go to RAM; SD card sees zero write activity - - Benefits: SD card longevity, no filesystem forensics (writes vanish on reboot) - - Persistent data: only encrypted_storage writes to SD (via LUKS container) - - setup.sh option: configure overlayfs at boot via initramfs hook - - Trade-off: RAM consumed by overlay (~50MB typical) - BATTLE-TESTED: overlayfs is standard Linux; Raspberry Pi OS supports it natively - HARDWARE TIER: All tiers (Pi Zero gets smaller overlay) -``` - -### 3.10 Intelligence [NEW additions] - -#### `modules/intel/net_intel.py` — Offensive Network Intelligence - -``` -Key Logic: - SOC capabilities twisted for offensive use: - - Beacon detection: identify EXISTING C2 traffic on the network - (other implants, malware, compromised hosts — valuable intel) - - Communication graphing: identify trust relationships, admin access patterns - - Anomaly baseline: establish what's "normal" so implant can blend in - - Service dependency mapping: identify critical services for impact assessment - - Authentication flow mapping: who authenticates to what, via which protocol - BATTLE-TESTED: Network traffic analysis is well-understood -``` +## 3. Surveillance Modules + +### 3.1 Passive Surveillance (24/7, zero noise, unsupervised) + +These modules start at deployment and run continuously without generating any network traffic. + +--- + +#### `modules/passive/packet_capture.py` — Full Packet Capture + +**Purpose**: Capture all network traffic to encrypted rotating PCAPs for offline analysis. + +- Promiscuous mode on bridge or tap interface +- BPF filters: full capture, credentials-only, DNS-only, or custom +- PCAP rotation: size-based (100MB default) or time-based (1h default) +- AES-256-GCM encryption before writing to disk +- Snap length configurable: 96 bytes (headers only) for Pi Zero, 65535 (full) for Pi 4+ +- Disk usage monitoring — auto-purge oldest PCAPs when threshold hit + +**Resources**: RAM 30-80MB (snap length dependent), CPU 5-15%, disk varies +**Dependencies**: libpcap, scapy + +--- + +#### `modules/passive/dns_logger.py` — DNS Query Logger + +**Purpose**: Build per-host browsing history from DNS queries. Every domain every host resolves, timestamped. + +- 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 + +**Resources**: RAM 15MB, CPU 2%, disk 5MB/day typical +**Dependencies**: scapy or dpkt + +--- + +#### `modules/passive/tls_sni_extractor.py` — TLS SNI Extractor + +**Purpose**: Log every HTTPS destination without decryption, from the ClientHello SNI field. + +- 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 +- Log: timestamp, source IP, destination IP:port, SNI hostname, TLS version + +**Resources**: RAM 10MB, CPU 2%, disk 3MB/day typical +**Dependencies**: scapy or dpkt + +--- + +#### `modules/passive/credential_sniffer.py` — Credential Sniffer + +**Purpose**: Extract credentials from cleartext protocols and NTLM/Kerberos authentication. + +- **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) +- Output: hashcat-compatible format, stored in credential_db +- Publishes CREDENTIAL_FOUND events on bus + +**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 +**Dependencies**: scapy, impacket + +--- + +#### `modules/passive/host_discovery.py` — Host Discovery + +**Purpose**: Build complete host inventory from passive network observation. + +- ARP table monitoring (new MACs) +- DHCP request/ACK sniffing (hostname, vendor class, requested IP) +- 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 + +**Resources**: RAM 15MB, CPU 2%, disk 5MB +**Dependencies**: scapy, data/oui.db + +--- + +#### `modules/passive/os_fingerprint.py` — Passive OS Fingerprinting + +**Purpose**: Identify operating systems without sending any probes. p0f-style. + +- 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 +**Dependencies**: scapy, data/os_sigs.db + +--- + +#### `modules/passive/traffic_analyzer.py` — Traffic Analyzer + +**Purpose**: Protocol distribution, flow analysis, bandwidth monitoring, beacon detection. + +- 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 +**Dependencies**: scapy + +--- + +#### `modules/passive/vlan_discovery.py` — VLAN Discovery + +**Purpose**: Map VLAN topology from passive observation. + +- 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 + +--- + +#### `modules/passive/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. + +- 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) + +--- + +#### `modules/passive/auth_flow_tracker.py` — Authentication Flow Tracker + +**Purpose**: Map who authenticates to what services and when, building per-user activity timelines. + +- 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 +**Dependencies**: scapy, impacket + +--- + +#### `modules/passive/smb_monitor.py` — SMB File Access Monitor + +**Purpose**: Track file share access patterns — which users access which shares and files. + +- 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 + +**Resources**: RAM 15MB, CPU 2%, disk 5MB +**Dependencies**: scapy, impacket + +--- + +#### `modules/passive/voip_capture.py` — VoIP/SIP Metadata Capture + +**Purpose**: Capture call records, participants, duration. Optionally capture RTP audio if unencrypted. + +- 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) + +--- + +#### `modules/passive/print_interceptor.py` — Print Job Interceptor + +**Purpose**: Capture print spool data from network print traffic. + +- 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 +- Publishes HANDSHAKE_CAPTURED events + +**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 + +**Resources**: RAM 20MB, CPU 3%, disk varies (attachment size) +**Dependencies**: scapy, email (stdlib) + +--- + +### 3.2 Active Surveillance (operator-enabled, then runs unattended) + +These modules require explicit operator activation. Once configured and started, they run without further interaction. + +--- + +#### `modules/active/arp_spoof.py` — ARP Spoofing + +**Purpose**: Become the man-in-the-middle by poisoning ARP caches. All target traffic flows through the implant. + +- 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 + +**Resources**: RAM 10MB, CPU 2% +**Dependencies**: scapy, iptables + +--- + +#### `modules/active/dns_poison.py` — DNS Poisoning + +**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 + +--- + +#### `modules/active/dhcp_spoof.py` — DHCP Spoofing + +**Purpose**: Rogue DHCP server to set implant as gateway and/or DNS server for new clients. + +- 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 + +**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. + +- 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. + +- 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 `