Spectra Assure SDK for Python ·

Note: Python 3.11 will be the minimum in the next version. This version still supports Python 3.10, which reaches its end of life on 2026-10-31. The next version of the SDK will require Python 3.11 or later.

Spectra Assure SDK for Python is the official library maintained by ReversingLabs that makes it easier to integrate with the Spectra Assure Portal and interact with it in your own applications.

The SDK provides access to the operations supported by the Spectra Assure Portal API, allowing you to work with Portal File Stream and Projects.

You can use the SDK to:

• Create, edit and delete projects and packages, and edit and delete versions
• Add versions by uploading a file, or by importing it from a URL or a package URL (PURL)
• List the projects in a group, the packages in a project and the versions of a package, and show the details of a version
• Show the analysis status and the performed checks of a version, download its analysis reports and its RL-SAFE archive, and rescan it
• Approve, reject and revoke versions, and download approved versions
• Upload or import, analyze, approve and download standalone files in the File Stream
• Query the Spectra Assure Community for open-source packages
• List the groups of an organization, show usage, export and import profile configurations, and export the audit log

Note: This documentation assumes that you already have a working knowledge of Python and previous experience with setting up your own Python projects.

What is the Spectra Assure Portal?

The Spectra Assure Portal is a SaaS solution that's part of the Spectra Assure platform - a new ReversingLabs solution for software supply chain security. More specifically, the Portal is a web-based application for improving and managing the security of your software releases and verifying third-party software used in your organization.

With the Spectra Assure Portal, you can:

• Scan your software packages to detect potential risks before release.
• Improve your SDLC by applying actionable advice from security scan reports to all phases of software development.
• Organize your software projects and automatically compare package versions to detect potentially dangerous behavior changes in the code.
• Manage software quality policies on the fly to ensure compliance and achieve maturity in your software releases.

Table of contents

• Requirements and dependencies
• Installation
• Authentication
• Quick start
• Logging
• Usage
  • Rate limiting
  • Configuration
  • Validation
  • Exceptions
• Examples
• Reference
• Operations
• Community repositories
• Sessions
• Support
• License
• Changes
• Versioning

Requirements and dependencies

• Python (minimal version: 3.10)
• requests; version: >=2.32.2,<=2.34.2
• An active Spectra Assure Portal account. If you don't already have a Portal account, you may need to contact the administrator of your Portal organization to invite you. Alternatively, if you're not a Spectra Assure customer yet, you can contact ReversingLabs to sign up for a Portal account.
• A Personal Access Token generated for your Spectra Assure Portal account.

Installation

To get started with the Spectra Assure SDK, install the latest version from PyPI with pip:

pip install spectra-assure-sdk

The SDK uses version v1 of the Spectra Assure Portal API. Tell it where your Portal is with host, server or both; see Usage. The API settings api_version, api_domain and api_proto must not be changed.

Authentication

Before using the Spectra Assure SDK, you need to set up authentication credentials for your Portal account.

If you don't already have it, generate a Personal Access Token for your account.

When you have the token, you can use it in any of the following ways:

• in a JSON configuration file
• with the token argument in your code

Roles and permissions set for your Portal account automatically apply to your token, and control which actions you can perform.

Keep in mind that Personal Access Tokens for Portal accounts have an expiration date. After a token expires, any apps or integrations relying on it for authentication will stop functioning. When this happens, you have to generate a new token and update it in all relevant places.

Quick start

You must import the SpectraAssureApiOperations class.

To start working with the SDK, initialize an instance of SpectraAssureApiOperations and specify all required parameters.

Using named arguments is explicitly enforced - positional arguments are not supported in any of the SDK calls.

The following example reads the settings from environment variables, lists the groups the specified token can access, and closes the connection when the with block ends.

Python code example

import os

from spectra_assure_api_client import SpectraAssureApiOperations

# os.environ[...] fails at once when a variable is missing; str(os.getenv(...))
# would instead pass the text "None" on as the organization name.
with SpectraAssureApiOperations(
    host=os.environ["RLPORTAL_HOST"],
    server=os.environ.get("RLPORTAL_SERVER"),  # optional
    organization=os.environ["RLPORTAL_ORG"],
    group=os.environ["RLPORTAL_GROUP"],
    token=os.environ["RLPORTAL_ACCESS_TOKEN"],
) as client:
    response = client.list_groups()
    print(response.status_code, response.json())

The settings can also come from a JSON configuration file, alone or together with named arguments, which take precedence over the file (see Configuration):

import os

from spectra_assure_api_client import SpectraAssureApiOperations

with SpectraAssureApiOperations(
    config_file="./myConfig.json",
    token=os.environ["RLPORTAL_ACCESS_TOKEN"],  # keeps the token out of the file
) as client:
    print(client.list_groups().status_code)

Example configuration file - myConfig.json

{
  "SpectraAssureApi" : {
    "host": "my.secure.software",
    "server": "test",
    "organization": "Test",
    "group": "Default",
    "timeout": 60,
    "auto_adapt_to_throttle": true
  }
}

Logging

The SDK logs through the standard Python logging module, under the logger spectra_assure_api_client (each module logs to a child of it, such as spectra_assure_api_client.communication.core). It never logs the token, and it masks a proxy password. Configure it like any library logger:

import logging

logging.basicConfig(level=logging.WARNING)
logging.getLogger("spectra_assure_api_client").setLevel(logging.INFO)

For scripts, the SDK has a helper that sets up a console handler, at the level in the LOG_LEVEL environment variable (default WARNING), and a <program>.log file in the current directory. Calling it again replaces the handlers it added rather than adding more:

import logging

from spectra_assure_api_client import SpectraAssureApiOperations

logger = logging.getLogger()
SpectraAssureApiOperations.make_logger(my_logger=logger)
logger.info("start program")

Usage

The following parameters are mandatory for all operations:

• organization - Name of a Portal organization to use in requests. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.
• group - Name of a Portal group to use in requests. The group must exist in the specified Portal organization. Group names are case-sensitive.
• token - Personal Access Token for authenticating to the Portal API.

The following parameters are optional:

• host - The host name of your Portal, usually my.secure.software.
  Any other host will be explicitly communicated to customers.
• server - Name of the Portal instance (tenant) to use in requests.
  The Portal instance name usually matches the subdirectory of my.secure.software in your Portal URL.
  For example, if your portal URL is 'my.secure.software/demo', the instance name to use with this parameter is 'demo'.

At least one of host and server must be given; with neither, the client cannot be created. They combine like this:

• read_timeout - The read timeout to be used for HTTPS requests, specified in seconds.
  The default is 3600 seconds.
• timeout - The older name for read_timeout; both set the same value.
  If both are given, read_timeout is used.
• connect_timeout - The connect timeout used by the https requests, specified in seconds.
  The default is 10 seconds.
  Downloads keep the read timeout within 10 to 3600 seconds and the connect timeout within 1 to 10 seconds; a value outside that range is adjusted and a warning is logged.
• auto_adapt_to_throttle - Some requests may be throttled and require a minimal wait time before the next request.
  With this option, you can automatically wait for the data to become available and for the required time to pass.
  By default, this option is disabled (set to false).
  This parameter can also be specified on each individual operation.
• no_ssl_verify - Set to true to turn off TLS certificate verification.
  By default, certificates are verified. Use this only for testing.
• config_file - Path to an optional JSON configuration file that supplies any of these settings; see Configuration.
• proxy_server, proxy_port, proxy_user, proxy_password - Optional proxy settings for all requests.
  proxy_server needs proxy_port, and proxy_user and proxy_password go together.
• additional_args - Data of your own, passed through untouched; get_additional_args() returns it.

Every setting can be given as a named argument or in the configuration file.

Operations on the Portal's projects, packages and versions take project, package and version as named arguments, and what they are given decides what they act on:

Which of these a call supports is shown in its table in Operations. File Stream calls take a file_id instead.

Refer to the full list of supported operations for more details on their usage and specific parameters they support.

Rate limiting

Requests to the Spectra Assure Portal API are subject to rate limiting as defined in the official API documentation.

This means that rate limits will also apply to requests sent by the SDK.

Optionally, you can enable the auto_adapt_to_throttle setting globally (when creating the SpectraAssureApiOperations instance) or on each individual operation. A call that is answered with 429 waits as long as specified in the API's Retry-After header and tries again, up to 5 attempts in total. Without that header, the call waits 60 seconds.

Download link requests are the exception. The API allows 10 requests per minute, so download() and filestream_download() wait out a 429 on a link request even when the setting is off. To fail immediately instead, pass auto_adapt_to_throttle=False to the call.

Because this setting may slow down responses, it is not recommended for interactive use. It is most suitable for automatic batch processing.

Configuration

The SDK supports specifying mandatory and optional parameters in any of the following ways:

• in a JSON configuration file
• directly as named arguments in the code

By default, the configuration is evaluated and merged in that order: configuration file -> named arguments. If a parameter is specified more than once, the latest stage overrides all previous instances. In other words, if a parameter is set in the configuration file and as a argument, the SDK will use the value from the argument.

• The configuration file must be in JSON format.
• The file name must end in .json, and the file must contain the SpectraAssureApi object; otherwise the SDK raises SpectraAssureInvalidAction.
• The file structure requires that all configuration parameters are placed as keys in the top-level SpectraAssureApi object like in the following example:

{
  "SpectraAssureApi" : {
    "host": "my.secure.software",
    "server": "test",
    "organization": "Test",
    "group": "Default",
    "timeout": 60,
    "auto_adapt_to_throttle": true
  }
}

The configuration file supports the following parameters:

Mandatory

• organization: string
• group: string
• token: string

Optional

• host: string
• server: string
• proxy_server: string
• proxy_port: int
• proxy_user: string
• proxy_password: string
• timeout: int (same as read_timeout)
• read_timeout: int
• connect_timeout: int
• auto_adapt_to_throttle: bool
• no_ssl_verify: bool | None = None.

A setting the SDK does not recognise is ignored, and a UserWarning is issued that names it and suggests the closest valid name. This applies to unknown keyword arguments and to unknown keys inside the SpectraAssureApi object of a configuration file. Keys outside that object are not checked.

All proxy_* parameters are optional. However, if you're using proxy_server, then you must also use proxy_port. Similarly, proxy_user and proxy_password must be used together.

Validation

Some operations support additional query parameters with values that require validation (for example, strings that have limited length or enumerated values).

The SDK does not explicitly check all values - the validation is performed on the Portal side.

Before using query parameters, it is recommended to check their limitations in the Portal API reference documentation or in the Portal OpenAPI specification.

Exceptions

Operations return the requests.Response of the API call, except four that do more than one call: download and filestream_download return a dict describing what was downloaded, or None when nothing qualified, and rl_safe_download and filestream_rl_safe_download return a tuple (downloaded, file_path). The operations that return the response do not raise on an HTTP error status; check response.status_code. The four download calls raise an exception when the API answers with an error. All operations raise exceptions for errors in their arguments or configuration. It is up to the SDK user to handle any exceptions.

Every exception the SDK raises derives from SpectraAssureExceptions, so one except SpectraAssureExceptions catches them all. Depending on the operation and the type of issue, the following exceptions may be raised:

• SpectraAssureExceptions - The base of all of them.
  • SpectraAssureInvalidAction - This action is not allowed, or a setting is invalid. It is also raised for every problem with the configuration file: it is missing or cannot be read, it is not valid JSON or not UTF-8 text, or it does not contain a JSON object with a SpectraAssureApi object in it. The original error, such as FileNotFoundError or json.JSONDecodeError, is available as its __cause__.
  • SpectraAssureWaitTimeoutExceeded - A wait timeout has expired.
  • SpectraAssureInvalidPath - The specified path is incorrect.
  • SpectraAssureUnexpectedNoDataFound - Received no data where we expected some.
  • SpectraAssureNoDownloadUrlInResult - The query returns no download URL.
  • SpectraAssureUnsupportedStrategy - Attempted download strategy is not supported.
  • SpectraAssureSpecError - The compiled API specification shipped with the SDK is missing or damaged; a packaging fault.
  • UrlDownloaderExceptions - The base of the downloader's exceptions.
    • UrlDownloaderUnknownHashKey - No digest found; can't find the proper hash key or the hash type is not supported.
    • UrlDownloaderTargetDirectoryIssue - The target file path does not exist or is not a directory.
    • UrlDownloaderTargetFileIssue - The target file name can't be extracted from the URL.
    • UrlDownloaderTempFileIssue - No temporary file can be created in the target directory.
    • UrlDownloaderFileVerifyIssue - Cannot calculate hash; verification failed.

Examples

An example program showing all supported operations is available in this repository: api_client_example.py

Reference

The doc folder in the SDK GitHub repository contains reference pages for individual operations.

You can also consult the official Spectra Assure Portal and API reference documentation for more detailed instructions on specific features and functionalities.

Operations

Every call is described in Operations: one entry per operation, with the class that provides it, a table of the levels it works at, and a link to its reference page in doc/.

• General operations: the organization, its groups, and projects, packages and versions; also the Community calls
• File Stream: standalone files, addressed by file_id
• Catalog: external catalogs, and the group's software catalog

Community repositories

The repository names the API accepts (the community values in its specification) are:

• gem
• npm
• nuget
• psgallery
• pypi
• vsx
• maven
• clawhub

The SDK passes the name to the API as given, so a repository the API adds works without an SDK update. Read more about supported communities.

Sessions

Every request a client makes goes through one requests.Session, held for the life of the client, so connections to the Portal are reused rather than opened for every call.

Public surface

client.close()                                   release the pooled connections
with SpectraAssureApiOperations(...) as client:   closes the session on exit
client.session                                   the session itself, if you need to tune it

close() is idempotent, and the client still works afterwards: requests opens a fresh connection on the next call.

Thread safety -- please read

requests.Session is not thread-safe, so a client must not be shared between threads. Give each thread its own client.

Support

To get assistance with the Spectra Assure SDK, you or your company need to have an existing support agreement with ReversingLabs. Then you can submit a support request with "Spectra Assure SDK" in the message subject.

ReversingLabs does not provide support if the original code from the official Spectra Assure SDK repository has been modified by you or any other open source community members. In those cases, contact the author(s) of the modified SDK for help.

License

The Spectra Assure SDK (Software Development Kit) for Python is released under the MIT License.

Changes

For a detailed list of changes see CHANGES.

Versioning