emfuzzer 0.1.0__py3-none-any.whl

emfuzzer/__init__.py

@@ -0,0 +1,62 @@
+# Copyright (c) 2025 Warsaw University of Technology
+# This file is licensed under the MIT License.
+# See the LICENSE.txt file in the root of the repository for full details.
+
+"""
+Main module of the application.
+"""
+
+import json
+import logging
+
+from .arguments import Arguments
+from .case import Case
+from .config import Config
+from .context import Context
+from .delay import Delay
+from .injector import Injector
+from .results import Results
+
+logger = logging.getLogger(__name__)
+
+
+def run(args: Arguments, config: Config) -> int:
+    results = Results(config)
+
+    with Context(config) as context:
+        case = Case.from_config(context=context, results=results)
+
+        injector = Injector.from_config(results=results, context=context)
+
+        delay_between_cases = Delay.from_config(
+            "delays", "between_cases", config=config
+        )
+        delay_before_inject = Delay.from_config(
+            "delays", "before_inject", config=config
+        )
+
+        for path in args.data:
+            logger.info(f"Opening {path}")
+            with path.open("rb") as file:
+                data = file.read()
+            if len(data) == 0:
+                logger.warning(f"No data found, skipping {path}")
+                continue
+
+            case_name = str(path)
+            results.add_key(case_name)
+
+            with case.execute(case_name):
+                delay_before_inject.wait()
+                injector.inject(case_name, data)
+
+            delay_between_cases.wait()
+
+        results.finish()
+    logger.info(f"Results:\n {results.summary()}")
+
+    with open(args.output_prefix + ".json", "w", encoding="utf-8") as f:
+        json.dump(results.to_dict(), f, indent=2)
+        f.write("\n")
+
+    return results.total_errors()

emfuzzer/__main__.py

@@ -0,0 +1,92 @@
+# Copyright (c) 2025 Warsaw University of Technology
+# This file is licensed under the MIT License.
+# See the LICENSE.txt file in the root of the repository for full details.
+
+"""
+Main entry point to the application.
+"""
+
+import argparse
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from . import run
+from .arguments import Arguments
+from .config import Config
+from .version import VERSION
+
+
+def __parse_data(parser: argparse.ArgumentParser, data: list[str]) -> list[Path]:
+    result = [Path(f) for f in data]
+    for f in result:
+        if not f.is_file():
+            parser.error(f"Specified path is not a file: {f}")
+    if len(result) != len(set(result)):
+        parser.error("Non-unique file names as inputs - results would be inconsistent")
+    return result
+
+
+def __setup_logger(prefix: str) -> None:
+    log_format = "%(asctime)s [%(levelname)8s](%(name)20s): %(message)s"
+    logging.basicConfig(
+        level=logging.DEBUG,
+        format=log_format,
+    )
+
+    root_logger = logging.getLogger()
+    handler = logging.FileHandler(f"{prefix}.log")
+    handler.setFormatter(root_logger.handlers[0].formatter)
+    logging.getLogger().addHandler(handler)
+
+    root_logger.info(f"Started instance ({VERSION})")
+
+
+def parse_args() -> Arguments:
+    parser = argparse.ArgumentParser(
+        prog="emfuzzer",
+        description="Fuzzing experiments orchestrator for embedded",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "data",
+        nargs="+",
+        help="list of files containing binary data to send to the target",
+    )
+    parser.add_argument(
+        "--output-prefix",
+        help="prefix to be used for saving output (logs, reports, etc.)",
+        default="emfuzzer",
+        type=str,
+    )
+    parser.add_argument(
+        "--config",
+        help="path to the configuration file",
+        default="default-config.json",
+        type=Path,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=VERSION,
+    )
+
+    args = parser.parse_args()
+
+    args.data = __parse_data(parser, args.data)
+    args.output_prefix += f"-{datetime.now():%Y%m%d-%H%M%S}"
+
+    return args
+
+
+def main() -> int:
+    args = parse_args()
+
+    __setup_logger(args.output_prefix)
+
+    return run(args, Config.from_file(args.config))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

emfuzzer/arguments.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2025 Warsaw University of Technology
+# This file is licensed under the MIT License.
+# See the LICENSE.txt file in the root of the repository for full details.
+
+"""
+Module representing command line arguments.
+"""
+
+from pathlib import Path
+from typing import Protocol
+
+
+class Arguments(Protocol):  # pylint: disable=too-few-public-methods
+    data: list[Path]
+    output_prefix: str
+    config: Path

emfuzzer/case.py

@@ -0,0 +1,43 @@
+# Copyright (c) 2025 Warsaw University of Technology
+# This file is licensed under the MIT License.
+# See the LICENSE.txt file in the root of the repository for full details.
+
+"""
+Module representing "case" - an instance of the experiment execution.
+"""
+
+from contextlib import contextmanager
+from typing import Iterator, Self
+
+from .context import Context
+from .results import Results
+from .subtasks import SubTasks
+
+
+class Case:
+
+    def __init__(self, setups: SubTasks, monitoring: SubTasks, checks: SubTasks):
+        self._setups = setups
+        self._monitoring = monitoring
+        self._checks = checks
+
+    @contextmanager
+    def execute(self, case_name: str) -> Iterator[None]:
+        self._setups.execute_for(case_name)
+        with self._monitoring.monitor(case_name):
+            yield
+        self._checks.execute_for(case_name)
+
+    @classmethod
+    def from_config(cls, context: Context, results: Results) -> Self:
+        return cls(
+            setups=SubTasks.from_config(
+                "case", "setups", results=results, context=context
+            ),
+            checks=SubTasks.from_config(
+                "case", "checks", results=results, context=context
+            ),
+            monitoring=SubTasks.from_config(
+                "case", "monitoring", results=results, context=context
+            ),
+        )

emfuzzer/coap/__init__.py

@@ -0,0 +1,109 @@
+# Copyright (c) 2025 Warsaw University of Technology
+# This file is licensed under the MIT License.
+# See the LICENSE.txt file in the root of the repository for full details.
+
+"""
+CoAP - Constrained Application Protocol support module.
+"""
+
+from enum import StrEnum, auto
+from typing import Self
+
+from ..config import Config
+from ..context import Context
+from ..delay import Delay
+from ..injector.subtask import TypedInjectionSubTask
+from ..io import IOLoop, SendQueue
+from ..io.net import NetworkAddress
+from ..io.sockets import UdpClientSocket
+from ..subtasks.subtask import SubTask, TypedSubTask
+from .validator import Validator
+
+
+class CoapMonitorResult(StrEnum):
+    SUCCESS = auto()
+    UNEXPECTED_MESSAGE_RECEIVED = auto()
+
+
+class CoapMonitor(TypedSubTask[CoapMonitorResult]):
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    def __init__(
+        self,
+        name: str,
+        io: IOLoop,
+        target: NetworkAddress,
+        response_timeout: float,
+        observation_timeout: float,
+    ):
+        super().__init__(name)
+        self._io = io
+        self._target = target
+        self._response_timeout = response_timeout
+        self._delay = Delay(observation_timeout, name + ".observation")
+
+        self._validator: Validator | None = None
+        self._socket: UdpClientSocket | None = None
+        self._queue: SendQueue[tuple[NetworkAddress, bytes]] | None = None
+
+    def start(self) -> CoapMonitorResult | SubTask.StartedType:
+        self._queue = self._io.make_queue(tuple[NetworkAddress, bytes])
+        self._validator = Validator(self._target, self._response_timeout)
+        self._socket = UdpClientSocket(
+            self.name() + ".udp", self._queue, self._validator
+        )
+        self._io.register(self._socket)
+        return SubTask.STARTED
+
+    def finish(self) -> CoapMonitorResult:
+        assert self._socket
+        assert self._validator
+        self._delay.wait()
+        self._io.close(self._socket)
+        return (
+            CoapMonitorResult.SUCCESS
+            if self._validator.unexpected_messages == 0
+            else CoapMonitorResult.UNEXPECTED_MESSAGE_RECEIVED
+        )
+
+    def result_type(self) -> type[CoapMonitorResult]:
+        return CoapMonitorResult
+
+    def send(self, data: bytes) -> None:
+        assert self._queue is not None
+        self._queue.put((self._target, data))
+
+    def wait_for_response(self) -> Validator.Result:
+        assert self._validator
+        return self._validator.wait_for_result()
+
+    @classmethod
+    def from_config(cls, name: str, config: Config, context: Context) -> Self:
+        result = cls(
+            name=name,
+            target=NetworkAddress.from_config(config.section("target")),
+            response_timeout=config.get_float("response_timeout"),
+            observation_timeout=config.get_float("observation_timeout"),
+            io=context.worker(IOLoop),
+        )
+        context.register_data(name, result)
+        return result
+
+
+class CoapInjector(TypedInjectionSubTask[Validator.Result]):
+    def __init__(self, name: str, monitor: CoapMonitor):
+        super().__init__(name)
+        self._monitor = monitor
+
+    def inject(self, data: bytes) -> Validator.Result:
+        self._monitor.send(data)
+        return self._monitor.wait_for_response()
+
+    def result_type(self) -> type[Validator.Result]:
+        return Validator.Result
+
+    @classmethod
+    def from_config(cls, name: str, config: Config, context: Context) -> Self:
+        return cls(
+            name=name,
+            monitor=context.data(CoapMonitor, config.get_str("monitor")),
+        )

emfuzzer/coap/code.py

@@ -0,0 +1,98 @@
+# Copyright (c) 2025 Warsaw University of Technology
+# This file is licensed under the MIT License.
+# See the LICENSE.txt file in the root of the repository for full details.
+
+"""
+CoAP - protocol codes etc.
+"""
+
+
+def decode_code(octet: int) -> tuple[int, int]:
+    clazz = (octet & 0b11100000) >> 5
+    code = octet & 0xB00011111
+    return clazz, code
+
+
+def code_short_string(code: tuple[int, int]) -> str:
+    return f"{code[0]}.{code[1]:02}"
+
+
+__MESSAGES: dict[int, tuple[str, dict[int, str]]] = {
+    1: (
+        "REQUEST",
+        {
+            0: "EMPTY",
+            1: "GET",
+            2: "POST",
+            3: "PUT",
+            4: "DELETE",
+            5: "FETCH",
+            6: "PATCH",
+            7: "iPATCH",
+        },
+    ),
+    2: (
+        "SUCCESS",
+        {
+            1: "Created",
+            2: "Deleted",
+            3: "Valid",
+            4: "Changed",
+            5: "Content",
+            31: "Continue",
+        },
+    ),
+    4: (
+        "CLIENT ERROR",
+        {
+            0: "Bad Request",
+            1: "Unauthorized",
+            2: "Bad Option",
+            3: "Forbidden",
+            4: "Not Found",
+            5: "Method Not Allowed",
+            6: "Not Acceptable",
+            8: "Request Entity Incomplete",
+            9: "Conflict",
+            12: "Precondition Failed",
+            13: "Request Entity Too Large",
+            15: "Unsupported Content-Format",
+        },
+    ),
+    5: (
+        "SERVER ERROR",
+        {
+            0: "Internal server error",
+            1: "Not implemented",
+            2: "Bad gateway",
+            3: "Service unavailable",
+            4: "Gateway timeout",
+            5: "Proxying not supported",
+        },
+    ),
+    7: (
+        "SIGNALING",
+        {
+            0: "Unassigned",
+            1: "CSM",
+            2: "Ping",
+            3: "Pong",
+            4: "Release",
+            5: "Abort",
+        },
+    ),
+}
+
+
+def code_message(code: tuple[int, int]) -> str:
+    class_message, code_dict = __MESSAGES.get(code[0], ("UNKNOWN", {}))
+    message = code_dict.get(code[1], "-unknown-")
+    return f"{class_message}: {message}"
+
+
+def code_to_string(code: tuple[int, int]) -> str:
+    return f"{code_short_string(code)} ({code_message(code)})"
+
+
+def code_reports_success(code: tuple[int, int]) -> bool:
+    return code[0] == 2

emfuzzer/coap/validator.py

@@ -0,0 +1,91 @@
+# Copyright (c) 2025 Warsaw University of Technology
+# This file is licensed under the MIT License.
+# See the LICENSE.txt file in the root of the repository for full details.
+
+"""
+CoAP - communication validator.
+"""
+
+import logging
+import threading
+from enum import StrEnum, auto
+
+from ..io.net import NetworkAddress, NetworkObserver
+from .code import code_reports_success, code_to_string, decode_code
+
+logger = logging.getLogger(__name__)
+
+
+class Validator(NetworkObserver):
+
+    class Result(StrEnum):
+        SUCCESS = auto()
+        UNKNOWN = auto()
+        UNEXPECTED_ORIGIN = auto()
+        MESSAGE_TOO_SHORT = auto()
+        OPERATION_FAILURE = auto()
+        TIMEOUT = auto()
+
+    def __init__(self, expected_ip: NetworkAddress, timeout: float):
+        self.expected_ip = expected_ip
+        self.timeout = timeout
+
+        self.cond = threading.Condition()
+        self.expecting = False
+        self.result: Validator.Result = self.Result.UNKNOWN
+
+        self.unexpected_messages = 0
+
+    def on_read(self, address: NetworkAddress, data: bytes) -> None:
+        with self.cond:
+            if not self.expecting:
+                self.__unexpected_message()
+                return
+            self.expecting = False
+            self.result = self.check_message(address, data)
+            self.cond.notify()
+
+    def check_message(self, address: NetworkAddress, data: bytes) -> Result:
+        if address != self.expected_ip:
+            logger.warning(
+                f"Message received from unexpected origin: {address} vs {self.expected_ip}"
+            )
+            return self.Result.UNEXPECTED_ORIGIN
+
+        if len(data) < 2:
+            logger.warning("Too short message")
+            return self.Result.MESSAGE_TOO_SHORT
+
+        code = decode_code(data[1])
+
+        logger.info(f"Received {code_to_string(code)}")
+
+        if not code_reports_success(code):
+            logger.warning("Operation reported as failed")
+            return self.Result.OPERATION_FAILURE
+
+        return self.Result.SUCCESS
+
+    def on_write(self, address: NetworkAddress, data: bytes) -> None:
+        with self.cond:
+            self.expecting = True
+            self.result = self.Result.UNKNOWN
+
+    def wait_for_result(self) -> Result:
+        with self.cond:
+            if not self.cond.wait_for(
+                lambda: self.result != self.Result.UNKNOWN, timeout=self.timeout
+            ):
+                self.expecting = False
+                logger.warning("Operation timed out")
+                return self.Result.TIMEOUT
+            result = self.result
+            self.result = self.Result.UNKNOWN
+            return result
+
+    def extra_stats(self) -> dict[str, int]:
+        return {"unexpected_messages": self.unexpected_messages}
+
+    def __unexpected_message(self) -> None:
+        logger.warning("Message unexpected at this stage")
+        self.unexpected_messages += 1

emfuzzer/config.py

@@ -0,0 +1,86 @@
+# Copyright (c) 2025 Warsaw University of Technology
+# This file is licensed under the MIT License.
+# See the LICENSE.txt file in the root of the repository for full details.
+
+"""
+Module for loading application configuration.
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Self, cast
+
+
+class Config:
+
+    def __init__(self, obj: dict[str, Any]):
+        self._obj = obj
+
+    def section(self, path: str, *subpath: str) -> Self:
+        subsection = cast(dict[str, Any], self._obj[path])
+        config = self.__class__(subsection)
+        if subpath:
+            try:
+                config.section(*subpath)
+            except KeyError:
+                raise KeyError(path, *subpath) from None
+        return config
+
+    def _get_value(self, path: str, *subpath: str) -> Any:
+        if subpath:
+            try:
+                # pylint: disable=protected-access
+                return self.section(path)._get_value(*subpath)
+            except KeyError:
+                raise KeyError(path, *subpath) from None
+        return self._obj[path]
+
+    def get_int(self, path: str, *subpath: str) -> int:
+        value = self._get_value(path, *subpath)
+        if not isinstance(value, int):
+            raise TypeError("not an int", path, *subpath)
+        return value
+
+    def get_float(self, path: str, *subpath: str) -> float:
+        value = self._get_value(path, *subpath)
+        if type(value) not in (int, float):
+            raise TypeError("not an float", path, *subpath)
+        return float(value)
+
+    def get_bool(self, path: str, *subpath: str) -> bool:
+        value = self._get_value(path, *subpath)
+        if type(value) not in (int, bool):
+            raise TypeError("not an bool", path, *subpath)
+        return bool(value)
+
+    def get_str(self, path: str, *subpath: str) -> str:
+        value = self._get_value(path, *subpath)
+        if not isinstance(value, str):
+            raise TypeError("not an str", path, *subpath)
+        return value
+
+    def get_config_list(self, path: str, *subpath: str) -> list[Self]:
+        value = self._get_value(path, *subpath)
+        if not isinstance(value, list):
+            raise TypeError("not an list", path, *subpath)
+        if any(not isinstance(x, dict) for x in value):
+            raise TypeError("not all elements are dict", path, *subpath)
+        return [self.__class__(v) for v in value]
+
+    def get_str_list(self, path: str, *subpath: str) -> list[str]:
+        value = self._get_value(path, *subpath)
+        if not isinstance(value, list):
+            raise TypeError("not an list", path, *subpath)
+        if any(not isinstance(x, str) for x in value):
+            raise TypeError("not all elements are str", path, *subpath)
+        return value
+
+    def to_dict(self) -> dict[str, Any]:
+        return self._obj
+
+    @classmethod
+    def from_file(cls, path: Path) -> Self:
+        with path.open() as file:
+            config = cls(json.load(file))
+            config._obj["__path__"] = str(path)
+            return config

emfuzzer/context.py

@@ -0,0 +1,74 @@
+# Copyright (c) 2025 Warsaw University of Technology
+# This file is licensed under the MIT License.
+# See the LICENSE.txt file in the root of the repository for full details.
+
+"""
+Module representing context of the experiment.
+"""
+
+from abc import ABC, abstractmethod
+from types import TracebackType
+from typing import Self, cast
+
+from .config import Config
+
+
+class Worker(ABC):
+    @abstractmethod
+    def start(self) -> None: ...
+
+    @abstractmethod
+    def stop(self) -> None: ...
+
+
+class Context:
+
+    def __init__(self, config: Config) -> None:
+        self._workers: dict[type[Worker], Worker] = {}
+        self._data: dict[str, object] = {}
+        self._config = config
+
+    @property
+    def config_root(self) -> Config:
+        return self._config
+
+    def worker[T: Worker](self, worker: type[T]) -> T:
+        if instance := self._workers.get(worker):
+            return cast(T, instance)
+
+        instance = worker()
+        instance.start()
+
+        self._workers[worker] = instance
+
+        return instance
+
+    def teardown(self) -> None:
+        for w in self._workers.values():
+            w.stop()
+
+        self._workers.clear()
+
+    def register_data(self, name: str, item: object) -> None:
+        if name in self._data:
+            raise RuntimeError(f"Data already registered: '{name}'")
+
+        self._data[name] = item
+
+    def data[T](self, data_type: type[T], name: str) -> T:
+        if item := self._data.get(name):
+            if isinstance(item, data_type):
+                return item
+            raise RuntimeError(f"Invalid data type for: '{name}'")
+        raise RuntimeError(f"Unknown data: '{name}'")
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        exc_traceback: TracebackType | None,
+    ) -> None:
+        self.teardown()