docs: add ScanCode.io and DejaCode compliance workflow reference (#607)

Signed-off-by: tdruez <tdruez@aboutcode.org>

Author: tdruez

docs/howto-1.rst

@@ -142,6 +142,8 @@ Review Usage Policy Impact
 
 Continue refining and reviewing your Usage Policies.
 
+.. _how_to_1_export_license_policies:
+
 Export License Policy Definitions
 ---------------------------------
 
@@ -155,3 +157,6 @@ ScanCode Toolkit (scancode-toolkit).
   section of the form.
 - View or edit the exported **license_policies.yml** file in your preferred text editor.
 - Use the file as an input option to ScanCode Toolkit to enhance the output results.
+- Provide the file to ScanCode.io, for the whole instance or per project, to flag each
+  detected license with your compliance alerts. See
+  `ScanCode.io License Policies <https://scancodeio.readthedocs.io/en/latest/policies.html>`_.

docs/images/reference-scancodeio-workflow/workflow.svg

@@ -31,7 +31,8 @@ DejaCode includes the following modules:
 * **API**: Use the DejaCode API to integrate with your other data sources and
   applications.
 
-New to DejaCode? Start with the :ref:`quickstart`.
+New to DejaCode? Start with the :ref:`quickstart`. To see how DejaCode and ScanCode.io
+work together, read the :ref:`reference_scancodeio_workflow`.
 
 .. toctree::
     :maxdepth: 2
@@ -72,13 +73,14 @@ New to DejaCode? Start with the :ref:`quickstart`.
     :maxdepth: 1
     :caption: Reference
 
+    reference-scancodeio-workflow
     reference-data-models
-    reference-vulnerability-management
+    reference-package-url
+    reference-license-clarity
     reference-policy-rules
+    reference-vulnerability-management
     reference-vulnerability-triage
-    reference-1
-    reference-2
-    reference-3-cravex
+    reference-cra-support
 
 .. toctree::
     :maxdepth: 1

docs/index.rst

@@ -63,6 +63,9 @@ With ScanCode.io, you can:
 Scans are listed from :guilabel:`Scans` in the :guilabel:`Integrations` section of the
 side menu.
 
+.. seealso::
+    :ref:`reference_scancodeio_workflow` for the complete workflow with ScanCode.io.
+
 Install your own ScanCode.io server
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/integrations-aboutcode.rst

@@ -84,6 +84,8 @@ First steps
 Next steps
 ----------
 
+- :ref:`reference_scancodeio_workflow` describes how DejaCode and ScanCode.io work
+  together.
 - :ref:`user_tutorial_1` and the following tutorials walk through each feature in
   detail.
 - :ref:`dataspace` explains how to set up your own Dataspace, users, and usage

docs/quickstart.rst

@@ -1,4 +1,4 @@
-.. _reference_3_cravex:
+.. _reference_cra_support:
 
 Cyber Resilience Act (CRA) Support
 ==================================

docs/reference-3-cravex.rst docs/reference-cra-support.rstdocs/reference-3-cravex.rst renamed to docs/reference-cra-support.rst

@@ -1,4 +1,4 @@
-.. _reference_1:
+.. _reference_license_clarity:
 
 Declared License Expression and License Clarity Scoring
 =======================================================

docs/reference-1.rst docs/reference-license-clarity.rstdocs/reference-1.rst renamed to docs/reference-license-clarity.rst

@@ -1,4 +1,4 @@
-.. _reference_2:
+.. _reference_package_url:
 
 Package URL (purl)
 ==================

docs/reference-2.rst docs/reference-package-url.rstdocs/reference-2.rst renamed to docs/reference-package-url.rst

@@ -0,0 +1,120 @@
+.. _reference_scancodeio_workflow:
+
+ScanCode.io and DejaCode Compliance Workflow
+============================================
+
+**ScanCode.io detects what is in your code. DejaCode records what you decide about it.**
+
+ScanCode.io analyzes one codebase at a time. DejaCode manages the compliance of all your
+Products over time.
+
+This page covers how the two work together. For everything else that DejaCode does, such
+as the License Library, Workflow Requests, and Reporting, see the
+:doc:`DejaCode documentation index <index>`.
+
+.. image:: images/reference-scancodeio-workflow/workflow.svg
+   :width: 100%
+   :alt: DejaCode shares the license policies with ScanCode.io (1), imports the Product
+         inventory detected by ScanCode.io (2), and requests Package scans (3). DejaCode
+         then supports the review (4), delivery (5), and maintenance (6) of the Product.
+
+Each number in the diagram is a step of the workflow, described below.
+
+1. Set Up
+---------
+
+- Enable the ScanCode.io, VulnerableCode, and PurlDB integrations, see
+  :ref:`integrations_aboutcode`.
+- Define your usage policies, see :ref:`how_to_1`.
+- Share your license policies with ScanCode.io, which then flags each detected license
+  with your compliance alerts, see :ref:`how_to_1_export_license_policies`.
+- Activate your policy rules, see :ref:`reference_policy_rules`.
+- Create a Product for each version of the software that you distribute, see
+  :ref:`user_tutorial_1`.
+
+2. Discover the Inventory
+-------------------------
+
+Choose the import action from the :guilabel:`Actions` dropdown of the Product, according
+to what you have:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 35 35
+
+   * - You have
+     - Action
+     - ScanCode.io pipeline
+   * - An SBOM (CycloneDX, SPDX)
+     - :guilabel:`Import SBOM`
+     - ``load_sbom``, run by DejaCode
+   * - Package manifests or lockfiles
+     - :guilabel:`Import Package manifests`
+     - ``resolve_dependencies``, run by DejaCode
+   * - A ScanCode.io project
+     - :guilabel:`Import ScanCode.io project`
+     - Any pipeline, already run
+   * - A ScanCode scan results file
+     - :guilabel:`Import ScanCode scan results`
+     - None: the file is imported as is
+
+For an in-depth analysis, run the pipelines in ScanCode.io, then import the project: it
+brings the Packages, their dependencies, and their vulnerabilities. With the
+``find_vulnerabilities`` and ``analyze_symbols_reachability`` pipelines, it also brings
+the reachability of each vulnerability.
+
+Imports run in the background, follow them on the :guilabel:`Activity` tab of the
+Product. A Package that already exists in your Dataspace keeps its curated data.
+
+3. Enrich the Packages
+----------------------
+
+The discovery identifies the Packages and their declared licenses. A scan of each
+Package goes further: it detects the licenses and copyrights in its files.
+
+- :guilabel:`Scan all Packages` sends each Package of the Product with a download URL to
+  ScanCode.io.
+- On the :guilabel:`Scan` tab of a Package, apply the detected values to its definition,
+  see :ref:`reference_license_clarity`.
+- :guilabel:`Improve Packages from PurlDB` completes the Package metadata.
+
+A Package is scanned and reviewed once, and every Product that uses it benefits.
+
+4. Review
+---------
+
+- Set the review status and concluded license of each Package in the Product, see
+  :ref:`user_tutorial_5_sboms`.
+- Resolve the policy violations, see :ref:`reference_policy_rules`.
+- Triage the vulnerabilities, see :ref:`how_to_4`. The reachability imported from
+  ScanCode.io is a starting point.
+
+5. Deliver
+----------
+
+Export from the reviewed Product. Unlike the ScanCode.io outputs, built from the scan
+results, these documents reflect your review decisions.
+
+- **SBOM** (CycloneDX, SPDX), see :ref:`user_tutorial_5_sboms`.
+- **VEX**, see :ref:`user_tutorial_6_vuln_report`.
+- **Attribution**, see :ref:`user_tutorial_1`.
+
+6. Maintain
+-----------
+
+- **New release**: clone the Product, then import the new release. The clone keeps the
+  inventory and its review. Imports only add Packages: remove the ones that are no
+  longer in the release.
+- **New vulnerabilities**: DejaCode refreshes them daily by default and can notify you,
+  see :ref:`reference_vulnerability_management`.
+
+Automate
+--------
+
+Each import action is available on the Product endpoint of the REST API:
+``load_sboms``, ``import_manifests``, ``pull_scancodeio_project_data``, and
+``import_from_scan``. See :ref:`integrations_rest_api`.
+
+The ScanCode.io tutorial `Analyze Codebase End to End with DepLock and DejaCode
+<https://scancodeio.readthedocs.io/en/latest/tutorial_cli_end_to_end_scanning_to_dejacode.html>`_
+shows a complete example.

docs/reference-scancodeio-workflow.rst

@@ -62,3 +62,7 @@ as for an imported SBOM, in :ref:`user_tutorial_5_sboms`:
 1. :ref:`user_tutorial_5_review_vulnerabilities`
 2. :ref:`user_tutorial_5_vulnerability_analysis`
 3. :ref:`user_tutorial_5_export_vex`
+
+.. seealso::
+    :ref:`reference_scancodeio_workflow` to use ScanCode.io and DejaCode together beyond
+    a one-time import.