Bug: 112369099

Clone this repo:
  1. 66e4e1c Add METADATA, MODULE_LICENSE_APACHE2, NOTICE, OWNERS am: 48c2766279 by Ji Won Shin · 3 months ago master
  2. 48c2766 Add METADATA, MODULE_LICENSE_APACHE2, NOTICE, OWNERS by Ji Won Shin · 3 months ago master-cuttlefish-testing-release
  3. 6fb6bb5 Import c9a1e56750a4eef6ffca95f41f79f06979056e01 into master am: f9fc8f8397 by Xin Li · 3 months ago
  4. f9fc8f8 Import c9a1e56750a4eef6ffca95f41f79f06979056e01 into master by Xin Li · 3 months ago
  5. b72591c Initial empty repository by (raulenrique) · 3 months ago sdk-release

libprotobuf-mutator

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 binutils cmake ninja-build liblzma-dev libz-dev pkg-config

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.

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:
  MyProtobufMutator(uint32_t seed) : protobuf_mutator::Mutator(seed) {}
  // Optionally redefine the Mutate* methods to perform more sophisticated mutations.
}
void Mutate(MyMessage* message) {
  MyProtobufMutator mutator(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.

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.