{"id":7189,"library":"dncil","title":"dncil - CIL Disassembler","description":"dncil is an open-source Python library developed by the FLARE team to disassemble Common Intermediate Language (CIL) instructions. It supports parsing the header, instructions, and exception handlers of .NET managed methods, exposing the data through an object-oriented API. The library is currently at version 1.0.2 and receives minor bug fixes and improvements with each release.","status":"active","version":"1.0.2","language":"en","source_language":"en","source_url":"https://www.github.com/mandiant/dncil","tags":["disassembler","cil",".net","reverse-engineering","mandiant","flare"],"install":[{"cmd":"pip install dncil","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Required for parsing .NET executables to extract CIL method bodies. While dncil disassembles raw CIL, dnfile helps obtain it from PE files.","package":"dnfile","optional":true}],"imports":[{"symbol":"CilMethodBody","correct":"from dncil.cil.body import CilMethodBody"},{"symbol":"CilMethodBodyReader","correct":"from dncil.cil.body.reader import CilMethodBodyReader"},{"symbol":"Instruction","correct":"from dncil.cil.instruction import Instruction"},{"symbol":"MethodBodyFormatError","correct":"from dncil.cil.error import MethodBodyFormatError"}],"quickstart":{"code":"from dncil.cil.body import CilMethodBody\nfrom dncil.cil.body.reader import CilMethodBodyReader\nfrom dncil.cil.enums import InstructionPrefix, OpCode\n\n# Example CIL bytes for a simple method that returns 5\n# (e.g., ldarg.0, ret or ldc.i4.5, ret)\n# This is a simplified example; real CIL bytes often come from a PE file.\n# For a full .NET executable, you would typically use `dnfile` to extract method bytes.\nsimple_cil_bytes = bytes([\n    OpCode.LDC_I4_S.value, 0x05, # ldc.i4.s 5\n    OpCode.RET.value             # ret\n])\n\n# Create a reader for the CIL bytes\nreader = CilMethodBodyReader(simple_cil_bytes, 0)\n\n# Parse the method body\ntry:\n    method_body = CilMethodBody(reader)\n    print(f\"Method has {len(method_body.instructions)} instructions:\")\n    for i, insn in enumerate(method_body.instructions):\n        print(f\"  {i:04X} {hex(insn.offset):<8} {insn.opcode.name:<15} {insn.operand}\")\nexcept Exception as e:\n    print(f\"Error disassembling CIL: {e}\")","lang":"python","description":"This quickstart demonstrates how to disassemble a raw byte stream representing a CIL method body. It initializes a `CilMethodBodyReader` with the CIL bytes and then parses a `CilMethodBody` to iterate through its instructions. For parsing CIL from actual .NET executables, the `dnfile` library is commonly used to extract the raw method bytes first."},"warnings":[{"fix":"Update to `dncil >=1.0.1` and ensure your analysis correctly handles signed integers for CIL branch targets and constants.","message":"Prior to `v1.0.1`, `dncil` might have incorrectly read CIL branch targets and 8-, 32-, and 64-bit constants as unsigned integers. `v1.0.1` corrected this behavior to read them as signed integers, aligning with the CIL specification.","severity":"gotcha","affected_versions":"<1.0.1"},{"fix":"Update error handling in your code to specifically catch `dncil.cil.error.MethodBodyFormatError` when processing CIL that might be malformed or invalid.","message":"Starting with `v1.0.2`, `dncil` now explicitly raises `dncil.cil.error.MethodBodyFormatError` when encountering invalid or malformed CIL method bodies. Previously, such conditions might have resulted in generic `Exception`s or undefined behavior.","severity":"breaking","affected_versions":">=1.0.2"},{"fix":"Install `dnfile` (e.g., `pip install dnfile`) to facilitate extraction of CIL method bytes from .NET executable files before passing them to `dncil`.","message":"While `dncil` is capable of disassembling raw CIL bytes, it does not handle parsing the broader .NET Portable Executable (PE) file format. To extract CIL method bodies from .NET executables, you will typically need to use `dncil` in conjunction with a PE parsing library like `dnfile`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify that the input byte stream is indeed a valid CIL method body and that the offset used to initialize `CilMethodBodyReader` is correct. If extracting from a PE file, ensure `dnfile` (or similar) is used correctly.","cause":"The byte stream provided to `CilMethodBodyReader` does not conform to the expected structure of a CIL method body, indicating corrupted data, an incorrect starting offset, or non-CIL input.","error":"dncil.cil.error.MethodBodyFormatError: invalid method body format"},{"fix":"Ensure `dncil` is installed by running `pip install dncil`. If using a virtual environment, confirm it is activated. Check `pip freeze` to see if `dncil` is listed.","cause":"The `dncil` library is either not installed in the current Python environment, or the environment is not correctly configured to locate installed packages.","error":"ModuleNotFoundError: No module named 'dncil.cil.body'"},{"fix":"Consult the `dncil` documentation or source code for the correct API to read data, such as `read()`, `read_u8()`, `read_i32()`, `read_token()`, etc. Ensure method names and arguments match the library's interface.","cause":"An attempt was made to call a method or access an attribute on a `CilMethodBodyReader` object that does not exist or is misspelled, often indicating a misunderstanding of the API.","error":"AttributeError: 'CilMethodBodyReader' object has no attribute 'read_some_data'"}]}