Drivers
GUARDARA can utilise different transport mechanisms to deliver test cases to the target. By default, it can deliver test cases over the network, the command line or via files. Support for each of these is provided by a set of built-in components called Drivers. A Driver is configured on a per-project basis when creating a new Project.
One of the design goals of GUARDARA was to allow users to implement their custom Drivers quickly. You can implement custom Drivers using the SDK.
This page discusses the built-in Drivers of GUARDARA.
Dummy
The Dummy Driver does not do anything. Its purpose is to help with development and testing. The only configurable option it provides is the Debug Mode. When the debug mode is enabled, the driver prints the actions performed and test cases generated by the Engine to the console.
Commandline
The Commandline Driver allows testing applications that accept data from the command line. The Driver exposes the below configuration options.
| Option | Description |
|---|---|
| Commandline | The option allows specifying the complete command line to use when calling the application. For example, if we wanted to call the ls command with the -l argument: ls -l. The insertion points for the test cases generated by the Engine can be marked with placeholders. For example, if we wanted to test the first argument of ls, we could type: ls {0}. More on this later. |
| Pipe Data | The option allows to pipe test cases generated by the Engine to the application. The best way to think about it is something like this: `echo ${MUTATED_DATA} |
An application may have multiple arguments, such as:
test_app -u admin -p password -c status -i 1
If we wanted to test all arguments, we had to craft the command line for the Driver, as shown below.
test_app -u {0} -p {1} -c {2} -i {3}
But, how do we specify how to mutate each of these arguments? It’s pretty simple. What is required is a single Message Template with four Groups at the root, each representing the value of an argument.
You can find a complete example on GitLab called Commandline Testing that demonstrates commandline application testing.
If Pipe Data was enabled, the first Group’s value within the Message Template would be piped to the application. All other Groups would serve as arguments. For example, demonstrated using a shell command:
echo {0} | test_app -u {1} -p {2} -c {3}
File
The File Driver allows saving the generated test cases into files. This is ideal when testing applications that process files. The Driver exposes the below configuration options.
| Option | Description |
|---|---|
| File Name | The name of the file to store mutations in. It is a template that supports the index placeholder, such as guardara-file-${index}. In this case, the index variable is replaced with a number incremented by each test case. |
| Path | The path to store the files under. As GUARDARA will likely generate a high number of test cases resulting in potentially hundreds of thousands of files, the driver creates sub-directories under this path where each subdirectory contains a total of 1000 files. |
| One File | When this option is enabled, all test cases are stored in a single file. The index placeholder within the File Name is ignored and can be removed. |
For example, when generating mutated binary files such as images, you will want to have One File disabled so that each image ends up being a separate file. However, if you want to test a CSV parser, you may enable the One File option, so test cases become rows in the CSV file.
Network / UDP
The UDP Network Driver allows transmitting test cases over UDP. The Driver exposes the below configuration options.
| Option | Description |
|---|---|
| Driver Mode | Defines whether GUARDARA should act as a Client or a Server. |
| Address | In Client mode, the Address option should specify the IP address or hostname of the target system to send messages to. In Server mode, the address field defines the IP address of the network interface to listen on. For example, to listen on all available interfaces in Server mode, you must set the Address to 0.0.0.0. |
| Port | In Client mode, it represents the port number of the target service is listening on. In Server mode, it represents the port number GUARDARA should bind to receive connections. |
| Listen to/Send on Broadcast | In Client mode, this option allows sending to broadcast addresses. In Server mode, it allows receiving broadcasted UDP messages destined to the port number defined by the Port configuration option. |
| Debug Mode | It does not have any effect and can be ignored. This option will be removed in a future release. |
Network / TCP
The TCP Network Driver allows transmitting test cases over TCP. The Driver exposes the below configuration options.
| Option | Description |
|---|---|
| Driver Mode | Defines whether GUARDARA should act as a Client or a Server. |
| Address | In Client mode, the Address option should specify the IP address or hostname of the target system to send messages to. In Server mode, the address field defines the IP address of the network interface to listen on. For example, to listen on all available interfaces in Server mode, you must set the Address to 0.0.0.0. |
| Port | In Client mode, it represents the port number of the target service is listening on. In Server mode, it represents the port number GUARDARA should bind to receive connections. |
Network / TCP / TLS
The TCP/TLS Network Driver allows transmitting test cases over TLS. The Driver exposes the below configuration options.
| Option | Description |
|---|---|
| Driver Mode | Defines whether GUARDARA should act as a Client or a Server. |
| Address | In Client mode, the Address option should specify the IP address or hostname of the target system to send messages to. In Server mode, the address field defines the IP address of the network interface to listen on. For example, to listen on all available interfaces in Server mode, you must set the Address to 0.0.0.0. |
| Port | In Client mode, it represents the port number of the target service is listening on. In Server mode, it represents the port number GUARDARA should bind to receive connections. |
| Certificate | The certificate to present to the target. |
| Certificate Private Key | The private key of the certificate. |
| CA Certificate | The CA certificate. |
| Certificate Validation | When enabled, strict certificate validation of the target is performed, including hostname validation. |
| Debug Mode | It does not have any effect and can be ignored. This option will be removed in a future release. |
Network / TCP / HTTP
The Driver only supports Client mode operations. When sending test cases, it acts very similarly to the TCP driver: it allows sending arbitrary data, even data that does not conform to the HTTP protocol. The HTTP driver is different from the TCP driver because it handles HTTP responses, for example, the different encodings (including chunked, gzipped, etc.) and supports keep-alive connections.
The Driver exposes the below configuration options.
| Option | Description |
|---|---|
| Protocol Scheme | Whether to use plain-text HTTP or secure HTTPS. |
| Address | The Address specified the IP address or hostname of the target. |
| Port | The port number the web application or web service listening on. |
| Certificate | The certificate to present to the target. |
| Certificate Private Key | The private key of the certificate. |
| CA Certificate | The CA certificate. |
| Certificate Validation | When enabled, strict certificate validation of the target is performed, including hostname validation. |
Network / RAW
The RAW Network Driver allows sending test cases over the network. Being a raw driver, it puts messages on the network without adding any headers, such as the ethernet header. The Driver exposes the below configuration options.
| Option | Description |
|---|---|
| Network Interface | The name of the network interface to use to send the test cases. For example: eth0. |