-
Notifications
You must be signed in to change notification settings - Fork 48
ClientUsage
In order to talk to FuzzManager, your fuzzer should use the client interface provided, called the Collector. It can be used as a standalone command line tool or directly as a Python class in case your fuzzer is written in Python. We'll first describe how to use the class interface directly from Python. If you want to use the command line interface instead, I still suggest that you read on because the command line interface is very similar to the class interface in terms of functionality and configuration.
The Collector constructor takes various arguments that are required for later operations. These arguments include a directory for signatures, server data such as hostname, port, etc. as well as authentication data and a client name. However, the preferred way to pass these options is not through the constructor, but through a configuration file. The constructor will try to read the configuration file located at ~/.fuzzmanagerconf and use any parameters from there if it hasn't been explicitly specified in the constructor call. This makes deployment very easy and saves time. An example configuration could look like this:
[Main]
sigdir = /home/example/signatures
serverhost = 127.0.0.1
serverport = 8000
serverproto = http
serverauthtoken = 4a253efa90f514bd89ae9a86d1dc264aa3133945
With this file present and readable, instantiating the Collector doesn't require any further arguments.
Several methods of the collector work with the CrashInfo class. This class stores all the necessary data about a crash. In order to get a CrashInfo instance, you need:
- A variable containing the stdout output of your program
- A variable containing the stderr output of your program
- A variable containing crash information as outputted by GDB or AddressSanitizer
- A ProgramConfiguration instance
The first three sets of data are typically already available in a fuzzer. Note that for GDB traces, the trace should contain first the stack trace, then a dump of all registers and then a dissassembly of the program counter (see also the FTB/Running/AutoRunner.py file which demonstrates how to output all information properly for FuzzManager).
The last thing required is the ProgramConfiguration. This class is largely a container class storing various properties of the program, e.g. product name, the platform, version and runtime options. Instead of instantiating the class and providing all the data manually, it is again recommended to use the configuration file support. Assuming your binary is located at /home/example/foo then creating a configuration file at /home/example/foo.fuzzmanagerconf with the necessary data is recommended. Such a file could look like this:
[Main]
platform = x86
product = mozilla-central
product_version = 70de2960aa87
os = linux
[Metadata]
pathPrefix = /srv/repos/mozilla-central/
buildFlags = --enable-optimize --enable-posix-nspr-emulation --enable-valgrind --enable-gczeal --target=i686-pc-linux-gnu --disable-tests --enable-debug
Once this file is present, you can call ProgramConfiguration.fromBinary with your binary path and the configuration will be created from the file. You can add program arguments and environment variables through the provided addProgramArguments and addEnvironmentVariables methods afterwards. Finally, call CrashInfo.fromRawCrashData with all of the described data. Here's a simple example:
# Note: This could fail and return None when the configuration is missing or throw if misconfigured
configuration = ProgramConfiguration.fromBinary(opts.binary)
configuration.addEnvironmentVariables(env)
configuration.addProgramArguments(args)
crashInfo = CrashInfo.fromRawCrashData(stdout, stderr, configuration, auxCrashData=crashdata)
Calling the refresh method of our Collector instance will download a zipfile from the server, containing the signatures and metadata exported by the server. Once the download is complete, the Collector will first delete all signatures including their metadata from the signature directory. Then the downloaded zipfile is extracted.
The search method is the first of a few methods requiring a crashInfo variable. Create it as described above and the Collector will search inside the signature directory for any matching signatures. Upon match, it will return a tuple containing the filename of the signature matching as well as a metadata object corresponding to that signature.
The submit method can be used to send a crash report to the FuzzManager server. Again the crashInfo parameter works as described above. In addition, you can provide a file containing a test and an optional "quality" indicator of the test (best quality is 0). The use of this quality indicator largely depends on how your fuzzer/reducer works. The server will prefer better qualities when proposing test cases for filing bugs. Finally, the method accepts an additional metadata parameter which can contain arbitrary information that is stored with the crash on the server. Note that this metadata is combined with the metadata found in the ProgramConfiguration of the crashInfo. When using binary configuration files, this means that the metadata supplied in that configuration file is automatically submitted with the crash to the server.
Further methods of the Collector include generate for generating signatures locally and download for downloading testcases from the server. Both methods work as documented in the source code and are only useful in special cases depending on the application scenario.