ocgraph 0.3.0__tar.gz

ocgraph-0.3.0/LICENSES/GTDGmbH.md

@@ -0,0 +1,24 @@
+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.

ocgraph-0.3.0/LICENSES/MauriMustonen.md

@@ -0,0 +1,24 @@
+Valid-License-Identifier: MauriMustonen
+License-Text:
+
+MIT License
+
+Copyright (c) 2021 Mauri Mustonen
+
+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.

ocgraph-0.3.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.3
+Name: ocgraph
+Version: 0.3.0
+Summary: Tool to visualize object code as control flow graph
+License: MIT
+Keywords: Object Code,Control Flow Graph,ECSS Category A,asm2cfg,Coverage
+Author: Mauri Mustonen
+Author-email: kazooiebombchu@gmail.com
+Maintainer: Christoph Weiss
+Maintainer-email: christoph.weiss@gtd-gmbh.de
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: graphviz (>=0.9,<0.10)
+Project-URL: Documentation, https://gtd-gmbh.gitlab.io/beta-software/ocgraph
+Project-URL: Forked from asm2cfg, https://github.com/Kazhuu/asm2cfg
+Project-URL: Homepage, https://gtd-gmbh.de/cat-a
+Project-URL: Repository, https://gitlab.com/gtd-gmbh/beta-software/ocgraph.git
+Description-Content-Type: text/markdown
+
+# Object Code Graph (ocgraph)
+
+This repo contains *ocgraph*, (**Object Code Graph**), a tool to
+read disassembler output and optionally corresponding coverage data to produce
+control flow graphs including coverage analysis on assembler level.
+
+The *ocgraph* 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 disassemblers.
+
+The tool source code is subject to the MIT License as indicated by the headers
+of the corresponding source code files.
+
+[!WARNING]
+> **WARNING**:
+>
+> **This tool is currently under development and in beta state It's not intended
+> to be complete and using it is on your own risk.**
+
+## Documentation
+
+Due to the lack of a full documentation, all previous information can be found
+in separate *Markdown* files in the *doc* folder:
+
+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/4_Github.md): Original GitHub documentation
+

ocgraph-0.3.0/README.md

@@ -0,0 +1,28 @@
+# Object Code Graph (ocgraph)
+
+This repo contains *ocgraph*, (**Object Code Graph**), a tool to
+read disassembler output and optionally corresponding coverage data to produce
+control flow graphs including coverage analysis on assembler level.
+
+The *ocgraph* 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 disassemblers.
+
+The tool source code is subject to the MIT License as indicated by the headers
+of the corresponding source code files.
+
+[!WARNING]
+> **WARNING**:
+>
+> **This tool is currently under development and in beta state It's not intended
+> to be complete and using it is on your own risk.**
+
+## Documentation
+
+Due to the lack of a full documentation, all previous information can be found
+in separate *Markdown* files in the *doc* folder:
+
+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/4_Github.md): Original GitHub documentation

ocgraph-0.3.0/ocgraph/__main__.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: GTDGmbH
+
+"""
+Module entry point for the ocgraph package.
+
+Let this module be executed from the command line with python -m ocgraph from root of the project.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .configuration import OcGraphConfiguration
+from .interface import Analyzer, CoverageReader, Drawer
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Sequence
+
+
+def read_lines(file_path: str) -> list[str]:
+    """Read all lines from the file and return them as a list."""
+    with Path(file_path).open("r", encoding="utf-8-sig") as file:
+        return file.readlines()
+
+
+def parse_args(args: Sequence[str] | None = None) -> argparse.Namespace:
+    """Separate argument parser for testing purposes."""
+    parser = argparse.ArgumentParser(
+        description="Assembly to Control-Flow-Graph rendering.",
+    )
+
+    parser.add_argument(
+        "-f",
+        "--file",
+        help="Disassembled object file",
+        required=True,
+    )
+    parser.add_argument(
+        "-d",
+        "--diss",
+        help="Disassembler option",
+        required=True,
+        choices=OcGraphConfiguration.disassemblers(),
+    )
+    parser.add_argument(
+        "-a",
+        "--arch",
+        help="Architecture option",
+        required=True,
+        choices=OcGraphConfiguration.architectures(),
+    )
+
+    parser.add_argument("-c", "--coverage", help="Coverage file for printing coverage")
+    parser.add_argument("-v", "--view", action="store_true", help="View as a dot graph")
+    parser.add_argument("-o", "--output", help="Target output filename")
+    parser.add_argument(
+        "-l",
+        "--logger",
+        choices=OcGraphConfiguration.loggers(),
+        default="default",
+        help="Logging mechanism preset",
+    )
+    return parser.parse_args(args)
+
+
+def main(args: Sequence[str] | None = None) -> None:
+    """Command-line entry point to the program."""
+    parsed_args = parse_args(args)
+
+    # Create configuration
+    config = OcGraphConfiguration(
+        disassembler=parsed_args.diss,
+        arch=parsed_args.arch,
+        logging_preset=parsed_args.logger,
+    )
+
+    lines = read_lines(parsed_args.file)
+
+    analyser = Analyzer(config=config)
+    analyser.parse_lines(lines=lines)
+
+    if parsed_args.coverage:
+        cov_reader = CoverageReader(instructions=analyser.instructions, config=config)
+        cov_reader.update_by_csv(parsed_args.coverage)
+
+    analyser.analyze()
+
+    drawer = Drawer(analyser.configuration)
+    drawer.draw_cfg(
+        name=analyser.function_name or "",
+        basic_blocks=analyser.basic_blocks,
+        output=parsed_args.output,
+    )

ocgraph-0.3.0/ocgraph/configuration/__init__.py

@@ -0,0 +1,4 @@
+"""The main file of the configuration module."""
+
+from .configuration import OcGraphConfiguration as OcGraphConfiguration
+from .logger import OCGraphLogger as OCGraphLogger

ocgraph-0.3.0/ocgraph/configuration/architecture/__init__.py

@@ -0,0 +1,8 @@
+"""The main file of the architecture module."""
+
+from .architecture import Architecture as Architecture
+from .arm import ArmArchitecture as ArmArchitecture
+from .msp430 import MSP430Architecture as MSP430Architecture
+from .ppc import PpcArchitecture as PpcArchitecture
+from .sparc import SparcArchitecture as SparcArchitecture
+from .x86 import X86Architecture as X86Architecture

ocgraph-0.3.0/ocgraph/configuration/architecture/architecture.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: GTDGmbH
+"""Contains all necessary functions for a TargetInfo class."""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ocgraph.data import Instruction
+
+# Common regexes
+HEX_PATTERN = r"[0-9a-fA-F]+"
+HEX_LONG_PATTERN = r"(?:0x0*)?" + HEX_PATTERN
+
+
+class Architecture(ABC):
+    """TargetInfo Class defining the target specific instruction set characteristics."""
+
+    @abstractmethod
+    def is_call(self, instruction: Instruction) -> bool:
+        """Return if disassembled instruction is a subroutine call."""
+        raise NotImplementedError  # pragma:no cover
+
+    @abstractmethod
+    def is_unconditional_branch(self, instruction: Instruction) -> bool:
+        """Return if disassembled instruction is an unconditional branch."""
+        raise NotImplementedError  # pragma:no cover
+
+    @abstractmethod
+    def get_branch_delay(self, instruction: Instruction) -> int:
+        """Return the branch delay of an instruction."""
+        raise NotImplementedError  # pragma:no cover
+
+    @abstractmethod
+    def is_direct_branch(self, instruction: Instruction) -> bool:
+        """Return true when the given instruction is a direct branch."""
+        raise NotImplementedError  # pragma:no cover
+
+    @abstractmethod
+    def is_branch(self, instruction: Instruction) -> bool:
+        """
+        Return if disassembled instruction is a branch instruction
+        (conditional or unconditional).
+        """
+        raise NotImplementedError  # pragma:no cover
+
+    @abstractmethod
+    def is_sink(self, instruction: Instruction) -> bool:
+        """Return if disassembled instruction serves as sink (e.g. ret)."""
+        raise NotImplementedError  # pragma:no cover
+
+
+class GenericArchitecture(Architecture):
+    """TargetInfo Class defining the target specific instruction set characteristics."""
+
+    def get_branch_delay(self, instruction: Instruction) -> int:
+        """Return the branch delay of an instruction."""
+        return 1
+
+    def is_direct_branch(self, instruction: Instruction) -> bool:
+        """Return true if the given instruction is a direct branch."""
+        return self.is_branch(instruction) and bool(
+            re.search(HEX_LONG_PATTERN, "|".join(instruction.ops)),
+        )

ocgraph-0.3.0/ocgraph/configuration/architecture/arm.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: GTDGmbH
+"""Contains instruction info for ARM-compatible targets."""
+
+import re
+
+from ocgraph.data import Instruction
+
+from .architecture import GenericArchitecture
+
+
+class ArmArchitecture(GenericArchitecture):
+    """ArmArchitecture Class."""
+
+    def is_call(self, instruction: Instruction) -> bool:
+        # Various flavors of call:
+        #   bl 0x19d90 <_IO_vtable_check>
+        # Note that we should be careful to not mix it with conditional
+        # branches like 'ble'.
+        if instruction.opcode:
+            return instruction.opcode.startswith("bl") and instruction.opcode not in (
+                "blt",
+                "ble",
+                "bls",
+            )
+        return False
+
+    def is_branch(self, instruction: Instruction) -> bool:
+        if instruction.opcode:
+            return instruction.opcode[0] == "b" and not self.is_call(instruction)
+        return False
+
+    def is_unconditional_branch(self, instruction: Instruction) -> bool:
+        return instruction.opcode == "b"
+
+    def is_sink(self, instruction: Instruction) -> bool:
+        """
+        Is this an instruction which terminates function execution e.g. return?
+        Detect various flavors of return like
+          bx lr
+          pop {r2-r6,pc}
+        Note that we do not consider conditional branches (e.g. 'bxle') to sink.
+        """
+        return (
+            bool(
+                re.search(
+                    r"\bpop\b.*\bpc\b",
+                    f"{instruction.opcode} {','.join(instruction.ops)}" or "",
+                ),
+            )
+            or (instruction.opcode == "bx" and instruction.ops[0] == "lr")
+            or instruction.opcode == "udf"
+        )

ocgraph-0.3.0/ocgraph/configuration/architecture/msp430.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: GTDGmbH
+"""Contains instruction info for MSP430-compatible targets."""
+
+from ocgraph.data import Instruction
+
+from .architecture import GenericArchitecture
+
+msp430_conditional_branches = [
+    "jc",
+    "jhs",
+    "jeq",
+    "jz",
+    "jge",
+    "jl",
+    "jn",
+    "jnc",
+    "jlo",
+    "jne",
+    "jnz",
+]
+
+msp430_unconditional_branches = [
+    "br",
+    "jmp",
+]
+
+
+class MSP430Architecture(GenericArchitecture):
+    """Msp430Architecture Class."""
+
+    def is_call(self, instruction: Instruction) -> bool:
+        if instruction.opcode:
+            return "call" in instruction.opcode
+        return False
+
+    def is_branch(self, instruction: Instruction) -> bool:
+        return instruction.opcode in (msp430_conditional_branches + msp430_unconditional_branches)
+
+    def is_direct_branch(self, instruction: Instruction) -> bool:
+        return self.is_branch(instruction)
+
+    def is_unconditional_branch(self, instruction: Instruction) -> bool:
+        return instruction.opcode in msp430_unconditional_branches
+
+    def is_sink(self, instruction: Instruction) -> bool:
+        if instruction.opcode:
+            return instruction.opcode.startswith("ret")
+        return False