commit 45dc317c31e0b30136c7471136ecf3a6c8ebf92d Author: n0mad1k Date: Tue Mar 17 07:39:01 2026 -0400 Add consolidated BigBrother design document post-tribe review Comprehensive network implant architecture incorporating findings from 6-agent security review tribe. Key additions: 802.1X NAC bypass, AD attack suite (Kerberoast/ADCS/coercion), autonomous decision engine, multi-protocol C2 chain, traffic mimicry, hardware tier enforcement, mandatory scope enforcement, OT/SCADA passive lockout, 5 attack chain recipes, detection risk matrix, and reliability safeguards. diff --git a/BIGBROTHER_DESIGN.md b/BIGBROTHER_DESIGN.md new file mode 100644 index 0000000..bb8d203 --- /dev/null +++ b/BIGBROTHER_DESIGN.md @@ -0,0 +1,2235 @@ +# 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