dncil is a Common Intermediate Language (CIL) disassembly library written in Python that supports parsing the header, instructions, and exception handlers of .NET managed methods. Parsed data is exposed through an object-oriented API to help you quickly develop CIL analysis tools using dncil.
Why Python? Existing libraries that support CIL disassembly, like dnLib, are written in C#. To leverage these tools, you must build C# applications which requires C# development experience. Using dncil, a pure Python alternative, you:
- Do not need
C#experience to analyzeCILprogrammatically. - Can quickly develop and test your
CILanalysis tools. - Can easily integrate your
CILanalysis tools with existingPythonprojects.
Example
The example script print_cil_from_dn_file.py uses dncil together with .NET analysis library dnfile to disassemble the managed methods found in a .NET executable. Let's see what it can do.
First, we compile the following C# source code:
using System;
public class HelloWorld
{
public static void Main(string[] args)
{
Console.WriteLine ("Hello World!");
}
}
Compilation results in a PE executable containing .NET metadata which informs the Common Language Runtime (CLR) how to execute our code. We use dnfile to parse this metadata which gives us the offset of our managed method Main. We then use dncil to disassemble and display the CIL instructions stored at this location.
Let's see the above in action:
$ python scripts/print_cil_from_dn_file.py hello-world.exe
Method: Main
0000 00 nop
0001 72 01 00 00 70 ldstr "Hello World!"
0006 28 04 00 00 0a call System.Console::WriteLine
000B 00 nop
000C 2a ret
Our method Main is represented by the CilMethodBody class. This class holds data that includes the header, CIL instructions, and exception handlers of a given managed method. It also exposes various helper functions:
> main_method_body.flags
SmallFormat : false
TinyFormat : false
FatFormat : false
TinyFormat1 : true
MoreSects : false
InitLocals : false
CompressedIL : false
> main_method_body.size
14
> hexdump.hexdump(main_method_body.get_bytes())
00000000: 36 00 72 01 00 00 70 28 04 00 00 0A 00 2A 6.r...p(.....*
> hexdump.hexdump(main_method_body.get_header_bytes())
00000000: 36 6
> hexdump.hexdump(main_method_body.get_instruction_bytes())
00000000: 00 72 01 00 00 70 28 04 00 00 0A 00 2A .r...p(.....*
Each CIL instruction found in our managed method Main is represented by the Instruction class. This class holds data that includes the offset, mnemonic, opcode, and operand of a given CIL instruction. It also exposes various helper functions:
> len(main_method_body.instructions)
5
> insn = main_method_body.instructions[1]
> insn.offset
1
> insn.mnemonic
'ldstr'
> insn.operand
token(0x70000001)
> insn.is_ldstr()
True
> insn.size
5
> hexdump.hexdump(insn.get_bytes())
00000000: 72 01 00 00 70 r...p
> hexdump.hexdump(insn.get_opcode_bytes())
00000000: 72 r
> hexdump.hexdump(insn.get_operand_bytes())
00000000: 01 00 00 70 ...p
Installing
To install dncil use pip to fetch the dncil module:
$ pip install dncil
To execute the example scripts be sure to install dnfile. Alternatively, install dncil with the development dependencies as described in the Development section below.
See print_cil_from_bytes.py for a quick example of using dncilto print the CIL instructions found in a byte stream containing a .NET managed method.
Development
If you'd like to review and modify dncil source code, you'll need to download it from GitHub and install it locally.
Use the following command to install dncil locally with development dependencies:
$ pip install /local/path/to/src[dev]
You'll need dncil's development dependencies to run tests and linting as described below.
Testing
Use the following command to run tests:
$ pytest /local/path/to/src/tests
Linting
Use the following commands to identify format errors:
$ pycodestyle --show-source /local/path/to/src/dncil /local/path/to/src/tests
$ black -l 120 -c /local/path/to/src
$ isort --profile black --length-sort --line-width 120 -c /local/path/to/src
Credits
dncil is based on the CIL parsing code found in dnLib.
262 Nov 25, 2022
4 Jan 04, 2022
1 Feb 08, 2022
123 Dec 22, 2022
1 Dec 14, 2021
1 Feb 10, 2022
20 Aug 06, 2022
6 Jul 25, 2022
13 Sep 27, 2022
7 Jan 03, 2023
106 Dec 19, 2022
1 Dec 31, 2021
475 Jan 01, 2023
12 Aug 16, 2021
1 Jan 06, 2022
1 Dec 01, 2021
307 Jan 01, 2023
12 Apr 19, 2022
0 Aug 31, 2022
16 Nov 03, 2022