Note on libFuzzer Source Code
概述：
libFuzzer is a util for fuzzing different C/C++ library. It’s quite handy to begin, we only need to define:
int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size);
Then, we pass the data to the library API. Here is an example from fuzzer test suite:
SSL_CTX *Init() {
SSL_library_init();
SSL_load_error_strings();
ERR_load_BIO_strings();
OpenSSL_add_all_algorithms();
SSL_CTX *sctx;
assert (sctx = SSL_CTX_new(TLSv1_method()));
/* These two file were created with this command:
openssl req -x509 -newkey rsa:512 -keyout server.key \
-out server.pem -days 9999 -nodes -subj /CN=a/
*/
assert(SSL_CTX_use_certificate_file(sctx, CERT_PATH "server.pem",
SSL_FILETYPE_PEM));
assert(SSL_CTX_use_PrivateKey_file(sctx, CERT_PATH "server.key",
SSL_FILETYPE_PEM));
return sctx;
}
extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
static SSL_CTX *sctx = Init();
SSL *server = SSL_new(sctx);
BIO *sinbio = BIO_new(BIO_s_mem());
BIO *soutbio = BIO_new(BIO_s_mem());
SSL_set_bio(server, sinbio, soutbio);
SSL_set_accept_state(server);
BIO_write(sinbio, data, size);
SSL_do_handshake(server);
SSL_free(server);
return 0;
}
初始化：
用户定义的函数
FuzzerDriver initialized the whole fuzzer. It collects all the external functions to global variable EF:
int FuzzerDriver(int *argc, char ***argv, UserCallback Callback) {
using namespace fuzzer;
assert(argc && argv && "Argument pointers cannot be nullptr");
std::string Argv0((*argv)[0]);
EF = new ExternalFunctions();
Some have been defined in FuzzerInterface at the beginning:
// Mandatory user-provided target function.
// Executes the code under test with [Data, Data+Size) as the input.
// libFuzzer will invoke this function *many* times with different inputs.
// Must return 0.
FUZZER_INTERFACE_VISIBILITY int
LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size);
// Optional user-provided initialization function.
// If provided, this function will be called by libFuzzer once at startup.
// It may read and modify argc/argv.
// Must return 0.
FUZZER_INTERFACE_VISIBILITY int LLVMFuzzerInitialize(int *argc, char ***argv);
// Optional user-provided custom mutator.
// Mutates raw data in [Data, Data+Size) inplace.
// Returns the new size, which is not greater than MaxSize.
// Given the same Seed produces the same mutation.
FUZZER_INTERFACE_VISIBILITY size_t
LLVMFuzzerCustomMutator(uint8_t *Data, size_t Size, size_t MaxSize,
unsigned int Seed);
// Optional user-provided custom cross-over function.
// Combines pieces of Data1 & Data2 together into Out.
// Returns the new size, which is not greater than MaxOutSize.
// Should produce the same mutation given the same Seed.
FUZZER_INTERFACE_VISIBILITY size_t
LLVMFuzzerCustomCrossOver(const uint8_t *Data1, size_t Size1,
const uint8_t *Data2, size_t Size2, uint8_t *Out,
size_t MaxOutSize, unsigned int Seed);
// Experimental, may go away in future.
// libFuzzer-provided function to be used inside LLVMFuzzerCustomMutator.
// Mutates raw data in [Data, Data+Size) inplace.
// Returns the new size, which is not greater than MaxSize.
FUZZER_INTERFACE_VISIBILITY size_t
LLVMFuzzerMutate(uint8_t *Data, size_t Size, size_t MaxSize);
As the comment suggests, user needs to implement these functions to interact with libFuzzer. Despite interface functions, it also collect functions provided by other sanitizer:
Unlike AFL, which implements all utilities itself, libFuzzer relies on LLVM sanitizers. Sanitizers allow libFuzzer to track coverage, bugs, and printing in a user-friendly format.
After initializing different flags trivially, we reach:
...
auto *MD = new MutationDispatcher(Rand, Options);
auto *Corpus = new InputCorpus(Options.OutputCorpus);
auto *F = new Fuzzer(Callback, *Corpus, *MD, Options);
...
Mutation Dispatcher
The first one is MutationDispatcher. The utility class provide different mutation methods. All strategies are inserted to DefaultMutator. The mutation function does exactly as the name indicates. We won’t step further on those functions. Basically, we can group them into byte operations, cross-over, and loading dictionary. If user customizes mutation methods, libFuzzer only uses user-provided functions (and no more default mutations). Eventually customized cross-over function is pushed to the set once implemented:
...
DefaultMutators.insert
DefaultMutators.begin(),
{
{&MutationDispatcher::Mutate_EraseBytes, "EraseBytes"},
{&MutationDispatcher::Mutate_InsertByte, "InsertByte"},
{&MutationDispatcher::Mutate_InsertRepeatedBytes,
"InsertRepeatedBytes"},
{&MutationDispatcher::Mutate_ChangeByte, "ChangeByte"},
{&MutationDispatcher::Mutate_ChangeBit, "ChangeBit"},
{&MutationDispatcher::Mutate_ShuffleBytes, "ShuffleBytes"},
{&MutationDispatcher::Mutate_ChangeASCIIInteger, "ChangeASCIIInt"},
{&MutationDispatcher::Mutate_ChangeBinaryInteger, "ChangeBinInt"},
{&MutationDispatcher::Mutate_CopyPart, "CopyPart"},
{&MutationDispatcher::Mutate_CrossOver, "CrossOver"},
{&MutationDispatcher::Mutate_AddWordFromManualDictionary,
"ManualDict"},
{&MutationDispatcher::Mutate_AddWordFromPersistentAutoDictionary,
"PersAutoDict"},
});
if(Options.UseCmp)
DefaultMutators.push_back(
{&MutationDispatcher::Mutate_AddWordFromTORC, "CMP"});
if (EF->LLVMFuzzerCustomMutator)
Mutators.push_back({&MutationDispatcher::Mutate_Custom, "Custom"});
else
Mutators = DefaultMutators;
if (EF->LLVMFuzzerCustomCrossOver)
Mutators.push_back(
{&MutationDispatcher::Mutate_CustomCrossOver, "CustomCrossOver"});
...
InputCorpus and Fuzzer
InputCorpus collects the generated input. The constructor initializes data in InputSizesPerFeature and SmallestElementPerFeature for storing COVs.
Fuzzer and CallBack function (the call back function is LLVMFuzzerTestOneInputactually) are assigned to variable F with some trivial loadings:
Fuzzer and CallBack function (the call back function is LLVMFuzzerTestOneInputactually) are assigned to variable F with some trivial loadings:
After loading flags and some varaible, libFuzzer will enter different modes depending on command arguments. Let’s analyze one by one.
Multi-Processes Mode
- In
FuzzerDriver, libFuzzer checks workers and jobs flags: - Then, it will create a number of threads according to workers number:
-
WorkerThreadwill run forNumJobstimes and derive fuzzing commands without providing worker and job parameter. Then usesystem()functions to run the new command:
TracePC Class
Before diving to fuzzer mode, we should take a look at TracePC. This module implements trace_pc_guard to collect features (similar to coverage) from a process in runtime. PC refers to program counter here. We can see the hooks from FuzzerTracePc.cpp (The source code is too long to paste here, but I recommend you to read them from the bottom of FuzzerTracePc.cpp). You can also find definitions of trace-pc-guard here
A program counter records the execution of instructions, it increase 1 by every execution
Tracing the Execution
Let’s see initialization first. TracePC finds the path of a program by inserting counter at the end of each edge. After executing each edge, HandleInline8bitCountersInit is invoked. The start address and stop address (refer to the begin and end of pc guard address which stores execution times of corresponding segment) will be rounded.
To avoid counting cycles, libFuzzer checks if current start address equals to the previous one. The function is terminated once in redundant cycles. Otherwise libFuzzer inserts a new module, with regions from start address to stop address sliced by page size (4096 by default).
Region has four attributes - start/stop address and two boolean indicating wether the page is enabled or a full page. The two boolean are false by default because of previous clean up operation TRC.ReseMaps() in Fuzzer constructor:
struct Region {
uint8_t *Start, *Stop;
bool Enabled;
bool OneFullPage;
};
Each element in Modules has a corresponding ModulePCTable (match by index). HandlePCsInit records all instrumented PCs information, including instrumented PC address and PCFlags for determining entry point:
Program Features
At the end of FuzzerTrace.cpp, you can find following implementation for trace-pc sanitizer. It turns out that libFuzzer hooks comparison function (including string and memory comparison), switch, and cmp instructions. Arguments from functions/instructions are passed to HandleCmp and AddValueForMemcmp. libFuzzer stores them because comparisons are more likely to affect control flow
extern "C" {
ATTRIBUTE_INTERFACE
void __sanitizer_cov_8bit_counters_init(uint8_t *Start, uint8_t *Stop) {
fuzzer::TPC.HandleInline8bitCountersInit(Start, Stop);
}
ATTRIBUTE_INTERFACE
void __sanitizer_cov_pcs_init(const uintptr_t *pcs_beg,
const uintptr_t *pcs_end) {
fuzzer::TPC.HandlePCsInit(pcs_beg, pcs_end);
}
ATTRIBUTE_INTERFACE
ATTRIBUTE_NO_SANITIZE_ALL
void __sanitizer_cov_trace_pc_indir(uintptr_t Callee) {
uintptr_t PC = reinterpret_cast<uintptr_t>(GET_CALLER_PC());
fuzzer::TPC.HandleCallerCallee(PC, Callee);
}
ATTRIBUTE_INTERFACE
ATTRIBUTE_NO_SANITIZE_ALL
ATTRIBUTE_TARGET_POPCNT
void __sanitizer_cov_trace_cmp8(uint64_t Arg1, uint64_t Arg2) {
uintptr_t PC = reinterpret_cast<uintptr_t>(GET_CALLER_PC());
fuzzer::TPC.HandleCmp(PC, Arg1, Arg2);
}
... // ignore many functions with identical usage
ATTRIBUTE_INTERFACE ATTRIBUTE_NO_SANITIZE_MEMORY
void __sanitizer_weak_hook_memmem(void *called_pc, const void *s1, size_t len1,
const void *s2, size_t len2, void *result) {
if (!fuzzer::RunningUserCallback) return;
fuzzer::TPC.MMT.Add(reinterpret_cast<const uint8_t *>(s2), len2);
}
} // extern "C"
HandleCmp converts two argument to a hash, then uses the hash as index for storing in TableOfRecentCompares, which is a bis-set based hash map. Similar to HandleCmp, AddValueForMemcmp computes hash of two strings and add it to the table. Every new bit is represented as a new coverage:
Fuzzer
The core part of libFuzzer. The driver function calls F->loop at very last to start fuzzing:
void Fuzzer::Loop(Vector<SizedFile> &CorporaFiles) {
auto FocusFunctionOrAuto = Options.FocusFunction;
DFT.Init(Options.DataFlowTrace, &FocusFunctionOrAuto, CorporaFiles,
MD.GetRand());
TPC.SetFocusFunction(FocusFunctionOrAuto);
ReadAndExecuteSeedCorpora(CorporaFiles);
DFT.Clear(); // No need for DFT any more.
TPC.SetPrintNewPCs(Options.PrintNewCovPcs);
TPC.SetPrintNewFuncs(Options.PrintNewCovFuncs);
system_clock::time_point LastCorpusReload = system_clock::now();
TmpMaxMutationLen =
Min(MaxMutationLen, Max(size_t(4), Corpus.MaxInputSize()));
while (true) {
auto Now = system_clock::now();
if (!Options.StopFile.empty() &&
!FileToVector(Options.StopFile, 1, false).empty())
break;
if (duration_cast<seconds>(Now - LastCorpusReload).count() >=
Options.ReloadIntervalSec) {
RereadOutputCorpus(MaxInputLen);
LastCorpusReload = system_clock::now();
}
if (TotalNumberOfRuns >= Options.MaxNumberOfRuns)
break;
if (TimedOut())
break;
// Update TmpMaxMutationLen
if (Options.LenControl) {
if (TmpMaxMutationLen < MaxMutationLen &&
TotalNumberOfRuns - LastCorpusUpdateRun >
Options.LenControl * Log(TmpMaxMutationLen)) {
TmpMaxMutationLen =
Min(MaxMutationLen, TmpMaxMutationLen + Log(TmpMaxMutationLen));
LastCorpusUpdateRun = TotalNumberOfRuns;
}
} else {
TmpMaxMutationLen = MaxMutationLen;
}
// Perform several mutations and runs.
MutateAndTestOne();
PurgeAllocator();
}
PrintStats("DONE ", "\n");
MD.PrintRecommendedDictionary();
}
The function will first initialize DataFlowTrace and TracePC, then do mutation and execution.
DataFlowTrace
If you provide data flow trace file, the following steps will be invoked. To be short, necessary arguments are passed to DataFlowTrace, a class for reading and handling data-flow traces.
The Loop will start DataFlowTrace.Init() first. All the function names will be pushed to a vector and mapped to corresponding index. Then a focused index FocusFuncIdx is chosen by some statistics distribution:
bool DataFlowTrace::Init(const std::string &DirPath, std::string *FocusFunction, Vector<SizedFile> &CorporaFiles, Random &Rand) {
if (DirPath.empty()) return false;
...
// Read functions.txt
std::ifstream IF(DirPlusFile(DirPath, kFunctionsTxt));
size_t NumFunctions = 0;
while (std::getline(IF, L, '\n')) {
FunctionNames.push_back(L);
NumFunctions++;
if (*FocusFunction == L)
FocusFuncIdx = NumFunctions - 1;
}
if (!NumFunctions)
return false;
...
Finally, it will rank the weights of functions, and get a focus function:
···
...
if (*FocusFunction == "auto") {
// AUTOFOCUS works like this:
// * reads the coverage data from the DFT files.
// * assigns weights to functions based on coverage.
// * chooses a random function according to the weights.
ReadCoverage(DirPath);
auto Weights = Coverage.FunctionWeights(NumFunctions);
Vector<double> Intervals(NumFunctions + 1);
std::iota(Intervals.begin(), Intervals.end(), 0);
auto Distribution = std::piecewise_constant_distribution<double>(
Intervals.begin(), Intervals.end(), Weights.begin());
FocusFuncIdx = static_cast<size_t>(Distribution(Rand));
*FocusFunction = FunctionNames[FocusFuncIdx];
assert(FocusFuncIdx < NumFunctions);
Printf("INFO: AUTOFOCUS: %zd %s\n", FocusFuncIdx,
FunctionNames[FocusFuncIdx].c_str());
for (size_t i = 0; i < NumFunctions; i++) {
if (!Weights[i]) continue;
Printf(" [%zd] W %g\tBB-tot %u\tBB-cov %u\tEntryFreq %u:\t%s\n", i,
Weights[i], Coverage.GetNumberOfBlocks(i),
Coverage.GetNumberOfCoveredBlocks(i), Coverage.GetCounter(i, 0),
FunctionNames[i].c_str());
}
}
...
FunctionWeights weights based on uncovered blocks and execute frequency. Either higher uncovered blocks or lower execute frequency leads to a higher weight. However, uncovered functions merely have 0 weight.
By the way, the order of *FocusFunction = FunctionNames[FocusFuncIdx]; and assert(FocusFuncIdx < NumFunctions); is weird. Is it supposed to assert before the index operation?
Eventually, the focused function will be aded to Traces:
...
size_t NumTraceFiles = 0;
size_t NumTracesWithFocusFunction = 0;
for (auto &SF : Files) {
auto Name = Basename(SF.File);
if (Name == kFunctionsTxt) continue;
if (!CorporaHashes.count(Name)) continue; // not in the corpus.
NumTraceFiles++;
// Printf("=== %s\n", Name.c_str());
std::ifstream IF(SF.File);
while (std::getline(IF, L, '\n')) {
size_t FunctionNum = 0;
std::string DFTString;
if (ParseDFTLine(L, &FunctionNum, &DFTString) &&
FunctionNum == FocusFuncIdx) {
NumTracesWithFocusFunction++;
if (FunctionNum >= NumFunctions)
return ParseError("N is greater than the number of functions", L);
Traces[Name] = DFTStringToVector(DFTString);
// Print just a few small traces.
if (NumTracesWithFocusFunction <= 3 && DFTString.size() <= 16)
Printf("%s => |%s|\n", Name.c_str(), std::string(DFTString).c_str());
break; // No need to parse the following lines.
}
}
}
...
Creating and running Corpus
Subsequently, the program start reading seed file in ReadAndExecuteSeedCorpora(CorporaFiles), a function for initializing corpus. libFuzzer tries empty input first, then iterate all the provided corpus files. \n will be used as default seed when we don’t provide any seed:
void Fuzzer::ReadAndExecuteSeedCorpora(Vector<SizedFile> &CorporaFiles) {
...
// Test the callback with empty input and never try it again.
uint8_t dummy = 0;
ExecuteCallback(&dummy, 0);
...
if (CorporaFiles.empty()) {
Printf("INFO: A corpus is not provided, starting from an empty corpus\n");
Unit U({'\n'}); // Valid ASCII input.
RunOne(U.data(), U.size());
} else {
Printf("INFO: seed corpus: files: %zd min: %zdb max: %zdb total: %zdb"
" rss: %zdMb\n",
CorporaFiles.size(), MinSize, MaxSize, TotalSize, GetPeakRSSMb());
if (Options.ShuffleAtStartUp)
std::shuffle(CorporaFiles.begin(), CorporaFiles.end(), MD.GetRand());
if (Options.PreferSmall) {
std::stable_sort(CorporaFiles.begin(), CorporaFiles.end());
assert(CorporaFiles.front().Size <= CorporaFiles.back().Size);
}
// Load and execute inputs one by one.
for (auto &SF : CorporaFiles) {
auto U = FileToVector(SF.File, MaxInputLen, /*ExitOnError=*/false);
assert(U.size() <= MaxInputLen);
RunOne(U.data(), U.size());
CheckExitOnSrcPosOrItem();
TryDetectingAMemoryLeak(U.data(), U.size(),
/*DuringInitialCorpusExecution*/ true);
}
}
...
}
Mutation in Depth
After running user-provided corpus in ReadAndExecuteSeedCorpora(CorporaFiles) (if provided), the Loop will eventually go to an infinity loop until a crash occurs, MutateAndTestOne is invoked here for mutation and running:
At the beginning, the function will choose two random input. One as a mutation target, another one as a cross-over target.Fuzzer then mutates the input several times according to Options.MutateDepth. We have two mutating methods here, MD.mutate and MD.MutateWithMask.
MutateWithMask
MD.MutateWithMask only mutates bytes marked in Mask (which has been defined as the focused function). After copying then to a temporary array T. The function uses the normal Md.mutate to convert data and eventually copy back to original array:
The general mutate
Md.mutate, on the other hand, uses one randomly selected mutation algorithm in each iteration until the cycle is over or current size exceeds max size. The implementation is in MutateImpl:
RunOne
RunOne is an additional wrapper function mainly for processing coverages after executing the program:
ExecuteCallBack
ExecuteCallBack copies data and executes the LLVMInputOneTest. Meanwhile, libFuzzer begins to trace the stack, heap, and program counters:
Counting new COVs
When execution ends, libFuzzer collects features (those comparisons we mentioned earlier) via a lambda:
And the following is the internal for CollectFeatures. To conclude, it finds the features for every regions by execution paths. Then add it to the corpus. The feature is unique once adding successfully. When UseValueProfileMask flag is true, comparisons are counted as features as well. Moreover, the stack depth is converted by log operation for additional feature calculation:
template <class Callback> // void Callback(size_t Feature)
ATTRIBUTE_NO_SANITIZE_ADDRESS
ATTRIBUTE_NOINLINE
void TracePC::CollectFeatures(Callback HandleFeature) const {
auto Handle8bitCounter = [&](size_t FirstFeature,
size_t Idx, uint8_t Counter) {
// if we do not use counters, it only converts address to features
if (UseCounters)
HandleFeature(FirstFeature + Idx * 8 + CounterToFeature(Counter));
else
HandleFeature(FirstFeature + Idx);
};
size_t FirstFeature = 0;
// iterating all edge path, then put the result of each execution to the feature set
for (size_t i = 0; i < NumModules; i++) {
for (size_t r = 0; r < Modules[i].NumRegions; r++) {
if (!Modules[i].Regions[r].Enabled) continue;
// iterate each byte
FirstFeature += 8 * ForEachNonZeroByte(Modules[i].Regions[r].Start,
Modules[i].Regions[r].Stop,
FirstFeature, Handle8bitCounter);
}
}
FirstFeature +=
8 * ForEachNonZeroByte(ExtraCountersBegin(), ExtraCountersEnd(),
FirstFeature, Handle8bitCounter);
// add comparsions to feature set
if (UseValueProfileMask) {
ValueProfileMap.ForEach([&](size_t Idx) {
HandleFeature(FirstFeature + Idx);
});
FirstFeature += ValueProfileMap.SizeInBits();
}
// add stack depth to feature set
// Step function, grows similar to 8 * Log_2(A).
auto StackDepthStepFunction = [](uint32_t A) -> uint32_t {
if (!A) return A;
uint32_t Log2 = Log(A);
if (Log2 < 3) return A;
Log2 -= 3;
return (Log2 + 1) * 8 + ((A >> Log2) & 7);
};
assert(StackDepthStepFunction(1024) == 64);
assert(StackDepthStepFunction(1024 * 4) == 80);
assert(StackDepthStepFunction(1024 * 1024) == 144);
if (auto MaxStackOffset = GetMaxStackOffset())
HandleFeature(FirstFeature + StackDepthStepFunction(MaxStackOffset / 8));
}
Back to RunOne. If fuzzer finds any new features, libFuzzer will update TPC and add current input to existing corpus:
TPC.UpdateObervedPCs() outputs the details to the screen. It iterates and uses two global sets for collecting called functions and pointer counter. If it is a entry point that has never been used, PC is added to CoveredFuncs for printing later:
Even though there might be no feature update, libFuzzer prefers to save corpus with smaller size for optimizing. Then remove the larger corpus:
Heap Leaking
A hook will be added for counting malloc and free times. The program will first check malloc==frees. Then it will run again in lsan disabled mode. If they are inequivalent twice, actual LSAN will be executed:
Conclusion
Surprisingly, the architecture of a fuzzer is not (that much) as thoughtful as a static analyzer. But it’s indeed an efficient strategy because of excellent performance.
