Shannon

A Rust CLI utility that calculates and visualizes block-wise Shannon entropy of files. Shannon aims to be command line based replacement for binwalk -E.

Shannon is available on crates.io and on github.

What is Shannon Entropy?

Shannon entropy measures the randomness or information density in data. Values range from 0 to 8 bits per byte:

• 0: Completely uniform (e.g., a file of all zeros)
• ~4-5: Typical text or code
• ~7-8: High randomness (encrypted or compressed data)

Use Cases

• Malware analysis: Identify packed or encrypted sections in executables
• File forensics: Detect hidden or embedded data within files
• Compression analysis: Visualize which parts of a file are already compressed
• Binary reverse engineering: Understand file structure and locate data regions

Screenshot

Installation

Via crates.io

cargo add shannon-cli

Local build

cargo build --release

The binary will be at target/release/shannon.

Usage

shannon <input_file> [OPTIONS]

Options

Examples

Analyze a binary with default settings:

shannon /usr/bin/ls

Use smaller blocks for finer granularity:

shannon firmware.bin --block-size 256

Compact output for smaller terminals:

shannon large_file.dat --width 80 --height 40

Output

A line summarizing the review is outputted.

The tool renders a bar chart in the terminal where:

• X-axis: Block index (position in file)
• Y-axis: Entropy value (0-8 bits per byte)

High entropy regions appear as tall bars, making it easy to spot encrypted or compressed sections at a glance.

A table of rising and falling edges in the entropy.

Library Usage

The crate also exposes a library for use in your own projects:

use shannon::{entropy, total_entropy, detect_edges, EdgeType};

// Calculate entropy of data (returns bits per byte, 0.0-8.0)
let data = b"Hello, world!";
let e: f64 = entropy(data);

// Calculate total entropy (bits per byte * length)
let total: f64 = total_entropy(data);

// Detect rising/falling entropy edges in a sequence
let values: Vec<(usize, f64)> = vec![(0, 7.8), (1, 7.9), (2, 2.0)];
let edges = detect_edges(&values, 0.95, 0.85); // high/low thresholds
for edge in edges {
    match edge.edge_type {
        EdgeType::Rising => println!("Rising edge at block {}", edge.block_index),
        EdgeType::Falling => println!("Falling edge at block {}", edge.block_index),
    }
}

Todo

• Implement dynamic BLOCK_SIZE like binwalk (so identical output is produced without manually matching BLOCK_SIZE).
• Enable input via stdin

License

MIT