🌐 通用解析器 (Pro)

注意：通用解析器仅在 DefectDojo Pro 中提供。

通用解析器在每个 DefectDojo Pro 实例中都已启用；无需进行任何操作即可使用。有关更多信息，请参阅我们的发布演示。

关于通用解析器#

DefectDojo 拥有一个庞大且定期更新的解析器库，用于帮助安全团队摄取数据。但是，有时用户使用的工具并不受这些解析器支持，或者他们可能希望以不同于现有解析器的方式将数据导入 DefectDojo 模型。

DefectDojo 的通用解析器旨在为使用不受支持的报告类型的用户提供一条前进之路，以导入和映射任何 JSON、CSV 或 XML 文件。

通用解析器的定位是：

• 一种快速支持我们尚无社区解析器的文件格式的方式，例如内部工具生成的报告
• 一个帮助您摄取数据的工具，即便某个社区解析器已经过时或未按您期望的方式构建发现项结构
• 一种替代自定义脚本的方案，无需再将工具报告转换为"通用发现项导入"扫描类型所要求的 CSV/JSON 格式
• 设计为任何人都易于使用，无需编写代码，且配置要求极少

通用解析器不是：

• 开源解析器、连接器或经过精心处理的"通用发现项导入"报告的全面替代品
• 无法处理用于构建发现项结构的细致分支逻辑

通用解析器的配置仅在 Pro UI 中可用，不过您仍然可以通过旧版 UI 或 API 使用通用解析器导入扫描。

第 1 步：创建新的通用解析器#

您可以通过点击导航栏"导入"部分下的"新建通用解析器"按钮来创建新的通用解析器，也可以从"添加发现项"页面上的链接创建。

第一个屏幕会要求您提供扫描文件和解析器名称。

该文件应当：

• 具有可识别的扩展名（请参阅下文支持的文件扩展名）
• 包含足够多的类似发现项的对象，以能够代表真实报告——即包含所有可选字段值的对象
• 大小不超过约 1-2MB——超过这个大小通常只会导致解析文件耗时更长，而没有任何好处

解析器名称将在为该新解析器创建 Test_Type 时使用。您可以在"添加发现项"页面的扫描类型下拉列表中找到新创建的通用解析器，名称类似于"Universal Parser - MyCustomParser"。解析器名称必须是唯一的，以避免在为导入选择扫描类型时产生混淆。

第 2 步：映射您的发现项字段#

上传示例扫描文件、选择解析器名称并点击"下一步"后，接下来的页面将允许您配置该通用解析器在使用此配置执行导入时如何填充发现项字段。在右侧，您会看到一系列 DefectDojo 发现项字段（输出字段）。每个输出字段左侧的下拉菜单允许您选择应使用扫描文件结构中的哪个（或哪些）项目（输入字段）来填充它们。

示例：

如果您上传的 JSON 格式扫描文件如下所示：

{
    "findings": [
        {
            "title": "Finding 1 Title",
            "description": "Finding 1 Description",
            "severity": "CRITICAL",
            "CVE": "CVE-2025-12345",
            ...
        },
        {
            "title": "Finding 2 Title",
            "description": "Finding 2 Description",
            "severity": "LOW",
            "CVE": "CVE-2025-54321",
            ...
        },
        ...

    ]
}

您将看到根据输入文件结构检测到的唯一字段的层级表示，并有图标指示每个字段的类型（如果可以确定的话）。然后，您可以在填充"Title"输出字段的下拉菜单中选择"title"输入字段，“description"输入字段可以对应"Description"输出字段，依此类推。

输入字段名称不必与输出字段名称匹配，并且您的扫描文件可能并不具备所有 DefectDojo 输出字段的对应项。

可映射的发现项字段#

下表列出了您可以将输入字段映射到的每一个 DefectDojo 发现项字段（输出字段）。您的扫描文件不一定对所有这些字段都有对应项——只需映射实际存在的字段即可。

• 必需 — 该输出字段必须至少映射一个输入字段，才能保存解析器。
• 接受多个输入 — 该输出字段可以由多个输入字段填充。当您映射多个字段时，每个值会显示在以其输入字段命名的标题下（请参阅多选字段）。

注意： 在上面的示例中，CVE 输入字段会被映射到漏洞 ID输出字段——DefectDojo 并没有一个字面上名为"CVE"的发现项字段。

必需字段#

以下输出字段需要映射输入字段：

• 标题
• 严重程度
• 描述

关于严重程度#

通用解析器会接受 DefectDojo 严重程度的任意大小写变体——“CRITICAL”、“Critical”、“cRiTiCaL” 等——并将其应用于您的发现项。任何与 DefectDojo 严重程度不匹配的值都会被替换为"信息"。这与目前解析器和连接器的工作方式一致：未知值通常会被映射为"信息"。

多选字段#

部分输出字段可以接受多个输入字段。如果您选择了多个输入字段，我们会在以该输入字段名称命名的标题下提供该字段的值。

示例

description

这是从输入文件中一个名为"description"的字段中提取的

detailed_description

这是从输入文件中一个名为"detailed_description"的字段中提取的

第 3 步：预览您的发现项#

选定输入字段到输出字段的映射后，您可以点击"下一步"按钮，查看使用所选配置将输入文件中的发现项导入 DefectDojo 后的效果预览。部分字段旁边会有一个"展开"按钮，供您查看该字段渲染后的完整 MarkDown 效果。我们只会渲染输入文件中前 25 个发现项的预览，但您也可以查看整个扫描文件中检测到的发现项总数。

如果预览效果不符合您的预期，可以点击"返回"按钮调整映射。对配置满意后，点击"提交"按钮创建您的新通用解析器。此操作不会自动执行导入。

创建通用解析器后，您将被重定向到"添加发现项"页面，您可以在该页面上传并导入与第 1 步中提供的示例文件结构相匹配的扫描文件。

关于通用解析器配置的补充说明#

选择合适的输入字段#

不同供应商生成的扫描报告格式可能差异很大，其中一些格式与 DefectDojo 的发现项模型的对应关系比其他格式更紧密。我们在可接受的内容上提供了相当大的灵活性，但仍必须施加一些结构，以确保在从输入到输出的转换过程中发现项不会出错。虽然我们可以容纳可选的输入字段，但我们不接受"全局"字段，或出现次数与发现项对象数量不一致的字段。

示例#

{
    "scan_type": "MyToolScan", // <- There is only one instance of this field, which doesn't match the number of findings
    "findings": [
        {
            "title": "Finding 1 Title",
            "description": "Finding 1 Description",
            "severity": "CRITICAL",
            "CVE": "CVE-2025-12345", // <- This optional field only appears in Finding 1 - that's okay!
            ...
        },
        {
            "title": "Finding 2 Title",
            "description": "Finding 2 Description",
            "severity": "CRITICAL",
            ...  // <- While there is no "CVE" field here, we can still query for it and simply default to a null value
        },
        ... 5 more findings ...
    ],
    "global_details": [
        {
            "nested_detail": "Global detail 1"
        },
        {
            "nested_detail": "Global detail 2" // <- The number of "global_details" objects (2) does not match the number of individual finding objects (7)
        }

    ]
}

保存通用解析器后#

您可以编辑与通用解析器关联的 Test_Type，以更改：

• 是否处于"活动"状态。如果不是，它将不会作为选项出现在"添加发现项"页面的"扫描类型"下拉列表中
• 其发现项应被标记为"静态"还是"动态"
• 您可以在"企业设置"下调整通用解析器的同工具与跨工具去重哈希码，以及重新导入哈希码。默认情况下，只会填充同工具去重和重新导入哈希码，使用必需值标题、严重程度和描述。

生命周期：创建、停用、重新启用#

通用解析器的生命周期是仅可创建的，在 UI 中没有编辑或删除功能。解析器一旦创建，其字段映射配置就无法修改，解析器本身也无法从 UI 中移除——这是有意为之的设计，因为通用解析器配置与 Test_Type 记录相关联，而这些记录可能被现有的发现项、测试和导入历史引用。

您可以在 UI 中执行以下操作：

• 停用某个解析器，使其不再出现在导入时的"扫描类型"下拉列表中。打开侧边栏中的导入 → 通用解析器，可查看您所有的通用解析器，并将"活动"开关关闭。（您也可以编辑底层的 Test_Type 并取消勾选"active"。）已停用的解析器不再作为添加发现项页面上的扫描类型选项出现，但使用该解析器导入的现有测试不受影响，仍可正常使用。
• 在同一屏幕中将"活动"开关重新打开，即可重新启用某个解析器。
• 编辑上一节中描述的 Test_Type 字段（活动/非活动、静态/动态、去重哈希码）。

扫描工具报告格式发生变化时的推荐工作流#

由于解析器一旦创建，其字段映射配置就被锁定，因此处理底层扫描工具格式变化的标准做法是滚动升级到新的解析器，而不是尝试编辑旧的解析器：

1. 使用新报告格式的样本创建一个新的通用解析器（参见第 1 步）。为它起一个不同的名称——例如在原名称后附加 v2 或日期。
2. 在您的 CI/CD 流水线或 UI 工作流中，将新的导入切换为使用新解析器的扫描类型。
3. 在确认新解析器生成的发现项符合预期后，停用旧解析器。使用旧解析器导入的测试仍会保留在 DefectDojo 中，并可继续进行分诊；只有新的导入会路由到新解析器。

如果您需要永久删除某个解析器配置（例如，因为它包含敏感字段名称），请联系 。

关于严重程度映射的说明#

通用解析器没有可配置的严重程度映射字段。严重程度会按以下规则自动映射：

• DefectDojo 严重程度的任意大小写变体都会被接受——CRITICAL、Critical、cRiTiCaL、critical 都会映射为严重。High、Medium、Low 和 Info 同理。
• 任何不匹配 DefectDojo 五个严重程度之一的值都会被映射为信息。

此行为对 DefectDojo 中的所有解析器（内置解析器、连接器和通用解析器）都是一致的。

如果您要摄取的扫描工具使用的严重程度标签与 DefectDojo 的不一致（例如"warning"、“note"或数字 CVSS 分数），通用解析器会将所有这些不匹配的值映射为"信息”。如果您需要不同的映射方式，目前最好的变通方法是在上游转换严重程度值——例如，在上传之前于您的 CI 流水线中进行转换——以便 DefectDojo 收到的值已经是 DefectDojo 五个严重程度名称之一。