You can generate project report using a custom Word template. In order to make a proper Word template, you should have a Microsoft Windows machine with Microsoft Word 2010 or more. Please note, that older Microsoft Word versions or Microsoft Word for Mac OS are not suitable for creating custom templates.

First of all, you need to enable the Developer tab in Word - you will need it for inserting variables and lists into the template. Please refer to Microsoft Office documentation on how to do this. After that tab is enabled, switch to it and enable the Design Mode. You need this mode to make all lists and variables visible.

There are 2 ways to insert data into the template:

Text Variables

Simple global variables insert some static data into the report. All variables look like a usual text within curly brackets (for example, {variable_name}). The following variables are supported:

• {project} - project name
• {company} - project company name
• {year} - project year
• {start_date} - project start date
• {deadline} - project deadline date
• {rating} - project rating
• {date} - current date
• {time} - current time
• {admin_name} - project admin name
• {admin_email} - project admin e-mail address
• {auditor_name} - current user name
• {auditor_email} - current user e-mail address
• {target_count} - project target count
• {check_count} - project check count
• {high_check_count} - check count with "High Risk" rating
• {med_check_count} - check count with "Medium Risk" rating
• {low_check_count} - check count with "Low Risk" rating
• {info_check_count} - check count with "Info" rating

Content Control

Content control blocks are responsible for inserting lists and variables into the report. You can insert content control blocks by pressing the Rich Text Content Control button in the Developer tab.

After the content control is inserted into the template, you should press the Properties button to edit its properties. The title of the content control doesn't affect anything - you can put there anything you want, so you can easily know what that control does. The system uses the field named Tag.

There are 4 different types of control tags which you can use in your templates:

• variable - you can use variables to insert content into the report, in conditions and list filters. A variable tag looks like this:

  var:SCOPE.NAME

  • SCOPE - an optional variable visibility scope. Scope is an object, from which the variable will get its value. The reporting engine uses scopes to access variables in lists. You can skip the scope specification for a variable, then the system will take the corresponding value from the current scope. See the detailed scopes explanation for more info.

  • NAME - variable name. Available variable names depend on object you get that variable from. See the full list of all available objects and their variables for more info.

  Example:

  var:project.name

• list - a list of objects. For example, it could be a list of targets within a project or a list of checks within a control. A list looks as follows:

  list:SCOPE.NAME

  • SCOPE - an optional list visibility scope. Scope is an object, from which the variable will get its list. The reporting engine uses scopes to access variables in lists. You can skip the scope specification for a list, then the system will take the corresponding value from the current scope. See the detailed scopes explanation for more info.

  • NAME - list name. Available list names depend on object you get that list from. See the full list of all available list names for more info.
  You can nest multiple list types into each other, so, for example if you use list:category on the top level, it will contain all categories across all targets within that project. Then you can create a list called list:check within it and that list will contain all checks within that particular category for all targets. The same is for other lists - if you create a target list, which has category list and which has check list, then you will get a checklist for each category within each target. Please refer to a list of possible object lists below.
• filter - you can filter lists by using filter on certain list item variable. A list with a filter looks like this:

  list:LIST|filter:VARIABLE(VALUE)

  • LIST - the name of a list variable. For example, it could be project.target, which would refer to the project target list. See the full list of all available objects and their variables for more info.
  • VARIABLE - the name of some variable within the list item. So, if you have a list of checks, then it should be a check variable, etc. Please note that it's not allowed to use a scope specifier here, only variable names are allowed. For example, if you have a list of checks, it could be rating, which would refer to the check rating. You can check a full list of variables for corresponding objects above, in the "variable" section.
  • VALUE - the scalar value (number or text), against which the variable is checked.
  
  

  For example, if you want to have a list of only high-risk checks, then the following tag should be used:

  list:check|filter:rating(high)

  You can use filters for every list and on every variable, but currently that mostly makes sense only for check lists and check ratings.

• condition - condition block. If the condition is true, then the text inside this content control is inserted into the report, otherwise the content block is removed. The condition tag looks like this:

  if:VARIABLE(VALUE)

  • VARIABLE - the name of some variable. For example, it could be project.rating, which would refer to the project overall rating. You can check a full list of available variables above, in the "variable" section.
  • VALUE - is the value, against which the variable is checked. There are 3 value types supported:
    • scalar value (some number or text) - checks if the variable specified is equal to the value provided. For example, you need to check if project rating is equal to 5:

      if:project.rating(5)

    • list of numbers or text values - checks if the variable specified is equal to one of the values provided. For example, you need to check if id is equal to 1, 2 or 3:

      if:id(1,2,3)

    • range of numbers - checks if the variable specified is within the given range (the range includes both starting and ending values). For example, you check if rating is >= 2 and <= 5 as follows:

      if:rating(2..5)

List of Available Objects, Variables and Lists

• project - this object represents the whole project, for which the report is generated. This is the default scope for the report - in other words, when you use a variable which is outside of any list and without a scope specified, it will get its value from the project object.

  Variables:

  • name - project name
  • year - project year
  • rating - project total rating, calculated over all targets
  
  

  Lists:

  • target - a list of targets in project
  • category - a list of all categories in all targets in project
  • check - a list of all checks in project
  
   

• target - this object represents one particular target from the project's target list. You can access this object from within the project.target list.

  Variables:

  • host - target host
  • description - target description
  
  

  Lists:

  • category - category list for target
  • check - a list of checks for target
  
   

• category - this object represents one particular category for project's or target's category list. You can access this object from within the project.category list or from target.category list.

  Variables:

  • name - category name
  
  

  Lists:

  • control - a list of controls within category
  • check - a list of category's checks
  
   

• control - this object is a single control for category's control list. You can access this kind of object from within the category.control list.

  Variables:

  • name - control name
  
  

  Lists:

  • check - a list of checks in control
  
   

• check - the object is a check representation for project's, target's, category's or control's list of checks. You can access this object from project.check, target.check, category.check or control.check lists.

  Variables:

  • name - check name
  • background_info - check background info
  • hints - check hints
  • question - check question
  • rating - check rating (text constant representation). Possible values:
    • high
    • med
    • low
    • info
    • hidden
    • no_vuln
    • none
  • rating_name - check rating name (like "High Risk" for high risk, etc.)
  • target - check target host
  • result - check result
  • technical_result - technical result
  • management_result - management result
  • reference - check reference name
  • solution - check solution. If a check has multiple solutions, this variable will hold a concatenated value.
  • technical_solution - technical solution
  • management_solution - management solution
  
  

  Lists:

  • attachment - a list of attachments for check
  
   

• attachment - the object is an attachment representation for check's attachment list. You can access this object from within the check.attachment list.

  Variables:

  • name - attachment file name (with extension)
  • image - attachment body. You can use this variable to insert the actual attachment image into the place you need.

Scopes Explanation

Scopes mechanism comes into action when you use object lists. For example, when you use some variables within a category list, your current scope will be tied to a category from that list. So, if you use a variable named name without any explicit scope specification inside that block, the system will know that it needs to insert there the name of a particular category from that list.

Then, for example, within that category block you need to have a list of controls. And inside the control block you use a variable named name without scope specification. In this case the system will get the value from the particular control, because control is the current variable scope.

If you have multiple nested lists, you can access to variables of the upper level lists by specifying the scope modififer. For example, you have 3 nested lists: targets → categories → checks. You can access target's variables from the check or category block by specifying the scope, for example: var:target.host (target here is the desired variable scope).

The default scope for the report is a project object. In other words, when you use a variable without a scope specified and which is not inside any lists, it will get its value from the project object.