Skip to main content

Troubleshooting Spectra Assure CLI

This troubleshooting guide provides solutions for common issues that might happen while you're working with the Spectra Assure CLI tools.

All issues are grouped by topic in the Troubleshooting topics section of this page. When an issue affects only a specific product version, it is indicated in the text.

The guide is intended for users with direct access to the Spectra Assure CLI tools.

Disclaimers and notices​

The information regarding the products in this guide is subject to change without notice. All statements, information, and recommendations in this guide are believed to be accurate but are presented without warranty of any kind, express or implied. Users must take full responsibility for their application of any products. In no event shall ReversingLabs be liable for any indirect, special, consequential, or incidental damages, including, without limitation, lost profits or loss or damage to data, arising out of the use or inability to use this guide, even if ReversingLabs has been advised of the possibility of such damages.

Safety messages​

Pay attention to call-out boxes in this guide, as their color and type indicates potential safety risk.

Specifically, the following two types of call-out boxes can contain safety messages:

caution

Caution messages are colored in yellow and optionally have more descriptive titles. They advise you about product limitations and actions that may be unsafe if performed incorrectly.

danger

Danger messages are colored in red and optionally have more descriptive titles. They warn you about actions that must be performed or avoided because of severe consequences, such as product malfunction, irreversible data loss, financial damage, or security breach.

General tips​

If the Spectra Assure CLI fails to run any of the supported commands, check the CLI output for error messages or instructions on how to resolve the issue.

The following checklist contains some general suggestions for troubleshooting the Spectra Assure CLI.

  • Make sure you're connected to the internet.
  • Confirm that your user account has permissions to run the CLI on your system.
  • Confirm you're using the latest CLI version and upgrade if necessary.
  • Confirm your license is valid and activated, and that you still have enough analysis capacity.
  • Check your command input for typos, missing or unnecessary characters, and incorrect package URL syntax.
  • Make sure the file you're trying to scan is officially supported, and convert it to another file format if necessary.
  • Check the command output for errors or useful pointers.
  • Create a new, empty package store and try to reproduce the issue there.
  • Use the search bar on this page to look up information about your issue in the documentation.

How to report issues​

If you can't find a solution to your problem in this guide or any other resource, reach out to ReversingLabs Support and report the issue.

Include the following information in your report:

  1. Issue description (explain what is happening and how it is different from the expected behavior)
  2. CLI version and OS/platform
  3. Steps to reproduce the problem
  4. CLI settings you have changed (if any)
  5. Logs, errors, and output messages (if any)
  6. Solutions and workarounds you have tried (if any)
Protect your information

Make sure there's no confidential information in your issue report, and that you have the permission to share any business-critical details.

Troubleshooting topics​

If you are experiencing issues with the Spectra Assure CLI, check if they have already been reported in this section.

Installation and licensing​

CLI installation or license activation fails​

The Spectra Assure CLI requires access to the ReversingLabs cloud for licensing purposes. The CLI needs to verify your license during the installation, and update your analysis capacity when you scan new packages.

In some cases, the installation may fail even if your system is connected to the internet. This can happen if your system uses a firewall or connects to the internet through a proxy. Your network configuration may be blocking access to the required endpoints in the ReversingLabs cloud.

Possible solutions

  • Allow the following required resources in your network configuration or endpoint protection tools:

    • data.reversinglabs.com
    • api.reversinglabs.com

Scanning and analysis​

rl-secure scan or rl-secure sync commands fail​

In some cases, the rl-secure scan or rl-secure sync commands may fail to analyze your software package. Syntax errors in policy configuration files frequently cause this issue. The command output usually contains relevant error messages that indicate the cause of the failure. You can use that information to resolve the issue. However, re-running the same command after resolving the issue may not always be successful.

Possible solutions

  • Check your policy configuration files for any syntax errors and correct them.
  • After resolving the issue, run rl-secure clean first, then repeat the rl-secure scan or rl-secure sync command that previously failed.

Windows-specific issues​

Antivirus scanners interfere with the CLI​

The Spectra Assure CLI creates a temporary work directory inside the package store while scanning software packages. That directory contains the software packages submitted for analysis while they're being unpacked. The work directory is automatically removed by the CLI when it is no longer needed. Users can also manually remove it with the rl-secure clean command if necessary.

Even if the work directory contains any malicious files, they are never executed on the system because the CLI only performs static analysis.

However, antivirus scanners, firewalls, and other endpoint detection solutions on Windows systems may attempt to scan the work directory. They may report a false positive and cause the CLI to crash if they block access to the files in the work directory.

Possible solutions

  • Add the CLI work directory to the exclusion list or similar configuration in your endpoint detection tools to prevent them from scanning it.

    By default, the work directory is located in the package store root (your-package-store/.rl-secure/work). If you're using the --work-dir option to create the work directory in different locations, you must add those custom paths to the exclusion list as well.

File system limitation error on NTFS​

The Spectra Assure CLI for Windows could throw the ERROR_FILE_SYSTEM_LIMITATION (665) error while processing software packages containing a large number of files. This issue arises only when using the NTFS file system. Due to some existing problems with fragmentation, NTFS has trouble saving software package metadata. All errors that occur during the analysis are logged.

Possible solutions

  • On Windows, it's recommended to use ReFS for processing software packages containing a large number of files.