diff --git a/docs/built-in-pipelines.rst b/docs/built-in-pipelines.rst index 13f8ffda71..644f81ee03 100644 --- a/docs/built-in-pipelines.rst +++ b/docs/built-in-pipelines.rst @@ -48,6 +48,14 @@ Analyze Docker Windows Image .. _pipeline_benchmark_purls: +Analyze Symbol Reachability +---------------------------- +.. autoclass:: scanpipe.pipelines.analyze_symbols_reachability.SymbolReachability() + :members: + :member-order: bysource + +.. _analyze_symbols_reachability: + Benchmark PURLs (addon) ----------------------- diff --git a/docs/images/tutorial-web-ui-analyze-symbol-reachability.png b/docs/images/tutorial-web-ui-analyze-symbol-reachability.png new file mode 100644 index 0000000000..349abf3bbb Binary files /dev/null and b/docs/images/tutorial-web-ui-analyze-symbol-reachability.png differ diff --git a/docs/index.rst b/docs/index.rst index 7149a5cfe7..4a16a2ebbe 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -47,6 +47,7 @@ Learn via practical step-by-step guides. - :ref:`tutorial_vulnerablecode_integration` - :ref:`tutorial_web_ui_symbol_and_string_collection` - :ref:`tutorial_cli_end_to_end_scanning_to_dejacode` +- :ref:`tutorial_analyze_symbols_reachability` .. rst-class:: column column2 bottom-left @@ -116,6 +117,7 @@ Indices and tables tutorial_vulnerablecode_integration tutorial_web_ui_symbol_and_string_collection tutorial_cli_end_to_end_scanning_to_dejacode + tutorial_analyze_symbols_reachability scanpipe-concepts built-in-pipelines custom-pipelines diff --git a/docs/scanpipe-pipes.rst b/docs/scanpipe-pipes.rst index f7485ab01e..c090256eb2 100644 --- a/docs/scanpipe-pipes.rst +++ b/docs/scanpipe-pipes.rst @@ -134,3 +134,8 @@ Windows ------- .. automodule:: scanpipe.pipes.windows :members: + +Reachability +------------- +.. automodule:: scanpipe.pipes.reachability + :members: diff --git a/docs/tutorial_analyze_symbols_reachability.rst b/docs/tutorial_analyze_symbols_reachability.rst new file mode 100644 index 0000000000..a972c2aea5 --- /dev/null +++ b/docs/tutorial_analyze_symbols_reachability.rst @@ -0,0 +1,106 @@ +.. _tutorial_analyze_symbols_reachability: + +Analyze Symbol Reachability +=========================== + +In this tutorial, we will introduce the add-on pipeline that can be used to +analyze symbols reachability from codebase resources. + +Requirements +------------ + +To successfully complete this tutorial, you first need to: + +- Install **ScanCode.io** locally :ref:`installation`. +- Have an existing project resource affected + by a vulnerability advisory that has a corresponding fix commit. +- Run the ``find_vulnerabilities`` pipeline :ref:`tutorial_vulnerablecode_integration`. + +Reachability Status +------------------- + +The reachability status can have one of the following values: + +- ``REACHABLE``: "yes" + (We found evidence that the vulnerable symbol is reachable and the vulnerable code exists.) +- ``UNKNOWN``: "unknown" + (We cannot determine reachability with confidence.) +- ``NOT_REACHABLE``: "no" + (We found evidence that the vulnerable symbol is not reachable.) + + +Run the ``analyze_symbols_reachability`` pipeline +------------------------------------------------- + +- Open any existing project containing a few resources. +- Click the **"Add pipeline"** button and select the **"analyze_symbols_reachability"** + pipeline from the dropdown list. +- Select **"Execute pipeline now"** and click **"Add pipeline"** to start the + reachability analysis. +- Once the pipeline run completes successfully, you can reach the **Resources** list view + by clicking the count number under the **"RESOURCES"** header. +- Click on one of the affected code files and navigate to + the **Extra** tab to view the ``symbols_reachability``. + +.. image:: images/tutorial-web-ui-analyze-symbol-reachability.png + +- The pipeline output also includes a JSON file containing the reachability + status for each advisory and resource, including the overall reachability + status (e.g., ``reachability-2026-08-18-15-12-51.json``). + +.. code-block:: json + :emphasize-lines: 2 + + { + "purl": "pkg:pypi/b2sdk@1.14.0", + "advisories": [ + { + "advisory_uid": "pypa/b2sdk/PYSEC-2022-33", + "is_reachable": "yes", + "details": [ + { + "resource_path": "b2sdk-1.14.0/b2sdk/account_info/sqlite_account_info.py", + "patch": { + "vcs_url": "https://github.com/backblaze/b2-sdk-python", + "commit_hash": "62476638986e5b6d7459aca5ef8ce220760226e0" + }, + "is_reachable": "yes", + "tool_details": [ + { + "symbol_name": "SqliteAccountInfo._create_database", + "is_called": true, + "is_defined": true, + "is_imported": false, + "is_exact": true, + "reachable_from": [ + "SqliteAccountInfo._validate_database" + ] + }, + { + "symbol_name": "SqliteAccountInfo", + "is_called": false, + "is_defined": true, + "is_imported": false, + "is_exact": true, + "reachable_from": [] + } + ], + "vulnerable_symbols": [ + "SqliteAccountInfo", + "SqliteAccountInfo._create_database" + ], + "fixed_symbols": [ + "SqliteAccountInfo", + "SqliteAccountInfo._create_database" + ] + }, + // ... more details + ] + } + } + +.. note:: + An advisory is considered ``REACHABLE`` if it is reachable through at least + one resource. If no resource is ``REACHABLE`` and at least one result is + ``UNKNOWN``, the advisory status is ``UNKNOWN``. Otherwise, its status is + ``NOT_REACHABLE``.