# Dependency Scanner ## Table of Contents 1. [Purpose](#purpose) 2. [Quick Start](#quick_start) 3. [Usage](#usage) 4. [Vulnerability Data Structure](#vulnerability_data_structure) 5. [How to generate SBOM for a software project](#generate_sbom_for_a_software_project) ### Purpose The **Dependency Scanner** (DS) is a useful tool to collect and analyze the dependencies of a software project. Aimed at identifying issues related to software supply-chain security. Dependencies are components or packages used in software that will be analyzed for known vulnerabilities or evidence of malware. ### Quick Start Use the following command to generate a list of both direct and indirect dependencies used within your project and identify potentially risky dependencies. Then upload them to the Xygeni Platform for review. ``` xygeni deps -n MyProject --format=text --upload ``` ``` Running xygeni... 2022-11-15 11:11:25.914 [main] INFO com.depsdoctor.cli.commands.ScanDepsCommand - Scan statistics: {"elapsedTime":"00:00:39.632","files":150,"filesByKind":{"Jar Analyzer":150}, "dependencies":122,"depsByEcosystem":{"jar":121,"unknown":1}} Dependencies found: 122 ┌───┬──────────────────────────────────────────────────┬─────────┬────────┬────────────┬─────┐ │Id │Group:Name:Version │Ecosystem│Language│ License │Flags│ ├───┼──────────────────────────────────────────────────┼─────────┼────────┼────────────┼─────┤ │1 │org.apache.logging.log4j:log4j-slf4j-impl:2.19.0 │ jar │ java │ Apache-2.0 │ │ ├───┼──────────────────────────────────────────────────┼─────────┼────────┼────────────┼─────┤ │2 │com.vdurmont:semver4j:3.1.0 │ jar │ java │ MIT │ │ ├───┼──────────────────────────────────────────────────┼─────────┼────────┼────────────┼─────┤ │3 │org.slf4j:slf4j-api:1.7.36 │ jar │ java │ │ │ ├───┼──────────────────────────────────────────────────┼─────────┼────────┼────────────┼─────┤ │4 │org.apache.logging.log4j:log4j-core:2.19.0 │ jar │ java │ Apache-2.0 │ │ ├───┼──────────────────────────────────────────────────┼─────────┼────────┼────────────┼─────┤ │5 │org.zeroturnaround:zt-exec:1.12 │ jar │ java │ Apache-2.0 │ │ ├───┼──────────────────────────────────────────────────┼─────────┼────────┼────────────┼─────┤ ... ├───┼──────────────────────────────────────────────────┼─────────┼────────┼────────────┼─────┤ │140│com.fasterxml.jackson.datatype:jackson-datatype-js│ jar │ java │ Apache-2.0 │ │ │ │r310:2.13.3 │ │ │ │ │ ├───┼──────────────────────────────────────────────────┼─────────┼────────┼────────────┼─────┤ │150│com.squareup.okhttp3:okhttp:4.10.0 │ jar │ java │ Apache-2.0 │ │ ├───┼──────────────────────────────────────────────────┼─────────┼────────┼────────────┼─────┤ │157│com.diogonunes:JColor:5.2.0 │ jar │ java │ MIT │ │ ├───┼──────────────────────────────────────────────────┼─────────┼────────┼────────────┼─────┤ │0 │:test: │ unknown │ │ │ RV │ └───┴──────────────────────────────────────────────────┴─────────┴────────┴────────────┴─────┘ Flags: R=top-level P=project V=virtual D=direct dependency ``` {% hint style="info" %} The Open Source Dependencies scanner can be launched in two different ways: * Running its own specific command ( `xygeni deps [options]` ) * Running the general command ( `xygeni scan --run="deps" [options]` ) {% endhint %} ### Usage The Open Source Dependencies Scanner is launched using the `xygeni deps [options]` command. To view all available options, use the `--help` flag: ```bash xygeni deps --help ``` The most important properties are: * **Name** of the Xygeni Project `-n` or `--name`. * **Input source** to analyze. Either specify a **directory** with: `-d` or `--dir` or specify a **repository** using: `--repo`. The scan will analyze the current working directory when no target is specified. * **Upload** results to the service `--upload`. By default, results are not uploaded. * **Output file** (`-o` or `--output`) and **format** (`-f` or `--format`). If no output file is specified (or stdout / - are used), the standard output is used. Use `--format=none` for no output. * SBOM properties: output file `--sbom` and format `--sbom-format`. See [Generate SBOM for a software project](https://docs.xygeni.io/xydocs/dependencies/DependencyScanner.html#_generate_sbom_for_a_software_project) for an example. * Specify what detectors to run with the `--detectors` / `--skip-detectors` options. A common use-case is to consider only issues with high or critical severity with `--detectors=high`. * Resolve vulnerabilities using the `--include-vulnerabilities` option. This will retrieve known vulnerabilities for all dependencies and include them in the dependency report. By default, vulnerabilities are resolved on the server side and can be managed through the Xygeni console. This way, vulnerabilities are also exported in the dependency report and could be read by third parties. * Using `--include-license-analysis` includes all licenses for all components and dependencies licenses in the JSON output ### Vulnerability Data Structure When using the `--include-vulnerabilities` option, the dependency scanner retrieves known vulnerabilities for all dependencies and includes them as children of each dependency in the output. Each vulnerability follows a structured format with the following fields: #### Vulnerability Fields * **`id`**: The unique identifier for the vulnerability (e.g., `CVE-2019-1010266`) * **`source`**: Information about the vulnerability source * `name`: The name of the vulnerability database (e.g., `NVD`) * `url`: The URL to the vulnerability details * **`references`**: Additional reference URLs (can be `null`) * **`ratings`**: Array of vulnerability severity ratings using different scoring methods * `score`: The numerical CVSS score (e.g., `4.0`, `6.5`) * `severity`: The severity level (e.g., `MEDIUM`) * `method`: The CVSS version used (e.g., `CVSSV2`, `CVSSV31`) * `vector`: The CVSS vector string * `justification`: Explanation for the rating (can be `null`) * **`cwes`**: Array of Common Weakness Enumeration (CWE) identifiers (e.g., `["CWE-400", "CWE-770"]`) * **`description`**: Detailed description of the vulnerability * **`detail`**: Additional vulnerability details (can be `null`) * **`created`**: When the vulnerability record was created (can be `null`) * **`published`**: When the vulnerability was publicly disclosed (ISO 8601 format) * **`updated`**: When the vulnerability record was last updated (ISO 8601 format) * **`rejected`**: Whether the vulnerability was rejected (can be `null`) * **`advisories`**: Array of advisory information * `title`: Advisory title (can be `null`) * `url`: URL to the advisory * **`versions`**: Information about affected versions * `startVersion`: The earliest affected version * `versionStartExcluded`: Whether the start version is excluded from the range * `endVersion`: The latest affected version (can be `null`) * `versionEndExcluded`: Whether the end version is excluded from the range #### Example Vulnerability Structure ```json { "id": "CVE-2019-1010266", "source": { "name": "NVD", "url": "https://nvd.nist.gov/vuln/detail/CVE-2019-1010266" }, "references": null, "ratings": [ { "score": 4.0, "severity": "MEDIUM", "method": "CVSSV2", "vector": "AV:N/AC:L/Au:S/C:N/I:N/A:P", "justification": null }, { "score": 6.5, "severity": "MEDIUM", "method": "CVSSV31", "vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:N/I:N/A:H", "justification": null } ], "cwes": ["CWE-400", "CWE-770"], "description": "lodash prior to 4.17.11 is affected by: CWE-400: Uncontrolled Resource Consumption. The impact is: Denial of service. The component is: Date handler. The attack vector is: Attacker provides very long strings, which the library attempts to match using a regular expression. The fixed version is: 4.17.11.", "detail": null, "created": null, "published": "2019-07-17T19:15:11.000+00:00", "updated": "2020-09-30T11:40:44.000+00:00", "rejected": null, "advisories": [ { "title": null, "url": "https://github.com/lodash/lodash/issues/3359" }, { "title": null, "url": "https://github.com/lodash/lodash/wiki/Changelog" }, { "title": null, "url": "https://security.netapp.com/advisory/ntap-20190919-0004/" }, { "title": null, "url": "https://snyk.io/vuln/SNYK-JS-LODASH-73639" } ], "versions": [ { "startVersion": "0", "versionStartExcluded": false, "endVersion": null, "versionEndExcluded": false } ] } ``` ### How to generate SBOM for a software project A **Software Bill Of Materials (SBOM)** is an inventory that details the components, including direct and indirect dependencies, along with their relationships and relevant metadata. The `xygeni deps` can be used to generate the SBOM, in the following formats: * [CycloneDX](https://cyclonedx.org/), a lightweight Software Bill of Materials (SBOM) standard designed for use in application security contexts and supply chain component analysis.. * [SPDX](https://spdx.dev/), The Software Package Data Exchange open standard (ISO/IEC 5962:2021). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.xygeni.io/xygeni-products/open-source-security-oss/dependency-scanner.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.