You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
An automatic fuzzing tool for ROS 2 C++ projects. The tool comprises two different commands: `auto_detector` and `ros2_fuzzer`.
12
12
13
13
## Installation
14
14
15
-
TODO (pending to be published at pip). Meanwhile execute `pip install .` at the ros2_automatic_fuzzer folder.
15
+
Install the `ros_automatic_fuzzer` folder with pip:
16
16
17
17
```bash
18
-
pip install ros2_fuzzer
18
+
pip3 install -e ros2_automatic_fuzzer
19
19
```
20
20
21
+
Alternatively, start the `start.sh` command, which spawn a Docker container with both the examples and the tool.
22
+
21
23
## Usage
22
24
23
25
1. Navigate to your ROS working space.
@@ -35,13 +37,16 @@ Check the following sections for detailed instructions for each step.
35
37
The `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.
36
38
37
39
Optional arguments:
38
-
*`--path PATH`. The path where to search for ROS artifacts. By default it is the working directory.
40
+
41
+
-`--path PATH`. The path where to search for ROS artifacts. By default it is the working directory.
39
42
40
43
Optional flags:
41
-
*`-f` or `--overwrite` to force overwriting the file.
42
-
*`-v` or `--verbose` to increase the output verbosity.
44
+
45
+
-`-f` or `--overwrite` to force overwriting the file.
46
+
-`-v` or `--verbose` to increase the output verbosity.
43
47
44
48
Typical bash invocation:
49
+
45
50
```bash
46
51
auto_detector
47
52
```
@@ -52,10 +57,10 @@ The `fuzz.yaml` file contains descriptions for topics, services, and action serv
52
57
53
58
The 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:
54
59
55
-
*`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.
56
-
*`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.
57
-
*`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`.
58
-
*`parameters` (optional). A list with all the parameters of the artifact. It can be inferred with the `auto_detector` command.
60
+
-`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.
61
+
-`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.
62
+
-`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`.
63
+
-`parameters` (optional). A list with all the parameters of the artifact. It can be inferred with the `auto_detector` command.
59
64
60
65
Follows 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.
61
66
@@ -90,20 +95,25 @@ services:
90
95
It 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.
91
96
92
97
Optional arguments:
93
-
* `--path PATH`. The path where to search for a `fuzz.yaml` file. By default it is on the working directory.
98
+
99
+
- `--path PATH`. The path where to search for a `fuzz.yaml` file. By default it is on the working directory.
94
100
95
101
Optional flags:
96
-
* `-v` or `--verbose` to increase the output verbosity.
102
+
103
+
- `-v`or `--verbose` to increase the output verbosity.
97
104
98
105
Typical bash invocation:
106
+
99
107
```bash
100
108
ros2_fuzzer
101
109
```
102
110
103
111
### Step 5. Adding the fuzzers to the `CMakeLists.txt` files
112
+
104
113
The `ros2_fuzzer` command generates files of the `*_generated.cpp` form, which have to be linked to their `CMakeList.txt` files to be compiled.
105
114
106
115
For example, for the following `fuzz.yaml` file:
116
+
107
117
```yaml
108
118
services:
109
119
add_three_ints:
@@ -117,11 +127,12 @@ The following code can be added into its `CMakeLists.txt` file (the `generated_f
To 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.
126
137
127
138
If you haven't done so, you can install AFL with
@@ -133,12 +144,13 @@ apt install afl
133
144
To 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.
134
145
135
146
```bash
136
-
export CC=afl-gcc
147
+
export CC=afl-gcc
137
148
export CXX=afl-g++
138
149
colcon build --cmake-clean-cache
139
150
```
140
151
141
152
### Step 7. Running the fuzzers
153
+
142
154
Navigate to `install/<package>/lib/<package>/`, where `<package>` is the name of your ROS package (or wherever the installation files are placed) and start the fuzzing search.
143
155
144
156
The command requires an `inputs/` folder, with some files with content. You can use random values extracted from `/dev/urandom`, for instance:
0 commit comments