<< Previouse | Up | Finished

Agent and Monitor

Now we are ready to configure our agent and monitors. Agents are special Peach processes that can be run locally or remote. These processes host one or more monitors that can perform such actions as attaching debuggers, watching memory consumption, etc. For this tutorial we are going to configure Microsoft WinDbg to monitor mplayer.exe for exceptions and other common issues. Additionally we will enable the HEAP debugging for the target process.

Configure the Agent and Monitor

First lets locate the commented out <Agent> element in the template file, it will look something like this:

<!-- TODO: Configure agent/monitors
        <Agent name="LocalAgent" location="http://127.0.0.1:9000">
        <Monitor class="test.TestStopOnFirst" />
        </Agent>
-->

We are going to uncomment this section and remove the "location" attribute. When no "location" attribute is present, Peach will automatically start a local Peach Agent. Additionally we will configure two monitors, a debugger and PageHeap.

<Agent name="LocalAgent">
   <Monitor class="debugger.WindowsDebugEngine">

        <!-- The command line to run.  Notice the filename provided matched up 
             to what is provided below in the Publisher configuration -->
        <Param name="CommandLine" value="mplayer.exe fuzzed.png" />

        <!-- This parameter will cause the debugger to wait for an action-call in
             the state model with a method="ScoobySnacks" before running
             program.
        -->
        <Param name="StartOnCall" value="ScoobySnacks" />

    </Monitor>

    <!-- Enable heap debugging on our process as well. -->
    <Monitor class="process.PageHeap">
        <Param name="Executable" value="mplayer.exe"/>
    </Monitor>
</Agent>

Configure State Model

Our current State Model looks like this:

<!-- This is our simple png state model -->
<StateModel name="TheState" initialState="Initial">
        <State name="Initial">
                
                <!-- Write out our png file -->
                <Action type="output" publisher="file">
                        <DataModel ref="TheDataModel"/>

                        <!-- This is our folder of sample files to read in -->
                        <Data name="data" fileName="samples/*.png"/>
                </Action>
                
                <Action type="close" publisher="file"/>
                
                <!-- Launch the target process -->
                <Action type="call" method="LaunchMplayer" publisher="launcher"/>
        </State>
</StateModel>

The only change we are going to make is to the "call" action. We are going to change the method attribute to also be "ScoobySnacks" to match up with our agent configuration.

<!-- This is our simple png state model -->
<StateModel name="TheState" initialState="Initial">
        <State name="Initial">
                
                <!-- Write out our png file -->
                <Action type="output" publisher="file">
                        <DataModel ref="TheDataModel"/>

                        <!-- This is our folder of sample files to read in -->
                        <Data name="data" fileName="samples/*.png"/>
                </Action>
                
                <Action type="close" publisher="file"/>
                
                <!-- Launch the target process -->
                <Action type="call" method="ScoobySnacks" publisher="launcher"/>
        </State>
</StateModel>

Configure Test

Okay, now we just need to enable the agent for our test. Head down to the <Test> element, specifically we are looking to uncomment this line, and modify our Launcher publisher.

<!-- <Agent ref="LocalAgent"/> -->

Leaving us with this:

<Test name="TheTest">
    <Agent ref="LocalAgent"/>
    <StateModel ref="TheState"/>
    
    <Publisher name="file" class="file.FileWriter">
        <Param name="fileName" value="fuzzed.png"/>
    </Publisher>

    <Publisher name="launcher" class="process.Launcher">
        <Param name="Command" value="mplayer fuzzed.png" />
    </Publisher>
</Test>

Then changing the Publisher Launcher to DebugLauncher and remove it's Param element. Leaving us with this:

<Test name="TheTest">
    <Agent ref="LocalAgent"/>
    <StateModel ref="TheState"/>
    
    <Publisher name="file" class="file.FileWriter">
        <Param name="fileName" value="fuzzed.png"/>
    </Publisher>

    <Publisher name="launcher" class="process.DebuggerLauncher"/>
</Test>

Configure Logging

Now that we are using monitors that can detect faults we will want to configure a logging mechanism to capture the results of our fuzzer run.

Todo this add the following to the <Run> element at the bottom of our XML file:

<Logger class="logger.Filesystem">
    <Param name="path" value="logs" />
</Logger>

So it looks like this:

<Run name="DefaultRun">
    
    <Test ref="TheTest" />

    <Logger class="logger.Filesystem">
        <Param name="path" value="logs" />
    </Logger>
    
</Run>

Running Fuzzer

peach png.xml