BlackBerryC2 2.0.0-beta

BlackBerryC2 is an encrypted remote administration and C2 framework designed exclusively for educational use, security research, and controlled laboratory environments.

The project demonstrates how to build a custom command-and-control server with application-layer cryptography, session management, and secure client communication without relying on external TLS stacks.

⚠️ Important Notice

This project is NOT malware and NOT intended for unauthorized access.

BlackBerryC2:

• Does not self-propagate
• Does not exploit vulnerabilities automatically
• Does not include persistence mechanisms
• Does not attempt to evade antivirus software

Use only on systems and networks you own or have explicit authorization to test.

Python dependencies:

pip install cryptography prompt_toolkit zstandard

zstandard is optional but recommended for transfers larger than 1 GB.

Key Features

• Custom TCP-based encrypted C2 server (v2.0)
• ECDHE (secp256r1) key exchange — ephemeral or persistent
• AES-256-GCM authenticated encryption per session
• HMAC-SHA256 per-packet authentication + anti-replay sequence numbers
• Multiple concurrent client sessions
• Interactive operator console with tab-completion (prompt_toolkit)
• Encrypted remote command execution
• Encrypted file transfers with zlib / Zstandard compression
• Recursive directory upload/download (get -r, put -r)
• Background transfers (-b flag) — non-blocking, cancellable
• Transfer resume support (.partial + .resume files)
• Client payload generator (generate-payload)
• IP blocking: persistent blocklist + temporary auto-bans
• Scan/flood detection: connect scan, banner grab, handshake failures, heartbeat flood
• Optional HTTP(S)/TLS proxy support (BlackBerryHTTPs_TLSProxyGUI)
• SPA (Single Packet Authorization) and Port-Knocking pre-auth
• BerryTransfer mode — dedicated file-transfer-only server (no shell)
• Encrypted session log (AES-256-GCM + PBKDF2, 600k iterations)
• Encrypted server log with in-shell viewer (log command)
• Startup config saved to logs/last_start.json

Cryptographic Design

BlackBerryC2 v2.0 establishes secure communication as follows:

1. Client connects via TCP; server sends service banner.
2. Client sends REQUEST_PUBKEY.
3. Server sends its ephemeral ECDHE public key (secp256r1).
4. Client sends its ECDHE public key + HMAC-SHA256 authentication tag.
5. Server verifies the HMAC against the pre-shared secret (HMAC_PRE_SHARED_SECRET).
6. Both sides derive a 256-bit AES session key via HKDF-SHA256 over the shared secret.
7. All further communication uses AES-256-GCM with per-packet HMAC-SHA256 and anti-replay sequence numbers.

Each session maintains:

• Its own AES-256 key and HMAC key
• Independent nonces (12-byte random per message)
• Isolated anti-replay tracker (sequence window ±100)
• Flood protection rate limiter (configurable commands/second)

All cryptographic keys are generated at runtime and never reused across restarts (unless --persistente is set).

Running the Server

python3 BlackBerryC2_server.py

Default configuration:

• Host: 0.0.0.0
• Port: 9949

Command-Line Arguments

Examples:

# Basic startup (prompts for log passphrase)
python3 BlackBerryC2_server.py

# Persistent ECDHE keys + verbose
python3 BlackBerryC2_server.py -p -vv

# Custom port, no HMAC check
python3 BlackBerryC2_server.py -P 8080 --no-secure

# Port-knocking on custom ports
python3 BlackBerryC2_server.py --spa --spa-mode knock --knock-seq 9001,9002,9003

# BerryTransfer mode with auto-confirm
python3 BlackBerryC2_server.py --berrytransfer --auto-confirm

# View/decrypt logs without starting server
python3 BlackBerryC2_server.py --logs

Operator Console Commands

Server Management

Proxy

Session Commands (inside select <ID>)

General

File Transfer

BerryTransfer Mode

BerryTransfer is a dedicated file-transfer-only server mode inspired by scp. When active, the server rejects all shell access and only accepts BT:* protocol commands.

Start:

python3 BlackBerryC2_server.py --berrytransfer
python3 BlackBerryC2_server.py --berrytransfer --auto-confirm  # no operator prompt for GETs

BerryTransfer shell commands:

Transfer log is written to logs/bt_transfer.jsonl (optionally AES-256-GCM encrypted).

SPA / Port-Knocking

When --spa is active, clients must authenticate via UDP before the TCP connection is accepted.

SPA mode (default): Client sends a 32-byte HMAC-SHA256 token to SPA_UDP_PORT.

token = HMAC-SHA256(HMAC_SECRET, "{ip}:{time_window_30s}")

Knock mode: Client knocks a sequence of UDP ports in order within a timeout window.

python3 BlackBerryC2_server.py --spa --spa-mode knock --knock-seq 7001,7002,7003 --knock-timeout 10

Authorized IPs are valid for --spa-ttl seconds (default 60).

Security Features

Logging

View logs with the built-in viewer:

BlackBerry> log

Or standalone (no server):

python3 BlackBerryC2_server.py --logs

Intended Use

This project is intended only for:

• Educational demonstrations
• Security research
• Controlled lab environments
• Authorized penetration testing

Unauthorized use against systems without permission is strictly prohibited.

License

See LICENSE file for full license details.

Disclaimer

This software is provided "as is", without warranty of any kind.
The authors assume no responsibility for misuse or damage caused by this software.