# Shadow Network
A covert peer-to-peer communication library for Rust, built around steganography,
onion routing, pluggable transports, and traffic analysis resistance.
---
## What is this?
Shadow Network is a collection of 22 Rust crates that, together, let you build
communication systems whose traffic is designed to be indistinguishable from
ordinary network activity. The library covers the full stack -- from low-level
cryptographic primitives up to application-level messaging with offline queues
and group chat.
It is a library, not an application. You pull in the crates you need and wire
them into your own project.
## Getting started
Add the top-level crate to your project:
```toml
[dependencies]
shadow-network = "0.1.0"
```
Or pick only the pieces you need:
```toml
[dependencies]
shadow-crypto = "0.1.0"
shadow-onion-routing = "0.1.0"
shadow-steganography = "0.1.0"
```
## Quick commands
```bash
# Run the full system check (22 subsystems + live end-to-end demo)
cargo run
# Run all 333 tests
cargo test --workspace
# Run a specific demo
cargo run --example phase4_demo
cargo run --example phase3_demo
cargo run --example phase2_demo
# Release build
cargo build --release
```
## Feature overview
### Protocol mimicry
Traffic is wrapped to look like WebRTC video conferencing, HTTPS browsing, or
IoT device chatter (MQTT, CoAP). Timing patterns are matched to the cover
protocol so that a passive observer doing deep packet inspection sees nothing
unusual.
### Steganographic encoding
Data can be hidden inside images using adaptive LSB embedding, DCT coefficient
modification, or spread-spectrum techniques. The encoder matches the entropy
profile of the cover medium so that statistical steganalysis is as hard as
possible.
### Distributed hash table
Peer discovery and key-value storage are handled by a Kademlia-based DHT with
XOR distance routing, geographic awareness, and Sybil resistance through a
reputation layer.
### NAT traversal
Full ICE implementation: STUN binding discovery, TURN relay fallback, UDP hole
punching, and UPnP/NAT-PMP port forwarding -- all disguised as whatever cover
protocol is in use.
### Distributed storage
Content-addressed chunks (BLAKE3), Reed-Solomon erasure coding, passive and
active replication, automatic deduplication.
### Cryptography
- ChaCha20-Poly1305 AEAD encryption
- X25519 key exchange (forward secrecy)
- Ed25519 signatures
- BLAKE3 hashing and HKDF key derivation
### Onion routing
Tor-style circuit construction with layered encryption through a configurable
number of relay hops.
### Traffic analysis resistance
Constant-bandwidth dummy traffic, adaptive timing jitter, packet-size
distribution matching, and mix-network batching to resist correlation attacks.
### Pluggable transports
An obfs XOR-stream transport, domain-fronting via CDN, and a bridge relay
system for unlisted entry points into the network.
### Reputation and Sybil defense
Composite trust scoring, proof-of-work identity puzzles, behavior tracking,
and epoch-based decay.
## Architecture
```
+---------------------------------------------------------------+
| Message Layer | File Sharing | Content Discovery | UI / API |
+---------------------------------------------------------------+
| Crypto Layer |
| (E2E Encryption, Signatures, Key Exchange) |
+---------------------------------------------------------------+
| Distributed Storage Layer (DHT) |
| (Content Addressing, Replication, Erasure Coding) |
+---------------------------------------------------------------+
| P2P Overlay Network |
| (Peer Discovery, Routing, NAT Traversal) |
+---------------------------------------------------------------+
| Steganography Engine |
| (Adaptive Embedding, Entropy Matching, Extraction) |
+---------------------------------------------------------------+
| Protocol Mimicry Layer |
| (WebRTC, HTTPS, IoT Protocol Emulation, Packet Shaping) |
+---------------------------------------------------------------+
| Transport Layer |
| (TCP, UDP, QUIC, TLS Handling) |
+---------------------------------------------------------------+
```
## Crate map
| 1 | shadow-core | Core types, PeerId, traits, error handling |
| 1 | shadow-crypto | ChaCha20-Poly1305, X25519, Ed25519, BLAKE3 |
| 1 | shadow-dht | Kademlia distributed hash table |
| 1 | shadow-steganography | LSB image/audio steganography |
| 1 | shadow-storage | Content-addressed storage with erasure coding |
| 1 | shadow-protocols | Protocol mimicry (WebRTC, HTTPS) |
| 1 | shadow-nat-traversal | STUN/TURN NAT hole punching |
| 1 | shadow-utils | Shared utilities |
| 2 | shadow-transport | libp2p-based P2P transport layer |
| 2 | shadow-messaging | E2E encrypted messaging with offline queues |
| 2 | shadow-stego-transport | Steganographic pipeline: image hiding + protocol mimicry |
| 2 | shadow-client | High-level node builder and API |
| 3 | shadow-benchmarks | Performance profiling and reports |
| 3 | shadow-monitoring | Metrics, health checks, alerting |
| 3 | shadow-security-audit | Fuzzing, timing attack detection, crypto verification |
| 3 | shadow-integration-tests | Cross-crate integration tests |
| 3 | shadow-load-testing | 10,000+ peer swarm simulation |
| 4 | shadow-onion-routing | Circuit-based Tor-style anonymous routing |
| 4 | shadow-traffic-analysis | Constant-rate shaping, mix networks |
| 4 | shadow-pluggable-transports | Obfs transport, domain fronting, bridge relays |
| 4 | shadow-reputation | Trust scoring, Sybil defense |
| 4 | shadow-network-sim | Adversary modeling, censorship simulation |
## Building
You need Rust 1.70 or later. Optional system libraries:
- libpcap-dev -- for packet capture analysis
- FFmpeg libraries -- for media processing
```bash
cargo build --release # all crates
cargo build -p shadow-crypto # just one crate
cargo test --workspace # full test suite
```
## Usage example
```rust
use client::{ShadowNodeBuilder, ShadowApi};
use crypto::Keypair;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let keypair = Keypair::generate();
let node = ShadowNodeBuilder::new()
.with_keypair(keypair)
.build()?;
let mut api = ShadowApi::new(node);
api.start().await?;
// store a value in the DHT
let key = [1u8; 32];
api.store(key, bytes::Bytes::from("hello")).await?;
// retrieve it
if let Some(data) = api.retrieve(&key).await {
println!("got: {}", String::from_utf8_lossy(&data));
}
api.stop().await?;
Ok(())
}
```
## Security considerations
The library is designed to resist:
- Deep packet inspection and flow analysis
- Timing correlation and volume analysis
- Protocol-level censorship and traffic shaping
- Man-in-the-middle and replay attacks
- Sybil attacks through reputation scoring
Known limitations:
- Endpoint compromise exposes everything
- A global passive adversary can still correlate traffic across the whole network
- Dummy traffic increases bandwidth usage
- Multi-hop routing adds latency
## Performance ballpark
| Throughput | 80-95% of cover protocol | at 10% steganographic capacity |
| Routing latency | 50-200 ms | 3-hop onion circuit |
| Connection setup | 2-5 s | includes NAT traversal |
| DHT lookup | 100-500 ms | with delayed lookups |
| Packet overhead | 15-20% | headers + padding |
## Contributing
Contributions are welcome. Useful areas:
- New protocol mimicry implementations
- Better steganographic algorithms
- Performance work
- Security analysis and threat modeling
- Documentation and examples
## Ethics
This is dual-use technology. It can protect journalists and activists under
authoritarian regimes; it can also be misused. Users are responsible for
complying with their local laws and for considering the ethical implications of
what they build with it.
## License
MIT. See the LICENSE file for the full text.
## Disclaimer
This software is provided for research and educational purposes. The author
assumes no liability for misuse. Do not rely on it in life-or-death situations
without a thorough independent security audit.