The ts-scan scanner is a powerful command-line tool designed for scanning package dependencies, generating Software Bill of Materials (SBOM) files, and analyzing existing SBOMs for security and compliance insights. It supports multiple SBOM formats, including SPDX and CycloneDX, allowing users to integrate it seamlessly into their software supply chain workflows.
The ts-scan scans a project for dependencies and stores the results using either its internal format or one of the supported SBOM formats: SPDX or CycloneDX. It currently supports PyPI, Maven, Gradle, NuGet, NPM, Composer (PHP), Cargo, Go, Dart/Flutter, Swift Package Manager, CocoaPods, and classic Visual Basic 6 projects, and can also utilize Syft as a backend allowing it to scan Docker containers.
Once dependencies are collected, the ts-scan can be used to either upload results to the TrustSource application, perform security analysis of components by identifying known vulnerabilities, or conduct an in-depth analysis of each package. The goal of the in-depth analysis is to extract license and copyright information, detect cryptographic algorithms, identify code snippets, or detect malware by applying its own analyzers or integrating with external tools such as scancode-toolkit, SCANOSS, and YARA.
The ts-scan can be seamlessly integrated into CI/CD pipelines, enabling automated security and compliance checks continuously. It can be configured to break a build if vulnerabilities or legal issues are detected, ensuring compliance early in the development process. Additionally, it can be used alongside SCM hooks on developers' machines for pre-commit checks or execute long-running in-depth analyses remotely during release builds.
ts-scan-agent is a companion open-source tool that looks at an arbitrary repository (including monorepos and container images) and proposes a concrete TrustSource scan concept: which parts should become TrustSource Modules, Infrastructure Modules or Linked Modules, and the exact ts-scan command to run for each. It's a separate, standalone project — worth a look before you work out module boundaries and CI wiring by hand.
ts-scan is available as a PyPI package. To install, you will require a recent Python (>= 3.10) version installed and pip (>=22.0). Generally pip is already contained in your Python distribution but if not, follow pip's installation instruction.
pip install ts-scanThis installs the dependency and SBOM scanner without the optional in-depth file analysis stack. To enable the
analyse command and generic file analysis, install the analyse extra:
pip install "ts-scan[analyse]"git clone https://github.com/trustsource/ts-scan.git
cd <path to the ts-scan repo, typically ts-scan>
pip install ./ --process-dependency-linksFor some scenarios you may want to provide ts-scan inside a Docker container, e.g. to prevent issues from version conflicts.
Caution
PLEASE NOTE: Scanning of Docker images using Syft from within the ts-scan Docker image is not supported for security reasons.
cd <path to the ts-scan>
docker build -t ts-scan .cd <path to the ts-scan>
docker buildx build --platform linux/amd64 -t ts-scan .Reason for this is, that pyminr - the encryption scanner - might fail to install on ARM chips.
docker run -it --rm -v <PROJECT_PATH>:/project trustsource/ts-scan scan -o /project/scan.json /project vcpkg projects work with ts-scan scan <project>: the scanner discovers existing
package data in standard project/CMake locations and installs manifest dependencies
through vcpkg when package data is absent. Options such as --vcpkg:installedDir,
--vcpkg:triplet, and --vcpkg:roots override discovery and scope. See the
vcpkg example for usage and limitations.
Conan 2 projects containing conanfile.py or conanfile.txt are supported.
The scanner resolves dependencies through conan graph info, or reads a build's
JSON graph with --conan:graphFile. See the Conan example
for profiles, offline scanning, and build/test dependency options.
The ts-scan functionality is divided into a set of commands based on the intended goal. The following commands are available:
| Command | Description |
|---|---|
| init | Initialize a TrustSource project |
| scan | Scan for package dependencies |
| analyse | Perform an in-depth analysis of a scan or an SBOM file |
| check | Check packages for legal issues and vulnerabilities |
| upload | Upload scan and analysis results to the TrustSource application |
| import | Import SPDX and CycloneDX files directly into the TrustSource application |
| convert | Convert SBOM between supported formats (TS, SPDX, CycloneDX) |
To display a list of all available commands, use:
ts-scan --helpTo get details about a specific command, use:
ts-scan <COMMAND> --helpBy first time ts-scan is executed, a user settings file is created in the home directory at $HOME/.ts-scan/config. It contains an empty [default] profile.
The user settings file can be used to store any option passed to the ts-scan. The groups of options can be grouped into profiles.
An example of a user settings file is:
[default]
api_key="<TrustSource API key>"
[dev]
api_key="<TrustSource API key from the Dev account>"
project_name="TrustSource default Project in the Dev account"The format is a dictionary with the option name in snake-case format as a key and a value. For example, if the ts-scan option for the project name is --project-name, the corresponding key in the user settings file is project_name.
When ts-scan is executed all options from the default profile are loaded as default values for the command line options. If an option is explicitly passed on the command line, it will override the default value.
To select a profile, use the -p\--profile option. For example, to use the dev profile, use:
ts-scan -p dev upload MyScan.jsonIn this case the ts-scan will use the api_key and project_name from the dev profile for the upload.
To store the API key and base URL in a profile without editing the file, use the configure command. Without options it shows the profile, with the API key masked:
ts-scan configure --api-key <TrustSource API key>
ts-scan -p dev configure --api-key <API key from the Dev account> --base-url https://api.dev.trustsource.ioThe base URL may be given with or without the API version: /v2 is appended only if it is missing.
Note: the API key and the base URL are tool settings. They are taken from the command line, the environment (e.g. TS_UPLOAD_API_KEY, TS_UPLOAD_BASE_URL) or the user settings file only, and are fixed when ts-scan starts. A scanned project cannot change them (see Init). The same applies to options that run programs or write files (--<pm>:executable, --<pm>:forward, -o/--output, --node:enableLifecycleScripts) and to values that reference environment variables (${VAR}).
Note: requests to the TrustSource API time out after 60 seconds. If large uploads need longer, set the environment variable TS_REQUEST_TIMEOUT to the limit in seconds, e.g. export TS_REQUEST_TIMEOUT=180.
The init command initializes a TrustSource project. It creates a project settings file tsproject.toml in the provided directory, which stores the project name, so it does not have to be passed every time a new scan is uploaded.
To initialize a project, use:
ts-scan init --project-name <TrustSource project name> <path to the project directory>Note: the project settings describe what is scanned, never where the results go or which programs run. A scanned repository may be foreign, so the following entries in its tsproject.toml are ignored with a warning:
api_keyandbase_url, so it cannot redirect your API key to another endpoint,- options that run programs or write files:
<pm>_executable,<pm>_forward,output_pathandnode_enableLifecycleScripts, so it cannot make ts-scan execute code of its choice, - values that reference environment variables (
$VAR,${VAR}), so it cannot send your environment, e.g. CI secrets, to an endpoint of its choice.
Store such settings with configure, in the user settings file, or pass them on the command line or in the environment.
Note: the project settings override the user settings file; the environment (TS_<COMMAND>_<OPTION>, e.g. TS_SCAN_PYPI_INDEXURL) and the explicitly passed command line options override the project settings.
The scan command searches for package dependencies in your project. By providing a path to either a project directory or a project file—depending on whether the package manager is file-based (e.g., .NET solutions, Maven) or directory-based (e.g., NPM, Gradle)—ts-scan automatically detects supported package management systems and extracts the full dependency tree. The scan results can be saved to a file using either the internal TS format or one of the supported SBOM formats: SPDX or CycloneDX.
To execute a scan and store results into a file, use:
ts-scan scan -o <path to the output file> [-f <output format>] <path to the project directory or a project file>The -f <output format> option controls the output format and can be:
ts- the TrustSource internal format (default)spdx-[tag|json|yaml|xml]- One of the SPDX formats, e.g.spdx-jsoncyclonedx-[json|xml]- One of the CycloneDX formats, e.g.cyclonedx-json
ts-scan detects the package management system from the files found in the scanned path. Scanners that read an already resolved lockfile need no toolchain installed and no network access; the others call the corresponding executable to resolve the graph.
| Ecosystem | Detected by | Resolved from | Executable required |
|---|---|---|---|
| PyPI | setup.py, pyproject.toml |
pip install --dry-run --report |
pip and access to the package index |
| Maven | pom.xml |
mvn dependency:tree |
mvn |
| Gradle | build.gradle[.kts] |
gradle dependencies |
gradle |
| NPM | package.json |
package-lock.json |
npm (to create the lockfile) |
| NuGet | *.sln, *.csproj, packages.config |
packages.lock.json, project.assets.json |
nuget / dotnet |
| Composer (PHP) | composer.json |
composer.lock |
composer (to create the lockfile) |
| Cargo | Cargo.toml |
Cargo.lock |
cargo (to create the lockfile) |
| Go | go.mod |
go list |
go |
| Dart / Flutter | pubspec.yaml |
dart pub deps |
dart / flutter |
| Swift Package Manager | Package.swift |
swift package show-dependencies |
swift |
| CocoaPods | Podfile.lock |
Podfile.lock |
no |
| Visual Basic 6 | *.vbp, *.vbg |
Project and group files | no |
| Docker images, file systems | passed as a source | Syft | syft |
ts-scan contains some general options as well as options that only apply while scanning specific package types. The package specific options are prefixed by the type of the package management system. We use the Package URL Type as a prefix. The following options are valid for most supported package management system:
--[maven|gradle|node|nuget|pypi|dart|swift|composer|cocoapods|vb6]:ignore- Disable scanning dependencies of the type--[maven|gradle|node|nuget|dart|swift|composer]:executable- Specify a path to the PM executable--[maven|gradle|node|nuget|dart|swift|composer]:forward- Forward arguments to the PM's executable--nuget:separateProjectScans- For a solution, create one scan per project using the project as the module--[node|dart|composer]:includeDevDependencies- Include development dependencies in the scan results--composer:includePlatformPackages- Include the PHP platform requirements (php,ext-*,lib-*,composer-*)--[node|cargo|composer]:enableMetadataRetrieval- Enrich packages with metadata from the online registry--pypi:extras- Include the optional dependencies of the given extras of the scanned project (comma-separated or repeated)--pypi:indexUrl/--pypi:extraIndexUrl- Resolve Python dependencies from a company package repository instead of PyPI
The full list of options including PM specific options can be printed using:
ts-scan scan --helpWhile scanning for Maven, Node and NuGet dependencies, ts-scan calls corresponding package manager executables. For example, in order to specify a path to the Maven excutable use the following option
ts-scan scan --maven:executable /opt/local/bin/mvn <PATH>Executable paths and forwarded parameters are tool settings: they are taken from the command line, the environment or the user settings file, never from the tsproject.toml of the scanned project.
A Python project is detected by its setup.py or pyproject.toml. ts-scan resolves the project and its dependencies with pip install --dry-run --ignore-installed --report, i.e. exactly as pip install <PATH> would for the Python version ts-scan runs with, without installing anything. Optional extras of the project and of its dependencies are only followed if they are requested, and requirements for other platforms or Python versions are skipped.
ts-scan scan --pypi:extras server,postgres -o scan.json <PATH>The transitive dependencies can only be determined with access to the package sources of the project. By default pip uses its own configuration (pip.conf, PIP_INDEX_URL), i.e. the public PyPI. A company package repository, e.g. a Nexus or Artifactory proxy, can be configured in the tsproject.toml in the root of the project, so that every scan of the repository uses it:
pypi_indexUrl = "https://nexus.example.com/repository/pypi/simple"
# pypi_extraIndexUrl = ["https://internal.example.com/simple"]Credentials do not belong into the repository. The project settings may therefore not reference environment variables; such values are ignored with a warning. Provide an index that requires authentication as a tool setting instead, where ${VAR} references are replaced with environment variables, e.g. with a CI secret:
export TS_SCAN_PYPI_INDEXURL='https://ci:${NEXUS_TOKEN}@nexus.example.com/repository/pypi/simple'
ts-scan scan -o scan.json <PATH>The same is possible with --pypi:indexUrl / --pypi:extraIndexUrl on the command line; both the command line and the environment override the project settings. An index in the user settings file applies to projects that configure none. Alternatively, pip takes the credentials for a host from ~/.netrc or a keyring. ts-scan passes the index URLs to pip in the environment and never writes credentials to its output. Note that an additional index allows a package of the same name from either index to be installed (dependency confusion); prefer a single repository that proxies PyPI.
If the dependencies cannot be resolved, e.g. because the package index is not reachable or a package is not available there, the scan is aborted with exit code 2 and no output is written. A scan with missing or guessed versions would be wrong.
A PHP project is detected by its composer.json. The dependency graph is resolved from the composer.lock file, therefore a committed lockfile produces the most accurate results and requires neither a Composer installation nor network access. If no lockfile is present, ts-scan calls composer update --no-install to create one. Should that fail, or should Composer not be installed, the scan falls back to the requirements declared in composer.json, which are then reported without resolved versions.
ts-scan scan --composer:includeDevDependencies --composer:includePlatformPackages -o scan.json <PATH>Platform requirements such as php or ext-json are not Packagist packages and are therefore excluded by default. When enabled, they are added with their declared constraint and their well-known license (e.g. PHP-3.01) for compliance purposes.
There are also options to forward parameters to a package manager executable. For example, in order to pass a settings file to Maven, one can use the following combination:
ts-scan scan --maven:forward --settings,customSettings.xml <PATH>--verbose- Enables verbose mode (including output from PM executables, useful for debugging)--tag <TAG>- Stores the SCM tag<TAG>in the scan--branch <BRANCH>- Stores the SCM branch<BRANCH>in the scan
ts-scan can use Syft scanner as a backend for dependencies scanning. To enable the Syft scanner, use the following option:
ts-scan scan --use-syft <SOURCE>As a source you can specify any type of sources accepted by Syft, for example a local filesystem path. For more details on supported formats please refer to Syft Supported Sources.
Before calling Syft, ts-scan tries to find the Syft executable in default locations, in order to specify a custom location use the following option:
ts-scan scan --use-syft --syft-path <syft executable> <SOURCE>To pass custom parameters directly to Syft:
ts-scan scan --use-syft --Xsyft <option>,<value> <SOURCE>Syft supports many different input types, and one of them is Docker images. To scan a local docker image, use the following command:
ts-scan scan --use-syft -o <OUTPUT> docker:<DOCKER IMAGE>The in-depth dependency analysis is performed using the analyse command, which takes a scan file as input in one of the supported formats: the internal TS format, SPDX, or CycloneDX. Depending on the dependency package, the tool locates its files and scans each one using ts-deepscan. Additionally, it uses SCANOSS to improve and enrich the collected in-depth scanning results. The analyse command can also take a directory as input to directly scan files inside it.
The command requires the optional analyse extra (pip install "ts-scan[analyse]"). Without it, the command remains visible in --help and reports how to enable it when invoked.
To analyse a scan or a directory and store results into a file, use:
ts-scan analyse [-f <input format>] [-o <output>] <path to the scan file or directory>The -f <input format> option specifies the input format of the scan to be checked (if a scan file is provided as input) and accepts the same values as the <output format> of the scan command.
By default, the analyse, command applies ts-deepscan using its default configuration and extends the analysis results with data from SCANOSS API.
To disable or fine-tune specific analysis steps, you can use additional options.
--disable-deepscan- Disables analysis using DeepScan.--disable-scanoss- Disables extending DeepScan results with SCANOSS data.--scanoss-api-key <SCANOSS API key>- A SCANOSS API key, required for accessing data provided by SCANOSS over non-public API. For more details, please refer to SCANOSS--Xdeepscan <OPTION>,<VALUE>- Forwards to the DeepScan scan command.
The --Xdeepscancan be used to configure the DeepScan analysers. For example, to analyse a scan while setting a timeout (in seconds) per file, use:
ts-scan analyse --Xdeepscan timeout,30 <path to the scan file or directory>For more details on available options for DeepScan, please refer to ts-deepscan documentation.
The ts-scan check command verifies project dependencies against the TrustSource vulnerability database.
The command can optionally exit with a non-zero error code (1) if vulnerabilities are found, making it suitable for CI/CD workflows.
To execute a vulnerabilities check, use the following command:
ts-scan check --api-key <TrustSource API key> [-f <input format>] [-o <output>] [--exit-on-vulns/--no-exit-on-vulns] [--vulns-confidence low|medium|high] <path to the scan file>The option --api-key <TrustSource API key> is required.
The -f <input format> option specifies the input format of the scan to be checked and accepts the same values as the <output format> of the scan command.
Optionally, using the -o <output> option, you can store the check results into a JSON file.
By default, the command prints or stores the findings and exits successfully. Use --exit-on-vulns if vulnerabilities should result in a non-zero error code (1).
The --vulns-confidence <level> option allows you to control the confidence level for matching components with affected products listed in security bulletins, such as product/vendor tuples in CVEs. The default value is medium.
The main options available for the check command are:
--exit-on-vulns- Exit with a non-zero (1) exit code if vulnerabilities are found (default:off)--vulns-confidence- Control the confidence level for vulnerability matches (default:medium)
The ts-scan upload command transfers dependency scans to the TrustSource API.
ts-scan upload --project-name <TrustSource project name> --api-key <TrustSource API key> [-f <input format>] [--wait-for-analysis] [--wait-timeout <seconds>] [--exit-on-legal/--no-exit-on-legal] [--exit-on-vulns/--no-exit-on-vulns] [--Werror] <path to the scan file>The options --project-name <TrustSource project name> and --api-key <TrustSource API key> are required.
The -f <input format> option specifies the input format of the scan to be uploaded and accepts the same values as the <output format> of the scan command.
During upload, embedded DeepScan results are transferred first when present, and the scan file is updated with the returned DeepScan identifiers and URLs.
Use --wait-for-analysis if the command should wait until TrustSource finishes processing the uploaded scan. In that mode, --wait-timeout controls how long to wait, and the command prints a link to the resulting analysis when available.
The policy exit flags only apply together with --wait-for-analysis:
--exit-on-legal- Exit with a non-zero (1) exit code if the finished analysis reports legal policy violations or, with--Werror, legal warnings--exit-on-vulns- Exit with a non-zero (1) exit code if the finished analysis reports vulnerability policy violations or, with--Werror, vulnerability warnings--Werror- Treat analysis warnings as violations when evaluating the policy exit flags
If --wait-for-analysis is not used, the command uploads the scan and returns immediately after the transfer completes.
ts-scan upload --helpThe import command is used to import SBOMs to the TrustSource App for the .... TBD:
Supported import formats:
- SPDX RDF (spdx-rdf)
- SPDX JSON (spdx-json)
- CycloneDX (cyclonedx)
ts-scan import -f <SBOM format> -v <SBOM format version> --module <SBOM module name> --module-id <SBOM module id> --project-name <TrustSource project name> --api-key <TrustSource API key> <path to the SBOM file>ts-scan import --helpTo convert a SBOM between supported formats, use:
ts-scan convert [-f <input format>] [-of <output format>] [-o <output>] <path to the SBOM file>The -f <input format> and the -of <output format> options specify the input format and the output format respectively and accept the same values as the of the scan command.