From patchwork Fri Jun 21 14:21:02 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bhargava Shastry X-Patchwork-Id: 1120324 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=openvswitch.org (client-ip=140.211.169.12; helo=mail.linuxfoundation.org; envelope-from=ovs-dev-bounces@openvswitch.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="okRIVMlT"; dkim-atps=neutral Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 45Vgpv1wKDz9s5c for ; Sat, 22 Jun 2019 00:21:26 +1000 (AEST) Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id C54CCF4A; Fri, 21 Jun 2019 14:21:23 +0000 (UTC) X-Original-To: ovs-dev@openvswitch.org Delivered-To: ovs-dev@mail.linuxfoundation.org Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id A4CD3F45 for ; Fri, 21 Jun 2019 14:21:22 +0000 (UTC) X-Greylist: whitelisted by SQLgrey-1.7.6 Received: from mail-wr1-f46.google.com (mail-wr1-f46.google.com [209.85.221.46]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 4E3677DB for ; Fri, 21 Jun 2019 14:21:21 +0000 (UTC) Received: by mail-wr1-f46.google.com with SMTP id r16so6747596wrl.11 for ; Fri, 21 Jun 2019 07:21:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id; bh=tHHEzJGBMXfjginjtHVkfzCxXuNXaso3F9d0J6tgH9M=; b=okRIVMlTOazG63NekJLxL9Y85vE/sA1b35H88gFyurMpmyjNzC5fNxVeP9qHcONle1 KHSpzufUK/Ey+gi8qsUrO193VsyA6tFnFZAueBmgzifKlHCc2ECXaW7tgvCMC0PreaeN REfW+UD612CWgx9hREMxyW01Ld5twwGVtuJjxvlRdlgLSXrruC4r7ZxQFLD0V/itXrcg gMZJ/ka1IpErUh/0WzhSEjmrhYMDl8Tx6qSYaFR8OA1d1PkjoLuF9SHorzVLTG2QsSQy lujHLi0KRgGy74O0/sjIPkwQERNLmT3JSsdbrFSaIyUrU3V2hyd5H3xV+8F9tJpuPJPZ CUDg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=tHHEzJGBMXfjginjtHVkfzCxXuNXaso3F9d0J6tgH9M=; b=PwLZ2/RAG33WRDcPMJAV+zjRT9UfucCAxMBDnlRCZl7IPwzRV9pyBR7IdqvuwaF//l g9zxoGBBxpPkwt8Q1LPR2WWNqqyRkhvbYxeaoRDQt4yDnCB344NDeUSHR1EXsIPugg9q CQ2jedStWkfKfCeJEYj942giO641r0zWG00Yn+gkIMs17XTBRcrvlZ/A59/VnwnvU2M8 tv4zR6yV2B3rjiHbmXiASMAeI3UaxpmU/XbYhv0t96o0wWJs5XwuNRG0cr95xqBZL8Oj M9XROvdemZzBJqLNzUHjAe3jxIE42aptTbCJ2o0IPyckQMLdZGlrjWlpPGBB01or+CrE Tjqg== X-Gm-Message-State: APjAAAXhMWeLuco1jn1OmDOlNuIykemp8k23ZLWzXgY+yLaWf6l5XvOy P1s18uW5MJCknq51qXVR+lhMBdVUO8g= X-Google-Smtp-Source: APXvYqwu5ohULVmi9V8bxqXxQKO0P51gZUJsh3I6MneMa8Z0QwR1ziQv9dMW/aSPYr4av4X4Xj5ckQ== X-Received: by 2002:adf:dc81:: with SMTP id r1mr13435408wrj.298.1561126879575; Fri, 21 Jun 2019 07:21:19 -0700 (PDT) Received: from x270.Speedport_W_724V_09011603_06_003 (p200300C0DF0AAA35D10A3706CB741B33.dip0.t-ipconnect.de. [2003:c0:df0a:aa35:d10a:3706:cb74:1b33]) by smtp.gmail.com with ESMTPSA id y17sm4355282wrg.18.2019.06.21.07.21.18 (version=TLS1_3 cipher=AEAD-AES256-GCM-SHA384 bits=256/256); Fri, 21 Jun 2019 07:21:18 -0700 (PDT) From: bshas3@gmail.com To: ovs-dev@openvswitch.org Date: Fri, 21 Jun 2019 16:21:02 +0200 Message-Id: <20190621142102.20284-1-bshas3@gmail.com> X-Mailer: git-send-email 2.17.1 X-Spam-Status: No, score=-1.7 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_ENVFROM_END_DIGIT,FREEMAIL_FROM, RCVD_IN_DNSWL_NONE autolearn=no version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org Cc: Bhargava Shastry Subject: [ovs-dev] [PATCH v2] ossfuzz: Add documentation X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org From: Bhargava Shastry [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 --- 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 + + 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 + + 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 followed by a +, 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 + + 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: + * .options: Defines configuration options for the fuzzer +that apply while fuzzing `fuzzer_target_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 + + 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 + + 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