shadow_network_sim/

analysis.rs

//! Statistical analysis — entropy, chi-squared, and uniformity tests for traffic.

use serde::{Serialize, Deserialize};

/// Result of statistical analysis on a dataset.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AnalysisResult {
    pub test_name: String,
    pub statistic: f64,
    pub p_value: f64,
    pub is_suspicious: bool,
    pub description: String,
}

/// Comprehensive traffic statistical analyzer.
pub struct StatisticalAnalyzer {
    /// P-value threshold for significance.
    pub significance_level: f64,
}

impl StatisticalAnalyzer {
    pub fn new() -> Self {
        Self {
            significance_level: 0.05,
        }
    }

    pub fn with_significance(mut self, level: f64) -> Self {
        self.significance_level = level;
        self
    }

    /// Shannon entropy of a byte distribution (0.0–8.0).
    pub fn byte_entropy(&self, data: &[u8]) -> f64 {
        if data.is_empty() {
            return 0.0;
        }

        let mut counts = [0u64; 256];
        for &byte in data {
            counts[byte as usize] += 1;
        }

        let len = data.len() as f64;
        let mut entropy = 0.0;

        for &count in &counts {
            if count > 0 {
                let p = count as f64 / len;
                entropy -= p * p.log2();
            }
        }

        entropy
    }

    /// Analyze byte entropy: encrypted/random data should be close to 8.0.
    pub fn entropy_analysis(&self, data: &[u8]) -> AnalysisResult {
        let entropy = self.byte_entropy(data);
        // Encrypted data: entropy > 7.5
        // English text: entropy ~ 4.0-5.0
        // Compressed: entropy > 7.0
        let is_suspicious = entropy < 6.0; // Low entropy = potentially unencrypted

        AnalysisResult {
            test_name: "Byte Entropy".into(),
            statistic: entropy,
            p_value: if is_suspicious { 0.01 } else { 0.5 },
            is_suspicious,
            description: format!(
                "Entropy: {:.3} bits/byte (max 8.0). {}",
                entropy,
                if is_suspicious {
                    "Low entropy may indicate unencrypted/structured data."
                } else {
                    "High entropy consistent with encryption."
                }
            ),
        }
    }

    /// Chi-squared test for uniformity of byte distribution.
    pub fn chi_squared_uniformity(&self, data: &[u8]) -> AnalysisResult {
        if data.is_empty() {
            return AnalysisResult {
                test_name: "Chi-Squared".into(),
                statistic: 0.0,
                p_value: 1.0,
                is_suspicious: false,
                description: "No data".into(),
            };
        }

        let mut counts = [0u64; 256];
        for &byte in data {
            counts[byte as usize] += 1;
        }

        let expected = data.len() as f64 / 256.0;
        let chi_sq: f64 = counts
            .iter()
            .map(|&c| {
                let diff = c as f64 - expected;
                diff * diff / expected
            })
            .sum();

        // Degrees of freedom = 255
        // For 255 df, critical value at 0.05 is ~293
        let is_suspicious = chi_sq > 293.0;

        AnalysisResult {
            test_name: "Chi-Squared Uniformity".into(),
            statistic: chi_sq,
            p_value: if is_suspicious { 0.01 } else { 0.5 },
            is_suspicious,
            description: format!(
                "Chi-squared: {:.1} (critical: 293.0 at α=0.05). {}",
                chi_sq,
                if is_suspicious {
                    "Non-uniform distribution detected."
                } else {
                    "Distribution consistent with random/encrypted data."
                }
            ),
        }
    }

    /// Test for repeated patterns in packet sizes.
    pub fn pattern_detection(&self, packet_sizes: &[usize]) -> AnalysisResult {
        if packet_sizes.len() < 4 {
            return AnalysisResult {
                test_name: "Pattern Detection".into(),
                statistic: 0.0,
                p_value: 1.0,
                is_suspicious: false,
                description: "Insufficient data".into(),
            };
        }

        // Count unique sizes
        let mut unique: std::collections::HashSet<usize> = std::collections::HashSet::new();
        for &s in packet_sizes {
            unique.insert(s);
        }

        let unique_ratio = unique.len() as f64 / packet_sizes.len() as f64;

        // Check for constant size (padding)
        let all_same = unique.len() == 1;

        // Check for repeating pattern
        let has_pattern = detect_repeating_pattern(packet_sizes);

        let is_suspicious = has_pattern && !all_same;

        AnalysisResult {
            test_name: "Pattern Detection".into(),
            statistic: unique_ratio,
            p_value: if is_suspicious { 0.01 } else { 0.5 },
            is_suspicious,
            description: format!(
                "Unique ratio: {:.2}, all_same: {}, repeating: {}. {}",
                unique_ratio,
                all_same,
                has_pattern,
                if all_same {
                    "Constant-size padding detected (good for privacy)."
                } else if is_suspicious {
                    "Repeating pattern may enable fingerprinting."
                } else {
                    "No obvious pattern detected."
                }
            ),
        }
    }

    /// Timing regularity analysis: detect constant-rate traffic.
    pub fn timing_regularity(&self, inter_packet_delays_us: &[u64]) -> AnalysisResult {
        if inter_packet_delays_us.is_empty() {
            return AnalysisResult {
                test_name: "Timing Regularity".into(),
                statistic: 0.0,
                p_value: 1.0,
                is_suspicious: false,
                description: "No data".into(),
            };
        }

        let mean = inter_packet_delays_us.iter().sum::<u64>() as f64
            / inter_packet_delays_us.len() as f64;

        let variance: f64 = inter_packet_delays_us
            .iter()
            .map(|&d| {
                let diff = d as f64 - mean;
                diff * diff
            })
            .sum::<f64>()
            / inter_packet_delays_us.len() as f64;

        let cv = if mean > 0.0 {
            variance.sqrt() / mean
        } else {
            0.0
        };

        // Very low CV = constant rate (which is defensive but detectable)
        // Very high CV = bursty (natural but fingerprintable)
        let is_suspicious = cv < 0.05 || cv > 2.0;

        AnalysisResult {
            test_name: "Timing Regularity".into(),
            statistic: cv,
            p_value: if is_suspicious { 0.01 } else { 0.5 },
            is_suspicious,
            description: format!(
                "CV: {:.4} (mean delay: {:.0}µs). {}",
                cv,
                mean,
                if cv < 0.05 {
                    "Very regular timing (constant-rate shaping detected)."
                } else if cv > 2.0 {
                    "Highly bursty traffic (may enable fingerprinting)."
                } else {
                    "Normal timing variation."
                }
            ),
        }
    }

    /// Run all analysis tests on a traffic sample.
    pub fn full_analysis(
        &self,
        payload: &[u8],
        packet_sizes: &[usize],
        delays_us: &[u64],
    ) -> Vec<AnalysisResult> {
        vec![
            self.entropy_analysis(payload),
            self.chi_squared_uniformity(payload),
            self.pattern_detection(packet_sizes),
            self.timing_regularity(delays_us),
        ]
    }

    /// Overall suspicion score (0.0–1.0) from all analyses.
    pub fn suspicion_score(
        &self,
        payload: &[u8],
        packet_sizes: &[usize],
        delays_us: &[u64],
    ) -> f64 {
        let results = self.full_analysis(payload, packet_sizes, delays_us);
        let suspicious_count = results.iter().filter(|r| r.is_suspicious).count();
        suspicious_count as f64 / results.len() as f64
    }
}

impl Default for StatisticalAnalyzer {
    fn default() -> Self {
        Self::new()
    }
}

/// Detect if there's a repeating pattern in the data.
fn detect_repeating_pattern(data: &[usize]) -> bool {
    if data.len() < 4 {
        return false;
    }

    // Try pattern lengths from 1 to half the data
    for pattern_len in 1..=(data.len() / 2) {
        let pattern = &data[..pattern_len];
        let mut matches = true;
        for i in pattern_len..data.len() {
            if data[i] != pattern[i % pattern_len] {
                matches = false;
                break;
            }
        }
        if matches && pattern_len < data.len() {
            return true;
        }
    }

    false
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_entropy_random_data() {
        let analyzer = StatisticalAnalyzer::new();
        // Generate pseudorandom data using hashing
        let mut data = Vec::new();
        for i in 0u16..1000 {
            let hash = crypto::hash_data(&i.to_le_bytes());
            data.extend_from_slice(hash.as_bytes());
        }
        let entropy = analyzer.byte_entropy(&data);
        assert!(entropy > 7.0, "Random data should have high entropy: {}", entropy);
    }

    #[test]
    fn test_entropy_structured_data() {
        let analyzer = StatisticalAnalyzer::new();
        let data = b"AAAAAABBBBBBCCCCCC".repeat(100);
        let result = analyzer.entropy_analysis(&data);
        assert!(result.is_suspicious, "Structured data should be flagged");
        assert!(result.statistic < 4.0);
    }

    #[test]
    fn test_chi_squared_uniform() {
        let analyzer = StatisticalAnalyzer::new();
        // Generate data with hash for near-uniform distribution
        let mut data = Vec::new();
        for i in 0u32..500 {
            let hash = crypto::hash_data(&i.to_le_bytes());
            data.extend_from_slice(hash.as_bytes());
        }
        let result = analyzer.chi_squared_uniformity(&data);
        assert!(!result.is_suspicious, "Uniform-like data should pass: chi²={}", result.statistic);
    }

    #[test]
    fn test_pattern_detection() {
        let analyzer = StatisticalAnalyzer::new();

        // Repeating pattern: should detect
        let sizes = vec![100, 200, 100, 200, 100, 200, 100, 200];
        let result = analyzer.pattern_detection(&sizes);
        assert!(result.is_suspicious, "Should detect repeating pattern");

        // Constant size: not suspicious (padding)
        let constant = vec![256, 256, 256, 256, 256];
        let result2 = analyzer.pattern_detection(&constant);
        assert!(!result2.is_suspicious, "Constant size is not suspicious (padding)");
    }

    #[test]
    fn test_timing_regularity() {
        let analyzer = StatisticalAnalyzer::new();

        // Very regular timing
        let regular = vec![1000, 1000, 1000, 1000, 1000];
        let result = analyzer.timing_regularity(&regular);
        assert!(result.is_suspicious, "Perfectly regular timing should be detected");

        // Normal variation
        let varied = vec![800, 1200, 950, 1100, 1050, 900];
        let result2 = analyzer.timing_regularity(&varied);
        assert!(!result2.is_suspicious, "Normal variation should not flag");
    }
}