[ovs-dev] [PATCH] ossfuzz: Add documentation
bshas3 at gmail.com
bshas3 at gmail.com
Fri Jun 21 12:55:39 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..f8192bc33
--- /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 may be found
+`https://github.com/google/oss-fuzz/blob/master/projects/openvswitch/Dockerfile`.
+
+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
\ No newline at end of file
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..eb2401b9d
--- /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 (switch to controller) Trusted
+ ofctl_parse_target Management Trusted
+ ofp_print_target South/North-bound (between switch and controller) Trusted
\ No newline at end of file
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