From patchwork Fri Jun 21 12:55:39 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bhargava Shastry X-Patchwork-Id: 1120219 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="N03Gr5x8"; 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 45VdwP2xBfz9s3l for ; Fri, 21 Jun 2019 22:56:04 +1000 (AEST) Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id 4E0A1E4D; Fri, 21 Jun 2019 12:56:02 +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 6B756E3E for ; Fri, 21 Jun 2019 12:56:01 +0000 (UTC) X-Greylist: whitelisted by SQLgrey-1.7.6 Received: from mail-wr1-f43.google.com (mail-wr1-f43.google.com [209.85.221.43]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 0AAAD7DB for ; Fri, 21 Jun 2019 12:55:59 +0000 (UTC) Received: by mail-wr1-f43.google.com with SMTP id f9so6448396wre.12 for ; Fri, 21 Jun 2019 05:55:59 -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=f0k9emhMhNxOt4MqWekA8Q2JVoqgSj6CPos5/Ez7y+k=; b=N03Gr5x8LUVBJ+rAnmjzFuFB0ZI/+cgEjaYNnKCErvKNsrN16R908jUTITRRXjI3K6 Uw/r77mXxDQ08IRw1XABxhdQBhYhRsLMm2aHFcv5AsDL2sPfWC/4hFNTYR6HpHAoR/4C Pde3CA9CcMGGW3G8V6OclRKMw6eAnJF3JCtmQrEHpZmjxE8T9HY38B1W/5Q53UN20JQd XHw/85fEHgTbjh+4mLjS3WTODcaLydWyn0vMnz7VHW64zPK1g2cJb2Fo2c8jPLLy0usj UUgey4XcxOtJoyrYq6fNlLJLNfkzu5TCDrxk1VqMMlX1v798k08WJ1qwP0wNxFU4Q4RY DmXg== 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=f0k9emhMhNxOt4MqWekA8Q2JVoqgSj6CPos5/Ez7y+k=; b=mN0yyp0sKT49NrSe5oBTRpCy8Kn9wGNX3SAIgs24vW+tEdeIk3johcsir95RsinOQ0 O3mBooiPIoAuy/+UaNl2t6hmeEe5k3irydr3Lv4rHDVj6aCZX8G2sfN0VLtLPc2ij+GA 2C6g9xaR9HxJfQni1EGyP+ptV3mR5UDWf8Ft/10ug4Duf+qf+O0VfHhlK0juzkSY/a+U sW8GAHMIqb9PFpby0HQu8/lqfBRQCP/axgf4IX/wpweAZjIewqj3INr32GujBtig4sXt 1532cRRTxRpbbC3eHxN2ggON0ggpZeWl6D+zI4dY6dQty2hRjosOLYHcKW/79CVDzia+ 8MlQ== X-Gm-Message-State: APjAAAWxxAg95Ld27A91jbSo8ktrYv1o03ZdBkTcHBXmLDNxeo3qFlgb NgXmUXvzWcUXb9mmT54A7v+1kWH/3ms= X-Google-Smtp-Source: APXvYqwTCW2M+O+1g/FEBZu6Fm70sD8et05IOH0lqhhvDrQkFgEwlLnQ6BfI+aVkqxeNSgYtnXc+CA== X-Received: by 2002:a5d:5286:: with SMTP id c6mr84187707wrv.118.1561121758344; Fri, 21 Jun 2019 05:55:58 -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 q21sm2691161wmq.13.2019.06.21.05.55.57 (version=TLS1_3 cipher=AEAD-AES256-GCM-SHA384 bits=256/256); Fri, 21 Jun 2019 05:55:57 -0700 (PDT) From: bshas3@gmail.com To: ovs-dev@openvswitch.org Date: Fri, 21 Jun 2019 14:55:39 +0200 Message-Id: <20190621125539.17677-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] 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..f8192bc33 --- /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 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: + * .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 \ 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 + + 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 + + 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