{"id":17327473,"url":"https://github.com/jnxf/automatic_fuzzing","last_synced_at":"2026-05-12T23:37:44.647Z","repository":{"id":67555430,"uuid":"334720906","full_name":"JnxF/automatic_fuzzing","owner":"JnxF","description":"An automatic fuzzing tool for ROS 2 C++ projects","archived":false,"fork":false,"pushed_at":"2021-05-31T09:38:04.000Z","size":336,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T10:15:05.151Z","etag":null,"topics":["fuzzing","ros","rosin"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JnxF.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-31T17:58:55.000Z","updated_at":"2021-05-31T09:38:06.000Z","dependencies_parsed_at":"2023-02-22T07:30:33.157Z","dependency_job_id":null,"html_url":"https://github.com/JnxF/automatic_fuzzing","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JnxF%2Fautomatic_fuzzing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JnxF%2Fautomatic_fuzzing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JnxF%2Fautomatic_fuzzing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JnxF%2Fautomatic_fuzzing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JnxF","download_url":"https://codeload.github.com/JnxF/automatic_fuzzing/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245785825,"owners_count":20671634,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fuzzing","ros","rosin"],"created_at":"2024-10-15T14:19:53.253Z","updated_at":"2026-05-12T23:37:44.618Z","avatar_url":"https://github.com/JnxF.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Automatic fuzzing for ROS 2\n\n![Python tests](https://github.com/rosin-project/ros2_fuzz/workflows/Python%20tests/badge.svg)\n![Hits](https://visitor-badge.glitch.me/badge?page_id=jnxf._automatic_fuzzing)\n[![GitHub stars](https://img.shields.io/github/stars/rosin-project/ros2_fuzz.svg)](https://GitHub.com/rosin-project/ros2_fuzz/stargazers/)\n[![GitHub forks](https://img.shields.io/github/forks/rosin-project/ros2_fuzz.svg)](https://GitHub.com/rosin-project/ros2_fuzz/network/)\n[![GitHub repo size in bytes](https://img.shields.io/github/repo-size/rosin-project/ros2_fuzz.svg)](https://github.com/rosin-project/ros2_fuzz)\n[![GitHub contributors](https://img.shields.io/github/contributors/rosin-project/ros2_fuzz.svg)](https://GitHub.com/rosin-project/ros2_fuzz/graphs/contributors/)\n[![GitHub license](http://img.shields.io/github/license/rosin-project/ros2_fuzz.svg)](https://github.com/rosin-project/ros2_fuzz/blob/master/LICENSE)\n\nAn automatic fuzzing tool for ROS 2 C++ projects. The tool comprises two different commands: `auto_detector` and `ros2_fuzzer`.\n\n## Installation\n\nInstall the `ros_automatic_fuzzer` folder with pip:\n\n```bash\npip3 install -e ros2_automatic_fuzzer\n```\n\nAlternatively, start the `start.sh` command, which spawn a Docker container with both the examples and the tool.\n\n## Usage\n\n1. Navigate to your ROS working space.\n2. Run `auto_detector`. This generates a `fuzz.yaml` file with `TODO` gaps.\n3. Fill the missing `TODO`s in the `fuzz.yaml` file and complete it.\n4. Run `ros2_fuzzer` and follow the instructions.\n5. Add the generated fuzzers to their CMakeLists.txt.\n6. Make a clean build with the `CC` and `CXX` environment variables pointing to AFL.\n7. Run the AFL fuzzers.\n\nCheck the following sections for detailed instructions for each step.\n\n### Step 2. The `auto_detector` command\n\nThe `auto_detector` command generates a YAML file called `fuzz.yaml` which contains descriptions for three types of artifacts: topics, services, and action servers. The detection process relies on regular expressions in C++, and therefore it is not bullet-proof.\n\nOptional arguments:\n\n- `--path PATH`. The path where to search for ROS artifacts. By default it is the working directory.\n\nOptional flags:\n\n- `-f` or `--overwrite` to force overwriting the file.\n- `-v` or `--verbose` to increase the output verbosity.\n\nTypical bash invocation:\n\n```bash\nauto_detector\n```\n\n### Step 3. The YAML format\n\nThe `fuzz.yaml` file contains descriptions for topics, services, and action servers. Some of the fields can be automatically extracted in the previous step thanks to the `auto_detector` command, but others must be manually introduced. There may be `TODO` blanks that must be filled.\n\nThe format is simple: there are three optional categories: `topics`, `services` and `actions`. Each of those is a dictionary, with the keys being the name of the artifact. Each artifact contains the following descriptors:\n\n- `headers_file` (compulsory). A string pointing to the `hpp` file where the type of the artifact is defined (the topic type, the service type, or the action type). Sometimes it can be directly inferred.\n- `source` (compulsory). A relative path to the `fuzz.yaml` file where the artifact to be fuzzed is located. It must be a C++ source code file.\n- `type` (compulsory). The type of the fuzzed artifact. It must conform to the `ros2 interface show` syntax. That is, with `::` as a separator and providing the full type. Correct examples are `example_interfaces::srv::AddTwoInts` and `std_msgs::msg::String`, but not `example_interfaces/srv/AddTwoInts` nor `String`.\n- `parameters` (optional). A list with all the parameters of the artifact. It can be inferred with the `auto_detector` command.\n\nFollows a concrete example. You can also check the syntax that is followed in [the YAML schema](ros2_automatic_fuzzer/yaml_utils/schema.yaml), which all `fuzz.yaml` files must conform to.\n\n```yaml\ntopics:\n  minimal_topic:\n    headers_file: std_msgs/msg/string.hpp\n    source: src/publisher_subscriber_example/src/publisher_member_function.cpp\n    type: std_msgs::msg::String\n    parameters: []\n  topic:\n    headers_file: std_msgs/msg/string.hpp\n    source: src/parameters_example_package/src/fuzz_target.cpp\n    type: std_msgs::msg::String\n    parameters: []\nservices:\n  add_two_ints:\n    headers_file: example_interfaces/srv/add_two_ints.hpp\n    node_name: minimal_subscriber\n    source: src/parameters_example_package/src/add_two_ints_server.cpp\n    type: example_interfaces::srv::AddTwoInts\n    parameters: []\n  add_three_ints:\n    headers_file: tutorial_interfaces/srv/add_three_ints.hpp\n    source: src/client_service_example/src/add_three_ints_server.cpp\n    type: tutorial_interfaces::srv::AddThreeInts\n    parameters: []\n```\n\n### Step 4. The `ros2_fuzzer` command\n\nIt consumes the `fuzz.yaml` file to generate C++ fuzzers for the selected artifacts. It allows generating fuzzers for all or some of them. Simply follow the steps on the screen. It may require calling `ros2 interface show`, and thus sourcing the ROS setup bash (with `. install/setup.bash`) may be required.\n\nOptional arguments:\n\n- `--path PATH`. The path where to search for a `fuzz.yaml` file. By default it is on the working directory.\n\nOptional flags:\n\n- `-v` or `--verbose` to increase the output verbosity.\n\nTypical bash invocation:\n\n```bash\nros2_fuzzer\n```\n\n### Step 5. Adding the fuzzers to the `CMakeLists.txt` files\n\nThe `ros2_fuzzer` command generates files of the `*_generated.cpp` form, which have to be linked to their `CMakeList.txt` files to be compiled.\n\nFor example, for the following `fuzz.yaml` file:\n\n```yaml\nservices:\n  add_three_ints:\n    headers_file: tutorial_interfaces/srv/add_three_ints.hpp\n    source: src/client_service_example/src/add_three_ints_server.cpp\n    type: tutorial_interfaces::srv::AddThreeInts\n    parameters: []\n```\n\nThe following code can be added into its `CMakeLists.txt` file (the `generated_fuzzer` keyword can be changed):\n\n```cmake\nadd_executable(generated_fuzzer src/add_three_ints_server_generated.cpp)\nament_target_dependencies(generated_fuzzer rclcpp tutorial_interfaces)\ninstall(TARGETS generated_fuzzer DESTINATION lib/${PROJECT_NAME})\n```\n\n### Step 6. Rebuilding with AFL\n\nTo fuzz your C++ artifacts, it is necessary to recompile the projects so that they include instrumentalization annotations on the byte code to be used in the fuzzing search. We have decided to use [AFL](https://github.com/google/AFL), an state-of-the-art fuzzer backed by Google.\n\nIf you haven't done so, you can install AFL with\n\n```bash\napt install afl\n```\n\nTo use it, set the `CC` and `CXX` environment variables to point to AFL and build the projects. We add the `--cmake-clean-cache` flag to prevent stale build files. Of course, you can use a more sofisticated way to build your projects, but make sure that the AFL's instrumentalization takes place.\n\n```bash\nexport CC=afl-gcc\nexport CXX=afl-g++\ncolcon build --cmake-clean-cache\n```\n\n### Step 7. Running the fuzzers\n\nNavigate to `install/\u003cpackage\u003e/lib/\u003cpackage\u003e/`, where `\u003cpackage\u003e` is the name of your ROS package (or wherever the installation files are placed) and start the fuzzing search.\n\nThe command requires an `inputs/` folder, with some files with content. You can use random values extracted from `/dev/urandom`, for instance:\n\n```bash\nmkdir inputs\nhead -c 50 /dev/urandom \u003e inputs/input0.txt\n```\n\nNow execute the `afl-fuzz` command (from AFL). Use the name of the executable found in that folder (try an `ls`) as the last parameter. The example shown in step #5 would be fuzzed with the following command:\n\n```bash\nafl-fuzz -i inputs/ -o outputs/ -m none -- ./generated_fuzzer\n```\n\nYou should just change the `generated_fuzzer` execution file to yours to make AFL work.\n\n## License\n\n[MIT](https://choosealicense.com/licenses/mit/)\n\n## Acknowledgements\n\n\u003ca href=\"http://rosin-project.eu\"\u003e\n  \u003cimg src=\"http://rosin-project.eu/wp-content/uploads/rosin_ack_logo_wide.png\" alt=\"rosin_logo\" height=\"60\"\u003e\n\u003c/a\u003e\n\nSupported by ROSIN - ROS-Industrial Quality-Assured Robot Software\nComponents. More information:\n\u003ca href=\"http://rosin-project.eu\"\u003erosin-project.eu\u003c/a\u003e\n\n\u003cimg src=\"http://rosin-project.eu/wp-content/uploads/rosin_eu_flag.jpg\" alt=\"eu_flag\" height=\"45\" align=\"left\" \u003e\n\nThis project has received funding from the European Union’s Horizon\n2020 research and innovation programme under grant agreement no. 732287.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjnxf%2Fautomatic_fuzzing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjnxf%2Fautomatic_fuzzing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjnxf%2Fautomatic_fuzzing/lists"}