Shadow Network

A covert peer-to-peer communication library for Rust, built around steganography, onion routing, pluggable transports, and traffic analysis resistance.

Author: Devansh Verma | License: MIT | Language: Rust 1.70+

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:

[dependencies]
shadow-network = "0.1.0"

Or pick only the pieces you need:

[dependencies]
shadow-crypto = "0.1.0"
shadow-onion-routing = "0.1.0"
shadow-steganography = "0.1.0"

Quick commands

# 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

+---------------------------------------------------------------+
|                     Client Application                        |
+---------------------------------------------------------------+
| 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

Building

You need Rust 1.70 or later. Optional system libraries:

• libpcap-dev -- for packet capture analysis
• FFmpeg libraries -- for media processing

cargo build --release            # all crates
cargo build -p shadow-crypto     # just one crate
cargo test --workspace           # full test suite

Usage example

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

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.