ocgraph 0.3.0__py3-none-any.whl

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/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/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/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/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/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