CVE二进制工具快速入门 / README

CVE二进制工具是一个免费的、开源的工具，可以帮助您使用来自国家漏洞数据库（NVD）的通用漏洞和暴露（CVE）列表以及来自Redhat、开源漏洞数据库（OSV）、Gitlab安全数据库（GAD）和Curl的已知漏洞数据，来查找软件中的已知漏洞。

CVE二进制工具使用NVD API，但未经NVD推荐或认证。

该工具有两个主要操作模式

1. 一种二进制扫描器，帮助您确定哪些软件包可能已包含在软件组件中。共有365个检查器。我们的初始重点是常见的、易受攻击的开源组件，如openssl、libpng、libxml2和expat。

2. 用于扫描各种格式的已知组件列表的工具，包括.csv文件、多个Linux发行版包列表、特定语言的包扫描器和多种软件物料清单（SBOM）格式。

旨在作为您持续集成系统的一部分使用，以实现定期漏洞扫描，并在供应链中的已知问题早期发出警告。它还可以用于自动检测组件并创建SBOM。

当CVE二进制工具运行时

1. 下载CVE数据（来自NVD、Redhat、OSV、Gitlab和Curl）。
   • 默认情况下，每天运行一次，而不是每次扫描时都运行。
   • 首次运行时，下载所有数据可能需要一些时间。
2. 创建/读取组件列表。有两种操作模式
   1. 通过结合二进制检查器和语言组件列表（如Python的requirements.txt）创建组件列表（包括版本）。
   2. 读取SBOM（使用标准化的软件物料清单格式中的现有组件列表。）
3. 创建CVE列表
   • 查找从现有物料清单中找到或读取的所有组件，并报告与它们相关的任何已知问题
4. 包含分类/附加数据
   • 有几种方法可以添加分类/注释，跟踪漏洞随时间变化的信息或已知修复数据
5. 以一个或多个格式（控制台、json、csv、html、pdf）生成报告

有关更多详细信息，请参阅我们的文档或此快速入门指南

• CVE二进制工具快速入门 / README
  • 安装CVE二进制工具
  • 最受欢迎的使用选项
    • 使用二进制扫描器查找已知漏洞
    • 扫描SBOM文件中的已知漏洞
    • 生成SBOM
    • 生成VEX
    • 分类漏洞
    • 离线使用工具
    • 在GitHub Actions中使用CVE二进制工具
  • 输出选项
  • 配置
  • 组件自动检测
    • 二进制检查器列表
    • 特定语言检查器
    • 支持的存档格式
  • 附加要求
  • 限制
  • 反馈 & 贡献
  • 安全问题
  • 完整选项列表

安装CVE二进制工具

CVE二进制工具可以使用pip安装

pip install cve-bin-tool

如果您想尝试来自cve-bin-tool github的最新代码或进行开发，您还可以使用pip install --user -e .从目录安装本地副本。有关如何在本地进行更详细的设置，请参阅贡献者文档。

pip会为您安装Python要求，但对于某些类型的提取，我们使用系统库。如果您在提取文件时遇到困难，您可能需要查看我们的附加要求列表（针对Linux和Windows）。

首次使用（默认情况下，每天一次）该工具将从一组已知漏洞数据源下载漏洞数据。由于NVD的可靠性问题，自版本3.3起，我们将默认使用我们的NVD镜像https://cveb.in/，而不是直接联系NVD。如果您希望从NVD服务器直接获取数据，您必须提供自己的NVD_API_KEY以使用他们的API。

如果您正在使用版本低于3.3的发布版，该发布版不使用我们的镜像，请使用如上所述的NVD_API_KEY。

最受欢迎的使用选项

使用二进制扫描器查找已知漏洞

在目录或文件上运行二进制扫描器

cve-bin-tool <directory/file>

注意：此选项还将使用任何特定语言检查器来查找组件中的已知漏洞。

默认情况下，该工具假定您正在尝试扫描整个目录，但如果您提供单个 .csv 或 .json 文件，其中列出依赖项，它将将其视为物料清单。您还可以直接使用 以下 --input-file 选项 指定物料清单文件，或按照以下说明扫描 SBOM。

扫描SBOM文件中的已知漏洞

扫描软件物料清单文件 (SBOM)

cve-bin-tool --sbom <sbom_filetype> --sbom-file <sbom_filename>

有效的 SBOM 类型是 SPDX、CycloneDX 和 SWID。SBOM 文件中产品名称的扫描不区分大小写。

SBOM 扫描指南提供了额外的 SBOM 扫描示例。

生成SBOM

除了扫描 SBOM，CVE 二进制工具还可以根据以下说明从扫描中生成 SBOM

cve-bin-tool  --sbom-type <sbom_type> --sbom-format <sbom-format> --sbom-output <sbom_filename> <other scan options as required>

有效的 SBOM 类型是 SPDX 和 CycloneDX。

生成的 SBOM 将包括产品名称、版本和供应商（如有）。不提供许可证信息。

SBOM 生成指南提供了额外的 SBOM 生成示例。

生成VEX

除了扫描 VEX，CVE 二进制工具还可以根据以下说明从扫描中生成 VEX

cve-bin-tool  --vex-type <vex_type> --vex-output <vex_filename> <other scan options as required>

有效的 VEX 类型是 CSAF、CycloneDX 和 OpenVEX。

VEX 生成指南提供了额外的 VEX 生成示例。

分类漏洞

使用 --vex-file 选项可以在扫描目录时添加额外的分类数据，如备注、评论等，以便输出将反映这些分类数据，您可以节省重新分类的时间（用法：cve-bin-tool --vex-file test.json /path/to/scan）。支持的格式是 CycloneDX、CSAF 和 OpenVEX VEX 格式，该格式可以使用 --vex-output 选项生成。

典型用法

1. 使用 cve-bin-tool /path/to/scan --vex-output triage.json 生成分类文件
2. 使用您喜欢的文本编辑器编辑 triage.json，提供有关列出的漏洞的分类信息。
3. 将此分类文件用于未来的扫描： cve-bin-tool /path/to/scan --vex-file triage.json

有关更好的使用指南，请参阅此 链接。

应能够在不同运行 cve-bin-tool 或与其他支持 CycloneDX VEX、OpenVEX 和 CSAF 格式的工具之间共享分类数据。这对于扫描相关产品或容器的团队、需要使用多个工具进行合规性检查的团队、拥有中央安全政策小组的公司（该小组提供有关漏洞分类的指导）等尤其有用。

离线使用工具

在运行扫描时指定 --offline 选项可确保 cve-bin-tool 不尝试下载最新的数据库文件或检查工具的新版本。

请注意，在工具以离线模式运行之前，您需要获取漏洞数据的副本。有关如何设置数据库的更多信息，请参阅 离线指南。

在GitHub Actions中使用CVE二进制工具

如果您想将 cve-bin-tool 作为 GitHub Action 流程的一部分进行集成，可以使用 cve-bin-tool 的官方 GitHub Action。更多详细信息请参阅 此处。GitHub Action 提供安全选项卡上的报告，该选项卡对开源项目以及付费获取访问权限的 GitHub 用户均可用。

如果您希望直接使用此工具，我们还提供了一个示例 GitHub Action。这对于希望将报告存储在证据库中的团队或没有访问 GitHub 安全选项卡的团队来说可能是一个不错的选择。

输出选项

CVE 二进制工具默认提供基于控制台的输出。如果您想提供其他格式，可以使用 --format 指定此格式和一个文件名，并在命令行上使用。有效格式包括 CSV、JSON、JSON2、控制台、HTML 和 PDF。可以使用 --output-file 标志指定输出文件名。

您还可以使用逗号 (',') 作为分隔符指定多个输出格式

cve-bin-tool file -f csv,json,json2,html -o report

注意：您必须在逗号 (',') 和输出格式之间不要留有空格。

您还可以通过指定 --vex-output 并使用 --vex-type 命令行选项定义类型来以漏洞利用交换 (VEX) 格式报告报告的漏洞。生成的 VEX 文件然后可以作为 --vex-file 使用，以支持分类过程。

如果您想使用 PDF 支持，您需要单独安装 reportlab 库。

如果您在安装 cve-bin-tool 时打算使用 PDF 支持，您可以指定它，report lab 将作为 cve-bin-tool 安装的一部分进行安装。

pip install cve-bin-tool[PDF]

如果您已经安装了 cve-bin-tool，您可以使用 pip 在之后添加 reportlab。

pip install --upgrade reportlab

请注意，由于与已知 CVE 相关（CVE-2020-28463），reportlab 已从默认的 cve-bin-tool 安装中移除。cve-bin-tool 代码使用推荐的缓解措施来限制添加到 PDF 中的资源，以及额外的输入验证。这是一个有点奇怪的 CVE，因为它描述了 PDF 的核心功能：外部项，如图像，可以嵌入其中，因此查看 PDF 的任何人都可以加载外部图像（类似于查看网页可以触发外部加载）。对此没有固有的“修复”，只有缓解措施，其中库的用户必须确保在生成时只添加预期项到 PDF 中。

由于用户可能不希望安装与一个开放、无法修复的 CVE 相关的软件，我们选择只将 PDF 支持提供给自行安装库的用户。一旦安装了库，PDF 报告选项将正常工作。

配置

您可以使用 --config 选项为工具提供配置文件。您仍然可以通过命令行参数覆盖配置文件中指定的选项。请参阅我们的示例配置文件，位于 test/config

组件自动检测

CVE 二进制工具尝试通过二进制检查器、支持的语言组件列表和文件提取方法自动检测组件。以下列出了支持自动检测的工具。

二进制检查器列表

以下检查器可用于在二进制文件中查找组件

所有检查器都可以在checkers目录中找到，包括如何添加新检查器的说明。

特定语言检查器

有几个检查器可用于在特定语言包中查找有漏洞的组件。

有关语言特定检查器的更多信息，请参阅CVE Binary Tool 手册。

支持的存档格式

自动提取器目前支持以下归档格式

附加要求

使用自动提取器，您可能需要以下工具，具体取决于您需要提取的支持的归档格式类型。

以下工具是运行 Linux 上完整测试套件所必需的

• file
• strings
• tar
• unzip
• rpm2cpio
• cpio
• ar
• cabextract

这些工具中的大多数在许多 Linux 系统上默认安装，但 cabextract 和 rpm2cpio 可能需要安装。

在 Windows 系统上，您可能需要

• ar
• 7z
• 展开
• pdftotext

Windows 默认已安装 Expand，但可能需要安装 ar 和 7z。如果您想运行我们的测试套件或扫描 zstd 压缩文件，我们建议安装此 7zip 的分支 7-zip-zstd。我们目前使用 7z 提取 jar、apk、msi、exe 和 rpm 文件。要安装 ar，您可以从这里安装 MinGW（其中包含 binutils 作为其一部分）并运行下载的 .exe 文件。

如果您尝试从 pip 安装时遇到构建库的错误，您可能需要安装 Windows 构建工具。Windows 构建工具可以从 https://visualstudio.microsoft.com/visual-cpp-build-tools/ 免费获取。

如果在 Windows 上安装 brotlipy 时遇到错误，安装上面的编译器应该可以解决这个问题。

运行测试需要 pdftotext。对于 cve-bin-tool 的用户可能不需要它，但开发者可能需要。在 Windows 上安装它的最佳方法是通过 conda（点击这里获取进一步说明）。

您可以检查 我们的 CI 配置，以查看我们明确测试的 Python 版本。

限制

此扫描器不会尝试利用问题或更详细地检查代码；它仅查找库签名和版本号。因此，它无法判断是否有人将修复程序回滚到有漏洞的版本，并且如果库或版本信息被故意混淆，则不会工作。

此工具旨在作为快速运行、易于自动化的检查在非恶意环境中使用，以便开发人员可以意识到已编译到他们的二进制文件中的旧库的安全问题。

该工具不保证报告的所有漏洞实际上都存在或可利用，它也无法保证找到所有现有的漏洞。它也无法找到所有现有的漏洞并保证找到所有漏洞。

用户可以在报告中添加分类信息，将问题标记为假阳性，表明风险已通过配置/使用更改等减轻，等等。

分类细节可以在其他项目中重复使用，例如，在 Linux 基础镜像上的分类可以应用于使用该镜像的多个容器。

有关更多信息和使用该工具与分类信息的使用方法，请参阅 这里。

如果您正在使用二进制扫描功能，请注意我们只有有限数量的二进制检查器（见上表），因此我们只能检测这些库。我们始终欢迎新的检查器贡献！您还可以使用其他方法来检测组件（例如，物料清单工具，如 tern），然后使用该结果列表作为 cve-bin-tool 的输入，以获取更全面的漏洞列表。

该工具使用漏洞数据库来检测现有漏洞，如果数据库更新不频繁（尤其是如果工具以离线模式使用），则该工具将无法检测到任何新发现的漏洞。因此，强烈建议保持数据库更新。

该工具不保证报告所有漏洞，因为该工具只能访问有限数量的公开可用漏洞数据库。我们始终欢迎为工具引入新的数据来源的贡献。

虽然对漏洞数据库中的数据进行了一些验证检查，但如果数据不完整或不一致，则该工具无法断言数据的质量或纠正任何差异。例如，这可能导致某些漏洞报告中将严重性报告为未知。

反馈 & 贡献

可以通过GitHub issue提交错误和功能请求。请注意，这些问题不是私密的，因此在提供输出时请确保不要泄露其他产品的安全问题。

也可以通过git提交拉取请求。

• 新贡献者应该阅读贡献指南以开始。
• 对于已经有一定开源项目贡献经验的开发者，可能不需要完整的指南，但仍应使用拉取请求清单以方便所有人。

CVE二进制工具的贡献者应遵守Python社区行为准则。如果您对此准则有任何疑问或担忧，请联系Terri。

安全问题

关于工具本身的安全问题，可以通过https://intel.com/security报告给英特尔的安全事件响应团队。

如果在使用此工具的过程中发现他人代码中的安全问题，请负责任地向相关方披露。

完整选项列表

用法： cve-bin-tool <要扫描的目录/文件>

options:
  -h, --help            show this help message and exit
  -e EXCLUDE, --exclude EXCLUDE
                        Comma separated Exclude directory path
  -V, --version         show program's version number and exit
  --disable-version-check
                        skips checking for a new version
  --disable-validation-check
                        skips checking xml files against schema
  --offline             operate in offline mode
  --detailed            add CVE description in csv or json report (no effect on console, html or pdf)

CVE Data Download:
  Arguments related to data sources and Cache Configuration

  -n {api,api2,json,json-mirror,json-nvd}, --nvd {api,api2,json,json-mirror,json-nvd}
                        choose method for getting CVE lists from NVD
  -u {now,daily,never,latest}, --update {now,daily,never,latest}
                        update schedule for data sources and exploits database (default: daily)
  --nvd-api-key NVD_API_KEY
                        Specify NVD API key (used to improve NVD rate limit).
                        Set to `no` to ignore any keys in the environment.
  -d DISABLE_DATA_SOURCE, --disable-data-source DISABLE_DATA_SOURCE
                        comma-separated list of data sources (CURL, EPSS, GAD, NVD, OSV, PURL2CPE, REDHAT, RSD) to disable (default: NONE)

  --use-mirror USE_MIRROR
                        use an mirror to update the database

Input:
  directory             directory to scan
  -i INPUT_FILE, --input-file INPUT_FILE
                        provide input filename
  -C CONFIG, --config CONFIG
                        provide config file
  -L PACKAGE_LIST, --package-list PACKAGE_LIST
                        provide package list
  --sbom {spdx,cyclonedx,swid}
                        specify type of software bill of materials (sbom) (default: spdx)
  --sbom-file SBOM_FILE
                        provide sbom filename
  --vex-file VEX_FILE
                        provide vulnerability exploitability exchange (vex) filename for triage processing


Output:
  -q, --quiet           suppress output
  -l {debug,info,warning,error,critical}, --log {debug,info,warning,error,critical}
                        log level (default: info)
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        provide output filename (default: output to stdout)
  --html-theme HTML_THEME
                        provide custom theme directory for HTML Report
  -f {csv,json,json2,console,html,pdf}, --format {csv,json,json2,console,html,pdf}
                        update output format (default: console)
                        specify multiple output formats by using comma (',') as a separator
                        note: don't use spaces between comma (',') and the output formats.
  --generate-config {yaml,toml,yaml,toml,toml,yaml}
                        generate config file for cve bin tool in toml and yaml formats.
  -c CVSS, --cvss CVSS  minimum CVSS score (as integer in range 0 to 10) to report (default: 0)
  -S {low,medium,high,critical}, --severity {low,medium,high,critical}
                        minimum CVE severity to report (default: low)
  --metrics             
                        check for metrics (e.g., EPSS) from found cves
  --epss-percentile EPSS_PERCENTILE
                        minimum epss percentile of CVE range between 0 to 100 to report. Automatically enables `--metrics`
  --epss-probability EPSS_PROBABILITY
                        minimum epss probability of CVE range between 0 to 100 to report. Automatically enables `--metrics`
  --no-0-cve-report     only produce report when CVEs are found
  -A [-], --available-fix [-]
                        Lists available fixes of the package from Linux distribution
  -b [-], --backport-fix [-]
                        Lists backported fixes if available from Linux distribution
  --affected-versions   Lists versions of product affected by a given CVE (to facilitate upgrades)
  --sbom-output SBOM_OUTPUT
                        provide software bill of materials (sbom) filename to generate
  --sbom-type {spdx,cyclonedx}
                        specify type of software bill of materials (sbom) to generate (default: spdx)
  --sbom-format {tag,json,yaml}
                        specify format of software bill of materials (sbom) to generate (default: tag)

Vex Output:
  Arguments related to Vex output document.

  --vex-ouptput VEX_OUTPUT
                        Provide vulnerability exploitability exchange (vex) filename to generate
  --vex-type {cyclonedx, csaf, openvex}
                        specify type of vulnerability exploitability exchange (vex) to generate (default: cyclonedx)
  --product PRODUCT     Product Name
  --release RELEASE     Release Version
  --vendor VENDOR       Vendor/Supplier of Product
  -rr REVISION_REASON, --revision-reason REVISION_REASON
                        a reason for the update to the vex document should be specified in double quotes
  --filter-triage       Filter cves based on triage data from Vex file

Merge Report:
  Arguments related to Intermediate and Merged Reports

  -a [APPEND], --append [APPEND]
                        save output as intermediate report in json format
  -t TAG, --tag TAG     add a unique tag to differentiate between multiple intermediate reports
  -m MERGE, --merge MERGE
                        comma separated intermediate reports path for merging
  -F FILTER, --filter FILTER
                        comma separated tag string for filtering intermediate reports

Checkers:
  -s SKIPS, --skips SKIPS
                        comma-separated list of checkers to disable
  -r RUNS, --runs RUNS  comma-separated list of checkers to enable

Database Management:
  --import-json IMPORT_JSON
                        import database from json files chopped by years
  --ignore-sig          do not verify PGP signature while importing json data
  --log-signature-error
                        when the signature doesn't match log the error only instead of halting (UNSAFE)
  --verify PGP_PUBKEY_PATH
                        verify PGP sign while importing json files
  --export-json EXPORT_JSON
                        export database as json files chopped by years
  --pgp-sign PGP_PRIVATE_KEY_PATH
                        sign exported json files with PGP
  --passphrase PASSPHRASE
                        required passphrase for signing with PGP
  --export EXPORT       export database filename
  --import IMPORT       import database filename

Exploits:
  --exploits            check for exploits from found cves

Deprecated:
  --triage-input-file TRIAGE_INPUT_FILE
                        replaced by --vex-file
  -x, --extract         autoextract compressed files
  --report              Produces a report even if there are no CVE for the respective output format

有关所有这些选项的更多信息，请参阅CVE二进制工具用户手册。