The settings file is used to specify customizable settings for RESTler. This format is in json and will be described below, in detail. Using the settings file is optional and all settings contained within are optional. When using the settings file, pass its path as a command-line argument, as follows:
Restler.exe fuzz --settings C:\somedir\restler_user_settings.json
If any setting is specified in both the settings file AND as a command-line argument, the settings file setting will take precedence.
The checker specific arguments. This is a dict type object where the keys are the checker's "friendly name", which is the checker's name without the word Checker (i.e. payloadbody or invaliddynamicobject). The values are another dict type object where the keys are a checker-specific argument name and the value is the argument value, which may be of any type. Example: {"mode":"exhaustive"}
Checkers' Friendly Names:
- LeakageRule
- ResourceHierarchy
- UseAfterFree
- NamespaceRule
- InvalidDynamicObject
- PayloadBody
- Examples
List of status codes that will be flagged as bugs.
Note:
Use wildcard '*' to allow any value after the star to exist. Ex: '2*' will match 200, 201, 210, etc.
Use wildcard '?' to allow any value in that specific location. Ex: '2?1' will match 201 or 211, but not 202.
List of paths to custom checker files that will be loaded during runtime.
A list of "non-bug" status codes. When this setting is defined, any status code received from the service-in-test that was not included in this list will be flagged as a bug.
Note:
Use wildcard '*' to allow any value on or after the star to exist. Ex: '2*' will match 200, 201, 210, etc.
Use wildcard '?' to allow any value in that specific location. Ex: '2?1' will match 201 or 211, but not 202.
Max number of objects of one type before deletion by the garbage collector
The fuzzing mode. Options are:
- bfs
- bfs-cheap
- random-walk
- directed-smoke-test
Length of time between garbage collection calls (seconds, None = no garbage collection)
Length of time the garbage collector will attempt to cleanup remaining resources at the end of fuzzing (seconds)
The global producer timing delay that is applied to all producers. Producer timing delay is a wait time (in seconds) that is applied after any request that is marked as a producer. This wait time will occur for every request in a sequence except the last request. The per-resource producer timing delay (below) will override this value.
The path to the grammar.json file for the API in test. This is required when using the examples and payload body checkers.
Set to override the Host that's specified in the grammar
Set to false to disable sending user agent with requests
The maximum amount of time, in seconds, to wait for a resource to be created before continuing.
The maximum number of parameter value combinations for parameters within a given request payload.
The maximum amount of time, in seconds, to wait for a response after sending a request.
Set to True to disable SSL for requests
Filters the grammar to only use endpoints whose paths contain the given regex string.
The time, in milliseconds, to throttle each request being sent. This is here for special cases where the server will block requests from connections that arrive too quickly. Using this setting is not recommended.
Once this time is reached, the fuzzing will stop. Time is in hours.
The command to execute in order to refresh the authentication token.
The interval between periodic refreshes of the authentication token, in seconds.
When set, polls for async resource creation before continuing
Certain settings can be applied to specific endpoints. These settings a defined in a per_resource_settings dict. For example:
"per_resource_settings": {
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/dnsZones/{zoneName}/{recordType}/{relativeRecordSetName}" : {
"producer_timing_delay": 5,
"create_once": 1
}
}
The above snippet will set the producer timing delay to 5 and activate create-once for the specified endpoint. Per resource settings override any global settings.
The per resource producer timing delay, in seconds. This is a dict type object where the key is the request's endpoint and the value is the producer timing delay. The endpoint can be found in the Swagger file or the grammar file created from compiling with RESTler.
When set to 1 (or true), this resource will be created and destroyed only once at the beginning and end of the fuzzing run. Note: Its child resources will be fuzzed and must be separately included in 'create_once' if desired.
If this setting is set with a valid path to a restler mutations dictionary, the values in that dictionary will be used for the specified resource. For instance, any custom payloads or fuzzable values for this endpoint will be taken from the specified custom dictionary instead of the default dictionary.
{
"max_combinations": 20,
"max_request_execution_time": 90,
"max_async_resource_creation_time": 60,
"global_producer_timing_delay": 2,
"dyn_objects_cache_size":20,
"fuzzing_mode": "directed-smoke-test",
"path_regex": "(\\w*)/ddosProtectionPlans(\\w*)",
"per_resource_settings": {
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/dnsZones/{zoneName}/{recordType}/{relativeRecordSetName}": {
"producer_timing_delay": 1,
"create_once": 1
"custom_dictionary": "c:\\restler\\custom_dict1.json"
},
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/dnsZones/{zoneName}" {
"producer_timing_delay": 5
}
},
"checkers": {
"useafterfree" : {
"mode" : "exhaustive"
},
"leakagerule" : {
"mode" : "normal"
},
"resourcehierarchy" : {
"mode" : "exhaustive"
}
}
}