Initial public release

Full BigBrother network implant - passive SOC + active exploitation. Personal identifiers removed; all capabilities intact. See README.md for setup and docs/deployment.md for detailed deployment.
2026-06-26 09:52:50 -04:00
commit ccc6b729de
175 changed files with 47941 additions and 0 deletions
@@ -0,0 +1,127 @@
+# BigBrother
+
+Network drop implant for silent, autonomous network surveillance. Deploy on any Debian host and get passive SOC-level visibility plus active exploitation capability over a C2 tunnel.
+
+> **Legal notice:** This tool is for authorized penetration testing, red team engagements, and security research on networks you own or have written permission to test. Unauthorized use is illegal and unethical. You are responsible for your actions.
+
+## What It Does
+
+BigBrother turns a cheap SBC or any Debian host into a persistent network implant with two operational modes:
+
+**Passive (always on)**
+- DNS query logging and exfiltration
+- TLS SNI fingerprinting (JA3/JA3S)
+- Credential sniffing (HTTP Basic, FTP, IMAP, POP3, SMTP)
+- Kerberos ticket harvesting
+- Host discovery and device fingerprinting
+- Device presence tripwire (Matrix alerts on arrival/departure)
+
+**Active (operator-triggered)**
+- ARP spoofing and poisoning
+- DNS/DHCP spoofing
+- Responder (LLMNR/NBT-NS/MDNS poisoning)
+- mitmproxy HTTPS interception
+- ntlmrelayx (NTLM credential relay)
+- Bettercap MITM orchestration
+
+**Stealth layer**
+- LKM rootkit (process/file/network hiding)
+- Process disguise and anti-forensics
+- JA3 fingerprint randomization
+- Kill switch
+
+**C2 connectivity**
+- WireGuard, Tailscale, or reverse SSH tunnel
+
+## Hardware
+
+| Board | Capability |
+|-------|-----------|
+| Orange Pi Zero 3 (1GB+) | Full passive + active + stealth |
+| Raspberry Pi 4 | Full passive + active + stealth |
+| Raspberry Pi 3B | Full passive, limited active |
+| Raspberry Pi Zero 2W | Passive only |
+| Any Debian host | Full capability |
+
+Minimum: 512MB RAM, one network interface, Debian 11+.
+
+## Quick Start
+
+1. Clone to the drop host or a staging machine:
+   ```bash
+   git clone <repo-url> bigbrother
+   cd bigbrother
+   ```
+
+2. Install dependencies and configure the implant:
+   ```bash
+   sudo bash operator_setup.sh
+   ```
+
+3. Deploy to a remote target:
+   ```bash
+   bash scripts/deploy.sh root@<target-host>
+   ```
+
+4. Start the core state machine:
+   ```bash
+   sudo python3 bigbrother_core.py
+   ```
+
+See `docs/deployment.md` for full setup, interface configuration, and C2 connectivity.
+
+## Configuration
+
+All config lives in `config/`. Key files:
+
+- `config/bigbrother.yaml` — core settings, module toggles, C2 parameters
+- `config/hardware_tiers.yaml` — per-platform capability profiles
+- `.env` — secrets and runtime overrides (never commit this)
+
+## Architecture
+
+```
+bigbrother_core.py          # Autonomous state machine + orchestrator
+modules/
+  passive/                  # DNS, TLS, credentials, Kerberos, hosts
+  active/                   # bettercap, ARP, DNS/DHCP spoof, Responder, ntlmrelayx
+  stealth/                  # LKM rootkit, process hide, anti-forensics
+  connectivity/             # WireGuard, Tailscale, reverse tunnel
+  analysis/                 # Local alert correlation
+net_alerter/                # Device presence daemon (standalone)
+presence/                   # Person presence tracking (multi-signal)
+utils/                      # Shared: crypto, logging, permissions, stealth
+config/                     # YAML configs and hardware profiles
+scripts/                    # Deploy and setup helpers
+```
+
+## Credential Encryption
+
+Captured credentials are encrypted before local storage and C2 transmission. Requires an Infisical-compatible secrets manager with a `CREDENTIAL_ENCRYPTION_KEY` secret:
+
+```bash
+export BB_CREDS_BIN=/path/to/your/creds-cli
+```
+
+The `creds` CLI must support: `creds get CREDENTIAL_ENCRYPTION_KEY`
+
+If `BB_CREDS_BIN` is not set, credentials are stored in plaintext with a warning.
+
+## Net Alerter
+
+Standalone Matrix alert daemon for device presence monitoring. See `net_alerter/README.md`.
+
+Requires a Matrix homeserver and access token:
+```bash
+MATRIX_HOMESERVER=https://your-homeserver.example.com
+MATRIX_ACCESS_TOKEN=syt_...
+MATRIX_ROOM_ID=!your-room-id:your-homeserver.example.com
+```
+
+## Contributing
+
+See `CONTRIBUTING.md`.
+
+## License
+
+MIT License. See `LICENSE`.