This document provides information on how to set up the various template document types within Canopy so that you can generate Word, PDF and other output types from Canopy.

Canopy Document Templates allow users to define the layout of the report to be presented to users during report or SoW writing. The Canopy Document Template is used to create a Report or SoW, and is also added to the exported XML document for document mapping. In general, Canopy Document Templates have a very similar layout to how the Word Template should be laid out.

A single Canopy Document Template can be mapped to Word Templates in many different ways. For example, you might map the XML to a full report, or to a summary report, or a findings only technical report, etc. These are all mappings of the same structure to different Word documents. However, it may be necessary to have a completely different structure for the report sections. Multiple Canopy Report Templates can be added to facilitate this. For example, you might have a report structure specific to your standard reporting requirements, but may require several others for client-specific reporting requirements.

Template mapping plugin

The latest version of the template mapping plugin can be obtained from:

• https://checksec.com/downloads/CheckSecPluginSetup-11-19-2016.zip

Some notes on the plugin:

• Microsoft Word is the preferred template designer at the moment. Microsoft Office provides the concept of content controls to facilitate inserting data from sources into Word documents.
• Canopy only supports the OOXML standard - i.e. Microsoft Word 2007 onwards. This means Canopy cannot generate Word 2003 formats.
• The Canopy Word Plugin works on Microsoft Office 2010 and 2013 (Windows Only).

Mapping a Microsoft Word Template

Setting Up

See the download link above.

Note: The plugin also installs .NET related dependencies. 

Once installed, follow these steps:

1. Open or Create a Word Document for mapping
2. Next, download the XML structure from Canopy to map to the Word document. This can be accessed via the Templates interface. Select the Template and click on "Download XML".
3. In Microsoft Word, click the "Authoring" ribbon tab. To begin the mapping process, click this tab and click on the "Show XML" ribbon button.
• Note: The first time you load the XML into the Word document for mapping, a dialogue will appear guiding you through the process.
4. An XML panel will be shown to the right, you can begin to inspect it for items to map to the document

Note: Enable the "Design Mode" function to ensure you are able to see all of the information about the Content Controls mapped to the document.

Starting from new or modifying an existing document

The mapping process can be applied to a completely new document or you can map existing documents. 

When mapping existing documents, ensure that there are no embedded files or links to external files in the template, as this may cause docx generation to fail.

Mapping Elements

In order to map an element (for example, the Company's name), expand the tree to find the element (CheckSec -> Company -> Name), right click and select "Data Value" and "Insert Content Control". This will insert a content control, which will then have the data inserted at run time.

Some elements may contain XHTML content (this is converted at runtime to OOXML). Those elements are wrapped within a DIV (<div></div>) block. Do not modify the DIV block, it's a placeholder to ensure the correct content gets inserted and converted. The DIV blocks will not automatically pick up the formatting in the Word document (*). The style must be set on these sections. To do this:

1. Left click inside the DIV block
2. Right click and select XHTML Style
3. Choose the style you want applied and save

Repeating Content Sections

A repeating section of a document is where data may have 1 or many instances to output. For example, a Finding typically has 1 or many instances to report on, so when designing Finding related sections, it is likely that you will need to repeat these sections. In order to achieve this, first map your elements for that section. For a Finding, you might want to include: Title, Rating, and the content fields. Map these individual elements (as above), then:

1. Select the elements (mouse select)
2. Navigate to the finding node
3. Right click and select "Repeat" -> "Insert Content Control"

The section now has a repeat around it. Repeats can also be nested to facilitate more complex mappings.

Conditions (XPATHs)

XPATH 1.0 can be used for creating conditions during document generation. For example, if you wanted a section to list Findings that were rated as Critical only, you could use a Condition for this.

Example: Coloured findings summary table

This example will show how to create a list of Findings (using repeats), ordered by their rating, inside a table in the Word document

1. In the Word document, go to the section of the report where the Finding Summary is to appear
2. From the Finding node insert the Finding Title and Finding Rating into the table cells.
• XPATH: /checksec[1]/company[1]/project[1]/phases[1]/phase[1]/findings_by_finding[1]/finding/title[1]
• XPATH: /checksec[1]/company[1]/project[1]/phases[1]/phase[1]/findings_by_finding[1]/finding/rating_type[1] 
3. Select the entire row
4. Right click on the finding node and choose "Condition" -> "Insert Content Control"
5. A very basic XPATH editor will pop up. The XPATH in this instance will perform a simple string test:
• XPATH: string(/checksec[1]/company[1]/project[1]/phases[1]/phase[1]/findings_by_finding[1]/finding/rating_type[1])='Critical'
• Note: you do not need to change the numbers, the repeat process takes care of that automatically
6. Add a repeat to ensure all Critical issues are output:
• Select the entire row, right click on Finding and select "Repeat" -> "Insert Content Control"

Repeat the above process for each rating that should appear in the table, changing the string test case for each rating.

Upload the mapped document

Once the document mapping process has been finished, upload the new template to the server. It will then be available for testing report generation. To upload:

1. Log into Canopy
2. Click on Templates
3. Select the Template Schema
4. Click on Mapped Word Templates
5. Click Upload Document
6. Set the title, select the Order By option (e.g. Finding by Findings) and choose the document

Once uploaded, the file will be available for everyone to use. When testing new templates, it's recommended that you use an appropriate naming policy.

Canopy XML structure

The Canopy XML structure is fairly self explanatory. There are data items which can be mapped to different sections in the Word document, which will then be replaced at runtime.

Some sections of the XML structure are dynamic - i.e. they are dependent on the Template Schema defined for the report in use. Dynamic sections include:

• Many fields under the Report node (see Creating a Canopy Template above)
• Finding Content node (pre-defined by CheckSec for your Company)

There are also multiple Finding groups in the XML. These are:

• Findings by Finding: This is the default output, which allows you to output Findings ordered based on the CheckSec risk rating (Critical to Info, Descending)
• Findings by Asset: Use this section if you want to easily group Findings based on the Asset (e.g. output all Findings under the sub header of the asset identifier, e.g. 127.0.0.1)
• Findings by Category: use this approach to easily organise findings based on a hierarchical arrangement of Category only.
• Findings by Category and Attack Class: use this approach to easily organise findings based on a hierarchical arrangement of Category and Attack Class.

Note: These are helper structures and can be replicated using XPATHs using the standard Findings by Finding output. However, that can become tricky, hence providing these supported ordering types.