1# libprotobuf-mutator
2
3## Overview
4libprotobuf-mutator is a library to randomly mutate
5[protobuffers](https://github.com/google/protobuf). <BR>
6It could be used together with guided
7fuzzing engines, such as [libFuzzer](http://libfuzzer.info).
8
9## Quick start on Debian/Ubuntu
10
11Install prerequisites:
12
13```
14sudo apt-get update
15sudo apt-get install binutils cmake ninja-build liblzma-dev libz-dev pkg-config
16```
17
18Compile and test everything:
19
20```
21mkdir build
22cd build
23cmake .. -GNinja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Debug
24ninja check
25```
26
27Clang is only needed for libFuzzer integration. <BR>
28By default, the system-installed version of
29[protobuf](https://github.com/google/protobuf) is used.  However, on some
30systems, the system version is too old.  You can pass
31`LIB_PROTO_MUTATOR_DOWNLOAD_PROTOBUF=ON` to cmake to automatically download and
32build a working version of protobuf.
33
34## Usage
35
36To use libprotobuf-mutator simply include
37[mutator.h](/src/mutator.h) and
38[mutator.cc](/src/mutator.cc) into your build files.
39
40The `ProtobufMutator` class implements mutations of the protobuf
41tree structure and mutations of individual fields.
42The field mutation logic is very basic --
43for better results you should override the `ProtobufMutator::Mutate*`
44methods with more sophisticated logic, e.g.
45using [libFuzzer](http://libfuzzer.info)'s mutators.
46
47To apply one mutation to a protobuf object do the following:
48
49```
50class MyProtobufMutator : public protobuf_mutator::Mutator {
51 public:
52  MyProtobufMutator(uint32_t seed) : protobuf_mutator::Mutator(seed) {}
53  // Optionally redefine the Mutate* methods to perform more sophisticated mutations.
54}
55void Mutate(MyMessage* message) {
56  MyProtobufMutator mutator(my_random_seed);
57  mutator.Mutate(message, 200);
58}
59```
60
61See also the `ProtobufMutatorMessagesTest.UsageExample` test from
62[mutator_test.cc](/src/mutator_test.cc).
63
64## Integrating with libFuzzer
65LibFuzzerProtobufMutator can help to integrate with libFuzzer. For example
66
67```
68#include "src/libfuzzer/libfuzzer_macro.h"
69
70DEFINE_PROTO_FUZZER(const MyMessageType& input) {
71  // Code which needs to be fuzzed.
72  ConsumeMyMessageType(input);
73}
74```
75
76Please see [libfuzzer_example.cc](/examples/libfuzzer/libfuzzer_example.cc) as an example.
77
78## UTF-8 strings
79"proto2" and "proto3" handle invalid UTF-8 strings differently. In both cases
80string should be UTF-8, however only "proto3" enforces that. So if fuzzer is
81applied to "proto2" type libprotobuf-mutator will generate any strings including
82invalid UTF-8. If it's a "proto3" message type, only valid UTF-8 will be used.
83