dotscope

https://docs.rs/dotscope
Admin
dotscope is a cross-platform Rust framework for analyzing, deobfuscating, emulating, and modifying...
Tokens:2,700,947
Snippets:27,945
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Basic Sequential Access Example

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.GuidIterator.html

Demonstrates basic iteration over GUIDs in a heap.

```APIDOC
### §Basic Sequential Access
```rust
use dotscope::metadata::streams::Guid;

#[rustfmt::skip]
let heap_data = [
    // GUID 1: Real assembly identifier
    0x8e, 0x90, 0x37, 0xd4, 0xe6, 0x65, 0x7c, 0x48,
    0x97, 0x35, 0x7b, 0xdf, 0xf6, 0x99, 0xbe, 0xa5,
    // GUID 2: Module identifier
    0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA,
    0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA,
];

let guid_heap = Guid::from(&heap_data)?;
let mut iterator = guid_heap.iter();
let null_guid = uguid::guid!("00000000-0000-0000-0000-000000000000");

// First GUID at index 1
let (index1, guid1) = iterator.next().unwrap();
assert_eq!(index1, 1);
assert_ne!(guid1, null_guid);

// Second GUID at index 2
let (index2, guid2) = iterator.next().unwrap();
assert_eq!(index2, 2);
assert_ne!(guid2, null_guid);

// No more GUIDs
assert!(iterator.next().is_none());
```
```

--------------------------------

### Get Process Summary Example

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.ProcessSummary.html

Demonstrates how to obtain and print information from a ProcessSummary object. This is useful for quick checks and debugging.

```rust
let summary = process.summary();
println!("Process: {}", summary.name);
println!("Instructions: {}", summary.instruction_count);
println!("Captured: {} assemblies, {} strings",
    summary.captured_assemblies,
    summary.captured_strings);
```

--------------------------------

### InstructionPointer Example

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.InstructionPointer.html

Example demonstrating the creation and usage of InstructionPointer.

```APIDOC
## Example
```rust
use dotscope::emulation::InstructionPointer;
use dotscope::metadata::token::Token;

// Create pointer at start of method
let mut ip = InstructionPointer::new(Token::new(0x06000001));
assert_eq!(ip.offset(), 0);

// Advance past a 5-byte instruction
ip.advance(5);
assert_eq!(ip.offset(), 5);

// Branch to new location
ip.branch_to(100);
assert_eq!(ip.offset(), 100);
```
```

--------------------------------

### StackTraceEntry Example

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.StackTraceEntry.html

An example demonstrating how to create and use a StackTraceEntry.

```APIDOC
## Example

```rust
use dotscope::emulation::StackTraceEntry;
use dotscope::metadata::token::Token;

let entry = StackTraceEntry {
    method: Token::new(0x06000001),
    method_name: Some("MyClass::MyMethod".to_string()),
    offset: 0x0042,
};
println!("at {} (IL_{:04X})", entry.method_name.unwrap(), entry.offset);
```
```

--------------------------------

### Initial Assembly Loading Example

Source: https://docs.rs/dotscope/latest/dotscope/prelude/index.html

A basic example demonstrating how to load a .NET assembly from a file path using the prelude.

```rust
use dotscope::prelude::*;

// Now you have access to the most common types
let assembly = CilObject::from_path("tests/samples/WindowsBase.dll")?;
let methods = assembly.methods();
```

--------------------------------

### Iterating Over All GUIDs

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.Guid.html

Provides an example of iterating through all GUIDs present in the Guid heap.

```APIDOC
## Iterating Over All GUIDs

### Description
Iterate over all GUIDs in the heap.

### Request Example
```rust
use dotscope::metadata::streams::Guid;

let heap_data = [0xFF; 32]; // Two GUIDs with pattern data
let guid_heap = Guid::from(&heap_data)?;

for (index, guid) in &guid_heap {
    println!("GUID {}: {}", index, guid);
}
```
```

--------------------------------

### Create CustomDebugKind from GUID Bytes

Source: https://docs.rs/dotscope/latest/dotscope/metadata/customdebuginformation/enum.CustomDebugKind.html

Shows how to create a CustomDebugKind enum variant from a 16-byte GUID array. Includes examples for a known GUID and an unknown GUID.

```rust
use dotscope::metadata::customdebuginformation::CustomDebugKind;

// Known Source Link GUID
let sourcelink_guid = [0x56, 0x05, 0x11, 0xCC, 0x91, 0xA0, 0x38, 0x4D,
                       0x9F, 0xEC, 0x25, 0xAB, 0x9A, 0x35, 0x1A, 0x6A];
let kind = CustomDebugKind::from_guid(sourcelink_guid);
assert_eq!(kind, CustomDebugKind::SourceLink);

// Unknown GUID
let unknown_guid = [0x00; 16];
let kind = CustomDebugKind::from_guid(unknown_guid);
assert!(matches!(kind, CustomDebugKind::Unknown(_)));
```

--------------------------------

### InstructionPointer Example

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.InstructionPointer.html

Demonstrates creating an InstructionPointer, advancing its offset, and branching to a new location. Requires importing InstructionPointer and Token.

```rust
use dotscope::emulation::InstructionPointer;
use dotscope::metadata::token::Token;

// Create pointer at start of method
let mut ip = InstructionPointer::new(Token::new(0x06000001));
assert_eq!(ip.offset(), 0);

// Advance past a 5-byte instruction
ip.advance(5);
assert_eq!(ip.offset(), 5);

// Branch to new location
ip.branch_to(100);
assert_eq!(ip.offset(), 100);
```

--------------------------------

### Load and Analyze .NET Assembly using Prelude

Source: https://docs.rs/dotscope

This example demonstrates loading a .NET assembly from a file path and printing the number of methods found, using the convenient prelude for common types.

```rust
use dotscope::prelude::*;

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

```

--------------------------------

### Enumerate Assembly and Module GUIDs

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.Guid.html

This example shows how to differentiate between assembly and module GUIDs during iteration, based on their index. It collects and counts GUIDs for each category.

```rust
use dotscope::metadata::streams::Guid;

let heap_data = [0xAB; 48]; // Three identical GUIDs for demonstration
let guid_heap = Guid::from(&heap_data)?;

let mut assembly_guids = Vec::new();
let mut module_guids = Vec::new();

for (index, guid) in guid_heap.iter() {
     
    if index == 1 {
        assembly_guids.push(guid);
    } else {
        module_guids.push(guid);
    }
}

println!("Found {} assembly GUIDs, {} module GUIDs",
         assembly_guids.len(), module_guids.len());
```

--------------------------------

### Start building a FileIOPermission

Source: https://docs.rs/dotscope/latest/dotscope/metadata/security/builders/struct.PermissionSetBuilder.html

Shows how to begin configuring a `System.Security.Permissions.FileIOPermission` with specific read and write paths. This permission controls file system access.

```rust
use dotscope::metadata::security::PermissionSetBuilder;

let builder = PermissionSetBuilder::new()
    .add_file_io_permission()
        .read_paths(&["C:\\Data"])
        .write_paths(&["C:\\Logs"])
        .build();
```

--------------------------------

### Access GUID Heap

Source: https://docs.rs/dotscope/latest/dotscope/metadata/cilobject/struct.CilObject.html

Get the #GUID heap, which stores 16-byte GUIDs referenced by metadata tables, often for COM interop. Returns None if the stream is missing.

```rust
use dotscope::CilObject;

let assembly = CilObject::from_path("tests/samples/mono_4.8/mscorlib.dll")?;

if let Some(guids) = assembly.guids() {
    // Look up GUID by index (from metadata table)
    if let Ok(guid) = guids.get(1) {
        println!("GUID: {}", guid);
    }
}
```

--------------------------------

### Instance Constructor Example

Source: https://docs.rs/dotscope/latest/dotscope/struct.MethodBuilder.html

Shows how to create an instance constructor for a class, including setting parameters and calling the base constructor.

```APIDOC
## Instance Constructor

### Description
Example of creating an instance constructor.

### Code
```rust
use dotscope::MethodBuilder;
use dotscope::metadata::signatures::TypeSignature;
use dotscope::metadata::token::Token;

let ctor_token = MethodBuilder::constructor()
    .parameter("name", TypeSignature::String)
    .parameter("age", TypeSignature::I4)
    .implementation(|body| {
        body.implementation(|asm| {
            // Call base constructor
            asm.ldarg_0()?  // this
               .call(Token::new(0x0A000001))? // base ctor token
               // Initialize fields...
               .ret()?;
            Ok(())
        })
    })
    .build(&mut assembly)?; // Assuming 'assembly' is a mutable CilAssembly instance
```
```

--------------------------------

### Assembly Identity GUID Access Example

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.Guid.html

Shows how to retrieve an assembly's GUID from a heap when its index is known from metadata. The retrieved GUID can then be used for comparisons or logging.

```rust
use dotscope::metadata::streams::Guid;

// Assembly table references GUID index 1
let assembly_guid_index = 1;
let heap_data = [0xAB; 16]; // Sample assembly GUID

let guid_heap = Guid::from(&heap_data)?;
let assembly_guid = guid_heap.get(assembly_guid_index)?;

let null_guid = uguid::guid!("00000000-0000-0000-0000-000000000000");
// Use for assembly comparison or caching
if assembly_guid != null_guid {
    println!("Assembly identifier: {}", assembly_guid);
}
```

--------------------------------

### Method Parameter Ordering Example

Source: https://docs.rs/dotscope/latest/dotscope/metadata/signatures/struct.SignatureMethod.html

Illustrates how parameters are ordered in a method signature and how they correspond to the `params` vector.

```text
void Method(int first, string second, bool third)
// params[0] = int, params[1] = string, params[2] = bool
```

--------------------------------

### Basic GUID Access from Heap

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.Guid.html

Demonstrates retrieving individual GUIDs from a constructed heap using 1-based indexing. Includes accessing a valid GUID and a null GUID, showcasing the `get` method's functionality.

```rust
use dotscope::metadata::streams::Guid;

#[rustfmt::skip]
let heap_data = [
    // GUID 1: d437908e-65e6-487c-9735-7bdff699bea5
    0x8e, 0x90, 0x37, 0xd4, 0xe6, 0x65, 0x7c, 0x48,
    0x97, 0x35, 0x7b, 0xdf, 0xf6, 0x99, 0xbe, 0xa5,
    // GUID 2: All zeros (null GUID)
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
];

let guid_heap = Guid::from(&heap_data)?;

// Access first GUID (1-based indexing)
let first_guid = guid_heap.get(1)?;
let null_guid = uguid::guid!("00000000-0000-0000-0000-000000000000");
assert_ne!(first_guid, null_guid);

// Access second GUID
let second_guid = guid_heap.get(2)?;
assert_eq!(second_guid, null_guid);
```

--------------------------------

### Get GUID Heap Index Bytes

Source: https://docs.rs/dotscope/latest/dotscope/metadata/tables/struct.TableInfo.html

Returns the byte size of #GUID heap indices (2 or 4 bytes).

```APIDOC
## guid_bytes

### Description
Returns the byte size of #GUID heap indices.

### Method
`guid_bytes() -> u8`

### Returns
`4` if the GUID heap uses large indices, `2` otherwise.
```

--------------------------------

### EmulationConfig Usage Examples

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.EmulationConfig.html

Demonstrates how to create and customize EmulationConfig instances using default, preset, and manual configurations.

```rust
use dotscope::emulation::EmulationConfig;

// Default configuration
let config = EmulationConfig::default();

// Preset for extraction
let config = EmulationConfig::extraction();

// Custom configuration
let config = EmulationConfig {
    symbolic_tracking: true,
    threading_enabled: false,
    ..EmulationConfig::analysis()
};
```

--------------------------------

### Classify GUIDs as null or active

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.GuidIterator.html

Illustrates how to classify GUIDs within a heap by checking if they are null. This example iterates through a heap containing only null GUIDs and counts them, printing a summary.

```rust
use dotscope::metadata::streams::Guid;

let heap_data = [0x00; 48]; // Three null GUIDs
let guid_heap = Guid::from(&heap_data)?;
let null_guid = uguid::guid!("00000000-0000-0000-0000-000000000000");

let mut null_count = 0;
let mut non_null_count = 0;

for result in guid_heap.iter() {
    let (index, guid) = result;
     
    if guid == null_guid {
        null_count += 1;
        println!("Null GUID at index {}", index);
    } else {
        non_null_count += 1;
        println!("Active GUID at index {}: {}", index, guid);
    }
}

println!("Summary: {} null, {} active", null_count, non_null_count);
```

--------------------------------

### Create and Use Security Instance

Source: https://docs.rs/dotscope/latest/dotscope/metadata/security/struct.Security.html

Demonstrates how to create a Security instance with a specific action and permission set, and how to inspect its action.

```rust
use dotscope::metadata::security::{Security, SecurityAction, PermissionSet};
use std::sync::Arc;

let permission_set = Arc::new(PermissionSet::new(&permission_data)?);

let security = Security {
    action: SecurityAction::Demand,
    permission_set,
};

match security.action {
    SecurityAction::Demand => {
        println!("This code demands specific permissions from callers");
    },
    _ => println!("Other security action"),
}
```

--------------------------------

### Handle GUID iteration with valid data

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.GuidIterator.html

Demonstrates the basic iteration over a GUID heap that contains valid GUID data. This example shows that the iterator proceeds without issues when the heap data is well-formed.

```rust
use dotscope::metadata::streams::Guid;

// Valid heap with two complete GUIDs
let heap_data = [0xFF; 32];
let guid_heap = Guid::from(&heap_data)?;

for (index, guid) in guid_heap.iter() {
    println!("GUID {}: {}", index, guid);
}
```

--------------------------------

### Create and execute a .NET process

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.EmulationProcess.html

Demonstrates creating an EmulationProcess using ProcessBuilder, finding an entry point, executing a method, and retrieving captured assemblies. Ensure the 'assembly' variable is defined and the build operation is handled for potential errors.

```rust
use dotscope::emulation::ProcessBuilder;
use dotscope::CilObject;

// Create a process
let process = ProcessBuilder::new()
    .assembly(assembly)
    .for_extraction()
    .capture_assemblies()
    .build()?;

// Find entry point and execute
if let Some(entry) = process.find_entry_point() {
    let outcome = process.execute_method(entry, vec![])?;
}

// Retrieve results
for captured in process.captured_assemblies() {
    std::fs::write("unpacked.dll", &captured.data)?;
}
```

--------------------------------

### AddressSpace Initialization and Usage Example

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.AddressSpace.html

Demonstrates creating a new AddressSpace, allocating a managed string, mapping raw memory, and setting a static field. Ensure necessary imports are present.

```rust
use dotscope::emulation::{AddressSpace, EmValue};
use dotscope::metadata::token::Token;

let space = AddressSpace::new();

// Allocate managed objects
let str_ref = space.alloc_string("Hello").unwrap();

// Map raw memory
space.map_data(0x1000, &[1, 2, 3, 4], "data").unwrap();

// Access static fields
let field_token = Token::new(0x04000001);
space.set_static(field_token, EmValue::I32(42)).unwrap();
```

--------------------------------

### Identity Classification Example

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.GuidIterator.html

Shows how to classify GUIDs as null or active during iteration.

```APIDOC
### §Identity Classification
```rust
use dotscope::metadata::streams::Guid;

let heap_data = [0x00; 48]; // Three null GUIDs
let guid_heap = Guid::from(&heap_data)?;
let null_guid = uguid::guid!("00000000-0000-0000-0000-000000000000");

let mut null_count = 0;
let mut non_null_count = 0;

for result in guid_heap.iter() {
    let (index, guid) = result;
     
    if guid == null_guid {
        null_count += 1;
        println!("Null GUID at index {}", index);
    } else {
        non_null_count += 1;
        println!("Active GUID at index {}: {}", index, guid);
    }
}

println!("Summary: {} null, {} active", null_count, non_null_count);
```
```

--------------------------------

### Basic Usage Example

Source: https://docs.rs/dotscope/latest/dotscope/metadata/method/struct.InstructionIterator.html

Demonstrates how to iterate through the first few methods of an assembly and print their instructions.

```APIDOC
## Basic Usage
```rust
use dotscope::CilObject;
use std::path::Path;

let assembly = CilObject::from_path(Path::new("tests/samples/WindowsBase.dll"))?;
for entry in assembly.methods().iter().take(3) {
    let method = entry.value();
    let mut instruction_count = 0;
     
    for instruction in method.instructions() {
        println!("IL_{:04X}: {} {:?}",
                instruction.offset, instruction.mnemonic, instruction.operand);
        instruction_count += 1;
         
        if instruction_count >= 10 { break; } // Limit for readability
    }
     
    println!("Method {} has {} total instructions",
             method.name, method.instruction_count());
}
```
```

--------------------------------

### SsaFunction Overview and Example

Source: https://docs.rs/dotscope/latest/dotscope/analysis/struct.SsaFunction.html

Demonstrates the basic structure of an SsaFunction and provides an example of its creation and usage, including adding blocks and querying variables.

```APIDOC
## Struct SsaFunction

### Description
A method in SSA (Static Single Assignment) form. This is the complete SSA representation of a CIL method, containing all basic blocks with phi nodes and SSA instructions, all SSA variables with their metadata, method signature information, and exception handlers.

### Example
```rust
use dotscope::analysis::{SsaFunction, SsaBlock, SsaVarId};

// Create an SSA function with 2 args, 1 local, and 3 blocks
let mut func = SsaFunction::new(2, 1);

// Add blocks
func.add_block(SsaBlock::new(0));
func.add_block(SsaBlock::new(1));
func.add_block(SsaBlock::new(2));

// Query variables
for var in func.variables() {
    println!("Variable: {}", var);
}
```
```

--------------------------------

### Get Stream Position

Source: https://docs.rs/dotscope/latest/dotscope/metadata/tables/type.CustomAttributeRc.html

Returns the current seek position from the start of the stream.

```rust
use std::io::Seek;

let mut seeker: Arc<dyn Seek> = ...;
let position = seeker.stream_position()?;
```

--------------------------------

### Construct Invalid GUID Heap

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.Guid.html

Shows examples of attempting to create a Guid heap with insufficient or empty data, resulting in an error. This highlights the validation checks performed during construction.

```rust
use dotscope::metadata::streams::Guid;

// Too small for even one GUID
let too_small = [0u8; 10];
assert!(Guid::from(&too_small).is_err());

// Empty data
let empty_data = &[];
assert!(Guid::from(empty_data).is_err());
```

--------------------------------

### Find First Occurrence of Guid

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.Guid.html

Use the `find` method to get the 1-based index of the first occurrence of a GUID in the heap. Returns `Some(index)` if found, `None` otherwise. This index is useful for metadata table references.

```rust
use dotscope::metadata::streams::Guid;

#[rustfmt::skip]
let heap_data = [
    0x8e, 0x90, 0x37, 0xd4, 0xe6, 0x65, 0x7c, 0x48,
    0x97, 0x35, 0x7b, 0xdf, 0xf6, 0x99, 0xbe, 0xa5,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
];
let guid_heap = Guid::from(&heap_data)?;

let target = uguid::guid!("d437908e-65e6-487c-9735-7bdff699bea5");
let null_guid = uguid::guid!("00000000-0000-0000-0000-000000000000");

assert_eq!(guid_heap.find(&target), Some(1));  // 1-based index
assert_eq!(guid_heap.find(&null_guid), Some(2));  // 1-based index

```

--------------------------------

### Initialize and Use DeobfuscationEngine

Source: https://docs.rs/dotscope/latest/dotscope/deobfuscation/struct.DeobfuscationEngine.html

Demonstrates how to initialize the DeobfuscationEngine with default configuration and use it to process an assembly from a file or a single method. Requires importing DeobfuscationEngine and EngineConfig.

```rust
use dotscope::deobfuscation::{DeobfuscationEngine, EngineConfig};

let config = EngineConfig::default();
let engine = DeobfuscationEngine::new(config);

// Process entire assembly from file
let (deobfuscated, result) = engine.process_file("obfuscated.dll")?;
println!("{}", result.summary());

// Or process a single method (consumes the assembly)
let assembly = CilObject::from_path("obfuscated.dll")?;
let (ssa, result) = engine.process_method(assembly, method_token)?;
```

--------------------------------

### Get the raw underlying data of the GUID heap

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.Guid.html

Returns the raw underlying data of the GUID heap, providing access to the complete heap data containing all 16-byte GUID entries in their original binary format. Useful for heap size calculation, bounds checking, and low-level metadata analysis.

```APIDOC
## pub fn data(&self) -> &[u8]

### Description
Returns the raw underlying data of the GUID heap.
This provides access to the complete heap data containing all 16-byte GUID entries in their original binary format. This method is useful for heap size calculation, bounds checking, and low-level metadata analysis.

### Returns
A byte slice containing the complete GUID heap data.

### Examples
```rust
use dotscope::metadata::streams::Guid;

let heap_data = [0xAB; 32]; // Two GUIDs, 16 bytes each
let guid_heap = Guid::from(&heap_data)?;

assert_eq!(guid_heap.data().len(), 32);
assert_eq!(guid_heap.data().len() / 16, 2); // Two GUIDs
```
```

--------------------------------

### Get Elapsed Analysis Time

Source: https://docs.rs/dotscope/latest/dotscope/compiler/struct.CompilerContext.html

Returns the total duration since the analysis started. Useful for performance monitoring.

```rust
pub fn elapsed(&self) -> Duration
```

--------------------------------

### Creating RuntimeState Instances

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.RuntimeState.html

Demonstrates creating RuntimeState instances with both default and custom configurations. The default constructor includes BCL hooks and P/Invoke stubs, while `with_config` allows for a minimal or tailored setup.

```rust
use dotscope::emulation::runtime::RuntimeState;
use dotscope::emulation::process::EmulationConfig;
use std::sync::Arc;

// Default configuration
let runtime = RuntimeState::new();

// Custom configuration
let config = EmulationConfig::minimal();
let runtime = RuntimeState::with_config(Arc::new(config));

// Access hooks (both BCL and native P/Invoke hooks are pre-registered)
println!("Hooks: {}", runtime.hooks().len());
```

--------------------------------

### Basic Assembly Analysis with Prelude

Source: https://docs.rs/dotscope/latest/dotscope/prelude/index.html

Demonstrates how to use the prelude for basic .NET assembly analysis, including loading an assembly and iterating through its types.

```rust
use dotscope::prelude::*;

// Core functionality immediately available
let assembly = CilObject::from_path("example.dll")?;
let types = assembly.types();

// Type system components
for entry in types.iter() {
    let cil_type = entry.value();
    match cil_type.flavor() {
        CilFlavor::Class => println!("Class: {}.{}", cil_type.namespace, cil_type.name),
        CilFlavor::Interface => println!("Interface: {}.{}", cil_type.namespace, cil_type.name),
        _ => {}
    }
}
```

--------------------------------

### Usage Example for CilTypeRefList

Source: https://docs.rs/dotscope/latest/dotscope/metadata/typesystem/type.CilTypeRefList.html

Demonstrates how to initialize and use CilTypeRefList. Ensure you have the necessary imports for CilTypeRefList, CilTypeRef, and Arc.

```rust
use dotscope::metadata::typesystem::{CilTypeRefList, CilTypeRef};
use std::sync::Arc;

let type_list: CilTypeRefList = Arc::new(boxcar::Vec::new());
// Add type references to the collection
```

--------------------------------

### Get Pass Count

Source: https://docs.rs/dotscope/latest/dotscope/compiler/struct.PassScheduler.html

Retrieves the number of non-normalization passes that have been registered with the scheduler. This can be useful for monitoring or debugging the pipeline setup.

```rust
pub fn pass_count(&self) -> usize
```

--------------------------------

### Get Current Stream Position

Source: https://docs.rs/dotscope/latest/dotscope/metadata/tables/type.AssemblyProcessorList.html

Returns the current seek position from the start of the stream. Useful for tracking progress or resuming operations.

```rust
Source§
#### fn stream_position(&mut self) -> Result<u64, Error>
Returns the current seek position from the start of the stream. Read more
Source§
```

--------------------------------

### Initialize and Use CilProject

Source: https://docs.rs/dotscope/latest/dotscope/project/struct.CilProject.html

Demonstrates creating a new CilProject, adding an assembly, and performing basic lookups and counts. Ensure necessary imports are present.

```rust
use dotscope::project::CilProject;
use dotscope::CilObject;
use std::path::Path;

let project = CilProject::new();

// Add assemblies to the project
let assembly = CilObject::from_path(Path::new("example.dll"))?;
project.add_assembly(assembly, true)?;

// Look up types across all loaded assemblies
if let Some(string_type) = project.get_type_by_name("System.String") {
    println!("Found type: {}", string_type.name);
}

println!("Project contains {} assemblies", project.assembly_count());

```

--------------------------------

### Get Language Name

Source: https://docs.rs/dotscope/latest/dotscope/metadata/tables/struct.Document.html

Returns a human-readable name for the programming language associated with the document. This method translates the language GUID into a recognizable string.

```rust
pub fn language_name(&self) -> &'static str
```

--------------------------------

### Example CilInstruction Initialization

Source: https://docs.rs/dotscope/latest/dotscope/assembly/struct.CilInstruction.html

Demonstrates how to initialize a CilInstruction with sample metadata for a 'nop' instruction. Ensure necessary types like OperandType, InstructionCategory, and FlowType are imported.

```rust
use dotscope::assembly::{CilInstruction, OperandType, InstructionCategory, FlowType};

// Example instruction definition (simplified)
let nop_instruction = CilInstruction {
    op_type: OperandType::None,
    instr: "nop",
    category: InstructionCategory::Misc,
    stack_pops: 0,
    stack_pushes: 0,
    flow: FlowType::Sequential,
};
```

--------------------------------

### Initialize and Step Interpreter

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.Interpreter.html

Demonstrates how to initialize an Interpreter and execute instructions step-by-step within a loop. Handles different step results like Continue, Return, and Branch.

```rust
use dotscope::emulation::{Interpreter, EmulationContext, EmulationLimits};

let limits = EmulationLimits::default();
let mut interpreter = Interpreter::new(limits, address_space, PointerSize::Bit64);

// Execute instructions one at a time
loop {
    match interpreter.step(&mut thread, &instruction)? {
        StepResult::Continue => continue,
        StepResult::Return { value } => break,
        StepResult::Branch { target } => {
            // Handle branch...
        }
        _ => {}
    }
}
```

--------------------------------

### Get Hash Algorithm Name

Source: https://docs.rs/dotscope/latest/dotscope/metadata/tables/struct.Document.html

Retrieves a human-readable string representing the hash algorithm used for the document. Provides a user-friendly name for the GUID.

```rust
pub fn hash_algorithm_name(&self) -> &'static str
```

--------------------------------

### Security Example Usage

Source: https://docs.rs/dotscope/latest/dotscope/metadata/security/struct.Security.html

Demonstrates how to create and use a Security object, including checking its action.

```APIDOC
## §Examples
```
use dotscope::metadata::security::{Security, SecurityAction, PermissionSet};
use std::sync::Arc;

let permission_set = Arc::new(PermissionSet::new(&permission_data)?);

let security = Security {
    action: SecurityAction::Demand,
    permission_set,
};

match security.action {
    SecurityAction::Demand => {
        println!("This code demands specific permissions from callers");
    },
    _ => println!("Other security action"),
}
```
```

--------------------------------

### Get Stream Position

Source: https://docs.rs/dotscope/latest/dotscope/metadata/customattributes/type.CustomAttributeValueList.html

Returns the current position within an Arc-wrapped `Seek`able stream. This indicates the number of bytes from the start of the stream.

```rust
use std::io::Seek;

// Assuming 'arc_seekable' is an Arc<impl Seek>
// let position = arc_seekable.stream_position()?;
```

--------------------------------

### Start building a SecurityPermission

Source: https://docs.rs/dotscope/latest/dotscope/metadata/security/builders/struct.PermissionSetBuilder.html

Demonstrates initiating the configuration of a `System.Security.Permissions.SecurityPermission` using its dedicated builder. This permission type controls fundamental security operations.

```rust
use dotscope::metadata::security::PermissionSetBuilder;

let builder = PermissionSetBuilder::new()
    .add_security_permission()
        .flags("Execution, SkipVerification")
        .build();
```

--------------------------------

### Custom Bounds Array Example

Source: https://docs.rs/dotscope/latest/dotscope/metadata/signatures/struct.SignatureArray.html

Illustrates creating an array signature with custom lower bounds for each dimension. Useful for arrays that do not start at index 0.

```rust
use dotscope::metadata::signatures::{SignatureArray, TypeSignature};
use dotscope::metadata::typesystem::ArrayDimensions;

let custom_array = SignatureArray {
    base: Box::new(TypeSignature::String),
    rank: 2,
    dimensions: vec![
        ArrayDimensions { size: Some(5), lower_bound: Some(1) }, // [1..5]
        ArrayDimensions { size: Some(6), lower_bound: Some(2) }, // [2..7]
    ],
};
```

--------------------------------

### ResourceType as_str() Examples

Source: https://docs.rs/dotscope/latest/dotscope/metadata/resources/enum.ResourceType.html

Demonstrates how to get the .NET type name for different ResourceType variants. Returns None for types without a direct .NET equivalent.

```rust
use dotscope::metadata::resources::ResourceType;

let string_type = ResourceType::String("hello".to_string());
assert_eq!(string_type.as_str(), Some("System.String"));

let int_type = ResourceType::Int32(42);
assert_eq!(int_type.as_str(), Some("System.Int32"));

let null_type = ResourceType::Null;
assert_eq!(null_type.as_str(), None);
```

--------------------------------

### new()

Source: https://docs.rs/dotscope/latest/dotscope/deobfuscation/struct.EngineConfig.html

Creates a new configuration with default settings.

```APIDOC
## new()

### Description
Creates a new configuration with default settings.

### Returns
A new `EngineConfig` with default values.
```

--------------------------------

### StackBehavior Examples

Source: https://docs.rs/dotscope/latest/dotscope/assembly/struct.StackBehavior.html

Illustrates how to create and use StackBehavior instances for different instruction types.

```APIDOC
## §Examples
```rust
use dotscope::assembly::StackBehavior;

// An instruction that pops 2 values and pushes 1 (like 'add')
let add_behavior = StackBehavior {
    pops: 2,
    pushes: 1,
    net_effect: -1,
};

// An instruction that only pushes (like 'ldloc')
let load_behavior = StackBehavior {
    pops: 0,
    pushes: 1,
    net_effect: 1,
};
```
```

--------------------------------

### Resolve MemberRef to MethodDef using TokenResolver

Source: https://docs.rs/dotscope/latest/dotscope/metadata/cilobject/struct.CilObject.html

Use the `resolver()` to get a `TokenResolver` for cross-table token resolution. This example shows how to resolve a `MemberRef` token to its local `MethodDef`.

```rust
use dotscope::CilObject;
use dotscope::metadata::token::Token;

let assembly = CilObject::from_path("tests/samples/WindowsBase.dll")?;
let resolver = assembly.resolver();

// Resolve a MemberRef to its local MethodDef
let member_ref = Token::new(0x0A000001);
if let Some(method_def) = resolver.resolve_method(member_ref) {
    println!("Resolved to MethodDef: 0x{:08X}", method_def.value());
}

// Find which type declares a method
let method = Token::new(0x06000001);
if let Some(declaring_type) = resolver.declaring_type(method) {
    println!("Declared in: {}", declaring_type.fullname());
}
```

--------------------------------

### Example Usage of StaticFieldStorage

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.StaticFieldStorage.html

Demonstrates how to create, set, get, and fork StaticFieldStorage. It shows storing an integer value, retrieving it, and verifying that forking creates an independent copy.

```rust
use dotscope::emulation::{StaticFieldStorage, EmValue};
use dotscope::metadata::token::Token;

let storage = StaticFieldStorage::new();

// Store a static field
let field_token = Token::new(0x04000001);
storage.set(field_token, EmValue::I32(42)).unwrap();

// Retrieve it later
assert_eq!(storage.get(field_token).unwrap(), Some(EmValue::I32(42)));

// Fork creates an independent copy (O(1) operation!)
let forked = storage.fork().unwrap();
forked.set(field_token, EmValue::I32(100)).unwrap();
// Original is unchanged
assert_eq!(storage.get(field_token).unwrap(), Some(EmValue::I32(42)));
```

--------------------------------

### Initialize and Use SyncState

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.SyncState.html

Demonstrates basic initialization and usage of SyncState for monitor and event operations. Ensure SyncState is initialized before use.

```rust
let mut sync = SyncState::new();

// Monitor operations
if sync.monitor_try_enter(obj, thread_id) {
    // Critical section
    sync.monitor_exit(obj, thread_id)?;
}

// Event operations
sync.event_create(event_obj, true, false); // ManualResetEvent
let threads_to_wake = sync.event_set(event_obj);
```

--------------------------------

### Get PE Headers Offset

Source: https://docs.rs/dotscope/latest/dotscope/prelude/struct.Pe.html

Returns the starting offset of the PE headers relative to the DOS header. This is crucial for locating PE headers within the file structure.

```rust
pub fn get_pe_headers_offset(&self) -> u64
```

--------------------------------

### Basic Assembly Loading and Analysis Example

Source: https://docs.rs/dotscope/latest/dotscope/metadata/cilobject/index.html

Demonstrates how to load a .NET assembly from a file and access basic information like module and assembly details, as well as counts of types and methods.

```rust
use dotscope::CilObject;
use std::path::Path;

// Load an assembly from file
let assembly = CilObject::from_path(Path::new("tests/samples/mono_4.8/mscorlib.dll"))?;

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

if let Some(assembly_info) = assembly.assembly() {
    println!("Assembly: {}", assembly_info.name);
}

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

--------------------------------

### Basic Sequential Access Example

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.BlobIterator.html

Demonstrates how to create a BlobIterator from a Blob heap and iterate through its contents to access blob data.

```rust
use dotscope::metadata::streams::Blob;

let data = &[0x00, 0x03, 0x41, 0x42, 0x43, 0x01, 0x44];
let blob_heap = Blob::from(data)?;
let mut iterator = blob_heap.iter();

// First blob: "ABC" at offset 1
let (offset1, blob1) = iterator.next().unwrap();
assert_eq!(offset1, 1);
assert_eq!(blob1, b"ABC");

// Second blob: "D" at offset 5
let (offset2, blob2) = iterator.next().unwrap();
assert_eq!(offset2, 5);
assert_eq!(blob2, b"D");

// No more blobs
assert!(iterator.next().is_none());
```

--------------------------------

### Process File and Get Deobfuscation Results

Source: https://docs.rs/dotscope/latest/dotscope/deobfuscation/struct.DeobfuscationResult.html

Instantiates a DeobfuscationEngine and processes a file to obtain deobfuscation results. This example shows how to access the event log length and a summary of statistics.

```rust
use dotscope::deobfuscation::{DeobfuscationEngine, EngineConfig};

let engine = DeobfuscationEngine::new(EngineConfig::default());
let result = engine.process_file(&mut assembly)?;

println!("Events: {}", result.events.len());
println!("Stats: {}", result.stats().summary());
```

--------------------------------

### Example Pre-Hook Implementation

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.HookContext.html

Demonstrates how to implement a pre-hook function using HookContext to log method details and arguments. Ensure to extract necessary data before returning.

```rust
use dotscope::emulation::{HookContext, PreHookResult, EmulationThread};

fn my_pre_hook(ctx: &HookContext, thread: &mut EmulationThread) -> PreHookResult {
    println!("Method: {}.{}::{}", ctx.namespace, ctx.type_name, ctx.method_name);
    println!("Args: {:?}", ctx.args);
    PreHookResult::Continue
}
```

--------------------------------

### Get Current Stream Position of Arc Seeker

Source: https://docs.rs/dotscope/latest/dotscope/metadata/tables/type.FieldRVARc.html

Returns the current seek position from the start of an Arc-wrapped `Seek`able stream. This is part of the `Seek` trait implementation for `Arc`.

```rust
use std::io::Seek;

// Assuming `my_arc_seeker` is an Arc<impl Seek>
// let pos = my_arc_seeker.stream_position()?;
```

--------------------------------

### Simple Static Method Example

Source: https://docs.rs/dotscope/latest/dotscope/struct.MethodBuilder.html

Demonstrates how to create a simple static method named 'Add' that takes two integer parameters and returns their sum.

```APIDOC
## Simple Static Method

### Description
Example of creating a simple static method.

### Code
```rust
use dotscope::prelude::*;
use dotscope::MethodBuilder;

let method_token = MethodBuilder::new("Add")
    .public()
    .static_method()
    .parameter("a", TypeSignature::I4)
    .parameter("b", TypeSignature::I4)
    .returns(TypeSignature::I4)
    .implementation(|body| {
        body.implementation(|asm| {
            asm.ldarg_0()? // Load first argument
               .ldarg_1()? // Load second argument
               .add()?      // Add them
               .ret()?;     // Return the result
            Ok(())
        })
    })
    .build(&mut assembly)?; // Assuming 'assembly' is a mutable CilAssembly instance
```
```

--------------------------------

### Get Instruction at Offset

Source: https://docs.rs/dotscope/latest/dotscope/emulation/struct.EmulationContext.html

Retrieves an instruction from a method at a specific offset relative to the start of the method's IL code. This is useful for analyzing control flow and instruction execution.

```APIDOC
## pub fn get_instruction_at(&self, method_token: Token, offset: u32) -> Result<Instruction>

### Description
Gets an instruction at a specific method-relative offset.

The offset is relative to the start of the method’s IL code (0 = first instruction). This is the offset used by CIL branch instructions and the instruction pointer.

### Parameters
* `method_token` (Token) - The token of the method to inspect.
* `offset` (u32) - The offset of the instruction within the method's IL code.

### Returns
Result<Instruction> - The instruction at the specified offset, or an error if the method is not found or no instruction exists at the offset.
```

--------------------------------

### Get Heap Fields for a Table

Source: https://docs.rs/dotscope/latest/dotscope/metadata/tablefields/index.html

Retrieves heap reference fields for a specified table type. Iterates through the fields to identify and print the offset for String, Blob, or GUID heap references.

```rust
use dotscope::metadata::tablefields::{get_heap_fields, HeapType};
use dotscope::metadata::tables::TableId;

// Get heap fields for a TypeDef row
let fields = get_heap_fields(TableId::TypeDef, &table_info);

for field in fields {
    match field.heap_type {
        HeapType::String => println!("String at offset {}", field.offset),
        HeapType::Blob => println!("Blob at offset {}", field.offset),
        HeapType::Guid => println!("GUID at offset {}", field.offset),
    }
}
```

--------------------------------

### Create and Get UserString

Source: https://docs.rs/dotscope/latest/dotscope/metadata/streams/struct.UserStrings.html

Demonstrates creating a UserStrings object from raw byte data and retrieving a specific string by its offset. Ensure the input data is valid and starts with a null byte.

```rust
use dotscope::metadata::streams::UserStrings;

// Create from heap data
let data = &[0u8, 65, 0, 0, 0];
let us = UserStrings::from(data)?;
let s = us.get(1)?;
assert_eq!(s.to_string_lossy(), "A");
```

--------------------------------

### Example: x64 processor targeting

Source: https://docs.rs/dotscope/latest/dotscope/metadata/tables/struct.AssemblyProcessorBuilder.html

Demonstrates building an AssemblyProcessor entry for x64 architecture. Requires the processor field to be set.

```rust
use dotscope::prelude::*;

// x64 processor targeting
let x64_proc = AssemblyProcessorBuilder::new()
    .processor(0x8664)  // x64 architecture
    .build(&mut assembly)?;
```

--------------------------------

### Get Current Stream Position

Source: https://docs.rs/dotscope/latest/dotscope/emulation/type.PostHookFn.html

Returns the current position within the `Arc`-wrapped `Seek`able stream, measured in bytes from the start. This is part of the `Seek` trait implementation for `Arc`.

```rust
fn stream_position(&mut self) -> Result<u64, Error>
```

--------------------------------

### X86Operand Examples

Source: https://docs.rs/dotscope/latest/dotscope/analysis/enum.X86Operand.html

Illustrates how to create and use X86Operand instances for registers, immediate values, and memory locations.

```APIDOC
## §Examples
```rust
use dotscope::analysis::{X86Operand, X86Register, X86Memory};

// Register operand
let reg = X86Operand::Register(X86Register::Eax);
assert!(reg.is_register());

// Immediate operand
let imm = X86Operand::Immediate(42);
assert_eq!(imm.as_immediate(), Some(42));

// Memory operand
let mem = X86Operand::Memory(X86Memory::base_disp(X86Register::Esp, 8, 4));
assert!(mem.is_memory());
```
```

--------------------------------

### Create AssemblyOSBuilder

Source: https://docs.rs/dotscope/latest/dotscope/metadata/tables/struct.AssemblyOSBuilder.html

Demonstrates how to create and configure an AssemblyOSBuilder to set OS platform and version details. Requires importing prelude and a mutable CilAssembly.

```rust
use dotscope::prelude::*;

let mut assembly = CilAssembly::new(view);
let token = AssemblyOSBuilder::new()
    .os_platform_id(1)
    .os_major_version(10)
    .os_minor_version(0)
    .build(&mut assembly)?;
```

--------------------------------

### ResourceType type_code() Examples

Source: https://docs.rs/dotscope/latest/dotscope/metadata/resources/enum.ResourceType.html

Illustrates how to get the official .NET type code for ResourceType variants used in encoding. Returns None for types without direct .NET equivalents or those not yet implemented.

```rust
use dotscope::metadata::resources::ResourceType;

let string_type = ResourceType::String("Hello".to_string());
assert_eq!(string_type.type_code(), Some(0x01));

let int_type = ResourceType::Int32(42);
assert_eq!(int_type.type_code(), Some(0x08));

let null_type = ResourceType::Null;
assert_eq!(null_type.type_code(), None); // No .NET equivalent
```

--------------------------------

### Operand as_string Method Examples

Source: https://docs.rs/dotscope/latest/dotscope/assembly/enum.Operand.html

Shows how to use the `as_string` method on the Operand enum to get a human-readable string representation. This method returns `None` for `Operand::None` and a formatted string for other variants.

```rust
use dotscope::assembly::{Operand, Immediate};
use dotscope::metadata::token::Token;

assert_eq!(Operand::None.as_string(), None);
assert_eq!(Operand::Immediate(Immediate::Int32(42)).as_string(), Some("Int32(42)".to_string()));
assert_eq!(Operand::Target(0x1000).as_string(), Some("0x00001000".to_string()));
assert_eq!(Operand::Token(Token::new(0x06000001)).as_string(), Some("0x06000001".to_string()));
assert_eq!(Operand::Local(5).as_string(), Some("V_5".to_string()));
assert_eq!(Operand::Argument(3).as_string(), Some("A_3".to_string()));
```

--------------------------------

### MethodBuilder - Instance Constructor Example

Source: https://docs.rs/dotscope/latest/dotscope/prelude/struct.MethodBuilder.html

Illustrates creating an instance constructor for a class. This example shows how to define parameters for the constructor and includes a placeholder for calling the base constructor and initializing fields.

```APIDOC
## Instance Constructor

### Description
This example demonstrates how to create an instance constructor (`.ctor`) for a class. It defines parameters for `name` (String) and `age` (I4) and includes a structure for calling the base constructor and initializing instance fields.

### Usage
```rust
use dotscope::MethodBuilder;
use dotscope::metadata::signatures::TypeSignature;
use dotscope::metadata::token::Token;

let ctor_token = MethodBuilder::constructor()
    .parameter("name", TypeSignature::String)
    .parameter("age", TypeSignature::I4)
    .implementation(|body| {
        body.implementation(|asm| {
            // Call base constructor
            asm.ldarg_0()? // Load `this`
               .call(Token::new(0x0A000001))? // Call base constructor token
               // Initialize fields...
               .ret()?;
            Ok(())
        })
    })
    .build(&mut assembly)?;
```
```

--------------------------------

### Set Value Blob for Debug Info

Source: https://docs.rs/dotscope/latest/dotscope/metadata/tables/struct.CustomDebugInformationBuilder.html

Sets the raw blob data for the custom debug information. The format depends on the Kind GUID. Examples include JSON for Source Link or arbitrary binary data.

```rust
use dotscope::prelude::*;

// JSON data for Source Link
let json_data = b"{\"documents\": {\"*\": \"https://github.com/...\"}}";
let builder = CustomDebugInformationBuilder::new()
    .value(json_data);

// Binary data for custom debug info
let binary_data = vec![0x01, 0x02, 0x03, 0x04];
let builder = CustomDebugInformationBuilder::new()
    .value(&binary_data);

// Empty value for some debug info types
let builder = CustomDebugInformationBuilder::new()
    .value(&[]);
```
Tokens:
Raw