Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libprotobuf-mutator / d7c4ce6d5c2148bd99de155b53b1a025b099d1ba
commitd7c4ce6d5c2148bd99de155b53b1a025b099d1ba[log] [tgz]
authorMitch Phillips <mitchp@google.com>Fri Oct 25 17:06:59 2019 -0700
committerandroid-build-merger <android-build-merger@google.com>Fri Oct 25 17:06:59 2019 -0700
tree3bd5488b20650a4129c37d6c62002551019b20dd
parent3cb181eb39c7682106935f1c8de99c07443bde66 [diff]
parente7cf186a6f11116f9deb54d9ebba8326987049f1 [diff]
Merge "Add Vitaly/Mitch to OWNERS."
am: e7cf186a6f

Change-Id: Ib29b1fb8d9149fe57fa7c2928413f3b74ee25bde
tree: 3bd5488b20650a4129c37d6c62002551019b20dd
  1. cmake/
  2. examples/
  3. port/
  4. src/
  5. .clang-format
  6. .gitignore
  7. .travis.yml
  8. AUTHORS
  9. CMakeLists.txt
  10. CONTRIBUTING
  11. libprotobuf-mutator.pc.in
  12. LICENSE
  13. METADATA
  14. MODULE_LICENSE_APACHE2
  15. NOTICE
  16. OWNERS
  17. 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:
  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.

Users of the library

Bugs found with help of the library

Chromium

Envoy

Related materials