bigbrother/BIGBROTHER_DESIGN.md

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
2. Full File Tree
3. Module Specifications
4. Module Interaction Model
5. Autonomous Decision Engine
6. Setup & Bootstrap
7. Systemd Services
8. Configuration Schemas
9. Implementation Phases
10. Hardware Tier Matrix
11. Detection Risk Matrix
12. Attack Chain Recipes
13. OPSEC Guidelines
14. Reliability Safeguards
15. Error Handling Strategy
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

#!/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]

# 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]

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

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