smallworld-re 1.0.0__py3-none-any.whl

smallworld/instructions/instructions.py

@@ -0,0 +1,258 @@
+import abc
+import logging
+import typing
+
+import capstone
+
+from .. import emulators, utils
+
+logger = logging.getLogger(__name__)
+
+
+class Operand(metaclass=abc.ABCMeta):
+    """An operand from an instruction."""
+
+    @abc.abstractmethod
+    def key(self, emulator: emulators.Emulator):
+        """Provide a unique key for this reference.
+
+        Arguments:
+            emulator: An emulator from which to fetch a value.
+
+        Returns:
+            A key value used to reference this operand.
+        """
+
+        pass
+
+    @abc.abstractmethod
+    def concretize(
+        self, emulator: emulators.Emulator
+    ) -> typing.Optional[typing.Union[int, bytes]]:
+        """Compute a concrete value for this operand, using an emulator.
+
+        Arguments:
+            emulator: An emulator from which to fetch a value.
+
+        Returns:
+            The concrete value of this operand.
+        """
+
+        pass
+
+
+class RegisterOperand(Operand):
+    """An operand from an instruction that is simply a register."""
+
+    def __init__(self, name: str):
+        self.name = name
+
+    def key(self, emulator: emulators.Emulator):
+        return self.name
+
+    def __eq__(self, other) -> bool:
+        return hash(self) == hash(other)
+
+    def __hash__(self) -> int:
+        return hash(self.__repr__())
+
+    def concretize(self, emulator: emulators.Emulator) -> int:
+        return emulator.read_register(self.name)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.name})"
+
+
+class MemoryReferenceOperand(Operand):
+    """An operand from an instruction which reads or writes memory."""
+
+    def __init__(self, size: int = 4):
+        self.size = size
+
+    @abc.abstractmethod
+    def address(self, emulator: emulators.Emulator) -> int:
+        """Compute a concrete value for this operand.
+
+        Arguments:
+            emulator: An emulator from which to fetch a value.
+
+        Returns:
+            The concrete value of this operand.
+        """
+
+    def key(self, emulator: emulators.Emulator) -> int:
+        return self.address(emulator)
+
+    def __eq__(self, other):
+        return self.__repr__() == other.__repr__()
+
+    def __hash__(self):
+        return hash(self.__repr__())
+
+    def concretize(self, emulator: emulators.Emulator) -> typing.Optional[bytes]:
+        return emulator.read_memory(self.address(emulator), self.size)
+
+
+class Instruction(metaclass=abc.ABCMeta):
+    """An instruction storage and semantic metadata class."""
+
+    def __init__(
+        self,
+        instruction: bytes,
+        address: int,
+        _instruction: typing.Optional[capstone.CsInsn] = None,
+    ):
+        self.instruction = instruction
+        self.address = address
+
+        if _instruction is None:
+            md = capstone.Cs(self.cs_arch, self.cs_mode)
+            md.detail = True
+
+            _instruction = md.disasm(instruction, address).__next__()
+
+        self._instruction = _instruction
+        self.disasm = f"{self._instruction.address:x} {self._instruction.mnemonic} {self._instruction.op_str}"
+
+    @property
+    @abc.abstractmethod
+    def angr_arch(self) -> str:
+        """angr architecture ID"""
+        return ""
+
+    @property
+    @abc.abstractmethod
+    def cs_arch(self) -> int:
+        """Capstone architecture ID"""
+        return 0
+
+    @property
+    @abc.abstractmethod
+    def cs_mode(self) -> int:
+        """Capstone mode ID"""
+        return 0
+
+    @classmethod
+    def from_capstone(cls, instruction: capstone.CsInsn):
+        """Construct from an existing Capstone instruction.
+
+        Arguments:
+            instruction: An existing Capstone instruction.
+        """
+        try:
+            return utils.find_subclass(
+                cls,
+                check=lambda x: x.cs_arch == instruction._cs.arch
+                and x.cs_mode == instruction._cs.mode,
+                instruction=instruction.bytes,
+                address=instruction.address,
+                _instruction=instruction,
+            )
+        except ValueError:
+            raise ValueError(
+                f"No instruction format for {instruction._cs.arch}:{instruction._cs.mode}"
+            )
+
+    @classmethod
+    def from_angr(cls, instruction, block, arch: str):
+        """Construct from an angr disassembler instruction.
+
+        Arguments:
+            instruction: An existing angr disassembler instruction
+            arch: angr architecture string
+        """
+        # angr's instructions don't include raw bytes.
+        off = instruction.address - block.addr
+        raw = block.bytes[off : off + instruction.size]
+        try:
+            return utils.find_subclass(
+                cls,
+                check=lambda x: x.angr_arch == arch,
+                instruction=raw,
+                address=instruction.address,
+            )
+        except ValueError:
+            raise ValueError(f"No instruction format for {arch}")
+
+    @classmethod
+    def from_bytes(cls, raw: bytes, address: int, arch: str, mode: str):
+        """Construct from a byte string."""
+        try:
+            return utils.find_subclass(
+                cls,
+                check=lambda x: x.arch == arch and x.mode == mode,
+                instruction=raw,
+                address=address,
+            )
+        except ValueError:
+            raise ValueError(f"No instruction format for {arch}:{mode}")
+
+    @abc.abstractmethod
+    def _memory_reference(self, operand) -> MemoryReferenceOperand:
+        pass
+
+    @property
+    def reads(self) -> typing.Set[Operand]:
+        """Registers and memory references read by this instruction.
+
+        This is a list of string register names and dictionary memory reference
+        specifications (i.e., in the form `base + scale * index + offset`).
+        """
+
+        read: typing.Set[Operand] = set()
+
+        for operand in self._instruction.operands:
+            if operand.type == capstone.CS_OP_MEM and (
+                not hasattr(operand, "access") or operand.access & capstone.CS_AC_READ
+            ):
+                read.add(self._memory_reference(operand))
+            elif operand.type == capstone.CS_OP_REG and (
+                not hasattr(operand, "access") or operand.access & capstone.CS_AC_READ
+            ):
+                read.add(RegisterOperand(self._instruction.reg_name(operand.reg)))
+
+        return read
+
+    @property
+    def writes(self) -> typing.Set[Operand]:
+        """Registers and memory references written by this instruction.
+
+        Same format as `reads`.
+        """
+
+        write: typing.Set[Operand] = set()
+
+        for operand in self._instruction.operands:
+            if operand.type == capstone.CS_OP_MEM and (
+                not hasattr(operand, "access") or operand.access & capstone.CS_AC_WRITE
+            ):
+                write.add(self._memory_reference(operand))
+            elif operand.type == capstone.CS_OP_REG and (
+                not hasattr(operand, "access") or operand.access & capstone.CS_AC_WRITE
+            ):
+                write.add(RegisterOperand(self._instruction.reg_name(operand.reg)))
+
+        return write
+
+    # def to_json(self) -> dict:
+    #     return {
+    #         "instruction": base64.b64encode(self.instruction).decode(),
+    #         "disasm": self.disasm,
+    #         "address": self.address,
+    #         "arch": self.arch,
+    #         "mode": self.mode,
+    #     }
+
+    # @classmethod
+    # def from_json(cls, dict):
+    #     if "instruction" not in dict:
+    #         raise ValueError(f"malformed {cls.__name__}: {dict!r}")
+
+    #     dict["instruction"] = base64.b64decode(dict["instruction"])
+
+    #     return cls(**dict)
+
+    def __repr__(self) -> str:
+        string = f"{self._instruction.mnemonic} {self._instruction.op_str}".strip()
+
+        return f"{self.__class__.__name__}(0x{self.address:x}: {string})"

smallworld/instructions/mips.py

@@ -0,0 +1,21 @@
+import capstone
+
+from .bsid import BSIDMemoryReferenceOperand
+from .instructions import Instruction, MemoryReferenceOperand
+
+
+class MIPSInstruction(Instruction):
+    angr_arch = "MIPS"
+    cs_arch = capstone.CS_ARCH_MIPS
+    cs_mode = capstone.CS_MODE_MIPS32 | capstone.CS_MODE_BIG_ENDIAN
+
+    def _memory_reference(self, operand) -> MemoryReferenceOperand:
+        return BSIDMemoryReferenceOperand(
+            base=self._instruction.reg_name(operand.value.mem.base),
+            offset=operand.value.mem.disp,
+            size=4,
+        )
+
+
+class MIPSELInstruction(MIPSInstruction):
+    cs_mode = capstone.CS_MODE_MIPS32

smallworld/instructions/x86.py

@@ -0,0 +1,100 @@
+import typing
+
+import capstone
+
+from .bsid import BSIDMemoryReferenceOperand
+from .instructions import Instruction, MemoryReferenceOperand, Operand, RegisterOperand
+
+
+class x86Instruction(Instruction):
+    word_size = 4
+    angr_arch = "X86"
+    cs_arch = capstone.CS_ARCH_X86
+    cs_mode = capstone.CS_MODE_32
+    sp = "esp"
+
+    def _memory_reference(self, base, index, scale, offset, size):
+        return BSIDMemoryReferenceOperand(
+            base=base, index=index, scale=scale, offset=offset, size=size
+        )
+
+    # operand is a capstone operand
+    def _memory_reference_operand(self, operand) -> MemoryReferenceOperand:
+        return self._memory_reference(
+            self._instruction.reg_name(operand.value.mem.base),
+            self._instruction.reg_name(operand.value.mem.index),
+            operand.value.mem.scale,
+            operand.value.mem.disp,
+            operand.size,
+        )
+
+    @property
+    def reads(self) -> typing.Set[Operand]:
+        """Registers and memory references read by this instruction.
+
+        This is a list of string register names and dictionary memory reference
+        specifications (i.e., in the form `base + scale * index + offset`).
+        """
+
+        reg_reads, _ = self._instruction.regs_access()
+        the_reads: typing.Set[Operand] = set(
+            [RegisterOperand(self._instruction.reg_name(r)) for r in reg_reads]
+        )
+
+        for operand in self._instruction.operands:
+            if operand.access & capstone.CS_AC_READ:
+                if operand.type == capstone.x86.X86_OP_MEM:
+                    if not self._instruction.mnemonic == "lea":
+                        # add the actual memory read
+                        the_reads.add(self._memory_reference_operand(operand))
+                    # add reads for parts of the operand
+                    base_name = self._instruction.reg_name(operand.mem.base)
+                    index_name = self._instruction.reg_name(operand.mem.index)
+                    if base_name:
+                        the_reads.add(RegisterOperand(base_name))
+                    if index_name:
+                        the_reads.add(RegisterOperand(index_name))
+                elif operand.type == capstone.x86.X86_OP_REG:
+                    # these are already in the list bc of regs_access above
+                    pass
+                else:
+                    # shouldn't happen
+                    assert 1 == 0
+        if self._instruction.mnemonic == "pop":
+            the_reads.add(self._memory_reference(self.sp, None, 1, 0, self.word_size))
+
+        return the_reads
+
+    @property
+    def writes(self) -> typing.Set[Operand]:
+        """Registers and memory references written by this instruction.
+
+        Same format as `reads`.
+        """
+        _, reg_writes = self._instruction.regs_access()
+        the_writes: typing.Set[Operand] = set(
+            [RegisterOperand(self._instruction.reg_name(r)) for r in reg_writes]
+        )
+        for operand in self._instruction.operands:
+            if operand.access & capstone.CS_AC_WRITE:
+                # please dont change this to CS_OP_MEM bc that doesnt work?
+                if operand.type == capstone.x86.X86_OP_MEM:
+                    assert not (self._instruction.mnemonic == "lea")
+                    the_writes.add(self._memory_reference_operand(operand))
+                elif operand.type == capstone.x86.X86_OP_REG:
+                    # operands doesn't contain implicit registers.
+                    # we get all registers from regs_write
+                    pass
+                else:
+                    assert 1 == 0
+        if self._instruction.mnemonic == "push":
+            the_writes.add(self._memory_reference(self.sp, None, 1, 0, self.word_size))
+
+        return the_writes
+
+
+class AMD64Instruction(x86Instruction):
+    angr_arch = "AMD64"
+    cs_mode = capstone.CS_MODE_64
+    sp = "rsp"
+    word_size = 8

smallworld/logging.py

@@ -0,0 +1,90 @@
+import logging
+import sys
+
+
+class CharacterLevelFilter(logging.Filter):
+    """Adds logging level as a single character for formatting."""
+
+    CHARACTERS = {
+        logging.DEBUG: "-",
+        logging.INFO: "+",
+        logging.WARNING: "!",
+        logging.ERROR: "*",
+        logging.CRITICAL: "#",
+    }
+
+    def filter(self, record):
+        record.levelchar = self.CHARACTERS.get(record.levelno, " ")
+        return True
+
+
+class ColorLevelFilter(logging.Filter):
+    """Adds logging level as a color for formatting."""
+
+    WHITE_DIM = "\x1b[37;2m"
+    WHITE = "\x1b[37m"
+    YELLOW = "\x1b[33m"
+    RED = "\x1b[31m"
+    RED_BOLD = "\x1b[31;1m"
+    END = "\x1b[0m"
+    NULL = END
+
+    COLORS = {
+        logging.DEBUG: WHITE_DIM,
+        logging.INFO: WHITE,
+        logging.WARNING: YELLOW,
+        logging.ERROR: RED,
+        logging.CRITICAL: RED_BOLD,
+    }
+
+    def filter(self, record):
+        record.levelcolor = self.COLORS.get(record.levelno, self.NULL)
+        return True
+
+
+def setup_logging(
+    level: int = logging.INFO,
+    verbose: bool = False,
+    colors: bool = True,
+    clear: bool = True,
+) -> None:
+    """Setup log handling.
+
+    Note: this should only be called once.
+
+    Arguments:
+        level: Logging level (from `logging` module).
+        verbose: Enable verbose logging mode.
+        colors: Enable logging colors (if supported).
+        clear: Remove all other handlers from the root logger.
+    """
+
+    if verbose:
+        format = "[%(asctime)s %(levelname)-7s|%(name)s]: %(message)s"
+    else:
+        format = "[%(levelchar)s] %(message)s"
+
+    if colors and sys.stderr.isatty():
+        format = f"%(levelcolor)s{format}{ColorLevelFilter.END}"
+
+    root = logging.getLogger()
+    root.setLevel(level)
+
+    if clear:
+        handlers = list(root.handlers)
+        for handler in handlers:
+            root.removeHandler(handler)
+
+    formatter = logging.Formatter(format)
+
+    handler = logging.StreamHandler()
+    handler.setLevel(level)
+    handler.addFilter(CharacterLevelFilter())
+    handler.addFilter(ColorLevelFilter())
+
+    handler.setFormatter(formatter)
+
+    root.addHandler(handler)
+
+
+__all__ = ["setup_logging"]

smallworld/platforms.py

@@ -0,0 +1,95 @@
+import enum
+from dataclasses import dataclass
+
+
+class Architecture(enum.Enum):
+    """Architecture and mode.
+
+    Names take the form ``{ARCH}_{MODE}`` where ``{ARCH}`` and ``{MODE}``
+    match the regex ``[A-Z0-9]+``.
+
+    Values are lowercase, kebab-case.
+    """
+
+    X86_32 = "x86-32"
+    """32-bit x86 supporting SSE extensions."""
+
+    X86_64 = "x86-64"
+    """64-bit x86 supporting AVX2 extensions."""
+
+    X86_64_AVX512 = "x86-64-avx512"
+    """64-bit x86 supporting AVX512 extensions."""
+
+    AARCH64 = "aarch64"
+
+    MIPS32 = "mips32"
+
+    MIPS64 = "mips64"
+
+    POWERPC64 = "powerpc64"
+    POWERPC32 = "powerpc32"
+
+    ARM_V5T = "arm-v5t"
+    ARM_V6M = "arm-v6m"
+    ARM_V6M_THUMB = "arm-v6m-thumb"
+    ARM_V7M = "arm-v7m"
+    ARM_V7R = "arm-v7r"
+    ARM_V7A = "arm-v7a"
+
+    RISCV64 = "riscv-64"
+
+    XTENSA = "xtensa"
+
+
+class Byteorder(enum.Enum):
+    """Endianness."""
+
+    BIG = "big"
+    """Big endian - most significant bit first."""
+
+    LITTLE = "little"
+    """Little endian - least significant bit first."""
+
+    MIDDLE = "middle"
+    """Middle endian - also known as PDP-endian."""
+
+
+class ABI(enum.Enum):
+    """Application binary interface.
+
+    Names match the regex ``[A-Z]+``.
+
+    Values are lowercase, kebab-case.
+    """
+
+    SYSTEMV = "system-v"
+    """System V."""
+
+    CDECL = "cdecl"
+    """Microsoft cdecl."""
+
+    VECTORCALL = "vectorcall"
+    """Microsoft vectorcall."""
+
+    FASTCALL = "fastcall"
+    """Microsoft fastcall."""
+
+    NONE = "none"
+    """No ABI"""
+
+
+@dataclass(frozen=True)
+class Platform:
+    """Platform metadata/configuration storage class."""
+
+    architecture: Architecture
+    """Architecture and mode."""
+
+    byteorder: Byteorder
+    """Endianness."""
+
+    def __repr__(self) -> str:
+        return f"{self.architecture}:{self.byteorder}"
+
+
+__all__ = ["Platform", "Architecture", "Byteorder", "ABI"]

smallworld/state/__init__.py

@@ -0,0 +1,6 @@
+from . import cpus, memory, models
+from .state import *  # noqa: F401, F403
+from .state import __all__ as __state__
+from .unstable import *  # noqa: F401, F403
+
+__all__ = __state__ + ["cpus", "models", "memory"]

smallworld/state/cpus/__init__.py

@@ -0,0 +1,32 @@
+from .aarch64 import AArch64
+from .amd64 import AMD64
+from .arm import ARMv5T, ARMv6M, ARMv6MThumb, ARMv7A, ARMv7M, ARMv7R
+from .cpu import *  # noqa: F401, F403
+from .cpu import __all__ as __cpu__
+from .i386 import I386
+from .mips import MIPSBE, MIPSEL
+from .mips64 import MIPS64BE, MIPS64EL
+from .powerpc import PowerPC32, PowerPC64
+from .riscv import RISCV64
+from .xtensa import XTensaBE, XTensaEL
+
+__all__ = __cpu__ + [
+    "AArch64",
+    "AMD64",
+    "ARMv5T",
+    "ARMv6M",
+    "ARMv6MThumb",
+    "ARMv7M",
+    "ARMv7R",
+    "ARMv7A",
+    "I386",
+    "MIPS64EL",
+    "MIPS64BE",
+    "MIPSEL",
+    "MIPSBE",
+    "PowerPC32",
+    "PowerPC64",
+    "RISCV64",
+    "XTensaBE",
+    "XTensaEL",
+]