1 Introduction

The WordExport plugin lets you export the contents of your repository into a Word XML formatted document.

In order for a note to appear in the exported report it will have to be assigned to the ‘WordExport ready’ category although the name of the category can be adjusted through the Configuration Manager constant.

In addition to this, the note’s Text needs to be formatted in a particular way as discussed in the next section of this guide.

Finally, you would need a template (although a default one is provided). A template is a specially formatted Word XML document that will be filled with the contents from the notes in your repository.

2 Note Format

The Framework lets you define your own fields, you can define as many fields as you want in your note’s Text as long as you follow the right format.

For this guide we are going to use: Title, Risk, Description and Recommendation:

3 A Basic Template

In order for the WordExport plugin to properly fill in your template, you will need to create a set of Custom Document Properties in your Word template.

Lets start with a new empty document. Go to the Advance Properties window. File -> Prepare -> Properties -> Document Properties -> Advanced Properties:

As you can see in the screenshot above, the set of Custom Properties must match the fields we defined in the Text of our note.

The next thing you need to do is create the document layout that you want. Hopefully any combination will do the trick. For example we will have a Details section and Summary of Findings table:

4 Import the Dradis Schema

Before we can continue we need to import the Dradis Framework XML Schema (dradisframework.xsd) to our current document.

The easiest way to do that is through the Developer tab in Word (File -> Word Options -> Popular -> tick the ‘Show Developer tab in the Ribbon’ check box).

[ Word 2003 note: To add the schema go to Tools -> Templates and Add-Ins (screenshot). ]

Go to the Schema option, then Add Schema, choose the downloaded copy of dradisframework.xsd (Note that this file is also provided with Dradis in /server/vendor/plugins/word_export/dradisframework.xsd).

And fill in the rest of the details:

That would create a new schema in the list and you just need to click on it to associate it with your current document.

Please note that you will only need to do this step once. When you are creating your second template, the schema would already be there and you would only need to associate it with the document.

5 Identify Sections

If everything goes according to plan, that should have activated the XML Structure panel on the right-hand side of the window as shown in the screenshot (click to enlarge – Word 2003 screenshot).

In the upper section of the panel you will see the XML structure of your document (more later). In the lower section you will see all the elements defined in the dradisframework.xsd schema which are:

• dradis-section: Used to delimit each section of the document.
• dradis-template: The plugin will repeat the section of the document that is enclosed between these tags for every Note in your reporting category.
• dradis-placeholder: Used internally by the plugin. You should not need to use this element.

What we need to do now is go through our document layout and apply these tags to the relevant sections.

To do this, just select the text you want to apply the tag to and then click on the chosen element in the XML panel.

Keep in mind that the plugin will only repeat the sections enclosed between dradis-template tags, so you can have introduction paragraphs, or other sub-sections inside the section that will not be repeated.

In our simple example, the result should be similar to the one shown in the screenshot:

6 Insert the Document Fields

The last thing we need to do with our template is indicate where the plugin needs to place the contents of the different fields of your notes.

As already discussed we are going to use Document Custom Properties to do it, so we need to insert the relevant fields in the right locations of our template.

To insert a field, select the text you want to replace (for instance we are going to use the Title field instead of the current Issue Title) and go to Insert -> Quick Parts -> Field…

[ Word 2003 note: To insert a field, select the text you want to replace (for instance we are going to use the Title field instead of the current Issue Title) and go to Insert -> Field… ]

In the Field names list, choose DocProperty and in the Property list choose Title. Be careful because there will be two Title properties: the first one is Word’s default property, the second one is the one we defined.

Repeat the process with every field in you note, replace the dummy text we used to create the look and feel of the template with you Custom Property fields.

Once you have inserted the field, Word will swap your text with the default text you chose when you created the Custom Property. It will also highlight the field with a grey background when you click on it.The final result should look like the screenshot below.

7 Upload to the Server

The final stage in this process. Save the document as a Word 2003 XML document. Use the filename template.xml.

Go to your Dradis installation folder, backup the current template (./server/vendor/plugins/word_export/template.xml) and replace it with your new one.

You don’t need to restart the server in order for the plugin to pick up the new template!

To get you started you can download the sample template we have created during this guide. There is also a new entry in the WordExport menu: View template that lets you inspect the current template used by the plugin.

8 Need help with your reporting template?

If you need help customizing your report templates, Security Roots Ltd offers a range of Dradis professional services including report customization.

You may also want to look into Dradis Professional Edition, the version of Dradis tailored to the needs of professional security companies with advanced reporting features.