Settings File ====================== .. warning:: **Deprecated** — This documentation is no longer maintained here. The settings schema and its documentation have moved to the `scanoss/schema `_ repository. Please refer to the `interactive docs `_ or the `canonical JSON Schema `_ for the latest version. 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 to download :download:`here ` Schema Overview --------------- The settings file consists of two main sections: Project Information ------------------- The ``self`` section contains basic information about your project: .. code-block:: json { "self": { "name": "my-project", "license": "MIT", "description": "Project description" } } Settings ======== The ``settings`` object allows you to configure various aspects of the scanning process. Currently, it provides control over which files should be skipped during scanning through the ``skip`` property. Skip Configuration ------------------ The ``skip`` object lets you define rules for excluding files from being scanned or fingerprinted. This can be useful for improving scan performance and avoiding unnecessary processing of certain files. Properties ~~~~~~~~~~ skip.patterns.scanning ^^^^^^^^^^^^^^^^^^^^^^ A list of patterns that determine which files should be skipped during scanning. The patterns follow the same format as ``.gitignore`` files. For more information, see the `gitignore patterns documentation `_. :Type: Array of strings :Required: No :Example: .. code-block:: json { "settings": { "skip": { "patterns": { "scanning": [ "*.log", "!important.log", "temp/", "debug[0-9]*.txt", "src/client/specific-file.js", "src/nested/folder/" ] } } } } skip.patterns.fingerprinting ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A list of patterns that determine which files should be skipped during fingerprinting. The patterns follow the same format as ``.gitignore`` files. For more information, see the `gitignore patterns documentation `_. :Type: Array of strings :Required: No :Example: .. code-block:: json { "settings": { "skip": { "patterns": { "fingerprinting": [ "*.log", "!important.log", "temp/", "debug[0-9]*.txt", "src/client/specific-file.js", "src/nested/folder/" ] } } } } skip.sizes.scanning ^^^^^^^^^^^^^^^^^^^ Rules for skipping files based on their size during scanning. :Type: Object :Required: No :Properties: * ``patterns`` (array of strings): List of glob patterns to apply the min/max size rule * ``min`` (integer): Minimum file size in bytes * ``max`` (integer): Maximum file size in bytes (Required) :Example: .. code-block:: json { "settings": { "skip": { "sizes": { "scanning": [ { "patterns": [ "*.log", "!important.log", "temp/", "debug[0-9]*.txt", "src/client/specific-file.js", "src/nested/folder/" ], "min": 100, "max": 1000000 } ] } } } } skip.sizes.fingerprinting ^^^^^^^^^^^^^^^^^^^^^^^^^ Rules for skipping files based on their size during fingerprinting. :Type: Object :Required: No :Properties: * ``patterns`` (array of strings): List of glob patterns to apply the min/max size rule * ``min`` (integer): Minimum file size in bytes * ``max`` (integer): Maximum file size in bytes (Required) :Example: .. code-block:: json { "settings": { "skip": { "sizes": { "fingerprinting": [ { "patterns": [ "*.log", "!important.log", "temp/", "debug[0-9]*.txt", "src/client/specific-file.js", "src/nested/folder/" ], "min": 100, "max": 1000000 } ] } } } } Pattern Format Rules '''''''''''''''''''' * Patterns are matched **relative to the scan root directory** * A trailing slash indicates a directory (e.g., ``path/`` matches only directories) * An asterisk ``*`` matches anything except a slash * Two asterisks ``**`` match zero or more directories (e.g., ``path/**/folder`` matches ``path/to``, ``path/to/folder``, ``path/to/folder/b``) * Range notations like ``[0-9]`` match any character in the range * Question mark ``?`` matches any single character except a slash Examples with Explanations '''''''''''''''''''''''''' .. code-block:: none # Match all .txt files *.txt # Match all .log files except important.log *.log !important.log # Match all files in the build directory build/ # Match all .pdf files in docs directory and its subdirectories docs/**/*.pdf # Match files like test1.js, test2.js, etc. test[0-9].js Scan Tuning Parameters ---------------------- The SCANOSS scan engine supports tuning parameters for snippet matching. These parameters allow you to fine-tune how the scanner identifies code snippets in your repository. .. list-table:: :header-rows: 1 :widths: 20 15 10 55 * - Parameter - Type - Default - Description * - ``min_snippet_hits`` - ``integer`` - ``0`` - Minimum snippet hits required. ``0`` defers to server configuration. * - ``min_snippet_lines`` - ``integer`` - ``0`` - Minimum snippet lines required. ``0`` defers to server configuration. * - ``ranking_enabled`` - ``boolean | null`` - ``null`` - Enable/disable result ranking. ``null`` defers to server configuration. * - ``ranking_threshold`` - ``integer | null`` - ``0`` - Ranking threshold value (``-1`` to ``10``). ``-1`` defers to server configuration. * - ``honour_file_exts`` - ``boolean | null`` - ``true`` - Honour file extensions during matching. ``null`` defers to server configuration. Example Configuration ~~~~~~~~~~~~~~~~~~~~~ Add the ``file_snippet`` section to your ``scanoss.json`` file: .. code-block:: json { "settings": { "file_snippet": { "min_snippet_hits": 3, "min_snippet_lines": 5, "ranking_enabled": true, "ranking_threshold": 5, "honour_file_exts": true } } } Complete Example ------------------- Here's a comprehensive example combining pattern and size-based skipping: .. code-block:: json { "settings": { "skip": { "patterns": { "scanning": [ "# Node.js dependencies", "node_modules/", "# Build outputs", "dist/", "build/" ], "fingerprinting": [ "# Logs except important ones", "*.log", "!important.log", "# Temporary files", "temp/", "*.tmp", "# Debug files with numbers", "debug[0-9]*.txt", "# All test files in any directory", "**/*test.js" ] }, "sizes": { "scanning": [ { "patterns": [ "*.log", "!important.log" ], "min": 512, "max": 5242880 } ], "fingerprinting": [ { "patterns": [ "temp/", "*.tmp", "debug[0-9]*.txt", "src/client/specific-file.js", "src/nested/folder/" ], "min": 512, "max": 5242880 } ] } } } } 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" }, "settings": { "skip": { "patterns": { "scanning": [ "node_modules/", "dist/", "build/", ], "fingerprinting": [ "*.log", "!important.log", "temp/", "*.tmp", "debug[0-9]*.txt", "**/*test.js" ] }, "sizes": { "scanning": [ { "patterns": [ "*.log", "!important.log", ], "min": 512, "max": 5242880 } ], "fingerprinting": [ { "patterns": [ "temp/", "debug[0-9]*.txt", "src/client/specific-file.js", "src/nested/folder/" ], "min": 512, "max": 5242880 } ] } }, "file_snippet": { "min_snippet_hits": 3, "min_snippet_lines": 5, "ranking_enabled": true, "ranking_threshold": 5, "honour_file_exts": true } }, "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" } ] } } Usage ----- You can pass the settings file path as an argument to the CLI .. code-block:: bash $ scanoss-py scan . --settings /path/to/settings.json If no settings file is provided, the default settings file will be used. The default location for the settings file is ``scanoss.json`` in the current working directory. If this file does not exist, settings will be omitted. You can also skip the default settings file: .. code-block:: bash $ scanoss-py scan . --skip-settings-file