Package: asm2cfg
asm2cfgPython command-line tool and GDB extension to view and save x86, ARM and objdump
assembly files as control-flow graph (CFG) pdf files. From GDB debugging session
useviewcfgcommand to view CFG and usesavecfgcommand to save it to the
pdf file.Program has been developed to support X86, ARM and objdump assembly outputs.
Program is mostly tested with x86 assembly. ARM and objdump formats might not be
fully supported. If you have any suggestions or find bugs, please open an issue
or create a pull request. If you want to contribute, checkDevelopmenthow to get started.Table of ContentInstallUsage From GDBUsage as StandaloneKnowing Function NameDisassemble FunctionDraw CFGExamplesDevelopmentPython EnvironmentTestingCode LintingCommand-Line InterfaceGDB IntegrationCurrent Development GoalsInstallProject can be installed with pippip install asm2cfgTo be able to view the dot files from GDB. External dot viewer is required. For
this purposexdotcan be used for example. Any
other dot viewer will also do. To install this on Debian based distro runsudo apt install xdotOr Arch basedsudo pacman -S xdotTo add extension to GDB you need to source the pip installed plugin to it. To
find where pip placed GDB extension runwhich gdb_asm2cfgor in case if you
use pyenv usepyenv which gdb_asm2cfg. Copy the path to the clipboard.Then in you home directory if not already add.gdbinitfile
and place following line in it and replace path from the earlier step.source <path-from-earlier>For example in my Linux machine line end up to besource ~/.local/bin/gdb_asm2cfg.pyNow when you start GDB no errors should be displayed and you are ready to go.Usage From GDBIn GDB session this extension provides commandviewcfgto view CFG with
external dot viewer. Commandsavecfgsaves the CFG to pdf file to current
working directory with same name as the function being dumped. Both commands
disassemble the current execution frame/function when the command is issued. To
see help for these commands usehelpcommand likehelp viewcfg.For example let's view main function from you favorite non-stripped executable.
First run GDB until main functiongdb -ex 'b main' -ex 'run' <executable>Now runviewcfgto view CFG as a dot graph with external editor. Or runsavecfgto save CFG to pdf file namedmain.pdfto current working directory. If
function is stripped then memory address of the function will used as a name
instead. For example0x555555555faf-0x555555557008.pdf.If assembly function is very large with a lot of jumps and calls to other
functions. Then rendering the CFG can take a long time. So be patient or cancel
rendering with Ctrl-C. To make the rendering faster you can skip function calls
instructions from splitting the code to more blocks. To set this runset skipcalls onand then run earlier command again. Note that if function is long
and has a lot of jumps inside itself, then rendering is still gonna take a long
time. To have normal behavior again runset skipcalls off.Usage as StandaloneThis method can be used with assembly files saved from ouput of objdump and GDB
disassembly. Pip installation will come withasm2cfgcommand-line tool for
this purpose.To use as standalone script you first need to dump assembly from GDB or objdump
to the file which is explained below.Knowing Function NameIf you don't know the name of function you're looking for then you can also list
all function names using GDB:gdb -batch -ex 'b main' -ex r -ex 'info functions' ./test_executableThis will set breakpoint at functionmain, then
run the program and print symbols from all loaded libraries.For functions which come from main executable you can avoid running the program
and simply dogdb -batch -ex 'info functions' ./test_executableIf you want to narrow the search down you can also use regexpgdb ... -ex 'info functions <regexp>' ...Disassemble FunctionOnce you have the function name, you can produce its disassembly viagdb -batch -ex 'b main' -ex r -ex 'pipe disassemble test_function | tee test_function.asm' ./test_executableorgdb -batch -ex 'set breakpoints pending on' -ex 'b test_function' -ex r -ex 'pipe disassemble | tee test_function.asm' ./test_executable(theset breakpoint pending oncommand enables pending breakpoints and
could be added to your.gdbinitinstead)For functions from main executable it's enough to dogdb -batch -ex 'pipe disassemble test_function | tee test_function.asm' ./test_executableYou can also extract function's disassembly fromobjdumpoutput:objdump -d ./test_executable | sed -ne '/<test_function/,/^$/p' > test_executable.asm(this may be useful for specific non-native targets which lack GDB support).Draw CFGNow you have the assembly file. Time to turn that to CFG pdf file. Do that by giving it
toasm2cfgcommand-line tool like soasm2cfg test_function.asmAsm2cfg by default expects x86 assembly files. If you want to use ARM assembly files,
then provide--target armcommand-line flag.Above command should outputtest_function.pdffile in the same directory where
the executable was ran. If the assembly file is stripped then the function
memory range is used as a name instead. For example0x555555555faf-0x555555557008.pdf.To view CFG instead of saving provide-vflag. And to skip function calls from
splitting the code to further blocks provide-cflag. To show the help use-h.ExamplesRepository includes examples which can be used to test the standalone
functionality for x86, ARM and objdump.Filetest_function.asmis non-stripped assembly file and its
corresponding outputtest_function.pdf.Filestripped_function.asmcontains
stripped function and its corresponding outputstripped_function.pdf.Fileatt_syntax.asmis an example of non-stripped AT&T assembly.Filehuge.asmis a large stripped
assembly function and its corresponding outputhuge.pdf. This can be used to
test processing time of big functions.Filesobjdump.asmandstripped_objdump.asmare the regular and stripped
objdump-based disassemblies of short functions.Filearm.asmis ARM based assembly file and its corresponding pdf file isarm.pdf.DevelopmentYou want to contribute? You're very welcome to do so! This section will give you
guidance how to setup development environment and test things locally.Python EnvironmentFor development this project manages packages with pipenv. Pipenv is a tool to
manage Python virtual environments and packages with much less pain compared to
normal pip and virtualenv usage.Install pipenv for your system following the guidehere.After installing pipenv. Create virtual environment and install all required
packages to it. Run following at project rootpipenv install -dNow you can activate the virtual environment withpipenv shellNow yourpythonandpipcommands will correspond to created virtual environment
instead of your system's Python installation.To deactivate the environment, useexitTestingThis project usespytestfor testing. Some
test are written using Python's own unittest testing framework, but they work
with pytest out of the box. Pytest style is preferred way to write tests.To run tests from project root, usepytestorpipenv run pytestDuring testing dot viewer might be opened if you have it installed. This is
because GDB integration commandviewcfgis tested, which will open external
dot viewer. Just close it after it's opened. It should not affect the test run
itself.Code LintingProject usesflake8andpylintfor code linting.To run flake8, useflake8And to run pylint usepylint src testBoth commands should not print any errors.Command-Line InterfaceTo test command-line interface of asm2cfg wihtout installing the package. You
can execute module directly. For example to print helppython -m src.asm2cfg -hStandalone method can be used to try out the examples underexamplesfolder as
well. For example following command should generatemain.pdffile to current
working directory.python -m src.asm2cfg -c examples/huge.asmGDB IntegrationBefore testing GDB functionality, make sure asm2cfg is not installed with pip!
This can lead to GDB using code from pip installed asm2cfg package instead of
code from this repository!Also pipenv cannot be used with GDB. You need to install required packages to
your system's Python pip. This is because your installed GDB is linked against
system's Python interpreter and will use it, instead of active virtual
environment. If packages are not installed to your system's pip. You are likely
to receive following error messages when trying to use asm2cfg with GDBModuleNotFoundError: No module named 'graphviz'To fix this, install required packages to your system's pip without active
virtual environment. Currently GDB integration only requires graphviz.pip install graphvizTo use asm2cfg GDB related functionality. Use following line from
project root.PYTHONPATH=${PWD}/src gdb -ex 'source src/gdb_asm2cfg.py'This will set Python import path so that GDB can import code from this
repository without installing the package. After this you should be able to use
commandsviewcfgandsavecfg.Current Development GoalsThere are might be cases asm2cfg will not fully support all x86 or ARM assembly
lines. If you encounter such problems please open an issue.Current developed goals are best described in issues section. Please open a new
one if existing one does not exist.If you want to talk to me, you can contact me at Discord with nameKazhuu#3121.