threatflux-binary-analysis 0.2.0

Comprehensive binary analysis library with multi-format support, disassembly, and security analysis
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
# ThreatFlux Binary Analysis

A comprehensive Rust library for binary analysis with multi-format support, disassembly capabilities, and advanced security analysis features. Designed for security researchers, malware analysts, and reverse engineers.

[![Crates.io](https://img.shields.io/crates/v/threatflux-binary-analysis.svg)](https://crates.io/crates/threatflux-binary-analysis)
[![Documentation](https://docs.rs/threatflux-binary-analysis/badge.svg)](https://docs.rs/threatflux-binary-analysis)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org)
[![CI](https://github.com/ThreatFlux/threatflux-binary-analysis/actions/workflows/ci.yml/badge.svg)](https://github.com/ThreatFlux/threatflux-binary-analysis/actions/workflows/ci.yml)
[![Release](https://github.com/ThreatFlux/threatflux-binary-analysis/actions/workflows/release.yml/badge.svg)](https://github.com/ThreatFlux/threatflux-binary-analysis/actions/workflows/release.yml)
[![Security](https://github.com/ThreatFlux/threatflux-binary-analysis/actions/workflows/security.yml/badge.svg)](https://github.com/ThreatFlux/threatflux-binary-analysis/actions/workflows/security.yml)
[![Documentation](https://github.com/ThreatFlux/threatflux-binary-analysis/actions/workflows/docs.yml/badge.svg)](https://github.com/ThreatFlux/threatflux-binary-analysis/actions/workflows/docs.yml)
[![codecov](https://codecov.io/gh/ThreatFlux/threatflux-binary-analysis/graph/badge.svg?token=DlAEOagOhp)](https://codecov.io/gh/ThreatFlux/threatflux-binary-analysis)
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/8f07242350d84597af1af64edbc505fa)](https://app.codacy.com/gh/ThreatFlux/threatflux-binary-analysis/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)

## ๐Ÿš€ Features

### Binary Format Support
- **PE (Portable Executable)**: Windows executables, DLLs, drivers
- **ELF (Executable and Linkable Format)**: Linux/Unix executables, shared libraries
- **Mach-O**: macOS executables, dynamic libraries, kernel extensions
- **WASM**: WebAssembly modules (enable with `wasm` feature)
- **Java**: JAR files and class files
- **Raw Binary**: Generic binary file analysis

### Analysis Capabilities
- **๐Ÿ” Header Analysis**: Parse and validate file headers
- **๐Ÿ“Š Section Analysis**: Enumerate and analyze sections/segments
- **๐Ÿ”— Symbol Resolution**: Extract and resolve function symbols
- **๐Ÿ“ˆ Control Flow Analysis**: Build control flow graphs with complexity metrics
- **๐ŸŽฏ Disassembly**: Multiple disassembly engines (Capstone, iced-x86)
- **๐Ÿ”’ Security Analysis**: Detect security features and vulnerabilities
- **๐Ÿ“ Entropy Analysis**: Calculate entropy for packed/encrypted sections
- **๐Ÿ—๏ธ Metadata Extraction**: Compiler detection, build information
- **๐Ÿ” String Extraction**: ASCII and Unicode string discovery
- **๐Ÿ“ฑ Mobile Analysis**: Android APK and iOS app analysis
- **๐Ÿ—œ๏ธ Compression Support**: Decompress common compressed sections
- **๐Ÿ—บ๏ธ Visualization**: Export control flow graphs to DOT format
- **๐Ÿ“ JSON Serialization**: Serialize analysis results to JSON

### Performance Features
- **โšก Memory-Mapped Files**: Efficient large file handling
- **๐Ÿ”„ Async Support**: Non-blocking analysis operations
- **๐Ÿงต Parallel Processing**: Multi-threaded analysis
- **๐Ÿ’พ Caching**: Smart caching of analysis results
- **๐Ÿ“ Streaming**: Process large files without loading entirely

## ๐Ÿ“ฆ Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
threatflux-binary-analysis = "0.1.0"
```

### Feature Flags

```toml
[dependencies]
threatflux-binary-analysis = { 
    version = "0.1.0", 
    features = [
        "pe",              # Windows PE format support
        "elf",             # Linux ELF format support  
        "macho",           # macOS Mach-O format support
        "wasm",            # WebAssembly module support
        "disasm-capstone", # Capstone disassembly engine
        "disasm-iced",     # iced-x86 disassembly engine
        "control-flow",    # Control flow analysis
        "entropy-analysis",# Statistical analysis
        "symbol-resolution",# Debug symbol support
        "compression",     # Compressed section support
        "visualization",   # Graph visualization
        "serde-support",   # JSON serialization support
    ]
}
```

#### Available Features

| Feature | Description | Default |
|---------|-------------|---------|
| `elf` | ELF format support | โœ… |
| `pe` | PE format support | โœ… |
| `macho` | Mach-O format support | โœ… |
| `java` | JAR/class file support | โœ… |
| `wasm` | WebAssembly support | โœ… |
| `disasm-capstone` | Capstone disassembly | โœ… |
| `disasm-iced` | iced-x86 disassembly | โœ… |
| `control-flow` | Control flow analysis | โœ… |
| `entropy-analysis` | Entropy calculation | โœ… |
| `symbol-resolution` | Debug symbol support | โœ… |
| `compression` | Compressed section support | โœ… |
| `visualization` | Graph visualization | โœ… |
| `serde-support` | JSON serialization | โœ… |

*The `disasm-iced` feature enables the [iced-x86](https://github.com/icedland/iced) disassembly engine. Activate it with `--features "disasm-iced"` to use iced-x86 instead of Capstone.*

*Enable WebAssembly module parsing with `--features "wasm"`.*

*Generate control flow graphs with `--features "control-flow"`.*

## ๐Ÿš€ Quick Start

### Basic Analysis

```rust
use threatflux_binary_analysis::{BinaryAnalyzer, AnalysisConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create analyzer with default configuration
    let analyzer = BinaryAnalyzer::new(AnalysisConfig::default());
    
    // Analyze a binary file
    let analysis = analyzer.analyze_file("./example.exe").await?;
    
    println!("Format: {:?}", analysis.format);
    println!("Architecture: {}", analysis.architecture);
    println!("Entry Point: 0x{:x}", analysis.entry_point);
    println!("Sections: {}", analysis.sections.len());
    
    Ok(())
}
```

### Advanced Configuration

```rust
use threatflux_binary_analysis::{
    BinaryAnalyzer, AnalysisConfig, DisassemblyConfig, SecurityConfig
};

let config = AnalysisConfig {
    // Enable comprehensive analysis
    parse_headers: true,
    parse_sections: true,
    parse_symbols: true,
    parse_imports: true,
    parse_exports: true,
    
    // Security analysis
    detect_packers: true,
    analyze_entropy: true,
    check_signatures: true,
    
    // Performance settings
    use_memory_mapping: true,
    max_file_size: 100 * 1024 * 1024, // 100MB
    timeout: Duration::from_secs(300),
    
    // Disassembly configuration
    disassembly: Some(DisassemblyConfig {
        engine: DisassemblyEngine::Capstone,
        max_instructions: 10000,
        follow_calls: true,
        analyze_control_flow: true,
    }),
    
    // Security configuration
    security: SecurityConfig {
        check_suspicious_sections: true,
        analyze_api_calls: true,
        detect_obfuscation: true,
        check_certificates: true,
    },
};

let analyzer = BinaryAnalyzer::new(config);
```

### Format-Specific Analysis

```rust
use threatflux_binary_analysis::formats::{PeAnalyzer, ElfAnalyzer, MachOAnalyzer};

// PE-specific analysis
let pe_analyzer = PeAnalyzer::new();
let pe_info = pe_analyzer.analyze("./windows.exe").await?;
println!("PE Timestamp: {:?}", pe_info.timestamp);
println!("Subsystem: {:?}", pe_info.subsystem);

// ELF-specific analysis  
let elf_analyzer = ElfAnalyzer::new();
let elf_info = elf_analyzer.analyze("./linux_binary").await?;
println!("ELF Type: {:?}", elf_info.elf_type);
println!("Machine: {:?}", elf_info.machine);

// Mach-O specific analysis
let macho_analyzer = MachOAnalyzer::new();
let macho_info = macho_analyzer.analyze("./macos_binary").await?;
println!("CPU Type: {:?}", macho_info.cpu_type);
println!("File Type: {:?}", macho_info.file_type);
```

### Disassembly

```rust
use threatflux_binary_analysis::disasm::{DisassemblyEngine, Disassembler};

// Create disassembler
let disassembler = Disassembler::new(DisassemblyEngine::Capstone)?;

// Disassemble a function
let instructions = disassembler.disassemble_function(
    &binary_data,
    entry_point,
    architecture,
    100 // max instructions
).await?;

for instruction in instructions {
    println!("0x{:x}: {} {}", 
        instruction.address, 
        instruction.mnemonic, 
        instruction.operands
    );
}
```

### Control Flow Analysis

```rust
use threatflux_binary_analysis::analysis::control_flow;
use threatflux_binary_analysis::BinaryFile;

// Parse binary and build control flow graphs
let binary = BinaryFile::parse(&data)?;
let cfgs = control_flow::analyze_binary(&binary)?;

for cfg in cfgs {
    println!(
        "Function {} has {} basic blocks",
        cfg.function.name,
        cfg.basic_blocks.len()
    );
    println!("Cyclomatic complexity: {}", cfg.complexity.cyclomatic_complexity);
}
```

### Security Analysis

```rust
use threatflux_binary_analysis::analysis::SecurityAnalyzer;

let security_analyzer = SecurityAnalyzer::new();
let security_report = security_analyzer.analyze(&analysis).await?;

println!("Security Features:");
for feature in &security_report.security_features {
    println!("  - {}: {}", feature.name, feature.enabled);
}

println!("Vulnerabilities:");
for vuln in &security_report.vulnerabilities {
    println!("  - {}: {} ({})", vuln.name, vuln.description, vuln.severity);
}

println!("Suspicious Indicators:");
for indicator in &security_report.suspicious_indicators {
    println!("  - {}: {}", indicator.indicator_type, indicator.description);
}
```

### Entropy Analysis

```rust
use threatflux_binary_analysis::analysis::EntropyAnalyzer;

let entropy_analyzer = EntropyAnalyzer::new();

// Analyze entropy for each section
for section in &analysis.sections {
    let entropy = entropy_analyzer.calculate_entropy(&section.data)?;
    println!("Section '{}': entropy = {:.2}", section.name, entropy);
    
    if entropy > 7.0 {
        println!("  ^ High entropy - possibly packed/encrypted");
    }
}

// Find entropy anomalies
let anomalies = entropy_analyzer.find_anomalies(&analysis)?;
for anomaly in anomalies {
    println!("Entropy anomaly at 0x{:x}: {}", anomaly.offset, anomaly.description);
}
```

## ๐Ÿ“Š Data Structures

### BinaryAnalysis

```rust
pub struct BinaryAnalysis {
    pub format: BinaryFormat,
    pub architecture: Architecture,
    pub endianness: Endianness,
    pub entry_point: u64,
    pub base_address: u64,
    pub file_size: u64,
    pub headers: Headers,
    pub sections: Vec<Section>,
    pub symbols: Vec<Symbol>,
    pub imports: Vec<Import>,
    pub exports: Vec<Export>,
    pub strings: Vec<ExtractedString>,
    pub metadata: BinaryMetadata,
    pub security_features: SecurityFeatures,
}
```

### Section Information

```rust
pub struct Section {
    pub name: String,
    pub virtual_address: u64,
    pub virtual_size: u64,
    pub file_offset: u64,
    pub file_size: u64,
    pub permissions: SectionPermissions,
    pub section_type: SectionType,
    pub entropy: Option<f64>,
    pub data: Vec<u8>,
    pub relocations: Vec<Relocation>,
}
```

### Symbol Information

```rust
pub struct Symbol {
    pub name: String,
    pub address: u64,
    pub size: Option<u64>,
    pub symbol_type: SymbolType,
    pub binding: SymbolBinding,
    pub visibility: SymbolVisibility,
    pub section_index: Option<usize>,
    pub demangled_name: Option<String>,
}
```

### Disassembly Result

```rust
pub struct Instruction {
    pub address: u64,
    pub bytes: Vec<u8>,
    pub mnemonic: String,
    pub operands: String,
    pub size: usize,
    pub groups: Vec<InstructionGroup>,
    pub branch_target: Option<u64>,
    pub is_call: bool,
    pub is_jump: bool,
    pub is_return: bool,
}
```

## ๐ŸŽฏ Examples

### Example 1: PE Malware Analysis

```rust
use threatflux_binary_analysis::{BinaryAnalyzer, AnalysisConfig, formats::pe::PeFeatures};

async fn analyze_malware_sample(path: &str) -> Result<(), Box<dyn std::error::Error>> {
    let config = AnalysisConfig {
        parse_headers: true,
        parse_sections: true,
        parse_imports: true,
        detect_packers: true,
        analyze_entropy: true,
        ..Default::default()
    };
    
    let analyzer = BinaryAnalyzer::new(config);
    let analysis = analyzer.analyze_file(path).await?;
    
    // Check for suspicious imports
    let suspicious_apis = vec![
        "VirtualAlloc", "VirtualProtect", "CreateRemoteThread",
        "WriteProcessMemory", "SetWindowsHookEx", "GetProcAddress"
    ];
    
    for import in &analysis.imports {
        if suspicious_apis.contains(&import.name.as_str()) {
            println!("โš ๏ธ  Suspicious API: {}", import.name);
        }
    }
    
    // Check for packed sections
    for section in &analysis.sections {
        if let Some(entropy) = section.entropy {
            if entropy > 7.5 {
                println!("๐Ÿ“ฆ Possibly packed section: {} (entropy: {:.2})", 
                    section.name, entropy);
            }
        }
    }
    
    // Check for unusual section names
    let normal_sections = vec![".text", ".data", ".rdata", ".rsrc", ".reloc"];
    for section in &analysis.sections {
        if !normal_sections.contains(&section.name.as_str()) {
            println!("๐Ÿ” Unusual section: {}", section.name);
        }
    }
    
    Ok(())
}
```

### Example 2: Binary Diffing

```rust
use threatflux_binary_analysis::{BinaryAnalyzer, AnalysisConfig};
use std::collections::HashMap;

async fn compare_binaries(path1: &str, path2: &str) -> Result<(), Box<dyn std::error::Error>> {
    let analyzer = BinaryAnalyzer::new(AnalysisConfig::default());
    
    let analysis1 = analyzer.analyze_file(path1).await?;
    let analysis2 = analyzer.analyze_file(path2).await?;
    
    println!("=== Binary Comparison ===");
    
    // Compare basic properties
    println!("Format: {} vs {}", analysis1.format, analysis2.format);
    println!("Architecture: {} vs {}", analysis1.architecture, analysis2.architecture);
    println!("Entry Point: 0x{:x} vs 0x{:x}", analysis1.entry_point, analysis2.entry_point);
    
    // Compare sections
    let sections1: HashMap<_, _> = analysis1.sections.iter()
        .map(|s| (s.name.clone(), s)).collect();
    let sections2: HashMap<_, _> = analysis2.sections.iter()
        .map(|s| (s.name.clone(), s)).collect();
    
    for (name, section1) in &sections1 {
        if let Some(section2) = sections2.get(name) {
            if section1.file_size != section2.file_size {
                println!("๐Ÿ“ Section '{}' size changed: {} -> {} bytes", 
                    name, section1.file_size, section2.file_size);
            }
        } else {
            println!("โž– Section '{}' removed", name);
        }
    }
    
    for name in sections2.keys() {
        if !sections1.contains_key(name) {
            println!("โž• Section '{}' added", name);
        }
    }
    
    // Compare imports
    let imports1: Vec<_> = analysis1.imports.iter().map(|i| &i.name).collect();
    let imports2: Vec<_> = analysis2.imports.iter().map(|i| &i.name).collect();
    
    for import in &imports2 {
        if !imports1.contains(import) {
            println!("๐Ÿ“ฅ New import: {}", import);
        }
    }
    
    for import in &imports1 {
        if !imports2.contains(import) {
            println!("๐Ÿ“ค Removed import: {}", import);
        }
    }
    
    Ok(())
}
```

### Example 3: Automated Unpacking Detection

```rust
use threatflux_binary_analysis::{
    BinaryAnalyzer, AnalysisConfig,
    analysis::{EntropyAnalyzer, PackerDetector}
};

async fn detect_packing(path: &str) -> Result<(), Box<dyn std::error::Error>> {
    let config = AnalysisConfig {
        analyze_entropy: true,
        detect_packers: true,
        parse_sections: true,
        ..Default::default()
    };
    
    let analyzer = BinaryAnalyzer::new(config);
    let analysis = analyzer.analyze_file(path).await?;
    
    // Use built-in packer detection
    let packer_detector = PackerDetector::new();
    let detection_result = packer_detector.detect(&analysis)?;
    
    if detection_result.is_packed {
        println!("๐Ÿ—œ๏ธ  File is likely packed!");
        if let Some(packer) = detection_result.detected_packer {
            println!("   Detected packer: {}", packer);
        }
        println!("   Confidence: {:.1}%", detection_result.confidence * 100.0);
    }
    
    // Manual entropy analysis
    let entropy_analyzer = EntropyAnalyzer::new();
    let overall_entropy = entropy_analyzer.calculate_file_entropy(&analysis)?;
    
    println!("๐Ÿ“Š Overall file entropy: {:.2}", overall_entropy);
    
    if overall_entropy > 7.0 {
        println!("   High entropy suggests compression or encryption");
    }
    
    // Check for entropy patterns
    for section in &analysis.sections {
        if let Some(entropy) = section.entropy {
            println!("   Section '{}': {:.2}", section.name, entropy);
            
            if entropy > 7.5 && section.permissions.executable {
                println!("     โš ๏ธ  Executable section with very high entropy!");
            }
        }
    }
    
    Ok(())
}
```

### Example 4: Function Analysis

```rust
use threatflux_binary_analysis::{
    BinaryAnalyzer, AnalysisConfig,
    disasm::{Disassembler, DisassemblyEngine},
    analysis::{ControlFlowAnalyzer, FunctionAnalyzer}
};

async fn analyze_functions(path: &str) -> Result<(), Box<dyn std::error::Error>> {
    let config = AnalysisConfig {
        parse_symbols: true,
        disassembly: Some(DisassemblyConfig {
            engine: DisassemblyEngine::Capstone,
            max_instructions: 1000,
            follow_calls: true,
            analyze_control_flow: true,
        }),
        ..Default::default()
    };
    
    let analyzer = BinaryAnalyzer::new(config);
    let analysis = analyzer.analyze_file(path).await?;
    
    let function_analyzer = FunctionAnalyzer::new();
    let functions = function_analyzer.identify_functions(&analysis).await?;
    
    println!("๐Ÿ” Found {} functions", functions.len());
    
    for function in &functions {
        println!("\n๐Ÿ“ Function: {} (0x{:x})", function.name, function.address);
        println!("   Size: {} bytes", function.size);
        println!("   Instructions: {}", function.instruction_count);
        println!("   Basic blocks: {}", function.basic_blocks.len());
        
        // Analyze function complexity
        if function.cyclomatic_complexity > 10 {
            println!("   โš ๏ธ  High complexity: {}", function.cyclomatic_complexity);
        }
        
        // Check for suspicious patterns
        if function.has_self_modifying_code {
            println!("   ๐Ÿšจ Self-modifying code detected!");
        }
        
        if function.calls_suspicious_apis {
            println!("   โš ๏ธ  Calls suspicious APIs");
        }
        
        // Print some disassembly
        println!("   First few instructions:");
        for (i, instruction) in function.instructions.iter().take(5).enumerate() {
            println!("     0x{:x}: {} {}", 
                instruction.address, 
                instruction.mnemonic, 
                instruction.operands
            );
        }
        
        if function.instructions.len() > 5 {
            println!("     ... ({} more instructions)", function.instructions.len() - 5);
        }
    }
    
    Ok(())
}
```

## ๐Ÿ”ง Configuration Options

### AnalysisConfig

```rust
pub struct AnalysisConfig {
    // What to parse
    pub parse_headers: bool,           // Parse file headers
    pub parse_sections: bool,          // Parse sections/segments  
    pub parse_symbols: bool,           // Parse symbol tables
    pub parse_imports: bool,           // Parse import tables
    pub parse_exports: bool,           // Parse export tables
    pub parse_relocations: bool,       // Parse relocation tables
    pub parse_debug_info: bool,        // Parse debug information
    
    // Analysis features
    pub detect_packers: bool,          // Run packer detection
    pub analyze_entropy: bool,         // Calculate entropy
    pub extract_strings: bool,         // Extract strings
    pub check_signatures: bool,        // Verify digital signatures
    pub analyze_control_flow: bool,    // Build control flow graphs
    
    // Performance settings
    pub use_memory_mapping: bool,      // Use memory-mapped files
    pub max_file_size: u64,           // Maximum file size (bytes)
    pub timeout: Duration,            // Analysis timeout
    pub parallel_processing: bool,     // Enable parallel processing
    
    // Disassembly settings
    pub disassembly: Option<DisassemblyConfig>,
    
    // Security settings
    pub security: SecurityConfig,
}
```

### DisassemblyConfig

```rust
pub struct DisassemblyConfig {
    pub engine: DisassemblyEngine,     // Capstone or iced-x86
    pub max_instructions: usize,       // Maximum instructions to disassemble
    pub follow_calls: bool,           // Follow function calls
    pub follow_jumps: bool,           // Follow conditional jumps
    pub analyze_control_flow: bool,    // Build control flow graphs
    pub detect_functions: bool,        // Identify function boundaries
    pub resolve_symbols: bool,         // Resolve symbol names
}
```

### SecurityConfig

```rust
pub struct SecurityConfig {
    pub check_suspicious_sections: bool,   // Check for unusual sections
    pub analyze_api_calls: bool,          // Analyze imported APIs
    pub detect_obfuscation: bool,         // Detect code obfuscation
    pub check_certificates: bool,          // Verify code signing certificates
    pub scan_for_shellcode: bool,         // Scan for shellcode patterns
    pub detect_anti_analysis: bool,       // Detect anti-analysis techniques
    pub check_known_malware: bool,        // Check against known malware signatures
}
```

## ๐Ÿ—๏ธ Architecture

The library is organized into several modules:

- **`formats/`**: Format-specific parsers (PE, ELF, Mach-O, etc.)
- **`disasm/`**: Disassembly engines (Capstone, iced-x86)
- **`analysis/`**: Analysis modules (control flow, security, entropy)
- **`utils/`**: Utility functions (memory mapping, pattern matching)
- **`types.rs`**: Common data structures
- **`error.rs`**: Error handling

### Format Parsers

Each binary format has its own parser module:

```rust
// PE format parser
use threatflux_binary_analysis::formats::pe::PeParser;
let pe_parser = PeParser::new();
let pe_analysis = pe_parser.parse(&file_data)?;

// ELF format parser
use threatflux_binary_analysis::formats::elf::ElfParser;
let elf_parser = ElfParser::new();
let elf_analysis = elf_parser.parse(&file_data)?;
```

### Disassembly Engines

Multiple disassembly engines are supported:

```rust
// Capstone engine (supports many architectures)
use threatflux_binary_analysis::disasm::CapstoneEngine;
let capstone = CapstoneEngine::new(Architecture::X86_64)?;
let instructions = capstone.disassemble(&code, address)?;

// iced-x86 engine (x86/x64 only, but very detailed)
use threatflux_binary_analysis::disasm::IcedEngine;
let iced = IcedEngine::new(Architecture::X86_64)?;
let instructions = iced.disassemble(&code, address)?;
```

## ๐Ÿ“ˆ Performance

The library is designed for high performance:

- **Memory-mapped files**: Efficient handling of large files
- **Lazy parsing**: Only parse what's needed
- **Parallel processing**: Multi-threaded analysis where possible
- **Streaming**: Process files without loading entirely into memory
- **Caching**: Cache analysis results to avoid redundant work

### Benchmarks

Typical performance on modern hardware:

| Operation | Throughput | Notes |
|-----------|------------|-------|
| PE header parsing | ~10,000 files/sec | Basic header info only |
| ELF section parsing | ~5,000 files/sec | Including section contents |
| Disassembly (Capstone) | ~500 MB/sec | x86-64 code |
| Entropy calculation | ~1 GB/sec | Using SIMD optimizations |
| Control flow analysis | ~100 functions/sec | Complex CFG construction |

Run benchmarks:

```bash
cargo bench
```

## ๐Ÿ”’ Security

The library follows secure coding practices:

- **Memory safety**: Rust's ownership model prevents buffer overflows
- **Input validation**: All inputs are validated and bounds-checked
- **Resource limits**: Configurable limits prevent DoS attacks
- **Sandboxing**: Analysis runs with minimal privileges
- **Timeout protection**: Prevents infinite loops in malicious files

### Handling Malicious Files

The library is designed to safely analyze potentially malicious files:

```rust
let config = AnalysisConfig {
    max_file_size: 100 * 1024 * 1024,  // 100MB limit
    timeout: Duration::from_secs(300),  // 5 minute timeout
    use_memory_mapping: true,           // Avoid loading entire file
    ..Default::default()
};
```

## ๐Ÿงช Testing

Run the test suite:

```bash
# Unit tests
cargo test

# Integration tests
cargo test --test integration_tests

# Test with different features
cargo test --features "disasm-capstone,control-flow"
cargo test --features "wasm"  # Enable WebAssembly support

# Test documentation examples
cargo test --doc
```

Test coverage:

```bash
# Install tarpaulin
cargo install cargo-tarpaulin

# Generate coverage report
cargo tarpaulin --out Html
```

## ๐Ÿ“š Examples

More examples are available in the [`examples/`](examples/) directory:

- [`basic_analysis.rs`]examples/basic_analysis.rs - Basic binary analysis
- [`control_flow.rs`]examples/control_flow.rs - Control flow analysis
- [`disassembly.rs`]examples/disassembly.rs - Disassembly examples
- [`security_analysis.rs`]examples/security_analysis.rs - Security analysis

Run an example:

```bash
cargo run --example basic_analysis --features "pe,elf" -- path/to/binary
```

## ๐Ÿค Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/ThreatFlux/threatflux-binary-analysis.git
cd threatflux-binary-analysis

# Install development dependencies
cargo install cargo-watch cargo-tarpaulin cargo-hack cargo-deny

# Install git hooks (runs make all before each commit)
./scripts/install-hooks.sh

# Run all checks (formatting, linting, tests, etc.)
make all

# Run tests in watch mode
cargo watch -x test

# Generate documentation
cargo doc --open --all-features
```

### Pre-commit Hooks

This project uses a pre-commit hook to ensure code quality. The hook automatically runs `make all` before each commit, which includes:
- Code formatting check
- Clippy linting with all feature combinations
- Security audit
- Dependency validation
- Tests with all feature combinations
- Feature combination checking

To install the pre-commit hook:
```bash
./scripts/install-hooks.sh
```

To bypass the hook in special cases:
```bash
git commit --no-verify
```

## ๐Ÿ“„ License

This project is licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE]LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT]LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

## ๐Ÿ”— Related Projects

- [ThreatFlux Hashing]../threatflux-hashing/ - High-performance file hashing
- [ThreatFlux String Analysis]../threatflux-string-analysis/ - Advanced string analysis
- [ThreatFlux Cache]../threatflux-cache/ - Intelligent caching system
- [File Scanner]../ - Complete file analysis framework

## ๐Ÿ“ž Support

- **Documentation**: [docs.rs/threatflux-binary-analysis]https://docs.rs/threatflux-binary-analysis
- **Issues**: [GitHub Issues]https://github.com/ThreatFlux/threatflux-binary-analysis/issues
- **Discussions**: [GitHub Discussions]https://github.com/ThreatFlux/threatflux-binary-analysis/discussions

---

**Security Notice**: This library is designed for security research and analysis. Always analyze suspicious files in a secure, isolated environment.