Clone this repo:

Branches

  1. c0a2038 Reset message if parsing failed. by Vitaly Buka · 14 days ago master
  2. af8136f Restrict proto3 strings to valid UTF-8 by Vitaly Buka · 2 weeks ago
  3. 8e4650f Add FieldInstance::EnforceUtf8 by Vitaly Buka · 2 weeks ago
  4. 418eba6 Add function to fix UTF-8 strings. by Vitaly Buka · 2 weeks ago
  5. 24d9fd0 Make argument name in cc the same as in h file. by Vitaly Buka · 3 weeks ago

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 docbook2x

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.

Usage

To use libprotobuf-mutator simply include protobuf_mutator.h and protobuf_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 protobuf_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.