{"id":18619867,"url":"https://github.com/kazhuu/asm2cfg","last_synced_at":"2025-08-19T07:31:25.888Z","repository":{"id":38388716,"uuid":"336778956","full_name":"Kazhuu/asm2cfg","owner":"Kazhuu","description":"Python command-line tool and GDB extension to view and save x86, ARM and objdump assembly files as control-flow graph (CFG) pdf files","archived":false,"fork":false,"pushed_at":"2024-04-01T13:23:47.000Z","size":3713,"stargazers_count":74,"open_issues_count":10,"forks_count":10,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-18T20:09:12.398Z","etag":null,"topics":["arm","assembly","breakpoint","cfg","control-flow-graphs","disassembler","disassembly","gdb","objdump","x86","x86-64","x86-assembly"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kazhuu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-07T12:16:13.000Z","updated_at":"2024-10-21T18:55:24.000Z","dependencies_parsed_at":"2023-01-24T02:16:47.824Z","dependency_job_id":null,"html_url":"https://github.com/Kazhuu/asm2cfg","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kazhuu%2Fasm2cfg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kazhuu%2Fasm2cfg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kazhuu%2Fasm2cfg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kazhuu%2Fasm2cfg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kazhuu","download_url":"https://codeload.github.com/Kazhuu/asm2cfg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230333847,"owners_count":18210133,"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":["arm","assembly","breakpoint","cfg","control-flow-graphs","disassembler","disassembly","gdb","objdump","x86","x86-64","x86-assembly"],"created_at":"2024-11-07T04:03:39.065Z","updated_at":"2024-12-18T20:09:17.297Z","avatar_url":"https://github.com/Kazhuu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# asm2cfg\n![CI status](https://github.com/Kazhuu/asm2cfg/actions/workflows/ci.yml/badge.svg)\n[![codecov](https://codecov.io/gh/Kazhuu/asm2cfg/branch/main/graph/badge.svg?token=ZHLOJO8Q3V)](https://codecov.io/gh/Kazhuu/asm2cfg)\n\nPython command-line tool and GDB extension to view and save x86, ARM and objdump\nassembly files as control-flow graph (CFG) pdf files. From GDB debugging session\nuse `viewcfg` command to view CFG and use `savecfg` command to save it to the\npdf file.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/Kazhuu/asm2cfg/blob/main/images/example.png?raw=true\" /\u003e\n\u003c/p\u003e\n\nProgram has been developed to support X86, ARM and objdump assembly outputs.\nProgram is mostly tested with x86 assembly. ARM and objdump formats might not be\nfully supported. If you have any suggestions or find bugs, please open an issue\nor create a pull request. If you want to contribute, check\n[Development](#development) how to get started.\n\n## Table of Content\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [Install](#install)\n* [Usage From GDB](#usage-from-gdb)\n* [Usage as Standalone](#usage-as-standalone)\n    * [Knowing Function Name](#knowing-function-name)\n    * [Disassemble Function](#disassemble-function)\n    * [Draw CFG](#draw-cfg)\n    * [Examples](#examples)\n* [Development](#development)\n    * [Python Environment](#python-environment)\n    * [Testing](#testing)\n    * [Code Linting](#code-linting)\n    * [Command-Line Interface](#command-line-interface)\n    * [GDB Integration](#gdb-integration)\n    * [Current Development Goals](#current-development-goals)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n## Install\n\nProject can be installed with pip\n\n```\npip install asm2cfg\n```\n\nTo be able to view the dot files from GDB. External dot viewer is required. For\nthis purpose [xdot](https://pypi.org/project/xdot/) can be used for example. Any\nother dot viewer will also do. To install this on Debian based distro run\n\n```\nsudo apt install xdot\n```\n\nOr Arch based\n\n```\nsudo pacman -S xdot\n```\n\nTo add extension to GDB you need to source the pip installed plugin to it. To\nfind where pip placed GDB extension run `which gdb_asm2cfg` or in case if you\nuse pyenv use `pyenv which gdb_asm2cfg`. Copy the path to the clipboard.\n\nThen in you home directory if not already add `.gdbinit` file\nand place following line in it and replace path from the earlier step.\n\n```\nsource \u003cpath-from-earlier\u003e\n```\n\nFor example in my Linux machine line end up to be\n\n```\nsource ~/.local/bin/gdb_asm2cfg.py\n```\n\nNow when you start GDB no errors should be displayed and you are ready to go.\n\n## Usage From GDB\n\nIn GDB session this extension provides command `viewcfg` to view CFG with\nexternal dot viewer. Command `savecfg` saves the CFG to pdf file to current\nworking directory with same name as the function being dumped. Both commands\ndisassemble the current execution frame/function when the command is issued. To\nsee help for these commands use `help` command like `help viewcfg`.\n\nFor example let's view main function from you favorite non-stripped executable.\nFirst run GDB until main function\n\n```\ngdb -ex 'b main' -ex 'run' \u003cexecutable\u003e\n```\n\nNow run `viewcfg` to view CFG as a dot graph with external editor. Or run `savecfg`\nto save CFG to pdf file named `main.pdf` to current working directory. If\nfunction is stripped then memory address of the function will used as a name\ninstead. For example `0x555555555faf-0x555555557008.pdf`.\n\nIf assembly function is very large with a lot of jumps and calls to other\nfunctions. Then rendering the CFG can take a long time. So be patient or cancel\nrendering with Ctrl-C. To make the rendering faster you can skip function calls\ninstructions from splitting the code to more blocks. To set this run `set\nskipcalls on` and then run earlier command again. Note that if function is long\nand has a lot of jumps inside itself, then rendering is still gonna take a long\ntime. To have normal behavior again run `set skipcalls off`.\n\n## Usage as Standalone\n\nThis method can be used with assembly files saved from ouput of objdump and GDB\ndisassembly. Pip installation will come with `asm2cfg` command-line tool for\nthis purpose.\n\nTo use as standalone script you first need to dump assembly from GDB or objdump\nto the file which is explained below.\n\n### Knowing Function Name\n\nIf you don't know the name of function you're looking for then you can also list\nall function names using GDB:\n\n```\ngdb -batch -ex 'b main' -ex r -ex 'info functions' ./test_executable\n```\n\nThis will set breakpoint at function `main`, then\nrun the program and print symbols from all loaded libraries.\n\nFor functions which come from main executable you can avoid running the program\nand simply do\n\n```\ngdb -batch -ex 'info functions' ./test_executable\n```\n\nIf you want to narrow the search down you can also use regexp\n\n```\ngdb ... -ex 'info functions \u003cregexp\u003e' ...\n```\n\n### Disassemble Function\n\nOnce you have the function name, you can produce its disassembly via\n\n```\ngdb -batch -ex 'b main' -ex r -ex 'pipe disassemble test_function | tee test_function.asm' ./test_executable\n```\n\nor\n\n```\ngdb -batch -ex 'set breakpoints pending on' -ex 'b test_function' -ex r -ex 'pipe disassemble | tee test_function.asm' ./test_executable\n```\n\n(the `set breakpoint pending on` command enables pending breakpoints and\ncould be added to your `.gdbinit` instead)\n\nFor functions from main executable it's enough to do\n\n```\ngdb -batch -ex 'pipe disassemble test_function | tee test_function.asm' ./test_executable\n```\n\nYou can also extract function's disassembly from `objdump` output:\n\n```\nobjdump -d ./test_executable | sed -ne '/\u003ctest_function/,/^$/p' \u003e test_executable.asm\n```\n\n(this may be useful for specific non-native targets which lack GDB support).\n\n### Draw CFG\n\nNow you have the assembly file. Time to turn that to CFG pdf file. Do that by giving it\nto `asm2cfg` command-line tool like so\n\n```\nasm2cfg test_function.asm\n```\n\nAsm2cfg by default expects x86 assembly files. If you want to use ARM assembly files,\nthen provide `--target arm` command-line flag.\n\nAbove command should output `test_function.pdf` file in the same directory where\nthe executable was ran. If the assembly file is stripped then the function\nmemory range is used as a name instead. For example\n`0x555555555faf-0x555555557008.pdf`.\n\nTo view CFG instead of saving provide `-v` flag. And to skip function calls from\nsplitting the code to further blocks provide `-c` flag. To show the help use\n`-h`.\n\n### Examples\n\nRepository includes examples which can be used to test the standalone\nfunctionality for x86, ARM and objdump.\n\nFile `test_function.asm` is non-stripped assembly file and its\ncorresponding output `test_function.pdf`.\n\nFile `stripped_function.asm` contains\nstripped function and its corresponding output\n`stripped_function.pdf`.\n\nFile `att_syntax.asm` is an example of non-stripped AT\u0026T assembly.\n\nFile `huge.asm` is a large stripped\nassembly function and its corresponding output `huge.pdf`. This can be used to\ntest processing time of big functions.\n\nFiles `objdump.asm` and `stripped_objdump.asm` are the regular and stripped\nobjdump-based disassemblies of short functions.\n\nFile `arm.asm` is ARM based assembly file and its corresponding pdf file is\n`arm.pdf`.\n\n## Development\n\nYou want to contribute? You're very welcome to do so! This section will give you\nguidance how to setup development environment and test things locally.\n\n### Python Environment\n\nFor development this project manages packages with pipenv. Pipenv is a tool to\nmanage Python virtual environments and packages with much less pain compared to\nnormal pip and virtualenv usage.\n\nInstall pipenv for your system following the guide\n[here](https://pipenv.pypa.io/en/latest/).\n\nAfter installing pipenv. Create virtual environment and install all required\npackages to it. Run following at project root\n\n```\npipenv install -d\n```\n\nNow you can activate the virtual environment with\n\n```\npipenv shell\n```\n\nNow your `python` and `pip` commands will correspond to created virtual environment\ninstead of your system's Python installation.\n\nTo deactivate the environment, use\n\n```\nexit\n```\n\n### Testing\n\nThis project uses [pytest](https://pypi.org/project/pytest/) for testing. Some\ntest are written using Python's own unittest testing framework, but they work\nwith pytest out of the box. Pytest style is preferred way to write tests.\n\nTo run tests from project root, use `pytest` or\n\n```\npipenv run pytest\n```\n\nDuring testing dot viewer might be opened if you have it installed. This is\nbecause GDB integration command `viewcfg` is tested, which will open external\ndot viewer. Just close it after it's opened. It should not affect the test run\nitself.\n\n### Code Linting\n\nProject uses [flake8](https://flake8.pycqa.org/en/latest/) and\n[pylint](https://pylint.org/) for code linting.\n\nTo run flake8, use\n\n```\nflake8\n```\n\nAnd to run pylint use\n\n```\npylint src test\n```\n\nBoth commands should not print any errors.\n\n### Command-Line Interface\n\nTo test command-line interface of asm2cfg wihtout installing the package. You\ncan execute module directly. For example to print help\n\n```\npython -m src.asm2cfg -h\n```\n\nStandalone method can be used to try out the examples under `examples` folder as\nwell. For example following command should generate `main.pdf` file to current\nworking directory.\n\n```\npython -m src.asm2cfg -c examples/huge.asm\n```\n\n### GDB Integration\n\nBefore testing GDB functionality, make sure asm2cfg is not installed with pip!\nThis can lead to GDB using code from pip installed asm2cfg package instead of\ncode from this repository!\n\nAlso pipenv cannot be used with GDB. You need to install required packages to\nyour system's Python pip. This is because your installed GDB is linked against\nsystem's Python interpreter and will use it, instead of active virtual\nenvironment. If packages are not installed to your system's pip. You are likely\nto receive following error messages when trying to use asm2cfg with GDB\n\n```\nModuleNotFoundError: No module named 'graphviz'\n```\n\nTo fix this, install required packages to your system's pip without active\nvirtual environment. Currently GDB integration only requires graphviz.\n\n```\npip install graphviz\n```\n\nTo use asm2cfg GDB related functionality. Use following line from\nproject root.\n\n```\nPYTHONPATH=${PWD}/src gdb -ex 'source src/gdb_asm2cfg.py'\n```\n\nThis will set Python import path so that GDB can import code from this\nrepository without installing the package. After this you should be able to use\ncommands `viewcfg` and `savecfg`.\n\n### Current Development Goals\n\nThere are might be cases asm2cfg will not fully support all x86 or ARM assembly\nlines. If you encounter such problems please open an issue.\n\nCurrent developed goals are best described in issues section. Please open a new\none if existing one does not exist.\n\nIf you want to talk to me, you can contact me at Discord with name\n`Kazhuu#3121`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkazhuu%2Fasm2cfg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkazhuu%2Fasm2cfg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkazhuu%2Fasm2cfg/lists"}