# BigBrother: Network Implant Architecture — Consolidated Design > **Version**: 2.0 — Post-Tribe Review Consolidated > **Date**: 2025-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. Architecture 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. ### Core Principles 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 ### 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│ │ │ │ │ │ └────────┴────────┴────────┴────────┴────────┴────────┴──────────┘ ``` --- ## 2. Full File Tree ``` ~/tools/bigbrother/ ├── bigbrother.py # Main CLI + interactive menu (Click + Rich) ├── setup.sh # Idempotent Debian bootstrap ├── 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 │ └── engagement_full.yaml # Full config for Pi 4 / Debian host │ ├── core/ │ ├── __init__.py │ ├── engine.py # Module lifecycle manager (load, start, stop, status) │ ├── scheduler.py # Task scheduler (cron-like, jitter-aware) │ ├── bus.py # Internal event bus (pub/sub between modules) │ ├── state.py # Persistent state manager (SQLite) │ ├── resource_monitor.py # RAM/CPU/disk watchdog, throttle enforcement │ ├── 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 │ ├── modules/ │ ├── __init__.py │ ├── base.py # Abstract base class for all modules │ │ │ ├── passive/ │ │ ├── __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 │ │ ├── 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] │ │ │ ├── active/ │ │ ├── __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 │ │ │ ├── connectivity/ │ │ ├── __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, DNS tunnel fallback │ │ ├── cellular_backup.py # LTE modem HAT for out-of-band C2 [NEW] │ │ └── ble_emergency.py # BLE emergency access channel [NEW] │ │ │ ├── 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] │ │ ├── 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] │ │ │ └── intel/ │ ├── __init__.py │ ├── credential_db.py # SQLite credential store (host/service/user/pass) │ ├── file_carver.py # PCAP file extraction (HTTP, SMB, FTP) │ ├── 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] │ ├── services/ │ ├── bigbrother-core.service # Main daemon (sleeper mode) │ ├── bigbrother-watchdog.service # Watchdog / auto-recovery │ ├── bigbrother-capture.service # Packet capture (passive) │ ├── bigbrother-discovery.service # Host discovery (passive) │ ├── 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 │ └── lkm/ │ ├── bb_hide.c # Kernel module source (process/file/net hiding) │ └── Makefile # Build for target kernel version │ ├── 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 │ ├── 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] │ │ ├── emerging-threats.rules │ │ └── snort-community.rules │ ├── ja3_fingerprints.db # Known JA3 hashes for common browsers [NEW] │ └── bpf_filters/ │ ├── credentials.bpf # BPF for credential protocols │ ├── discovery.bpf # BPF for discovery traffic │ └── full_capture.bpf # BPF for full capture (minus noise) │ ├── 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 │ ├── 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] │ └── 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] └── 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 ``` #### `modules/intel/supply_chain_detect.py` — Supply Chain Detection ``` Key Logic: DETECTION ONLY — no exploitation without explicit operator approval. Detects: - Internal package repositories (PyPI mirrors, npm, Maven, NuGet) - WSUS servers (Windows Update) - Internal CA servers - Configuration management (Puppet, Chef, Ansible, SCCM) - Container registries (Docker, Harbor) - CI/CD systems (Jenkins, GitLab, TeamCity) Output: list of supply chain targets with access assessment Operator must explicitly approve any supply chain attack via CLI BATTLE-TESTED: Detection is passive traffic analysis; proven technique CRITICAL POLICY: Exploitation requires explicit written operator approval (separate from normal scope authorization) ``` #### `modules/intel/report_generator.py` — ENHANCED ``` New capabilities: - Engagement timeline: chronological event log with timestamps - Credential report: all captured credentials, sources, crack status - Topology diagram: auto-generated Graphviz network map - Attack chain documentation: which attacks succeeded, evidence chain - Executive summary: high-level findings for client presentation - Push notification integration: high-value findings sent via ntfy.sh ``` ### 3.11 Notifications [NEW] #### `notifications/push.py` — Push Notifications ``` Key Logic: - ntfy.sh integration (self-hosted or public) - Webhook support (Slack, Discord, custom) - Events that trigger push: CREDENTIAL_FOUND (high-value: domain admin, cloud tokens) AD_DOMAIN_FOUND LATERAL_MOVE_SUCCESS OT_PROTOCOL_DETECTED (warning) SCOPE_VIOLATION (alert) RESOURCE_CRITICAL CONNECTIVITY_CHANGED (C2 down/up) - Rate limited: max 1 push per event type per 5 minutes - Encrypted payload option (encrypt notification content) - C2 channel used for delivery (does not create new network connections) BATTLE-TESTED: ntfy.sh is simple and reliable ``` --- ## 4. Module Interaction Model ``` ┌──────────────────────────────────────────────────────┐ │ bigbrother.py │ │ (CLI + Interactive Menu) │ └────────────────────────┬─────────────────────────────┘ │ ┌────────────────────────▼─────────────────────────────┐ │ core/engine.py │ │ (Module Lifecycle Manager) │ │ discover / load / start / stop / status │ │ + scope_enforcer + hardware_tier │ └──┬──────────────────┬──────────────────────────┬─────┘ │ │ │ ┌──────────────▼──┐ ┌───────────▼────────┐ ┌─────────────▼──────┐ │ core/bus.py │ │ core/state.py │ │ core/scheduler.py │ │ (Event Pub/Sub) │ │ (SQLite State) │ │ (Timed Tasks) │ └──┬──┬──┬──┬──┬──┘ └────────────────────┘ └────────────────────┘ │ │ │ │ │ │ │ │ │ └──── KILL_SWITCH ────────► core/kill_switch.py │ │ │ └─────── RESOURCE_* ─────────► core/resource_monitor.py │ │ └────────── CREDENTIAL_FOUND ───► intel/credential_db.py + push.py │ └───────────── HOST_DISCOVERED ────► intel/topology_mapper.py └──────────────── PCAP_ROTATED ───────► exfil/stager.py AD_DOMAIN_FOUND ────► decision/state_machine.py TICKET_HARVESTED ───► intel/credential_db.py CLOUD_TOKEN_FOUND ──► intel/credential_db.py + push.py OT_PROTOCOL_DETECTED → scope_enforcer (lockout) + push.py SCOPE_VIOLATION ────► audit log + push.py (ALERT) Module Dependency Graph (extended): packet_capture ──► credential_sniffer ──► credential_db ──► os_fingerprint ──► traffic_analyzer ──► topology_mapper ──► vlan_discovery ──► vlan_hop ──► kerberos_harvest ──► credential_db ──► protocol_analyzer ──► net_intel ──► cloud_harvest (passive mode) host_discovery ──► topology_mapper ──► scanner ──► env_classifier arp_spoof ──► dns_spoof ──► ssl_downgrade (OPT-IN) ──► session_hijack ──► file_extractor ──► email_intercept ──► cloud_harvest (active MITM mode) responder ──► ntlm_relay ──► adcs_attack (ESC8 relay) coerce ──► ntlm_relay (captures coerced auth) credential_db ──► kerberoast (needs domain cred) ──► lateral_move (auto-spray) ──► dcsync (needs DA cred) nac_bypass ──► bridge (enhanced bridge mode) tailscale ──► vpn_channel ──► exfil_manager wireguard ──► vpn_channel cellular_backup ──► exfil_manager (fallback) traffic_mimicry ──► exfil_manager (shapes exfil traffic) ja3_spoofer ──► http_channel, doh_channel (spoofs TLS fingerprint) env_classifier ──► state_machine (recommends attack path) hardening_detector ──► active modules (blocks if hardening detected) ``` --- ## 5. Autonomous Decision Engine ### State Machine Flow ``` ┌─────────┐ auto ┌─────────┐ operator ┌──────────┐ │ DEPLOY │──────────────►│ RECON │──────────────►│ EXPLOIT │ │ │ │ │ │ │ │-baseline│ │-passive │ │-active │ │-classify│ │-discover │ │-AD suite │ │-harden │ │-cred snif│ │-L2/L3 │ │ detect │ │-kerberos │ │-NAC bypas│ └─────────┘ │-proto │ └────┬─────┘ ▲ │ analyze │ │ │ └──────────┘ │ success │ ▲ ▼ ┌────┴────┐ │ ┌──────────┐ │ (reset) │ reactivate │ COLLECT │ └─────────┘ │ │ │ ┌─────┴────┐ │-lateral │ │ DORMANT │◄─────────────│-cloud │ │ │ complete │-data │ │-minimal │ │ harvest │ │-check-in │◄──┐ └────┬─────┘ └──────────┘ │ │ │ ┌────▼─────┐ └──────────│ EXFIL │ complete │ │ │-staged │ │-multi-ch │ └──────────┘ ANY STATE ──── kill switch ────► DESTROYED ``` ### Environment-Based Recommendations ``` AD Domain detected: → Recommend: kerberoast, asrep_roast, bloodhound_ingest → If ADCS found: recommend coerce → ADCS relay chain → If no pre-auth found: recommend coerce → ntlm_relay Flat Linux detected: → Recommend: responder (if mixed), SSH credential spray → Focus: credential_sniffer, lateral_move (SSH) OT/SCADA detected: → LOCKOUT: all active modules for OT subnets → Passive only: protocol_analyzer, traffic_analyzer → Alert operator via push notification Cloud-Heavy detected: → Recommend: cloud_harvest (passive first, then active) → Focus: OAuth/SAML token capture, metadata service access ``` --- ## 6. Setup & Bootstrap ### `setup.sh` — Package List ```bash #!/usr/bin/env bash # BigBrother Implant Bootstrap — Idempotent set -euo pipefail BB_DIR="$(cd "$(dirname "$0")" && pwd)" BB_VENV="${BB_DIR}/.venv" detect_platform() { if grep -q "Raspberry Pi Zero 2" /proc/device-tree/model 2>/dev/null; then echo "pi_zero" elif grep -q "Raspberry Pi 4" /proc/device-tree/model 2>/dev/null; then echo "pi4" elif grep -q "Raspberry Pi" /proc/device-tree/model 2>/dev/null; then echo "pi" else echo "generic" fi } PLATFORM=$(detect_platform) CORE_PACKAGES=( python3 python3-venv python3-dev python3-pip build-essential libssl-dev libffi-dev # Networking bridge-utils ebtables iptables nftables iproute2 net-tools tcpdump nmap dnsutils # WiFi hostapd dnsmasq wireless-tools wpasupplicant aircrack-ng # VPN wireguard-tools # Crypto cryptsetup # Tools curl wget git jq tmux # Build deps libpcap-dev libnetfilter-queue-dev # BLE [NEW] bluez libbluetooth-dev ) FULL_PACKAGES=( responder mitmproxy autossh # LKM build deps [NEW] linux-headers-$(uname -r) ) PI4_PACKAGES=( # Cellular modem support [NEW] ppp usb-modeswitch ) # Python packages setup_venv() { python3 -m venv "$BB_VENV" source "${BB_VENV}/bin/activate" pip install --quiet --upgrade pip wheel pip install --quiet \ click rich pyyaml cryptography scapy netfilterqueue impacket \ certipy-ad bloodhound dnslib requests ntfy if [ "$PLATFORM" != "pi_zero" ]; then pip install --quiet mitmproxy || true fi } ``` Full setup.sh includes: Tailscale install, Responder from GitHub, iodine DNS tunnel, directory structure, systemd services, kernel parameters, Pi optimizations (GPU memory, Bluetooth disable, swap), hardening (permissions, core dumps disabled), overlayfs setup (optional). --- ## 7. Systemd Services All service descriptions use innocuous names. No mention of BigBrother. | Service File | Description (visible) | Actual Function | |---|---|---| | `bigbrother-core.service` | System Thermal Management Daemon | Main daemon | | `bigbrother-watchdog.service` | System Health Monitor | Watchdog | | `bigbrother-capture.service` | Network Interface Statistics Collector | Packet capture | | `bigbrother-discovery.service` | Network Device Monitor | Host discovery | | `bigbrother-bridge.service` | Network Bridge Service | Transparent bridge | | `bigbrother-tailscale.timer` | VPN Health Check Timer | Tailscale health | Resource limits enforced via systemd: - Core: MemoryMax=400M, CPUQuota=70% - Watchdog: MemoryMax=50M, CPUQuota=5% - Capture: MemoryMax=100M, CPUQuota=20% - Discovery: MemoryMax=50M, CPUQuota=10% --- ## 8. Configuration Schemas ### `config/scope.yaml` — MANDATORY [NEW] ```yaml # Engagement scope — REQUIRED for active module operation # Active modules will REFUSE to operate without a valid scope file engagement: name: "op-example" authorization: "SOW-2025-0042" # Reference to authorization document start_date: "2025-03-15" end_date: "2025-04-15" in_scope: networks: - "10.0.0.0/8" - "172.16.0.0/12" - "10.0.0.0/24" hosts: - "dc01.target.corp" - "web01.target.corp" wireless: - ssid: "CorpWiFi" - ssid: "CorpGuest" cloud: - "target-corp AWS account 123456789012" - "target-corp Azure tenant abc-def-ghi" exclusions: # Never target these, even if in-scope CIDR hosts: - "10.0.0.1" # Core router - "10.0.1.100" # Production database networks: - "10.99.0.0/16" # Partner network ot_scada: # PASSIVE ONLY — hard lockout on active modules networks: - "10.50.0.0/16" # ICS network - "10.51.0.0/16" # SCADA DMZ note: "Industrial control systems — observation only, zero interaction" supply_chain: # Requires SEPARATE explicit approval per target approval_required: true approved_targets: [] # Populated by operator after discovery ``` ### `config/hardware_tiers.yaml` [NEW] ```yaml tiers: pi_zero_2w: ram_total_mb: 512 ram_usable_mb: 400 max_passive_modules: 4 max_active_modules: 1 max_concurrent_modules: 5 cpu_quota_pct: 70 snap_length: 96 flow_table_max: 5000 flow_timeout_sec: 600 top_talkers_n: 20 sqlite_cache_pages: 50 compression: "zlib" # lzma too RAM-heavy key_derivation: "pbkdf2" # argon2id too RAM-heavy excluded_modules: - mitmproxy_mode - file_carver # Too RAM-heavy - lkm_rootkit # Not for Pi - cellular_backup # USB power budget overlay_tmpfs_mb: 30 pi4: ram_total_mb: 4096 # 4GB model preferred ram_usable_mb: 3500 max_passive_modules: 8 max_active_modules: 4 max_concurrent_modules: 12 cpu_quota_pct: 80 snap_length: 65535 flow_table_max: 50000 flow_timeout_sec: 3600 top_talkers_n: 100 sqlite_cache_pages: 2000 compression: "lzma" key_derivation: "argon2id" excluded_modules: - lkm_rootkit # Not for Pi overlay_tmpfs_mb: 200 debian_host: ram_total_mb: 0 # Dynamic detection ram_usable_mb: 0 # Dynamic max_passive_modules: 0 # Unlimited max_active_modules: 0 # Unlimited max_concurrent_modules: 0 # Unlimited cpu_quota_pct: 90 snap_length: 65535 flow_table_max: 100000 flow_timeout_sec: 3600 top_talkers_n: 500 sqlite_cache_pages: 8000 compression: "lzma" key_derivation: "argon2id" excluded_modules: [] # Everything available overlay_tmpfs_mb: 0 # Not needed ``` ### `config/bigbrother.yaml` — Master Config ```yaml engagement: name: "op-example" client: "" scope_file: "config/scope.yaml" # MANDATORY device: platform: "auto" hostname: "iot-sensor-03" install_path: "/opt/.cache/bb" network: primary_interface: "auto" bridge: enabled: false internal: "eth0" external: "eth1" wifi: interface: "wlan0" client_ssid: "" client_passphrase: "" cellular: # [NEW] enabled: false modem_device: "/dev/ttyUSB0" apn: "internet" pin: "" connectivity: primary: "tailscale" failover_chain: # [NEW — explicit chain] - tailscale - wireguard - reverse_tunnel_ssh - reverse_tunnel_http - dns_tunnel - cellular_backup tailscale: auth_key: "" hostname: "iot-sensor-03" wireguard: private_key: "" peer_public_key: "" endpoint: "" allowed_ips: "10.100.0.0/24" reverse_tunnel: server: "" port: 443 key_path: "" security: kill_passphrase_hash: "" encryption_key_derive: "argon2id" network_derived_key: false # [NEW] dead_man_switch: enabled: false interval_hours: 24 action: "wipe" auto_lock_timeout: 300 gps_geofence: # [NEW] enabled: false center_lat: 0.0 center_lon: 0.0 radius_meters: 1000 action: "wipe" # wipe if moved outside geofence notifications: # [NEW] enabled: false method: "ntfy" # ntfy | webhook ntfy_topic: "" ntfy_server: "https://ntfy.sh" webhook_url: "" encrypt_payload: true operating_hours: enabled: true timezone: "America/New_York" start: "08:00" end: "18:00" weekend_active: false baseline: # [NEW] duration_hours: 48 auto_start: true ``` --- ## 9. Implementation Phases ### Phase 1: Foundation (Week 1) **Goal**: Core infrastructure, module lifecycle, scope enforcement. ``` Files: - bigbrother.py (CLI skeleton, Click groups, basic menu) - core/engine.py, bus.py, state.py, scheduler.py, resource_monitor.py - core/scope_enforcer.py [NEW] - modules/base.py - utils/config_loader.py, resource.py, permissions.py, logging.py - config/bigbrother.yaml, modules.yaml, scope.yaml [NEW] - config/hardware_tiers.yaml [NEW] - requirements.txt, setup.sh (core packages only) - tests/conftest.py, test_engine.py, test_bus.py, test_scope.py [NEW] Validation: Module lifecycle works. Scope enforcer rejects out-of-scope targets. Hardware tier detection accurate on Pi Zero 2W, Pi 4, Debian. ``` ### Phase 2: Stealth Layer (Week 2) **Goal**: OPSEC foundation before any network activity. ``` Files: - modules/stealth/ (all 7 original modules) - modules/stealth/overlayfs_manager.py [NEW] - utils/crypto.py (full implementation) - utils/stealth.py (jitter, timing, rate limiting) - core/kill_switch.py - config/stealth.yaml - services/bigbrother-watchdog.service Validation: Encrypted storage works. Process disguised. Kill switch wipes all data. Watchdog restarts crashed module. Overlayfs operational on Pi. ``` ### Phase 3: Passive Collection (Week 3) **Goal**: Sleeper mode fully operational. Zero network noise. ``` Files: - modules/passive/ (all 6 original passive modules) - modules/passive/kerberos_harvest.py [NEW] - modules/passive/protocol_analyzer.py [NEW] - modules/intel/credential_db.py - utils/networking.py - data/oui.db, os_sigs.db, bpf_filters/ - services/bigbrother-core.service, capture.service, discovery.service Validation: All hosts discovered, credentials captured from test services, Kerberos tickets harvested, protocol analysis running. Zero IDS alerts. ``` ### Phase 4: Decision Engine + Connectivity (Week 4) **Goal**: Environment classification, hardening detection, reliable C2. ``` Files: - decision/state_machine.py, env_classifier.py, hardening_detector.py [NEW] - modules/connectivity/ (all 5 original modules) - modules/connectivity/cellular_backup.py [NEW] - modules/connectivity/ble_emergency.py [NEW] - modules/stealth/traffic_mimicry.py [NEW — baseline capture] - services/bigbrother-bridge.service, tailscale.timer - scripts/setup_bridge.sh, teardown_bridge.sh Validation: Environment correctly classified (AD/Linux/OT/Cloud). Hardening detection identifies DAI, DHCP snooping, 802.1X. Failover chain works: Tailscale → WireGuard → SSH → DNS → Cellular. Traffic baseline captured over 48h. ``` ### Phase 5: Exfiltration + Notifications (Week 5) **Goal**: Multi-channel exfil with traffic mimicry. ``` Files: - modules/exfil/ (all original + 4 new channels) - modules/stealth/ja3_spoofer.py [NEW] - notifications/push.py [NEW] - config/exfil.yaml Validation: Exfil over VPN at rate limit. Failover to DoH when VPN blocked. Domain fronting works through CDN. JA3 fingerprint matches Chrome. Push notifications received for high-value events. ``` ### Phase 6: NAC Bypass + MITM (Week 6) **Goal**: Network access despite 802.1X, core MITM capabilities. ``` Files: - modules/active/nac_bypass.py [NEW — CRITICAL] - modules/active/arp_spoof.py, dns_spoof.py, dhcp_spoof.py - modules/active/session_hijack.py - modules/active/ssl_downgrade.py (OPT-IN gated) - modules/stealth/ids_tester.py [NEW] - data/ids_rules/ [NEW] - tests/test_nac_bypass.py [NEW] Validation: NAC bypass via bridge passthrough on 802.1X network. ARP spoof + DNS spoof chain works. IDS tester identifies risky actions. ``` ### Phase 7: AD Attack Suite (Week 7) **Goal**: Full AD compromise capability. ``` Files: - modules/ad/ (all 6 modules) [NEW] - modules/active/ntlm_relay.py (enhanced with ADCS relay) Validation: Kerberoast extracts TGS hashes. AS-REP roasting works. PetitPotam → ADCS relay → domain admin cert → DCSync full chain. BloodHound ingest produces valid JSON. ``` ### Phase 8: Active Advanced + Lateral Movement (Week 8) **Goal**: Credential exploitation, pivoting, cloud access. ``` Files: - modules/active/responder.py, evil_twin.py, scanner.py, packet_inject.py - modules/active/lateral_move.py [NEW] - modules/active/cloud_harvest.py [NEW] - modules/passive/wireless_intel.py [NEW] - templates/captive_portals/, hostapd/, responder/ Validation: Credential spray across discovered hosts. SOCKS pivot through compromised host. Cloud tokens extracted from traffic. Wireless probe requests collected. ``` ### Phase 9: L2/L3 + Intelligence (Week 9) **Goal**: Layer 2/3 attacks, full intelligence reporting. ``` Files: - modules/l2l3/ (all 3 modules) [NEW] - modules/intel/ (file_carver, topology_mapper, report_generator enhanced) - modules/intel/net_intel.py, supply_chain_detect.py [NEW] - config/attack_chains.yaml [NEW] Validation: STP root bridge takeover. HSRP gateway takeover. Network topology diagram generated. Engagement report complete. Supply chain targets identified (detection only). ``` ### Phase 10: Hardening, LKM, Polish (Week 10) **Goal**: Production-ready. Battle-tested. Edge cases handled. ``` Files: - modules/stealth/lkm_rootkit.py [NEW] - modules/active/vlan_hop.py (deprioritized, built last) - templates/lkm/bb_hide.c, Makefile [NEW] - scripts/build_lkm.sh, gps_geofence.py [NEW] Tasks: - Comprehensive error handling audit - Pi Zero performance optimization pass - Memory leak testing (72-hour soak test) - Full integration tests on all Pi models + Debian - Interactive menu polish (Rich TUI) - setup.sh validation on clean OS images - Crypto implementation security audit - Final OPSEC review - Attack chain recipe validation ``` --- ## 10. Hardware Tier Matrix ### What Runs Where | Module | Pi Zero 2W (512MB) | Pi 4 (4GB) | Debian Host | |--------|:---:|:---:|:---:| | **Core Framework** | Y | Y | Y | | **Passive: packet_capture** | Y (96B snap) | Y (full) | Y (full) | | **Passive: host_discovery** | Y | Y | Y | | **Passive: credential_sniffer** | Y | Y | Y | | **Passive: os_fingerprint** | Y | Y | Y | | **Passive: traffic_analyzer** | Y (pruned) | Y | Y | | **Passive: vlan_discovery** | Y | Y | Y | | **Passive: wireless_intel** | Y (probe only) | Y | Y | | **Passive: kerberos_harvest** | Y | Y | Y | | **Passive: protocol_analyzer** | Limited | Y | Y | | **Active: arp_spoof** | Y | Y | Y | | **Active: dns_spoof** | Y | Y | Y | | **Active: ssl_downgrade** | N (no mitmproxy) | Y (opt-in) | Y (opt-in) | | **Active: responder** | Limited | Y | Y | | **Active: evil_twin** | Y (if USB WiFi) | Y | Y | | **Active: dhcp_spoof** | Y | Y | Y | | **Active: vlan_hop** | Y | Y | Y | | **Active: ipv6_attack** | Y | Y | Y | | **Active: scanner** | Y (slow) | Y | Y | | **Active: packet_inject** | Y | Y | Y | | **Active: ntlm_relay** | Limited | Y | Y | | **Active: session_hijack** | Y | Y | Y | | **Active: file_extractor** | N (RAM) | Y | Y | | **Active: email_intercept** | Limited | Y | Y | | **Active: nac_bypass** | Y (bridge mode) | Y | Y | | **Active: lateral_move** | Limited | Y | Y | | **Active: cloud_harvest** | Y (passive) | Y | Y | | **AD: kerberoast** | Limited | Y | Y | | **AD: asrep_roast** | Y | Y | Y | | **AD: adcs_attack** | Limited | Y | Y | | **AD: bloodhound_ingest** | N (RAM) | Y | Y | | **AD: dcsync** | Limited | Y | Y | | **AD: coerce** | Y | Y | Y | | **L2L3: stp_attack** | Y | Y | Y | | **L2L3: hsrp_takeover** | Y | Y | Y | | **L2L3: ospf_inject** | Y | Y | Y | | **Exfil: all channels** | Y | Y | Y | | **Connectivity: cellular** | N (power) | Y | Y | | **Connectivity: BLE** | Y | Y | Adapter needed | | **Stealth: lkm_rootkit** | N | N | Y | | **Stealth: overlayfs** | Y (30MB) | Y (200MB) | N/A | | **Stealth: ja3_spoofer** | Y | Y | Y | | **Intel: file_carver** | N (RAM) | Y | Y | | **Intel: net_intel** | Limited | Y | Y | ### Pi Zero 2W Constraints - Max 4 passive + 1 active module simultaneously - Snap length 96 bytes (headers only) for packet capture - Flow table capped at 5,000 entries, 10-minute timeout - No mitmproxy, no file_carver, no bloodhound_ingest - PBKDF2 instead of Argon2id for key derivation - zlib instead of lzma for compression - Single-threaded processing where possible - Temperature throttle at 75C (no heatsink) - 256MB swap (emergency only — SD card wear concern) ### Memory Budget: Pi Zero 2W Sleeper Mode | Component | RAM (MB) | |---|---| | OS + kernel | ~110 | | Python interpreter | ~25 | | Core framework | ~15 | | packet_capture (96B) | ~30 | | host_discovery | ~15 | | credential_sniffer | ~20 | | kerberos_harvest | ~15 | | stealth modules | ~20 | | encrypted_storage | ~10 | | overlayfs overhead | ~30 | | exfil_stager | ~20 | | connectivity | ~25 | | **TOTAL** | **~335** | | **Headroom** | **~65** | --- ## 11. Detection Risk Matrix | Capability | Detection Risk | Evasion Strategy | Notes | |---|---|---|---| | Passive packet capture | **LOW** | Promiscuous mode on bridge; no traffic generated | Invisible unless physical inspection | | Host discovery (passive) | **LOW** | Reads ARP table, listens for broadcasts | Zero active traffic | | Credential sniffing | **LOW** | Passive extraction from observed traffic | No network footprint | | Kerberos harvesting | **LOW** | Passive extraction from Kerberos traffic | No active queries | | Protocol analysis | **LOW** | Passive traffic observation | No traffic generated | | Traffic baseline | **LOW** | 48h of pure listening | Enables future blending | | ARP spoofing | **MEDIUM** | Rate-limited replies, jittered timing | Detected by DAI, ARP watch | | DNS spoofing | **MEDIUM** | Selective targeting, upstream forwarding | Detected by DNS monitoring | | LLMNR/NBT-NS poisoning | **MEDIUM** | Selective targeting, fingerprint mode | Detected by advanced EDR | | NTLM relay | **MEDIUM** | Coordinated with Responder timing | Detected by SMB signing enforcement | | SSL stripping | **HIGH** | HSTS bypass attempts | **Mostly dead** — HSTS preload kills it | | Evil twin AP | **HIGH** | Channel separation, power matching | WIDS/WIPS detect rogue APs | | DHCP spoofing | **MEDIUM** | Race condition timing, selective targets | DHCP snooping detects | | VLAN hopping | **HIGH** | Double-tagging requires native VLAN mismatch | **Rarely works** on modern switches | | IPv6 SLAAC spoofing | **LOW** | Most networks don't monitor IPv6 | RA Guard detects if deployed | | STP root bridge | **HIGH** | Lowest priority BPDU | BPDU guard detects immediately | | HSRP/VRRP takeover | **MEDIUM** | Priority manipulation, auth bypass | Protocol state change logged | | OSPF injection | **HIGH** | Requires auth key | Route changes visible to all speakers | | Nmap scanning | **MEDIUM** | T2 timing, source port 53, randomization | IDS rules match patterns | | Kerberoasting | **LOW** | Normal TGS requests — indistinguishable | No detection signature | | AS-REP roasting | **LOW** | Normal AS-REQ — indistinguishable | Requires known usernames | | ADCS abuse | **LOW** | Normal certificate enrollment | Certificate request logging may flag | | PetitPotam coercion | **LOW** | Single authenticated RPC call | Event log entries but rarely monitored | | BloodHound ingest | **LOW** | Normal LDAP queries | Volume may be flagged by SIEM | | DCSync | **MEDIUM** | Replication API — legitimate but rare | Detected by monitoring replication events | | Lateral movement | **MEDIUM** | Use captured credentials, normal auth | Failed auth attempts logged | | Cloud token harvest | **LOW** | Passive extraction from MITM position | No cloud API calls | | NAC bypass (bridge) | **LOW** | Transparent — EAP passes through | Physical inspection only detection | | Domain fronting C2 | **LOW** | HTTPS to legitimate CDN | Some CDNs now block | | DNS tunnel exfil | **MEDIUM** | Low rate, randomized types, multi-domain | High query volume detectable | | DoH exfil | **LOW** | HTTPS to Google/Cloudflare | Virtually undetectable | | ICMP tunnel | **LOW-MEDIUM** | Mimics normal ping size/interval | Payload analysis detects | | Tailscale C2 | **LOW** | Looks like HTTPS to Derp servers | Tailscale IPs could be blocklisted | | WireGuard C2 | **LOW** | Encrypted UDP, looks like noise | Fixed port may be flagged | | Cellular C2 | **LOW** | Out-of-band, bypasses network entirely | Physical detection of modem | | Process disguise | **LOW** | Matches legitimate system services | Memory analysis reveals | | LKM rootkit | **LOW** | Kernel-level hiding | Rootkit hunters (rkhunter, chkrootkit) | | Traffic mimicry | **LOW** | Matches established baseline patterns | Advanced ML-based detection | --- ## 12. Attack Chain Recipes ### Recipe 1: Domain Takeover via ADCS ``` Prerequisites: Bridge deployed, passive collection running, AD domain detected Detection Risk: LOW-MEDIUM overall Time Estimate: 2-6 hours (plus 48h baseline) Success Rate: ~70% when ADCS present with vulnerable templates Chain: 1. [PASSIVE] env_classifier detects AD domain 2. [PASSIVE] kerberos_harvest captures AS-REP hashes (if any no-preauth accounts) 3. [PASSIVE] protocol_analyzer identifies DCs, ADCS servers 4. [ACTIVE] responder starts LLMNR/NBT-NS poisoning → captures NTLMv2 hashes 5. [ACTIVE] ntlm_relay configured to relay to ADCS HTTP enrollment 6. [ACTIVE] coerce.petitpotam targets DC → DC authenticates to implant 7. [ACTIVE] ntlm_relay relays DC auth to ADCS → obtains DC certificate 8. [ACTIVE] Use DC cert for Kerberos authentication → obtain TGT as DC 9. [ACTIVE] dcsync extracts all domain hashes 10. [EXFIL] Credential dump exfiltrated via DoH channel Fallback paths: - If ADCS not present: coerce → relay to LDAP → add replication rights → DCSync - If coercion fails: kerberoast + offline cracking → use cracked creds - If no relay targets: bloodhound_ingest to find alternative attack paths ``` ### Recipe 2: Credential Harvesting (Passive + Active) ``` Prerequisites: Bridge deployed, passive collection running Detection Risk: LOW (passive), MEDIUM (active phase) Time Estimate: 24-72 hours passive, 2-4 hours active Success Rate: ~90% (some credentials always flow in cleartext) Chain: 1. [PASSIVE] credential_sniffer captures cleartext (FTP, HTTP, SNMP, Telnet) 2. [PASSIVE] kerberos_harvest extracts Kerberos hashes from traffic 3. [PASSIVE] protocol_analyzer identifies all authentication protocols in use 4. [PASSIVE] wireless_intel captures WPA handshakes (if WiFi in scope) 5. [ACTIVE] responder poisons LLMNR/NBT-NS → NTLMv2 hash capture 6. [ACTIVE] evil_twin with captive portal → credential phishing 7. [ACTIVE] ipv6_attack SLAAC spoof → become IPv6 gateway → intercept auth 8. [INTEL] credential_db consolidates all, exports hashcat format 9. [EXFIL] Credential dump exfiltrated (highest priority) Credential types captured: - Cleartext passwords (FTP, HTTP Basic, Telnet, SNMP communities) - NTLMv1/v2 hashes (Responder, passive NTLM extraction) - Kerberos TGS hashes (Kerberoasting from traffic) - Kerberos AS-REP hashes (no pre-auth accounts) - HTTP form credentials (captive portal) - WPA handshakes (offline cracking) - Session tokens / cookies (session hijack) ``` ### Recipe 3: Network MITM Full Chain ``` Prerequisites: Bridge deployed, hardening_detector run, targets identified Detection Risk: MEDIUM Time Estimate: 1-2 hours setup, continuous operation Success Rate: ~80% (blocked by DAI, DHCP snooping) Chain: 1. [RECON] hardening_detector checks for DAI, DHCP snooping, port security 2. [ACTIVE] arp_spoof targets specific hosts (not full subnet — less noise) 3. [ACTIVE] dns_spoof redirects specific domains (selective, not wildcard) 4. [ACTIVE] session_hijack extracts cookies and tokens from intercepted traffic 5. [ACTIVE] file_extractor carves files from HTTP/SMB/FTP traffic 6. [ACTIVE] email_intercept captures SMTP/IMAP messages 7. [ACTIVE] cloud_harvest extracts AWS/Azure/GCP tokens from HTTPS Alternative (if ARP spoof blocked by DAI): 1. [ACTIVE] ipv6_attack — SLAAC spoofing (IPv6 RA Guard less common than DAI) 2. [ACTIVE] dhcp_spoof — race legitimate DHCP (if snooping not enabled) 3. [ACTIVE] hsrp_takeover — become gateway at L3 (if HSRP/VRRP in use) ``` ### Recipe 4: Cloud Pivot from On-Prem ``` Prerequisites: Credentials obtained (from Recipe 2), cloud environment detected Detection Risk: LOW-MEDIUM Time Estimate: 4-8 hours Success Rate: ~60% (depends on cloud posture) Chain: 1. [PASSIVE] env_classifier detects cloud-heavy environment 2. [PASSIVE] cloud_harvest extracts tokens from observed traffic 3. [ACTIVE] lateral_move accesses hosts with cloud CLI tools installed 4. [ACTIVE] cloud_harvest (active) reads AWS/Azure/GCP credentials from disk 5. [ACTIVE] cloud_harvest reads EC2 metadata / managed identity endpoints 6. [EXFIL] Cloud tokens exfiltrated (high priority) 7. [C2] Operator uses tokens from external position for cloud enumeration Cloud-specific paths: - AWS: Instance role credentials → assume-role chain → S3 data access - Azure: Managed identity → Graph API → email/SharePoint access - GCP: Service account key → Cloud Storage → BigQuery data access ``` ### Recipe 5: Wireless Compromise ``` Prerequisites: WiFi adapter in scope, wireless targets authorized Detection Risk: HIGH (evil_twin), MEDIUM (passive) Time Estimate: 2-8 hours Success Rate: ~70% (depends on WIDS/WIPS presence) Chain: 1. [PASSIVE] wireless_intel captures probe requests → identifies client networks 2. [PASSIVE] wireless_intel detects WIDS presence → adjust attack parameters 3. [PASSIVE] wireless_intel captures WPA handshakes passively 4. [ACTIVE] evil_twin clones target SSID on adjacent channel 5. [ACTIVE] evil_twin sends deauth frames to target AP (force client migration) 6. [ACTIVE] evil_twin serves captive portal → credential harvest 7. [ACTIVE] Alternatively: WPA handshake capture → exfil for offline cracking 8. [INTEL] Captured credentials added to credential_db WIDS-aware adjustments: - If WIDS detected: skip deauth, rely on natural roaming - Reduce evil_twin power to minimum needed - Use legitimate-looking SSID variations (add "5G", "Guest") - Time attacks during high-traffic periods (arrival/lunch) ``` --- ## 13. OPSEC Guidelines ### Pre-Deployment 1. **Sanitize hardware**: Remove all identifying labels, serial number stickers. Use generic enclosure. 2. **MAC address**: Change from Raspberry Pi OUI (B8:27:EB, DC:A6:32, E4:5F:01) to common vendor (Dell, HP, Intel) BEFORE connecting to target network. 3. **Hostname**: Generic IoT name (iot-sensor-03, thermostat-1, printer-queue). Never use "kali", "attack", "pentest". 4. **SSH keys**: Generate fresh keys for each engagement. No reuse. Neutral key comment (no username@hostname). 5. **Tailscale**: Use per-engagement auth key. Hostname matches device disguise. Tag with innocuous labels. 6. **SD card**: Use high-endurance industrial card (Samsung PRO Endurance, SanDisk MAX Endurance). Configure overlayfs for write protection. 7. **Pre-bundle everything**: All tools, databases, signatures installed before deployment. Zero package installs on target network. 8. **Scope file**: Populate scope.yaml completely BEFORE deployment. Never deploy without scope. ### During Operation 9. **48-hour baseline**: Always capture baseline before any active operation. This delay is an investment. 10. **Hardening detection**: Run hardening_detector before activating any attack module. Respect the results. 11. **Working hours only**: Active modules operate during business hours only (configurable). After-hours activity is anomalous. 12. **Traffic blending**: Use traffic_mimicry to shape implant traffic to match baseline patterns. 13. **JA3 fingerprinting**: All outbound HTTPS uses ja3_spoofer to match Chrome/Firefox fingerprint. 14. **Rate limiting**: All active modules use jitter. Never send at fixed intervals. 15. **Scope enforcement**: Every target IP checked against scope.yaml before any active interaction. No exceptions. 16. **OT/SCADA lockout**: If OT protocols detected, those subnets are permanently locked out from active modules. Passive observation only. 17. **Supply chain**: Detection only. Exploitation requires separate written operator approval beyond normal scope authorization. 18. **IDS self-testing**: Run ids_tester before new active module activation to estimate detection risk. 19. **Selective targeting**: Never ARP spoof an entire subnet. Target specific hosts. Less noise. 20. **C2 channel rotation**: Don't rely on a single C2 channel. Use failover chain. Rotate primary channel periodically. ### Network Footprint 21. **Bridge mode**: Implant invisible at L2/L3. No IP, no MAC on network. Physical inspection only. 22. **Tailscale**: Looks like HTTPS to Derp servers. Corporate firewalls allow. Only anomaly: Tailscale destination IPs. 23. **DNS tunneling**: Low rate (<1 query/sec), randomize query types, use multiple domains, legitimate-looking subdomain patterns. 24. **Domain fronting**: HTTPS to high-reputation CDN. Network sees legitimate CDN traffic. 25. **DoH**: DNS queries over HTTPS to Google/Cloudflare. Virtually unblockable. ### Host Forensics 26. **Process names**: All processes match legitimate system services. `ps aux` shows nothing suspicious. 27. **File paths**: Installed in `/opt/.cache/bb/` — looks like a system cache directory. 28. **Log suppression**: rsyslog filters, auditd exclusions, journald rate-limit increase. 29. **Encrypted storage**: All sensitive data on LUKS. Network-derived key option means physical seizure is not enough. 30. **tmpfs**: Active operations in RAM. Power loss = instant evidence destruction. 31. **overlayfs**: SD card sees zero write activity (except LUKS container). 32. **No bash history**: HISTFILE unset. utmp/wtmp/btmp entries for implant sessions removed. 33. **Timestamps**: All created files timestomped to match OS install date. ### Kill Switch 34. **Multi-trigger**: CLI command, remote (Tailscale), dead man's switch (no heartbeat), physical (GPIO), GPS geofence. 35. **Speed first**: Key destruction takes milliseconds. Data is immediately unrecoverable. Full overwrite follows. 36. **Resilient**: If interrupted, next boot auto-completes wipe via boot flag. 37. **Anti-recovery**: LUKS header destruction sufficient. Belt-and-suspenders dd overwrite follows. ### Counter-Intelligence 38. **Beacon detection**: protocol_analyzer identifies existing C2/malware on the network. Valuable intel AND avoids stepping on other operations. 39. **WIDS detection**: wireless_intel identifies wireless IDS before attempting WiFi attacks. 40. **IDS testing**: ids_tester checks planned actions against known rule signatures. 41. **DHCP fingerprinting**: Vendor class identifier matches spoofed device type. --- ## 14. Reliability Safeguards ### SD Card Reliability 1. **overlayfs**: Root filesystem mounted read-only with tmpfs overlay. Only LUKS container writes to SD. 2. **High-endurance cards**: Require Samsung PRO Endurance or equivalent (rated for continuous write). 3. **USB storage option**: External USB drive for PCAP and bulk data (preserves SD life). 4. **SMART monitoring**: If USB storage, monitor health via smartctl. 5. **Write amplification reduction**: Disable journaling on ext4 data partition (tune2fs -O ^has_journal). LUKS handles integrity. ### Power Reliability 6. **UPS HAT**: Support for PiJuice, UPS HAT 2, or similar battery backup. 7. **Graceful shutdown**: On power loss detection (GPIO interrupt from UPS), initiate: - Stop active modules (prevent half-completed attacks) - Flush all pending writes - Lock encrypted storage - Safe filesystem unmount - Shutdown 8. **Boot recovery**: On unexpected power loss (no graceful shutdown), boot sequence: - Check for incomplete wipe flag → complete wipe if found - fsck on data partitions - Start in passive-only mode (operator must re-authorize active) - Alert via C2 that ungraceful shutdown occurred ### Process Reliability 9. **Watchdog hierarchy**: systemd → watchdog service → engine → per-module monitoring 10. **Module isolation**: Subprocess per module on Pi Zero. OOM killer targets lowest-priority module. 11. **oom_score_adj**: Core=-500 (never killed), Passive=100, Active=200 (killed first). 12. **Memory leak detection**: Resource monitor tracks per-module RSS over time. Kills + restarts if growth exceeds 2x estimate. 13. **Crash recovery**: Module crash → auto-restart up to 3 times → disable + alert. ### Network Reliability 14. **Failover chain**: Tailscale → WireGuard → SSH reverse → HTTP tunnel → DNS tunnel → Cellular 15. **Bridge failsafe**: If bridge fails, fall back to passive tap (promiscuous without bridge). 16. **C2 health check**: Periodic heartbeat. Failed heartbeat → try next channel in chain. 17. **Connectivity state machine**: Each channel has CONNECTED/DEGRADED/FAILED states. Auto-promote next channel. ### Data Integrity 18. **SQLite WAL mode**: Concurrent reads, crash-safe writes. 19. **PCAP checksums**: SHA-256 hash stored per PCAP file. Verify before exfil. 20. **Exfil ACK protocol**: Each chunk acknowledged by C2. Unacknowledged chunks retransmitted. 21. **Credential dedup**: UNIQUE constraints prevent duplicate entries in credential_db. ### Deployment Validation 22. **Pre-flight checks**: setup.sh validates all dependencies installed, services configured, permissions set. 23. **Self-test mode**: `bigbrother.py selftest` runs: module discovery, bus communication, crypto round-trip, resource detection, scope loading, network interface enumeration. 24. **Dry-run mode**: Active modules support `--dry-run` that validates config and checks permissions without generating traffic. --- ## 15. Error Handling Strategy ### Layered Error Handling ``` Layer 1: Module-level - Try/except around all network I/O - Socket errors: retry with backoff (max 3) - Permission errors: log + MODULE_ERROR + graceful stop - Resource errors: request resource_monitor assessment - Parse errors: debug log, continue Layer 2: Engine-level - Module crash: catch, log, MODULE_ERROR, attempt restart - Module hang (60s no response): force kill, restart - Dependency failure: pause dependent modules Layer 3: System-level (watchdog + systemd) - Watchdog monitors core service - systemd Restart=on-failure / Restart=always - PID, memory, disk checks Layer 4: Catastrophic - OOM: kill lowest-priority active module - Disk full: purge oldest PCAPs, pause capture - Network down: failover chain - Power loss: boot recovery sequence - SD card failure: switch to tmpfs-only mode - Kill switch failure: continue sequence, skip failed step ``` ### Error Recovery Matrix | Error Type | Action | Notification | |---|---|---| | Socket timeout | Retry 3x → stop module | MODULE_ERROR | | Permission denied | Stop module, report | MODULE_ERROR | | OOM | Kill lowest-priority active | RESOURCE_CRITICAL + push | | Disk full | Purge old PCAPs, pause capture | RESOURCE_CRITICAL + push | | Module crash | Auto-restart (max 3) | MODULE_ERROR | | C2 disconnect | Failover chain | CONNECTIVITY_CHANGED + push | | SD card failure | tmpfs-only mode | RESOURCE_CRITICAL + push | | Scope violation | Block action, alert | SCOPE_VIOLATION + push | | OT protocol detected | Lock out active for subnet | OT_PROTOCOL_DETECTED + push | | Kill switch fail | Continue, skip step | Volatile log only | | Bridge failure | Fall back to passive tap | CONNECTIVITY_CHANGED + push | | Tailscale auth expiry | Failover to WireGuard | CONNECTIVITY_CHANGED | ### Specific Failure Modes **Bridge failure**: Traffic stops flowing through target network. Catastrophic for engagement. Mitigation: `Restart=always`, ebtables fallback, CONNECTIVITY_CHANGED event. If unrestorable in 60s, fall back to passive tap. **Tailscale auth expiry**: Pre-auth keys have TTL. Monitor for "NeedsLogin" state, failover to WireGuard, alert operator via dead-drop DNS TXT. **NAC bypass disruption**: If 802.1X re-authentication kicks the victim device, bridge passthrough handles re-auth transparently. If victim device reboots, monitor for EAPOL exchange and pass through. **Encrypted storage corruption**: LUKS header backup in separate location. Periodic integrity check via `cryptsetup luksDump`. If corrupted, data lost but implant continues operating with tmpfs-only storage. **LKM rootkit panic**: Kernel module bug = kernel panic = device reboot. Mitigation: extensive testing. Module has `safe_mode` flag that limits hooking to reduce risk. Never auto-load — operator must explicitly request. --- ## 16. Key Design Decisions 1. **Event bus architecture**: Modules communicate through pub/sub, not direct calls. Clean testing, easy module addition. 2. **Stealth-first initialization**: Phase 2 (stealth) before Phase 3 (passive collection). Never operate without OPSEC layer. 3. **Mandatory scope enforcement**: Engine refuses to start active modules without valid scope.yaml. Every target checked. OT/SCADA hard lockout. 4. **48-hour baseline before active ops**: Operational cost is justified by dramatically better traffic blending. 5. **Hardware tier enforcement**: Pi Zero 2W gets hard module limits. No ambiguity about what can run. 6. **Multi-channel C2 with automatic failover**: Six-deep failover chain. Chunk-based transfer with ACK for resume. 7. **Kill switch is first-class**: Integrates with every module, multiple triggers, survives interruption, speed-first design. 8. **Everything encrypted at rest**: Only plaintext on disk is minimal bootstrap code to unlock encrypted storage. 9. **SSL stripping deprecated**: Opt-in only with explicit warnings. HSTS killed it. 10. **VLAN hopping deprioritized**: Rarely works on modern switches. Built last, warning on activation. 11. **OT/SCADA passive only**: Hard lockout. No exceptions. No override. Industrial safety is non-negotiable. 12. **Supply chain requires separate approval**: Detection is passive and automatic. Exploitation requires explicit written operator approval. 13. **LKM rootkit is optional**: Only for compromised host deployment. Never for Pi hardware. Kernel panics are unacceptable for implant reliability. 14. **Decision engine recommends, operator decides**: State machine suggests transitions and module selections. Operator must approve all escalations beyond RECON. 15. **SD card protection via overlayfs**: Reliability is critical for long-duration deployments. Zero writes to SD except LUKS container. --- ## Appendix A: Battle-Tested vs Theoretical Assessment Based on Red Team Professional (Agent 5) real-world engagement experience: ### Battle-Tested (High Confidence) - Responder LLMNR/NBT-NS poisoning - NTLM relay attacks - Kerberoasting / AS-REP roasting - PetitPotam → ADCS relay chain - BloodHound data collection - DCSync - ARP spoofing (when DAI absent) - Evil twin with captive portal - IPv6 SLAAC spoofing (most networks don't monitor IPv6) - DNS tunneling for exfil - Domain fronting C2 - Tailscale/WireGuard for reliable C2 - NAC bypass via transparent bridge - Probe request collection - WPA handshake capture ### Works But With Caveats - HSRP/VRRP takeover (requires auth key or no auth) - DHCP spoofing (race condition, DHCP snooping blocks) - Scanner with T2 timing (works but sophisticated IDS catches patterns) - Lateral movement via impacket (noisy if credentials wrong) - Cloud token harvest from traffic (depends on MITM position) - Dead drop exfil (operational overhead) - JA3 spoofing (Python implementation tricky) ### Theoretical / Lab-Proven But Field-Uncertain - VLAN hopping via double-tagging (almost never works in production) - SSL stripping (HSTS killed it for modern sites) - STP root bridge takeover (very noisy, instant alerts) - OSPF route injection (requires auth key) - EAP relay NAC bypass (timing-sensitive) - LKM rootkit on unknown kernels - Steganographic exfil (low bandwidth, high implementation complexity) - BLE device fingerprinting (accuracy varies) - Traffic mimicry ML baseline (only as good as the model) - IDS ruleset self-testing (only tests known rules) --- ## Appendix B: Critical Implementation Files Priority-ordered by architectural importance: 1. `core/engine.py` — Everything depends on module lifecycle working correctly 2. `core/scope_enforcer.py` — Must be bulletproof; scope violations are engagement-ending 3. `modules/base.py` — Module contract; wrong design causes cascading refactors 4. `core/bus.py` — Architectural backbone; thread safety critical 5. `utils/crypto.py` — A flaw here compromises everything 6. `modules/passive/packet_capture.py` — Most complex passive module; performance-critical 7. `modules/active/nac_bypass.py` — #1 tribe addition; bridge passthrough must be solid 8. `modules/ad/coerce.py` + `modules/active/ntlm_relay.py` — Core of the AD attack chain 9. `decision/env_classifier.py` — Drives attack recommendations; accuracy matters 10. `modules/stealth/traffic_mimicry.py` — Baseline quality determines OPSEC quality