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