Crate dotscope

Expand description

§dotscope

A cross-platform framework for analyzing, deobfuscating, emulating, and modifying .NET PE executables. Built in pure Rust, dotscope provides comprehensive tooling for parsing CIL (Common Intermediate Language) bytecode, metadata structures, disassembling, and transforming .NET assemblies without requiring Windows or the .NET runtime.

§Architecture

The library is organized into several key modules that work together to provide complete .NET assembly analysis:

File Layer: Memory-mapped file access and binary parsing
Metadata Layer: ECMA-335 metadata parsing and type system representation
Assembly Layer: CIL instruction processing with complete disassembly and assembly capabilities
Analysis Layer: SSA form, control flow graphs, data flow analysis, and call graphs
Deobfuscation Layer: Pass-based optimization pipeline with obfuscator-specific handling
Emulation Layer: CIL bytecode interpreter with BCL stubs for runtime value computation
Validation Layer: Configurable validation and integrity checking

§Key Components

crate::CilObject - Main entry point for .NET assembly analysis
crate::metadata - Complete ECMA-335 metadata parsing and type system
crate::assembly - Complete CIL instruction processing: disassembly, analysis, and assembly
crate::analysis - Program analysis with SSA, CFG, data flow, and call graphs
crate::deobfuscation - Deobfuscation engine with 20 optimization passes
crate::emulation - CIL bytecode emulation with BCL method stubs
crate::prelude - Convenient re-exports of commonly used types
crate::Error and crate::Result - Comprehensive error handling

§Features

Complete metadata analysis - Parse all ECMA-335 metadata tables and streams
CIL processing - Complete instruction decoding, encoding, and control flow analysis
Cross-platform - Works on Windows, Linux, macOS, and any Rust-supported platform
Memory safe - Built in Rust with comprehensive error handling
Rich type system - Full support for generics, signatures, and complex .NET types
Static analysis - SSA form, control flow graphs, data flow analysis, call graphs
Deobfuscation - 20 passes, ConfuserEx support, string decryption, control flow recovery
CIL emulation - Bytecode interpreter with 119+ BCL stubs and copy-on-write memory
Extensible architecture - Modular design for custom analysis and tooling

§Usage Examples

§Quick Start

Add dotscope to your Cargo.toml:

[dependencies]
dotscope = "0.6.0"

§Using the Prelude

For convenient access to the most commonly used types, import the prelude:

use dotscope::prelude::*;

// Load and analyze a .NET assembly  
let assembly = CilObject::from_path("tests/samples/WindowsBase.dll")?;
println!("Found {} methods", assembly.methods().len());

§Basic Assembly Analysis

use dotscope::metadata::cilobject::CilObject;
use std::path::Path;

// Load and parse a .NET assembly
let assembly = CilObject::from_path(Path::new("tests/samples/WindowsBase.dll"))?;

// Access metadata
if let Some(module) = assembly.module() {
    println!("Module: {}", module.name);
}

// Iterate through types and methods
let methods = assembly.methods();
println!("Found {} methods", methods.len());

§Memory-based Analysis

use dotscope::metadata::cilobject::CilObject;

// Analyze from memory buffer
let binary_data: Vec<u8> = std::fs::read("assembly.dll")?;
let assembly = CilObject::from_mem(binary_data)?;

// Same API as file-based analysis
println!("Assembly loaded from memory");

§Custom Analysis with Validation

use dotscope::{CilObject, ValidationConfig};

fn analyze_assembly(path: &str) -> dotscope::Result<()> {
    // Use minimal validation for best performance
    let assembly = CilObject::from_path_with_validation(
        std::path::Path::new(path),
        ValidationConfig::minimal()
    )?;
     
    // Access imports and exports
    let imports = assembly.imports();
    let exports = assembly.exports();
     
    println!("Imports: {} items", imports.total_count());
    println!("Exports: {} items", exports.total_count());
     
    Ok(())
}

§CIL Instruction Processing

The assembly module provides comprehensive CIL instruction processing with both disassembly (bytecode to instructions) and assembly (instructions to bytecode) capabilities.

§Disassembly

use dotscope::{assembly::decode_instruction, Parser};

let bytecode = &[0x00, 0x2A]; // nop, ret
let mut parser = Parser::new(bytecode);
let instruction = decode_instruction(&mut parser, 0x1000)?;

println!("Mnemonic: {}", instruction.mnemonic);
println!("Flow type: {:?}", instruction.flow_type);

§Assembly

use dotscope::assembly::InstructionAssembler;

let mut asm = InstructionAssembler::new();
asm.ldarg_0()?      // Load first argument
   .ldarg_1()?      // Load second argument
   .add()?          // Add them together
   .ret()?;         // Return result
let (bytecode, max_stack, handlers) = asm.finish()?; // Returns [0x02, 0x03, 0x58, 0x2A]

§Integration

The instruction processing seamlessly integrates with the metadata system. The crate::CilObject provides access to both metadata and method bodies for comprehensive analysis workflows, while the assembly system uses the same instruction metadata to ensure perfect consistency between disassembly and assembly.

§Metadata-Driven Disassembly

use dotscope::CilObject;

let assembly = CilObject::from_path(std::path::Path::new("tests/samples/WindowsBase.dll"))?;

// Access raw metadata tables
if let Some(tables) = assembly.tables() {
    println!("Metadata tables present: {}", tables.table_count());
}

// Access metadata heaps with indexed access and iteration
if let Some(strings) = assembly.strings() {
    let name = strings.get(1)?; // Indexed access
     
    // Iterate through all entries
    for (offset, string) in strings.iter() {
        println!("String at {}: '{}'", offset, string);
    }
}

§Standards Compliance

dotscope implements the ECMA-335 specification (6th edition) for the Common Language Infrastructure. All metadata structures, CIL instructions, and type system features conform to this standard.

§References

ECMA-335 Standard - Official CLI specification
.NET Runtime - Microsoft’s reference implementation

§Error Handling

All operations return Result<T, Error> with comprehensive error information:

use dotscope::{Error, metadata::cilobject::CilObject};

match CilObject::from_path(std::path::Path::new("tests/samples/crafted_2.exe")) {
    Ok(assembly) => println!("Successfully loaded assembly"),
    Err(Error::NotSupported) => println!("File format not supported"),
    Err(Error::Malformed { message, .. }) => println!("Malformed file: {}", message),
    Err(e) => println!("Other error: {}", e),
}

§Thread Safety

All public types are std::marker::Send and std::marker::Sync unless explicitly documented otherwise. The library is designed for safe concurrent access across multiple threads.

§Development and Testing

Re-exports§

pub use metadata::cilassemblyview::CilAssemblyView;
pub use metadata::cilobject::CilObject;
pub use metadata::validation::ValidationConfig;
pub use metadata::validation::ValidationEngine;
pub use metadata::query::MethodQuery;
pub use metadata::query::TypeQuery;
pub use metadata::streams::Blob;
pub use metadata::streams::BlobIterator;
pub use metadata::streams::Guid;
pub use metadata::streams::GuidIterator;
pub use metadata::streams::StreamHeader;
pub use metadata::streams::Strings;
pub use metadata::streams::StringsIterator;
pub use metadata::streams::TablesHeader;
pub use metadata::streams::UserStrings;
pub use metadata::streams::UserStringsIterator;

Modules§

analysis: Program analysis infrastructure for .NET assemblies.
assembly: CIL instruction processing: disassembly, analysis, and assembly based on ECMA-335.
compiler: Compiler infrastructure for SSA-based code transformations.
deobfuscation: Deobfuscation framework and transformation passes.
emulation: CIL emulation engine for .NET bytecode execution.
metadata: .NET metadata parsing, loading, and type system based on ECMA-335.
prelude: Convenient re-exports of the most commonly used types and traits.
project: Multi-assembly project management and loading.

Macros§

create_table_match: Generate the complete match expression for creating metadata tables in TablesHeader::add_table().
dispatch_table_type: Macro that provides unified dispatch from TableId enum values to their corresponding Raw table types.
impl_table_access: Generate TableAccess trait implementations for metadata tables.
malformed_error: Helper macro for creating malformed data errors with source location information.
out_of_bounds_error: Helper macro for creating out-of-bounds errors with source location information.
owned_validators: Creates a collection of owned validators with automatic priority sorting.
raw_validators: Convenience macros for creating validator collections.

Structs§

CilAssembly: Mutable assembly for editing and modification operations.
CleanupRequest: Mutable assembly for editing and modification operations.
CoffHeader: Provides access to low-level file and memory parsing utilities.
DataDirectories: Provides access to low-level file and memory parsing utilities.
DataDirectory: Provides access to low-level file and memory parsing utilities.
DosHeader: Provides access to low-level file and memory parsing utilities.
File: Provides access to low-level file and memory parsing utilities.
LastWriteWinsResolver: Mutable assembly for editing and modification operations.
Machine: Provides access to low-level file and memory parsing utilities.
MethodBodyBuilder: Mutable assembly for editing and modification operations.
MethodBuilder: Mutable assembly for editing and modification operations.
OptionalHeader: Provides access to low-level file and memory parsing utilities.
Parser: Provides access to low-level file and memory parsing utilities.
Pe: Provides access to low-level file and memory parsing utilities.
PeCharacteristics: Provides access to low-level file and memory parsing utilities.
PeExport: Provides access to low-level file and memory parsing utilities.
PeImport: Provides access to low-level file and memory parsing utilities.
SectionTable: Provides access to low-level file and memory parsing utilities.
StandardFields: Provides access to low-level file and memory parsing utilities.
Subsystem: Provides access to low-level file and memory parsing utilities.
WindowsFields: Provides access to low-level file and memory parsing utilities.

Enums§

ChangeRefKind: Mutable assembly for editing and modification operations.
DataDirectoryType: Provides access to low-level file and memory parsing utilities.
Error: dotscope Error type.

Type Aliases§

ChangeRefRc: Mutable assembly for editing and modification operations.
Result: dotscope Result type.

Crate dotscope

Crate dotscope Copy item path

§dotscope

§Architecture

§Key Components

§Features

§Usage Examples

§Quick Start

§Using the Prelude

§Basic Assembly Analysis

§Memory-based Analysis

§Custom Analysis with Validation

§CIL Instruction Processing

§Disassembly

§Assembly

§Integration

§Metadata-Driven Disassembly

§Standards Compliance

§References

§Error Handling

§Thread Safety

§Development and Testing

Re-exports§

Modules§

Macros§

Structs§

Enums§

Type Aliases§

Crate dotscope