export: add basic text report exporter

README.md

@@ -29,22 +29,22 @@ https://sbom-cve-check.readthedocs.io/en/latest/index.html) for further details.
 This tool was started as a way of replacing the *cve-check* logic
 implemented in Yocto, which requires running a full build to perform a
 new CVE analysis. `sbom-cve-check` instead can run on the SBOM
-produced once by Yocto and can be used to regularly run the CVE
+produced once by Yocto Project and can be used to regularly run the CVE
 analysis in less than a minute.
 
 ## Getting started
 
-Assuming you're using Yocto, 4 easy steps:
+Assuming you're using Yocto Project, 4 easy steps:
 
 1. **Install** the tool:<br>
    `pip install sbom-cve-check[extra]`<br>
    (You may want to do this in a Python virtual environment).
 
-2. **Generate** the SBOM with Yocto:<br>
-   SPDXv3.0 is generated by default since Yocto Walnascar (5.2).<br>
+2. **Generate** the SBOM with Yocto Project:<br>
+   SPDXv3.0 is generated by default since Yocto ProjectWalnascar (5.2).<br>
    Add `INHERIT += "vex"` in your `local.conf`.
 
-3. **Retrieve** two artifacts from the Yocto `deploy` directory:<br>
+3. **Retrieve** two artifacts from the Yocto Project`deploy` directory:<br>
    `${IMAGE_NAME}.rootfs.spdx.json`: The SPDX v3.0 SBOM file.<br>
    `${IMAGE_NAME}.rootfs.json`: File generated by the vex.bbclass.
 
@@ -65,8 +65,8 @@ Assuming you're using Yocto, 4 easy steps:
 - Allow to generate an SBOM (CDX or SPDX 3.0) as output even if the
   SBOM specified as input is in another format.
 
-## Compatibility with Yocto
+## Compatibility with Yocto Project
 
-The compatibility with the SBOM generated by Yocto is described in the
-[Yocto SBOM](
-https://sbom-cve-check.readthedocs.io/en/latest/sbom.html#yocto-sbom) section.
+The compatibility with the SBOM generated by Yocto Project is described in the
+[Yocto Project SBOM](
+https://sbom-cve-check.readthedocs.io/en/latest/sbom.html#yocto-project-sbom) section.

docs/database.md

@@ -29,15 +29,15 @@ flag as described in the subsections below, or from one or more TOML
 
 The following CVE and annotation databases are supported:
 
-| Name                 | Short description                                    |
-|----------------------|------------------------------------------------------|
-| `openvex-file`       | Path to one OpenVEX annotation file                  |
-| `openvex-dir`        | Directory containing OpenVEX annotation files        |
-| `spdx3-file`         | Path to one SPDX v3.0 SBOM file                      |
-| `yocto-vex-manifest` | Path to Yocto VEX manifest, generated by vex.bbclass |
-| `simple-annotations` | Directory containing simple YAML annotation files    |
-| `cve-db-nvd-fkie`    | Path to FKIE nvd-json-data-feeds git repository      |
-| `cve-db-cvelist`     | Path to CVEProject cvelistV5 git repository          |
+| Name                 | Short description                                            |
+|----------------------|--------------------------------------------------------------|
+| `openvex-file`       | Path to one OpenVEX annotation file                          |
+| `openvex-dir`        | Directory containing OpenVEX annotation files                |
+| `spdx3-file`         | Path to one SPDX v3.0 SBOM file                              |
+| `yocto-vex-manifest` | Path to Yocto Project VEX manifest, generated by vex.bbclass |
+| `simple-annotations` | Directory containing simple YAML annotation files            |
+| `cve-db-nvd-fkie`    | Path to FKIE nvd-json-data-feeds git repository              |
+| `cve-db-cvelist`     | Path to CVEProject cvelistV5 git repository                  |
 
 The database type can be specified:
  - From a configuration file using the `type=` option.
@@ -253,22 +253,22 @@ more common, for this database to be added automatically via the input
 
 ### yocto-vex-manifest
 
-This annotation database provides a single Yocto {term}`VEX` manifest file
-generated from the Yocto `vex.bbclass`.
+This annotation database provides a single Yocto Project {term}`VEX` manifest
+file generated from the Yocto Project `vex.bbclass`.
 
-This file contains the following information for each Yocto recipe
+This file contains the following information for each Yocto Project recipe
 (non-exclusive list):
  - package version
  - list of CPE
- - list of associated Yocto annotations specified by `CVE_STATUS`
+ - list of associated Yocto Project annotations specified by `CVE_STATUS`
 
-By default, in Yocto, the file is provided in the `deploy` directory with the
-following name: `${IMAGE_BASENAME}-${MACHINE}.rootfs.json`
+By default, in the Yocto Project, the file is provided in the `deploy` directory
+with the following name: `${IMAGE_BASENAME}-${MACHINE}.rootfs.json`
 
 For convenience, this database file can also be directly added with the
-`--yocto-vex-manifest` flag followed by the path to the Yocto VEX manifest file.
-But in that case, no additional options can be specified: default options will
-be used.
+`--yocto-vex-manifest` flag followed by the path to the Yocto Project VEX
+manifest file. But in that case, no additional options can be specified: default
+options will be used.
 
 ### simple-annotations
 

docs/export.md

@@ -30,6 +30,7 @@ The following exporters are provided:
 |----------------------------|--------------------------------------------------|
 | `csv`                      | A CSV file: one line by CVE                      |
 | `spdx3`                    | An SPDX v3.0 with CVE and associated assessments |
+| `summary`                  | A plain text file listing the vulnerable CVEs    |
 | `yocto-cve-check-manifest` | A JSON file, with a format similar to cve-check  |
 
 The export format can be specified by using the `--export-type` flag.
@@ -84,11 +85,17 @@ be added to the SPDX file:
  - External references
  - {term}`VEX` {term}`assessment`
 
-### Yocto cve-check format
+### Summary format
+
+This export, selected with the `summary` type, generates a plain-text file
+listing all of the vulnerabilities in each component, in a style similar to the
+console output from the Yocto Project's `cve-check` class.
+
+### Yocto Project cve-check format
 
 This export, selected with `yocto-cve-check-manifest` type, generates a JSON
-file in a format very similar to the cve-check output generated via Yocto's
-`cve-check.bbclass`.
+file in a format very similar to the cve-check output generated via Yocto
+Project's `cve-check.bbclass`.
 
 There are various differences and limitations:
  - In each package object, an additional key is specified: `cpes`. This key
@@ -98,8 +105,8 @@ There are various differences and limitations:
  - `cvesInRecord` is set to `Yes` for all products if there is at least one
    CVE associated with this package.
 
-For more details on the *cve-check* export format, see the Yocto developer
-manual on [vulnerabilities](
+For more details on the *cve-check* export format, see the Yocto Project
+Developer Manual on [vulnerabilities](
 https://docs.yoctoproject.org/dev/dev-manual/vulnerabilities.html).
 
 ## Export options

docs/introduction.md

@@ -25,7 +25,7 @@ these requirements and maintain a proactive security posture.
 
 The **sbom-cve-check** tool was developed to simplify this process. It allows
 users to automatically search for CVEs related to the components listed in an
-SBOM. Although it was initially designed to analyze Yocto-generated SBOMs
+SBOM. Although it was initially designed to analyze Yocto Project-generated SBOMs
 for embedded devices, it can be used with any SBOM file (if the format is
 supported) to perform vulnerability assessments outside of build environments.
 This makes **sbom-cve-check** a valuable tool for developers, integrators,
@@ -46,7 +46,7 @@ their software supply chain.
 
  - **Annotation Support**:
 
-   Can consume OpenVEX files, Yocto VEX annotations and custom annotations,
+   Can consume OpenVEX files, Yocto Project VEX annotations and custom annotations,
    enabling users to document and manage vulnerability assessments - such as
    confirming that a CVE does not affect a product under specific conditions.
 
@@ -61,7 +61,7 @@ their software supply chain.
    Generates [exports](export.md) in multiple formats:
     - A simple CSV report for easy review or integration into reporting
       pipelines.
-    - A similar format that Yocto *cve-check* generates.
+    - A similar format that Yocto Project *cve-check* generates.
     - An enriched SPDX 3.0 file, where the original SBOM is extended with CVE
       information and associated assessments, while preserving the complete
       vulnerability context in a machine-readable form.

docs/sbom.md

@@ -22,10 +22,10 @@ an archive or a directory.
 
 The following SBOM input formats are supported:
 
-| Name    | Short description           |
-|---------|-----------------------------|
-| `spdx2` | SPDX v2.2 Yocto SBOM file   |
-| `spdx3` | SPDX v3.0 JSON-LD SBOM file |
+| Name    | Short description                   |
+|---------|-------------------------------------|
+| `spdx2` | SPDX v2.2 Yocto Project SBOM file   |
+| `spdx3` | SPDX v3.0 JSON-LD SBOM file         |
 
 The SBOM type can be specified by using the `--sbom-type` flag. If this option
 flag is not specified, *sbom-cve-check* tries to automatically detect the SBOM
@@ -37,7 +37,7 @@ For a {term}`SPDX` v2.2 format, the tool expects to receive the path to either:
  - a directory containing multiple `.spdx.json` files.
  - a TAR archive, typically with the following extension: `.spdx.tar.zst`.
 
-*sbom-cve-check* was only tested with SBOMs generated by Yocto. SPDX v2
+*sbom-cve-check* was only tested with SBOMs generated by  Project. SPDX v2
 generated by other tools is not currently supported, but contributions are
 welcome.
 
@@ -74,60 +74,60 @@ the following flags can be used: `--sbom-obsolete-assessment-check`,
 To prevent the automatic creation of an annotation database from the SBOM file,
 the `--ignore-sbom-annotations` flag needs to be set.
 
-## Yocto SBOM
+## Yocto Project SBOM
 
-### Yocto release compatibility
+### Yocto Project release compatibility
 
-| Codename   | Yocto Version | Support status                            |
-|------------|---------------|-------------------------------------------|
-| Kirkstone  | 4.0           | Not supported                             |
-| Scarthgap  | 5.0           | Supported since 2024-04.14 (yocto-5.0.14) |
-| Styhead    | 5.1           | Not supported, and not tested             |
-| Walnascar  | 5.2           | Fully supported                           |
-| Whinlatter | 5.3           | Should be functional, not tested (yet)    |
+| Codename   | Yocto Project Version | Support status                            |
+|------------|-----------------------|-------------------------------------------|
+| Kirkstone  | 4.0                   | Not supported                             |
+| Scarthgap  | 5.0                   | Supported since 2024-04.14 (yocto-5.0.14) |
+| Styhead    | 5.1                   | Not supported, and not tested             |
+| Walnascar  | 5.2                   | Fully supported                           |
+| Whinlatter | 5.3                   | Should be functional, not tested (yet)    |
 
-For Yocto Scarthgap, the sbom-cve-check is fully usable using the latest
+For Yocto Project Scarthgap, the sbom-cve-check is fully usable using the latest
 revision from `scarthgap` branch. The latest commits include the `vex.bbclass`
 and allow all CVE annotations to be exported to the SPDX v3.0 file. These
 improvement will be present in the future 2024-04.14 (yocto-5.0.14) release.
 
 ### SPDX v3.0
 
-Yocto is able to generate an SPDX SBOM file in v3.0.1 format. By default, the
+The Yocto Project is able to generate an SPDX SBOM file in v3.0.1 format. By default, the
 `create-spdx.bbclass` is inherited: See `meta/conf/distro/defaultsetup.conf`.
-Since Yocto *Styhead* release (5.1), the `create-spdx.bbclass` generates an SPDX
+Since Yocto Project *Styhead* release (5.1), the `create-spdx.bbclass` generates an SPDX
 v3.0. For older releases, the `create-spdx-3.0.bbclass` needs to be explicitly
 used:
 ```
 INHERIT:remove = "create-spdx"
 INHERIT += "create-spdx-3.0"
 ```
 
-Yocto, by default, generates the SBOM in the `deploy` directory with the
+The Yocto Project, by default, generates the SBOM in the `deploy` directory with the
 following name: `${IMAGE_BASENAME}-${MACHINE}.rootfs.spdx.json`.
 
 ### SPDX v2.2
 
-Yocto is able to generate an SPDX SBOM file in v2.2 format. By default, the
+The Yocto Project is able to generate an SPDX SBOM file in v2.2 format. By default, the
 `create-spdx.bbclass` is inherited: See `meta/conf/distro/defaultsetup.conf`.
-In Yocto *Scarthgap* release (5.0), the `create-spdx.bbclass` generates an SPDX
+In Yocto Project *Scarthgap* release (5.0), the `create-spdx.bbclass` generates an SPDX
 v2.2. For newer releases, the `create-spdx-2.2.bbclass` needs to be explicitly
 used:
 ```
 INHERIT:remove = "create-spdx"
 INHERIT += "create-spdx-2.2"
 ```
 
-Yocto exports very little information about CVE status when using SPDX v2.2.
-It is recommended to either use SPDX v3.0, or also use the information provided
-by the manifest generated by `vex.bbclass`.
+THe Yocto Project exports very little information about CVE status when using
+SPDX v2.2. It is recommended to either use SPDX v3.0, or also use the
+information provided by the manifest generated by `vex.bbclass`.
 
-Yocto, by default, generates the SBOM in the `deploy` directory with the
+The Yocto Project, by default, generates the SBOM in the `deploy` directory with the
 following name: `${IMAGE_BASENAME}-${MACHINE}.rootfs.spdx.tar.zst`.
 
-### Yocto configuration
+### Yocto Project configuration
 
-To be able to extract all Yocto annotations specified in the recipes by the
+To be able to extract all Yocto Project annotations specified in the recipes by the
 `CVE_STATUS` variable, there are 2 options:
  - Configure `SPDX_INCLUDE_VEX` to `all`, but this is not recommended;
    otherwise, the SPDX generation can be very slow, and the resulting SPDX

docs/user-guide.md

@@ -148,17 +148,17 @@
  - [Design: Finding Applicable CVEs](design.md#find-applicable-cve)
  - [Design: Compute VEX assessment](design.md#compute-vex-assessment)
 
-## Compatibility with Yocto
+## Compatibility with Yocto Project
 
-The compatibility with the SBOM generated by Yocto is described in the
-[Yocto SBOM](sbom.md#yocto-sbom) subsection.
+The compatibility with the SBOM generated by the Yocto Project is described in the
+[Yocto Project SBOM](sbom.md#yocto-project-sbom) subsection.
 
 ## Examples of invocation
 
-The example below uses as input the SPDX v3.0 SBOM file generated by Yocto,
-and the additional VEX manifest generated by the `vex.bbclass`, which contains
-all the Yocto annotations declared in the recipes by the `CVE_STATUS` variable,
-as described in the [Yocto SBOM](sbom.md#yocto-sbom) section.
+The example below uses as input the SPDX v3.0 SBOM file generated by the Yocto
+Project, and the additional VEX manifest generated by the `vex.bbclass`, which
+contains all the Yocto Project annotations declared in the recipes by the `CVE_STATUS`
+variable, as described in the [Yocto Project SBOM](sbom.md#yocto-project-sbom) section.
 
 
 For example with:
@@ -166,7 +166,7 @@
 IMAGE_NAME="core-image-minimal-qemuarm"
 ```
 
 This example generates as output a JSON file in a
 [similar format](export.md#yocto-cve-check-format), which is generated by the
 `cve-check.bbclass`.
 
@@ -187,9 +187,9 @@
   --export-type csv --export-path out.csv
 ```
 
-The following input files can be found in the Yocto `deploy` directory:
+The following input files can be found in the Yocto Project `deploy` directory:
  - `${IMAGE_NAME}.rootfs.spdx.json`: The SPDX v3.0 SBOM file.
- - `${IMAGE_NAME}.rootfs.json`: The Yocto VEX manifest, generated by the
+ - `${IMAGE_NAME}.rootfs.json`: The Yocto Project VEX manifest, generated by the
    `vex.bbclass`.
 
 ## Overview of command-line options
@@ -247,7 +247,7 @@
   --add-db [TYPE PATH KEY=VALUE, ...]
                         Allow to add database from command line
   --yocto-vex-manifest PATH
-                        Shortcut to specify a Yocto Vex manifest, with default configuration
+                        Shortcut to specify a Yocto Project Vex manifest, with default configuration
   --check-obsolete-assessment-by-default
                         If set, by default, check for obsolete assessment
   --disable-auto-updates

src/sbom_cve_check/cli.py

@@ -481,7 +481,7 @@ def main() -> None:
         metavar="PATH",
         type=pathlib.Path,
         action="append",
-        help="Shortcut to specify a Yocto Vex manifest, with default configuration",
+        help="Shortcut to use a Yocto Project Vex manifest, with default configuration",
     )
     conf_p.add_argument(
         "--check-obsolete-assessment-by-default",

src/sbom_cve_check/export/export_summary.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+# SPDX-License-Identifier: GPL-2.0-only
+
+import contextlib
+import pathlib
+import sys
+import typing
+from collections.abc import Generator
+
+from ..database.annot_aggregate import AggregateAnnotEntry
+from ..sbom.component import CompBuild
+from ..sbom.sbom_base import Sbom
+from .export_base import BaseExport
+from .registry import register_export
+
+
+@register_export("summary")
+class SummaryExport(BaseExport):
+    """
+    Export vulnerability information in plain text.
+
+    Basic plain text summary report, listing components that have unresolved
+    vulnerabilities.
+    """
+
+    def __init__(self, sbom: Sbom, out_path: pathlib.Path) -> None:
+        """
+        Initialize SummaryExport.
+
+        :param sbom: The SBOM object.
+        :param out_path: Output file path.
+        """
+        super().__init__(sbom, out_path)
+        self._file: typing.TextIO | None = None
+
+    def start_export(self) -> Generator[None, None, None]:
+        """
+        Start the report export.
+
+        :return: Generator context.
+        """
+        with (
+            contextlib.nullcontext(sys.stdout)
+            if self._out_path.name == "-"
+            else self._out_path.open("w", encoding="utf-8")
+        ) as self._file:
+            yield
+
+    def export_comp_info(
+        self, comp_build: CompBuild
+    ) -> Generator[None, tuple[bool, AggregateAnnotEntry], None]:
+        """
+        Export component build info to report.
+
+        :param comp_build: Component build object.
+        :return: Generator accepting vulnerability annotations.
+        """
+        assert self._file
+        vuln_ids = []
+        version = comp_build.pkg_version or comp_build.version
+        try:
+            while True:
+                is_filtered, annotation = yield
+                if not is_filtered and annotation.vulnerable:
+                    vuln_ids.append(annotation.identifier.id)
+        finally:
+            if vuln_ids:
+                self._file.write(
+                    f"Unpatched vulnerabilities in {comp_build.build_name}-{version}: "
+                    f"{' '.join(sorted(vuln_ids))}\n"
+                )