报告生成器 (Pro)

注意：可复用报告生成器（主题、块、模板以及已保存的生成报告）是 DefectDojo Pro 的功能，目前处于测试阶段。

DefectDojo Pro 报告生成器允许您使用可复用的组件来编写精美的报告，这样您只需构建一次组件即可在任何地方重复使用，而无需每次都从头开始构建报告。您可以通过侧边栏中的**📄 报告**区域访问它。

与开源版的比较#

开源版 DefectDojo 可以构建报告、运行报告并让您获取输出，但它不会保存报告模板，也不会持久化保存您生成的报告。每份报告都是一次性的操作。

DefectDojo Pro 将报告功能转变为可复用的构建模块。您可以保存主题、块和模板，随意混合搭配、重复使用；您运行的每份报告都会作为生成报告持久化保存，供您日后下载或重新运行。Pro 版还通过完整的 REST API 公开整个工作流程，并支持 LLM 辅助创作，因此报告可以通过编程方式构建和运行。

💡 Tip: 如果您使用的是开源版 DefectDojo，请改为参阅开源版报告生成器。

核心概念#

报告生成器由四个部分组成，每个部分都作为 /api/v2/ 下的 REST 资源提供：report_themes、report_blocks、report_templates 和 generated_reports。了解它们之间的关系，是高效构建报告的关键。

主题#

主题用于控制报告的视觉样式和品牌形象：包括颜色、页眉和页脚图片，以及页脚文字。只需定义一次主题，即可为您生成的每份报告应用一致的企业品牌形象。

主题包含以下设置：

💡 Tip: 所有五种颜色均以 7 个字符的十六进制值表示（例如 #1e3a5f），因此您可以精确匹配组织的品牌调色板。

您可以在下方的界面中完成此操作，也可以通过 API 实现自动化。

块#

块是可复用的内容单元。您只需构建一次块，配置好其显示内容，然后就可以将其放入任意数量的模板中。共有四种块类型：

**固定内容（Stock）**块的配置方式是选择五种固定内容类型之一，并根据需要提供标题、副标题、文本内容或图片：

• 封面
• 目录
• 分页符
• 图片
• 文本块

**表格（Tabular）块和详情（Detail）**块都会从单个实体中提取实时记录。您需要通过模型选择来确定实体，然后选择要包含哪些字段，以及记录的排序方式。模型选择必须是以下七种实体之一：

• 组织（Organization）
• 资产（Asset）
• 测试活动（Engagement）
• 测试（Test）
• 发现项（Finding）
• 测试类型（Test type）
• 风险接受（Risk acceptance）

💡 Tip: 在 DefectDojo Pro 中，资产（Assets）以前称为产品（Products），组织（Organizations）以前称为产品类型（Product Types）。您在部分底层字段和筛选器名称中可能仍会遇到这些旧称呼。

两者的区别在于呈现方式：**表格（Tabular）块以列式表格的形式排列记录，适合用于汇总和清单；而详情（Detail）**块则以长文本布局逐条呈现记录，最适合展示描述、影响、缓解措施和参考资料等富含 Markdown 内容的字段。

💡 Tip: 筛选器归属于块，而不是模板。块会自带其筛选器，因此复用某个块时，该块出现的每个地方都会应用完全相同的筛选器。如果您需要相同的内容但使用不同的筛选器，请复制该块并调整副本。

您可以在下方的界面中完成此操作，也可以通过 API 实现自动化。

模板#

模板是绑定到单个主题的一组有序块列表。模板定义了报告中会出现哪些内容及其顺序，而与之绑定的主题则决定报告的外观。

由于模板是通过引用的方式包含块的，同一个块可以在模板中多次出现。例如，一个可复用的分页符块可以插入到同一份报告的多个部分之间。

您可以在下方的界面中完成此操作，也可以通过 API 实现自动化。

生成报告#

运行模板会生成一份生成报告：这是一个持久化保存的 PDF 或 HTML 文件，您可以随时下载或重新运行。每份生成报告都是某一时刻的固定快照——它记录的是生成时 DefectDojo 中的数据，当底层数据后续发生变化时不会自动更新。若要获取最新快照，请重新运行该模板。

生成报告在构建过程中会经历以下状态：

🔑 Important: 报告功能默认处于启用状态。超级用户可以在设置 > 功能开关中开启或关闭该功能（参见功能开关）。查看报告时会遵循 DefectDojo 基于角色的访问控制（RBAC）——即使在报告内部，用户也只能看到其有权查看的数据。

您可以在下方的界面中完成此操作，也可以通过 API 实现自动化。

在界面中构建报告#

以下步骤将引导您完成端到端的报告构建流程：创建主题、创建承载内容的块、将其组装成模板，并生成最终报告。

第 1 步：创建主题#

首先进入主题区域。主题列表会显示您已定义的所有主题，并允许您创建新主题。

打开一个新主题以设置其品牌形象。主题表单提供五种颜色设置、可选的页眉和页脚图片、页脚文字，以及页码显示开关。请选择与您组织品牌相匹配的颜色，让您生成的每份报告风格保持一致。

第 2 步：创建块#

接下来，构建内容块。块列表会显示您所有类型的全部块。

要创建数据驱动的块，请选择其类型并进行配置。下面的示例是一个名为“未关闭发现项”的表格（Tabular）块：块类型设置为“表格”，提供了标题，模型为发现项，所选字段包括严重程度、标题、产品、存续天数和 SLA 剩余天数，记录按数字化严重程度降序排列。由于筛选器归属于块，此处的筛选条目精确规定了该块无论在何处使用都会提取哪些记录。

在将块提交到模板之前，您可以使用预览功能查看应用主题后的渲染效果。下面的预览展示了一个应用了主题颜色和品牌样式的封面（“DefectDojo Security Report”）。

💡 Tip: 当您需要相同的布局但使用不同的筛选器时，可以使用复制功能复制现有块。由于筛选器会随块一起复制，因此若要基于同一列布局生成例如“严重发现项”表格和“高危发现项”表格，复制是正确的做法。

第 3 步：组装模板#

准备好块之后，就可以构建模板了。模板列表会显示您已保存的模板。

在模板编辑器中，您需要选择一个主题，并按照应显示的顺序排列各个块。下面的示例按“封面 → 执行摘要简介 → 未关闭发现项 → KEV → 分页符 → 资产清单”的顺序排列。使用添加现有块可复用已构建的块，使用添加新块可即时创建新块，并可通过拖动手柄调整顺序。请记住，同一个块可以多次出现——一个分页符块就可以插入到多个部分之间。

第 4 步：生成并下载#

模板准备就绪后，即可生成报告。生成对话框会确认所使用的模板，并允许您选择输出格式——HTML 或 PDF。

生成的报告会汇集在生成报告列表中，其中显示每份报告的状态、文件格式、请求和完成时间，以及下载链接。

您可以随时重新运行模板以生成最新报告。请注意，每份生成报告都是某一时刻的固定快照——它反映的是生成时的数据，不会随着 DefectDojo 数据的变化而改变，因此需要最新快照时请重新运行模板。

从经典报告引擎迁移#

经典报告引擎——即侧边栏中经典报告引擎下列出的报告生成器、报告模板和生成报告页面——将在 **3.3.0 版（2026 年 9 月 8 日）**中被移除。在此之前，这些页面会显示提示该日期的横幅，并且它们与本报告生成器都提供一键迁移功能。

迁移已保存的模板#

您可以在任意经典页面上使用迁移到新引擎，也可以在此处的所有报告模板页面上使用从经典引擎导入。两者执行的是相同的转换过程，因此从哪个入口开始都没有区别，并且两者都可以安全地多次运行：如果某个经典模板的名称在此处已经存在，系统会将其报告为已迁移，而不会重复创建。

每个经典小组件都会转换为一个块：

有两项内容无法迁移，迁移工具会针对每个模板明确说明这一点，而不是将其转换为近似的内容：

• 执行摘要（Executive Summary）——经典引擎会根据同一份报告中的发现项小组件推导出执行摘要。目前没有与之等效的汇总块；如果需要，请将其重建为文本块。
• 报告选项（Report Options）——并非一个块。其中的报告名称会成为新模板的名称。发现项备注、发现项图片以及按小组件设置的分页符，在新引擎中属于主题级别的设置。

已运行的报告会怎样#

不会有任何变化。经典引擎生成的生成报告都是已完成的文件，因此无需转换。在该引擎被移除之前，它们会一直保留在列表中并可供下载——如果您希望在 3.3.0 版之后继续保留这些文件，请自行保存。

如果报告生成器被关闭#

即使**报告（Reporting）**功能开关被禁用，迁移功能仍然可以正常使用。转换后的模板只是不会显示，直到该功能开关重新开启为止，因此您可以按照自己的节奏迁移模板。

后续步骤#

• 报告生成器 API——通过脚本实现整个工作流程（主题、块、模板和生成报告），从而实现可重复的自动化报告生成。
• 使用 LLM 的报告生成器——使用 LLM 辅助创作功能，以对话方式设计和构建报告。