PlexTrac provides a default template for exporting reports. While this default template works for many scenarios, situations exist when a more tailored approach is required.
To bridge this gap and provide greater flexibility, a range of pre-built export templates are provided. These templates contain a user-friendly framework that allows customizing the output without needing knowledge of the Jinja2 language or extensive programming skills. These templates can be used or modified as is, resulting in personalized reports that meet requirements.
A Jinja template is a specialized document template incorporating placeholders and dynamic content generation capabilities using the Jinja2 templating engine. These templates are designed to streamline the process of creating customized Word documents with variable content.
For those new to the self-service report templates, the subpages in the Overview section provide essential terminology, various templating types, and different styles used within Word document templates. It also contains an overview of how templates are associated and exported within PlexTrac, with links to more robust documentation and step-by-step instructions.
This introductory material is designed to help orientate and establish a solid foundation in templating concepts.
Each report export template has three main sections:
Setup Code
Cover Page and Table of Contents
Report Body
This section begins at the document's start and continues to the first cover page option. This section provides the user the ability to:
Configure formatting options, including defining colors for table headers, background severity colors, and severity text colors (see each template's "Defining Color Codes" page for more information).
Specify display options, allowing customization of how the title page, summary table, and detailed findings sections are presented (see each template's "Selecting Display Options" page for more information).
Incorporate pre-built functions that can be invoked elsewhere in the document (see each template's "Using Pre-Built Functions" page for more information).
Users can modify formatting and display options, but changing or creating additional pre-built functions requires understanding the Jinja2 language and the PlexTrac data structure.
This section offers multiple pre-built cover page options for users to choose from. Users can make adjustments to graphics and static content as needed. Advanced users may further enhance the content by incorporating additional data extracted from PlexTrac through augmentations to the setup code.
This section encompasses all content following the Cover Page and Table of Contents. It is the primary area where pre-built functions are invoked to format the exported data per user preferences. Users can include static content, such as section headings or paragraphs, that remain consistent across different reports. Standard divisions within the Report Body often include sections such as the Executive Summary, Methodology, Findings Summary, Detailed Findings, and Appendixes.
Variables in the template represent dynamic data and are used to insert and display values from a data source within the template. Variables are enclosed in double curly braces {{ }}
. They can display values, perform operations, or apply filters to manipulate the data before rendering it in the template.
Various template elements, including namespaces, color codes, option definitions, generic macros, and a table of contents macro, can be modified.
Jinja template's static content is adjustable except for the setup code.
Below is an example of variables from a pre-built report export template.
Each template will have a different combination of variables and parameters found at the beginning of the template. A specific template may not include all of the variables listed below.
Namespaces: A dictionary or context containing variable names and their corresponding values. Jinja2 uses this namespace to replace the placeholder with the actual values when rendering a template. Several namespaces are defined to store variables of different data types, including strings, numbers, lists, booleans, integers, and floats.
Color Codes: Used to change table headings colors, criticality backgrounds within tables, and severity text colors.
Display Options: Used for tables and other display configurations in the exported report.
Cover Pages: Used to personalize the report by updating the cover page's colors, background images, and logo.
Option Definitions: Defines cover page options, display settings, and formatting options. For example, setting the cover page to "3," enabling strict narratives, and setting the display of informational findings to true.
Generic Macros: Provides flexibility in customizing the template's behavior, such as setting report field variables, displaying narratives with customizable headings and handling errors.
Table of Contents Macro: Generates and defines a table of contents.
Other Macros: Additional macros are used to set severity colors and control the spacing between findings in the report.
Static Content vs. Jinja Code: Anything that is not Jinja code can be modified without inducing errors on export. Any static content can be changed. Additional static content can be added anywhere other than the setup code section. It is easy to identify Jinja code statements, as they are always bookended with one of two methods:
Logic Statements
{%
<Logic statements are bracketed with curly-brace percent signs>
%}
Print Statements
{{
<Print statements are bracketed with double curly braces>
}}
In Jinja, macros allow users to define reusable template code pieces. They are similar to functions or subroutines in traditional programming languages. Macros are useful for creating modular and maintainable templates. Jinja macros provide numerous advantages in templating and offer reusability, modularity, and consistency by reusing template components.
The pre-built report export templates include macros to facilitate easy modification. The specific macros available vary on the template.
Jinja macros and Word macros are two distinct concepts with different applications. Jinja macros are utilized for web templating and generating dynamic content, whereas Word macros are used for automating tasks and customizing Microsoft Word documents. These macros serve unique purposes and are programmed using different languages and environments.
PlexTrac does not use Word macros in any template.
The basic syntax is as follows:
macro_name
: The name of the macro. It can be any valid identifier.
(arg1, arg2, ...)
: Optional arguments that are passed to the macro.
{# Macro content here #}
: Where the content of the macro is defined, which can include the Jinja template code.
To use a macro, call it by its name and provide any required arguments:
For example:
{%p macro display_narrative(label,label_as_heading=true,heading_level = “h2”,error = true) %}
The macro's content will be inserted into the template when it is called, with any arguments replaced by the values provided.
Arguments are the values or parameters users can pass to macros when invoking these elements within a template. These arguments are pivotal in customizing the behavior, enabling users to supply dynamic data for processing or displaying within the template. Arguments may be values of any data type and mandatory or optional. Macros may have pre-defined values to use if no arguments are passed when calling the function.
Arguments may become mandatory if any argument's default value is changed beyond position 1.
In Jinja, positions refer to the order in which arguments are defined and expected when calling the macro. The positions determine where specific values should be provided when invoking the macro. Each argument in a macro has a designated position based on the order in which it appears in the macro's argument list.
For instance, when calling a macro such as my_macro_name()
, which has no arguments (indicated by the empty parentheses), may still be a valid call. This is because default values can be defined for the macro's arguments, or these arguments may only affect the macro's behavior when explicitly used. However, arguments beyond the first position may only be passed if arguments are provided for all preceding positions.
In the example, if the argument in position one has a default value (e.g., "foobar") defined in the macro, changing the argument in position two would still require the user to provide an argument for position 1, even if it matches the default value. For instance, my_macro_name("foobar", true)
it would be a valid call. In this case, the argument's value at position two is changed to true
, but it is still necessary to provide a value for the argument at position one, even if it matches the default value of "foobar." This ensures that the arguments are correctly passed and maintains the intended behavior of the macro.
PlexTrac identifies which (if any) arguments are mandatory in the specific template documentation for each macro.
Macro calls should be arranged in the Report Body section of the template and subsections of the report.
This page defines terms used throughout the Pre-Built Report Exports documentation. Two distinct categories of terminology are utilized, each accompanied by its unique label:
Data Types Inside the PlexTrac Platform: These terms are identified as (PlexTrac)
and pertain to data types, structures, or components intrinsic to the PlexTrac platform and may encompass findings, assets, users, reports, and other data entities that play a central role in PlexTrac.
Elements of a Jinja Template: These terms are identified as (Template)
and indicate elements specific to Jinja templates. These include placeholders (variables), control structures (such as loops and conditionals), filters (utilized for text manipulation), and other elements.
Baseline Jinja Template (Template)
: The .docx file is being modified to create customized report exports. It is uploaded to Account Admin -> Templates -> Export templates.
Detailed Findings (Template):
The Jinja template's section renders configurable detailed information about each finding, which can be divided by scopes.
Editor Table (PlexTrac)
: A table generated inside a narrative table in PlexTrac.
Finding's Layout (PlexTrac)
: Defines the finding custom fields that will be available whenever editing a finding in a report (optional). Found in Account Admin -> Layouts.
Jinja Table (Template)
: A table built dynamically on export by the Jinja code within the template.
Macros: In Jinja, macros are a feature that allows users to define reusable template code pieces.
Narrative Section (PlexTrac)
: An individual content block comprised of a title and a rich-text field (RTF). It may include embedded inline images, tables or code blocks.
Prefixes: Prefixes are short labels or identifiers added to reference numbers or codes. For example, findings related to network security might have "NET" as their prefix, while findings related to policy compliance might have "POL" as their prefix.
Report Custom Fields (PlexTrac)
: Metadata fields that may exist at the report level and are defined in the Details tab when editing a report and included as part of the report template. Examples include Application Name, Author, Lead Tester, Project Manager, etc.
Report Template (PlexTrac)
: The starting attributes and reusable content for a report. It comprises three main sections: The Jinja template, the report custom fields, and the narrative sections. Found in Account Admin -> Templates.
Scope: Denotes a specific category of technical examination, including Internal, External, Webapp, Wireless, Social, and Physical tests. When an engagement encompasses multiple scopes, it is termed a "multi-scope" assessment.
Scope Tag (PlexTrac)
: A tag applied to a finding to ensure that the finding is displayed in the appropriate scope sections of a report.
Static Content (Template)
: Anything in a Jinja template that is not Jinja code. Static content will always be rendered on export, as presented in the Jinja template.
Summary of Findings Table (Template)
: A Jinja table that provides one row for each finding with a user-configurable number of attribute columns such as reference number, title, severity and CVSS score. The Jinja template can render separate tables for each scope but can optionally include all findings in a single table.
Tags: In Jinja templates, tags are placeholders enclosed in double curly braces like {{ tag_name }}
. These tags can be used to insert dynamic data or logic into the template. In this case, the tags are related to findings, scopes, and prefixes.
Variables: Placeholders for dynamic data that can be substituted with actual values when the template is rendered.
Word Style (Template)
: A set of text attributes in Microsoft Word that dictate how the text of a given style will be rendered, including font, size, spacing, color and more.