emfuzzer 0.1.0__tar.gz

emfuzzer-0.1.0/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Warsaw University of Technology
+
+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.

emfuzzer-0.1.0/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.3
+Name: emfuzzer
+Version: 0.1.0
+Summary: Experiments runner for embedded environments
+License: MIT
+Keywords: embedded,fuzzing,testing,experiments
+Author: Konrad Grochowski
+Author-email: Konrad.Grochowski@pw.edu.pl
+Requires-Python: >= 3.13
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: Software Development :: Testing
+Requires-Dist: paramiko (==3.5.1)
+Project-URL: ChangeLog, https://github.com/ZBOSK-II/emfuzzer/blob/master/CHANGELOG.md
+Project-URL: GitHub, https://github.com/ZBOSK-II/emfuzzer
+Description-Content-Type: text/markdown
+
+Emfuzzer - fuzzing experiments orchestrator for embedded
+============================================================
+
+When executing fuzzing experiment on embedded environment
+one often faces challenge of performing multiple tasks in
+reapetable and observable manner, for example: reset board,
+ensure embedded software booted, send fuzzing data using
+selected link, monitor peripheral state to detect changes
+in behaviour etc.
+
+This is what Emfuzzer helps to orchestrate: it runs various
+tools and scripts in specific manner, then gathers their
+results for further inspections.
+
+_Note_: although focused on fuzzing and embedded systems,
+Emfuzzer can help with any software-related experiments,
+that require repeatable order of tasks and results capture.
+
+
+Installation
+------------------------------------------------------------
+Emfuzzer is available on PyPI, it is recommended to install
+it in isolated environment, either by using Python `venv` or
+tools like `pipx`.
+
+``` shell
+python -m venv .venv
+source .venv/bin/activate
+pip install emfuzzer
+```
+
+``` shell
+pipx install emfuzzer
+```
+
+Usage
+------------------------------------------------------------
+To run experiments simply run:
+
+``` shell
+emfuzzer --config=experiment.json test1.bin test2.bin
+```
+
+For each specified data file steps from `experiment.json`
+will be executed and gathered results stored in file named
+`emfuzzer-CURRENTDATE.json`. Application will output logs
+to the console and also store them in `.log` file next to
+the `.json` results file. The prefix for output files can
+be modified using `--output-prefix` command line switch.
+
+See `default-config.json` in source directory for example
+of experiment definition (this file can be safely used -
+the "experiment" calls `cat` on each passed file).
+
+To obtain complete command line switches documentation call
+`emfuzzer --help`.
+
+
+Experiment
+------------------------------------------------------------
+Each data file passed to the emfuzzer represents a single
+Test Case. For each test case following experiment steps
+will be performed:
+
+ 1. Setup tasks will be executed and their results stored.
+ 2. Monitoring tasks will be started.
+ 3. Injector will use Test Case data to perform the main
+    experiment task (e.g. fuzzing data injection).
+ 4. Injector will observe system behaviour to capture
+    result of the injection.
+ 5. Monitoring tasks will finish, their results stored.
+ 6. Check tasks will be executed and their results stored.
+ 7. Go to 1 for next Test Case.
+
+Configuration
+------------------------------------------------------------
+Experiment configuration is stored in JSON format.
+
+See chapters below for list of all types of injectors, tasks
+and monitors (with arguments).
+
+Below is the `default-config.json` with comments:
+``` json-with-comments
+{
+  "delays": {
+    "between_cases": 0.2, // delay between Test Cases
+    "before_inject": 1    // delay after all setups
+  },
+  "injector": {
+    "type": "subprocess", // type of injection
+    "args": {             // arguments for given injector
+      "cmd": [
+        "cat"
+      ],
+      "shell": false,
+      "timeout": 1
+    }
+  },
+  "case": {                    // for each case
+    "setups": [                // list of setups
+      {
+        "type": "subprocess",  // type of setup tasks
+        "name": "setup",       // name used in results
+        "args": {              // arguments for given setup
+          "cmd": [
+            "echo",
+            "SETUP"
+          ],
+          "finish": {
+            "timeout": 0.5,
+            "signal": "NONE"
+          },
+          "shell": false
+        }
+      },
+      {                        // second setup
+        "type": "ping_alive",
+        "name": "ping",
+        "args": {
+          "host": "127.0.0.1",
+          "timeout": 10,
+          "interval": 1
+        }
+      }
+    ],
+    "monitoring": [],          // monitoring tasks
+    "checks": [                // list of checks tasks
+      {                        // same as setups
+        "type": "ping_stable",
+        "name": "ping",
+        "args": {
+          "host": "127.0.0.1",
+          "count": 2,
+          "interval": 1
+        }
+      },
+      {
+        "type": "subprocess",
+        "name": "teardown",
+        "args": {
+          "cmd": [
+            "echo",
+            "TEARDOWN"
+          ],
+          "finish": {
+            "timeout": 0.5,
+            "signal": "NONE"
+          },
+          "shell": false
+        }
+      }
+    ]
+  }
+}
+```
+
+
+Injectors
+------------------------------------------------------------
+Injectors are the tools that take the experiment data,
+use it to "inject" it into the system, and then observe the
+effects. Currently supported injectors' types:
+
+ * `subprocess` - execute script and captures its exit code.
+   Arguments:
+    - `cmd` - (list of strings) command to be executed, data
+      will be passed as the last argument to the call
+    - `shell` - (boolean) true when shell should be used todo
+      interpret the command
+    - `timeout` - (float) time to wait for command to finish
+ * `coap` - CoAP (Constrained Application Protocol) injector
+   data will be sent over UDP to specified address, success
+   when positive response is received from the system.
+   Arguments:
+    - `target` - dictionary containing `host` and `port` of
+      the target
+    - `response_timeout` - (float) timeout to wait for CoAP
+      response after sending the data
+    - `observation_timeout` - (float) additional time for
+      detecting any unexpected messages _after_ the response
+
+SubTasks & Monitors
+------------------------------------------------------------
+Sub Tasks are tasks that for each case can be executed as
+setups or checks.
+
+_Note_: failure of "setup" _does not_ interrupt the test
+case execution - it is logged and stored in results, next
+steps are still executed, to be analyzed later.
+
+Monitors are tasks that their execution is started after
+setups, then they are active during the injection and
+finish before checks.
+
+Available tasks:
+ * `subprocess` - execute script and capture its exit code.
+   Arguments:
+    - `cmd` - (list of strings) command to be executed
+    - `shell` - (boolean) true when shell should be used todo
+      interpret the command
+    - `finish` - configuration of finishing the task:
+      - `signal` - (string) signal name to be sent to the
+        task (can be `NONE`)
+      - `timeout` - (float) time to wait for command to
+        finish (starts after signal is sent)
+ * `ping_stable` - pings a target number of times, expects
+   all pings to reply.
+   Arguments:
+     - `host` - (string) host to be checked
+     - `count` - (integer) number of pings to sent
+     - `interval` - (integer) interval between pings
+ * `ping_alive` - pings a target and expects first response
+   Arguments:
+     - `host` - (string) host to be checked
+     - `timeout` - (float) timeout to wait for response
+     - `interval` - (integer) interval between pings
+ * `remote` - executes command over SSH and captures its
+   exit code.
+   Arguments:
+     - `connection` - dictionary containing:
+       - `host`
+       - `port`
+       - `username`
+       - `password`
+     - `command` - (string) command to be executed
+     - `start_key` - (string) string expected in the output
+       of the executed command for the command to be considered
+       "started successfully"
+     - `start_timeout` - (float) timeout for the start of
+       the command
+    - `finish` - configuration of finishing the task:
+      - `signal` - (string) signal name to be sent to the
+        task (can be `NONE`)
+      - `timeout` - (float) time to wait for command to
+        finish (starts after signal is sent)
+ * `coap_monitor` - listens for CoAP responses
+   Arguments:
+    - `target` - dictionary containing `host` and `port` of
+      the target
+    - `response_timeout` - (float) timeout to wait for CoAP
+      response after sending any data
+      (useful only when used as Injector)
+    - `observation_timeout` - (float) additional time for
+      detecting any unexpected messages when monitoring
+      finishes
+

emfuzzer-0.1.0/README.md

@@ -0,0 +1,245 @@
+Emfuzzer - fuzzing experiments orchestrator for embedded
+============================================================
+
+When executing fuzzing experiment on embedded environment
+one often faces challenge of performing multiple tasks in
+reapetable and observable manner, for example: reset board,
+ensure embedded software booted, send fuzzing data using
+selected link, monitor peripheral state to detect changes
+in behaviour etc.
+
+This is what Emfuzzer helps to orchestrate: it runs various
+tools and scripts in specific manner, then gathers their
+results for further inspections.
+
+_Note_: although focused on fuzzing and embedded systems,
+Emfuzzer can help with any software-related experiments,
+that require repeatable order of tasks and results capture.
+
+
+Installation
+------------------------------------------------------------
+Emfuzzer is available on PyPI, it is recommended to install
+it in isolated environment, either by using Python `venv` or
+tools like `pipx`.
+
+``` shell
+python -m venv .venv
+source .venv/bin/activate
+pip install emfuzzer
+```
+
+``` shell
+pipx install emfuzzer
+```
+
+Usage
+------------------------------------------------------------
+To run experiments simply run:
+
+``` shell
+emfuzzer --config=experiment.json test1.bin test2.bin
+```
+
+For each specified data file steps from `experiment.json`
+will be executed and gathered results stored in file named
+`emfuzzer-CURRENTDATE.json`. Application will output logs
+to the console and also store them in `.log` file next to
+the `.json` results file. The prefix for output files can
+be modified using `--output-prefix` command line switch.
+
+See `default-config.json` in source directory for example
+of experiment definition (this file can be safely used -
+the "experiment" calls `cat` on each passed file).
+
+To obtain complete command line switches documentation call
+`emfuzzer --help`.
+
+
+Experiment
+------------------------------------------------------------
+Each data file passed to the emfuzzer represents a single
+Test Case. For each test case following experiment steps
+will be performed:
+
+ 1. Setup tasks will be executed and their results stored.
+ 2. Monitoring tasks will be started.
+ 3. Injector will use Test Case data to perform the main
+    experiment task (e.g. fuzzing data injection).
+ 4. Injector will observe system behaviour to capture
+    result of the injection.
+ 5. Monitoring tasks will finish, their results stored.
+ 6. Check tasks will be executed and their results stored.
+ 7. Go to 1 for next Test Case.
+
+Configuration
+------------------------------------------------------------
+Experiment configuration is stored in JSON format.
+
+See chapters below for list of all types of injectors, tasks
+and monitors (with arguments).
+
+Below is the `default-config.json` with comments:
+``` json-with-comments
+{
+  "delays": {
+    "between_cases": 0.2, // delay between Test Cases
+    "before_inject": 1    // delay after all setups
+  },
+  "injector": {
+    "type": "subprocess", // type of injection
+    "args": {             // arguments for given injector
+      "cmd": [
+        "cat"
+      ],
+      "shell": false,
+      "timeout": 1
+    }
+  },
+  "case": {                    // for each case
+    "setups": [                // list of setups
+      {
+        "type": "subprocess",  // type of setup tasks
+        "name": "setup",       // name used in results
+        "args": {              // arguments for given setup
+          "cmd": [
+            "echo",
+            "SETUP"
+          ],
+          "finish": {
+            "timeout": 0.5,
+            "signal": "NONE"
+          },
+          "shell": false
+        }
+      },
+      {                        // second setup
+        "type": "ping_alive",
+        "name": "ping",
+        "args": {
+          "host": "127.0.0.1",
+          "timeout": 10,
+          "interval": 1
+        }
+      }
+    ],
+    "monitoring": [],          // monitoring tasks
+    "checks": [                // list of checks tasks
+      {                        // same as setups
+        "type": "ping_stable",
+        "name": "ping",
+        "args": {
+          "host": "127.0.0.1",
+          "count": 2,
+          "interval": 1
+        }
+      },
+      {
+        "type": "subprocess",
+        "name": "teardown",
+        "args": {
+          "cmd": [
+            "echo",
+            "TEARDOWN"
+          ],
+          "finish": {
+            "timeout": 0.5,
+            "signal": "NONE"
+          },
+          "shell": false
+        }
+      }
+    ]
+  }
+}
+```
+
+
+Injectors
+------------------------------------------------------------
+Injectors are the tools that take the experiment data,
+use it to "inject" it into the system, and then observe the
+effects. Currently supported injectors' types:
+
+ * `subprocess` - execute script and captures its exit code.
+   Arguments:
+    - `cmd` - (list of strings) command to be executed, data
+      will be passed as the last argument to the call
+    - `shell` - (boolean) true when shell should be used todo
+      interpret the command
+    - `timeout` - (float) time to wait for command to finish
+ * `coap` - CoAP (Constrained Application Protocol) injector
+   data will be sent over UDP to specified address, success
+   when positive response is received from the system.
+   Arguments:
+    - `target` - dictionary containing `host` and `port` of
+      the target
+    - `response_timeout` - (float) timeout to wait for CoAP
+      response after sending the data
+    - `observation_timeout` - (float) additional time for
+      detecting any unexpected messages _after_ the response
+
+SubTasks & Monitors
+------------------------------------------------------------
+Sub Tasks are tasks that for each case can be executed as
+setups or checks.
+
+_Note_: failure of "setup" _does not_ interrupt the test
+case execution - it is logged and stored in results, next
+steps are still executed, to be analyzed later.
+
+Monitors are tasks that their execution is started after
+setups, then they are active during the injection and
+finish before checks.
+
+Available tasks:
+ * `subprocess` - execute script and capture its exit code.
+   Arguments:
+    - `cmd` - (list of strings) command to be executed
+    - `shell` - (boolean) true when shell should be used todo
+      interpret the command
+    - `finish` - configuration of finishing the task:
+      - `signal` - (string) signal name to be sent to the
+        task (can be `NONE`)
+      - `timeout` - (float) time to wait for command to
+        finish (starts after signal is sent)
+ * `ping_stable` - pings a target number of times, expects
+   all pings to reply.
+   Arguments:
+     - `host` - (string) host to be checked
+     - `count` - (integer) number of pings to sent
+     - `interval` - (integer) interval between pings
+ * `ping_alive` - pings a target and expects first response
+   Arguments:
+     - `host` - (string) host to be checked
+     - `timeout` - (float) timeout to wait for response
+     - `interval` - (integer) interval between pings
+ * `remote` - executes command over SSH and captures its
+   exit code.
+   Arguments:
+     - `connection` - dictionary containing:
+       - `host`
+       - `port`
+       - `username`
+       - `password`
+     - `command` - (string) command to be executed
+     - `start_key` - (string) string expected in the output
+       of the executed command for the command to be considered
+       "started successfully"
+     - `start_timeout` - (float) timeout for the start of
+       the command
+    - `finish` - configuration of finishing the task:
+      - `signal` - (string) signal name to be sent to the
+        task (can be `NONE`)
+      - `timeout` - (float) time to wait for command to
+        finish (starts after signal is sent)
+ * `coap_monitor` - listens for CoAP responses
+   Arguments:
+    - `target` - dictionary containing `host` and `port` of
+      the target
+    - `response_timeout` - (float) timeout to wait for CoAP
+      response after sending any data
+      (useful only when used as Injector)
+    - `observation_timeout` - (float) additional time for
+      detecting any unexpected messages when monitoring
+      finishes

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