fNET 0.1.0

An allocation-free, iced-style .NET CIL and Mono extension disassembler
Documentation
  • Coverage
  • 9.36%
    74 out of 791 items documented1 out of 132 items with examples
  • Size
  • Source code size: 2.3 MB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 3.3 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 4s Average build duration of successful builds.
  • all releases: 4s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • valeria-org/fNET
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • bombaris34

fNET

crates.io Documentation MIT license

A modern Rust disassembler for raw .NET Common Intermediate Language (CIL), with an API shaped like fARM64 and iced-x86.

The library has no dependencies, forbids unsafe code, and defaults to no_std without alloc. Decoder, Instruction, opcode inspection, prefix grouping, switch target iteration, and formatting work without a heap. Rust 1.85 or newer is required (edition 2024).

use fNET::{BufSink, Code, Decoder, DecoderOptions, FmtFormatter, Formatter};

let bytes = [0x1f, 42, 0x2b, 0xfc, 0x2a];
let mut decoder = Decoder::new(&bytes, 0x1000, DecoderOptions::NONE);
let constant = decoder.decode();
assert_eq!(constant.code(), Code::LdcI4S);
assert_eq!(constant.immediate_i32(), Some(42));

let branch = decoder.decode();
assert_eq!(branch.near_branch_target(), Some(0x1000));
let mut buffer = [0; 64];
let mut output = BufSink::new(&mut buffer);
FmtFormatter::new().format(&branch, &mut output).unwrap();
assert_eq!(output.as_str(), "br.s IL_1000");

Install the crate with:

[dependencies]
fNET = "0.1"

Coverage

  • 219 standard CIL instructions and semantic prefixes, covering every assigned one-byte and 0xFE encoding. All six prefixes are supported: constrained., no., readonly., tail., unaligned., and volatile.. no. is included explicitly because CoreCLR's opcode table reserves its slot and Reflection.Emit does not expose it.
  • 43 distinct Mono operation identities, covering the 35 modern 0xF0 instructions, retired mono_jit_attach / mono_jit_detach, the historical mono_get_last_error, and five early conversion/free helpers. Five explicit dialect selections cover the conflicting maps found across all 46 revisions of Mono's main-branch opcode-table history. This includes the current mono_remap_ovf_exc (F0 23) and mono_ldvirtftn_delegate (F0 24). See the source audit for exact revisions and corrections.
  • Private extension registration for unused/reserved slots, including fixed byte payloads, counted byte payloads, and all standard operand layouts.
  • Seven reserved marker descriptors (F8–FD, FF) available through decode_reserved. FE always introduces a two-byte instruction; it cannot be decoded as a standalone prefix1.
  • All operand layouts: signed integers, unsigned local/argument indices, raw IEEE float payloads, metadata tokens, signed branches, and switches.
  • Standard aliases such as brnull, brzero, brinst, endfault, ldelem.any, stelem.any, and ldind.u8.
  • Per-opcode operand layout, exact encoding, canonical mnemonic, opcode kind, static stack behaviour, and control-flow classification.

The catalogue contains 269 operation identities: 219 standard, 43 Mono, and seven reserved. Modern/retired decoding uses 263 descriptors; the three early maps contain 7, 12, and 15 descriptors, and the legacy profile replaces F01B's saver with the getter. Shared operations retain their Code across maps. Code::Invalid and Code::Custom are separate sentinels. Sources are pinned in NOTICE; catalogue generation is reproducible offline.

This library accepts a method's code bytes. PE headers, metadata tables, exception clauses, ReadyToRun code, Mono JIT IR and interpreter wordcode use separate formats. Unregistered experimental or future assignments are reported as invalid. Metadata tokens and Mono wrapper-data indices are retained without requiring an assembly reader. Static stack effects for calls and returns can depend on signatures; count() returns None in those cases.

Decoder API

Decoder::new(bytes, ip, options) follows fARM64's constructor shape; CIL has no bitness argument. with_ip is an alias. The decoder supports decode, decode_into, iced-style decode_out, can_decode, last_error, position, set_position, ip, set_ip, and iteration by value or mutable reference.

use fNET::{Decoder, DecoderOptions, Instruction};

let bytes = [0x00, 0x2a];
let mut decoder = Decoder::new(&bytes, 0, DecoderOptions::ECMA335);
let mut instruction = Instruction::default();
while decoder.can_decode() {
    decoder.decode_out(&mut instruction);
    assert!(!instruction.is_invalid());
}

DecoderOptions::NONE / default() enable all implemented extensions and reject reserved markers, following fARM64's default extension policy. DecoderOptions::ECMA335 disables Mono. FeatureSet::MONO enables the selected Mono map; MONO_LEGACY additionally enables retired identities. Reserved bytes:

use fNET::{DecoderOptions, FeatureSet};
let options = DecoderOptions {
    features: FeatureSet::ALL,
    decode_reserved: true,
};

Instructions are Copy values borrowing the original input. Keep that input alive when storing instructions. bytes() returns the original complete span; offset() is the byte-slice position and ip() is the caller's address mapping. Code names exact operations; Mnemonic and Code::canonical() normalize short and macro forms. op_count() counts explicit operands, while helpers such as variable_index() and immediate_i32() also expose implicit macro values. Typed helpers return Option, avoiding ambiguous zero values.

All CIL fields are read in little-endian byte order without alignment assumptions. Branch targets use the address after the instruction. Switch displacements use the address after the entire switch table. Addresses wrap modulo 2^64. Instruction lengths use usize; switches have no fixed case-count limit and retain a borrowed displacement table instead of allocating one target per case. Mono's pointer-named InlineI operands are four-byte IDs / wrapper-data indices, not host-sized native pointers.

Malformed input

Every decode on nonempty input advances:

  • An unassigned opcode consumes its opcode byte or two-byte escape sequence.
  • A truncated opcode, operand, or switch consumes the remaining tail once.
  • A recognized disabled extension consumes the full encoded instruction.
  • A reserved marker consumes one byte.
  • A direct decode at EOF returns an empty invalid instruction with NoMoreBytes; iteration simply ends.

Failures carry Code::Invalid and a DecodeError on both the instruction and Decoder::last_error(). Raw consumed bytes remain available for diagnostics. Overflowing switch counts are checked against the input before accessing the table. Seeking beyond the slice returns InvalidPosition without changing state.

Prefix grouping

Default decoding reports each semantic prefix as an instruction. Use decode_prefixed() or into_prefixed() to group a prefix sequence with its target:

use fNET::{Code, Decoder, DecoderOptions};
let bytes = [0xfe, 0x13, 0xfe, 0x12, 1, 0x4a];
let grouped = Decoder::new(&bytes, 0, DecoderOptions::NONE).decode_prefixed();
assert_eq!(grouped.instruction.code(), Code::LdindI4);
assert_eq!(grouped.prefixes().count(), 2);
assert_eq!(grouped.len(), 6);

Order, duplicates, and raw prefix operand values are preserved. A trailing sequence is reported as MissingInstruction. PrefixedInstruction exposes the complete span and its first IP; its inner instruction keeps its own opcode IP and offset. Offsets from prefixes() are relative to prefix_bytes().

grouped.validate_prefixes(PrefixValidationOptions::Ecma335) checks all six prefixes: alignment values, nonzero no. masks, per-bit target compatibility, duplicates, constrained type-token tags, and tail. calls followed by ret. The Runtime policy also allows constrained. on call and ldftn, per .NET's ECMA augments. validate_prefixes_with_resolver accepts a PrefixMetadataResolver to validate readonly. calls to an array's special Address method; unresolved calls return MetadataRequired. These structural checks do not verify stack types, token existence, method signatures, exception regions, or branch entry boundaries.

Historical and private dialects

Select MonoDialect::July2002, Early2002, May2004, Legacy, or Modern with the builder. Selection is explicit because the same F0 bytes mean different operations. Early maps include additions made before their next renumbering; Legacy uses the post-2004 map with the pre-July-2019 F01B getter. It retains the current map's additive opcodes and retired attach/detach descriptors; it is a disassembly superset, rather than a particular runtime's executable instruction set.

use fNET::{Code, Decoder, DecoderOptions, MonoDialect};
let bytes = [0xf0, 1, 255];
let instruction = Decoder::new(&bytes, 0, DecoderOptions::NONE)
    .with_mono_dialect(MonoDialect::May2004).decode();
assert_eq!(instruction.code(), Code::MonoFunc2);
assert_eq!(instruction.immediate_u8(), Some(255));
assert_eq!(instruction.encoding(), 0xf001);

Use Instruction::encoding() and op_code() for the selected dialect's exact encoding and metadata. Code::value() is an operation ID (early-only and getter IDs use E100..E105); Code::op_code() gives the default descriptor, and Code::from_encoding() resolves the modern/retired map only.

use fNET::{Decoder, DecoderOptions, ExtensionTable, OpCodeInfo, OperandKind, Operand};
let descriptors = [OpCodeInfo::custom(0xf780, 2, "vendor.blob", OperandKind::ShortInlineData)];
let extensions = ExtensionTable::new(&descriptors).unwrap();
let bytes = [0xf7, 0x80, 2, 0xaa, 0xbb];
let instruction = Decoder::with_extensions(&bytes, 0, DecoderOptions::NONE, extensions).decode();
assert_eq!(instruction.name(), "vendor.blob");
assert_eq!(instruction.operand(), Operand::Bytes(&[0xaa, 0xbb]));

Descriptors and input bytes must outlive decoded instructions. Registration rejects assigned encodings, duplicate entries, and conflicting one/two-byte maps. Two-byte private encodings use F0..FF escapes. A registered escape reinterprets that whole namespace, including a formerly reserved standalone marker. Each descriptor retains its own name, stack effects, and flow; its code is Custom.

Formatting

Instruction and PrefixedInstruction implement Display. FmtFormatter implements the object-safe Formatter trait and writes into any core::fmt::Write sink, including BufSink. Buffer overflow returns fmt::Error and sets overflowed(); previously written UTF-8 remains valid.

FormatterOptions controls address labels, hexadecimal case, integer formatting, and lossless raw float-bit rendering. SymbolResolver optionally supplies names for metadata tokens and branch targets; unresolved operands retain raw values. The alloc feature adds format_to_string. std implies alloc and enables std::error::Error and the CLI example:

cargo run --features std --example disasm -- method-code.bin 0x1000

Validation and development

cargo test
cargo test --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --all -- --check
cargo check --no-default-features --target wasm32-unknown-unknown
cargo check --no-default-features --target armv7a-none-eabi
python tools/generate.py --check

Tests cover all assigned encodings, every unused one-byte/FE/F0 slot and early map, every truncation boundary, branch sign boundaries, float bit preservation, large switches, cursor movement, malformed streams, prefix grouping, formatting, and runtime dialect gates, private maps, and the six-prefix compatibility matrix. Checked-in fixtures compare all Reflection.Emit descriptors and 3,056 actual methods / 66,130 instructions / 40 switches from .NET Framework 2/4 and .NET 5/8/9/10 against an independent .NET decoder. Mono layouts also have literal consumer/emitter regressions. Normal builds and tests need neither Python nor .NET nor network access.

To regenerate the catalogue from the committed source snapshots:

python tools/generate.py
cargo fmt --all

To regenerate the independent fixtures (requires .NET 10 SDK):

dotnet run --project tools/oracle -- tests/data

The oracle also accepts an assembly path and a maximum method count. It stores the producer runtime version and source assembly MVID next to the corpus. Commit regenerated sources and fixtures after reviewing changes.

The dependency-free structured fuzz harness has seed/count replay. It exercises raw and damaged method slices, prefixes, private payloads, all Mono selections, cursor/IP invariants, switch targets, formatting, and truncation:

cargo run --release --example stress -- 1000000 1179534676

Four fixed seeds also run as regression tests. This harness uses deterministic mutation and grammar generation; it is not a coverage-guided fuzzer.

The Rust library is licensed under MIT. Upstream source attribution and reference-material notices are in NOTICE. Source and issue tracking are hosted at valeria-org/fNET. Version history is in CHANGELOG.md; maintainers can follow the release instructions.