From 3113e0fda1fe7841b4b950ae8da7b822d56b1618 Mon Sep 17 00:00:00 2001 From: Matias Daloia Date: Fri, 15 Nov 2024 14:02:58 +0100 Subject: [PATCH] Add scanoss settings schema docs --- .gitignore | 2 +- docs/assets/scanoss-settings-schema.json | 132 +++++++++++++++++ docs/source/conf.py | 29 +++- docs/source/index.rst | 2 + docs/source/scanoss_settings_schema.rst | 175 +++++++++++++++++++++++ 5 files changed, 332 insertions(+), 8 deletions(-) create mode 100644 docs/assets/scanoss-settings-schema.json create mode 100644 docs/source/scanoss_settings_schema.rst diff --git a/.gitignore b/.gitignore index a0cb5a6..8f6bbb3 100644 --- a/.gitignore +++ b/.gitignore @@ -27,5 +27,5 @@ docs/build .devcontainer/devcontainer.json !.devcontainer/*.example.json - !tests/data/*.json +!docs/assets/*.json diff --git a/docs/assets/scanoss-settings-schema.json b/docs/assets/scanoss-settings-schema.json new file mode 100644 index 0000000..b47beec --- /dev/null +++ b/docs/assets/scanoss-settings-schema.json @@ -0,0 +1,132 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "title": "Scanoss Settings", + "type": "object", + "properties": { + "self": { + "type": "object", + "description": "Description of the project under analysis", + "properties": { + "name": { + "type": "string", + "description": "Name of the project" + }, + "license": { + "type": "string", + "description": "License of the project" + }, + "description": { + "type": "string", + "description": "Description of the project" + } + } + }, + "bom": { + "type": "object", + "description": "BOM Rules: Set of rules that will be used to modify the BOM before and after the scan is completed", + "properties": { + "include": { + "type": "array", + "description": "Set of rules to be added as context when scanning. This list will be sent as payload to the API.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "File path", + "examples": ["/path/to/file", "/path/to/another/file"], + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "purl": { + "type": "string", + "description": "Package URL to be used to match the component", + "examples": [ + "pkg:npm/vue@2.6.12", + "pkg:golang/github.com/golang/go@1.17.3" + ] + }, + "comment": { + "type": "string", + "description": "Additional notes or comments" + } + }, + "uniqueItems": true, + "required": ["purl"] + } + }, + "remove": { + "type": "array", + "description": "Set of rules that will remove files from the results file after the scan is completed.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "File path", + "examples": ["/path/to/file", "/path/to/another/file"] + }, + "purl": { + "type": "string", + "description": "Package URL", + "examples": [ + "pkg:npm/vue@2.6.12", + "pkg:golang/github.com/golang/go@1.17.3" + ] + }, + "comment": { + "type": "string", + "description": "Additional notes or comments" + } + }, + "uniqueItems": true, + "required": ["purl"] + } + }, + "replace": { + "type": "array", + "description": "Set of rules that will replace components with the specified one after the scan is completed.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "File path", + "examples": ["/path/to/file", "/path/to/another/file"] + }, + "purl": { + "type": "string", + "description": "Package URL to replace", + "examples": [ + "pkg:npm/vue@2.6.12", + "pkg:golang/github.com/golang/go@1.17.3" + ] + }, + "comment": { + "type": "string", + "description": "Additional notes or comments" + }, + "license": { + "type": "string", + "description": "License of the component. Should be a valid SPDX license expression", + "examples": ["MIT", "Apache-2.0"] + }, + "replace_with": { + "type": "string", + "description": "Package URL to replace with", + "examples": [ + "pkg:npm/vue@2.6.12", + "pkg:golang/github.com/golang/go@1.17.3" + ] + } + }, + "uniqueItems": true, + "required": ["purl", "replace_with"] + } + } + } + } + } +} diff --git a/docs/source/conf.py b/docs/source/conf.py index 9d25efb..b081422 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -6,23 +6,38 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'Documentation for scanoss-py' -copyright = '2024, Scan Open Source Solutions SL' -author = 'Scan Open Source Solutions SL' +import os +import shutil + +project = "Documentation for scanoss-py" +copyright = "2024, Scan Open Source Solutions SL" +author = "Scan Open Source Solutions SL" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [] -templates_path = ['_templates'] +templates_path = ["_templates"] exclude_patterns = [] +def setup(): + if not os.path.exists("_static"): + os.makedirs("_static") + + schema_path = os.path.join("..", "asets", "scanoss-settings-schema.json") + if os.path.exists(schema_path): + shutil.copy2(schema_path, "_static/scanoss-settings-schema.json") + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'furo' -html_logo = 'scanosslogo.png' -html_static_path = ['_static'] +html_theme = "furo" +html_logo = "scanosslogo.png" +html_static_path = ["_static"] + +html_context = { + "schema_url": "https://scanoss.readthedocs.io/en/latest/_static/scanoss-settings-schema.json" +} diff --git a/docs/source/index.rst b/docs/source/index.rst index 308f2ce..3d855bd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -46,6 +46,8 @@ To enable dependency scanning, an extra tool is required: scancode-toolkit. To install it run: ``pip3 install -r requirements-scancode.txt`` +.. include:: scanoss_settings_schema.rst + Commands and arguments ====================== diff --git a/docs/source/scanoss_settings_schema.rst b/docs/source/scanoss_settings_schema.rst new file mode 100644 index 0000000..1b0bccb --- /dev/null +++ b/docs/source/scanoss_settings_schema.rst @@ -0,0 +1,175 @@ +Settings File +====================== + +SCANOSS provides a settings file to customize the scanning process. The settings file is a JSON file that contains project information and BOM (Bill of Materials) rules. It allows you to include, remove, or replace components in the BOM before and after scanning. + +The schema is available at: ``https://.readthedocs.io/en/latest/_static/schema.json`` + +Schema Overview +------------- + +The settings file consists of two main sections: + +Project Information +----------------- + +The ``self`` section contains basic information about the your project: + +.. code-block:: json + + { + "self": { + "name": "my-project", + "license": "MIT", + "description": "Project description" + } + } + +BOM Rules +--------- + +The ``bom`` section defines rules for modifying the BOM before and after scanning. It contains three main operations: + +1. Include Rules +~~~~~~~~~~~~~~ + +Rules for adding context when scanning. These rules will be sent to the SCANOSS API meaning they have more chance of being considered part of the resulting scan. + +.. code-block:: json + + { + "bom": { + "include": [ + { + "path": "/path/to/file", + "purl": "pkg:npm/vue@2.6.12", + "comment": "Optional comment" + } + ] + } + } + +2. Remove Rules +~~~~~~~~~~~~~ + +Rules for removing files from results after scanning. These rules will be applied to the results file after scanning. The post processing happens on the client side. + +.. code-block:: json + + { + "bom": { + "remove": [ + { + "path": "/path/to/file", + "purl": "pkg:npm/vue@2.6.12", + "comment": "Optional comment" + } + ] + } + } + +3. Replace Rules +~~~~~~~~~~~~~~ + +Rules for replacing components after scanning. These rules will be applied to the results file after scanning. The post processing happens on the client side. + +.. code-block:: json + + { + "bom": { + "replace": [ + { + "path": "/path/to/file", + "purl": "pkg:npm/vue@2.6.12", + "replace_with": "pkg:npm/vue@2.6.14", + "license": "MIT", + "comment": "Optional comment" + } + ] + } + } + +Important Notes +------------- + +Matching Rules +~~~~~~~~~~~~ + +1. **Full Match**: Requires both PATH and PURL to match. It means the rule will be applied ONLY to the specific file with the matching PURL and PATH. +2. **Partial Match**: Matches based on either: + - File path only (PURL is optional). It means the rule will be applied to all files with the matching path. + - PURL only (PATH is optional). It means the rule will be applied to all files with the matching PURL. + + +File Paths +~~~~~~~~~ + +- All paths should be specified relative to the scanned directory +- Use forward slashes (``/``) as path separators + +Given the following example directory structure: +.. code-block:: text + + project + ├── src + │ └── component.js + └── lib + └── utils.py + +- If the scanned directory is ``/project/src``, then: + - ``component.js`` is a valid path + - ``lib/utils.py`` is an invalid path and will not match any files +- If the scanned directory is ``/project``, then: + - ``src/component.js`` is a valid path + - ``lib/utils.py`` is a valid path + +Package URLs (PURLs) +~~~~~~~~~~~~~~~~~~ + +PURLs must follow the Package URL specification: + +- Format: ``pkg://@`` +- Examples: + - ``pkg:npm/vue@2.6.12`` + - ``pkg:golang/github.com/golang/go@1.17.3`` +- Must be valid and include all required components +- Version is strongly recommended but optional + +Example Configuration +------------------- + +Here's a complete example showing all sections: + +.. code-block:: json + + { + "self": { + "name": "example-project", + "license": "Apache-2.0", + "description": "Example project configuration" + }, + "bom": { + "include": [ + { + "path": "src/lib/component.js", + "purl": "pkg:npm/lodash@4.17.21", + "comment": "Include lodash dependency" + } + ], + "remove": [ + { + "purl": "pkg:npm/deprecated-pkg@1.0.0", + "comment": "Remove deprecated package" + } + ], + "replace": [ + { + "path": "src/utils/helper.js", + "purl": "pkg:npm/old-lib@1.0.0", + "replace_with": "pkg:npm/new-lib@2.0.0", + "license": "MIT", + "comment": "Upgrade to newer version" + } + ] + } + } \ No newline at end of file