Export System

SPEAR provides comprehensive export capabilities for security assessment reports. This guide covers the implemented PDF export system, public portal sharing, and planned DOCX export feature.

Export Formats

Format	Description	Status
PDF	Professional formatted documents	Implemented
Public Portal	Web-based sharing	Implemented
DOCX	Editable Word documents	Planned

PDF Export System

5:30

▶

PDF Export System Overview Understanding the export architecture, configuring options, and generating professional PDFs 💡 Explainer Video

The PDF export system generates professional PDFs from report content using Go Rod (headless Chrome). It integrates report sections, themes, and branding into cohesive PDF documents.

🎨 Export Architecture Diagram Illustration

Architecture

flowchart LR
    A[Export Dialog] --> B[Backend Processing]
    B --> C[Fetch Report Data]
    B --> D[Fetch Theme Settings]
    B --> E[Fetch Branding]

    C --> F[Section Assembler]
    D --> F
    E --> F

    F --> G[Generate HTML]
    G --> H[Apply Theme CSS]
    H --> I[Headless Browser]
    I --> J[PDF File]
    J --> K[Download]
    K --> A

Export Flow

Frontend UI - User configures export options in PDFExportDialog
Backend API - Receives export request with configuration
Data Assembly - Fetches report, sections, findings, and metadata
Theme Application - Applies selected theme styles and branding
HTML Generation - Builds complete HTML document with cover page, TOC, sections
Image Processing - Converts images to base64 for embedding
PDF Rendering - Go Rod (headless Chrome) converts HTML to PDF
File Storage - PDF stored temporarily for download
Download - Returns URL for client download

🖥️ PDFExportDialog with All Options Screenshot

Export Options

4:15

▶

Configuring PDF Export Options Selecting themes, adjusting page settings, configuring headers/footers, and using async mode 🎥 Demo Video

Option	Type	Default	Description
`themeId`	string	-	Theme to apply for styling
`includeCovers`	boolean	`true`	Include cover pages
`includeToc`	boolean	`true`	Generate table of contents
`pageSize`	string	`'A4'`	Page size (A4, Letter, Legal, A3, A5)
`orientation`	string	`'portrait'`	Portrait or landscape
`margins`	object	`{top: 1.0, right: 1.0, bottom: 1.0, left: 1.0}`	Page margins in inches
`includeHeader`	boolean	`true`	Include page headers
`includeFooter`	boolean	`true`	Include page footers
`darkMode`	boolean	`false`	Use dark mode styling
`async`	boolean	`false`	Use async processing for large reports

Page Sizes

Size	Dimensions	Common Use
A4	8.27 x 11.69 in	International standard
Letter	8.5 x 11 in	US standard
Legal	8.5 x 14 in	Legal documents
A3	11.69 x 16.54 in	Large format
A5	5.83 x 8.27 in	Compact documents

Theme Integration

🖥️ Theme Configuration Interface Screenshot

7:00

▶

Creating and Applying Custom Themes Configuring colors, fonts, table styles, and custom CSS for branded PDF exports 📚 Video Tutorial

Themes control the visual appearance of exported PDFs.

Color Configuration

Property	Description
Background	Page background color
Text	Primary text color
Primary	Accent/highlight color
Heading	Heading text color (H1-H4)
Muted	Secondary text color

Font Configuration

Property	Description
Body Font	Main content font family
Heading Font	Heading font family
Code Font	Monospace font for code
Base Size	Base font size in points

Table Styles

Property	Description
Borders	Border style and color
Header Background	Table header background color
Cell Padding	Internal cell padding
Alternating Rows	Zebra striping for rows

Custom CSS

Themes support custom CSS injection for advanced styling:

/* Custom theme CSS */
.severity-critical {
  background-color: #dc2626;
  color: white;
}

.finding-card {
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

Branding Integration

🖥️ Branding Integration Settings Screenshot

Organization branding is automatically applied to exported documents.

Logo Configuration

Property	Description
Light Mode Logo	Logo for light backgrounds
Dark Mode Logo	Logo for dark backgrounds
Logo Position	Header placement (left, center, right)
Logo Size	Maximum dimensions

Brand Colors

Property	Description
Primary Color	Main brand color
Accent Color	Secondary brand color

Footer Text

Customizable footer text with placeholders:

{{page}} - Current page number
{{pages}} - Total page count
{{date}} - Export date
{{report.title}} - Report title

Logo URLs

Logos are served from PocketBase storage:

/api/files/branding_settings/{recordId}/{filename}

Section Assembly

Loading Process

Fetch section definitions from report template
Build hierarchical section tree
Process each section by type
Generate HTML fragments
Combine with page break rules

Section Types

Type	Processing
`static`	Render fixed template content
`freeform`	Render user-edited rich text
`dynamic`	Generate from data (findings, assets)
`pdf_only`	Include only in PDF exports

Repeating Sections

Sections marked as repeating generate content for each service:

[Service A Section]
  - Service A Content
  - Service A Findings

[Service B Section]
  - Service B Content
  - Service B Findings

Page Breaks

Page breaks inserted based on heading levels:

Heading	Page Break
H1	Always before
H2	Configurable
H3+	Never

Findings HTML

Findings are rendered with severity badges, CVSS scores, and structured content:

<div class="finding">
  <div class="finding-header">
    <span class="severity severity-high">High</span>
    <h3>SQL Injection in Login Form</h3>
    <span class="cvss">CVSS: 8.6</span>
  </div>
  <div class="finding-body">
    <!-- Description, remediation, etc. -->
  </div>
</div>

Async Processing

For large reports (50+ sections), async processing avoids timeouts.

Queue System

Export request creates a queue entry for processing
Background worker processes the export
Progress updates available while processing
Download available when complete

Job States

State	Description
`queued`	Waiting for processing
`processing`	Export in progress
`completed`	Export finished successfully
`failed`	Export failed with error

Progress Tracking

{
  "queueId": "job-xyz789",
  "status": "processing",
  "progress": 65,
  "message": "Processing section 13 of 20"
}

Timeouts

Mode	Timeout
Synchronous	5 minutes
Asynchronous	30 minutes

Export History

🖥️ Export History Interface Screenshot

Track previous exports for auditing and re-download.

Stored Data

Field	Description
Export Date	When export was generated
Format	PDF or Portal
User	Who initiated export
Options	Configuration used
File	Stored export file URL
Status	completed, failed, or expired

Re-download

Previous exports are re-downloadable until cleanup:

Navigate to Export History in the report editor
Select previous export
Click Download

Public Portal Export

🖥️ Public Portal Configuration Screenshot

Web-based report sharing for client review.

Features

Custom branding application
Interactive navigation
Access control with tokens
Expiration settings
View tracking

Configuration

Setting	Description
Token	Secure access token (auto-generated)
Expiry	Access expiration date
Status	Active, expired, or revoked
Access Count	Number of times portal has been viewed

Portal URL Format

Public portals are accessed via a unique token-based URL provided when creating the portal share.

Planned: DOCX Export

Planned Features

Preserves rich text formatting
Tables with styling
Images embedded
Editable in Microsoft Word

Planned Options

Similar to PDF export with format-specific adjustments:

No page break configuration (Word handles pagination)
Font embedding options
Compatibility mode selection

Planned Endpoint

POST /api/reports/{id}/export-docx

Cleanup and Retention

Automatic Cleanup

Daily cleanup job removes old exports:

Default retention: 7 days
Configurable via PDF_RETENTION_DAYS environment variable

Manual Cleanup

Administrators can manually delete exports from the export history interface.

Performance Tips

Optimize Images

Compress images before upload
Use appropriate dimensions (not larger than needed)
Prefer JPEG for photos, PNG for diagrams

Use Async Mode

For reports with:

50+ sections
Many images
Complex findings tables

Theme CSS Caching

Themes are cached per export. Avoid inline styles in content that override theme settings.

Finding Limits

Keep finding descriptions concise
Use summaries for very long technical details
Link to external references when appropriate

Troubleshooting

Blank PDF

Causes:

Empty section content
Theme template errors
CSS rendering issues

Solutions:

Verify section content exists
Check theme template syntax
Test with default theme

Missing Images

Causes:

Invalid image URLs
Images too large
PocketBase file access issues

Solutions:

Verify image URLs are accessible
Check file size limits
Re-upload images

Export Timeout

Causes:

Large report (50+ sections)
Many high-resolution images
Server resource constraints

Solutions:

Use async mode
Optimize images
Split into multiple reports

Missing Headers/Footers

Causes:

Theme template missing header/footer sections
Options disabled in export request

Solutions:

Verify theme includes header/footer templates
Check includeHeader and includeFooter options

Font Issues

Causes:

Custom fonts not available
Font embedding disabled

Solutions:

Use web-safe fonts
Enable font embedding in theme
Test PDF in different viewers