Canopy has a Report template "form" builder. This allows you to build the general layouts using headers, nested headers, rich-text blocks and tables.
First, you create a Report template by clicking on the button: that can be found under Templates → Reports. This button shows the following pop-up window:
To add a new section (main heading) level click on the top level '+' button:
This pops up the New Content window, which allows you to select three types of content types:
Selecting a type and then saving allows you to add to the structure of the document:
Once you add a section, you can also delete it or rename it. If it's a table, you can also add/remove rows to the table:
This table is using the 'Resource' type for person, the 'Text' type for the role and 'Date' type for the date involved field.
If you have built a report template in another instance of Canopy, or if CheckSec Support send you one (typically as a JSON file) you can export/import it as follows:
# List the templates installed canopy-manage templatedocument # Export a specific template canopy-manage templatedocument --export $id $template.json # Import a specific template canopy-manage templatedocument --import $template.json |
If you receive errors regarding uuid values, edit the exported $template.json file and replace all of the uuid values with null. |
Once a Report template has been built, the XML mapping document can be exported from Canopy. This is a combination of the custom report structure, Canopy's default data model and any other custom fields (REF). This document can be exported by clicking on the Download XML button in the follow screen:
This outputs a file name $reportname.xml.
The XML document is structured around Canopy's model hierarchy.
Section | Description | XPath |
---|---|---|
checksec | This is the main root of the XML document | /checksec |
system_data | This is system specific data and is rarely used in customer reports, but may be useful for cross-referencing/labelling if required. | /checksec/system_data |
report | The report section of the XML structure is where report specific fields (static and dynamic) are stored. Custom report structure and data (i.e. what is built based on the Building a Report template section above) is output under the report/content section. | /checksec/report |
company | This is the main starting point for the hierarchy of data within Canopy. Canopy groups its data under company (or 'client') containers. Company specific fields are available under the company node, such as the company's name, the account manager, etc. All other sections of the XML document fall under this node. | /checksec/company |
project | The phase node stores all project related material, including associated phases. Under the project level you can access standard project fields, such as the title, reference and so on, as well as any custom fields added via the Administrative interface in Canopy. | /checksec/company/project/ |
phases | The phase node stores all phase related material, including the findings, assets and so on. Under the phase level you can access standard phase fields, such as the title, reference and so on, as well as any custom fields added via the Administrative interface in Canopy. | /checksec/company/project/phases/phase |
findings_by_finding (Group by: Finding), findings_by_asset (Group by: Asset), findings_by_category (Group by: Category), findings_by_category_and_attack_class (Group by: Category and Attack Class), findings_ by_rating (DEPRECATED) | Canopy's finding data is stored under different node hierarchies. Multiple node hierarchies are used to make Word template setup more convenient:
The above groupings are only made available for convenience purposes, as writing complex XPaths to look up data from a single tree hierarchy can be tricky and inefficient. | /checksec/company/project/phases/phase/findings_by_finding |
findings | The findings section provides access to the finding fields, such as title, rating_type (the overall rating), status, CVSS ratings, etc. Here you can also find the finding's content and custom fields - under the 'content' sub-section. | /checksec/company/project/phases/phase/findings_by_finding/finding |
assets | The assets section contains the asset fields. There are also some summary fields here such as a csv list of assets and a csv list of ports per asset - both convenience functions to save Word template setup overhead. | /checksec/company/project/phases/phase/findings_by_finding/finding/assets |
examples | The examples section includes each example that has been output that's associated with the asset and the finding. There are many fields here, such as the title, source, etc. The example detail field is a rich text field where tool data or additional manual data tends to be included. | /checksec/company/project/phases/phase/findings_by_finding/finding/assets/examples |
references | This section provides access to the reference fields. References are structured data sets used to store items such as CVE, CWE, and other types of reference information (public or private). | /checksec/company/project/phases/phase/findings_by_finding |
retest | This section is a special findings block that contains re-test history information. | /checksec/company/project/phases/phase/retest |
Data stored in Canopy can be linked (mapped) to Word documents using the Canopy Word plugin. This can be downloaded from the CheckSec Clients Portal (https://clients.checksec.com). If you need access, please contact support via https://support.checksec.com. For information on installing the plugin, see Installing the Canopy Word mapping plugin.
The plugin allows you to import the canopy data fields, along with your own custom report fields, and any custom fields you might have defined via the Administration interface. This "data model" (output as an XML file) allows you to insert placeholders for data that will be populated during the report generation process. Around these data placeholders you can add logic for repeating (where you expect to have 0, 1 or more entries) and conditionals (i.e. "if" logic) that you can use to dynamically include/exclude other pieces of data or even entire sections of a document (e.g. if you want a web app summary section to be added when web app findings are present, you can do that using conditionals - see below).
There are five main types of fields in use:
These fields must be inserted using the CheckSec provided plugin. Fields inserted from the Developer tab may not function as expected. |
Once the plugin has been installed, you're now ready to map the Word document. In order to map the Word document, follow these steps:
When setting up Word templates, we recommend Design Mode be enabled as it helps with being precise from a data point insertion perspective. However, it can be helpful to turn it off when you want to review general layout and styling. |
Data fields in the panel can be accessed by either drag and drop or using right-click and then inserting required option:
For repeat sections - i.e. expandable nodes in the XML tree - the options for "Insert Repeat content control" will be available:
For example, if you wanted to insert a selection of data points from the finding structure and then repeat the section, you can build up a section like the following:
The above screenshot has an example of a mix of configurations including simple data fields, conditionals (for the table colour selection based on the rating) and repeats (around the asset, around the finding table block itself and around the entire section 4 to repeat for multiple phases, if available). To achieve this:
A short video is available to show you how to use the Canopy mapping plugin:
REF.
Conditionals are very powerful, but require some experience with XPath. The table below provides some common conditionals that
Example requirement | Sample XPath |
---|---|
Check if a finding is rated as critical. | Either of the following options will work:
|
Check if any of the findings have CVSS3 score is in a certain range. For example, you might want to output a specific block based on whether there are CVSS3 scores in any finding that are rated as 'High' (qualitatively speaking). | count(/checksec[1]/company[1]/project[1]/phases[1]/phase[1]/findings_by_finding[1]/finding[cvss3_score >= 7.0 and cvss3_score < 10.0])>0 |
Check if there is a CVSS3 score defined using a boolean check as to whether a node value is set. | boolean(/checksec[1]/company[1]/project[1]/phases[1]/phase[1]/findings_by_finding[1]/finding[node()]) |
Styling content controls in Word
There are two main types of styling Word considers: run level and block level. Runs are typically simple data points or a single paragraph. These can be styled in the Word document as normal. For example, if a finding title is inserted, this can be styled and the styling will be retained during report generation:
However, when considering blocks and styling, Word needs to be told what style to apply for the base styling. The block content can then influence in the styling. Our block controls are the XHTML fields inserted into the Word document (i.e. wrapped with XHTML label and containing <div>Field name</div> content placeholders). These fields must be configured to use a specific base style when something other than Normal is required. This can be done by using the right-click context menu and select the appropriate style from the XHTML Styles option:
If you want a custom style to appear in this list, you must ensure its Style type (in the Style create/edit dialogue) is set to: Linked (paragraph and character). |
Canopy supports Microsoft Word charts natively. This means that any chart you can build in Word, you can have an associated plugin to generate the chart data to populate it. This gives you lots of flexibility to be able to display data. Some example chart implementations that are available include:
And so on. Access to the default chart set is available on request (chart plugins). We can also help you build chart plugins, as required. Please open a support ticket via https://support.checksec.com if you have any questions regarding this.
When the Word template is set up to include the data points that should be populated from Canopy, it then needs to be uploaded to Canopy so other users can use it for report generation.
To upload a newly mapped Word template, or an updated Word template, following these steps:
if you have updated a Word template, there's no need to create a new Report Template, simply upload the updated template to the existing Report Template. If you create a NEW report template, none of the report specific fields (e.g. exec summary, scope) will be available, which will lead to incorrect reports being generated. |
The fields are as follows:
TODO.