diff --git a/LICENSES/GTDGmbH.md b/LICENSES/GTDGmbH.md index a612ad9..120e287 100644 --- a/LICENSES/GTDGmbH.md +++ b/LICENSES/GTDGmbH.md @@ -1,373 +1,24 @@ -Mozilla Public License Version 2.0 -================================== - -1. Definitions --------------- - -1.1. "Contributor" - means each individual or legal entity that creates, contributes to - the creation of, or owns Covered Software. - -1.2. "Contributor Version" - means the combination of the Contributions of others (if any) used - by a Contributor and that particular Contributor's Contribution. - -1.3. "Contribution" - means Covered Software of a particular Contributor. - -1.4. "Covered Software" - means Source Code Form to which the initial Contributor has attached - the notice in Exhibit A, the Executable Form of such Source Code - Form, and Modifications of such Source Code Form, in each case - including portions thereof. - -1.5. "Incompatible With Secondary Licenses" - means - - (a) that the initial Contributor has attached the notice described - in Exhibit B to the Covered Software; or - - (b) that the Covered Software was made available under the terms of - version 1.1 or earlier of the License, but not also under the - terms of a Secondary License. - -1.6. "Executable Form" - means any form of the work other than Source Code Form. - -1.7. "Larger Work" - means a work that combines Covered Software with other material, in - a separate file or files, that is not Covered Software. - -1.8. "License" - means this document. - -1.9. "Licensable" - means having the right to grant, to the maximum extent possible, - whether at the time of the initial grant or subsequently, any and - all of the rights conveyed by this License. - -1.10. "Modifications" - means any of the following: - - (a) any file in Source Code Form that results from an addition to, - deletion from, or modification of the contents of Covered - Software; or - - (b) any new file in Source Code Form that contains any Covered - Software. - -1.11. "Patent Claims" of a Contributor - means any patent claim(s), including without limitation, method, - process, and apparatus claims, in any patent Licensable by such - Contributor that would be infringed, but for the grant of the - License, by the making, using, selling, offering for sale, having - made, import, or transfer of either its Contributions or its - Contributor Version. - -1.12. "Secondary License" - means either the GNU General Public License, Version 2.0, the GNU - Lesser General Public License, Version 2.1, the GNU Affero General - Public License, Version 3.0, or any later versions of those - licenses. - -1.13. "Source Code Form" - means the form of the work preferred for making modifications. - -1.14. "You" (or "Your") - means an individual or a legal entity exercising rights under this - License. For legal entities, "You" includes any entity that - controls, is controlled by, or is under common control with You. For - purposes of this definition, "control" means (a) the power, direct - or indirect, to cause the direction or management of such entity, - whether by contract or otherwise, or (b) ownership of more than - fifty percent (50%) of the outstanding shares or beneficial - ownership of such entity. - -2. License Grants and Conditions --------------------------------- - -2.1. Grants - -Each Contributor hereby grants You a world-wide, royalty-free, -non-exclusive license: - -(a) under intellectual property rights (other than patent or trademark) - Licensable by such Contributor to use, reproduce, make available, - modify, display, perform, distribute, and otherwise exploit its - Contributions, either on an unmodified basis, with Modifications, or - as part of a Larger Work; and - -(b) under Patent Claims of such Contributor to make, use, sell, offer - for sale, have made, import, and otherwise transfer either its - Contributions or its Contributor Version. - -2.2. Effective Date - -The licenses granted in Section 2.1 with respect to any Contribution -become effective for each Contribution on the date the Contributor first -distributes such Contribution. - -2.3. Limitations on Grant Scope - -The licenses granted in this Section 2 are the only rights granted under -this License. No additional rights or licenses will be implied from the -distribution or licensing of Covered Software under this License. -Notwithstanding Section 2.1(b) above, no patent license is granted by a -Contributor: - -(a) for any code that a Contributor has removed from Covered Software; - or - -(b) for infringements caused by: (i) Your and any other third party's - modifications of Covered Software, or (ii) the combination of its - Contributions with other software (except as part of its Contributor - Version); or - -(c) under Patent Claims infringed by Covered Software in the absence of - its Contributions. - -This License does not grant any rights in the trademarks, service marks, -or logos of any Contributor (except as may be necessary to comply with -the notice requirements in Section 3.4). - -2.4. Subsequent Licenses - -No Contributor makes additional grants as a result of Your choice to -distribute the Covered Software under a subsequent version of this -License (see Section 10.2) or under the terms of a Secondary License (if -permitted under the terms of Section 3.3). - -2.5. Representation - -Each Contributor represents that the Contributor believes its -Contributions are its original creation(s) or it has sufficient rights -to grant the rights to its Contributions conveyed by this License. - -2.6. Fair Use - -This License is not intended to limit any rights You have under -applicable copyright doctrines of fair use, fair dealing, or other -equivalents. - -2.7. Conditions - -Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted -in Section 2.1. - -3. Responsibilities -------------------- - -3.1. Distribution of Source Form - -All distribution of Covered Software in Source Code Form, including any -Modifications that You create or to which You contribute, must be under -the terms of this License. You must inform recipients that the Source -Code Form of the Covered Software is governed by the terms of this -License, and how they can obtain a copy of this License. You may not -attempt to alter or restrict the recipients' rights in the Source Code -Form. - -3.2. Distribution of Executable Form - -If You distribute Covered Software in Executable Form then: - -(a) such Covered Software must also be made available in Source Code - Form, as described in Section 3.1, and You must inform recipients of - the Executable Form how they can obtain a copy of such Source Code - Form by reasonable means in a timely manner, at a charge no more - than the cost of distribution to the recipient; and - -(b) You may distribute such Executable Form under the terms of this - License, or sublicense it under different terms, provided that the - license for the Executable Form does not attempt to limit or alter - the recipients' rights in the Source Code Form under this License. - -3.3. Distribution of a Larger Work - -You may create and distribute a Larger Work under terms of Your choice, -provided that You also comply with the requirements of this License for -the Covered Software. If the Larger Work is a combination of Covered -Software with a work governed by one or more Secondary Licenses, and the -Covered Software is not Incompatible With Secondary Licenses, this -License permits You to additionally distribute such Covered Software -under the terms of such Secondary License(s), so that the recipient of -the Larger Work may, at their option, further distribute the Covered -Software under the terms of either this License or such Secondary -License(s). - -3.4. Notices - -You may not remove or alter the substance of any license notices -(including copyright notices, patent notices, disclaimers of warranty, -or limitations of liability) contained within the Source Code Form of -the Covered Software, except that You may alter any license notices to -the extent required to remedy known factual inaccuracies. - -3.5. Application of Additional Terms - -You may choose to offer, and to charge a fee for, warranty, support, -indemnity or liability obligations to one or more recipients of Covered -Software. However, You may do so only on Your own behalf, and not on -behalf of any Contributor. You must make it absolutely clear that any -such warranty, support, indemnity, or liability obligation is offered by -You alone, and You hereby agree to indemnify every Contributor for any -liability incurred by such Contributor as a result of warranty, support, -indemnity or liability terms You offer. You may include additional -disclaimers of warranty and limitations of liability specific to any -jurisdiction. - -4. Inability to Comply Due to Statute or Regulation ---------------------------------------------------- - -If it is impossible for You to comply with any of the terms of this -License with respect to some or all of the Covered Software due to -statute, judicial order, or regulation then You must: (a) comply with -the terms of this License to the maximum extent possible; and (b) -describe the limitations and the code they affect. Such description must -be placed in a text file included with all distributions of the Covered -Software under this License. Except to the extent prohibited by statute -or regulation, such description must be sufficiently detailed for a -recipient of ordinary skill to be able to understand it. - -5. Termination --------------- - -5.1. The rights granted under this License will terminate automatically -if You fail to comply with any of its terms. However, if You become -compliant, then the rights granted under this License from a particular -Contributor are reinstated (a) provisionally, unless and until such -Contributor explicitly and finally terminates Your grants, and (b) on an -ongoing basis, if such Contributor fails to notify You of the -non-compliance by some reasonable means prior to 60 days after You have -come back into compliance. Moreover, Your grants from a particular -Contributor are reinstated on an ongoing basis if such Contributor -notifies You of the non-compliance by some reasonable means, this is the -first time You have received notice of non-compliance with this License -from such Contributor, and You become compliant prior to 30 days after -Your receipt of the notice. - -5.2. If You initiate litigation against any entity by asserting a patent -infringement claim (excluding declaratory judgment actions, -counter-claims, and cross-claims) alleging that a Contributor Version -directly or indirectly infringes any patent, then the rights granted to -You by any and all Contributors for the Covered Software under Section -2.1 of this License shall terminate. - -5.3. In the event of termination under Sections 5.1 or 5.2 above, all -end user license agreements (excluding distributors and resellers) which -have been validly granted by You or Your distributors under this License -prior to termination shall survive termination. - -************************************************************************ -* * -* 6. Disclaimer of Warranty * -* ------------------------- * -* * -* Covered Software is provided under this License on an "as is" * -* basis, without warranty of any kind, either expressed, implied, or * -* statutory, including, without limitation, warranties that the * -* Covered Software is free of defects, merchantable, fit for a * -* particular purpose or non-infringing. The entire risk as to the * -* quality and performance of the Covered Software is with You. * -* Should any Covered Software prove defective in any respect, You * -* (not any Contributor) assume the cost of any necessary servicing, * -* repair, or correction. This disclaimer of warranty constitutes an * -* essential part of this License. No use of any Covered Software is * -* authorized under this License except under this disclaimer. * -* * -************************************************************************ - -************************************************************************ -* * -* 7. Limitation of Liability * -* -------------------------- * -* * -* Under no circumstances and under no legal theory, whether tort * -* (including negligence), contract, or otherwise, shall any * -* Contributor, or anyone who distributes Covered Software as * -* permitted above, be liable to You for any direct, indirect, * -* special, incidental, or consequential damages of any character * -* including, without limitation, damages for lost profits, loss of * -* goodwill, work stoppage, computer failure or malfunction, or any * -* and all other commercial damages or losses, even if such party * -* shall have been informed of the possibility of such damages. This * -* limitation of liability shall not apply to liability for death or * -* personal injury resulting from such party's negligence to the * -* extent applicable law prohibits such limitation. Some * -* jurisdictions do not allow the exclusion or limitation of * -* incidental or consequential damages, so this exclusion and * -* limitation may not apply to You. * -* * -************************************************************************ - -8. Litigation -------------- - -Any litigation relating to this License may be brought only in the -courts of a jurisdiction where the defendant maintains its principal -place of business and such litigation shall be governed by laws of that -jurisdiction, without reference to its conflict-of-law provisions. -Nothing in this Section shall prevent a party's ability to bring -cross-claims or counter-claims. - -9. Miscellaneous ----------------- - -This License represents the complete agreement concerning the subject -matter hereof. If any provision of this License is held to be -unenforceable, such provision shall be reformed only to the extent -necessary to make it enforceable. Any law or regulation which provides -that the language of a contract shall be construed against the drafter -shall not be used to construe this License against a Contributor. - -10. Versions of the License ---------------------------- - -10.1. New Versions - -Mozilla Foundation is the license steward. Except as provided in Section -10.3, no one other than the license steward has the right to modify or -publish new versions of this License. Each version will be given a -distinguishing version number. - -10.2. Effect of New Versions - -You may distribute the Covered Software under the terms of the version -of the License under which You originally received the Covered Software, -or under the terms of any subsequent version published by the license -steward. - -10.3. Modified Versions - -If you create software not governed by this License, and you want to -create a new license for such software, you may create and use a -modified version of this License if you rename the license and remove -any references to the name of the license steward (except to note that -such modified license differs from this License). - -10.4. Distributing Source Code Form that is Incompatible With Secondary -Licenses - -If You choose to distribute Source Code Form that is Incompatible With -Secondary Licenses under the terms of this version of the License, the -notice described in Exhibit B of this License must be attached. - -Exhibit A - Source Code Form License Notice -------------------------------------------- - - This Source Code Form is subject to the terms of the Mozilla Public - License, v. 2.0. If a copy of the MPL was not distributed with this - file, You can obtain one at http://mozilla.org/MPL/2.0/. - -If it is not possible or desirable to put the notice in a particular -file, then You may include the notice in a location (such as a LICENSE -file in a relevant directory) where a recipient would be likely to look -for such a notice. - -You may add additional accurate notices of copyright ownership. - -Exhibit B - "Incompatible With Secondary Licenses" Notice ---------------------------------------------------------- - - This Source Code Form is "Incompatible With Secondary Licenses", as - defined by the Mozilla Public License, v. 2.0. +Valid-License-Identifier: GTDGmbH +License-Text: + +Copyright (c) 2023 GTD GmbH. All rights reserved. + +MIT License + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the “Software”), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index eab295b..2602e52 100644 --- a/README.md +++ b/README.md @@ -1,450 +1,28 @@ -## Object Code Graph (ocgraph) +# Object Code Graph (ocgraph) -## How to Run +This repo contains *asm2cfg*, (**Assembler to control-flow-graph**), a tool to +read disassembler output and optional corresponding coverage data to produce +control flow graphs including coverage analysis on assembler level. -Custom python script: +The *asm2cfg* source code implemented by GTD GmbH is forked from the asm2cfg +repository on [Github](https://github.com/Kazhuu/asm2cfg) and reworked to +function with several architectures and disassembler. -```python -from ocgraph.interface.analyzer import Analyzer -from ocgraph.interface.drawer import Drawer -from ocgraph.interface.coverage_reader import CoverageReader +The tool source code is subject to the MIT License as indicated by the headers +of the corresponding source code files. -from ocgraph.coverage_tracer import CoverageTracer -from ocgraph.configuration.configuration import CovTraceConfiguration +[!WARNING] +> **WARNING**: +> +> **This tool is currently under development and in beta state It's not intended +> to be complete and using is on your own risk.** -# Create configuration -config = OcGraphConfiguration(disassembler="objdump", arch="sparc") +## Documentation -# Read input text -lines = read_lines("a.out") +Due to the lack of a full documentation, all previous information can be found +in separate *Markdown* files in the *doc* folder: -# Analyze input text -analyser = Analyzer(config=config) -analyser.parse_lines(lines=lines) - -# Update analyzed input with coverage data -cov_reader = CoverageReader(instructions=analyser.instructions config=config) -cov_reader.update_by_csv(args.coverage) - -drawer = Drawer(analyser.configuration) -drawer.draw_cfg(name=analyser.function_name, basic_blocks=analyser.basic_blocks, output="a.pdf") -``` - -As python module: - -```cmd -python3 -m ocgraph -f a.out -d objdump -a sparc -c cov.csv -o a.pdf -``` - -As command line script: - -```cmd -./asm2cfg -f a.out -d objdump -a sparc -c cov.csv -o a.pdf -``` - - -## Design - - -```mermaid ---- -title: OcGraph design ---- -classDiagram - - class Configuration { - __init__(arch, disassembler, logging): - +dict disassembler_option - +dict architecture_option - +dict preset_logging - } - class Disassembler { - Name - parse_line() - ...() - } - class Architecture { - is_branch() - ...() - } - class Logger { Name } - - Configuration --* Disassembler - Configuration --* Architecture - Configuration --* Logger - - class Analyzer { - __init__(config) - parse_file(file_path): basic_blocks - } - class CoverageReader { - __init__(basic_blocks, config) - update_by_csv(file_path) - } - class Drawer { - __init__(config) - draw_cfg(basic_blocks, output) - } - class __main__ { - main() - } - - __main__ --> Configuration - __main__ --> Analyzer - __main__ --> CoverageReader - __main__ --> Drawer - -``` - -# asm2cfg -![CI status](https://github.com/Kazhuu/asm2cfg/actions/workflows/ci.yml/badge.svg) -[![codecov](https://codecov.io/gh/Kazhuu/asm2cfg/branch/main/graph/badge.svg?token=ZHLOJO8Q3V)](https://codecov.io/gh/Kazhuu/asm2cfg) - -Python 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 -use `viewcfg` command to view CFG and use `savecfg` command 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, check -[Development](#development) how to get started. - -## Table of Content - - - -* [Install](#install) -* [Usage From GDB](#usage-from-gdb) -* [Usage as Standalone](#usage-as-standalone) - * [Knowing Function Name](#knowing-function-name) - * [Disassemble Function](#disassemble-function) - * [Draw CFG](#draw-cfg) - * [Examples](#examples) -* [Development](#development) - * [Python Environment](#python-environment) - * [Testing](#testing) - * [Code Linting](#code-linting) - * [Command-Line Interface](#command-line-interface) - * [GDB Integration](#gdb-integration) - * [Current Development Goals](#current-development-goals) - - - -## Install - -Project can be installed with pip - -``` -pip install asm2cfg -``` - -To be able to view the dot files from GDB. External dot viewer is required. For -this purpose [xdot](https://pypi.org/project/xdot/) can be used for example. Any -other dot viewer will also do. To install this on Debian based distro run - -``` -sudo apt install xdot -``` - -Or Arch based - -``` -sudo pacman -S xdot -``` - -To add extension to GDB you need to source the pip installed plugin to it. To -find where pip placed GDB extension run `which gdb_asm2cfg` or in case if you -use pyenv use `pyenv which gdb_asm2cfg`. Copy the path to the clipboard. - -Then in you home directory if not already add `.gdbinit` file -and place following line in it and replace path from the earlier step. - -``` -source -``` - -For example in my Linux machine line end up to be - -``` -source ~/.local/bin/gdb_asm2cfg.py -``` - -Now when you start GDB no errors should be displayed and you are ready to go. - -## Usage From GDB - -In GDB session this extension provides command `viewcfg` to view CFG with -external dot viewer. Command `savecfg` saves 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 use `help` command like `help viewcfg`. - -For example let's view main function from you favorite non-stripped executable. -First run GDB until main function - -``` -gdb -ex 'b main' -ex 'run' -``` - -Now run `viewcfg` to view CFG as a dot graph with external editor. Or run `savecfg` -to save CFG to pdf file named `main.pdf` to current working directory. If -function is stripped then memory address of the function will used as a name -instead. For example `0x555555555faf-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 run `set -skipcalls on` and 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 run `set skipcalls off`. - -## Usage as Standalone - -This method can be used with assembly files saved from ouput of objdump and GDB -disassembly. Pip installation will come with `asm2cfg` command-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 Name - -If 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_executable -``` - -This will set breakpoint at function `main`, 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 do - -``` -gdb -batch -ex 'info functions' ./test_executable -``` - -If you want to narrow the search down you can also use regexp - -``` -gdb ... -ex 'info functions ' ... -``` - -### Disassemble Function - -Once you have the function name, you can produce its disassembly via - -``` -gdb -batch -ex 'b main' -ex r -ex 'pipe disassemble test_function | tee test_function.asm' ./test_executable -``` - -or - -``` -gdb -batch -ex 'set breakpoints pending on' -ex 'b test_function' -ex r -ex 'pipe disassemble | tee test_function.asm' ./test_executable -``` - -(the `set breakpoint pending on` command enables pending breakpoints and -could be added to your `.gdbinit` instead) - -For functions from main executable it's enough to do - -``` -gdb -batch -ex 'pipe disassemble test_function | tee test_function.asm' ./test_executable -``` - -You can also extract function's disassembly from `objdump` output: - -``` -objdump -d ./test_executable | sed -ne '/ test_executable.asm -``` - -(this may be useful for specific non-native targets which lack GDB support). - -### Draw CFG - -Now you have the assembly file. Time to turn that to CFG pdf file. Do that by giving it -to `asm2cfg` command-line tool like so - -``` -asm2cfg test_function.asm -``` - -Asm2cfg by default expects x86 assembly files. If you want to use ARM assembly files, -then provide `--target arm` command-line flag. - -Above command should output `test_function.pdf` file 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 example -`0x555555555faf-0x555555557008.pdf`. - -To view CFG instead of saving provide `-v` flag. And to skip function calls from -splitting the code to further blocks provide `-c` flag. To show the help use -`-h`. - -### Examples - -Repository includes examples which can be used to test the standalone -functionality for x86, ARM and objdump. - -File `test_function.asm` is non-stripped assembly file and its -corresponding output `test_function.pdf`. - -File `stripped_function.asm` contains -stripped function and its corresponding output -`stripped_function.pdf`. - -File `att_syntax.asm` is an example of non-stripped AT&T assembly. - -File `huge.asm` is a large stripped -assembly function and its corresponding output `huge.pdf`. This can be used to -test processing time of big functions. - -Files `objdump.asm` and `stripped_objdump.asm` are the regular and stripped -objdump-based disassemblies of short functions. - -File `arm.asm` is ARM based assembly file and its corresponding pdf file is -`arm.pdf`. - -## Development - -You 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 Environment - -For 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 guide -[here](https://pipenv.pypa.io/en/latest/). - -After installing pipenv. Create virtual environment and install all required -packages to it. Run following at project root - -``` -pipenv install -d -``` - -Now you can activate the virtual environment with - -``` -pipenv shell -``` - -Now your `python` and `pip` commands will correspond to created virtual environment -instead of your system's Python installation. - -To deactivate the environment, use - -``` -exit -``` - -### Testing - -This project uses [pytest](https://pypi.org/project/pytest/) for 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, use `pytest` or - -``` -pipenv run pytest -``` - -During testing dot viewer might be opened if you have it installed. This is -because GDB integration command `viewcfg` is tested, which will open external -dot viewer. Just close it after it's opened. It should not affect the test run -itself. - -### Code Linting - -Project uses [flake8](https://flake8.pycqa.org/en/latest/) and -[pylint](https://pylint.org/) for code linting. - -To run flake8, use - -``` -flake8 -``` - -And to run pylint use - -``` -pylint src test -``` - -Both commands should not print any errors. - -### Command-Line Interface - -To test command-line interface of asm2cfg wihtout installing the package. You -can execute module directly. For example to print help - -``` -python -m src.asm2cfg -h -``` - -Standalone method can be used to try out the examples under `examples` folder as -well. For example following command should generate `main.pdf` file to current -working directory. - -``` -python -m src.asm2cfg -c examples/huge.asm -``` - -### GDB Integration - -Before 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 GDB - -``` -ModuleNotFoundError: 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 graphviz -``` - -To 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 -commands `viewcfg` and `savecfg`. - -### Current Development Goals - -There 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 name -`Kazhuu#3121`. +1. [Installation](doc/1_Installation.md): Instructions to install the tool +2. [How to Run](doc/2_HowToRun.md): Guideline to run the tool +3. [Development](doc/3_Development.md): Information for Developer +4. [Github asm2cfg](doc/3_Development.md): Original Github documentation diff --git a/doc/1_Installation.md b/doc/1_Installation.md new file mode 100644 index 0000000..1e90e8b --- /dev/null +++ b/doc/1_Installation.md @@ -0,0 +1,7 @@ +# Installation + +## Dependencies for *asm2cfg* + +- Python >=3.6 +- The python `graphviz` for printing the graph, please install them e.g. with + `pip`. Preferably use a `virtualenv`. diff --git a/doc/2_HowToRun.md b/doc/2_HowToRun.md new file mode 100644 index 0000000..192c301 --- /dev/null +++ b/doc/2_HowToRun.md @@ -0,0 +1,41 @@ +# How to Run + +## As python module + +```cmd +python3 -m ocgraph -f a.out -d objdump -a sparc -c cov.csv -o a.pdf +``` + +## As command line script + +```cmd +./asm2cfg -f a.out -d objdump -a sparc -c cov.csv -o a.pdf +``` + +## Custom python script + +```python +from ocgraph.interface.analyzer import Analyzer +from ocgraph.interface.drawer import Drawer +from ocgraph.interface.coverage_reader import CoverageReader + +from ocgraph.coverage_tracer import CoverageTracer +from ocgraph.configuration.configuration import CovTraceConfiguration + +# Create configuration +config = OcGraphConfiguration(disassembler="objdump", arch="sparc") + +# Read input text +lines = read_lines("a.out") + +# Analyze input text +analyser = Analyzer(config=config) +analyser.parse_lines(lines=lines) + +# Update analyzed input with coverage data +cov_reader = CoverageReader(instructions=analyser.instructions config=config) +cov_reader.update_by_csv(args.coverage) + +drawer = Drawer(analyser.configuration) +drawer.draw_cfg(name=analyser.function_name, basic_blocks=analyser.basic_blocks, output="a.pdf") +``` diff --git a/doc/3_Development.md b/doc/3_Development.md new file mode 100644 index 0000000..e1cf37a --- /dev/null +++ b/doc/3_Development.md @@ -0,0 +1,53 @@ +# Development + +## Design + +```mermaid +--- +title: OcGraph design +--- +classDiagram + + class Configuration { + __init__(arch, disassembler, logging): + +dict disassembler_option + +dict architecture_option + +dict preset_logging + } + class Disassembler { + Name + parse_line() + ...() + } + class Architecture { + is_branch() + ...() + } + class Logger { Name } + + Configuration --* Disassembler + Configuration --* Architecture + Configuration --* Logger + + class Analyzer { + __init__(config) + parse_file(file_path): basic_blocks + } + class CoverageReader { + __init__(basic_blocks, config) + update_by_csv(file_path) + } + class Drawer { + __init__(config) + draw_cfg(basic_blocks, output) + } + class __main__ { + main() + } + + __main__ --> Configuration + __main__ --> Analyzer + __main__ --> CoverageReader + __main__ --> Drawer + +``` diff --git a/doc/4_Github.md b/doc/4_Github.md new file mode 100644 index 0000000..b3a81ff --- /dev/null +++ b/doc/4_Github.md @@ -0,0 +1,354 @@ + +# asm2cfg + +![CI status](https://github.com/Kazhuu/asm2cfg/actions/workflows/ci.yml/badge.svg) +[![codecov](https://codecov.io/gh/Kazhuu/asm2cfg/branch/main/graph/badge.svg?token=ZHLOJO8Q3V)](https://codecov.io/gh/Kazhuu/asm2cfg) + +Python 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 +use `viewcfg` command to view CFG and use `savecfg` command 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, check +[Development](#development) how to get started. + +## Table of Content + + + +* [Install](#install) +* [Usage From GDB](#usage-from-gdb) +* [Usage as Standalone](#usage-as-standalone) + * [Knowing Function Name](#knowing-function-name) + * [Disassemble Function](#disassemble-function) + * [Draw CFG](#draw-cfg) + * [Examples](#examples) +* [Development](#development) + * [Python Environment](#python-environment) + * [Testing](#testing) + * [Code Linting](#code-linting) + * [Command-Line Interface](#command-line-interface) + * [GDB Integration](#gdb-integration) + * [Current Development Goals](#current-development-goals) + + + +## Install + +Project can be installed with pip + +``` +pip install asm2cfg +``` + +To be able to view the dot files from GDB. External dot viewer is required. For +this purpose [xdot](https://pypi.org/project/xdot/) can be used for example. Any +other dot viewer will also do. To install this on Debian based distro run + +``` +sudo apt install xdot +``` + +Or Arch based + +``` +sudo pacman -S xdot +``` + +To add extension to GDB you need to source the pip installed plugin to it. To +find where pip placed GDB extension run `which gdb_asm2cfg` or in case if you +use pyenv use `pyenv which gdb_asm2cfg`. Copy the path to the clipboard. + +Then in you home directory if not already add `.gdbinit` file +and place following line in it and replace path from the earlier step. + +``` +source +``` + +For example in my Linux machine line end up to be + +``` +source ~/.local/bin/gdb_asm2cfg.py +``` + +Now when you start GDB no errors should be displayed and you are ready to go. + +## Usage From GDB + +In GDB session this extension provides command `viewcfg` to view CFG with +external dot viewer. Command `savecfg` saves 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 use `help` command like `help viewcfg`. + +For example let's view main function from you favorite non-stripped executable. +First run GDB until main function + +``` +gdb -ex 'b main' -ex 'run' +``` + +Now run `viewcfg` to view CFG as a dot graph with external editor. Or run `savecfg` +to save CFG to pdf file named `main.pdf` to current working directory. If +function is stripped then memory address of the function will used as a name +instead. For example `0x555555555faf-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 run `set +skipcalls on` and 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 run `set skipcalls off`. + +## Usage as Standalone + +This method can be used with assembly files saved from ouput of objdump and GDB +disassembly. Pip installation will come with `asm2cfg` command-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 Name + +If 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_executable +``` + +This will set breakpoint at function `main`, 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 do + +``` +gdb -batch -ex 'info functions' ./test_executable +``` + +If you want to narrow the search down you can also use regexp + +``` +gdb ... -ex 'info functions ' ... +``` + +### Disassemble Function + +Once you have the function name, you can produce its disassembly via + +``` +gdb -batch -ex 'b main' -ex r -ex 'pipe disassemble test_function | tee test_function.asm' ./test_executable +``` + +or + +``` +gdb -batch -ex 'set breakpoints pending on' -ex 'b test_function' -ex r -ex 'pipe disassemble | tee test_function.asm' ./test_executable +``` + +(the `set breakpoint pending on` command enables pending breakpoints and +could be added to your `.gdbinit` instead) + +For functions from main executable it's enough to do + +``` +gdb -batch -ex 'pipe disassemble test_function | tee test_function.asm' ./test_executable +``` + +You can also extract function's disassembly from `objdump` output: + +``` +objdump -d ./test_executable | sed -ne '/ test_executable.asm +``` + +(this may be useful for specific non-native targets which lack GDB support). + +### Draw CFG + +Now you have the assembly file. Time to turn that to CFG pdf file. Do that by giving it +to `asm2cfg` command-line tool like so + +``` +asm2cfg test_function.asm +``` + +Asm2cfg by default expects x86 assembly files. If you want to use ARM assembly files, +then provide `--target arm` command-line flag. + +Above command should output `test_function.pdf` file 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 example +`0x555555555faf-0x555555557008.pdf`. + +To view CFG instead of saving provide `-v` flag. And to skip function calls from +splitting the code to further blocks provide `-c` flag. To show the help use +`-h`. + +### Examples + +Repository includes examples which can be used to test the standalone +functionality for x86, ARM and objdump. + +File `test_function.asm` is non-stripped assembly file and its +corresponding output `test_function.pdf`. + +File `stripped_function.asm` contains +stripped function and its corresponding output +`stripped_function.pdf`. + +File `att_syntax.asm` is an example of non-stripped AT&T assembly. + +File `huge.asm` is a large stripped +assembly function and its corresponding output `huge.pdf`. This can be used to +test processing time of big functions. + +Files `objdump.asm` and `stripped_objdump.asm` are the regular and stripped +objdump-based disassemblies of short functions. + +File `arm.asm` is ARM based assembly file and its corresponding pdf file is +`arm.pdf`. + +## Development + +You 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 Environment + +For 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 guide +[here](https://pipenv.pypa.io/en/latest/). + +After installing pipenv. Create virtual environment and install all required +packages to it. Run following at project root + +``` +pipenv install -d +``` + +Now you can activate the virtual environment with + +``` +pipenv shell +``` + +Now your `python` and `pip` commands will correspond to created virtual environment +instead of your system's Python installation. + +To deactivate the environment, use + +``` +exit +``` + +### Testing + +This project uses [pytest](https://pypi.org/project/pytest/) for 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, use `pytest` or + +``` +pipenv run pytest +``` + +During testing dot viewer might be opened if you have it installed. This is +because GDB integration command `viewcfg` is tested, which will open external +dot viewer. Just close it after it's opened. It should not affect the test run +itself. + +### Code Linting + +Project uses [flake8](https://flake8.pycqa.org/en/latest/) and +[pylint](https://pylint.org/) for code linting. + +To run flake8, use + +``` +flake8 +``` + +And to run pylint use + +``` +pylint src test +``` + +Both commands should not print any errors. + +### Command-Line Interface + +To test command-line interface of asm2cfg wihtout installing the package. You +can execute module directly. For example to print help + +``` +python -m src.asm2cfg -h +``` + +Standalone method can be used to try out the examples under `examples` folder as +well. For example following command should generate `main.pdf` file to current +working directory. + +``` +python -m src.asm2cfg -c examples/huge.asm +``` + +### GDB Integration + +Before 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 GDB + +``` +ModuleNotFoundError: 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 graphviz +``` + +To 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 +commands `viewcfg` and `savecfg`. + +### Current Development Goals + +There 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 name +`Kazhuu#3121`. diff --git a/ocgraph/__main__.py b/ocgraph/__main__.py index 9a26f63..b53afcb 100755 --- a/ocgraph/__main__.py +++ b/ocgraph/__main__.py @@ -1,4 +1,5 @@ -#!/usr/bin/env python3 +#!/usr/bin/env python +# SPDX-License-Identifier: GTDGmbH """ Let this module be executed from the command line with python -m ocgraph from root of the project diff --git a/ocgraph/configuration/architecture/architecture.py b/ocgraph/configuration/architecture/architecture.py index cbf36ff..511c5a1 100755 --- a/ocgraph/configuration/architecture/architecture.py +++ b/ocgraph/configuration/architecture/architecture.py @@ -1,4 +1,5 @@ -#!/usr/bin/env python3 +#!/usr/bin/env python +# SPDX-License-Identifier: GTDGmbH """Contains all necessary functions for a TargetInfo class.""" from abc import ABC, abstractmethod diff --git a/ocgraph/configuration/architecture/arm.py b/ocgraph/configuration/architecture/arm.py index df6ba6b..920b626 100755 --- a/ocgraph/configuration/architecture/arm.py +++ b/ocgraph/configuration/architecture/arm.py @@ -1,4 +1,5 @@ -#!/usr/bin/env python3 +#!/usr/bin/env python +# SPDX-License-Identifier: GTDGmbH """ Contains instruction info for ARM-compatible targets. """ import re diff --git a/ocgraph/configuration/architecture/ppc.py b/ocgraph/configuration/architecture/ppc.py index 6ec15c3..2551fa1 100755 --- a/ocgraph/configuration/architecture/ppc.py +++ b/ocgraph/configuration/architecture/ppc.py @@ -1,4 +1,5 @@ -#!/usr/bin/env python3 +#!/usr/bin/env python +# SPDX-License-Identifier: GTDGmbH """Contains instruction info for PPC-compatible targets.""" import re diff --git a/ocgraph/configuration/architecture/sparc.py b/ocgraph/configuration/architecture/sparc.py index f99c6ec..807e881 100755 --- a/ocgraph/configuration/architecture/sparc.py +++ b/ocgraph/configuration/architecture/sparc.py @@ -1,4 +1,5 @@ -#!/usr/bin/env python3 +#!/usr/bin/env python +# SPDX-License-Identifier: GTDGmbH """Contains instruction info for Sparc-compatible targets.""" from .architecture import Architecture diff --git a/ocgraph/configuration/architecture/x86.py b/ocgraph/configuration/architecture/x86.py index ac90e46..fb12212 100755 --- a/ocgraph/configuration/architecture/x86.py +++ b/ocgraph/configuration/architecture/x86.py @@ -1,4 +1,5 @@ -#!/usr/bin/env python3 +#!/usr/bin/env python +# SPDX-License-Identifier: GTDGmbH """Contains instruction info for X86-compatible targets.""" import re diff --git a/ocgraph/configuration/configuration.py b/ocgraph/configuration/configuration.py index 0d6f83b..2a80fcf 100755 --- a/ocgraph/configuration/configuration.py +++ b/ocgraph/configuration/configuration.py @@ -1,6 +1,8 @@ -#!/usr/bin/env python3 +#!/usr/bin/env python +# SPDX-License-Identifier: GTDGmbH """Module for configuration of the ocgraph package.""" -import logging + +from .logger import OcctreLogger, preset_logging from .architecture.architecture import Architecture from .architecture.x86 import X86Architecture @@ -50,26 +52,6 @@ }, } -preset_logging: dict[str, dict] = { - "development": { - "file_log": "debug.log", - "file_level": logging.DEBUG, - "console_log": True, - "console_level": logging.DEBUG, - }, - "module": { - "file_log": None, - "file_level": logging.ERROR, - "console_log": False, - "console_level": logging.ERROR, - }, - "default": { - "file_log": "asm2cfg.log", - "file_level": logging.INFO, - "console_log": True, - "console_level": logging.INFO, - }, -} # fmt: on @@ -92,15 +74,7 @@ def __init__( self.__dict__ = _preset # configure logging - log_config = preset_logging.get(logging_preset) - if log_config["file_log"]: - file_stream: logging.FileHandler = logging.FileHandler(log_config["file_log"]) - file_stream.setLevel(log_config["file_level"]) - self.logger.addHandler(file_stream) - if log_config["console_log"]: - console_stream: logging.StreamHandler = logging.StreamHandler() - console_stream.setLevel(log_config["console_level"]) - self.logger.addHandler(console_stream) + self.logger = OCGraphLogger("OcGraph", logging_preset, "asm2cfg.log") @staticmethod def architectures(): diff --git a/ocgraph/configuration/disassembler/disassembler.py b/ocgraph/configuration/disassembler/disassembler.py index 73822e4..ff118ea 100755 --- a/ocgraph/configuration/disassembler/disassembler.py +++ b/ocgraph/configuration/disassembler/disassembler.py @@ -1,6 +1,4 @@ #!/usr/bin/env python3 -# SPDX-License-Identifier: GTDGmbH -# Copyright 2023 by GTD GmbH. """Class configuring the used disassembler tool.""" from abc import ABC, abstractmethod diff --git a/ocgraph/configuration/logger.py b/ocgraph/configuration/logger.py new file mode 100755 index 0000000..b68874b --- /dev/null +++ b/ocgraph/configuration/logger.py @@ -0,0 +1,47 @@ +#!/usr/bin/env python +# SPDX-License-Identifier: GTDGmbH +# Copyright 2024 by GTD GmbH. +"""Class configuring the OCGraph logging.""" +import logging + +# fmt: off +logging_preset: dict[str, dict] = { + "development": { + "file_log": True, + "file_level": logging.DEBUG, + "console_log": True, + "console_level": logging.DEBUG + }, + + "module": { + "file_log": False, + "file_level": logging.ERROR, + "console_log": False, + "console_level": logging.ERROR + }, + + "default": { + "file_log": True, + "file_level": logging.INFO, + "console_log": True, + "console_level": logging.INFO + }, +} +# fmt: on + + +class OCGraphLogger(logging.Logger): + """Logging mechanism for module""" + + def __init__(self, name: str, preset="default", file=""): + super().__init__(name) + log_config = logging_preset.get(preset) + if log_config["file_log"]: + logging_file = file + ".log" + file_stream: logging.FileHandler = logging.FileHandler(logging_file) + file_stream.setLevel(log_config["file_level"]) + self.addHandler(file_stream) + if log_config["console_log"]: + console_stream: logging.StreamHandler = logging.StreamHandler() + console_stream.setLevel(log_config["console_level"]) + self.addHandler(console_stream) diff --git a/ocgraph/interface/coverage_reader.py b/ocgraph/interface/coverage_reader.py index 561a02b..18dde93 100755 --- a/ocgraph/interface/coverage_reader.py +++ b/ocgraph/interface/coverage_reader.py @@ -1,4 +1,5 @@ -#!/usr/bin/env python3 +#!/usr/bin/env python +# SPDX-License-Identifier: GTDGmbH """Class for read coverage input and update the instruction.""" import ast import csv diff --git a/ocgraph/interface/drawer.py b/ocgraph/interface/drawer.py index 1ae02ff..e2ba199 100755 --- a/ocgraph/interface/drawer.py +++ b/ocgraph/interface/drawer.py @@ -1,4 +1,5 @@ -#!/usr/bin/env python3 +#!/usr/bin/env python +# SPDX-License-Identifier: GTDGmbH """Class for drawing the output.""" import tempfile diff --git a/scripts/batch_objdump.sh b/scripts/batch_objdump.sh index 630b2c9..0c1ff66 100755 --- a/scripts/batch_objdump.sh +++ b/scripts/batch_objdump.sh @@ -1,4 +1,5 @@ -#!/bin/bash +#!/usr/bin/env python +# SPDX-License-Identifier: GTDGmbH function_array=( acos