dncil

dncil ist eine in Python geschriebene Disassemblierungsbibliothek für die Common Intermediate Language (CIL), die das Parsen des Headers, der Anweisungen und der Exception-Handler von verwalteten .NET-Methoden unterstützt. Die geparsten Daten werden über eine objektorientierte API bereitgestellt, damit du schnell CIL-Analysewerkzeuge mit dncil entwickeln kannst.

Warum Python? Vorhandene Bibliotheken, die CIL-Disassemblierung unterstützen, wie dnLib, sind in C# geschrieben. Um diese Werkzeuge zu nutzen, musst du C#-Anwendungen erstellen, was C#-Entwicklungserfahrung erfordert. Mit dncil, einer reinen Python-Alternative, kannst du:

1. keine C#-Erfahrung benötigen, um CIL programmatisch zu analysieren.
2. deine CIL-Analysewerkzeuge schnell entwickeln und testen.
3. deine CIL-Analysewerkzeuge problemlos in vorhandene Python-Projekte integrieren.

Beispiel

Das Beispielskript print_cil_from_dn_file.py verwendet dncil zusammen mit der .NET-Analysebibliothek dnfile, um die in einer .NET-ausführbaren Datei enthaltenen verwalteten Methoden zu disassemblieren. Schauen wir uns an, was es kann.

Zuerst kompilieren wir den folgenden C#-Quellcode:

using System;	

public class HelloWorld
{
    public static void Main(string[] args)
    {
        Console.WriteLine ("Hello World!");
    }
}

Die Kompilierung ergibt eine ausführbare PE-Datei, die .NET-Metadaten enthält, die der Common Language Runtime (CLR) mitteilen, wie unser Code ausgeführt werden soll. Wir verwenden dnfile, um diese Metadaten zu parsen, was uns den Offset unserer verwalteten Methode Main liefert. Anschließend verwenden wir dncil, um die an dieser Stelle gespeicherten CIL-Anweisungen zu disassemblieren und anzuzeigen.

Sehen wir uns das oben Genannte in Aktion an:

$ 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            

Unsere Methode Main wird durch die Klasse CilMethodBody repräsentiert. Diese Klasse enthält Daten, die den Header, die CIL-Anweisungen und die Exception-Handler einer bestimmten verwalteten Methode umfassen. Sie stellt außerdem verschiedene Hilfsfunktionen bereit:

>  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(.....*

Jede CIL-Anweisung in unserer verwalteten Methode Main wird durch die Klasse Instruction repräsentiert. Diese Klasse enthält Daten, die den Offset, die Mnemonik, den Opcode und den Operanden einer bestimmten CIL-Anweisung umfassen. Sie stellt außerdem verschiedene Hilfsfunktionen bereit:

>  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

Installation

Um dncil zu installieren, rufe das dncil-Modul mit pip ab:

$ pip install dncil

Um die Beispielskripte auszuführen, stelle sicher, dass dnfile installiert ist. Alternativ kannst du dncil mit den Entwicklungskomponenten installieren, wie im Abschnitt Entwicklung unten beschrieben.

Ein kurzes Beispiel zur Verwendung von dncil zum Ausgeben der CIL-Anweisungen, die in einem Bytestrom mit einer verwalteten .NET-Methode enthalten sind, findest du in print_cil_from_bytes.py.

Entwicklung

Wenn du den Quellcode von dncil ansehen und ändern möchtest, musst du ihn von GitHub herunterladen und lokal installieren.

Verwende den folgenden Befehl, um dncil lokal mit den Entwicklungskomponenten zu installieren:

$ pip install /local/path/to/src[dev]

Du benötigst die Entwicklungskomponenten von dncil, um die unten beschriebenen Tests und Linting auszuführen.

Testen

Verwende den folgenden Befehl, um die Tests auszuführen:

$ pytest /local/path/to/src/tests

Linting

Verwende die folgenden Befehle, um Formatfehler zu erkennen:

$ black -l 120 -c /local/path/to/src
$ isort --profile black --length-sort --line-width 120 -c /local/path/to/src
$ mypy --config-file /local/path/to/src/.github/mypy/mypy.ini /local/path/to/src/dncil/ /local/path/to/src/scripts/ /local/path/to/src/tests/

Danksagungen

dncil basiert auf dem CIL-Parsing-Code, der in dnLib zu finden ist.