Integrating Tool Output with your Dradis Pro Template

This guide contains:

• Start by defining your Issue/Evidence fields
• Pick the tool, data source, and report template
• Map source fields to Dradis fields and customize the content.
• Tips and Tricks
  • Use Code Blocks automatically
  • Include Static Text
  • Create tables

Think of the Mappings Manager as the magic decoder ring for all the different tools. None of them speak the same language! One calls a field Description, another calls it Details, a third calls it Discussion. And, by default, exactly none of them will match your custom report template.

Before you upload tool output into your project, make sure that your Mappings Manager is configured to match your templates' report template properties.

Start by defining your Issue/Evidence fields

Make sure that you have decided on the format for your Issues and Evidence and that you've created report template properties that define the fields to be used for each.

Pick the tool, data source, and report template

Make sure you're signed in as an Administrator. Then, navigate to the Mappings Manager in the header of your instance and select the correct tool from the left-hand sidebar. We'll use Nessus in this example.

Next, you need to select which data source to use. This selection will determine the list of available fields you can use for your mapping, along with the destination they will populate in your project. Possible destinations include: Issue, Evidence, or Note. You can find the full list of all data sources, their destinations, and available tool fields here. In our example, we chose Report Item because we want to populate the Issue fields with this mapping.

After selecting the data source, the next step is to choose the correct template for which you want to create the mapping. You can have multiple mappings for the same tool, each for a different template, if you have more than one. Notice how all your Dradis fields get added automatically, based on the report template properties you created for your template before.

Please note that you won't be able to select a template that doesn't have any report template properties defined yet!

Map source fields to Dradis fields and customize the content

1. Select the appropriate source field from the dropdown, and the correct mapping syntax will be added to the content pane automatically. Repeat this process for each field. Note that the content section can be further customized; check the Tips and Tricks below.

   

2. Check the Preview pane on the right side, and confirm that the sample output looks correct after you have added everything necessary to the content fields.

   

Switch to the Validation tab and make sure that there are no errors present. If there are, add the missing Dradis fields to your mapping or edit your report template properties.



3. Note that we used the Custom Text source field for the Type Dradis field to have only static text there instead of data from the scanner.

4. You may decide that you want additional fields mapped in the Mappings Manager that don't exist in your Report Template Properties. For example, perhaps your report template uses Tags or a #[Severity]# for organising Issue severity, but you want to import the CVSS scores and CVSS vectors for issues from some or all plugins to set or verify the issue severities. In that case, you can select Custom Field as the Dradis Field, enter a field name in the text box that appears, and assign it a Source Field value.

   

5. Once you are finished with source fields and content, make sure to press the Create Mapping button at the bottom left to save your mapping.

   

6. After saving the mapping, you will be redirected to the tool mappings page, where you can see all your current mappings. To edit your mapping, press the Edit button; to delete it, press the Delete button. Note that deleting your report template will also automatically delete all associated mappings!

   

7. Proceed with adding any additional mappings by following the same steps. In the example below, we are adding another Nessus mapping for the Evidence. Note that we combined syntax from two source fields for the Location Dradis field to get the port and protocol data together. Another important feature we used here is the Custom Field Dradis field. You can use this when you need to add a field that is not present in your report template properties. As a result, Validator won't check for the presence of this field.

   

After you are done, you should see all the mappings you created listed in the scanner mappings list.

Tips and Tricks

In some situations, you'll want to format the data a little more in the Mappings Manager.

You can automatically apply code blocks, add static text or even create tables.

Use Code Blocks automatically

If you have output that is going to contain code, you'll want to wrap it in a code block. Without the code block, your Word report may try to include code (especially XML) into the internal XML structure of the Word document and cause chaos.

To prevent this chaos, just include the bc.. marker before the field name in the Editor. Make sure to use the double-dot version of the code block marker to accomodate multiple lines of code in the field.

For example:

#[Request]#
bc.. {{ burp[issue.request] }}

Include Static Text

If you want, you can also include static text in the Editor. This will be imported as static text and is helpful when you're including context for specific values.

For example, instead of just including the severity value under #[Details]# without context, we can add static text like:

#[Details]#
Severity: {{ burp[issue.severity] }}

Create Tables

You can create Custom Tables within your Dradis project or here in the Mappings Manager using the Textile syntax.

To display the data in a table, we just need to use the Textile format like:

|_.Header|_.Row|
|Body|Row|

For example, we can create a table that contains the Host/Path/Location details for our instance of Evidence:

|_.Host|_.Path|_.Location|
|{{ burp[issue.host] }}|{{ burp[issue.path] }}|{{ burp[issue.location] }}|