Bug: 112369099

Clone this repo:
  1. 7e7a774 Upgrade libprotobuf-mutator to dbe588bfb6922060e557fe5b8ee27d2923000c1a am: 2fcbc34326 am: 9ee6084729 am: 237cd6833b by Sadaf Ebrahimi · 1 year, 9 months ago aml_hef_341811030 aml_rkp_341810000 android14-d2-release android14-d2-s1-release android14-d2-s2-release android14-d2-s3-release android14-d2-s4-release android14-d2-s5-release android14-dev android14-mainline-healthfitness-release android14-qpr1-release android14-qpr1-s2-release android14-qpr2-release android14-qpr2-s1-release android14-qpr2-s2-release android14-qpr2-s3-release android14-qpr2-s4-release android14-qpr2-s5-release android14-qpr3-release android14-qpr3-s2-release main master aml_cfg_341510000 aml_hef_341114030 aml_hef_341311010 aml_hef_341415040 aml_hef_341512030 aml_hef_341613000 aml_hef_341717050 aml_hef_341811030 aml_rkp_341012000 aml_rkp_341015010 aml_rkp_341114000 aml_rkp_341311000 aml_rkp_341510000 aml_rkp_341810000 android-14.0.0_r16 android-14.0.0_r17 android-14.0.0_r18 android-14.0.0_r19 android-14.0.0_r20 android-14.0.0_r21 android-14.0.0_r22 android-14.0.0_r23 android-14.0.0_r24 android-14.0.0_r25 android-14.0.0_r26 android-14.0.0_r27 android-14.0.0_r29 android-14.0.0_r30 android-14.0.0_r31 android-14.0.0_r32 android-14.0.0_r33 android-14.0.0_r34 android-14.0.0_r35 android-14.0.0_r36 android-14.0.0_r37 android-14.0.0_r38 android-14.0.0_r39 android-14.0.0_r40 android-14.0.0_r41 android-14.0.0_r42 android-14.0.0_r43 android-14.0.0_r44 android-14.0.0_r45 android-14.0.0_r50 android-14.0.0_r51 android-14.0.0_r52 android-14.0.0_r53 android-14.0.0_r54
  2. 237cd68 Upgrade libprotobuf-mutator to dbe588bfb6922060e557fe5b8ee27d2923000c1a am: 2fcbc34326 am: 9ee6084729 by Sadaf Ebrahimi · 1 year, 9 months ago android-u-beta-1-gpl
  3. 9ee6084 Upgrade libprotobuf-mutator to dbe588bfb6922060e557fe5b8ee27d2923000c1a am: 2fcbc34326 by Sadaf Ebrahimi · 1 year, 9 months ago main-16k-with-phones
  4. 2fcbc34 Upgrade libprotobuf-mutator to dbe588bfb6922060e557fe5b8ee27d2923000c1a by Sadaf Ebrahimi · 1 year, 9 months ago
  5. dbe588b Remove one empty line by Vitaly Buka · 1 year, 10 months ago


TravisCI Build Status Fuzzing Status


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
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.


sudo ninja install

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


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

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.

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.

static PostProcessorRegistration<MyMessageType> reg1 = {
    [](MyMessageType* message, unsigned int seed) {
      TweakMyMessage(message, seed);
static PostProcessorRegistration<MyMessageType> reg2 = {
    [](MyMessageType* message, unsigned int seed) {
      DifferentTweakMyMessage(message, seed);
static PostProcessorRegistration<MyMessageType::Nested> reg_nested = {
    [](MyMessageType::Nested* message, unsigned int seed) {
      TweakMyNestedMessage(message, seed);

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

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.


Currently the library does not mutate extensions. This can be a problem if extension contains required fields so the library will not be able to change the message into valid initialized state. You can use post processing hooks to cleanup/initialize the message as workaround.

Users of the library

Bugs found with help of the library



Related materials