From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.5 required=3.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,HK_RANDOM_FROM,INCLUDES_PATCH, MAILING_LIST_MULTI,MSGID_FROM_MTA_HEADER,SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 2C181C34031 for ; Thu, 20 Feb 2020 04:21:19 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id EA5162465D for ; Thu, 20 Feb 2020 04:21:18 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=bushare.onmicrosoft.com header.i=@bushare.onmicrosoft.com header.b="70G1nhXg" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org EA5162465D Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=bu.edu Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:35896 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j4dKw-0004T0-5r for qemu-devel@archiver.kernel.org; Wed, 19 Feb 2020 23:21:18 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:45241) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j4dBw-00051V-4v for qemu-devel@nongnu.org; Wed, 19 Feb 2020 23:12:01 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j4dBu-00060z-MO for qemu-devel@nongnu.org; Wed, 19 Feb 2020 23:12:00 -0500 Received: from mail-co1nam11on2117.outbound.protection.outlook.com ([40.107.220.117]:50663 helo=NAM11-CO1-obe.outbound.protection.outlook.com) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1j4dBu-00060B-F3 for qemu-devel@nongnu.org; Wed, 19 Feb 2020 23:11:58 -0500 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Grude3XhKwyny0DWEHYbYkMKZU5YqpNJHFQdrpvVPJl6YtuCYXXPFdjSEZyV3uL+X6HWdSAzlb69Khy8FOnGKpetTpNgfMtc8MlzrPYwGaa49K1Z73HSs3ipAphilSmRcb5buKwIvQkgekZbxMfFXPf1NRB8O8rTMfhz+1E0BXoIixvciyVBsUrlRZ7hbmbYwGe43e6rkPZDxyghyey0OsMSXClomaKqTpUqkVhxNC6OQ03g0UWltgE6h6qsbJe01DiTtd974176ItQ9M+cX2zZZIls9t3xA3Aqv/7VUjfPU7E4pKkAPNasrkHxKPx7nMmXGxOXWpzAepys438r5gA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=cktvTDTXYe8uMVWK4Z54RXGzV2P4V9b7TT+6HraiB48=; b=Up/Bu3v10+GjdpvfwlnLn6fd2wx8zAzFbtRKEorc+JAjnllCcvK6dJNMh9UuX2x40WKNRxZjx3w9kyrHgxs6qFtEf25GEcTvG+AzcBS54aV1PPPb81Y2ejiAACtn3Wz+1VF6nn3OFelydYR2p1qwf+CyI+r67kTyqubxAcNpzCtgFnp9cS7O6HkM6KOEaaQusm2qryH+pduSEIn6XyTCqvRcNXkAtwdinD/Y9NOYIVQw/sGAwgPDOT+lEJdF2ZIN1V+01Y/Fc25hqAZMiPPX56RpJNV9EIjkTlK81SUOBrPGRKGXk8u+KqqCJKrox32zofr+JBNFhIRAsuAAFto7JA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=bu.edu; dmarc=pass action=none header.from=bu.edu; dkim=pass header.d=bu.edu; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bushare.onmicrosoft.com; s=selector2-bushare-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=cktvTDTXYe8uMVWK4Z54RXGzV2P4V9b7TT+6HraiB48=; b=70G1nhXgzxFTT8ABgDhZhzyKZ92WRkp4UJPJ7XYcgeyir0WWRLYZ+gdpKdIAzcnwx2jrHSzd4MTZBkVnYHuBoRE7G3AzeHVYMsDoQcgeFHGI9XYFWHLWeOnCZ30Ice5n9pmjkSsBdtCSBv/k5dUMG2Y7naanAQR8d4h+GvDzhxM= Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=alxndr@bu.edu; Received: from SN6PR03MB3871.namprd03.prod.outlook.com (2603:10b6:805:6d::32) by SN6PR03MB3807.namprd03.prod.outlook.com (2603:10b6:805:6a::20) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.2729.22; Thu, 20 Feb 2020 04:11:57 +0000 Received: from SN6PR03MB3871.namprd03.prod.outlook.com ([fe80::9c11:10cd:6e97:bbe8]) by SN6PR03MB3871.namprd03.prod.outlook.com ([fe80::9c11:10cd:6e97:bbe8%7]) with mapi id 15.20.2729.033; Thu, 20 Feb 2020 04:11:57 +0000 From: Alexander Bulekov To: qemu-devel@nongnu.org Subject: [PATCH v10 22/22] fuzz: add documentation to docs/devel/ Date: Wed, 19 Feb 2020 23:11:18 -0500 Message-ID: <20200220041118.23264-23-alxndr@bu.edu> X-Mailer: git-send-email 2.25.0 In-Reply-To: <20200220041118.23264-1-alxndr@bu.edu> References: <20200220041118.23264-1-alxndr@bu.edu> Content-Transfer-Encoding: quoted-printable Content-Type: text/plain X-ClientProxiedBy: BL0PR0102CA0048.prod.exchangelabs.com (2603:10b6:208:25::25) To SN6PR03MB3871.namprd03.prod.outlook.com (2603:10b6:805:6d::32) MIME-Version: 1.0 Received: from mozz.bu.edu (128.197.127.33) by BL0PR0102CA0048.prod.exchangelabs.com (2603:10b6:208:25::25) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.2750.17 via Frontend Transport; Thu, 20 Feb 2020 04:11:56 +0000 X-Mailer: git-send-email 2.25.0 X-Originating-IP: [128.197.127.33] X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: d07d73b3-9faf-41fc-64fb-08d7b5bb0687 X-MS-TrafficTypeDiagnostic: SN6PR03MB3807: X-MS-Exchange-Transport-Forked: True X-Microsoft-Antispam-PRVS: X-MS-Oob-TLC-OOBClassifiers: OLM:9508; X-Forefront-PRVS: 031996B7EF X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10019020)(4636009)(346002)(136003)(396003)(39860400002)(376002)(366004)(199004)(189003)(36756003)(86362001)(81166006)(75432002)(8676002)(2616005)(478600001)(81156014)(8936002)(66476007)(5660300002)(6916009)(66556008)(66946007)(956004)(316002)(786003)(6486002)(6666004)(7696005)(16526019)(186003)(26005)(4326008)(1076003)(2906002)(52116002); DIR:OUT; SFP:1102; SCL:1; SRVR:SN6PR03MB3807; H:SN6PR03MB3871.namprd03.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; A:1; MX:1; Received-SPF: None (protection.outlook.com: bu.edu does not designate permitted sender hosts) X-MS-Exchange-SenderADCheck: 1 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: 4cIzG2OeqjFow/BHVzwKsfBg8WEMxg6U90R7IxO4hxhDKq9z2tQEe1YreZ7IOB0poqKK3OP2/g5D+NT9VDsZGCypag+gwWlCeHK9DnKzGYXJlGD+X8z+2qkPTMPMT9sXaCXHhSsq4StyddnMHH4mJ1PNiPlA+msutxrGkvcJLJ1zfsEMDBWy96OuYXMZvGT/lacECvLbDAWKkhvpg4caQC1E0yGsQhC24uIHbUXmW//5cTw2NtD5hZVkk+lvQuEPUkFXnUHz5dPI5X/ca/k7wkRu8ystPBFGPJfe79+VQgiYyI5r1CZeJ7Otdi+jMi/Xh0soOaEnXxeB3QsoYjagYCtPhxUsXMV7Nk9P4u3oQzIU48/5fNKalz+1cIkRXRs1pjs4vRBpWtE1RC0NPX8leZ/q+i1x0lvSbcAmitr3CJFDsQ1+l/Ys/ny+F7Vk1U42 X-MS-Exchange-AntiSpam-MessageData: OoYnPZMSbBZnRlJbD1i4D/MI4Ac13xAZ8G6J7tQTAxC6cguRkm0vxOhcEYqdgMsV2xfK7hLBKhLeB1Bhe68sO7SeO7XbRgOuI9vME5sXkAVOKeG5qQXZU3+6o+hY46FzEmcz68DfHx90IM7VGrewFg== X-OriginatorOrg: bu.edu X-MS-Exchange-CrossTenant-Network-Message-Id: d07d73b3-9faf-41fc-64fb-08d7b5bb0687 X-MS-Exchange-CrossTenant-OriginalArrivalTime: 20 Feb 2020 04:11:57.1731 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: d57d32cc-c121-488f-b07b-dfe705680c71 X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: eHdj8Q3ghyDcf+vNRKfP4KWmkc6XmiQcIjWW7P0/ybX3xrzFAUxIzFpSU4OszJ5h X-MS-Exchange-Transport-CrossTenantHeadersStamped: SN6PR03MB3807 X-detected-operating-system: by eggs.gnu.org: Windows NT kernel [generic] [fuzzy] X-Received-From: 40.107.220.117 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Alexander Bulekov , pbonzini@redhat.com, bsd@redhat.com, stefanha@redhat.com, darren.kenny@oracle.com Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" Signed-off-by: Alexander Bulekov Reviewed-by: Stefan Hajnoczi Reviewed-by: Darren Kenny --- docs/devel/fuzzing.txt | 116 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 docs/devel/fuzzing.txt diff --git a/docs/devel/fuzzing.txt b/docs/devel/fuzzing.txt new file mode 100644 index 0000000000..324d2cd92b --- /dev/null +++ b/docs/devel/fuzzing.txt @@ -0,0 +1,116 @@ +=3D Fuzzing =3D + +=3D=3D Introduction =3D=3D + +This document describes the virtual-device fuzzing infrastructure in QEMU = and +how to use it to implement additional fuzzers. + +=3D=3D Basics =3D=3D + +Fuzzing operates by passing inputs to an entry point/target function. The +fuzzer tracks the code coverage triggered by the input. Based on these +findings, the fuzzer mutates the input and repeats the fuzzing. + +To fuzz QEMU, we rely on libfuzzer. Unlike other fuzzers such as AFL, libf= uzzer +is an _in-process_ fuzzer. For the developer, this means that it is their +responsibility to ensure that state is reset between fuzzing-runs. + +=3D=3D Building the fuzzers =3D=3D + +NOTE: If possible, build a 32-bit binary. When forking, the 32-bit fuzzer = is +much faster, since the page-map has a smaller size. This is due to the fac= t that +AddressSanitizer mmaps ~20TB of memory, as part of its detection. This res= ults +in a large page-map, and a much slower fork(). + +To build the fuzzers, install a recent version of clang: +Configure with (substitute the clang binaries with the version you install= ed): + + CC=3Dclang-8 CXX=3Dclang++-8 /path/to/configure --enable-fuzzing + +Fuzz targets are built similarly to system/softmmu: + + make i386-softmmu/fuzz + +This builds ./i386-softmmu/qemu-fuzz-i386 + +The first option to this command is: --fuzz_taget=3DFUZZ_NAME +To list all of the available fuzzers run qemu-fuzz-i386 with no arguments. + +eg: + ./i386-softmmu/qemu-fuzz-i386 --fuzz-target=3Dvirtio-net-fork-fuzz + +Internally, libfuzzer parses all arguments that do not begin with "--". +Information about these is available by passing -help=3D1 + +Now the only thing left to do is wait for the fuzzer to trigger potential +crashes. + +=3D=3D Adding a new fuzzer =3D=3D +Coverage over virtual devices can be improved by adding additional fuzzers= . +Fuzzers are kept in tests/qtest/fuzz/ and should be added to +tests/qtest/fuzz/Makefile.include + +Fuzzers can rely on both qtest and libqos to communicate with virtual devi= ces. + +1. Create a new source file. For example ``tests/qtest/fuzz/foo-device-fuz= z.c``. + +2. Write the fuzzing code using the libqtest/libqos API. See existing fuzz= ers +for reference. + +3. Register the fuzzer in ``tests/fuzz/Makefile.include`` by appending the +corresponding object to fuzz-obj-y + +Fuzzers can be more-or-less thought of as special qtest programs which can +modify the qtest commands and/or qtest command arguments based on inputs +provided by libfuzzer. Libfuzzer passes a byte array and length. Commonly = the +fuzzer loops over the byte-array interpreting it as a list of qtest comman= ds, +addresses, or values. + +=3D Implementation Details =3D + +=3D=3D The Fuzzer's Lifecycle =3D=3D + +The fuzzer has two entrypoints that libfuzzer calls. libfuzzer provides it= 's +own main(), which performs some setup, and calls the entrypoints: + +LLVMFuzzerInitialize: called prior to fuzzing. Used to initialize all of t= he +necessary state + +LLVMFuzzerTestOneInput: called for each fuzzing run. Processes the input a= nd +resets the state at the end of each run. + +In more detail: + +LLVMFuzzerInitialize parses the arguments to the fuzzer (must start with t= wo +dashes, so they are ignored by libfuzzer main()). Currently, the arguments +select the fuzz target. Then, the qtest client is initialized. If the targ= et +requires qos, qgraph is set up and the QOM/LIBQOS modules are initialized. +Then the QGraph is walked and the QEMU cmd_line is determined and saved. + +After this, the vl.c:qemu__main is called to set up the guest. There are +target-specific hooks that can be called before and after qemu_main, for +additional setup(e.g. PCI setup, or VM snapshotting). + +LLVMFuzzerTestOneInput: Uses qtest/qos functions to act based on the fuzz +input. It is also responsible for manually calling the main loop/main_loop= _wait +to ensure that bottom halves are executed and any cleanup required before = the +next input. + +Since the same process is reused for many fuzzing runs, QEMU state needs t= o +be reset at the end of each run. There are currently two implemented +options for resetting state: +1. Reboot the guest between runs. + Pros: Straightforward and fast for simple fuzz targets. + Cons: Depending on the device, does not reset all device state. If the + device requires some initialization prior to being ready for fuzzing + (common for QOS-based targets), this initialization needs to be done af= ter + each reboot. + Example target: i440fx-qtest-reboot-fuzz +2. Run each test case in a separate forked process and copy the coverage + information back to the parent. This is fairly similar to AFL's "deferr= ed" + fork-server mode [3] + Pros: Relatively fast. Devices only need to be initialized once. No nee= d + to do slow reboots or vmloads. + Cons: Not officially supported by libfuzzer. Does not work well for dev= ices + that rely on dedicated threads. + Example target: virtio-net-fork-fuzz --=20 2.25.0