Module Specification - Hazelwire/Hazelwire GitHub Wiki

This is the draft of the module-specification. By module-specification we mean the document that explains how to create an Hazelwire module from any piece of code or binary blob. It is developed to be as flexible as possible, the idea is that you can create a piece of vulnerable software like you would while developing any CTF, then create a Hazelwire module by packaging it into a Debian package and write a XML config file. The configfile is so the Hazelwire VM-Generator knows the specifics of your module and is able to create a configfile incorporating the user specific settings and insert that into the Debian package. After that the debian package can be installed on any computer running dpkg.

Both the flag points and the Option values specified here are the defaultvalues, they can later be replaced by userset values (the application doesn't need to know that the values differ from the defaults).

For more information on the creation of deb packages to work together with hazelwire follow our tutorial at http://hazelwire.github.com/Hazelwire/packaging_tutorial.html .

This is when you want to group multiple modules into one package and let the generation application know that they belong together. This might be handy for searching/filtering modules.

In option there is a 'type' attribute, right now there are three types namely:

• integer
• float
• text
• boolean

The type attribute will be used in the GUI to determine what kind of GUI element should be used for the configuration window.

There is also a tag system, this can be whatever you want to describe your module. In the GUI the modules will be sorted by tags in the list, so it's handy to use common tags like Buffer Overflow (instead of b0f or whatever you'd call it). Your module can have multiple tags which means it will be in the module list multiple times (once for every tag). A list of common tags will be posted later.

At this moment there are 3 different types which should be included as a tag:

• Web
• Service
• Local

If your module is a service it has to have a port to listen on. This port can be specified with the <serviceport></serviceport> tag in the general info. This tag has an attribute 'editable', if set to true the system will automaticly make an option to set the serviceport. This option will be included in the final transfered 'config.xml' for this module, just like any other option. It will also store this information in the manifest.xml for use at the server (else the sanity checking would have some serious troubles :P).

In order to distribute your module you should create a .deb of your code and package it inside of a .zip with the configfile (example displayed below) called "config.xml". Place these files in a directory that has the same name as your module so that it will be extracted to modules/*module-name*/ by the generation application.

Every module needs to have a deploy/manage script that manages the flags (inserting them) and does whatever things you need to do with it after the files are installed. This script is also responsible for handling the module specific options you specified in the initial config.xml. From this config.xml a new config.xml will be created and by default transferred to the VM in the modules/*modulename*/ directory (the location can be userset, but it will always be the same dir as your .deb). A good way of working with this is to call this script inside of the .deb's installation process. You can find the directory where the module is saved by using the Linux environment variable MODULEDIR, for more information on how to use this in your code you should check the documentation of the language you are working with (most languages support it one way or another). The deployscript should be contained in your .deb package. Your config.xml should state the absolute path that the file will have inside of the vm (after unpacking) in the configfile (<deployscript></deployscript>).

In order to distribute your module you should create a .zip archive file containing the following files: <Modulename> (dir)

• .deb package : this contains the actual vulnerable code and functions just like any other .deb package, if your .deb works on your own box it should work with Hazelwire.
• config.xml : this contains the configuration for a module in Hazelwire (see example below)

The system knows where your manage script is, and when the game start it will push the flags towards your manage script as parameters like this:

./managescript.sh deploy flag1 flag2 flag3 ... flagN

Because modules can have an arbitrary number of flags used in arbitrary ways we cannot standardize this process for you. After the system delivers the flag to your manage script you are free to do with it what you want. You could save them in a file or shove them into a database.

WARNING: Do not use string literals like 'flag' or absolute path's to your flag location in your modules. It might also be a good idea to encode the flags to prevent people from searching the whole system for flags using regular expressions.

This is actually just for the framework developers but I wouldn't want any confusion about this. A module can be made hidden by including <hidden>true</hidden> in the general-info section of the config.xml. This means that it will get installed by default and it will not show in the list of available modules. This is used for installing things like the ClientBot (actually just the clientbot right now... but basicly management stuff the administrator doesn't need to worry about).

<hazelwire-module>
	<general-info>
		<name>Test Module</name>
		<author>Tim Strijdhorst</author>
		<date>02-10-2011</date>
		<file>test.deb</file>
		<deployscript>/usr/share/test/deploy.sh</deployscript>
		<serviceport editable="true">31337</serviceport>
		<package>
			<name>Hazelwire Test Package</name>
			<id>1</id>
		</package>
		<tags>
			<tag>Service</tag>
			<tag>Buffer Overflow</tag>
			<tag>Format String</tag>
		</tags>
	</general-info>
	<flags>
		<flag>
			<points>10</points>
		</flag>
		<flag>
			<points>5</points>
		</flag>
	</flags>
	<options>
		<option>
			<name>Welcome message</name>
			<value type="text">Welcome to the megacorp website</value>
		</option>
		<option>
			<name>Hardcore mode</name>
			<value type="boolean">false</value>
		</option>
		<option>
			<name>Something that apparently neeads a floating point</name>
			<value type="float">3.141592</value>
		</option>
	</options>
</hazelwire-module>

Please note you are in no way bound to the /usr/share/hazelwire/ directory. This is just the dir we use ourselves to give us a little more oversight but in the wild you probably want don't want to put all the modules next to eachother...

Also note the use of os.getenv("MODULEDIR") to get to the config.xml with the user-specific settings. In this case it has just been used for the editable port, which is also just an option from the module perspective (although a special one generated by the system).

#!/usr/bin/python

import sys
import xml.dom.minidom
import os

if sys.argv[1] == 'deploy':
    flag = sys.argv[2]
    f = open("/usr/share/hazelwire/testmodule3/exploit/flag.txt", 'w')
    f.write(flag)
    f.close()

if sys.argv[1] == "configure":
    dom = xml.dom.minidom.parse(os.getenv("MODULEDIR")+"testmodule3/config.xml")
    #The service port is configurable in this module, get it from the XML:
    for option in dom.getElementsByTagName("option"):
        if option.getElementsByTagName("name")[0].childNodes[0].data == "Service port":
            port = option.getElementsByTagName("value")[0].childNodes[0].data
    #Write the port number to a file in the module dir
    f = open("/usr/share/hazelwire/testmodule3/port", "w")
    f.write(port)
    f.close()

The XML format is created according to the guidelines you can find here: http://www.ibm.com/developerworks/xml/library/x-eleatt/index.html