[ovs-dev] ossfuzz: Add documentation
diff mbox series

Message ID 20190621125539.17677-1-bshas3@gmail.com
State Accepted
Headers show
Series
  • [ovs-dev] ossfuzz: Add documentation
Related show

Commit Message

bshas3@gmail.com June 21, 2019, 12:55 p.m. UTC
From: Bhargava Shastry <bshas3@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@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

Comments

0-day Robot June 21, 2019, 1:58 p.m. UTC | #1
Bleep bloop.  Greetings , I am a robot and I have tried out your patch.
Thanks for your contribution.

I encountered some error that I wasn't expecting.  See the details below.


checkpatch:
WARNING: Line is 81 characters long (recommended limit is 79)
#275 FILE: Documentation/fuzzing/ovs-fuzzing-infrastructure.rst:57:
`https://github.com/google/oss-fuzz/blob/master/projects/openvswitch/Dockerfile`.

WARNING: Line is 83 characters long (recommended limit is 79)
#361 FILE: Documentation/fuzzing/security-analysis-of-ovs-fuzzers.rst:41:
    odp_target                  North-bound (switch to controller)          Trusted

WARNING: Line is 91 characters long (recommended limit is 79)
#363 FILE: Documentation/fuzzing/security-analysis-of-ovs-fuzzers.rst:43:
    ofp_print_target            South/North-bound (between switch and controller)   Trusted

Lines checked: 420, Warnings: 3, Errors: 0


build:
reading sources... [ 88%] topics/ovsdb-replication
reading sources... [ 88%] topics/porting
reading sources... [ 89%] topics/role-based-access-control
reading sources... [ 90%] topics/testing
reading sources... [ 91%] topics/tracing
reading sources... [ 92%] topics/windows
reading sources... [ 93%] tutorials/faucet
reading sources... [ 94%] tutorials/index
reading sources... [ 94%] tutorials/ipsec
reading sources... [ 95%] tutorials/ovn-ipsec
reading sources... [ 96%] tutorials/ovn-openstack
reading sources... [ 97%] tutorials/ovn-rbac
reading sources... [ 98%] tutorials/ovn-sandbox
reading sources... [ 99%] tutorials/ovs-advanced
reading sources... [100%] tutorials/ovs-conntrack


Warning, treated as error:
/var/lib/jenkins/jobs/upstream_build_from_pw/workspace/Documentation/fuzzing/ovs-fuzzers.rst:40: ERROR: Unexpected indentation.

make[2]: *** [docs-check] Error 1
make[2]: Leaving directory `/var/lib/jenkins/jobs/upstream_build_from_pw/workspace'
make[1]: *** [all-recursive] Error 1
make[1]: Leaving directory `/var/lib/jenkins/jobs/upstream_build_from_pw/workspace'
make: *** [all] Error 2


Please check this out.  If you feel there has been an error, please email aconole@bytheb.org

Thanks,
0-day Robot

Patch
diff mbox series

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@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@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@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@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@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