Refine the XLSX documentation and add SPDX/CycloneDX entries #1589 (#1610)

* Refine the XLSX documentation and add SPDX/CycloneDX entries #1589

Signed-off-by: tdruez <[email protected]>

* Add FAQ entry wrt. containers #1575

Signed-off-by: tdruez <[email protected]>

---------

Signed-off-by: tdruez <[email protected]>

Author: tdruez

docs/data-models.rst

@@ -14,34 +14,44 @@ Project
     :undoc-members:
     :member-order: groupwise
 
+.. _data_models_codebase_resource:
+
 CodebaseResource
 ----------------
 .. autoclass:: scanpipe.models.CodebaseResource()
     :members:
     :undoc-members:
     :member-order: groupwise
 
+.. _data_models_discovered_package:
+
 DiscoveredPackage
 -----------------
 .. autoclass:: scanpipe.models.DiscoveredPackage()
     :members:
     :undoc-members:
     :member-order: groupwise
 
+.. _data_models_discovered_dependency:
+
 DiscoveredDependency
 --------------------
 .. autoclass:: scanpipe.models.DiscoveredDependency()
     :members:
     :undoc-members:
     :member-order: groupwise
 
+.. _data_models_codebase_relation:
+
 CodebaseRelation
 ----------------
 .. autoclass:: scanpipe.models.CodebaseRelation()
     :members:
     :undoc-members:
     :member-order: groupwise
 
+.. _data_models_project_message:
+
 ProjectMessage
 --------------
 .. autoclass:: scanpipe.models.ProjectMessage()

docs/faq.rst

@@ -322,6 +322,39 @@ data older than 7 days::
   command.
 
 How can I provide my license policies?
----------------------------------------
+--------------------------------------
 
 For detailed information about the policies system, refer to :ref:`policies`.
+
+Can you analyze Dockerfiles?
+----------------------------
+
+We have code in https://github.com/aboutcode-org/container-inspector/blob/main/src/container_inspector/dockerfile.py
+for this ... but this may not be wired in other tools at the moment.
+It can for instance map dockerfile instructions to actual docker image history,
+https://github.com/aboutcode-org/container-inspector/blob/main/src/container_inspector/dockerfile.py#L204
+
+Can you analyze a built image? (Build Docker Image Analysis)
+------------------------------------------------------------
+
+Yes, we do this in ScanCode.io. We have one fairly unique feature to actually account
+for all files used in all layers.
+
+Can you analyze all layers of a running container?
+--------------------------------------------------
+
+ScanCode.io scans all layers of images. We can scan all layers of a running container
+if you save the running container as an image first.
+We can also fetch images from registries, local files and technically also from a
+running container, say in a local docker ... but this has not yet been tested so far.
+We do not introspect k8s clusters to analyze the deployed and running images
+there (yet) and that would be a nice future addition.
+For now we can instead work on the many images there, save and analyze them.
+
+Can you analyze Docker in Docker?
+---------------------------------
+
+The input to ScanCode is a local saved image: Docker or OCI.
+Docker in Docker support will demand to have access to the saved images
+(either extracted from the Docker images in Docker, or mounted in a volume or saved
+from the Docker in the Docker image). Once saved we can analyze these alright.

docs/images/output-files-xlsx-packages.png

@@ -64,11 +64,10 @@ ScanCode.io home screen.
 
 .. image:: images/output-files-projects-list.png
 
-Understanding Output Files
---------------------------
-As previously mentioned, the output file format is set using the ``–-format``
-option to either JSON or XLSX data files. Regardless of the format, the
-data included in either output file remains almost the same.
+Supported formats
+-----------------
+
+.. _output_files_json:
 
 JSON
 ^^^^
@@ -252,23 +251,85 @@ The results will also include all of the  or files (codebase resources) found.
       "is_archive": false
     }]
 
+.. _output_files_xlsx:
+
 Excel (XLSX)
 ^^^^^^^^^^^^
-ScanCode.io can produce the scan results in a .xlsx file format, which will
-include two Excel sheets for the Discovered Packages and the Codebase Resources.
+ScanCode.io can generate scan results in **Excel (.xlsx)** format. The exported file
+contains multiple sheets, categorized by data type. The following sheets are
+**always included**:
+
+- **PACKAGES**: :ref:`data_models_discovered_package`
+- **DEPENDENCIES**: :ref:`data_models_discovered_dependency`
+- **RESOURCES**: :ref:`data_models_codebase_resource`
+- **RELATIONS**: :ref:`data_models_codebase_relation`
+- **MESSAGES**: :ref:`data_models_project_message`
+
+Additional sheets are included **only when relevant** (i.e., when data is available):
+
+- **LAYERS**: Included when scanning **container images** using the
+  :ref:`pipeline_analyze_docker_image` pipeline.
+- **TODOS**: Contains resources flagged as **"REQUIRES_REVIEW"**.
+- **VULNERABILITIES**: Lists vulnerabilities detected in project **packages** and
+  **dependencies**, typically when using the :ref:`pipeline_find_vulnerabilities`
+  pipeline. This sheet is omitted if no vulnerabilities are found.
+
+.. warning::
+   Unlike JSON exports, the **XLSX output** does not include general scan metadata,
+   such as tool version, execution date, or scan parameters.
+
+   Since it contains only a subset of the project data, it **cannot** be used to
+   recreate the project. For this purpose, prefer the :ref:`output_files_json` output.
+
+.. _output_files_spdx:
+
+SPDX
+^^^^
+
+ScanCode.io can generate Software Bill of Materials (SBOM) in the **SPDX** format,
+which is an open standard for communicating software component information.
+SPDX is widely used for license compliance, security analysis, and software supply
+chain transparency.
+
+For more details, visit: https://spdx.dev/
+
+The SPDX output includes:
+
+- **Packages:** Information about detected software packages, including name, version,
+  licensing, and supplier details.
+- **Files:** A list of scanned files with associated metadata, including licenses and
+  copyright notices.
+- **Relationships:** Dependencies and associations between packages and files.
+- **Licenses:** License expressions for detected components.
 
 .. note::
-    Unlike the JSON file, the XLSX output file does not include any general
-    information about the scan process, tool, date, etc.
+   ScanCode.io produces SPDX documents in **SPDX JSON and Tag/Value formats**.
 
-The **Discovered Packages** data sheet includes details about all packages found:
+.. _output_files_cyclonedx:
 
-.. image:: images/output-files-xlsx-packages.png
+CycloneDX
+^^^^^^^^^
 
-while the **Codebase Resources** sheet includes information about each
-individual file:
+ScanCode.io can generate **CycloneDX** SBOMs, a lightweight standard designed for
+security and dependency management. CycloneDX is optimized for vulnerability analysis
+and software supply chain risk assessment.
+
+For more details, visit: https://cyclonedx.org/
+
+The CycloneDX output includes:
+
+- **Components:** A list of identified software components, including their
+  versions and licensing information.
+- **Dependencies:** Relationships between software components, useful for analyzing
+  supply chain risks.
+- **Vulnerabilities (when available):** If vulnerability scanning is enabled,
+  detected vulnerabilities will be included in the CycloneDX output.
+- **Metadata:** Information about the scan, including tool details and execution data.
+
+.. note::
+   ScanCode.io produces CycloneDX SBOMs in **JSON format**.
 
-.. image:: images/output-files-xlsx-resources.png
+.. _output_files_attribution:
 
 Attribution
 ^^^^^^^^^^^