To introduce Fuzzware in a very basic scenario that requires very little effort to configure, lets consider fuzzing some very simple XML with a simple XSD file.
Fuzzware can be configured by a tool called Fuzzsaw, so start Fuzzsaw (Start->Fuzzware->Fuzzsaw) and create a new project from the Project menu (or use Ctrl+N). In the New Project window select Browse and create a new directory called Tutorials under the 'Fuzzware Projects' directory, then create a Tutorial1 directory under Turorials. Tutorial1 will be the directory all configuration and log files are stored in, as well as the name of your project.
Save the following two files into the Tutorial1 directory:
<tst:AddressBook xmlns:tst="urn:Fuzzware.Tutorials.Tutorial1"> Tutorial1.xsd
<?xml version="1.0" encoding="utf-8"?>
<xs:element name="Entry" minOccurs="0" maxOccurs="unbounded">
<xs:element name="FirstName" type="xs:string" />
<xs:element name="LastName" type="xs:string" />
You can open these in your favourite XML editor (I tend to use Microsoft Visual Studio, but anything will do). The XML given here is simply being used to contain an address book on people's names.
A note on XML namespaces, while technically not essential for an XML document, Fuzzware works a lot better when one is used and preferably with a namespace prefix used for all the XML nodes (the tst in the XML above). A namespace may seem like an added complication, but actually makes things simpler in the long run, so becoming comfortable with them from the outset is important.
By default for a new project, Fuzzware will select an input source of 'Fuzz an XML file'. Since we are fuzzing an XML file we will keep this option, but we need to specify the input XML and XSD files; clicking on 'Configure the input source' allows us to do this.
By default for a new project, Fuzzware will select an output destination of 'Store testcases in a directory'. The output destination is what we want to do with our fuzzed test cases. For this tutorial we just want to write them to a directory and so we don't need to change the default option. This option will default to a directory called 'out' relative to the project directory (Tutorial1) and will store test cases with a file extension of .xml, both of these need not be changed.
Now we are going to configure Fuzzware to do some very simple fuzzing. When Fuzzware creates a new project it will populate the data types and structures fuzzing configuration with default values that are a useful starting point for fuzzing a real data format. For our purposes there are too many values, so we are going to remove some.
Go to 'Options for fuzzing data types' and expand the Strings section. Select the first fuzzing technique, 'Replace with long strings'. Remove all but the first 5 values (you can multi-select by holding down Shift and selecting the 6th and last entries, delete using the delete key or Delete from the Edit menu).
For all the other String fuzzing techniques delete all the value entries as above (you can use Ctrl+a to select all entries). We also want to remove all data structure fuzzing, so select 'Options for fuzzing data structures' (the main menu on the left), expand the Occurrence section and delete all the values in the box. Now when we fuzz we should only produce a handful of test cases.
We are now ready to test our input and output configuration. Select 'Configure and Run fuzzer', by default the Test Mode should be on, click Start to run the fuzzer.
A command prompt should have appeared showing information about the execution of the fuzzer, we can safely ignore this for now. Look in the Tutorial1 directory, there should be a new directory call 'out' and a log file (called Log with a timestamp in its name, this contains the same information as is printing to the command prompt window and sometimes some extra information). Open the 'out' directory and there should be a file called OutputWithoutFuzzing.xml which should contain.
This isn't very nicely formatted for XML, so close the file, go back to the UI and from the Project menu select 'Project Properties', on the 'Output Format' tab select the option 'Format XML with line breaks and indentation'. Re-run the fuzzer. Now we should get.
At this stage it should be clear that Fuzzware is accurately reproducing the input XML.
Now we can do some fuzzing, click on the Test Mode button to turn Test Mode off and re-run the fuzzer. Looking in the 'out' directory we should find 30 test cases.
You should open a selection of these to convince yourself that Fuzzware has made changes to the files. The naming convention used for these files corresponds to the state of Fuzzware, hence state or filename like
Can be understood as
tst-FirstName - the name of the node that has been fuzzed
0 - the n-th instance of the node with that name, hence tst-FirstName-0 refers to the first node with that name, tst-FirstName-1 refers to the second and tst-FirstName-All refers to all nodes with that name.
StringLength-3 - refers to the StringLength fuzzing technique using the 3rd value from the configuration for this technique, in this case a string of length 3 characters (note, had the 3rd value in the configuration of the 'Replace with long strings' fuzzing technique been 10, then a string of length 10 would be used but the name of the state/file would still be tst-FirstName-0-StringLength-3).
That is all there is to the basic's of configuring the fuzzer if we already have an XML and XSD file.
Below are some suggestions for activities to see how some of the other fuzzing techniques work.
- Remove the values for the 'Replace with long strings' fuzzing technique and choose another string fuzzing technique and add some values. Run Fuzzware again to see the effect on the output.
- Add an Age element to the XSD and to the XML that is of type integer. Remove all the String fuzzing values (or just disable String fuzzing by changing the On to Off in the top-right hand corner of the Strings configuration box). Remove all the pre-configured values for Integer types and then choose an Integer fuzzing technique and add some values. See how Fuzzware alters integers.
- Repeat 2 for all the Integer fuzzing techniques.
- Repeat 2 for Decimal and Byte type fuzzing.
- Remove all the values (or disable fuzzing) for type fuzzing, experiment with structure fuzzing by adding values to Occurrence fuzzing.
- On the 'Configure and Run fuzzer' page try entering a Start State and then an End State (copy a state from the output testcases produced (without the file extension)).
Don't forget to delete all the output testcases between runs of Fuzzware to make it easier to see which new test cases Fuzzware has created.