# Spectra Assure SDK for Python
Spectra Assure SDK for Python is the official library maintained by ReversingLabs that makes it easier to integrate with the [Spectra Assure Portal](https://docs.secure.software/portal/) and interact with it in your own applications.
The SDK provides access to operations supported by the [Spectra Assure Portal API](https://docs.secure.software/api/).
The Portal API only supports Portal Projects features, and cannot be used to work with the File Stream.
You can use the SDK to:
- Create and delete projects and packages in the Portal
- Add and remove package versions in the Portal
- Update details for projects, packages, and versions
- Get a list of all projects in a group, all packages in a project, all versions in a package, and show details for any package version
- Show analysis status and performed checks for a package version
- Download analysis reports for a package version
- Download package versions previously approved in the Portal GUI
> **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](https://www.reversinglabs.com/products/software-supply-chain-security) - 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](#requirements-and-dependencies)
- [Installation](#installation)
- [Authentication](#authentication)
- [Quick start](#quick-start)
- [Logging](#logging)
- [Usage](#usage)
- [Rate limiting](#rate-limiting)
- [Configuration](#configuration)
- [Validation](#validation)
- [Exceptions](#exceptions)
- [Reference](#reference)
- [Operations](#operations)
- [Support](#support)
- [License](#license)
- [Versioning](#versioning)
## Requirements and dependencies
- Python (minimal version: 3.10)
- [requests](https://pypi.org/project/requests/) (version not critical)
- 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](https://docs.secure.software/portal/members#invite-a-new-member). Alternatively, if you're not a Spectra Assure customer yet, you can [contact ReversingLabs](https://docs.secure.software/portal/#get-access-to-securesoftware-portal) to sign up for a Portal account.
- A [Personal Access Token](https://docs.secure.software/api/generate-api-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`
By default, the SDK uses the Spectra Assure Portal API `v1` with `my.secure.software` as the host.
The default host and API version must not be modified by SDK users.
## 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](https://docs.secure.software/api/generate-api-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](https://docs.secure.software/portal/user-management#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](#usage).
*Using named arguments is explicitly enforced - positional arguments are not supported in any of the SDK calls.*
The following code example shows how to combine different ways of specifying the required parameters (as named arguments, in a JSON configuration file, or both).
**Python code example**
```
import os
from spectra_assure_api_client import SpectraAssureApiOperations
prefix = "RLPORTAL_"
server = str(os.getenv(f"{prefix}SERVER"))
organization = str(os.getenv(f"{prefix}ORG"))
group = str(os.getenv(f"{prefix}GROUP"))
token = str(os.getenv(f"{prefix}ACCESS_TOKEN"))
configFile = "./myConfig.json"
for what in [1, 2, 3]:
try:
if what == 1:
# Use only named arguments
aHandle = SpectraAssureApiOperations(
server=server,
organization=organization,
group=group,
token=token,
)
elif what == 2:
# Use only the configuration file
# Note: with the current configFile example, this will fail because the token is not specified
aHandle = SpectraAssureApiOperations(
configFile=configFile,
)
elif what == 3:
# Combine the configuration file with named arguments
aHandle = SpectraAssureApiOperations(
configFile=configFile,
token=token,
)
print(aHandle)
except Exception as e:
print(e)
```
**Example configuration file - myConfig.json**
```
{
"SpectraAssureApi" : {
"server": "test",
"organization": "Test",
"group": "Default",
"timeout": 60,
"auto_adapt_to_throttle": true
}
}
```
### Logging
The SDK uses logging internally. You can interface with the logging functions in the SDK by using the standard Python logging library.
**Logging example**
```
import os
import logging
import sys
from spectra_assure_api_client import SpectraAssureApiOperations
logger = logging.getLogger()
def make_logger(logger: logging.Logger) -> None:
logger.setLevel(logging.DEBUG)
progName = os.path.basename(sys.argv[0])
if progName.endswith(".py"):
progName = progName[:-3]
fileName = f"{progName}.log"
fh = logging.FileHandler(fileName)
fh.setLevel(logging.INFO)
ch = logging.StreamHandler()
ch.setLevel(os.getenv("LOG_LEVEL", "WARNING"))
formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
ch.setFormatter(formatter)
fh.setFormatter(formatter)
# add the handlers to logger
logger.addHandler(ch)
logger.addHandler(fh)
if __name__ == "__main__":
make_logger(logger)
logger.info("start program")
```
## Usage
The following parameters are mandatory for all operations:
- **server** - Name of the Portal instance 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'.
- **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:
- **timeout** - The request timeout to be used for HTTPS requests to the Portal API, specified in seconds.
The default is 10 seconds.
- **auto_adapt_to_throttle** - Some requests may be
[throttled](#rate-limiting)
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.
Some operations support multiple targets (project, package, version) that have to be provided as named arguments.
Based on the provided arguments, the library can automatically decide the target of the operation.
The first value of 'None' decides the target of the operation:
```
- project: str | None;
If we don't have a project name,
we are doing something with a group.
- package: str | None;
If we don't have a package name,
we are doing something with a project.
- version: str | None;
If we don't have a version name,
we are doing something with a package.
- If all args are not None,
we are doing something with a version.
```
Refer to the full list of [supported operations](#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](https://docs.secure.software/api-reference/#section/About-the-API/Rate-limiting).
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.
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 is arbitrary.
The file structure requires that all configuration parameters are placed as keys in the top-level `SpectraAssureApi`
object like in the following example:
```
{
"SpectraAssureApi" : {
"server": "test",
"organization": "Test",
"group": "Default",
"timeout": 60,
"auto_adapt_to_throttle": true
}
}
```
The configuration file supports the following parameters:
**Mandatory**
- server: `string`
- organization: `string`
- group: `string`
- token: `string`
**Optional**
- proxy_server: `string`
- proxy_port: `int`
- proxy_user: `string`
- proxy_password: `string`
- timeout: `int`
- auto_adapt_to_throttle: `bool`
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](https://docs.secure.software/api-reference/) or in the [Portal OpenAPI specification](https://docs.secure.software/redocusaurus/secure-software-public-v1.yaml).
### Exceptions
All operations return a `requests.Response` and may raise exceptions in case of errors or misconfiguration.
It is up to the SDK user to handle any exceptions.
Depending on the operation and the type of issue, the following exceptions may be raised:
- `SpectraAssureInvalidAction` - This action is not allowed
- `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
- `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` - There is an issue with 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](./examples/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](https://docs.secure.software/portal/) and
[API reference documentation](https://docs.secure.software/api/)
for more detailed instructions on specific features and functionalities.
### Operations
Every class listed in this section maps directly to a Portal API operation,
except **SpectraAssureApiOperationsDownload** which is a synthetic operation not directly available on the Portal.
If an operation supports query parameters, they should be provided in the `qp` argument list.
Any invalid parameters will be automatically filtered out.
[`SpectraAssureApiOperationsChecks`](./doc/checks.md)
**Show performed checks for a version.**
| | Group | Project | Package | Version |
| -- | -- | -- | -- | -- |
| Targets | | | | ✔️ |
| Query parameters | | | | |
[`SpectraAssureApiOperationsCreate`](./doc/create.md)
**Create a project or package in the Portal.**
| | Group | Project | Package | Version |
| -- | -- | -- | -- | -- |
| Targets | | ✔️ | ✔️ | |
| Query parameters | | ✔️ | ✔️ | |
[`SpectraAssureApiOperationsDelete`](./doc/delete.md)
**Remove a project, package, or version from the Portal.**
| | Group | Project | Package | Version |
| -- | -- | -- | -- | -- |
| Targets | | ✔️ | ✔️ | ✔️ |
| Query parameters | | | | ✔️ |
[`SpectraAssureApiOperationsDownload`](./doc/download.md)
**Download file(s) of approved version(s).**
This class uses `list` and `status` operations to gather information about what is downloadable,
and only requests the artifact download URL for versions that are selected for download.
Every time the download link is generated, your Portal download capacity is reduced by the artifact's file size,
even if the artifact is not downloaded from the link.
If your user account doesn't have permission to download files from the Portal,
the API responds with an error and the download capacity remains unaffected.
[`SpectraAssureApiOperationsEdit`](./doc/edit.md)
**Edit details for a project, package, or version.**
| | Group | Project | Package | Version |
| -- | -- | -- | -- | -- |
| Targets | | ✔️ | ✔️ | ✔️ |
| Query parameters | | ✔️ | ✔️ | ✔️ |
[`SpectraAssureApiOperationsList`](./doc/list.md)
**List all groups, projects, packages, and versions.**
| | Group | Project | Package | Version |
| -- | -- | -- | -- | -- |
| Targets | ✔️ | ✔️ | ✔️ | ✔️ |
| Query parameters | | | | |
[`SpectraAssureApiOperationsReport`](./doc/report.md)
**Download analysis report for a version.**
| | Group | Project | Package | Version |
| -- | -- | -- | -- | -- |
| Targets | | | | ✔️ |
| Query parameters | | | | ✔️ |
[`SpectraAssureApiOperationsScan`](./doc/scan.md)
**Upload and scan a new version.**
| | Group | Project | Package | Version |
| -- | -- | -- | -- | -- |
| Targets | | | | ✔️ |
| Query parameters | | | | ✔️ |
[`SpectraAssureApiOperationsStatus`](./doc/status.md)
**Show analysis status for a version.**
| | Group | Project | Package | Version |
| -- | -- | -- | -- | -- |
| Targets | | | | ✔️ |
| Query parameters | | | | ✔️ |
[`SpectraAssureApiOperationsSync`](./doc/sync.md)
**Sync a version.**
| | Group | Project | Package | Version |
| -- | -- | -- | -- | -- |
| Targets | | | | ✔️ |
| Query parameters | | | | |
[`SpectraAssureApiOperationsApprove`](./doc/approve.md)
**Approve a version.**
| | Group | Project | Package | Version |
| -- | -- | -- | -- | -- |
| Targets | | | | ✔️ |
| Query parameters | | | | ✔️ |
[`SpectraAssureApiOperationsReject`](./doc/reject.md)
**Reject a version.**
| | Group | Project | Package | Version |
| -- | -- | -- | -- | -- |
| Targets | | | | ✔️ |
| Query parameters | | | | ✔️ |
[`SpectraAssureApiOperationsRevoke`](./doc/revoke.md)
**Revoke a previously approved version.**
| | Group | Project | Package | Version |
| -- | -- | -- | -- | -- |
| Targets | | | | ✔️ |
| Query parameters | | | | ✔️ |
## 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](./LICENSE.MD).
## Versioning
| Version | Description |
| -- | -- |
| v1.0.2 | add version actions: `sync`, `approve`, `reject`, `revoke` |
| v1.0.1 | add `rl-uri` report |
| v1.0.0 | initial |
Raw data
{
"_id": null,
"home_page": null,
"name": "spectra-assure-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Rl devops <55623149+rl-devops@users.noreply.github.com>",
"keywords": "Python, ReversingLabs, Secure Software, Spectra Assure",
"author": "rl-devops",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# Spectra Assure SDK for Python\n\nSpectra Assure SDK for Python is the official library maintained by ReversingLabs that makes it easier to integrate with the [Spectra Assure Portal](https://docs.secure.software/portal/) and interact with it in your own applications.\n\nThe SDK provides access to operations supported by the [Spectra Assure Portal API](https://docs.secure.software/api/).\nThe Portal API only supports Portal Projects features, and cannot be used to work with the File Stream.\n\nYou can use the SDK to:\n\n- Create and delete projects and packages in the Portal\n- Add and remove package versions in the Portal\n- Update details for projects, packages, and versions\n- Get a list of all projects in a group, all packages in a project, all versions in a package, and show details for any package version\n- Show analysis status and performed checks for a package version\n- Download analysis reports for a package version\n- Download package versions previously approved in the Portal GUI\n\n\n> **Note:**\n> This documentation assumes that you already have a working knowledge of\n> Python and previous experience with setting up your own Python projects.\n\n\n**What is the Spectra Assure Portal?**\n\nThe Spectra Assure Portal is a SaaS solution that's part of the [Spectra Assure platform](https://www.reversinglabs.com/products/software-supply-chain-security) - a new ReversingLabs solution for software supply chain security.\nMore 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.\n\nWith the Spectra Assure Portal, you can:\n\n- Scan your software packages to detect potential risks before release.\n- Improve your SDLC by applying actionable advice from security scan reports to all phases of software development.\n- Organize your software projects and automatically compare package versions to detect potentially dangerous behavior changes in the code.\n- Manage software quality policies on the fly to ensure compliance and achieve maturity in your software releases.\n\n\n## Table of contents\n\n- [Requirements and dependencies](#requirements-and-dependencies)\n- [Installation](#installation)\n- [Authentication](#authentication)\n- [Quick start](#quick-start)\n - [Logging](#logging)\n- [Usage](#usage)\n - [Rate limiting](#rate-limiting)\n - [Configuration](#configuration)\n - [Validation](#validation)\n - [Exceptions](#exceptions)\n- [Reference](#reference)\n - [Operations](#operations)\n- [Support](#support)\n- [License](#license)\n- [Versioning](#versioning)\n\n\n## Requirements and dependencies\n\n- Python (minimal version: 3.10)\n- [requests](https://pypi.org/project/requests/) (version not critical)\n- 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](https://docs.secure.software/portal/members#invite-a-new-member). Alternatively, if you're not a Spectra Assure customer yet, you can [contact ReversingLabs](https://docs.secure.software/portal/#get-access-to-securesoftware-portal) to sign up for a Portal account.\n- A [Personal Access Token](https://docs.secure.software/api/generate-api-token) generated for your Spectra Assure Portal account.\n\n\n## Installation\n\nTo get started with the Spectra Assure SDK, install the latest version from PyPI with pip:\n\n`pip install spectra-assure-sdk`\n\nBy default, the SDK uses the Spectra Assure Portal API `v1` with `my.secure.software` as the host.\nThe default host and API version must not be modified by SDK users.\n\n\n## Authentication\n\nBefore using the Spectra Assure SDK, you need to set up authentication credentials for your Portal account.\n\nIf you don't already have it, generate a [Personal Access Token](https://docs.secure.software/api/generate-api-token) for your account.\n\nWhen you have the token, you can use it in any of the following ways:\n\n- in a JSON configuration file\n- with the `token` argument in your code\n\n[Roles and permissions](https://docs.secure.software/portal/user-management#roles-and-permissions) set for your Portal account automatically apply to your token, and control which actions you can perform.\n\nKeep in mind that Personal Access Tokens for Portal accounts have an expiration date.\nAfter a token expires, any apps or integrations relying on it for authentication will stop functioning.\nWhen this happens, you have to generate a new token and update it in all relevant places.\n\n\n## Quick start\n\nYou must import the `SpectraAssureApiOperations` class.\n\nTo start working with the SDK, initialize an instance of `SpectraAssureApiOperations` and specify all [required parameters](#usage).\n\n*Using named arguments is explicitly enforced - positional arguments are not supported in any of the SDK calls.*\n\nThe following code example shows how to combine different ways of specifying the required parameters (as named arguments, in a JSON configuration file, or both).\n\n**Python code example**\n\n```\nimport os\nfrom spectra_assure_api_client import SpectraAssureApiOperations\n\nprefix = \"RLPORTAL_\"\n\nserver = str(os.getenv(f\"{prefix}SERVER\"))\norganization = str(os.getenv(f\"{prefix}ORG\"))\ngroup = str(os.getenv(f\"{prefix}GROUP\"))\ntoken = str(os.getenv(f\"{prefix}ACCESS_TOKEN\"))\n\nconfigFile = \"./myConfig.json\"\n\nfor what in [1, 2, 3]:\n try:\n if what == 1:\n # Use only named arguments\n aHandle = SpectraAssureApiOperations(\n server=server,\n organization=organization,\n group=group,\n token=token,\n )\n elif what == 2:\n # Use only the configuration file\n # Note: with the current configFile example, this will fail because the token is not specified\n aHandle = SpectraAssureApiOperations(\n configFile=configFile,\n )\n elif what == 3:\n # Combine the configuration file with named arguments\n aHandle = SpectraAssureApiOperations(\n configFile=configFile,\n token=token,\n )\n print(aHandle)\n except Exception as e:\n print(e)\n```\n\n**Example configuration file - myConfig.json**\n\n```\n{\n \"SpectraAssureApi\" : {\n \"server\": \"test\",\n \"organization\": \"Test\",\n \"group\": \"Default\",\n \"timeout\": 60,\n \"auto_adapt_to_throttle\": true\n }\n}\n```\n\n\n### Logging\n\nThe SDK uses logging internally. You can interface with the logging functions in the SDK by using the standard Python logging library.\n\n**Logging example**\n\n```\nimport os\nimport logging\nimport sys\nfrom spectra_assure_api_client import SpectraAssureApiOperations\n\nlogger = logging.getLogger()\n\ndef make_logger(logger: logging.Logger) -> None:\n logger.setLevel(logging.DEBUG)\n\n progName = os.path.basename(sys.argv[0])\n if progName.endswith(\".py\"):\n progName = progName[:-3]\n fileName = f\"{progName}.log\"\n\n fh = logging.FileHandler(fileName)\n fh.setLevel(logging.INFO)\n\n ch = logging.StreamHandler()\n ch.setLevel(os.getenv(\"LOG_LEVEL\", \"WARNING\"))\n\n formatter = logging.Formatter(\"%(asctime)s - %(name)s - %(levelname)s - %(message)s\")\n ch.setFormatter(formatter)\n fh.setFormatter(formatter)\n\n # add the handlers to logger\n logger.addHandler(ch)\n logger.addHandler(fh)\n\nif __name__ == \"__main__\":\n make_logger(logger)\n logger.info(\"start program\")\n```\n\n\n## Usage\n\nThe following parameters are mandatory for all operations:\n\n- **server** - Name of the Portal instance to use in requests.\nThe Portal instance name usually matches the subdirectory of my.secure.software in your Portal URL.\nFor example, if your portal URL is 'my.secure.software/demo', the instance name to use with this parameter is 'demo'.\n- **organization** - Name of a Portal organization to use in requests.\nThe user account that is sending the request must be a member of the specified organization and have the appropriate\npermissions to perform the requested operation. Organization names are case-sensitive.\n- **group** - Name of a Portal group to use in requests. The group must exist in the specified Portal organization.\nGroup names are case-sensitive.\n- **token** - Personal Access Token for authenticating to the Portal API.\n\nThe following parameters are optional:\n\n- **timeout** - The request timeout to be used for HTTPS requests to the Portal API, specified in seconds.\nThe default is 10 seconds.\n\n- **auto_adapt_to_throttle** - Some requests may be\n[throttled](#rate-limiting)\nand require a minimal wait time before the next request.\nWith this option, you can automatically wait for the data to become available and for the required time to pass.\nBy default, this option is disabled (set to `false`).\nThis parameter can also be specified on each individual operation.\n\n\nSome operations support multiple targets (project, package, version) that have to be provided as named arguments.\nBased on the provided arguments, the library can automatically decide the target of the operation.\nThe first value of 'None' decides the target of the operation:\n\n```\n - project: str | None;\n If we don't have a project name,\n we are doing something with a group.\n - package: str | None;\n If we don't have a package name,\n we are doing something with a project.\n - version: str | None;\n If we don't have a version name,\n we are doing something with a package.\n - If all args are not None,\n we are doing something with a version.\n```\n\nRefer to the full list of [supported operations](#operations) for more details\non their usage and specific parameters they support.\n\n\n### Rate limiting\n\nRequests to the Spectra Assure Portal API are subject to rate limiting as defined in [the official API documentation](https://docs.secure.software/api-reference/#section/About-the-API/Rate-limiting).\n\nThis means that rate limits will also apply to requests sent by the SDK.\n\nOptionally, you can enable the `auto_adapt_to_throttle` setting globally\n(when creating the `SpectraAssureApiOperations` instance) or on each individual operation.\n\nBecause this setting may slow down responses, it is not recommended for interactive use.\nIt is most suitable for automatic batch processing.\n\n\n### Configuration\n\nThe SDK supports specifying mandatory and optional parameters in any of the following ways:\n\n- in a JSON configuration file\n- directly as named arguments in the code\n\nBy default, the configuration is evaluated and merged in that order: configuration file -> named arguments.\nIf a parameter is specified more than once, the latest stage overrides all previous instances.\nIn other words, if a parameter is set in the configuration file and as a argument,\nthe SDK will use the value from the argument.\n\nThe configuration file must be in JSON format.\nThe file name is arbitrary.\nThe file structure requires that all configuration parameters are placed as keys in the top-level `SpectraAssureApi`\nobject like in the following example:\n\n```\n{\n \"SpectraAssureApi\" : {\n \"server\": \"test\",\n \"organization\": \"Test\",\n \"group\": \"Default\",\n \"timeout\": 60,\n \"auto_adapt_to_throttle\": true\n }\n}\n```\n\nThe configuration file supports the following parameters:\n\n**Mandatory**\n\n- server: `string`\n- organization: `string`\n- group: `string`\n- token: `string`\n\n**Optional**\n\n- proxy_server: `string`\n- proxy_port: `int`\n- proxy_user: `string`\n- proxy_password: `string`\n- timeout: `int`\n- auto_adapt_to_throttle: `bool`\n\n\nAll `proxy_*` parameters are optional.\nHowever, if you're using `proxy_server`, then you must also use `proxy_port`.\nSimilarly, `proxy_user` and `proxy_password` must be used together.\n\n### Validation\n\nSome operations support additional query parameters with values that require validation\n(for example, strings that have limited length or enumerated values).\n\nThe SDK does not explicitly check all values - the validation is performed on the Portal side.\n\nBefore using query parameters, it is recommended to check their limitations in the\n[Portal API reference documentation](https://docs.secure.software/api-reference/) or in the [Portal OpenAPI specification](https://docs.secure.software/redocusaurus/secure-software-public-v1.yaml).\n\n\n### Exceptions\n\nAll operations return a `requests.Response` and may raise exceptions in case of errors or misconfiguration.\nIt is up to the SDK user to handle any exceptions.\n\nDepending on the operation and the type of issue, the following exceptions may be raised:\n\n- `SpectraAssureInvalidAction` - This action is not allowed\n- `SpectraAssureInvalidPath` - The specified path is incorrect\n- `SpectraAssureUnexpectedNoDataFound` - Received no data where we expected some\n- `SpectraAssureNoDownloadUrlInResult` - The query returns no download URL\n- `SpectraAssureUnsupportedStrategy` - Attempted download strategy is not supported\n- `UrlDownloaderUnknownHashKey` - No digest found; can't find the proper hash key or the hash type is not supported\n- `UrlDownloaderTargetDirectoryIssue` - The target file path does not exist or is not a directory\n- `UrlDownloaderTargetFileIssue` - The target file name can't be extracted from the URL\n- `UrlDownloaderTempFileIssue` - There is an issue with the target directory\n- `UrlDownloaderFileVerifyIssue` - Cannot calculate hash; verification failed\n\n\n## Examples\n\nAn example program showing all supported operations is available in this repository:\n[api_client_example.py](./examples/api_client_example.py)\n\n\n## Reference\n\nThe `doc` folder in the SDK GitHub repository contains reference pages for individual operations.\n\nYou can also consult the official\n[Spectra Assure Portal](https://docs.secure.software/portal/) and\n[API reference documentation](https://docs.secure.software/api/)\nfor more detailed instructions on specific features and functionalities.\n\n\n### Operations\n\nEvery class listed in this section maps directly to a Portal API operation,\nexcept **SpectraAssureApiOperationsDownload** which is a synthetic operation not directly available on the Portal.\n\nIf an operation supports query parameters, they should be provided in the `qp` argument list.\nAny invalid parameters will be automatically filtered out.\n\n[`SpectraAssureApiOperationsChecks`](./doc/checks.md)\n\n**Show performed checks for a version.**\n\n| | Group | Project | Package | Version |\n| -- | -- | -- | -- | -- |\n| Targets | | | | \u2714\ufe0f |\n| Query parameters | | | | |\n\n\n[`SpectraAssureApiOperationsCreate`](./doc/create.md)\n\n**Create a project or package in the Portal.**\n\n| | Group | Project | Package | Version |\n| -- | -- | -- | -- | -- |\n| Targets | | \u2714\ufe0f | \u2714\ufe0f | |\n| Query parameters | | \u2714\ufe0f | \u2714\ufe0f | |\n\n\n[`SpectraAssureApiOperationsDelete`](./doc/delete.md)\n\n**Remove a project, package, or version from the Portal.**\n\n| | Group | Project | Package | Version |\n| -- | -- | -- | -- | -- |\n| Targets | | \u2714\ufe0f | \u2714\ufe0f | \u2714\ufe0f |\n| Query parameters | | | | \u2714\ufe0f |\n\n\n[`SpectraAssureApiOperationsDownload`](./doc/download.md)\n\n**Download file(s) of approved version(s).**\n\nThis class uses `list` and `status` operations to gather information about what is downloadable,\nand only requests the artifact download URL for versions that are selected for download.\n\nEvery time the download link is generated, your Portal download capacity is reduced by the artifact's file size,\neven if the artifact is not downloaded from the link.\nIf your user account doesn't have permission to download files from the Portal,\nthe API responds with an error and the download capacity remains unaffected.\n\n\n[`SpectraAssureApiOperationsEdit`](./doc/edit.md)\n\n**Edit details for a project, package, or version.**\n\n| | Group | Project | Package | Version |\n| -- | -- | -- | -- | -- |\n| Targets | | \u2714\ufe0f | \u2714\ufe0f | \u2714\ufe0f |\n| Query parameters | | \u2714\ufe0f | \u2714\ufe0f | \u2714\ufe0f |\n\n\n[`SpectraAssureApiOperationsList`](./doc/list.md)\n\n**List all groups, projects, packages, and versions.**\n\n| | Group | Project | Package | Version |\n| -- | -- | -- | -- | -- |\n| Targets | \u2714\ufe0f | \u2714\ufe0f | \u2714\ufe0f | \u2714\ufe0f |\n| Query parameters | | | | |\n\n\n[`SpectraAssureApiOperationsReport`](./doc/report.md)\n\n**Download analysis report for a version.**\n\n| | Group | Project | Package | Version |\n| -- | -- | -- | -- | -- |\n| Targets | | | | \u2714\ufe0f |\n| Query parameters | | | | \u2714\ufe0f |\n\n\n[`SpectraAssureApiOperationsScan`](./doc/scan.md)\n\n**Upload and scan a new version.**\n\n| | Group | Project | Package | Version |\n| -- | -- | -- | -- | -- |\n| Targets | | | | \u2714\ufe0f |\n| Query parameters | | | | \u2714\ufe0f |\n\n\n[`SpectraAssureApiOperationsStatus`](./doc/status.md)\n\n**Show analysis status for a version.**\n\n| | Group | Project | Package | Version |\n| -- | -- | -- | -- | -- |\n| Targets | | | | \u2714\ufe0f |\n| Query parameters | | | | \u2714\ufe0f |\n\n[`SpectraAssureApiOperationsSync`](./doc/sync.md)\n\n**Sync a version.**\n\n| | Group | Project | Package | Version |\n| -- | -- | -- | -- | -- |\n| Targets | | | | \u2714\ufe0f |\n| Query parameters | | | | |\n\n[`SpectraAssureApiOperationsApprove`](./doc/approve.md)\n\n**Approve a version.**\n\n| | Group | Project | Package | Version |\n| -- | -- | -- | -- | -- |\n| Targets | | | | \u2714\ufe0f |\n| Query parameters | | | | \u2714\ufe0f |\n\n[`SpectraAssureApiOperationsReject`](./doc/reject.md)\n\n**Reject a version.**\n\n| | Group | Project | Package | Version |\n| -- | -- | -- | -- | -- |\n| Targets | | | | \u2714\ufe0f |\n| Query parameters | | | | \u2714\ufe0f |\n\n[`SpectraAssureApiOperationsRevoke`](./doc/revoke.md)\n\n**Revoke a previously approved version.**\n\n| | Group | Project | Package | Version |\n| -- | -- | -- | -- | -- |\n| Targets | | | | \u2714\ufe0f |\n| Query parameters | | | | \u2714\ufe0f |\n\n\n## Support\n\nTo get assistance with the Spectra Assure SDK,\nyou or your company need to have an existing support agreement with ReversingLabs.\nThen you can submit a support request with \"Spectra Assure SDK\" in the message subject.\n\nReversingLabs does not provide support if the original code from the official Spectra Assure SDK repository\nhas been modified by you or any other open source community members.\nIn those cases, contact the author(s) of the modified SDK for help.\n\n\n## License\n\nThe Spectra Assure SDK (Software Development Kit) for Python is released under [the MIT License](./LICENSE.MD).\n\n## Versioning\n\n| Version | Description |\n| -- | -- |\n| v1.0.2 | add version actions: `sync`, `approve`, `reject`, `revoke` |\n| v1.0.1 | add `rl-uri` report |\n| v1.0.0 | initial |\n",
"bugtrack_url": null,
"license": null,
"summary": "Python package for interfacing with the Spectra Assure Portal API.",
"version": "1.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/reversinglabs/spectra-assure-sdk/issues",
"Home Page": "https://github.com/reversinglabs/spectra-assure-sdk/",
"Repository": "https://github.com/reversinglabs/spectra-assure-sdk/"
},
"split_keywords": [
"python",
" reversinglabs",
" secure software",
" spectra assure"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "25ddfb4c89fe794010c294c6a19d03d2a4249680ba28b0d828c0ca21cf2711d5",
"md5": "5d00d0059b3d35fd1279c364a92d2ccf",
"sha256": "c28798e1047536265abb92f8a18627de1a5c601f01ccd5f45b527295905791b3"
},
"downloads": -1,
"filename": "spectra_assure_sdk-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5d00d0059b3d35fd1279c364a92d2ccf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 49963,
"upload_time": "2024-11-12T08:46:12",
"upload_time_iso_8601": "2024-11-12T08:46:12.649252Z",
"url": "https://files.pythonhosted.org/packages/25/dd/fb4c89fe794010c294c6a19d03d2a4249680ba28b0d828c0ca21cf2711d5/spectra_assure_sdk-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-12 08:46:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "reversinglabs",
"github_project": "spectra-assure-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "spectra-assure-sdk"
}
JSON
