Report Templates

Report templates define the output format and structure for generated reports. RAPTR supports two formats: DOCX (Microsoft Word) and HTML. Both use Jinja2 templating syntax with access to the full assessment data.

Report templates are managed via custom data seeding.

Template Context

When a report is generated, RAPTR builds a ReportContext and passes all its fields as top-level Jinja2 variables to the template. The following sections document every available variable.

Top-Level Variables

Data Reference

AssessmentInfo

ActivityGroupReport

ActivityReport

This is the most detailed data object — it contains everything about a single activity.

Identity & Metadata

MITRE ATT&CK

Timing

Detail Fields (Markdown)

Expected Results (Red Team)

Actual Results (Blue Team)

Detection Notes (Markdown)

Related Entities

Static Evaluation

Time-Based Evaluation

Severity-Based Evaluation

Dynamic Evaluation Questions

Files / Attachments

DynamicQuestionReport

FileReport

AssessmentStatistics

The statistics variable contains the same data that powers the Statistics page in the RAPTR frontend. All metrics are computed over visible, non-deleted activities in visible, non-deleted groups.

StateDistributionItem

PriorityBreakdownItem

PriorityAverageScoreItem

MitreOverallTacticScoreItem

Aggregated detection scores for a single MITRE tactic across all its techniques. Scores are percentages (0-100).

MitreTacticScoreItem

Groups techniques under a single tactic.

MitreTechniqueScoreItem

Same fields as MitreOverallTacticScoreItem but for a single technique.

MeanTimeMetricsItem

Mean time metrics grouped by priority. Times are in seconds.

SeverityAccuracyItem

Confusion matrix row showing how actual alert severities compare to the expected severity.

DOCX Templates

DOCX templates use docxtpl (Jinja2 for Word documents). You create a .docx file in Microsoft Word or LibreOffice and insert Jinja2 tags directly into the document text.

Basic Syntax

Use standard Jinja2 syntax inside the document:

• Variables: {{ assessment.name }}
• Loops: {%tr for activity in activities_flat %} ... {%tr endfor %}
• Conditionals: {% if activity.logged %}Yes{% else %}No{% endif %}

Markdown Fields

Markdown fields (rationale, actions, requirements, notes, detection notes) are automatically converted to styled Word content if the required styles are present in the template.

Required Styles

Your DOCX template must define these named styles for markdown rendering to work correctly. If a style is missing, the content falls back to the "Normal" style.

Paragraph styles (applied to entire paragraphs via w:pStyle):

Character styles (applied to inline text runs via w:rStyle):

Table Rows

To loop over activities in a table, use the {%tr %} tag (table row):

| # | Activity Name | Tactic | Result |
|---|---|---|---|
{%tr for a in activities_flat %}
| {{ a.position }} | {{ a.name }} | {{ a.mitre_tactic_name }} | {{ a.coverage_score }}% |
{%tr endfor %}

Images & Attachments

Images from markdown fields (pasted screenshots) are automatically embedded as inline images in the DOCX output, scaled to a maximum width of 5.5 inches. If an image cannot be loaded, a fallback italic text with the alt text is inserted.

HTML Templates

HTML templates use standard Jinja2 syntax with autoscaping enabled.

The tojson Filter

The | tojson filter is the only custom Jinja2 filter available. It serializes a Python object to a JSON string for embedding in <script> tags:

<script>
    const activities = {{ raw_activities | tojson }};
    const stats = {{ statistics | tojson }};
</script>

This custom filter is required instead of Jinja2's built-in because:

1. Datetime handling — the report context contains datetime objects (e.g. generated_at, activity timestamps) that Python's json.dumps() cannot serialize by default. The filter converts them to ISO 8601 strings.
2. Autoescaping safety — the rendering engine runs with autoescape=True, which would HTML-entity-encode raw JSON output (e.g. turning " into "). The filter wraps the output in Markup() to prevent this, keeping the JSON valid inside <script> blocks.

All other formatting (dates, percentages, colors, etc.) should be handled client-side in JavaScript.

Images in HTML

File attachments include base64-encoded content. To embed images:

{% for file in activity.files %}
  {% if file.content_type.startswith('image/') %}
    <img src="data:{{ file.content_type }};base64,{{ file.data_base64 }}"
         alt="{{ file.filename }}" />
  {% endif %}
{% endfor %}

Markdown in HTML

Unlike DOCX templates, markdown fields in HTML are not automatically converted. The raw markdown string is provided. To render markdown in HTML, either:

• Use a JavaScript markdown library (e.g., marked.js) in the rendered HTML
• Pre-process the markdown fields in the template with a custom filter

Example HTML Structure

<!DOCTYPE html>
<html>
<head>
    <title>{{ assessment.name }} - Report</title>
    <style>
        /* Your styles here */
    </style>
</head>
<body>
    <h1>{{ assessment.name }}</h1>
    <p>{{ assessment.description }}</p>
    <p>Generated: {{ generated_at | format_datetime }} by {{ generated_by }}</p>

    <h2>Summary</h2>
    <p>Coverage: {{ statistics.average_coverage_score | round(1) }}%</p>
    <p>Completed by Priority:</p>
    <ul>
    {% for item in statistics.priority_breakdown %}
        <li>{{ item.priority }}: {{ item.count }}</li>
    {% endfor %}
    </ul>

    <h2>Activities</h2>
    {% for group in activities_grouped %}
    <h3>{{ group.name }}</h3>
    <table>
        <tr><th>Activity</th><th>Tactic</th><th>Coverage</th></tr>
        {% for a in group.activities %}
        <tr>
            <td>{{ a.name }}</td>
            <td>{{ a.mitre_tactic_name }}</td>
            <td>{{ a.coverage_score or 'N/A' }}%</td>
        </tr>
        {% endfor %}
    </table>
    {% endfor %}
</body>
</html>

Common Patterns

Iterating Grouped vs Flat

Grouped — preserves group structure:

{% for group in activities_grouped %}
  Group: {{ group.name }} ({{ group.stats.total_activities }} activities)
  {% for activity in group.activities %}
    {{ activity.name }}
  {% endfor %}
{% endfor %}

Flat — single sorted list (sort order selected by user during export):

{% for activity in activities_flat %}
  {{ activity.name }} — {{ activity.group_name }}
{% endfor %}

Conditional Detection Results

{% if activity.logged %}
  Logged: Yes ({{ activity.log_time | format_datetime }})
{% else %}
  Logged: No
{% endif %}

Pass/Fail Styling

{% if activity.logged_evaluation == "pass" %}
  PASS
{% elif activity.logged_evaluation == "fail" %}
  FAIL
{% else %}
  N/A
{% endif %}

Dynamic Evaluation Questions

{% for dq in activity.dynamic_questions %}
  Q: {{ dq.question }}
  A: {{ dq.data or "Not answered" }}
  Result: {{ dq.result }}
{% endfor %}