{"id":19390614,"url":"https://github.com/mandiant/dncil","last_synced_at":"2025-04-06T03:07:05.426Z","repository":{"id":37960208,"uuid":"463670924","full_name":"mandiant/dncil","owner":"mandiant","description":"The FLARE team's open-source library to disassemble Common Intermediate Language (CIL) instructions.","archived":false,"fork":false,"pushed_at":"2023-12-19T18:01:04.000Z","size":151,"stargazers_count":124,"open_issues_count":4,"forks_count":12,"subscribers_count":8,"default_branch":"main","last_synced_at":"2023-12-20T13:06:08.832Z","etag":null,"topics":["gsoc-2023"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mandiant.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-02-25T20:46:22.000Z","updated_at":"2024-01-09T21:40:54.787Z","dependencies_parsed_at":"2023-12-20T08:42:06.624Z","dependency_job_id":"692adf8d-8d38-44ad-9c76-1a8d233d8892","html_url":"https://github.com/mandiant/dncil","commit_stats":{"total_commits":49,"total_committers":3,"mean_commits":"16.333333333333332","dds":0.4285714285714286,"last_synced_commit":"046f4dbb87a60278068ff19d87079c472a468c09"},"previous_names":[],"tags_count":3,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mandiant%2Fdncil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mandiant%2Fdncil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mandiant%2Fdncil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mandiant%2Fdncil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mandiant","download_url":"https://codeload.github.com/mandiant/dncil/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247427006,"owners_count":20937201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gsoc-2023"],"created_at":"2024-11-10T10:22:13.670Z","updated_at":"2025-04-06T03:07:05.406Z","avatar_url":"https://github.com/mandiant.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![dncil](./.github/dncil.png)\n\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/dncil)](https://pypi.org/project/dncil)\n[![Last release](https://img.shields.io/github/v/release/mandiant/dncil)](https://github.com/mandiant/dncil/releases)\n[![CI](https://github.com/mandiant/dncil/actions/workflows/tests.yml/badge.svg)](https://github.com/mandiant/dncil/actions/workflows/tests.yml)\n[![Downloads](https://pepy.tech/badge/dncil)](https://pepy.tech/project/dncil)\n[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE.txt)\n\n`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`.\n\nWhy `Python`? Existing libraries that support `CIL` disassembly, like [`dnLib`](https://github.com/0xd4d/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:\n\n1. Do not need `C#` experience to analyze `CIL` programmatically.\n2. Can quickly develop and test your `CIL` analysis tools.\n3. Can easily integrate your `CIL` analysis tools with existing `Python` projects.\n\n## Example\n\nThe example script [`print_cil_from_dn_file.py`](scripts/print_cil_from_dn_file.py) uses `dncil` together with `.NET` analysis library [`dnfile`](https://github.com/malwarefrank/dnfile) to disassemble the managed methods found in a `.NET` executable. Let's see what it can do.\n\nFirst, we compile the following `C#` source code:\n\n```C#\nusing System;\t\n\npublic class HelloWorld\n{\n    public static void Main(string[] args)\n    {\n        Console.WriteLine (\"Hello World!\");\n    }\n}\n```\n\nCompilation 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.\n\nLet's see the above in action:\n\n```\n$ python scripts/print_cil_from_dn_file.py hello-world.exe \n\nMethod: Main\n0000    00                  nop            \n0001    72 01 00 00 70      ldstr          \"Hello World!\"\n0006    28 04 00 00 0a      call           System.Console::WriteLine\n000B    00                  nop            \n000C    2a                  ret            \n```\n\nOur method `Main` is represented by the [`CilMethodBody`](dncil/cil/body/__init__.py) 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:\n\n```Python\n\u003e  main_method_body.flags\nSmallFormat  :  false\nTinyFormat   :  false\nFatFormat    :  false\nTinyFormat1  :  true\nMoreSects    :  false\nInitLocals   :  false\nCompressedIL :  false\n\u003e  main_method_body.size\n14\n\u003e  hexdump.hexdump(main_method_body.get_bytes())\n00000000: 36 00 72 01 00 00 70 28  04 00 00 0A 00 2A        6.r...p(.....*\n\u003e  hexdump.hexdump(main_method_body.get_header_bytes())\n00000000: 36                                                6\n\u003e  hexdump.hexdump(main_method_body.get_instruction_bytes())\n00000000: 00 72 01 00 00 70 28 04  00 00 0A 00 2A           .r...p(.....*\n```\n\nEach `CIL` instruction found in our managed method `Main` is represented by the [`Instruction`](dncil/cil/instruction.py) class. This class holds data that includes the offset, mnemonic, opcode, and operand of a given `CIL` instruction. It also exposes various helper functions:\n\n```Python\n\u003e  len(main_method_body.instructions)\n5\n\u003e  insn = main_method_body.instructions[1]\n\u003e  insn.offset\n1\n\u003e  insn.mnemonic\n'ldstr'\n\u003e  insn.operand\ntoken(0x70000001)\n\u003e  insn.is_ldstr()\nTrue\n\u003e  insn.size\n5\n\u003e  hexdump.hexdump(insn.get_bytes())\n00000000: 72 01 00 00 70                                    r...p\n\u003e  hexdump.hexdump(insn.get_opcode_bytes())\n00000000: 72                                                r\n\u003e  hexdump.hexdump(insn.get_operand_bytes())\n00000000: 01 00 00 70                                       ...p\n```\n\n## Installing\n\nTo install `dncil` use `pip` to fetch the `dncil` module:\n\n```\n$ pip install dncil\n```\n\nTo execute the example scripts be sure to install [`dnfile`](https://github.com/malwarefrank/dnfile). Alternatively, install `dncil` with the development dependencies as described in the `Development` section below.\n\nSee [print_cil_from_bytes.py](scripts/print_cil_from_bytes.py) for a quick example of using `dncil`to print the `CIL` instructions found in a byte stream containing a `.NET` managed method.\n\n## Development\n\nIf you'd like to review and modify `dncil` source code, you'll need to download it from GitHub and install it locally. \n\nUse the following command to install `dncil` locally with development dependencies:\n\n```\n$ pip install /local/path/to/src[dev]\n```\n\nYou'll need `dncil`'s development dependencies to run tests and linting as described below.\n\n### Testing\n\nUse the following command to run tests:\n\n```\n$ pytest /local/path/to/src/tests\n```\n\n### Linting\n\nUse the following commands to identify format errors:\n\n```\n$ black -l 120 -c /local/path/to/src\n$ isort --profile black --length-sort --line-width 120 -c /local/path/to/src\n$ 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/\n```\n\n## Credits\n\n`dncil` is based on the `CIL` parsing code found in [`dnLib`](https://github.com/0xd4d/dnlib).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmandiant%2Fdncil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmandiant%2Fdncil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmandiant%2Fdncil/lists"}