dnfile 0.3.0

.NET binary extractor
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

# dnfile

[![CI](https://github.com/marirs/dnfile-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/marirs/dnfile-rs/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/dnfile.svg)](https://crates.io/crates/dnfile)
[![Docs.rs](https://docs.rs/dnfile/badge.svg)](https://docs.rs/dnfile)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![MSRV](https://img.shields.io/badge/MSRV-1.85-blue.svg)](#requirements)

A Rust crate for parsing .NET executable files — PE files containing CLR (Common Language Runtime) metadata, streams, tables, and CIL (Common Intermediate Language) bytecode.

It is a Rust port of [malwarefrank/dnfile](https://github.com/malwarefrank/dnfile), the Python library used by tools like [Mandiant capa](https://github.com/mandiant/capa) for static analysis of .NET malware.

## What it does

Given a .NET PE file (an executable, DLL, or assembly compiled to MSIL), `dnfile` lets you:

- Parse the **CLR header** and verify .NET flags (IL-only, 32-bit-required, strong-named, etc.).
- Walk the **#~ / #- metadata stream** and access its ~50 ECMA-335 tables (`Module`, `TypeDef`, `MethodDef`, `MemberRef`, `Assembly`, `ManifestResource`, etc.) by name or index.
- Read **#Strings, #US, #GUID, #Blob** heaps.
- Resolve **coded indexes** (TypeDefOrRef, MemberRefParent, HasCustomAttribute, …) into typed table rows.
- Decode every **CIL instruction** in every method body, including operand types, branch targets, switch tables, and tokens.
- Detect **mixed-mode** (managed + native) and **P/Invoke** functions.

## Quick start

Add to your `Cargo.toml`:

```toml
[dependencies]
dnfile = "0.3"
```

Then:

```rust
use dnfile::DnPe;

fn main() -> dnfile::Result<()> {
    let pe = DnPe::new("MyAssembly.dll")?;
    let clr = pe.net()?;

    // CLR header flags
    println!("flags: {:?}", clr.flags);

    // Iterate decoded method bodies
    for func in clr.functions() {
        println!("function with {} instructions", func.instructions.len());
    }

    // Direct metadata-table access by name
    let methods = clr.md_table("MethodDef")?;
    println!("MethodDef rows: {}", methods.row_count());

    // Read a user string by RID
    if let Ok(s) = clr.get_us(1) {
        println!("first user string: {}", s);
    }

    Ok(())
}
```

## Command-line tool: `dndump`

`dndump` is a [Mandiant capa](https://github.com/mandiant/capa)-style inspector for .NET binaries. It prints the CLR header, metadata streams, populated tables, and the first methods discovered. Pre-built binaries for Linux / macOS / Windows are attached to each [GitHub release](https://github.com/marirs/dnfile-rs/releases).

Install from source:

```bash
cargo install dnfile --features cli
```

Or build locally:

```bash
cargo build --release --features cli --bin dndump
./target/release/dndump path/to/Sample.exe
```

Other useful invocations:

```bash
dndump --methods 100 Sample.exe        # show first 100 methods
dndump --strings Sample.exe            # also dump #US user strings
dndump --json Sample.exe > parsed.json # machine-readable output
```

A minimal library-usage example lives in [`examples/dnfile.rs`](examples/dnfile.rs):

```bash
cargo run --example dnfile -- path/to/Sample.exe
```

## Feature coverage

Metadata tables supported (with full parse implementations):

`Module`, `TypeRef`, `TypeDef`, `Field`, `MethodDef`, `Param`, `InterfaceImpl`, `MemberRef`, `Constant`, `CustomAttribute`, `FieldMarshal`, `DeclSecurity`, `ClassLayout`, `FieldLayout`, `StandAloneSig`, `EventMap`, `Event`, `PropertyMap`, `Property`, `MethodSemantics`, `MethodImpl`, `ModuleRef`, `TypeSpec`, `ImplMap`, `FieldRva`, `EncLog`, `EncMap`, `Assembly`, `AssemblyProcessor`, `AssemblyOS`, `AssemblyRef`, `AssemblyRefProcessor`, `AssemblyRefOS`, `File`, `ExportedType`, `ManifestResource`, `NestedClass`, `GenericParam`, `GenericMethod`, `GenericParamConstraint`, `FieldPtr`, `MethodPtr`, `ParamPtr`.

Stubbed (returns `NotImplementedError`, does not panic): `EventPtr`, `PropertyPtr`, `Unused`, `MaxTable`. These appear only in uncompressed `#-` streams or are reserved by ECMA-335.

CIL: all one- and two-byte opcodes from ECMA-335 §III.

Not currently implemented: managed-resource (`ResourceSet`) parsing — only the `ManifestResource` metadata-table entry is exposed; the resource blob itself is not parsed.

## Requirements

- Rust **1.85** or newer (2024 edition).

## Why a Rust port?

`dnfile-rs` was originally written to power [capa-rs](https://github.com/marirs/capa-rs), the Rust port of Mandiant's capability extractor. It is suitable for any Rust-side static analysis of .NET binaries that does not require executing the IL.

## Used by

- [capa-rs](https://github.com/marirs/capa-rs) — static capability extractor for PE / ELF / shellcode / .NET binaries.

## License

Licensed under the [Apache License, Version 2.0](LICENSE).

## Acknowledgements

- [malwarefrank/dnfile](https://github.com/malwarefrank/dnfile) — the original Python implementation that this port is modelled on.
- [ECMA-335](https://ecma-international.org/publications-and-standards/standards/ecma-335/) — Common Language Infrastructure (CLI) specification.