Configuration

Customize Batin's detection behavior for your use case.

DetectionConfig

The DetectionConfig struct controls all detection parameters.

use batin::DetectionConfig;

let config = DetectionConfig {
    max_read_bytes: 3072,               // Bytes to read for detection
    enable_entropy: true,                // Enable entropy analysis
    enable_polyglot: true,               // Enable polyglot detection
    enable_embedded: true,               // Scan for embedded threats
    entropy_threshold: 7.2,              // Packed detection threshold
    packed_chi_square_threshold: 100.0,  // Chi-square threshold for packing
    encrypted_entropy_threshold: 7.8,    // Encryption detection threshold
    encrypted_chi_square_threshold: 50.0,// Chi-square for encryption
    timeout_ms: 5000,                    // File read timeout
};

Builder style

Start from the defaults and override only what you need with the chainable with_* setters:

use batin::DetectionConfig;

let config = DetectionConfig::default()
    .with_max_read_bytes(8192)
    .with_entropy(true)
    .with_timeout_ms(10_000);

Validation

Call config.validate() to reject nonsensical values before use, for example a zero max_read_bytes, an entropy threshold outside 0.0..=8.0, or an encrypted_entropy_threshold lower than entropy_threshold. from_bytes and from_file_path validate the config automatically and return DetectionError::InvalidConfig on a bad value.

Archive limits

Archive recursion has its own limits in ArchiveConfig (maximum extracted file size, total size, entry count, and the suspicious compression ratio). Pass it to archive::scan_archive_with_config to tune fast triage versus deep forensics.

Configuration Options

max_read_bytes

Maximum bytes to read from each file for signature detection.

Value	Use Case
1024	Quick scans, reduce I/O
3072	Default - balanced
8192	Better accuracy for complex formats
65536	Deep analysis, slower

let config = DetectionConfig {
    max_read_bytes: 8192, // Read more for better accuracy
    ..Default::default()
};

enable_entropy

Toggle Shannon entropy analysis.

• true (default): Calculate entropy, detect packed/encrypted
• false: Skip entropy analysis (faster)

// Fast scan without entropy
let config = DetectionConfig {
    enable_entropy: false,
    ..Default::default()
};

enable_polyglot

Toggle multi-format detection.

• true (default): Scan multiple offsets for hidden formats
• false: Only detect primary signature

// Skip polyglot detection
let config = DetectionConfig {
    enable_polyglot: false,
    ..Default::default()
};

enable_embedded

Toggle embedded threat scanning.

• true (default): Scan for macros, JavaScript, executables
• false: Skip embedded content analysis

// Skip embedded scanning
let config = DetectionConfig {
    enable_embedded: false,
    ..Default::default()
};

Entropy Thresholds

Fine-tune packed/encrypted detection:

Parameter	Default	Description
entropy_threshold	7.2	Min entropy for "packed" flag
packed_chi_square_threshold	100.0	Max chi-square for "packed" flag
encrypted_entropy_threshold	7.8	Min entropy for "encrypted" flag
encrypted_chi_square_threshold	50.0	Max chi-square for "encrypted" flag

Understanding the Thresholds

Packed files have:

• High entropy (compressed data)
• Moderate chi-square (not perfectly random)

Encrypted files have:

• Very high entropy (near 8.0)
• Low chi-square (nearly uniform distribution)

// Stricter detection (fewer false positives)
let config = DetectionConfig {
    entropy_threshold: 7.5,          // Higher threshold
    encrypted_entropy_threshold: 7.9, // Near maximum
    ..Default::default()
};

timeout_ms

Maximum time to spend reading a file.

• 5000 (default): 5 seconds
• Prevents DoS from large/slow files

// Faster timeout for web applications
let config = DetectionConfig {
    timeout_ms: 2000, // 2 seconds
    ..Default::default()
};

---

Preset Configurations

Fast Scan (Minimal)

let fast_config = DetectionConfig {
    max_read_bytes: 1024,
    enable_entropy: false,
    enable_polyglot: false,
    enable_embedded: false,
    timeout_ms: 1000,
    ..Default::default()
};

Security-Focused

let security_config = DetectionConfig {
    max_read_bytes: 8192,
    enable_entropy: true,
    enable_polyglot: true,
    enable_embedded: true,
    entropy_threshold: 7.0,  // Lower threshold (more sensitive)
    timeout_ms: 10000,
    ..Default::default()
};

Forensic Analysis

let forensic_config = DetectionConfig {
    max_read_bytes: 65536,  // Read more data
    enable_entropy: true,
    enable_polyglot: true,
    enable_embedded: true,
    timeout_ms: 30000,      // Allow more time
    ..Default::default()
};

---

Environment Variables

The CLI reads these environment variables:

Variable	Description
VT_API_KEY	VirusTotal API key for batin reputation (online feature)
RUST_LOG	Tracing log filter, for example RUST_LOG=debug
NO_COLOR	Disable colored output when set

Detection parameters such as the read size and timeout are set through DetectionConfig in the library, not environment variables.

# Verbose logging for a scan
RUST_LOG=debug batin scan /directory -r --verbose

---

Performance Tuning

High-Throughput Scanning

// Minimize I/O and processing
let high_throughput = DetectionConfig {
    max_read_bytes: 512,    // Minimal read
    enable_entropy: false,   // Skip entropy
    enable_polyglot: false,  // Skip polyglot
    enable_embedded: false,  // Skip embedded
    timeout_ms: 500,         // Quick timeout
    ..Default::default()
};

Memory-Constrained Environment

// Reduce memory usage
let low_memory = DetectionConfig {
    max_read_bytes: 1024,   // Small buffer
    enable_entropy: true,    // Entropy is O(1) memory
    enable_polyglot: false,  // Skip to reduce allocations
    enable_embedded: false,  // Skip to reduce allocations
    ..Default::default()
};

---

Configuration for Specific File Types

Document Analysis

let doc_config = DetectionConfig {
    enable_embedded: true,   // Detect macros
    enable_entropy: false,   // Usually not packed
    ..Default::default()
};

Executable Analysis

let exe_config = DetectionConfig {
    enable_entropy: true,    // Detect packing
    enable_polyglot: true,   // Detect PDF+EXE attacks
    max_read_bytes: 8192,    // Read more for headers
    ..Default::default()
};

Archive Analysis

let archive_config = DetectionConfig {
    enable_embedded: true,   // Find executables in archives
    max_read_bytes: 65536,   // Read central directory
    ..Default::default()
};