Reports & Scheduling

Automated SOC Report Generation, PDF Export, Scheduling, Tenant-Scoped Access, and Report Sharing

Complete

Auto-Generation

Monthly, quarterly, yearly reports generated on schedule

Complete

PDF / HTML Export

WeasyPrint PDF with HTML fallback for browser printing

Complete

Report Sharing

Share reports with external users via time-limited tokens

Complete

SSO + Tenant Scoping

Multi-tenant isolation with SSO and JWT auth support

Overview

The Reports module is the executive-facing output layer of the ThreatOps SOCaaS platform. It automatically produces monthly, quarterly, and yearly SOC performance reports, provides on-demand report generation, supports PDF downloads, and enables controlled report sharing with external stakeholders. Every report is tenant-scoped and accessible through both SSO and local JWT authentication.

Enterprise and government customers expect regular, professional-quality reports showing SOC performance KPIs, incident summaries, compliance posture, and operational metrics. Manual report creation does not scale across a multi-tenant SOCaaS platform. This module fully automates the report lifecycle from generation through distribution.

What Was Proposed

Automated report generation on configurable schedules (daily, weekly, monthly)
Multiple report types: executive monthly, SLA performance, detection coverage
PDF and HTML export capabilities
Tenant-scoped report access with SSO support
Report sharing with external users
Customer-facing dashboard with KPIs
Report lifecycle management (generated reports browsing, viewing, downloading)

What's Built Complete

Report Generator Engine

File: platform/api/app/services/report_generator.py (~2000+ lines)

4 Report Period Types: monthly, quarterly, yearly, on_demand
Automated Scheduling: Daily check at 2 AM UTC for pending reports. Monthly on 1st, quarterly on Jan/Apr/Jul/Oct 1st, yearly on Jan 1st
Styled HTML Output: Self-contained HTML reports with embedded CSS, executive summaries, KPI tables, incident highlights, and compliance sections
JSON Data Export: Structured JSON alongside HTML for programmatic consumption
File Storage: Reports stored in platform/api/reports/{tenant_id}/{year}/{month}/
Report Registry: In-memory registry with metadata (ID, type, tenant, period, generation timestamp, file size, sections)

Report Sharing Service

File: platform/api/app/services/report_sharing.py

Share reports with specific email addresses using time-limited tokens
Track access counts, download counts, and last access timestamps
Revoke shares and query sharing statistics
Configurable expiration (default 30 days)

Reporting Service (Legacy + SSO)

File: platform/api/app/services/reporting_service.py

Executive report generation with KPI calculation
SLA performance reports
Detection coverage reports

PDF Generator

File: platform/api/app/services/pdf_generator.py

WeasyPrint integration for true PDF output
Automatic HTML fallback when WeasyPrint is not installed
Styled executive-quality PDF with ThreatOps branding

API Router: 20+ Endpoints

File: platform/api/app/routers/reports.py (~820 lines)

The reports router is the largest single router in the platform, covering generated reports, tenant-scoped access, sharing, scheduling, KPIs, and legacy compatibility.

Frontend Pages

/reports -- Executive report overview with KPI table, incident highlights, and links to generated reports
/reports/generated -- Browsable list of generated reports with type filters, schedule viewer, and on-demand generation trigger
/reports/generated/[id] -- Individual report viewer with HTML rendering and download options
/reports/lifecycle -- Report lifecycle management

Architecture

Frontend (Next.js)                           API (FastAPI)
+--------------------------------+     +-------------------------------------+
| /reports                       |     | /api/v1/reports/*                   |
|   KPI Table, Incident Summary  | --> |                                     |
| /reports/generated             |     | ReportGenerator (auto-scheduling)   |
|   Report List, On-Demand Gen   |     |   monthly/quarterly/yearly/on_demand|
| /reports/generated/[id]        |     |   HTML + JSON output                |
|   Report Viewer, Download      |     |                                     |
| /reports/lifecycle             |     | ReportingService (legacy)           |
|   Lifecycle Management         |     |   executive, SLA, detection reports |
+--------------------------------+     |                                     |
                                       | ReportSharingService                |
                                       |   share tokens, access tracking     |
                                       |                                     |
                                       | PDFGenerator                        |
                                       |   WeasyPrint / HTML fallback        |
                                       |                                     |
                                       | ReportScheduler                     |
                                       |   daily/weekly/monthly schedules    |
                                       |                                     |
                                       | ReportAccessMiddleware              |
                                       |   SSO + JWT tenant isolation        |
                                       +-------------------------------------+
                                                     |
                                               PostgreSQL (Report model)

Routing

Type	Path	Description
Frontend	`/reports`	Executive report overview with KPIs
Frontend	`/reports/generated`	Generated reports list and on-demand generation
Frontend	`/reports/generated/[id]`	Individual report viewer
Frontend	`/reports/lifecycle`	Report lifecycle management
API Prefix	`/api/v1/reports`	All report endpoints

API Endpoints

Method	Endpoint	Description
Generated Reports (File-Based SOC Reports)
`GET`	`/generated`	List all generated SOC reports with metadata
`GET`	`/generated/{report_id}`	Get report content (HTML or JSON via format param)
`GET`	`/generated/{report_id}/download`	Download report as HTML or JSON file
`POST`	`/generated/generate`	Trigger on-demand SOC report generation
`GET`	`/schedule/upcoming`	View generation schedule and next upcoming reports
`GET`	`/templates/list`	List available report templates/types
SSO-Compatible Tenant-Scoped
`GET`	`/my-reports`	List reports for authenticated user's tenant
`GET`	`/dashboard`	Customer-facing dashboard with KPIs and compliance summary
`GET`	`/shared`	List reports shared with authenticated user
`GET`	`/{report_id}/view`	View specific report (tenant-scoped)
`GET`	`/{report_id}/download`	Download report as PDF (tenant-scoped)
Sharing & Administration
`POST`	`/{report_id}/share`	Share report with specific users (admin only)
`DELETE`	`/shares/{share_id}`	Revoke a report share (admin only)
`GET`	`/{report_id}/share-stats`	Get sharing statistics (admin only)
Legacy Endpoints
`POST`	`/generate`	Generate report on demand (analyst/admin)
`GET`	`/`	List reports for current tenant
`GET`	`/kpis`	Get KPI metrics for tenant
`GET`	`/schedules`	List report schedules
`POST`	`/schedule`	Create recurring report schedule
`DELETE`	`/schedules/{schedule_id}`	Remove a report schedule
`GET`	`/{report_id}`	Get full report data by ID
`GET`	`/{report_id}/pdf`	Download report as PDF document

Prerequisites

PostgreSQL database with the Report model migrated
SQLAlchemy async session (get_db dependency)
Report access middleware configured (report_access.py -- supports SSO tokens and local JWT)
Optional: WeasyPrint for true PDF generation (falls back to HTML)
File system write access for platform/api/reports/ directory

Data Model

Report Model (PostgreSQL)

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	string	Tenant isolation key
`report_type`	ReportType enum	executive_monthly, sla_performance, detection_coverage, etc.
`period_start`	datetime	Report period start
`period_end`	datetime	Report period end
`generated_at`	datetime	Generation timestamp
`status`	ReportStatus	pending, generating, completed, failed
`data`	JSON	Full report data payload
`created_at`	datetime	Record creation timestamp

Enums

Enum	Values
`ReportPeriodType`	`monthly`, `quarterly`, `yearly`, `on_demand`
`ReportGenerationStatus`	`pending`, `generating`, `completed`, `failed`
`ReportType`	`executive_monthly`, `sla_performance`, `detection_coverage`

UI Description

The Reports module spans four frontend pages:

/reports: Executive overview page with an "Operational" status banner, three generated report cards (Monthly, Quarterly, Annual) with quick-generate buttons, a KPI metrics table (MTTA, MTTR, Auto-Resolution Rate, etc.) with green/amber/red status icons, and an incident highlights section with severity badges and resolution descriptions
/reports/generated: Browsable report catalog with type filter tabs (monthly/quarterly/yearly/on_demand), type-colored badges, file size display, report schedule viewer with countdown timers, and an on-demand generation dialog for custom date ranges
/reports/generated/[id]: Individual report viewer that renders the report's HTML content inline, with download buttons for HTML and JSON formats and sharing controls
/reports/lifecycle: Report lifecycle management for scheduling and distribution workflows