VMF 4.1.0 Release

Author: ebraunstein

CMakeLists.txt

@@ -46,6 +46,9 @@ set(CMAKE_CXX_COMPILER g++)
 # Use address sanitizer?
 #add_compile_options(-fsanitize=address)
 #add_link_options(-fsanitize=address)
+#Or if those flags don't work, then use these:
+#set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-omit-frame-pointer -fsanitize=address")
+#set (CMAKE_LINKER_FLAGS "${CMAKE_LINKER_FLAGS} -fno-omit-frame-pointer -fsanitize=address")
 
 # Add debug info?
 #add_link_options(-g)
@@ -55,7 +58,7 @@ set(CMAKE_CXX_COMPILER g++)
 set(CMAKE_EXPORT_COMPILE_COMMANDS True)
 
 #############################################################
-project(VMF VERSION 4.0.0
+project(VMF VERSION 4.1.0
     LANGUAGES CXX )
 #############################################################
 

README.md

@@ -12,6 +12,8 @@
 ### Upgrading from an Earlier Release of VMF?
 See [migration-4.0.0.md](docs/migration-4.0.0.md) for a list of the API changes in VMF 4.0.0.
 
+***Note: VMF is compatible with compiler instrumentation from AFL++ 4.10c or earlier, due to an update in the forkserver interface that was introduced in 4.20c.  VMF will be updated in a future release to fix this compatibility issue.***
+
 ### VMF Compatibility
 
 As of now, VMF can be run in Docker and on the following distributions of Linux:
@@ -23,6 +25,7 @@ As of now, VMF can be run in Docker and on the following distributions of Linux:
 - Ubuntu 20.04, and 22.04
 
 VMF depends on several open source projects, but uses a "batteries-included" philosophy to dependencies where practical.
+
 The sources of particular versions of these dependencies live inside of the VMF tree.  
 For more information about VMF's included package, and other required dependencies, see
 [External Projects](docs/external_projects.md)

docs/configuration.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-The VMF configuration file is contained in one or more YAML file. These YAML files provides a structure to the configuration of the fuzzer and its modules.  Each top level YAML section (i.e. `vmfFramework`) must be contained within a single file, but otherwise the configuration parameters may be split into multiple files, as desired.  Note that all of the examples provided with VMF put the System Under Test (SUT) specific parameters into one file, and the other configuration sections in a second file.  See [getting_started.md](/docs/getting_started.md) for more information on our example configuration files and their organization.
+The VMF configuration file is contained in one or more YAML file. These YAML files provides a structure to the configuration of the fuzzer and its modules.  Each top level YAML section (i.e. `vmfFramework`) must be contained within a single file, but otherwise the configuration parameters may be split into multiple files, as desired.  Note that all of the examples provided with VMF put the System Under Test (SUT) specific parameters into one file, and the other configuration sections in a second file.  See [getting_started.md](getting_started.md) for more information on our example configuration files and their organization.
 
 ## Top level sections
 
@@ -28,6 +28,8 @@ StatsOutput:
 IterativeController: 
   corpusUpdateRateMins: 30
   corpusInitialUpdateMins: 10
+  batchSize: 1000
+  
 
 #Config options for the storage module 
 SimpleStorage:

docs/coremodules/core_modules_configuration.md

@@ -22,12 +22,16 @@ Executor and Feedback modules
 * [`AFLFavoredFeedback`](#section-aflfavoredfeedback)
 
 Output modules
+* [`ComputeStats`](#section-computestats)
 * [`CorpusMinimization`](#section-corpusminimization)
+* [`CSVMetadataOutput`](#section-csvmetadataoutput)
+* [`LoggerMetadataOutput`](#section-loggermetadataoutput)
 * [`SaveCorpusOutput`](#section-savecorpusoutput)
 * [`StatsOutput`](#section-statsoutput)
 
 Controller modules
 * [`Parameters Common to All Controller Modules`](#section-parameters-common-to-all-controller-modules)
+* [`AnalysisController`](#section-analysiscontroller)
 * [`IterativeController`](#section-iterativecontroller)
 * [`NewCoverageController`](#section-newcoveragecontroller)
 * [`RunOnceController`](#section-runoncecontroller)
@@ -530,6 +534,25 @@ AFLFavoredFeedback:
   sizeWeight: 1.0           # sizeWeight should be 0.0-10.0 (0.0 will remove this factor. Must be nonnegative.)
   speedWeight: 5.0          # speedWeight should be 0.0-10.0 (0.0 will remove this factor. Must be nonnegative.)
 ```
+## <a id="ComputeStats"></a>Section: `ComputeStats`
+
+Configuration information specific to the ComputeStats module, which computes statistics using the information in storage.
+
+### `ComputeStats.statsRateInSeconds`
+
+Value type: `<int>`
+
+Status: Optional
+
+Default value: 1
+
+Usage: This parameter specifies how often the module should compute statistics, in seconds.  Note that a few of the total test case statistics have to be counted on every pass through the fuzzing loop, because they rely on directly observing new test cases on storage.  This parameter controls the rate of computing the remaining statistics.
+
+### Configuration example
+```yaml
+ComputeStats:
+  statsRateInSeconds: 10
+```
 
 ## <a id="CorpusMinimization"></a>Section: `CorpusMinimization`
 
@@ -550,6 +573,56 @@ Usage: This parameter specifies how often the module is scheduled, in minutes. I
 SaveCorpusOutput:
   frequencyInMinutes: 30
 ```
+## <a id="CSVMetadataOutput"></a>Section: `CSVMetadataOutput`
+
+Configuration information specific to the CSVMetadataOutput module, which periodically writes the numeric values in metadata to a CSV file.
+
+### `CSVMetadataOutput.outputRateInSeconds`
+
+Value type: `<int>`
+
+Status: Optional
+
+Default value: 5
+
+Usage: This parameter specifies how often (in seconds) the metadata values should be written to the CSV file
+
+### `CSVMetadataOutput.outputFileName`
+
+Value type: `<string>`
+
+Status: Optional
+
+Default value: "metadata.csv"
+
+Usage: This parameter specifies the filename of the CSV output file.  The directory used is the VMF output directory (vmfFramework.outputBaseDir).
+
+### Configuration example
+```yaml
+CSVMetadataOutput:
+  outputFileName: "Test_3.CSV"
+  outputRateInSeconds: 1
+```
+
+## <a id="LoggerMetadataOutput"></a>Section: `LoggerMetadataOutput`
+
+Configuration information specific to the LoggerMetadataOutput module, which periodically writes the numeric values in metadata to the VMF Logger.
+
+### `LoggerMetadataOutput.outputRateInSeconds`
+
+Value type: `<int>`
+
+Status: Optional
+
+Default value: 5
+
+Usage: This parameter specifies how often (in seconds) the metadata values should be written to the Logger.
+
+### Configuration example
+```yaml
+LoggerMetadataOutput:
+  outputRateInSeconds: 60
+```
 
 ## <a id="SaveCorpusOutput"></a>Section: `SaveCorpusOutput`
 
@@ -603,23 +676,44 @@ StatsOutput:
 ```
 
 ## <a id="ControllerCommonParameters"></a>Section: `Parameters Common to All Controller Modules`
-Parameters that are common to all Controller Modules (these parameters are supported by the base ControllerModule class).  Each of these parameters is only relevant for distributed fuzzing, and will have no effect on standalone execution.
+
+Parameters that are common to all core Controller Modules (these parameters are supported by the base ControllerModulePattern class). Note that some are relevant ONLY for distributed fuzzing and will have no effect on standalone execution.
+
+### `controller.keepAllSeeds`
+
+Value type: `<bool>`
+
+Status: Optional
+
+Default value: true
+
+Usage: If set to true, all seed testcases will be saved and inserted into the fuzzing queue regardless of their coverage or quality. If set to false, only testcases that the feedback module decides to keep (eg have new coverage) will be kept. When set to true, more care should be given to seed redundancy and quality.
 
 ### `controller.corpusInitialUpdateMins`
 
 Value type: `<int>`
 
-Status: Optional
+Status: Optional - Distributed fuzzing only
 
 Default value: 5
 
 Usage: This sets the minimum number of minutes that must pass before the controller will perform the first corpus update.  Do not configure this parameter to be smaller than 5min unless you are using a very small number of VMFs.
 
+### `controller.batchSize`
+
+Value type: `<int>`
+
+Status: Optional - Distributed fuzzing only
+
+Default value: 1000
+
+Usage: This sets a maximum number of new test cases that will be pulled in from the server at once.  All the test cases will eventually be pulled in, but this parameter limits how many get pulled in at once (in order to limit the RAM usage by VMF).  When this value is too large, VMF will use an excessive amount of RAM (with resulting slow downs, consequently this value may need to be set to be smaller if the test cases are large).
+
 ### `controller.corpusUpdateRateMins`
 
 Value type: `<int>`
 
-Status: Optional
+Status: Optional - Distributed fuzzing only
 
 Default value: 5
 
@@ -629,12 +723,15 @@ Usage: This sets a minimum rate for the controller to retrieve subsequent corpus
 
 Value type: `<list of strings>`
 
-Status: Optional
+Status: Optional - Distributed fuzzing only
 
 Default value: ["RAN_SUCCESSFULLY"]
 
 Usage: This parameter controls which test case tags are retrieved by the controller. The default value is ["RAN_SUCCESSFULLY"], which will retrieve only the test cases ran succesfully (i.e. didn't hang or crash). This is the correct value if you are using VMF Core Modules in your fuzzer.
 
+## <a id="AnalysisController"></a>Section: `AnalysisController`
+The AnalysisController does not support any custom configuration parameters.
+
 ## <a id="IterativeController"></a>Section: `IterativeController`
 Configuration information specific to the IterativeController.
 ### `IterativeController.runTimeInMinutes`