Skip to main content

​
Overview

Faction allows you to create fully customized Microsoft Word (DOCX) report templates for different assessment types and retests. This guide covers template creation, variable usage, section organization, and custom graphics integration.

​
Template System Architecture

Faction uses a variable-replacement template engine:
  1. Create a DOCX template with placeholder variables
  2. Assign template to assessment types
  3. During report generation, Faction replaces variables with assessment data
  4. Final report maintains your formatting, branding, and structure
Multiple templates can exist for different assessment types (Web App, API, Mobile) or purposes (initial assessment vs. retest).

​
Creating a Custom Template

1

Start with a Word Document

Create a new Microsoft Word (DOCX) document with your desired:
  • Company branding and logo
  • Header and footer formatting
  • Font styles and sizes
  • Color scheme
  • Page layout and margins
  • Section organization
2

Add Template Variables

Insert placeholder variables where dynamic content should appear. Variables use the format:
{{variable_name}}

​
Standard Assessment Variables

  • {{assessment_name}} - Assessment name
  • {{app_id}} - Application identifier
  • {{start_date}} - Assessment start date
  • {{end_date}} - Assessment end date
  • {{assessor_name}} - Lead assessor name
  • {{assessor_team}} - Assessor team name
  • {{engagement_contact}} - Engagement contact name
  • {{summary}} - Executive summary content
  • {{risk_analysis}} - Risk analysis section

​
Vulnerability Variables

  • {{vulnerabilities}} - Full vulnerability table/list
  • {{vulnerability_count}} - Total number of findings
  • {{critical_count}} - Count by severity
  • {{high_count}} - High severity count
  • {{medium_count}} - Medium severity count
  • {{low_count}} - Low severity count
Contact Faction support or check the documentation at /guides/custom-templates for a complete variable reference.
3

Structure Vulnerability Sections

Create repeating sections for vulnerability details:
Vulnerability: {{vuln_name}}

Description:
{{vuln_description}}

Recommendation:
{{vuln_recommendation}}

Details:
{{vuln_details}}

Risk Rating: {{vuln_overall}}
Category: {{vuln_category}}
Tracking ID: {{vuln_tracking_id}}
Faction will repeat this section for each vulnerability found during the assessment.
4

Add Custom Field Variables

If you’ve configured custom fields at the assessment or organization level, reference them:
{{custom_field_name}}
Common custom field uses:
  • Compliance framework identification
  • Business unit or department
  • Vendor or client name
  • Contract or project numbers
  • Custom report metadata
Create custom field variables for frequently reused text blocks like legal disclaimers or testing methodology descriptions.
5

Configure Section Organization

Organize vulnerabilities by:

​
By Risk Level

Group all critical findings, then high, medium, and low. This is the default sorting.

​
By Category

Group by OWASP Top 10, CWE category, or custom categorization:
{{vulnerabilities_by_category}}

​
By Custom Section

If your assessment uses custom sections (Web, API, Mobile), organize accordingly:
{{section_web_vulnerabilities}}
{{section_api_vulnerabilities}}
{{section_mobile_vulnerabilities}}
Section organization must be enabled in assessment type settings and supported by your Faction version.
6

Insert Charts and Graphics

​
Using Extensions for Custom Graphics

Faction’s Extension system (App Store) allows custom bar charts and graphics in reports:
  1. Install chart extensions from the Faction App Store
  2. Reference chart placeholders in your template:
{{risk_distribution_chart}}
{{category_breakdown_chart}}
{{timeline_chart}}
  1. Extensions generate charts during report creation
  2. Charts are embedded as images in the final DOCX
Custom graphics require the Faction Extension system introduced in version 1.2+. See the README for extension documentation.

​
Static Images

Embed static images (logos, diagrams) directly in the template - they’ll be preserved in generated reports.
7

Add Table of Contents

Insert a Word table of contents:
  1. In Word, go to References > Table of Contents
  2. Choose a style
  3. The TOC will update based on your heading styles
Recipients may need to right-click the TOC and select “Update Field” to refresh page numbers in the generated report.
8

Style Vulnerability Tables

Format vulnerability tables with:
  • Consistent column widths
  • Header row styling
  • Alternating row colors
  • Border styles
  • Cell padding
Faction preserves table formatting when inserting vulnerability data.
9

Save Template

Save as a DOCX file with a descriptive name:
  • web-app-assessment-template.docx
  • api-pentest-template.docx
  • retest-report-template.docx
10

Upload to Faction

  1. Navigate to Templates > Report Templates in Faction
  2. Click Upload Template
  3. Select your DOCX file
  4. Assign to one or more assessment types
  5. Set as default for that type (optional)
11

Test Template

Generate a test report:
  1. Create or select an assessment with sample data
  2. Choose your new template
  3. Generate report
  4. Review formatting, variable replacement, and layout
  5. Iterate as needed

​
Template Variables Reference

​
Assessment-Level Variables

VariableDescription
{{assessment_name}}Name of the assessment
{{app_id}}Application/project identifier
{{start_date}}Assessment start date
{{end_date}}Assessment end date
{{completed_date}}When assessment was finalized
{{summary}}Executive summary content
{{risk_analysis}}Risk analysis section
{{assessor_name}}Primary assessor full name
{{assessor_email}}Assessor email address
{{assessor_team}}Team name
{{engagement_name}}Engagement contact
{{remediation_name}}Remediation contact
{{distribution_list}}Email distribution list

​
Vulnerability-Level Variables

VariableDescription
{{vuln_name}}Vulnerability title
{{vuln_description}}Full description
{{vuln_recommendation}}Remediation guidance
{{vuln_details}}Exploit details and POC
{{vuln_category}}OWASP/CWE category
{{vuln_likelihood}}Likelihood rating
{{vuln_impact}}Impact rating
{{vuln_overall}}Overall risk severity
{{vuln_cvss_score}}CVSS numeric score
{{vuln_cvss_vector}}CVSS vector string
{{vuln_tracking_id}}Unique tracking ID
{{vuln_opened}}Discovery date
{{vuln_closed}}Production closure date

​
Count and Statistics Variables

VariableDescription
{{total_vulnerabilities}}Total finding count
{{critical_count}}Critical severity count
{{high_count}}High severity count
{{medium_count}}Medium severity count
{{low_count}}Low severity count
{{info_count}}Informational count

​
Retest Report Templates

Create specialized templates for verification/retest reports:
  • Include original vulnerability status
  • Show before/after risk levels
  • Highlight which issues were fixed vs. remain open
  • Reference original assessment and tracking IDs
Assign retest templates separately from initial assessment templates in the template configuration.

​
Best Practices

Test with Real Data

Use an actual assessment with representative findings to test template formatting.

Keep Formatting Simple

Avoid complex Word features that may not translate well during generation.

Use Heading Styles

Apply Word heading styles (Heading 1, 2, 3) for proper TOC generation.

Version Control Templates

Maintain template versions and document changes for audit purposes.

Include Legal Disclaimers

Add scope limitations, disclaimers, and confidentiality statements to templates.

Brand Consistently

Use organization colors, fonts, and logos for professional appearance.

​
Extension-Based Custom Graphics

Faction 1.2+ includes an App Store for extensions that can:
  • Generate custom bar charts
  • Create vulnerability distribution graphs
  • Add timeline visualizations
  • Produce custom metrics dashboards
Extensions run during report generation and insert graphics into template placeholders.
See the Faction App Store documentation and README for available extensions and development guides.

​
Troubleshooting Templates

  • Check variable spelling and case sensitivity
  • Ensure variables use correct {{variable}} format
  • Verify the variable exists in Faction’s variable list
  • Simplify Word formatting (avoid complex styles)
  • Use tables for structured layout
  • Test with minimal formatting first, then add complexity
  • Verify image files are uploaded to assessment
  • Check image references use correct format
  • Ensure images are in supported formats (PNG, JPG)
  • Remind report recipients to right-click TOC and select “Update Field”
  • Use Word’s built-in TOC feature, not manual tables

Creating Assessments

Configure assessment types and templates

Vulnerability Tracking

Manage findings that appear in reports

Official Template Guide

Comprehensive template documentation

Extensions & App Store

Add custom graphics and integrations

Build docs developers (and LLMs) love

Get started for freeTalk to us