smallworld-re 1.0.0__py3-none-any.whl

smallworld/exceptions/exceptions.py

@@ -0,0 +1,85 @@
+class Error(Exception):
+    """Common base class for all exceptions."""
+
+
+class ConfigurationError(Error):
+    """Raised when there is a problem with configuration."""
+
+    pass
+
+
+class EmulationError(Error):
+    """Raised when emulation fails."""
+
+    pass
+
+
+class EmulationStop(EmulationError):
+    """Base class for all emulation stopping exceptions."""
+
+    pass
+
+
+class EmulationBounds(EmulationStop):
+    """Raised when execution goes out of bounds."""
+
+    pass
+
+
+class EmulationExitpoint(EmulationStop):
+    """Raised when execution hits an exit point."""
+
+    pass
+
+
+class UnsupportedRegisterError(EmulationError):
+    """Raised if you ask for a register unsupported by the emulator"""
+
+    pass
+
+
+class SymbolicValueError(EmulationError):
+    """Raised if you try to collapse a symbolic value to a concrete one"""
+
+    pass
+
+
+class UnsatError(EmulationError):
+    """Raised if a symbolic expression is unsatisfiable given constraints"""
+
+    pass
+
+
+class EmulationException(EmulationError):
+    """Raised when the underlying emulator fails.
+
+    This wraps known exceptions thrown by an Emulator.
+
+    Arguments:
+        exception: The original exception thrown.
+    """
+
+    def __init__(self, exception: Exception):
+        self.exception = exception
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.exception})"
+
+
+class AnalysisError(Error):
+    """Some kind of error in analysis."""
+
+
+__all__ = [
+    "Error",
+    "ConfigurationError",
+    "EmulationError",
+    "EmulationStop",
+    "EmulationBounds",
+    "EmulationExitpoint",
+    "EmulationException",
+    "SymbolicValueError",
+    "UnsatError",
+    "UnsupportedRegisterError",
+    "AnalysisError",
+]

smallworld/exceptions/unstable/__init__.py

@@ -0,0 +1 @@
+from .exceptions import *  # noqa: F401, F403

smallworld/exceptions/unstable/exceptions.py

@@ -0,0 +1,25 @@
+from .. import exceptions
+
+
+class UnicornEmulationError(exceptions.EmulationError):
+    def __init__(self, exception: Exception, pc: int, data: dict):
+        self.exception = exception
+        self.pc = pc
+        self.data = data
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}({self.exception}, {hex(self.pc)}, {self.data})"
+        )
+
+
+class AnalysisSetupError(exceptions.AnalysisError):
+    """Raised when an analysis run gets into trouble during setup."""
+
+
+class AnalysisRunError(exceptions.AnalysisError):
+    """Raised when something goes wrong during an analysis."""
+
+
+class AnalysisSignal(exceptions.Error):
+    """Raised to signal a non-fatal exception during an analysis."""

smallworld/extern/__init__.py

@@ -0,0 +1,4 @@
+from . import ctypes
+from .unstable import *  # noqa: F401, F403
+
+__all__ = ["ctypes"]

smallworld/extern/ctypes.py

@@ -0,0 +1,94 @@
+import ctypes
+
+# TODO: Figure out how to type-hint a ctypes objects
+# The base class for ctypes objects is private (with good reason.)
+# There are hacky and likely-fragile ways to get it.
+
+
+class TypedPointer(ctypes.c_void_p):
+    """Typed pointer class
+
+    This class fills a gap in ctypes ability to represent data.
+
+    The existing typed pointer classes are designed
+    as direct references to Python objects;
+    it's not possible to set a specific address.
+
+    c_void_p represents the correct kind of value,
+    but has no associated data type.
+
+    Warning:
+        Do not instantiate this class directly! The referenced type needs to be
+        bound to a class, since ctypes uses instances to represent specific
+        variables or fields. Use ``create_typed_pointer()`` to create a
+        subclass for your type.
+    """
+
+    _type = None
+
+    def __init__(self, *args, **kwargs):
+        # No idea what the signature for this should be,
+        # and don't want to pick one in case it changes
+        if self.__class__ == TypedPointer:
+            raise TypeError("Cannot instantiate TypedPointer directly")
+        # NOTE: Due to a bug, can't use super() in ctypes subclasses
+        ctypes.c_void_p.__init__(self, *args, **kwargs)
+
+    @property
+    def type(self):
+        """The type referenced by this pointer."""
+
+        return self._type
+
+    def __str__(self):
+        return f"Pointer {self.type} = {self.value}"
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, TypedPointer)
+            and other.type == self.type
+            and other.value == self.value
+        )
+
+
+_pointertypes = {
+    None: ctypes.c_void_p,
+    ctypes.c_char: ctypes.c_char_p,
+    ctypes.c_wchar: ctypes.c_wchar_p,
+}
+
+
+def create_typed_pointer(reference):
+    """Create a typed pointer class.
+
+    The referenced type should be any ctypes type definition, or ``None`` to
+    represent 'void'.
+
+    Referenced types that already have a ctypes pointer value type will return
+    that type, not a ``TypedPointer``::
+
+        create_typed_pointer(c_char)  # returns c_char_p
+        create_typed_pointer(c_wchar)  # returns c_wchar_p
+        create_typed_pointer(None)  # returns c_void_p
+
+    Arguments:
+        reference: The ctypes object defining the referenced type.
+
+    Returns:
+        A subclass of ``TypedPointer`` representing your referenced type.
+    """
+    if reference in _pointertypes:
+        return _pointertypes[reference]
+    else:
+        # Dynamically create a new subclass of TypedPointer to represent this
+        # particular type
+        name = f"{type.__name__}Pointer"
+        cls = type(name, (TypedPointer,), {"type": reference})
+        _pointertypes[reference] = cls
+        return cls
+
+
+__all__ = [
+    "TypedPointer",
+    "create_typed_pointer",
+]

smallworld/extern/unstable/__init__.py

@@ -0,0 +1 @@
+from . import ghidra  # noqa: F401

smallworld/extern/unstable/ghidra.py

@@ -0,0 +1,129 @@
+import logging
+import typing
+
+from ... import platforms, state
+
+# TODO fix these imports after refactoring state module
+# from ... import models, state
+
+logger = logging.getLogger(__name__)
+
+
+# TODO: fix the cpustate type label once refactoring state module is complete
+def setup_default_libc(
+    flat_api: typing.Any,
+    libc_func_names: typing.List[str],
+    cpustate: typing.Any,
+    canonicalize: bool = True,
+) -> None:
+    """Map some default libc models into the cpu state.
+
+    Uses Ghdira to figure out entry points in PLT for libc fns and arranges for
+    those in a user-provided list to be hooked using the default models in
+    Smallworld.  Idea is you might not want all of them mapped and so you say
+    just these for now.
+
+    Arguments:
+        flat_api: this is what gets returned by pyhidra.open_program(elf_file)
+        libc_func_names: list of names of libc functions
+        cpustate: cpu state into which to map models
+    """
+
+    platform = platforms.Platform(
+        platforms.Architecture.X86_64, platforms.Byteorder.LITTLE
+    )
+    abi = platforms.ABI.SYSTEMV
+
+    program = flat_api.getCurrentProgram()
+    listing = program.getListing()
+
+    # find plt section
+    plt = None
+    for block in program.getMemory().getBlocks():
+        if "plt" in block.getName():
+            plt = block
+
+    assert plt is not None
+
+    # map all requested libc default models
+    num_mapped = 0
+    num_no_model = 0
+    num_too_many_models = 0
+    for func in listing.getFunctions(True):
+        func_name = func.getName()
+        entry = func.getEntryPoint()
+        if not plt.contains(entry):
+            continue
+        else:
+            if func_name in libc_func_names:  # type: ignore
+                try:
+                    # func is in plt and it is a function for which we want to use a default model
+                    int_entry = int(entry.getOffset())
+                    model = state.models.Model.lookup(
+                        func_name, platform, abi, int_entry
+                    )
+                    cpustate.map(model)
+                    logger.debug(
+                        f"Added libc model for {func_name} entry {int_entry:x}"
+                    )
+                    num_mapped += 1
+                except ValueError:
+                    logger.debug(
+                        f"As there is no default model for {func_name}, adding with null model, entry {int_entry:x}"
+                    )
+                    model = state.models.Model.lookup("null", platform, abi, int_entry)
+                    cpustate.map(model)
+                    num_no_model += 1
+
+    logger.info(
+        f"Libc model mappings: {num_mapped} default, {num_no_model} no model, {num_too_many_models} too many models"
+    )
+
+
+# TODO: fix the cpustate type label once refactoring state module is complete
+def setup_section(
+    flat_api: typing.Any,
+    section_name: str,
+    cpustate: typing.Any,
+    elf_file: str = "None",
+) -> bytes:
+    """Set up this section in cpustate, possibly using contents of elf file
+
+    Uses ghidra to get start addr / size of sections for adding them to
+    cpustate. If elf_file is specified, the data will come from the file (ghidra
+    tells us where to find it) and get mapped into cpustate memory. Else that
+    will be zeros.
+
+    Arguments:
+        flat_api: this is what gets returned by pyhidra.open_program(elf_file)
+        section_name: '.data' or '.txt' or '.got' or ..
+        cpustate: cpu state into which to map models
+        elf_file: name of file flat_api came from (elf)
+
+    Returns:
+        If elf_file is specified then cpu state for that came from
+        file which means we loaded the data out of the file at the
+        correct offset.  This will be returned in that case. Else, the
+        section data will be 0s.
+
+    """
+    # note, elf_file assumed to be same as one flat_api opened
+    program = flat_api.getCurrentProgram()
+    memory = program.getMemory()
+    block = memory.getBlock(section_name)
+    address = int(block.start.getOffset())
+    size = int(block.size)
+    section_bytes = None
+    if elf_file == "None":
+        # assume we are to just zero this
+        section_bytes = b"\0" * size
+    else:
+        # this is file offset that block
+        offs_in_elf = block.getSourceInfos()[0].getFileBytesOffset()
+        # read actual section bytesout of elf
+        with open(elf_file, "rb") as e:
+            e.seek(offs_in_elf)
+            section_bytes = e.read(size)
+    section = state.memory.RawMemory.from_bytes(section_bytes, address)
+    cpustate.map(section, section_name)
+    return section_bytes

smallworld/helpers.py

@@ -0,0 +1,107 @@
+import argparse
+import logging
+import typing
+
+logger = logging.getLogger(__name__)
+
+
+from . import analyses, emulators, exceptions, state
+
+T = typing.TypeVar("T", bound=state.Machine)
+
+
+def analyze(
+    machine: state.Machine,
+    asys: typing.List[typing.Union[analyses.Analysis, analyses.Filter]],
+) -> None:
+    """Run requested analyses on some code
+
+    Arguments:
+        machine: A state class from which emulation should begin.
+        asys: List of analyses and filters to run
+    """
+
+    filters: typing.List[analyses.Filter] = []
+    runners: typing.List[analyses.Analysis] = []
+    for analysis in asys:
+        if isinstance(analysis, analyses.Filter):
+            filters.append(analysis)
+            filters[-1].activate()
+        elif isinstance(analysis, analyses.Analysis):
+            runners.append(analysis)
+
+    try:
+        for analysis in runners:
+            analysis.run(machine)
+    except:
+        logger.exception("Error durring analysis")
+    finally:
+        for filter in filters:
+            filter.deactivate()
+
+
+def fuzz(
+    machine: state.Machine,
+    input_callback: typing.Callable,
+    crash_callback: typing.Optional[typing.Callable] = None,
+    always_validate: bool = False,
+    iterations: int = 1,
+) -> None:
+    """Creates an AFL fuzzing harness.
+
+    Arguments:
+        cpu: A state class from which emulation should begin.
+        input_callback: This is called for every input. It should map the input
+            into the state. It should return true if the input is accepted and
+            false if it should be skipped.
+        crash_callback: This is called on crashes to validate that we do in
+            fact care about this crash.
+        always_validate: Call the crash_callback everytime instead of just on
+            crashes.
+        iterations: How many iterations to run before forking again.
+    """
+
+    try:
+        import unicornafl
+    except ImportError:
+        raise RuntimeError(
+            "missing `unicornafl` - afl++ must be installed manually from source"
+        )
+
+    arg_parser = argparse.ArgumentParser(description="AFL Harness")
+    arg_parser.add_argument("input_file", type=str, help="File path AFL will mutate")
+    args = arg_parser.parse_args()
+
+    cpu: typing.Optional[state.cpus.CPU] = None
+    for c in machine.members(state.cpus.CPU).items():
+        if cpu is not None:
+            raise exceptions.ConfigurationError("cannot fuzz a multi-core machine")
+        cpu = c
+    if cpu is None:
+        raise exceptions.ConfigurationError("cannot fuzz a zero-core machine")
+
+    emu = emulators.UnicornEmulator(cpu.platform)
+    machine.apply(emu)
+
+    exits = []
+    code = None
+    for code in machine.members(state.memory.code.Executable).items():
+        exits.extend([b.stop for b in code.bounds])
+
+    if len(exits) == 0:
+        if code is None:
+            raise exceptions.ConfigurationError("Cannot fuzz a machine with no code")
+        exits.append(code.base + len(code.image))
+
+    unicornafl.uc_afl_fuzz(
+        uc=emu.engine,
+        input_file=args.input_file,
+        place_input_callback=input_callback,
+        exits=exits,
+        validate_crash_callback=crash_callback,
+        always_validate=always_validate,
+        persistent_iters=iterations,
+    )
+
+
+__all__ = ["analyze"]

smallworld/hinting/__init__.py

@@ -0,0 +1,8 @@
+from .hinting import *  # noqa: F401, F403
+from .hinting import __all__ as __hinting__
+from .hints import *  # noqa: F401, F403
+from .hints import __all__ as __hints__
+from .utils import *  # noqa: F401, F403
+from .utils import __all__ as __utils__
+
+__all__ = __hinting__ + __hints__ + __utils__

smallworld/hinting/hinting.py

@@ -0,0 +1,214 @@
+import copy
+import json
+import logging
+import sys
+import typing
+from dataclasses import dataclass
+
+"""
+Will this appear in docs?
+
+
+"""
+
+# logging re-exports
+from logging import WARNING
+
+from .. import logging as internal_logging
+
+
+class Serializable:
+    """Base class for serialization support.
+
+    Descendants should implement the methods below to allow automatic
+    serialization/deserialization using the JSON encoder/decoder classes below.
+    """
+
+    def to_dict(self) -> dict:
+        raise NotImplementedError()
+
+    @classmethod
+    def from_dict(cls, dict):
+        raise NotImplementedError()
+
+
+@dataclass(frozen=True)
+class Hint(Serializable):
+    """Base class for all Hints.
+
+    Arguments:
+        message: A message for this Hint.
+    """
+
+    message: str
+    """A detailed description."""
+
+    def to_dict(self) -> dict:
+        """Convert to a dictionary which can be trivially serialized.
+
+        Returns:
+            A dictionary containing the hint.
+        """
+
+        return self.__dict__
+
+    @classmethod
+    def from_dict(cls, dict):
+        """Load from a dictionary.
+
+        Arguments:
+            dict: Dictionary from which to construct the hint.
+
+        Returns:
+            The constructed hint.
+        """
+
+        return cls(**dict)
+
+
+class Hinter(logging.Logger):
+    """A custom logger that only accepts Hints."""
+
+    def _log(self, level, msg, *args, **kwargs):
+        if not isinstance(msg, Hint):
+            raise ValueError(f"{repr(msg)} is not a Hint")
+
+        return super()._log(level, msg, *args, **kwargs)
+
+
+root = Hinter(name="root", level=WARNING)
+Hinter.root = typing.cast(logging.RootLogger, root)
+Hinter.manager = logging.Manager(Hinter.root)
+Hinter.manager.loggerClass = Hinter
+
+
+def get_hinter(name: typing.Optional[str] = None) -> Hinter:
+    """Get a hinter with the given name.
+
+    Arguments:
+        name: The name of the hinter to get - if `None` this returns the
+            root Hinter.
+
+    Returns:
+        A Hinter with the given name.
+    """
+
+    if not name or isinstance(name, str) and name == root.name:
+        return root
+
+    return typing.cast(Hinter, Hinter.manager.getLogger(name))
+
+
+class SerializableJSONEncoder(json.JSONEncoder):
+    def default(self, o):
+        if isinstance(o, Serializable):
+            d = o.to_dict()
+            d["class"] = f"{o.__class__.__module__}.{o.__class__.__name__}"
+
+            return d
+        return super().default(o)
+
+
+class SerializableJSONDecoder(json.JSONDecoder):
+    def __init__(self, *args, **kwargs):
+        json.JSONDecoder.__init__(self, object_hook=self.object_hook, *args, **kwargs)
+
+    def object_hook(self, dict):
+        if "class" in dict:
+            module, name = dict["class"].rsplit(".", 1)
+            cls = getattr(sys.modules[module], name)
+            del dict["class"]
+
+            return cls.from_dict(dict)
+        return dict
+
+
+class JSONFormatter(logging.Formatter):
+    """A custom JSON formatter for json-serializable messages.
+
+    Arguments:
+        keys (dict): A dictionary mapping json keys to their logging format
+            strings.
+    """
+
+    def __init__(self, *args, keys=None, **kwargs):
+        super().__init__(*args, **kwargs)
+
+        keys = keys or {}
+        self.keys = {}
+        for name, fmt in keys.items():
+            self.keys[name] = logging.Formatter(fmt)
+
+    def format(self, record):
+        formatted = {}
+
+        for key, formatter in self.keys.items():
+            formatted[key] = formatter.format(record)
+
+        formatted["content"] = record.msg
+
+        hint, record.msg = record.msg, None
+        modified = copy.deepcopy(record)
+        record.msg = hint
+
+        modified.msg = json.dumps(formatted, cls=SerializableJSONEncoder)
+
+        return super().format(modified)
+
+
+def setup_hinting(
+    level: int = logging.INFO,
+    verbose: bool = False,
+    colors: bool = True,
+    stream: bool = True,
+    file: typing.Optional[str] = None,
+) -> None:
+    """Set up hint handling.
+
+    Note:
+        This should only be called once.
+
+    Arguments:
+        level: Hinting level (from `hinting` module).
+        verbose: Enable verbose hinting mode.
+        colors: Enable hinting colors (if supported).
+        stream: Enable stream logging.
+        file: If provided, enable file logging to the path provided.
+    """
+
+    if verbose:
+        keys = {
+            "time": "%(asctime)s",
+            "level": "%(levelname)s",
+            "source": "%(name)s",
+        }
+    else:
+        keys = {}
+
+    root = get_hinter()
+    root.setLevel(level)
+
+    if stream:
+        format = "[%(levelchar)s] %(message)s"
+
+        if colors and sys.stderr.isatty():
+            format = f"%(levelcolor)s{format}{internal_logging.ColorLevelFilter.END}"
+
+        formatter = JSONFormatter(format, keys=keys)
+
+        handler: logging.Handler = logging.StreamHandler()
+        handler.setLevel(level)
+        handler.addFilter(internal_logging.CharacterLevelFilter())
+        handler.addFilter(internal_logging.ColorLevelFilter())
+        handler.setFormatter(formatter)
+
+        root.addHandler(handler)
+
+    if file:
+        formatter = JSONFormatter("%(message)s", keys=keys)
+        handler = logging.FileHandler(file, mode="w")
+        handler.setFormatter(formatter)
+        root.addHandler(handler)
+
+
+__all__ = ["Hint", "Serializable", "root", "get_hinter", "setup_hinting"]