Glossary of Field References

This is a glossary of fields that can be referenced for use in custom export templates.

Note that while some fields may be referenced directly (e.g. {{ CLIENT_INFO.name }}), many fields must be referenced through the use of iterative loops. This glossary is divided into sections based on how the data is accessed.

Directly Referenced Fields

These fields can be accessed anywhere in the template without using iterative loops:

Client Description: {{ CLIENT_INFO.description }}

Client Company: {{ REPORT_INFO.prepared_for }}

Client Logo: {{ CLIENT_LOGO }}

Client Name: {{ CLIENT_INFO.name }}

Client POC: {{ CLIENT_INFO.poc.name }}

Client POC email: {{ CLIENT_INFO.poc.email }}

Report End Date: {{ REPORT_INFO.end_date }}

Report Start Date: {{ REPORT_INFO.start_date }}

Report Title: {{ REPORT_INFO.title }}

Tenant Name: {{ REPORT_INFO.source_tenant.name }}

Tenant POC email: {{ REPORT_INFO.source_tenant.poc.email }}

Tenant POC Name (first last): {{ REPORT_INFO.source_tenant.poc.first }} {{ REPORT_INFO.source_tenant.poc.last }}

Total number of Findings: {{ FINDING_SUMMARY.totals.total_reported }}

Total number of Findings by Severity:

  • Critical: {{ FINDING_SUMMARY.critical.total }}

  • High: {{ FINDING_SUMMARY.high.total }}

  • Medium: {{ FINDING_SUMMARY.medium.total }}

  • Low: {{ FINDING_SUMMARY.low.total }}

  • Informational: {{ FINDING_SUMMARY.informational.total }}

Findings Fields: Unitary Values

The reference method presented in this section should be used for the following fields:

  • Finding Title

  • Finding Description

  • Finding Severity

  • Finding ID (Unique number assigned by PlexTrac)

To reference a standard unitary field associated with a finding, you will need to iterate through the findings. Before attempting to reference any field, you should use conditional statements to verify the existence of a value for the field; attempting to reference a non-existent field will result in an error. The basic syntax used to reference a finding title, severity or description using the finding description as an example, is:

{%p for group in FINDINGS %}
{%p for item in group.FINDINGS %}
{%p if item.description %}
{{ item.description }}
{%p endif %}
{%p endfor %}
{%p endfor %}

The reference syntax for the fields referenced using this method are:

  • Finding Title: {{ item.title }}

  • Finding Description: {{ item.description }}

  • Finding Severity: {{ item.severity }}

  • Finding ID Number: {{ item.flaw_id }}

Report-Level Information: Standard Lists

The reference method presented in this section should be used for the following fields:

  • Report Engagement Types

  • Report Operators

  • Report Tags

To access these data, you must iterate through the lists with a "for" loop.

{%p for type in REPORT_INFO.engagement_type %}
{{ type }}
{%p endfor %}
{%p for op in REPORT_INFO.operators %}
{{ op }}
{%p endfor %}
{%p for tag in REPORT_INFO.tags %}
{{ tag }}
{%p endfor %}

Findings Fields: Standard Lists

The reference method presented in this section should be used for the following fields:

  • Finding Affected Assets

  • Finding Recommendations

  • Finding References

  • Report Engagement Types

The above fields associated with findings are stored as arrays, even if the current implementation only allows for a single array element to be stored.

To reference an array field associated with a finding, you will need to iterate through both the findings and the elements in the array. Before attempting to reference any field, you should use conditional statements to verify the existence of a value for the field; attempting to reference a non-existent field will result in an error.

The basic syntax used to reference the element in one of these arrays, using Recommendations as an example, is:

{%p for group in FINDINGS %}
{%p for item in group.FINDINGS %}
{%p if item.recommendations %}
{%p for recommendation in item.recommendations %}
{{ recommendation }}
{%p endfor %}
{%p endif %}
{%p endfor %}
{%p endfor %}

The reference syntax for the fields referenced using this method in conjunction with iteration through the findings are:

  • Finding Affected Assets:

    • {%p for asset in item.affected_assets %}

    • {{ asset }}

    • {%p endfor %}

  • Finding Recommendations:

    • {%p for recommendation in item.recommendations %}

    • {{ recommendation }}

    • {%p endfor %}

  • Finding References:

    • {%p for reference in item.references %}

    • {{ reference }}

    • {%p endfor %}

Findings Fields: Exhibits and Code Samples

The reference method presented in this section should be used for the following fields:

  • Finding Exhibits (screenshots, images or video clips)

  • Finding Code Samples

  • Captions associated with either Exhibits or Code Samples

Finding Exhibits and Code Samples are stored as arrays, however each element of the array has two attributes that must be referenced separately: the exhibit/code sample object and the caption associated with that object (if present).

To reference an array field associated with a finding, you will need to iterate through both the findings and the elements in the array. Before attempting to reference any field, you should use conditional statements to verify the existence of a value for the field; attempting to reference a non-existent field will result in an error.

The basic syntax used to reference the attributes for an element in one of these arrays, using Exhibits as an example, is:

{%p for group in FINDINGS %}
{%p for item in group.FINDINGS %}
{%p if item.exhibits %}
{%p for exhibit in item.exhibits %}
{%p if exhibit.caption %}
{{ exhibit.caption }}
{%p endif %}
{%p if exhibit.path %}
{{ exhibit.path }}
{%p endif %}
{%p endfor %}
{%p endif %}
{%p endfor %}
{%p endfor %}

Note 1: In your Word .docx template, center {{ exhibit.caption }} and {{ exhibit.path }}.

Note 2: You can create a Style in Word that will automatically number your captions for you. For your chosen style, set "Bullets and Numbering" properties to:

  • List: Numbered

  • Level: 1

  • Numbering Style: 1,2,3...

  • Start At: 1

You can also copy and paste the "Screenshot Caption" and "CodeSample Caption" styles used in the PlexTrac Custom Export Template provided in the Overview of the Custom Word Templates section of this documentation.

The reference syntax for the fields referenced using this method in conjunction with iteration through the findings are:

  • Finding Exhibits:

    • See Above Example

  • Finding Code Samples:

    {%p if item.code_samples %}
    {%p for sample in item.code_samples %}
    {%p if sample.caption %}
    {{ sample.caption }}
    {%p endif %}
    {%p if sample.code %}
    {{ sample.code }}
    {%p endif %}
    {%p endfor %}
    {%p endif %}

Findings Fields: Scores

The reference method presented in this section should be used for the following fields:

  • Score (CVSS, CVSSv3 base, CVSSv3 Temporal or General)

When assigning a finding a score, you have three mutually exclusive options: CVSS, CVSSv3 base, CVSSv3 Temporal or General (custom scoring methodology). Each methodology includes a key (CVSS, CVSSv3 base, CVSSv3 Temporal or General), a score (free-text value) and a calculation method (free-text value). Because you may use more than one scoring system in a report, it is advisable to provide logic that checks for all three if displaying score information for a finding.

To reference a score associated with a finding, you will need to iterate through both the findings and reference the specific score key (CVSS, CVSSv3 base, CVSSv3 Temporal or General). Before attempting to reference any field, you should use conditional statements to verify the existence of a value for the field; attempting to reference a non-existent field will result in an error.

The basic syntax used to reference the attributes for an score of unknown type (CVSS, CVSSv3 base, CVSSv3 Temporal or General) is:

{%p for group in FINDINGS %}
{%p for item in group.FINDINGS %}
{%p if item.fields and item.fields.scores %}
{%p if item.fields.scores.cvss3 and item.fields.scores.cvss3.label and item.fields.scores.cvss3.value and item.fields.scores.cvss3.calculation %}
{{ item.fields.scores.cvss3.label }}: {{ item.fields.scores.cvss3.value }}
Calculation: {{ item.fields.scores.cvss3.calculation }}
{%p elif item.fields.scores.cvss3_temporal and item.fields.scores.cvss3_temporal.label and item.fields.scores.cvss3_temporal.value and item.fields.scores.cvss3_temporal_score.calculation %}
{{ item.fields.scores.cvss3_temporal.label }}: {{ item.fields.scores.cvss3_temporal.value}}
Calculation: {{ item.fields.scores.cvss3_temporal.calculation }}
{%p elif item.fields.scores.cvss and item.fields.scores.cvss.label and item.fields.scores.cvss.value and item.fields.scores.cvss.calculation %}
{{ item.fields.scores.cvss.label }}: {{ item.fields.scores.cvss.value}}
Calculation: {{ item.fields.scores.cvss.calculation }}
{%p elif item.fields.scores.general and item.fields.scores.general.label and item.fields.scores.general.value and item.fields.scores.general.calculation %}
{{item.fields.scores.general.label }}: {{ item.fields.scores.general.value }}
Calculation: {{ item.fields.scores.general.calculation }}
{%p endif %}
{%p endif %}
{%p endfor %}
{%p endfor %}

Findings Fields: Custom Fields

The reference method presented in this section should be used for the following fields:

  • Any Custom Findings Fields

Custom Fields are stored as arrays, however each element of the array has three attributes that must be referenced separately: the key, label and value. The key must be known when authoring the template, as it is used to call out label and value. Therefore, it is advisable to use a Custom Fields Template to standardize the syntax of custom field keys.

To reference a custom field associated with a finding, you will need to iterate through both the findings and reference the specific key. Before attempting to reference any field, you should use conditional statements to verify the existence of a value for the field; attempting to reference a non-existent field will result in an error.

The basic syntax used to reference the label and value attributes for a custom field, using a key of "scope" as an example, is:

{%p for group in FINDINGS %}
{%p for item in group.FINDINGS %}
{%p if item.fields %}
{%p if item.fields.scope %}
{{ item.fields.scope.label}}: {{item.fields.scope.value}}
{%p endif %}
{%p endif %}
{%p endfor %}
{%p endfor %}

Custom fields are often used to identify where in a report a finding should be displayed. For example, if you only wanted to display information for findings with a "scope" of "webapp_pentest":

{%p for group in FINDINGS %}
{%p for item in group.FINDINGS %}
{%p if item.fields %}
{%p if item.fields.scope %}
{%p if item.fields.scope == "webapp_pentest" %}
{{ item.severity }}: {{ item.title }}
{{ item.description }}
{%p endif %}
{%p endif %}
{%p endif %}
{%p endfor %}
{%p endfor %}

Custom Report Sections

If you are using a Custom Report Template and have added custom fields, you can reference each section through the following conditional statements. This will reference on the free text you enter in the "Section Title" for each Custom Report Section you add. For this example, we will use "Rules of Engagement"

{%p if REPORT_INFO.executive_summary.custom_fields %}
{%p for item in REPORT_INFO.executive_summary.custom_fields %}}
{%p if "Rules of Engagement" in item.label %}
{{ item.label }}
{{ item.text }}
{%p endif %}
{%p endfor %}
{%p endif %}