[ovs-dev] [PATCH v2] ossfuzz: Add documentation

bshas3 at gmail.com bshas3 at gmail.com
Fri Jun 21 14:21:02 UTC 2019


From: Bhargava Shastry <bshas3 at gmail.com>

[RFC] Documents OvS fuzzing effort and performs a rudimentary security
analysis of existing OvS fuzzing harnesses.

Feedback on the documentation and analysis appreciated.

Signed-off-by: Bhargava Shastry <bshas3 at gmail.com>
---
 Documentation/automake.mk                     |   5 +
 Documentation/fuzzing/index.rst               |  39 ++++++
 Documentation/fuzzing/ovs-fuzzers.rst         | 119 ++++++++++++++++++
 .../fuzzing/ovs-fuzzing-infrastructure.rst    |  95 ++++++++++++++
 .../security-analysis-of-ovs-fuzzers.rst      |  43 +++++++
 Documentation/fuzzing/what-is-fuzzing.rst     |  46 +++++++
 6 files changed, 347 insertions(+)
 create mode 100644 Documentation/fuzzing/index.rst
 create mode 100644 Documentation/fuzzing/ovs-fuzzers.rst
 create mode 100644 Documentation/fuzzing/ovs-fuzzing-infrastructure.rst
 create mode 100644 Documentation/fuzzing/security-analysis-of-ovs-fuzzers.rst
 create mode 100644 Documentation/fuzzing/what-is-fuzzing.rst

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 082438e09..807236ac4 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -114,6 +114,11 @@ DOC_SOURCE = \
 	Documentation/internals/contributing/documentation-style.rst \
 	Documentation/internals/contributing/libopenvswitch-abi.rst \
 	Documentation/internals/contributing/submitting-patches.rst \
+	Documentation/fuzzing/index.rst \
+	Documentation/fuzzing/what-is-fuzzing.rst \
+	Documentation/fuzzing/ovs-fuzzing-infrastructure.rst \
+	Documentation/fuzzing/ovs-fuzzers.rst \
+	Documentation/fuzzing/security-analysis-of-ovs-fuzzers.rst \
 	Documentation/requirements.txt \
 	$(addprefix Documentation/ref/,$(RST_MANPAGES) $(RST_MANPAGES_NOINST))
 FLAKE8_PYFILES += Documentation/conf.py
diff --git a/Documentation/fuzzing/index.rst b/Documentation/fuzzing/index.rst
new file mode 100644
index 000000000..29480dfe5
--- /dev/null
+++ b/Documentation/fuzzing/index.rst
@@ -0,0 +1,39 @@
+..
+      Copyright (c) 2016, Stephen Finucane <stephen at that.guru>
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+===============
+Introduction
+===============
+
+How to get started with Open vSwitch.
+
+.. toctree::
+   :maxdepth: 2
+
+   what-is-fuzzing
+   ovs-fuzzing-infrastructure
+   ovs-fuzzers
+   security-analysis-of-ovs-fuzzers
+
diff --git a/Documentation/fuzzing/ovs-fuzzers.rst b/Documentation/fuzzing/ovs-fuzzers.rst
new file mode 100644
index 000000000..8ed3b53ed
--- /dev/null
+++ b/Documentation/fuzzing/ovs-fuzzers.rst
@@ -0,0 +1,119 @@
+..
+      Copyright (c) 2016, Stephen Finucane <stephen at that.guru>
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+============
+Introduction
+============
+
+OvS fuzzer test harnesses define the libFuzzer fuzz API. In doing so,
+they define what is to be done with the input supplied by the fuzzer.
+
+At a minimum, the libfuzzer API is defined as follows:
+
+```
+// input_ is a byte array, size is the length of said byte array
+int
+LLVMFuzzerTestOneInput(const uint8_t *input, size_t size)
+{
+    // Input processing
+    process_input(input, size);
+
+    // Must always return 0. Non-zero return codes are reserved by libFuzzer.
+    return 0;
+}
+```
+
+In certain scenarios, it may be necessary to constrain the input supplied by
+the fuzzer. One scenario is when `process_input` accepts a C string. One
+way to do this would be as follows:
+
+```
+// input_ is a byte array, size is the length of said byte array
+int
+LLVMFuzzerTestOneInput(const uint8_t *input, size_t size)
+{
+    // Constrain input
+    // Check if input is null terminated
+    const char *cstring = (const char*) input;
+    if (cstring[size - 1] != '\0')
+        return 0;
+
+    // Input processing
+    process_input(cstring);
+
+    // Must always return 0. Non-zero return codes are reserved by libFuzzer.
+    return 0;
+}
+```
+
+OvS fuzzer test harnesses are located in the `tests/oss-fuzz` sub-directory.
+At the time of writing, there are a total of six harnesses:
+  * `flow_extract_target.c`
+  * `json_parser_target.c`
+  * `miniflow_target.c`
+  * `odp_target.c`
+  * `ofctl_parse_target.c`
+  * `ofp_print_target.c`
+
+--------------------
+flow_extract_target
+--------------------
+
+Extracts flow from and parses fuzzer supplied packet payload.
+
+--------------------
+json_parser_target
+--------------------
+
+Parses fuzzer supplied string as JSON, encoding the parsed JSON
+into a JSON RPC message, and finally decoding the encoded JSON
+ RPC message back to JSON.
+
+--------------------
+miniflow_target
+--------------------
+
+Extracts flow from fuzzer supplied packet payload, converts flow
+to a miniflow and performs various miniflow operations.
+
+--------------------
+odp_target
+--------------------
+
+Parses fuzzer supplied string as an ODP flow, and the same string as
+an ODP action.
+
+--------------------
+ofctl_parse_target
+--------------------
+
+Treats fuzzer supplied input as a <flow_command> followed by a
+<flow_mod_string>, invoking the `parse_ofp_flow_mod_str` on the pair.
+
+--------------------
+ofp_print_target
+--------------------
+
+Parses fuzzer supplied data as an Open Flow Protocol buffer.
\ No newline at end of file
diff --git a/Documentation/fuzzing/ovs-fuzzing-infrastructure.rst b/Documentation/fuzzing/ovs-fuzzing-infrastructure.rst
new file mode 100644
index 000000000..780ecdcf3
--- /dev/null
+++ b/Documentation/fuzzing/ovs-fuzzing-infrastructure.rst
@@ -0,0 +1,95 @@
+..
+      Copyright (c) 2016, Stephen Finucane <stephen at that.guru>
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+============
+Introduction
+============
+
+Open vSwitch is enrolled in the oss-fuzz program. oss-fuzz is a free continuous
+fuzzing service and infrastructure offered by Google. An enrolled project is
+continually fuzzed and bug reports are sent to maintainers as and when they
+are generated.
+
+The technical requirements to enrol OvS in oss-fuzz program are:
+  * Dockerfile (hosted in Google's ossfuzz GitHub repo)
+  * Bash build script (hosted in Google's ossfuzz GitHub repo)
+
+Each of these requirements is explained in the following paragraphs.
+
+-----------
+Dockerfile
+-----------
+
+Dockerfile defines the box in which OvS will be built by oss-fuzz builder bots.
+This file must be self sufficient in that it must define a build environment in
+which OvS can be built from source code.
+
+The build environment comprises
+  * Linux box provided by Google (Ubuntu)
+  * Packages required to build OvS (e.g., libssl-dev python etc.)
+  * Source code of OvS (fetched by oss-fuzz builder bots from OvS'
+   GitHub mirror on a daily basis)
+  * Build script written in Bash
+
+The Dockerfile definition for OvS is located in the
+`projects/openvswitch/Dockerfile` sub-directory of Google's oss-fuzz repo.
+
+Build script
+------------
+
+The build script defines steps required to compile OvS from source code.
+The (Linux) box used by oss-fuzz builder bots (defined by Dockerfile) is
+different from the box in which fuzzing actually happens. It follows that
+the build script must ensure that fuzzing binaries are linked statically so
+that no assumption is made about packages available in the fuzzing box.
+
+OvS contains a make target called `oss-fuzz-targets` for compiling and linking
+OvS fuzzer binaries. The line of bash script responsible for building
+statically linked OvS fuzzing binaries is the following:
+
+```
+./boot.sh && ./configure && make -j$(nproc) && make oss-fuzz-targets
+```
+
+The oss-fuzz build environment assumes that OvS build system respects
+compiler/linker flags defined via standard bash environment variables called
+`CFLAGS`, `CXXFLAGS` etc. The oss-fuzz builder bot defines these flags so
+that OvS fuzzing binaries are correctly instrumented.
+
+oss-fuzz expects all fuzzing binaries, and optionally, configuration and
+seed inputs to be located in a hard-coded directory, referenced by the bash
+variable `$OUT`, in the root filesystem of the build box.
+
+OvS source repo contains configuration for the oss-fuzz fuzzers in the
+`tests/oss-fuzz/config` sub-directory. There are two types of configuration
+files:
+  * <fuzzer_target_name>.options: Defines configuration options for the fuzzer
+that apply while fuzzing `fuzzer_target_name`
+  * <name>.dict: Defines a dictionary to be used for some `fuzzer_target_name`
+
+Fuzzer configuration parameters of relevance to OvS are:
+  * dict: names the dictionary file to be used for fuzzing
+  * close_fd_mask: defines a file descriptor mask that filters console output
+generated by OvS fuzzing binaries
diff --git a/Documentation/fuzzing/security-analysis-of-ovs-fuzzers.rst b/Documentation/fuzzing/security-analysis-of-ovs-fuzzers.rst
new file mode 100644
index 000000000..f4a0e7ba8
--- /dev/null
+++ b/Documentation/fuzzing/security-analysis-of-ovs-fuzzers.rst
@@ -0,0 +1,43 @@
+..
+      Copyright (c) 2016, Stephen Finucane <stephen at that.guru>
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+============
+Introduction
+============
+
+OvS fuzzer harnesses test different components of OvS. This document
+performs a security analysis of these harnesses. The intention is to
+not only tabulate what is currently done but also to help expand
+on the set of harnesses.
+
+    ================= ============== ==============
+    Fuzzer harness    Interface      Input source
+    ================= ============== ==============
+    flow_extract_target         External            Untrusted
+    json_parser_target          OVS DB              Trusted
+    miniflow_target             External            Untrusted
+    odp_target                  North-bound         Trusted
+    ofctl_parse_target          Management          Trusted
+    ofp_print_target            South/North-bound   Trusted
diff --git a/Documentation/fuzzing/what-is-fuzzing.rst b/Documentation/fuzzing/what-is-fuzzing.rst
new file mode 100644
index 000000000..529ba07ba
--- /dev/null
+++ b/Documentation/fuzzing/what-is-fuzzing.rst
@@ -0,0 +1,46 @@
+..
+      Copyright (c) 2016, Stephen Finucane <stephen at that.guru>
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+============
+Introduction
+============
+
+
+Usually, software teams do functional testing (which is great) but not
+ security testing of their code. For example:
+
+```
+func_add(int x, int y) { return x+y; }
+```
+may have a unit test like so:
+
+```
+ASSERT((func_add(4,5)==9))
+```
+However, corner cases are usually not tested so that `x=INT_MAX; y=1`
+ demonstrates a problem in the implementation.
+
+Fuzz testing is routinely used to probabilistically generate such corner
+cases and feed them to program APIs to test their behavior.
\ No newline at end of file
-- 
2.17.1



More information about the dev mailing list