Reporting - Faction

Overview

Faction’s reporting engine transforms assessment data into professional DOCX reports using customizable templates. The system supports multiple report templates per team, assessment-type-specific templates, retest reports, and advanced customization through report variables.

Report Templates

Report templates are managed through the ReportTemplates class (src/com/fuse/dao/ReportTemplates.java) and support extensive customization.

Template Properties

// ReportTemplates.java core fields
private String name;           // Template identifier
private String variable;       // Template variable name for code reference
private String filename;       // Original DOCX filename
private Teams team;            // Team that owns this template
private AssessmentType type;   // Assessment type (e.g., Web App, Network)
private boolean retest;        // Whether this is a retest template
private String fileType;       // Output format (typically "docx")

Template Storage

Templates can be stored in two ways:

Database Storage
File System Storage

Templates stored as base64-encoded data within the database:

private Boolean saveInDB = false;
private String base64EncodedTemplate;  // Encoded DOCX file

Benefits:

No filesystem dependencies
Included in database backups
Easier deployment

Report Types

Assessment Reports

Full reports generated after completing security assessments:

// FinalReport.java stores generated reports (Assessment.java:66)
@OneToOne(fetch = FetchType.LAZY, cascade = CascadeType.ALL, orphanRemoval = true)
private FinalReport finalReport;

Retest Reports

Specialized reports for remediation validation:

// Separate retest report storage (Assessment.java:70)
@OneToOne(fetch = FetchType.LAZY, cascade = CascadeType.ALL, orphanRemoval = true)
private FinalReport retestReport;

Retest templates typically include only re-tested vulnerabilities and remediation status, providing a focused validation document.

Report Generation

The report generation process transforms assessment data into formatted DOCX files:

Generation Flow

Select Template

System identifies appropriate template based on:

Assessment type
Team assignment
Retest flag

Load Template

Template retrieved from database or filesystem:

@Transient
public InputStream getTemplate() {
    String b64Template = this.getBase64EncodedTemplate();
    byte[] docx = Base64.decodeBase64(b64Template);
    return new ByteArrayInputStream(docx);
}

Replace Variables

Assessment data populates template placeholders

Generate Output

Final DOCX created and stored as FinalReport

Report Variables

Templates use variables to dynamically insert assessment data. Common variables include:

Standard Variables

Variable	Description	Source
`{{assessment.name}}`	Assessment name	Assessment.java:41
`{{assessment.summary}}`	Executive summary	Assessment.java:39
`{{assessment.riskAnalysis}}`	Risk analysis section	Assessment.java:40
`{{assessment.start}}`	Start date	Assessment.java:49
`{{assessment.end}}`	End date	Assessment.java:50
`{{assessment.appId}}`	Target application	Assessment.java:48

Vulnerability Variables

Templates can iterate over vulnerabilities:

{{#vulnerabilities}}
  Name: {{name}}
  Severity: {{overall}}
  Description: {{description}}
  Recommendation: {{recommendation}}
  Details: {{details}}
{{/vulnerabilities}}

Custom Field Variables

Custom fields are accessible in templates:

{{#customFields}}
  {{fieldName}}: {{fieldValue}}
{{/customFields}}

Refer to the Custom Report Templates documentation for comprehensive variable reference and advanced templating techniques.

Graphics and Charts

Faction supports embedding charts and graphics in reports through extensions:

Chart Types

Vulnerability Distribution

Pie charts showing findings by severity level

Category Breakdown

Bar charts of vulnerabilities by category (XSS, SQLi, etc.)

Risk Trends

Line charts showing risk over time for campaigns

Extension-Based Graphics

The App Store extension system enables custom chart generation:

// ReportFeatures.java extension points
public static byte[] finalizeReport(byte[] report, String reportType) {
    return report;  // Extensions can modify report before finalization
}

Extensions can:

Generate charts from assessment data
Insert graphics into DOCX templates
Create custom visualizations
Add compliance matrices

The Jira integration and other App Store extensions demonstrate graphics capabilities for vulnerability distribution and status tracking.

Large Report Handling

Faction automatically handles large reports by chunking the data:

// FinalReport.java chunking for reports >15MB (line 67)
private Boolean largeFile = false;
@OneToMany(fetch = FetchType.LAZY, cascade = CascadeType.ALL, orphanRemoval = true)
private List<FinalReportPart> parts = new ArrayList<>();

if(base64EncodedPdf != null && base64EncodedPdf.length() > 15_000_000) {
    this.largeFile = true;
    String[] chunks = this.chunk(base64EncodedPdf);
    // Split into 15MB chunks for database storage
}

Reports with many screenshots or detailed findings may exceed database field limits. Faction automatically splits these into manageable chunks.

Template Management

Default Template Initialization

New teams automatically receive a sample template:

// ReportTemplates.java:117-149 - Downloads default template
public void initDefaultTemplate(Teams team, AssessmentType type) {
    String defaultReportName = "default-report-template.docx";
    URL defaultTemplateURL = new URL(
        "https://github.com/factionsecurity/report_templates/raw/main/" + defaultReportName);
    // Downloads and initializes template
}

Template Customization

Download Template

Export existing template or start with default template

Edit in Word

Modify formatting, add your branding, customize sections

Add Variables

Insert Faction variables where dynamic data should appear

Upload Template

Upload customized DOCX back to Faction

Test Generation

Generate a test report to verify formatting and variables

File Type Support

While DOCX is the primary format, Faction’s architecture supports extensibility:

// ReportFeatures.java defines available formats
public static String[] getReportOptions() {
    return new String[] {"docx"};
}

Future versions may support additional formats like PDF, HTML, or Markdown through the extension system.

Report Storage

Generated reports are stored in the FinalReport entity:

// FinalReport.java key fields
private String filename;           // Report filename
private String base64EncodedPdf;   // Base64-encoded report content
private Date gentime;              // Generation timestamp
private Boolean retest;            // Retest report flag
private String fileType;           // File format ("docx")

Reports include metadata:

Generation time: When report was created
Report type: Assessment or retest
File format: Output format used
File size: Whether chunking was required

Multi-Template Strategy

Organizations can maintain multiple templates:

By Assessment Type

Web Application: Focused on OWASP findings
Network Penetration Test: Infrastructure-focused layout
Cloud Security Review: Cloud-specific sections and compliance
Mobile Application: Mobile platform considerations

By Client or Compliance

PCI DSS: Include PCI-specific language and requirements
SOC 2: Align with trust service criteria
Custom Client Templates: Match client’s preferred format

By Report Scope

Executive Summary: High-level overview for leadership
Technical Details: In-depth findings for security teams
Retest Validation: Remediation-focused reporting

Best Practices

Version Control Templates

Maintain template versions to track changes over time. Download templates before making significant changes.

Test Variable Substitution

Always generate test reports after template changes to ensure variables populate correctly.

Standardize Formatting

Use consistent styles in Word templates (Heading 1, Heading 2, etc.) for professional appearance.

Include Branding

Add company logos, color schemes, and footer information to templates for branded reports.

Plan for Graphics

Reserve space in templates for charts and graphics that extensions will generate.

Next Steps

Custom Templates Guide

Comprehensive guide to creating custom report templates

Assessments

Learn about assessment data included in reports

Vulnerabilities

Understand vulnerability data for reporting

App Store Extensions

Extend reporting with custom graphics and features

Getting Started

Core Features

User Guides

Integrations

Extensions

​Overview

​Report Templates

​Template Properties

​Template Storage

​Report Types

​Assessment Reports

​Retest Reports

​Report Generation

​Generation Flow

​Report Variables

​Standard Variables

​Vulnerability Variables

​Custom Field Variables

​Graphics and Charts

​Chart Types

Vulnerability Distribution

Category Breakdown

Risk Trends

​Extension-Based Graphics

​Large Report Handling

​Template Management

​Default Template Initialization

​Template Customization

​File Type Support

​Report Storage

​Multi-Template Strategy

​By Assessment Type

​By Client or Compliance

​By Report Scope

​Best Practices

​Next Steps

Custom Templates Guide

Assessments

Vulnerabilities

App Store Extensions

Build docs developers (and LLMs) love

Overview

Report Templates

Template Properties

Template Storage

Report Types

Assessment Reports

Retest Reports

Report Generation

Generation Flow

Report Variables

Standard Variables

Vulnerability Variables

Custom Field Variables

Graphics and Charts

Chart Types

Extension-Based Graphics

Large Report Handling

Template Management

Default Template Initialization

Template Customization

File Type Support

Report Storage

Multi-Template Strategy

By Assessment Type

By Client or Compliance

By Report Scope

Best Practices

Next Steps