bslim_fuzzutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Consuming Integers in a Range to Pass to an Interface

Purpose

Provide fuzz test utilities for basic types.

Classes

• bslim::FuzzUtil: functions to create basic types from fuzz data

See also

bslim_fuzzdataview

Description

This component provides a namespace, bslim::FuzzUtil, containing functions that create fundamental and standard library types from fuzz data provided by a fuzz harness (e.g., libFuzzer).

See {http://bburl/BDEFuzzTesting} for details on how to build and run with fuzz testing enabled.

Usage

This section illustrates intended use of this component.

Example 1: Consuming Integers in a Range to Pass to an Interface

Suppose we wish to fuzz test a function with preconditions.

First, we define the TradingInterfaceUnderTest struct:

struct TradingInterfaceUnderTest {
    // This utility class provides sample functionality to demonstrate how
    // fuzz data might be used.
 
    // CLASS METHODS
    static int numEarningsAnnouncements(int year, int month)
        // Return a value containing the number of earnings announcements
        // in the specified 'year' and 'month'.  The behavior is undefined
        // unless '1950 < year < 2030' and 'month' is in '[1 .. 12]'.  Note
        // that the values here are arbitrary, and in the real-world this
        // data would be obtained from a database or an API.
    {
        BSLS_ASSERT(1950 <  year  && year  < 2030);
        BSLS_ASSERT(   1 <= month && month <=  12);
 
        if (2020 < year && 6 < month) {
            return 11;                                            // RETURN
        }
        return 6;
    }
};

Then, we need a block of raw bytes. This would normally come from a fuzz harness (e.g., the LLVMFuzzerTestOneInput entry point function from libFuzzer). Since libFuzzer is not available here, we initialize a myFuzzData array that we will use instead.

const bsl::uint8_t  myFuzzData[] = {0x43, 0x19, 0x0D, 0x44, 0x37, 0x0D,
                                    0x38, 0x5E, 0x9B, 0xAA, 0xF3, 0xDA};

Next, we create a FuzzDataView to wrap the raw bytes.

bslim::FuzzDataView fdv(myFuzzData, sizeof myFuzzData);

Now, we pass this FuzzDataView to FuzzUtil to generate values within the permissible range of the function under test:

int month = bslim::FuzzUtil::consumeNumberInRange<int>(&fdv,    1,   12);
int year  = bslim::FuzzUtil::consumeNumberInRange<int>(&fdv, 1951, 2029);
assert(   1 <= month && month <=   12);
assert(1951 <= year  && year  <= 2029);

Finally, we can use these int values to pass to a function that returns the number of earnings announcements scheduled in a given month.

int numEarnings =
    TradingInterfaceUnderTest::numEarningsAnnouncements(year, month);
(void) numEarnings;