Android 12.1.0 release 25
[automerger skipped] Mark ab/7061308 as merged in stage. am: 9e21264e25 -s ours am: 102378d8ce -s ours

am skip reason: Change-Id Ia1cd62c93d0f9a40e908f8cc96b4687dc4a7b2c7 with SHA-1 e4886f2221 is in history

Original change: undetermined

MUST ONLY BE SUBMITTED BY AUTOMERGER

Change-Id: I993c2136dce54cc3ea39e4e883a147c4a22e7160
tree: f6e1e64a91647161c26338b6205f3f9655476a01
  1. cmake/
  2. examples/
  3. port/
  4. src/
  5. .clang-format
  6. .gitignore
  7. .travis.yml
  8. Android.bp
  9. AUTHORS
  10. CMakeLists.txt
  11. CONTRIBUTING
  12. libprotobuf-mutator.pc.in
  13. libprotobuf-mutatorConfig.cmake.in
  14. LICENSE
  15. METADATA
  16. MODULE_LICENSE_APACHE2
  17. OWNERS
  18. README.md
README.md

libprotobuf-mutator

TravisCI Build Status Fuzzing Status

Overview

libprotobuf-mutator is a library to randomly mutate protobuffers.
It could be used together with guided fuzzing engines, such as libFuzzer.

Quick start on Debian/Ubuntu

Install prerequisites:

sudo apt-get update
sudo apt-get install protobuf-compiler libprotobuf-dev binutils cmake \
  ninja-build liblzma-dev libz-dev pkg-config autoconf libtool

Compile and test everything:

mkdir build
cd build
cmake .. -GNinja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Debug
ninja check

Clang is only needed for libFuzzer integration.
By default, the system-installed version of protobuf is used. However, on some systems, the system version is too old. You can pass LIB_PROTO_MUTATOR_DOWNLOAD_PROTOBUF=ON to cmake to automatically download and build a working version of protobuf.

Installation:

ninja
sudo ninja install

This installs the headers, pkg-config, and static library. By default the headers are put in /usr/local/include/libprotobuf-mutator.

Usage

To use libprotobuf-mutator simply include mutator.h and mutator.cc into your build files.

The ProtobufMutator class implements mutations of the protobuf tree structure and mutations of individual fields. The field mutation logic is very basic -- for better results you should override the ProtobufMutator::Mutate* methods with more sophisticated logic, e.g. using libFuzzer's mutators.

To apply one mutation to a protobuf object do the following:

class MyProtobufMutator : public protobuf_mutator::Mutator {
 public:
  // Optionally redefine the Mutate* methods to perform more sophisticated mutations.
}
void Mutate(MyMessage* message) {
  MyProtobufMutator mutator;
  mutator.Seed(my_random_seed);
  mutator.Mutate(message, 200);
}

See also the ProtobufMutatorMessagesTest.UsageExample test from mutator_test.cc.

Integrating with libFuzzer

LibFuzzerProtobufMutator can help to integrate with libFuzzer. For example

#include "src/libfuzzer/libfuzzer_macro.h"

DEFINE_PROTO_FUZZER(const MyMessageType& input) {
  // Code which needs to be fuzzed.
  ConsumeMyMessageType(input);
}

Please see libfuzzer_example.cc as an example.

Mutation post-processing (experimental)

Sometimes it‘s necessary to keep particular values in some fields without which the proto is going to be rejected by fuzzed code. E.g. code may expect consistency between some fields or it may use some fields as checksums. Such constraints are going to be significant bottleneck for fuzzer even if it’s capable of inserting acceptable values with time.

PostProcessorRegistration can be used to avoid such issue and guide your fuzzer towards interesting code. It registers callback which will be called for each message of particular type after each mutation.

static protobuf_mutator::libfuzzer::PostProcessorRegistration<MyMessageType> reg = {
    [](MyMessageType* message, unsigned int seed) {
      TweakMyMessage(message, seed);
    }};

DEFINE_PROTO_FUZZER(const MyMessageType& input) {
  // Code which needs to be fuzzed.
  ConsumeMyMessageType(input);
}

Optional: Use seed if callback uses random numbers. It may help later with debugging.

Important: Callbacks should be deterministic and avoid modifying good messages. Callbacks are called for both: mutator generated and user provided inputs, like corpus or bug reproducer. So if callback performs unnecessary transformation it may corrupt the reproducer so it stops triggering the bug.

Note: You can add callback for any nested message and you can add multiple callbacks for the same message type.

DEFINE_PROTO_FUZZER(const MyMessageType& input) {
  static PostProcessorRegistration reg1 = {
      [](MyMessageType* message, unsigned int seed) {
        TweakMyMessage(message, seed);
      }};
  static PostProcessorRegistration reg2 = {
      [](MyMessageType* message, unsigned int seed) {
        DifferentTweakMyMessage(message, seed);
      }};
  static PostProcessorRegistration reg_nested = {
      [](MyMessageType::Nested* message, unsigned int seed) {
        TweakMyNestedMessage(message, seed);
      }};

  // Code which needs to be fuzzed.
  ConsumeMyMessageType(input);
}

UTF-8 strings

“proto2” and “proto3” handle invalid UTF-8 strings differently. In both cases string should be UTF-8, however only “proto3” enforces that. So if fuzzer is applied to “proto2” type libprotobuf-mutator will generate any strings including invalid UTF-8. If it's a “proto3” message type, only valid UTF-8 will be used.

Users of the library

Bugs found with help of the library

Chromium

Envoy

Related materials