# Spectra Analyze Documentation > Malware analysis appliance documentation including setup, API, administration, and sample analysis. This file contains all documentation content in a single document following the llmstxt.org standard. ## Getting started with Spectra Analyze This guide walks you through your first malware analysis with Spectra Analyze. You will configure the Spectra Intelligence cloud connection, upload a file, view the analysis report, and understand the classification result. ## Prerequisites Before you begin: - Spectra Analyze is deployed and accessible on your network (hardware appliance, OVA, or cloud instance) - You have login credentials (username and password) - Your browser is up to date (Chrome recommended) If you have not yet deployed Spectra Analyze, see [Setup and initial configuration](./initial-configuration.md). **Tip: Initial credentials** Your initial administrator username and password are provided by [ReversingLabs Support](mailto:support@reversinglabs.com). Change the default password after your first login. ## Step 1: Configure the Spectra Intelligence cloud connection Spectra Analyze enriches every analyzed file with data from [Spectra Intelligence](/SpectraIntelligence/) — a cloud threat intelligence service that provides scanner results, threat names, and community classifications. Without this connection, Spectra Analyze still performs local static analysis, but enrichment data will be missing from reports. 1. Navigate to **Administration > Configuration > Spectra Intelligence**. 2. Enter your Spectra Intelligence **username** and **password**. 3. Select **Test connection** to confirm the appliance can reach `appliance-api.reversinglabs.com`. 4. Select **Save**. If the connection test fails, verify that your network allows outbound HTTPS (port 443) to `appliance-api.reversinglabs.com`. You may also need to allowlist the Cloudflare IP ranges and `185.64.132.0/22`. See [IP/domain allowlisting](./initial-configuration.md#ipdomain-allowlisting) for details. **Note: If you do not yet have Spectra Intelligence credentials, contact [ReversingLabs Support](mailto:support@reversinglabs.com).** ## Step 2: Access the web interface Open your browser and navigate to the Spectra Analyze appliance URL provided by your administrator (for example, `https://spectra-analyze.example.com`). Log in with your credentials. After logging in, you land on the **Dashboard**, which shows recent analysis activity and system status. ## Step 3: Upload a file for analysis 1. Select **Submit** from the header bar. 2. Select the file you want to analyze. Supported formats include executables, archives, documents, and mobile apps — over 400 formats in total. 3. Optionally add a comment or tags to help organize your results later. 4. Select **Upload**. Spectra Analyze submits the file to [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) for static analysis. Most files complete analysis within seconds. ## Step 4: View the analysis report When analysis completes, the file appears in your results list. Select the file to open its **Sample Details** page. The report includes: - **Classification** — Malicious, Suspicious, Goodware, or Unknown, with a risk score from 0 to 10 - **Threat name** — For malicious files, the malware family name - **Indicators** — Extracted behavioral indicators mapped to [MITRE ATT&CK](https://attack.mitre.org/) tactics - **Extracted files** — Child files unpacked from archives or installers - **Metadata** — File hashes, format details, certificate information See [Sample Details](./Sample%20Details/index.md) for a full explanation of every report field. ## Step 5: Understand your results Spectra Analyze classifies every analyzed file and assigns a risk score. This section explains how to read and interpret that classification. **Info: Read more about the ReversingLabs [classification algorithm](/General/AnalysisAndClassification/Classification).** ### Color coding and sample status Spectra Analyze uses consistent color coding throughout the interface to indicate sample classification and risk. ![Four colors (left to right: red indicating malicious, green indicating goodware, orange indicating suspicious, and dark gray indicating no threats were found) used in the interface to indicate sample status](images/a1000-cheatsheet-color-intro.png) Inside each symbol is the sample's risk score. Samples with no threats found do not have a risk score. Samples with a risk score of 5 are represented using a unique icon. The indicators found during analysis were deemed insufficient to classify the file as definitively malicious or benign. These samples have a higher chance of changing classification if new information becomes available. Color-coded indicators appear in the following parts of the interface: - **YARA page** — statistics about ruleset matches ![Section of the YARA page showing color-coded status for YARA rulesets](images/a1000-cheatsheet-yara-rulesets.png) - **Sample Details page** — as the background color of the Report Summary Header ![Upper part of the Sample Details page with numbered indicators showing color-coded sample status](images/a1000-cheatsheet-circles.png) - **How We Caught This tab** — in the File Similarity and File Classifications sections ![Section of the Sample Details page with numbered indicators showing color-coded sample status](images/a1000-cheatsheet-circles4.png) - **URI stats** — on the Interesting Strings, Network References, and Malware Configurations tabs ![Network References section of the Sample Details page with color-coded indicators of sample status](images/a1000-cheatsheet-circles3.png) ### Understanding the risk score The risk score is a numerical value from 0 to 10 that indicates the severity of the classification. | Risk score | Classification | Meaning | |---|---|---| | 0 | Unknown | Not enough information to classify | | 1 | Goodware | Known-clean file | | 2–4 | Suspicious | Concerning indicators, not confirmed malicious | | 5 | Suspicious | Insufficient indicators to confirm malicious or benign; classification may change | | 6–10 | Malicious | Confirmed malware; higher scores indicate greater severity | Risk scores are assigned by the severity of the detected threat. Values from 0 to 5 are reserved for samples classified as goodware or known. Lesser threats like adware get a risk score of 6, while ransomware and trojans always get a risk score of 10. Some users may choose to ignore lower risk classifications, but those samples are still classified as malicious to warn about potential threats, such as installers that have embedded adware. Some Spectra Analyze APIs return sample classification as a numerical value: `0` for unknown, `1` for goodware, `2` for suspicious, and `3` for malicious. ### Understanding the classification reason The classification reason specifies which technology detected a threat. Files usually have multiple detections from more than one classifier, but the classification reason tile specifies which one produced the final classification. The final classification always matches one of the classifiers, but individual classifiers may have differing results between them. Due to differences in how different malicious samples and malware families behave, some samples might end up classified as malicious by one technology, and still be considered goodware by others. This does not negate or diminish the final classification — it is why Spectra Analyze uses multiple sources to classify files. Overlooking the classification reason may result in confusion. For example, adding custom YARA rules to Spectra Analyze is a powerful malware hunting feature, but improperly written rulesets can be too broad and result in a large number of samples suddenly getting classified as malicious by a YARA rule, even though everything else points to goodware. On the **Sample Details** page, the **How We Caught This** tab shows: - **File Similarity** — whether the file matches known malicious or clean samples in the Spectra Intelligence database - **File Classifications** — the specific YARA rules, threat names, or scanner results that contributed to the classification Reviewing the classification reason helps you assess whether the result is expected and whether further investigation is needed. ### Understanding threat propagation Threat propagation is the mechanism by which classification spreads from a child file to its parent. When Spectra Analyze unpacks an archive or installer, it analyzes every contained object. If a child file is classified as malicious, that classification propagates upward to the parent. This means a container file such as a ZIP archive can receive a malicious classification even if the archive itself contains no malicious code — the threat is in its contents. The **Extracted Files** section of the Sample Details page shows the full unpacked file tree and the classification of each object. ### Administering classification overrides Classifications can be overridden either through Goodware Overrides, where the classification of a high-trust parent sample is propagated down to extracted files, or manually by using the Spectra Analyze override feature. If you disagree with a classification, you can override it manually. Overrides are useful when a file is misclassified due to incomplete intelligence data or when internal tooling triggers a false positive. To override a classification: 1. Open the **Sample Details** page for the file. 2. Select **Override classification**. 3. Select the correct classification and provide a reason. 4. Select **Save**. In cases where the classification was set by the user, it is considered final and displayed in the header, as well as in the table below. Local classification overrides are visible as final to all appliance users, while the Spectra Intelligence overrides are additionally synchronized with other appliances using the same Spectra Intelligence account, and other Spectra Intelligence accounts belonging to the same company, indicated by the middle segment of the username — `u/company/user`. In cases where a sample has both overrides, the local override is displayed as the final classification. Overrides are visible to all users on the appliance and are logged for audit purposes. See [Classification](/General/AnalysisAndClassification/Classification/) for details on how scoring works and how overrides interact with threat propagation. ### Understanding the overall classification The overall classification shown at the top of the Sample Details page represents the final verdict for the submitted file, taking into account: - The file's own static analysis results - Threat propagation from any extracted child files - Any applied classification overrides - Enrichment data from Spectra Intelligence In most cases, analysis results are overwhelmingly biased towards a certain classification: a malicious file will be detected as such by Spectra Core and backed up by a large percentage (not necessarily 100%) of scanner detections. It will probably have an exact threat name, naming the malware type or the specific malware family. Certain file types might belong to a RHA File Similarity bucket with other malicious files. Even if such files get some negative results from specific technologies, it is highly unlikely that they are not malicious. On some occasions, a sample classified as goodware can still have some Spectra Intelligence scanner detections, but not enough to affect the final classification. These detections are most likely false positives, but users are still advised to check the scanner list to see which scanners detected a threat. In conclusion, while false detections are not impossible, they are much easier to identify if all of the important factors are considered and understood. For more information, see [Classification](/General/AnalysisAndClassification/Classification/) and [Risk Score Table](/General/AnalysisAndClassification/RiskScoreTable/). When a file has been overridden, the interface distinguishes between the original classification and the overridden classification so you can always see both the automated result and the manual correction. ### MITRE ATT&CK integration Spectra Analyze maps indicators detected during static analysis to the MITRE ATT&CK framework. When a sample's analysis reveals indicators that correspond to known ATT&CK tactics and techniques, they are displayed in the ATT&CK section of the Sample Details page. This mapping helps analysts correlate file-level findings with adversary behaviors documented in the ATT&CK knowledge base. ## Next steps - [Search for files](./search-page.md) — query your analyzed file collection - [YARA rules](./yara.md) — write and deploy custom detection rules - [API Documentation](./API%20Documentation/index.md) — automate file submissions and retrieve results programmatically - [Dashboard](./dashboard.md) — monitor appliance health and throughput --- ## Spectra Analyze — Malware Analysis for Threat Analysts Spectra Analyze is a malware analysis solution designed for individual analysts and small teams. It combines deep static file analysis with cloud threat intelligence to accelerate threat detection, investigation, and collaboration. Spectra Analyze is available as a hardware/software appliance or as a cloud-based service. ## Introduction Spectra Analyze is powered by [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis), the ReversingLabs engine for automated static decomposition and analysis of binary files. When you submit a file, Spectra Core identifies the file format and unpacks it to extract all available information from every contained object. Spectra Core can identify more than 4000 file formats and unpack more than 400 of them, including PE packers, archives, installation packages, firmware images, documents, and mobile applications. Once unpacked, Spectra Core extracts metadata from each file: strings, format header details, function names, library dependencies, file segments, and static behavior analysis with capability information. This data is combined with threat intelligence from Spectra Intelligence, a cloud service that provides scanner results, threat names, and community classifications, to produce a complete analysis report. The result is a classification of each analyzed file as malicious, suspicious, goodware, or unknown, along with a risk score and the indicators that drove the result. For more information about the latest features, see the [Spectra Analyze website](https://www.reversinglabs.com/products/spectra-analyze). **Tip: New to Spectra Analyze?** See [Getting Started](./getting-started.md) to configure your first cloud connection, upload a file, and interpret your first analysis report. ## Navigating the Interface This section describes the layout of the Spectra Analyze interface, including the terminology and visual indicators used throughout the appliance and its documentation. ### Global Header Bar The global header bar runs across the top of every page in the Spectra Analyze interface. It contains the most commonly used controls and the main navigation menu. From left to right: - **Search Samples** is a text field for entering search queries. Clicking the field expands it across the header bar and hides other menu items to give more space for constructing queries. Performing a search navigates to the **Advanced Search** page. See [Advanced Search](./advanced-search.md). - **Submit** opens the file and URL submission dialog. An upload progress bar appears in the header bar while files are uploading. Navigating away from the page or refreshing the browser during an upload will cancel it. See [File and URL Submissions](./file-submissions.md). - **Dashboard** displays submission and processing statistics for a specified time range. See [Dashboard](./dashboard.md). - **Search & Submissions** provides access to the Advanced Search feature for querying analyzed files across local and global Spectra Intelligence data sets. See [Search & Submissions Page](./search-page.md). - **YARA** allows rule-based identification and classification of files using text or binary patterns. If this item is not visible, it can be enabled under **Administration > User Roles**. See [YARA Hunting](./yara.md). - **Graph** provides an interactive visualization of relationships between malware samples, files, domains, IPs, and other entities. See [Graph Page](graph.md). - **Help** contains links to appliance documentation, ReversingLabs support, and the legend for risk score indicators. - **Quota Indicator** (pie chart icon) shows the current usage status of all ReversingLabs APIs configured on the appliance that have a limited quota. - **Alerts Indicator** enables real-time monitoring of changes in malware classification and analysis results. If there are unresolved alerts, their count appears as a red badge on the indicator. See [Alerts](./alerts.md). - **Health Status Indicator** shows the current status of the appliance. See [Health Status Indicator](#health-status-indicator) below. - **User menu** shows the current username and provides access to Administration, User Profile, and Log Out. - **Risk Tolerance** shows the current risk tolerance level for the appliance, if enabled. See [Risk Tolerance Levels](./Administration/users-personalization/risk-tolerance-levels.md). ### Health Status Indicator The second to last item in the main appliance menu is the health status indicator, pointing out issues with the system load and showing if the appliance is connected to a file reputation service, and if the service is reachable or not. Administrators can click the icon to open a pop-up with a more granular look at the system resources: Disk Usage, Memory usage, CPU utilization, outstanding alerts and issues, and Spectra Detect Manager connection status. The pop-up also contains a link to [Open System Status page](./Administration/usage-alerts/system-status/) with detailed information on all the system monitoring services. Thresholds for these services, such as CPU/memory/disk usage or queue sizes, are configured on the [Administration > Configuration > System Health](./Administration/configuration-update/configuration/#system-health) page. If there are no issues with the system load and if the appliance is connected to Spectra Intelligence or the T1000 File Reputation Appliance, this is indicated by a black icon. A red icon with a small exclamation mark means that the reputation service is not configured or reachable or that CPU/memory/disk usage or queue sizes went over the configured thresholds. In this case, hovering over the icon lists the detected issues. ![description](images/analyze-status-indicator.png) The services used to deliver file reputation data (Spectra Intelligence or T1000 File Reputation Appliance) can be configured under **Administration > Configuration** in the [Spectra Intelligence](./Administration/configuration-update/configuration/#spectra-intelligence) and [T1000 File Reputation Appliance](./Administration/configuration-update/configuration/#t1000-file-reputation-appliance) dialogs. --- ## Setup and initial configuration ## Setup and configuration checklist ✅ Ensure [system requirements](#system-requirements) are met. ✅ [Import](#importing-the-appliance-image) the appliance image. ✅ Perform the [initial configuration](#initial-system-configuration-via-console) via console. ✅ [Log in](#first-login-to-spectra-analyze) and [update administrator credentials](#change-default-administrator-credentials). ✅ [License](#appliance-licensing) the appliance. ✅ Update your [user profile](#user-profile) as needed. **Info: For assistance with Spectra Analyze setup, contact [ReversingLabs Support](mailto:support@reversinglabs.com).** ## System requirements ### Minimum system requirements The minimum system requirements are: - 1 TB of SSD storage - 8 CPU cores - 32 GB RAM These are the minimum resource settings, and are fine for average use with dozens of samples per day. The settings might have to be adjusted upwards depending on the expected usage. ### Recommended system requirements For heavier usage, the recommended settings are: - 2 TB of SSD storage - 12 CPU cores - 64 GB RAM **Info: Spectra Analyze configured to use the recommended settings can analyze 7 or more samples per minute. File retention should be set to 7 days, as the performance drops off by 5-10% per week with longer retention times.** ### Hosted instances For hosted instances, ReversingLabs provides the following resources: - 512 GB of storage - 16 CPU cores - 64 GB RAM Hosted instances support up to 10 000 files per day with a 3-month retention period depending on the file size. ## Importing the appliance image The package contains the following files: ``` a1000.md5 a1000.ova ``` The .md5 file contains the plain text MD5 hash of the .ova file for file integrity verification. The .ova file utilizes the VMDK disk format and can be imported by ESXi version 5.5 or higher. The following screenshots show how to import the .ova file in vSphere Version 5.5, hypervisor ESXi 5.5: ![../_images/analyze-installation-1.png](images/analyze-installation-1.png)![../_images/analyze-installation-2.png](images/analyze-installation-2.png)![../_images/analyze-installation-3.png](images/analyze-installation-3.png)![../_images/analyze-installation-4.png](images/analyze-installation-4.png)![../_images/analyze-installation-5.png](images/analyze-installation-5.png)![../_images/analyze-installation-6.png](images/analyze-installation-6.png)![../_images/analyze-installation-7.png](images/analyze-installation-7.png) ## Initial system configuration via console For physical appliances, first connect a keyboard, mouse and display to access and interact with the console menu. When the appliance is running, either as a physical device or in the virtual environment, the following configuration screen is used to configure it after completing the installation. ![../_images/analyze-initial-console-setup.png](images/analyze-initial-console-setup.png) To select an option, enter the menu item number and follow the prompts. The menu contains the following options: 1. Change the hostname. 2. Select the network interface. 3. Set static IP. Mutually exclusive setting with dynamic IP via DHCP. 4. Set dynamic IP via DHCP. Mutually exclusive setting with static IP. 5. Configure 2 DNS servers. 6. Configure up to 4 NTP servers. 7. Configure SNMP and set the SNMP community string. 8. Change the password for the "admin" user. 9. Shut down or restart the appliance. To restart the appliance after modifying the settings, enter the number next to `Shutdown / Restart`, then answer "n" to the shutdown question and "y" to the restart question. The console configuration tool does not provide any detailed success messages in response to configuring the network settings. To continue working with the appliance after the initial setup, open the web browser and enter the appliance IP address displayed in the console configuration tool. ### Network ports The Spectra Analyze appliance supports the following ports for inbound connections: - 80/TCP and 443/TCP for connecting to the web interface. - 161/UDP for SNMP monitoring. Outgoing connections to the internet via the following ports are also supported: - 53/UDP for DNS. - 123/UDP for NTP. However, it is strongly recommended that users configure the system to use their own DNS and NTP infrastructure if necessary. For outgoing connections to Spectra Intelligence at **https://appliance-api.reversinglabs.com**, the destination port is 443/TCP. The DNS name is **appliance-api.reversinglabs.com** and the connection supports HTTPS only. ### IP/domain allowlisting It is necessary to allowlist certain IP ranges and domains for connectivity with our cloud-based services. The primary range to allowlist is Cloudflare's public IP range, as outlined in their [official documentation](https://www.cloudflare.com/en-gb/ips/). Additionally, allowlist the IP range `185.64.132.0/22`, which covers various ReversingLabs endpoints crucial for full functionality and communication between your systems and the Spectra Analyze appliance. Furthermore, if the **Enable Spectra Analyze Networking Toolkit** option is enabled, the appliance attempts to gather additional network data from trusted sources such as `whois`, `bgpview.io`, `GeoLite City`, and DNS services. ## First login to Spectra Analyze From a web browser, visit the host address configured in the [Initial system configuration via console](./initial-configuration.md#initial-system-configuration-via-console) section to access the login screen of the Spectra Analyze web interface. If the Spectra Analyze is configured to support OpenID authentication, additional login options are displayed under the default login form. ![../_images/analyze-login.png](images/analyze-login.png) Log in using the default case-sensitive administrator credentials for the Spectra Analyze web application, provided by [ReversingLabs Support](mailto:support@reversinglabs.com). Failed login attempts are recorded in the appliance logs and visible in the `/var/log/rlapp/rlapp.log` file. Once the user logs in, a popup window is displayed for all accounts on the appliance. The popup contains the latest release highlights, informing the users about the changes delivered in the new Spectra Analyze version. Users can dismiss the popup, and it is not displayed on subsequent logins. To view the popup again at any time, go to the appliance footer, and click **What’s New**. ### Change default administrator credentials #### Password After logging in, look for the password change notice at the top of the page. Click the ***your password*** link and change the administrator account password in the dialog that opens. Alternatively, from the top navigation bar go to the 👤 **> [User Profile](#user-profile)** page with additional configuration options, and update your password from there. If password requirements are configured on the appliance under [Administration > Configuration > Configuration & Update > Authentication](../Administration/configuration-update/configuration/#authentication), the new administrator account password must comply with them. #### Email The email address associated with the default administrator account should also be changed. If you need to reset your password, on the [Login](#first-login-to-spectra-analyze) screen, click the ***Forgot your password?*** link. The emails sent from the appliance go to the email address associated with the administrator account. To change the email address, go to [Administration > Users & Personalization > Users](../Administration/users-personalization/users/) and [search](../Administration/users-personalization/users/#searching-for-users) for the "admin" user. Click it to open the **Change user** dialog and [modify](../Administration/users-personalization/users/#editing-users) the email address specified there. ## Appliance licensing On first login after installing or updating the appliance, the appliance must be licensed. For detailed instructions, see [Licensing](../Administration/configuration-update/licensing/). ## User Profile To update the current user's profile, go to 👤 **> User Profile**. The **User Profile** page contains options for configuring the profile of the user currently logged into the appliance, and for managing alert subscriptions. ### Profile Under **Profile**, modify the current user's profile. Apart from setting a first name, last name, and email address, users can also change the password for logging into the appliance. If password requirements are configured on the appliance, the new user account password must comply with them. The **Profile** section displays a warning if the new password does not satisfy the configured password requirements. To save your changes, click **Submit**. ### Alerts Configuration Under **Alerts Configuration**, you can see all alert subscriptions for the current user. For more information, see [Managing Alert Subscriptions and Delivery Methods](../alerts/#managing-alert-subscriptions-and-delivery-methods). --- ## Appendix: Technical Reference — Spectra Analyze Administration ## Overview This section provides a technical reference for some of the Spectra Analyze appliance configuration options. ## SNMP trap thresholds **Info: For more information, see [SNMP](../configuration/#snmp).** The Spectra Analyze appliance can receive notifications, or traps, about important system events via the Simple Network Management Protocol (SNMP). Traps used for monitoring the average system load, and memory and disk usage, are generated by the Distributed Management Event Management Information Base (MIB): *DISMAN-EVENT-MIB::mteTriggerFired*. Traps related to Spectra Detect and classification queue sizes are generated by the *tswQueueThreshold* MIB. To enable SNMP traps and configure the address of the trap sink server, adjust the values in the [Administration > Configuration & Update > Configuration > SNMP](../configuration/#snmp) dialog on the Spectra Analyze appliance. The dialog also allows setting thresholds for **Supported events**, described in more detail below. ### Average system load This trap is sent if the average load of the local system exceeds specified values of 1-minute, 5-minute or 15-minute averages. Values should be provided as percentages, which are recalculated into appropriate thresholds as reported with `uptime` or `top` commands. The following examples show traps triggered by a high 1-minute, 5-minute and 15-minute system load average respectively: ``` 2018-01-26 14:35:54 [UDP: [192.168.123.247]:60418->[192.168.123.17]:162]: DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (13) 0:00:00.13 SNMPv2-MIB::snmpTrapOID.0 = OID: DISMAN-EVENT-MIB::mteTriggerFired DISMAN-EVENT-MIB::mteHotTrigger.0 = STRING: laTable DISMAN-EVENT-MIB::mteHotTargetName.0 = STRING: DISMAN-EVENT-MIB::mteHotContextName.0 = STRING: DISMAN-EVENT-MIB::mteHotOID.0 = OID: UCD-SNMP-MIB::laErrorFlag.1 DISMAN-EVENT-MIB::mteHotValue.0 = INTEGER: 1 UCD-SNMP-MIB::laNames.1 = STRING: Load-1 UCD-SNMP-MIB::laErrMessage.1 = STRING: 1 min Load Average too high (= 2.56) ``` ``` 2018-01-26 14:35:54 [UDP: [192.168.123.247]:60418->[192.168.123.17]:162]: DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (13) 0:00:00.13 SNMPv2-MIB::snmpTrapOID.0 = OID: DISMAN-EVENT-MIB::mteTriggerFired DISMAN-EVENT-MIB::mteHotTrigger.0 = STRING: laTable DISMAN-EVENT-MIB::mteHotTargetName.0 = STRING: DISMAN-EVENT-MIB::mteHotContextName.0 = STRING: DISMAN-EVENT-MIB::mteHotOID.0 = OID: UCD-SNMP-MIB::laErrorFlag.2 DISMAN-EVENT-MIB::mteHotValue.0 = INTEGER: 1 UCD-SNMP-MIB::laNames.2 = STRING: Load-5 UCD-SNMP-MIB::laErrMessage.2 = STRING: 5 min Load Average too high (= 2.00) ``` ``` 2018-01-26 14:35:54 [UDP: [192.168.123.247]:60418->[192.168.123.17]:162]: DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (13) 0:00:00.13 SNMPv2-MIB::snmpTrapOID.0 = OID: DISMAN-EVENT-MIB::mteTriggerFired DISMAN-EVENT-MIB::mteHotTrigger.0 = STRING: laTable DISMAN-EVENT-MIB::mteHotTargetName.0 = STRING: DISMAN-EVENT-MIB::mteHotContextName.0 = STRING: DISMAN-EVENT-MIB::mteHotOID.0 = OID: UCD-SNMP-MIB::laErrorFlag.3 DISMAN-EVENT-MIB::mteHotValue.0 = INTEGER: 1 UCD-SNMP-MIB::laNames.3 = STRING: Load-15 UCD-SNMP-MIB::laErrMessage.3 = STRING: 15 min Load Average too high (= 2.05) ``` ### Used memory This trap is sent if used memory on the local system exceeds the specified percentage. The default value is 80%. The following example shows an event triggered by memory usage that exceeded the configured trap threshold: ``` DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (8) 0:00:00.08 SNMPv2-MIB::snmpTrapOID.0 = OID: DISMAN-EVENT-MIB::mteTriggerFired DISMAN-EVENT-MIB::mteHotTrigger.0 = STRING: memoryFree DISMAN-EVENT-MIB::mteHotTargetName.0 = STRING: DISMAN-EVENT-MIB::mteHotContextName.0 = STRING: DISMAN-EVENT-MIB::mteHotOID.0 = OID: UCD-SNMP-MIB::memTotalFree.0 DISMAN-EVENT-MIB::mteHotValue.0 = INTEGER: 2124816 UCD-SNMP-MIB::memTotalReal.0 = INTEGER: 16467096 kB ``` ### Used disk space This trap is sent if used disk space on any of the mounted disks exceeds the specified percentage. The default value is 90%. The following example shows an event triggered by a disk with less than 10% of free disk space on the /boot partition: ``` DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (25) 0:00:00.25 SNMPv2-MIB::snmpTrapOID.0 = OID: DISMAN-EVENT-MIB::mteTriggerFired DISMAN-EVENT-MIB::mteHotTrigger.0 = STRING: dskTable DISMAN-EVENT-MIB::mteHotTargetName.0 = STRING: DISMAN-EVENT-MIB::mteHotContextName.0 = STRING: DISMAN-EVENT-MIB::mteHotOID.0 = OID: UCD-SNMP-MIB::dskErrorFlag.26 DISMAN-EVENT-MIB::mteHotValue.0 = INTEGER: 1 UCD-SNMP-MIB::dskPath.26 = STRING: /boot UCD-SNMP-MIB::dskErrorMsg.26 = STRING: /boot: less than 10% free (= 8%) ``` ### Spectra Detect queue size This trap is sent if the number of messages in any of the queues used for Spectra Detect communication exceeds the specified value. Since the check is performed once every minute, it is possible to have the peak message count in the queue higher than the threshold, if the duration of the peak was shorter than 1 minute. Logged events have two values, the name of the queue that triggered the event and the size of the queue at the moment the event was triggered. ### Classifications queue size This trap is sent if the number of messages in any of the queues used for classifications exceeds the specified value. Since the check is performed once every minute, it is possible to have the peak message count in the queue higher than the threshold, if the duration of the peak was shorter than 1 minute. Logged events have two values, the name of the queue that triggered the event and the size of the queue at the moment the event was triggered. ### Spectra Analyze MIB descriptions | MIB Module | Value | OID | Description | |---------------|-----------------------------------|-----------------------------------|-----------------------------------------------------| | RL-MIB | `device` | .1.3.6.1.4.1.48699.1.1 | | | RL-MIB | `a1000` | .1.3.6.1.4.1.48699.1.1.2 | | | RL-TCBASE-MIB | `tcbMib` | .1.3.6.1.4.1.48699.1.1.2.1 | | | RL-TCBASE-MIB | `tcbMibObjects` | .1.3.6.1.4.1.48699.1.1.2.1.1 | | | RL-TCBASE-MIB | `tcbScalars` | .1.3.6.1.4.1.48699.1.1.2.1.1.1 | | | RL-TCBASE-MIB | `tcbQueuesApiLongState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.1 | State for api_longrunning queue. | | RL-TCBASE-MIB | `tcbQueuesApiLongCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.2 | Number of consumers for api_longrunning queue. | | RL-TCBASE-MIB | `tcbQueuesApiLongMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.3 | Number of messages for api_longrunning queue. | | RL-TCBASE-MIB | `tcbQueuesApiReqsState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.4 | State for api_requests queue. | | RL-TCBASE-MIB | `tcbQueuesApiReqsCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.5 | Number of consumers for api_requests queue. | | RL-TCBASE-MIB | `tcbQueuesApiReqsMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.6 | Number of messages for api_requests queue. | | RL-TCBASE-MIB | `tcbQueuesCeleryState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.7 | State for celery queue. | | RL-TCBASE-MIB | `tcbQueuesCeleryCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.8 | Number of consumers for celery queue. | | RL-TCBASE-MIB | `tcbQueuesCeleryMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.9 | Number of messages for celery queue. | | RL-TCBASE-MIB | `tcbQueuesDefaultState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.10 | State for default queue queue. | | RL-TCBASE-MIB | `tcbQueuesDefaultCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.11 | Number of consumers for default queue. | | RL-TCBASE-MIB | `tcbQueuesDefaultMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.12 | Number of messages for default queue. | | RL-TCBASE-MIB | `tcbQueuesTasksApiState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.13 | State for tasks.api queue. | | RL-TCBASE-MIB | `tcbQueuesTasksApiCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.14 | Number of consumers for tasks.api queue. | | RL-TCBASE-MIB | `tcbQueuesTasksApiMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.15 | Number of messages for tasks.api queue. | | RL-TCBASE-MIB | `tcbQueuesTasksApiLongState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.16 | State for tasks.api.longrunning queue. | | RL-TCBASE-MIB | `tcbQueuesTasksApiLongCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.17 | Number of consumers for tasks.api.longrunning queue. | | RL-TCBASE-MIB | `tcbQueuesTasksApiLongMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.18 | Number of messages for tasks.api.longrunning queue. | | RL-TCBASE-MIB | `tcbQueuesTasksApiReqState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.19 | State for tasks.api.requests queue. | | RL-TCBASE-MIB | `tcbQueuesTasksApiReqCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.20 | Number of consumers for tasks.api.requests queue. | | RL-TCBASE-MIB | `tcbQueuesTasksApiReqMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.21 | Number of messages for tasks.api.requests queue. | | RL-TCBASE-MIB | `tcbQueuesTasksClassState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.22 | State for tasks.classification queue. | | RL-TCBASE-MIB | `tcbQueuesTasksClassCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.23 | Number of consumers for tasks.classification queue. | | RL-TCBASE-MIB | `tcbQueuesTasksClassMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.24 | Number of messages for tasks.classification queue. | | RL-TCBASE-MIB | `tcbQueuesTasksDefaultState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.25 | State for tasks.default queue. | | RL-TCBASE-MIB | `tcbQueuesTasksDefaultCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.26 | Number of consumers for tasks.default queue. | | RL-TCBASE-MIB | `tcbQueuesTasksDefaultMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.27 | Number of messages for tasks.default queue. | | RL-TCBASE-MIB | `tcbQueuesTasksTransferState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.28 | State for tasks.transfer queue. | | RL-TCBASE-MIB | `tcbQueuesTasksTransferCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.29 | Number of consumers for tasks.transfer queue. | | RL-TCBASE-MIB | `tcbQueuesTasksTransferMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.30 | Number of messages for tasks.transfer queue. | | RL-TCBASE-MIB | `tcbQueuesTcbaseCollectorState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.31 | State for tcbase.collector queue. | | RL-TCBASE-MIB | `tcbQueuesTcbaseCollectorCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.32 | Number of consumers for tcbase.collector queue. | | RL-TCBASE-MIB | `tcbQueuesTcbaseCollectorMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.33 | Number of messages for tcbase.collector queue. | | RL-TCBASE-MIB | `tcbQueuesHagentErrorState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.34 | State for tiscale.hagent_error queue. | | RL-TCBASE-MIB | `tcbQueuesHagentErrorCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.35 | Number of consumers for tiscale.hagent_error queue. | | RL-TCBASE-MIB | `tcbQueuesHagentErrorMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.36 | Number of messages for tiscale.hagent_error queue. | | RL-TCBASE-MIB | `tcbQueuesHagentInputState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.37 | State for tiscale.hagent_input queue. | | RL-TCBASE-MIB | `tcbQueuesHagentInputCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.38 | Number of consumers for tiscale.hagent_input queue. | | RL-TCBASE-MIB | `tcbQueuesHagentInputMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.39 | Number of messages for tiscale.hagent_input queue. | | RL-TCBASE-MIB | `tcbQueuesHagentRetryState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.40 | State for tiscale.hagent_retry queue. | | RL-TCBASE-MIB | `tcbQueuesHagentRetryCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.41 | Number of consumers for tiscale.hagent_retry queue. | | RL-TCBASE-MIB | `tcbQueuesHagentRetryMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.42 | Number of messages for tiscale.hagent_retry queue. | | RL-TCBASE-MIB | `tcbQueueName` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.43 | Queue name. | | RL-TCBASE-MIB | `tcbQueueSize` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.44 | Queue size. | | RL-TCBASE-MIB | `tcbQueuesTasksIntegrationsState` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.45 | State for tasks.integrations queue. | | RL-TCBASE-MIB | `tcbQueuesTasksIntegrationsCons` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.46 | Number of consumers for tasks.integrations queue. | | RL-TCBASE-MIB | `tcbQueuesTasksIntegrationsMsg` | .1.3.6.1.4.1.48699.1.1.2.1.1.1.47 | Number of messages for tasks.integrations queue. | | RL-TCBASE-MIB | `tcbTables` | .1.3.6.1.4.1.48699.1.1.2.1.1.2 | | | RL-TCBASE-MIB | `tcbMibNotifications` | .1.3.6.1.4.1.48699.1.1.2.1.2 | | | RL-TCBASE-MIB | `tcbQueueThreshold` | .1.3.6.1.4.1.48699.1.1.2.1.2.1 | Queue size exceeded configured threshold. | | RL-TCBASE-MIB | `redundancyTrigger` | .1.3.6.1.4.1.48699.1.1.2.1.2.2 | Failover on HA system. | | RL-TCBASE-MIB | `redundancyTriggerOk` | .1.3.6.1.4.1.48699.1.1.2.1.2.3 | HA System resumed operation. | | RL-TCBASE-MIB | `tcbMibConformance` | .1.3.6.1.4.1.48699.1.1.2.1.3 | | Download the MIB file in CSV format. ## System alerting **Info: For more information, see [System alerting](../configuration/#system-alerting).** If system alerting is enabled under [Administration > Configuration & Update > Configuration > System alerting](../configuration/#system-alerting), the following system operations and services are monitored. Syslog notifications are sent when any of the services or operations meets the condition(s) defined in the table. | SYSTEM OPERATION OR SERVICE | NOTIFICATION TRIGGER | | ------------------------------- | -------------------------------------------- | | RAM | Usage is over 90% for 10 minutes. | | CPU | Usage is over 40% for 2 minutes. | | CPU wait (waiting for IO) | Over 20% for 2 minutes. | | Disk usage | Over 90% for 10 minutes. | | UWSGI service | Down for 2 minutes. | | NGINX service | Down for 2 minutes. | | RABBIT-MQ service | Down for 2 minutes. | | POSTGRES service | Down for 2 minutes. | | MEMCACHED service | Down for 2 minutes. | | CROND service | Down for 2 minutes. | | SSHD service | Down for 2 minutes. | | SUPERVISORD service | Down for 2 minutes. | | SMTP | Enabled, but stopped for 4 minutes. | | NTPD | Enabled, but stopped for 4 minutes. | | Any of the SUPERVISORD services | Crashed. | | SCALE socket | Not detected/does not exist for 4 minutes. | | SCALE INPUT queue | Receiving over 500 messages for 10 minutes. | | SCALE RETRY queue | Receiving over 100 messages for 10 minutes. | | COLLECTOR queue | Receiving over 1000 messages for 10 minutes. | | CLASSIFICATION queue | Receiving over 5000 messages for 10 minutes. | ### Connector alerts When [Connectors](./../../integrations-connectors/connectors) are configured and running, CEF messages for supported events are sent to syslog if system alerting is properly configured on the appliance. Most alerts are shared between connectors, but there are some connector-specific messages. For the full list of all supported CEF event fields, refer to the table below. **Info: Threat detection CEF messages are sent only when the **Enable automatic file sorting** option is selected in the [Connectors](./../../integrations-connectors/connectors) configuration dialog.** #### CEF event formatting schema ``` CEF:0|{device.vendor}|{device.name}|{device.version}|{signature.id}|{name}|{severity}| csxLabel={label.value} csx={field.value} ``` #### CEF event fields | Signature IDs | CEF event field | Description | Supported connectors | | ------------------------------------------------------------ | --------------- | ------------------------------------------------------------ | -------------------------------- | | Threat detection | cs1Label | cs1 field label. Always equals classification. | Network File Share, AbuseBox, S3 | | Threat detection | cs1 | File classification status (malicious, suspicious, goodware, unknown). | Network File Share, AbuseBox, S3 | | Threat detection | cs2label | cs2 field label. Always equals detectionName. | Network File Share, AbuseBox, S3 | | Threat detection | cs2 | The detected threat name, formatted according to the [Malware naming standard](/General/AnalysisAndClassification/Classification/#malware-naming-standard). | Network File Share, AbuseBox, S3 | | Threat detection | cs3label | cs3 field label. Always equals detectionReason. | Network File Share, AbuseBox, S3 | | Threat detection | cs3 | The appliance that analyzed and classified the file. Possible values are A1000, TitaniumScale. | Network File Share, AbuseBox, S3 | | connector_health | cs4Label | cs4 field label. Always equals app_health. | Network File Share, AbuseBox, S3 | | connector_health | cs4 | Sent if there are any errors or performance issues with the connector or the appliance. Always equals FAILED. | Network File Share, AbuseBox, S3 | | connector_mount_success, connector_mount_failure | cs5Label | cs5 field label. Always equals mount. | Network File Share | | connector_mount_success, connector_mount_failure | cs5 | Sent on network resource mount events. Possible values are SUCCESS for connector_mount_success and FAILED for connector_mount_failure. | Network File Share | | connector_read | cs6Label | cs6 field label. Always equals file_read. | Network File Share, AbuseBox, S3 | | connector_read | cs6 | Sent when the connector fails to read the file from the connected storage/mail account. Always equals FAILED. | Network File Share, AbuseBox, S3 | | connector_upload | cs7Label | cs7 field label. Always equals analysis. | Network File Share, AbuseBox, S3 | | connector_upload | cs7 | Sent when files fail to upload to the appliance for analysis. Always equals FAILED. | Network File Share, AbuseBox, S3 | | connector_move_files | cs8Label | cs8 field label. Always equals file_moving. | Network File Share, S3 | | connector_move_files | cs8 | If advanced file sorting is enabled for the connector, this event is sent for each file move. Possible values are FAILED, SUCCESS. | Network File Share, S3 | | connector_unmount_success, connector_unmount_failure | cs9Label | cs9 field label for connector unmount events. Always equals unmount. | Network File Share | | connector_unmount_success, connector_unmount_failure | cs9 | Shows the network resource unmount status. Possible values are SUCCESS for connector_unmount_success and FAILED for connector_unmount_failure. | Network File Share | | Threat detection, connector_move_files, connector_upload, connector_read | cs9Label | cs9 field label for events related to file operations. Always equals fileName. | Network File Share, S3 | | Threat detection, connector_move_files, connector_upload, connector_read | cs9 | Shows the name of the file related to the specific event. | Network File Share, S3 | | connector_unmount_success, connector_unmount_failure | cs10Label | cs10 field label. Always equals mountAddress. | Network File Share | | All event types except Threat detection | cs10 | The address of the network resource. | Network File Share | | connector_email_fetch_failure, connector_email_fetch_success | cs11Label | cs11 field label. Always equals email_fetch. | AbuseBox | | connector_email_fetch_failure, connector_email_fetch_success | cs11 | Sent when the connector fails/succeeds in downloading an email message from the connected email account to the appliance. Always equals FAILED for connector_email_fetch_failure and SUCCESS for connector_email_fetch_success. | AbuseBox | | connector_email_fetch_failure, connector_email_fetch_success | cs12Label | cs12 field label. Always equals exchangeServer. | AbuseBox | | connector_email_fetch_failure, connector_email_fetch_success | cs12 | The address of the Exchange server (without the protocol scheme) from which the connector is attempting to retrieve email. | AbuseBox | | connector_email_fetch_failure | cs13Label | cs13 field label. Always equals failure_reason. | AbuseBox | | connector_email_fetch_failure | cs13 | The reason why email failed to download. Possible values are:connection error, non_existing_smtp_address,authentication_error, non_existing_inbox_folder,disk_threshold_reached. | AbuseBox | | connector_move_files | cs14Label | cs14 field label. Always equals destination. | AbuseBox | | connector_move_files | cs14 | If advanced file sorting is enabled for the connector, this is the destination where the file was moved during processing. | Network File Share, S3 | | All CEF messages except those that already contain the mountAddress field | cs15Label | cs15 field label. Always equals sourceAddress. | Network File Share, S3 | | All CEF messages except those that already contain the mountAddress field | cs15 | The address of the file source (for example, a network file share, or an S3 bucket). | Network File Share, S3 | ### Examples #### Success mounting a network drive (Network File Share) ``` CEF:0|ReversingLabs|TitaniumCore|3.9.3.0|connector_mount_success|connector_mount_success|0| cs5Label=mount cs5=SUCCESS ``` #### Failure reading files from a network drive (Network File Share) ``` CEF:0|ReversingLabs|TitaniumCore|3.9.3.0|connector_read|connector_read|10|cs6Label=file_read cs6=FAILED cs9Label=fileName cs9=/mnt/incoming/installer.msi ``` #### Threat detection for files uploaded from a network drive (Network File Share) ``` CEF:0|ReversingLabs|TitaniumCore|3.9.3.0|detection|Threat detection|10|fileHash=93f5a83b850becd35f12fca8acs907ead cs2Label=classification cs2=malicious cs1Label=detectionName cs1=ByteCode-MSIL.Trojan.Genkryptik reason=cloud ``` #### Success fetching email (AbuseBox) ``` CEF:0|ReversingLabs|A1000|5.11.0|connector_email_fetch_success|connector_email_fetch_success|0| cs12Label=exchangeServer cs12=devops-exchange.exch.rl.lan cs11Label=email_fetch cs11=SUCCESS ``` #### Failure fetching email (AbuseBox) ``` CEF:0|ReversingLabs|A1000|5.11.0|connector_email_fetch_failure|connector_email_fetch_failure|10| cs13Label=failure_reason cs13=authentication_error cs12Label=exchangeServer cs12=devops-exchange.exch.rl.lan cs11Label=email_fetch cs11=FAILED ``` #### Connector/appliance in an unhealthy state (Network File Share, AbuseBox, S3) ``` CEF:0|ReversingLabs|A1000|5.11.0|connector_health|connector_health|10|cs4Label=app_health cs4=FAILED ``` #### Failed file upload (Network File Share, AbuseBox, S3) ``` CEF:0|ReversingLabs|A1000|5.11.0|connector_upload|connector_upload|10|cs9Label=fileName cs9=application_windows.exe cs7Label=analysis cs7=FAILED ``` #### Successful file move (Network File Share, S3) ``` CEF:0|ReversingLabs|A1000|5.10.8-1|connector_move_files|connector_move_files|0|cs9Label=fileName cs9=BavPro_Setup_GL.zip cs8Label=file_moving cs8=SUCCESS cs14Label=destination cs14=/Malicious/BavPro_Setup_GL.zip ``` ## Configuring MCP Server with AI assistants The MCP (Model Context Protocol) server enables AI assistants to connect to Spectra Analyze APIs for malware reporting, IOC triage, and reputation lookups. The following steps describe how to configure the MCP server integration with Claude Desktop. ### Prerequisites - MCP server must be enabled on Spectra Analyze. Navigate to **Administration > Configuration > MCP Server** and check the **Enable MCP Server** option. For more information, see [MCP Server](../configuration/#mcp-server). - A valid API token for the Spectra Analyze instance. ### Configuration steps 1. Download the [`.mcpb` file](pathname:///files/reversinglabs-spectra-analyze.mcpb). 2. In Claude Desktop, navigate to **Settings > Extensions > Advanced Settings > Install Extension**. 3. Click **Install**. 4. Set **MCP Server URL** to `https://SPECTRA_ANALYZE_HOST/mcp/` and replace `SPECTRA_ANALYZE_HOST` with your Spectra Analyze hostname. Ensure that the URL includes a trailing slash, or the connection will fail. 5. Set **Token** to a valid API token for the Spectra Analyze instance. 6. Save, and toggle the button to enable the service. ### Usage Use the pre-canned prompts by going to **+ > Connectors > Add from Spectra Analyze**, or start asking questions directly. Example queries: - "Retrieve detailed threat analysis for the file 5884d853f85eb536244f354ba5d6cf9b4e702c7f" - "Check network reputation for 45.148.11.242" - "Search for samples targeting industrial control systems" - "Gather some hashes for windows PE samples with sandbox evasion and anti-analysis tricks that I can use to test our company sandbox" ![MCP Server configuration in Claude Desktop](images/analyze-admin-techref-mcp.png) --- ## Backup & Purge — Spectra Analyze Administration ***Spectra Analyze > Administration > Configuration & Update > Backup & Purge*** The **Backup & Purge** features provide an automated way to manage storage space on the Spectra Analyze appliance. Backup lets users perform database backups, and restore the appliance database from previous backups. With purge, users can define which samples are considered old and have them automatically removed at scheduled times. Additionally, users can clean up the database and the samples at any time by manually running the purge task. To access the backup and purge features, go to [**Administration > Configuration & Update > Configuration > Backup & Purge**](/SpectraAnalyze/Administration/configuration-update/configuration#backup--purge) and check **Enable Backup & Purge**. When enabled, backup and purge run automatically every day at midnight (00:00 UTC) by default, or at any other time and frequency specified by the user. However, users can run backup and purge manually at any time on the **Administration > Configuration & Update > Backup & Purge** page, and perform data removal according to predefined configuration criteria. ## Defining backup and purge criteria Before running a purge manually, go to **Administration > Configuration & Update > Configuration > Backup & Purge** and select the correct classification statuses to purge. Optionally, check **Backup Database Before Purging** to ensure a backup is created before running the purge. ## Running manual backup To run a backup manually, go to **Administration > Configuration & Update > Backup & Purge** and click **Run Backup**. This action runs a manual backup without a purge. The duration of the backup process and the size of the backup file vary depending on the appliance configuration and retention parameters. While backup is running, the appliance operates with degraded performance. The database backup file is created in the PostgreSQL database format. The filename of the backup file contains the date and time when the backup was performed in the format `database-a1000-[date-time].dump`. By default, the database backup file is stored in the `/data/tcbase-backup` directory on the appliance. Backup files contain analysis information, including the verdict and analysis results. Configuration and original files are not backed up. Spectra Analyze does not store multiple database backup files as every new backup overwrites the previous one. To download the database backup file, go to **Administration > Configuration & Update > Backup & Purge** and click **Download database backup**. You can store the file to a safe location or import it into a new Spectra Analyze instance. Only the latest database backup file can be downloaded using this option. To import the database from an existing backup file, go to **Administration > Configuration & Update > Backup & Purge > Restore database backup**. Click **Choose file** to select a backup file to upload, and enter the **Password** you use to log into the Spectra Analyze appliance. Finally, click **Upload and restore**. Performing this action restarts the appliance and imports the uploaded database. The process takes several minutes, during which the maintenance page is displayed. Refresh it to return to the Spectra Analyze appliance interface. ## Running manual purge To run a purge manually, go to **Administration > Configuration & Update > Backup & Purge** and click **Run Purge**. This action runs a manual purge. Whether or not this action also runs a backup is determined by the **Backup Database Before Purging** checkbox under **Administration > Configuration & Update > Configuration > Backup & Purge**. It's not possible to execute a manual purge multiple times in quick succession, or while a scheduled purge is already in progress. While a purge is running, the appliance enters maintenance mode and cannot be used until the purge completes. --- ## Certificates — Spectra Analyze Administration ***Spectra Analyze > Administration > Configuration & Update > Certificates*** The **Root CA Trust Store Management** page enables administrators to manage Root CA certificates for Spectra Analyze and Spectra Detect appliances. Managing Root CA certificates defines which certificate authorities the appliance considers trusted. Adding a certificate to the trust store allows the system to automatically validate and establish secure connections with services whose certificates are issued by that authority. Users can add, remove, trust, and distrust Root CA certificates through the web interface to customize the appliance's certificate validation behavior for secure communications. ## Certificate scope Certificates managed through the Spectra Analyze interface apply to: - **Spectra Detect Manager** - **Spectra Detect Hub** - **Spectra Detect Worker** - **Spectra Analyze** ## Accessing certificate management To access the certificate management interface: 1. Log into the appliance web interface as an administrator. 2. Navigate to **Administration > Certificates**. 3. The certificate management page displays all Root CA certificates currently in the Trust Store. ## Certificate list overview The certificate management page displays a table with the following information for each certificate: | Column | Description | |----------------|-----------------------------------------------| | **ID** | Number of certificate. | | **Subject** | Name of certificate. | | **Issuer** | Certificate issuer. | | **Valid From** | Certificate validity start date. | | **Valid To** | Certificate validity end date. | | **Filename** | Name of .pem file. | | **Trusted** | Whether the certificate is currently trusted. | | **Actions** | Available operations for the certificate. | ## Adding Root CA certificates To add a new Root CA certificate to the Trust Store: 1. Under **Administration > Certificates**, click **Add Certificate**. 2. Click **Browse Files**, and select a valid certificate file in `.pem` format. 3. Click **Upload** to add the certificate to the Trust Store. 4. The certificate appears in the list with the **Trusted** status set to *Yes*. ## Managing certificates To distrust or blocklist a certificate: 1. Locate the certificate in the list. 2. Under **Actions**, click **Distrust**. 3. Confirm the change in the modal dialog. 4. The **Trusted** status changes to *No*. To re-trust a certificate: 1. Locate the certificate in the list. 2. Under **Actions**, click **Trust**. 3. Confirm the change in the modal dialog. 4. The **Trusted** status changes to *Yes*. To remove a certificate: 1. Locate the certificate in the list. 2. Under **Actions**, click **Remove**. 3. Confirm the change in the modal dialog. 4. The certificate is deleted from the Trust Store. **Info: Some certificates may be greyed out because you don't have the necessary permissions to modify them.** To reset the Trust Store: 1. Click **Remove All Added Certificates**. 2. Confirm the action in the modal dialog. 3. All user-added certificates are removed from the Trust Store. **Warning: Removal of certificates works for both trusted and distrusted certificates and completely deletes them from the system.** Clicking **Remove All Added Certificates** removes all certificates added by users and cannot be undone. --- ## Configuration ***Spectra Analyze > Administration > Configuration & Update > Configuration*** ## Overview Under **Configuration**, set up the system configuration settings. The available settings are divided into configuration dialogs described below. **Warning: Configuration through Spectra Detect Manager** You can also apply preconfigured settings using **Spectra Detect Manager**. For more information, see [Configuration management using Spectra Detect Manager](#configuration-management-using-spectra-detect-manager). If the `local.yaml` configuration file on the appliance contains local configuration settings, a warning is displayed at the top of the page. In case of issues when configuring the appliance, inspect the existing values in `local.yaml`, as they may conflict with the values set in the configuration dialogs. When done updating the settings, click **Save**. The appliance is restarted and begins using the new settings. **Note: - Settings marked with an asterisk (*) are required. To complete the initial configuration of the appliance, all settings marked with an asterisk should be changed.** - ReversingLabs sends Spectra Intelligence settings and credentials to the users separately for enabling full file reputation and classification by the appliance. ## General | Setting | Description | | ------------------------------------------------- | ------------------------------------------------------------ | | ***General*** | | **Appliance domain*** | Appliance domain name or IP address, used for creating links back to the appliance. This should not include the protocol, for example, *http*, but should include any non-default port. For example, *example.com, 192.168.128.42, 192.168.128.42:8080* | | **Allowed hosts*** | A list of strings, one per line, representing the host/domain names that this appliance installation can serve. Values in this list can be fully qualified names, for example, *www.example.com*, in which case they are matched against the request’s host header exactly using case-insensitive matching, and not including port. A value beginning with a period can be used as a subdomain wildcard, for example, *.example.com* matches *example.com, www.example.com*, and any other subdomain of *example.com*. A value of “*” matches anything, for example, *.reversinglabs.com, 89.201.174.154, 89.201.174.152* | | **Page size** | Default number of items per page to use in paged lists or tables, for example, on the **Submissions** page. Users can manually change this directly on each page. | | **Web server protocol** | Configure HTTPS, HTTPS and HTTP, or just HTTP for the protocol by which the appliance can be accessed. **Note:** The value configured here determines which protocol must be used in requests to Spectra Analyze APIs. Click **SSL configuration** to generate a new self-signed SSL certificate or upload a custom one. For more information, see options below. | | **SSL configuration** | Displayed as the link next to the **Web server protocol** option. Click it to open the **Update SSL certificate** page. | | **Generate new SSL certificate** | Select and click **Submit** to generate a new self-signed SSL certificate for the server to use. | | **Upload certificate** | Click **Choose File** to upload a file containing a custom SSL certificate to replace the self-signed certificate generated by Spectra Analyze. **Note:** Firefox users might encounter issues with custom certificates. The support section explains how to resolve them. | | **Upload certificate private key** | Click **Choose File** to upload a file containing the key that corresponds to the certificate uploaded in the previous option. | | **File Size Limit** | The maximum file size in MB that can be submitted to the appliance. The default and maximum value is 2000 MB. Other [file size restrictions](/SpectraAnalyze/file-submissions/#file-size-restrictions) still apply. | | ***Reverse proxy configuration*** | If the appliance is behind a reverse proxy, the following two settings must be configured in order to use the [Authentication > Login security > Block login for specific IP address](#authentication) option. | | **HTTP header containing originating IP address** | If the appliance is behind a reverse proxy, specify the HTTP header used to identify the originating IP address of a client connecting to the appliance through the reverse proxy. The most commonly used header is *X-Forwarded-For*. | | **Number of trusted reverse proxies** | If the appliance is behind a reverse proxy, specify the number of trusted reverse proxies. This setting is used when the originating IP address header is present to identify the correct client IP address. | | **Password list** | The appliance uses the passwords defined in this list when attempting to decrypt password-protected compressed files submitted for analysis. Prior to submitting password-protected compressed files to the appliance, users can add the password for each file to this list. Enter one password per line. | | **Enable Root Login via SSH** | Select to permit SSH root logins to the appliance. Contact [ReversingLabs Support](mailto:support@reversinglabs.com) for additional information and guidance. | | **Disable SWAP memory** | Select to disable the usage of SWAP memory on the appliance. | ## SMTP | Setting | Description | | ---------------------------- | ------------------------------------------------------------ | | **Enable SMTP** | Select to enable the SMTP (Simple Mail Transfer Protocol) service on the appliance. This allows the appliance to send email notifications to a configured email address. If the SMTP service is configured correctly, it is visible under **External Services Connectivity** on the [System Status](/SpectraAnalyze/Administration/usage-alerts/system-status) page. | | **SMTP server** | The host to use for sending email. This field is empty by default. For the SMTP service to function properly, the user needs to input the host. | | **SMTP port** | Port of the host used for sending email. This field is empty by default. For the SMTP service to function properly, the user needs to input the port. | | **Username** | SMTP user name for authentication. | | **Password** | SMTP password associated with the specified user name. | | **Default “from” email address** | The email address used by the appliance as the “from” address when sending email. This is usually used for password resets, error alerts, and other. | | **Use TLS** | Select to use a secure TLS (Transport Layer Security) connection when communicating with the SMTP server. | ## System Time | Setting | Description | | ----------------------------------- | ------------------------------------------------------------ | | **Enable network time synchronization** | Select to enable server clock synchronization via NTP, which uses port 123. | | **Timezone** | Select the timezone of the appliance. | | **NTP servers** | A list of servers, one per line, to use for system clock synchronization. | ## Authentication | Setting | Description | | ------- | ----------- | | ***Session duration*** | | **Duration of login session** | How long an authenticated user session remains active on the appliance, set in minutes, hours or days. Minimum: 1 minute; maximum: 90 days. The default is 7 days. | | **Session expire at browser close** | When selected, the session for every logged-in user expires when the user closes their browser, requiring the user to log in every time they start their browser. This setting may be overridden by local web browser settings. | | ***Session inactivity timeout*** | | **Automatically log out inactive users** | When selected, the session for every logged-in user expires after the configured period of inactivity in minutes, hours or days. | | **Period of inactivity before signout** | How long an authenticated user session can be inactive on the appliance before being signed out. Set in minutes, hours or days. | | ***CSRF settings*** | | **Use session-based CSRF cookies** | When selected, the CSRF (Cross-Site Request Forgery) cookies expire when the user closes their browser. By default, persistent CSRF cookies are used, and cookie age is approximately 1 year. This setting may be overridden by local web browser settings. | | ***Password requirements*** | Criteria configured here apply to passwords for all accounts on the appliance. Federated (single sign-on) accounts are not affected by the criteria configured here. All settings are optional and can be used in combination with other password requirements. Define the following password requirements: **Minimum password length, Must contain at least 1 uppercase character, Must contain at least 1 lowercase character, Must contain at least 1 decimal digit, Don't allow passwords from list of commonly used passwords**. | | ***Login security*** | Criteria configured here apply to all accounts on the appliance instance. Requests to the authentication API are also affected by the criteria configured here. | | **Temporarily block user login after certain number of failed login attempts** | Select to enable temporary account locking for every account that consecutively fails to log into the appliance. If this option is not selected, other login security options cannot be configured and do not apply. | | **Number of failed login attempts** | Specify the maximum allowed amount of consecutive failed login attempts. If a user's login attempts exceed the number configured here, their account is temporarily locked and prevented from logging in. When an account is locked, appliance administrators cannot unlock it. The user whose account is locked has to wait until the login delay expires. The login delay is configured under **Block timeout**. | | **Block timeout** | Specify how long a user's account remains locked after the maximum allowed amount of failed login attempts is exceeded. The time interval can be defined in seconds, minutes, or hours. When an account is locked, appliance administrators cannot unlock it. The account is automatically unlocked after the login delay configured here expires. | | **Block login for specific IP address** | The appliance tracks IP addresses from which users are attempting to log in. If this option is selected, users who consecutively fail to log in are blocked by their current IP address. They are unable to log in from the IP address detected in failed login attempts, but they can still log in from any other IP address. If this option is not selected, users are blocked based on their account username regardless of the IP address, and they can't log in from any IP address. The login delay interval set up under **Block timeout** and the allowed **Number of failed login attempts** apply to accounts blocked in this way. If the appliance is behind a reverse proxy, make sure that reverse proxy settings in under [**General**](#general) are properly configured so that the users' IP addresses can be identified. When an account is blocked in this way, appliance administrators cannot unblock it. The account is automatically unlocked after the configured login delay expires. | | **Send notification email to administrator when login block occurs** | Select to automatically send email notifications when an account is locked based on configured login security criteria. [**Email Alerting**](#system-alerting) and [**SMTP**](#smtp) must be enabled and configured on the appliance in order to send notification emails. The emails are sent to the address configured in [**System Alerting**](#system-alerting). | The remainder of this section describes how to configure single sign-on login options selected under ***User Directory***. ### LDAP | Setting | Description | | ------- | ----------- | | ***Connection*** | | | **LDAP server host** | Host name or IP address of the server providing LDAP authentication. For example, *ldap.example.com*. Click **Test** to verify the connection to the server. | | **LDAP server port** | LDAP server host port. The defaults are 389 (LDAP) or 636 (LDAPS). | | **TLS** | Select to use a secure (TLS) connection when communicating with the LDAP server. | | **TLS require certificate** | Select to require TLS certificate verification when communicating with the LDAP server. | | **Select CA certificate** | Click **Choose File** to upload a TLS certificate for verifying the LDAP host identity. The certificate must be in `.pem` format. To apply the certificate, the options **TLS** and **TLS require certificate** must be enabled. It is also possible to upload certificates through the *Central Configuration Management* section on Spectra Detect Manager if the appliance is connected and authorized on the Manager. | | **Bind DN or user** | User to log into the LDAP server for searches. DN stands for Distinguished Name. For example, *user@example.com* or *cn=user,dc=example,dc=com* | | **Password** | Password for the Bind user account. | | ***User Schema*** | | | **Base DN** | Root node in LDAP from which to search for users. For example, *cn=users,dc=example,dc=com*.| | **Scope** | Scope of the user directory searches. The available options are *base, one level, subordinate, subtree*. | | **User object class** | The objectClass value used when searching for users. For example, *user*. | | **User name attribute** | The user name field. For example, *sAMAccountName* or *cn*. | | ***Group Schema*** | The majority of fields in this section are the same as in the ***User Schema*** section, except the settings relate to groups. | | **Base DN** | Root node in LDAP from which to search for groups. For example, *cn=groups,dc=example,dc=com*.| | **Scope** | Scope of the group directory searches. The available options are *base, one level, subordinate, subtree*. | | **Group object class** | The objectClass value used when searching for groups. For example, *group*. | | **Group name attribute** | The group name field. For example, *cn*. | | **Group type** | LDAP group membership attribute. The available options are *Member, Unique Member*. | | ***User attribute mapping*** | | | **First name** | Field to map to a user's first name. For example, *givenName*. | | **Last name** | Field to map to a user's last name. For example, *sn*. | | **E-mail** | Field to map to email. For example, *mail*. | | ***User access*** | | | **Active flag group** | Group DN. Users are marked as active only if they belong to this group. For example, *cn=active,ou=users,dc=example,dc=com*. | | **Superuser flag group** | Group DN. Users are marked as superusers only if they belong to this group. For example, *cn=admins,ou=groups,dc=example,dc=com*. | | **Require group** | Group DN. Authentication fails for any user that does not belong to this group. For example, *cn=enabled,ou=groups,dc=example,dc=com*. | | **Deny group** | Group DN. Authentication fails for any user that belongs to this group. For example, *cn=disabled,ou=groups,dc=example,dc=com*. | ### OAuth 2.0 / OpenID Connect For more information, see [OpenID guide](/General/SecurityAndAccessControl/OpenID). ----- ### SAML For more information, see [SAML guide](/General/SecurityAndAccessControl/SAML). ----- ## Spectra Intelligence **Tip: Best practice** Multiple Spectra Analyze instances should **not** be configured to use the same cloud account, as this can interfere with appliance functionality, and particularly with YARA ruleset synchronization. It is advised to use these settings only if there is just one Spectra Analyze appliance in the configuration group. | Setting | Description | | ------------------------------------------------------ | ------------------------------------------------------------ | | **Spectra Intelligence URL** * | The host address for the Spectra Intelligence service. Click **Test** to check for any connectivity issues. The default URL is *https://appliance-api.reversinglabs.com* | | **Username** * | Spectra Intelligence username for authentication. Every appliance instance must be connected to its own Spectra Intelligence account. **Note:** Sharing accounts between multiple instances can interfere with the functionality of the appliance, particularly with YARA rule synchronization. | | **Password** * | Spectra Intelligence password for authentication. Every appliance instance must be connected to its own Spectra Intelligence account. **Note:** Sharing accounts between multiple instances can interfere with the functionality of the appliance, particularly with YARA rule synchronization. | | **Timeout** | Default Spectra Intelligence service connection timeout in seconds. Maximum is 1000. **Note:** It is highly recommended to set this timeout to 1 second in air-gapped networks. | | **Proxy host** | Optional proxy host name for routing requests from the appliance to Spectra Intelligence, for example, *192.168.1.15*. If configured, this proxy is also used by the Local URL crawling method and all integrations on the Spectra Analyze appliance: ReversingLabs Cloud Sandbox and Auxiliary Analysis, Joe Sandbox, FireEye, CAPE, Cuckoo, Cisco Secure Malware Analytics, VMRay. | | **Proxy port** | Optional proxy port number, for example, 1080. | | **Proxy username** | Username for proxy authentication, if proxy is configured. | | **Proxy password** | Password for proxy authentication, if proxy is configured. | | **Maximum fetch file size** | Maximum size of an individual file in MiB that is allowed to be downloaded from the cloud to Spectra Analyze. The default value is 500 MiB, the minimum is 1 MiB, and the maximum is 2000 MiB. Files exceeding the size configured here have a special indicator icon in the Spectra Analyze interface. This limit also affects URL submissions using the Spectra Intelligence crawling method, where it applies to individual files downloaded from the submitted URL. Files going over this limit are skipped during URL analysis. | | **Automatic Upload to Spectra Intelligence** | Allow files to be automatically uploaded to the cloud whenever they are uploaded to the appliance. | | **Allow Upload of API statistics to Spectra Intelligence** | Allow ReversingLabs to collect anonymous API usage statistics related to the cloud. Click **Show Example Data** to see an example of data being logged and sent. | ## T1000 File Reputation Appliance | Setting | Description | | -------------- | ------------------------------------------------------------ | | **T1000 URL** * | The host address for the on-premise T1000 File Reputation appliance. Click **Test** to check for any connectivity issues. | | **Username** * | T1000 user name for authentication. **Note:** This user name needs to be created via the *T1000 Web administration* application. | | **Password** * | T1000 password for authentication. **Note:** This password needs to be created via the *T1000 Web administration* application. | | **Timeout** | Default T1000 service connection timeout in seconds. Maximum is 60. | | **Proxy host** | Proxy host name for routing request from the appliance to T1000. For example, *192.168.1.15*. | | **Proxy port** | Proxy port number. For example, *1080*. | | **Proxy username** | Username for proxy authentication, if proxy is configured. | | **Proxy password** | Password for proxy authentication, if proxy is configured. | ## Metrics | Setting | Description | | ------------------- | ------------------------------------------------------------ | | ***SNMP settings*** | | | **Enable SNMP service** | Select to enable the Simple Network Management Protocol service. **Note:** This must be enabled if the appliance is to be connected to the Spectra Detect Manager. | | **Community** | Enter the name of an SNMP community list for authentication. Community is a list of SNMP clients authorized to make requests. **Note:** The SNMP service does not function properly if this field is not configured. If the appliance is connected to the Spectra Detect Manager, the Manager is not be able to retrieve accurate appliance status information if this field is not configured. | | ***SNPM trap settings*** | | | **Enable trap sink** | Select to enable sending SNMP traps to the sink server. Traps are asynchronous, unsolicited SNMP messages sent by the SNMP agent to notify about important events on the appliances. The Spectra Analyze appliance supports traps for the events listed in this configuration dialog. | | **Trap community** | Enter the SNMP trap community string. If **Enable SNMP service** and **Enable trap sink** are selected, this field is required. | | **Trap sink server** | Enter the host name or the IP address of the trap sink server. The sink server is the location to which SNMP traps are sent. If **Enable SNMP service** and **Enable trap sink** are selected, this field is required. | | **Supported events** | A set of configuration fields allowing the user to set the thresholds for supported types of events. Thresholds are values that trigger an SNMP trap, and they can be configured for **Average system load**, **Used memory**, **Used disk space**, **Spectra Detect queue size** and **Classifications queue size**. For more information, see [SNMP trap thresholds](../appendix-tech-reference/#snmp-trap-thresholds). | | ***Prometheus settings*** | | | **Enable Prometheus metrics** | Select to enable Prometheus monitoring for this instance of Spectra Analyze. | ## System Alerting | Setting | Description | | --------------------------------------------- | ------------------------------------------------------------ | | ***System alerting*** || | **Enable** | Select to receive alerts about the status of critical system services to the syslog server. For more information, see [System alerting](../appendix-tech-reference/#system-alerting). | | **Host** | Host address of the remote syslog server to send alerts to. | | **Port** | Port of the remote syslog server. | | **Protocol** | Communication protocol to use when sending alerts to remote syslog server. The available options are TCP (default) and UDP. | | **Enable audit logs to be sent to syslog server** | Select to enable forwarding appliance audit logs to the configured syslog server. This option is disabled by default, which means that audit logs are not automatically sent to syslog. Enabling this option increases the traffic between the appliance and the syslog server. | | ***Email alerting*** || | **Enable** | Select to receive alerts about the status of critical system services to the configured email address. | | **Email error alerts to** | The appliance administrator’s email address for receiving error alerts. | ## Spectra Detect Processing Settings | Setting | Description | | ----------------------------------------------------- | ------------------------------------------------------------ | | **Processing settings** | Processing settings determine which file formats are unpacked by Spectra Core for detailed analysis. The available options are **Fast**, **Best**, and **Normal**. *Best* fully processes all formats supported by the appliance. *Normal* and *Fast* both process a limited set of file formats, but *Normal* supports more formats than *Fast*. When *Fast* or *Normal* is selected, a list of formats that will **not** be fully processed is displayed. The Spectra Analyze displays only a basic set of information on the [Sample Details](/SpectraAnalyze/Sample%20Details/) page for those file formats. | | **Enable ReversingLabs file reputation** | Allow Spectra Core to retrieve classification information from Spectra Intelligence or T1000 during sample analysis. This option is enabled by default. If both file reputation services are configured on the appliance, T1000 has priority and is used by Spectra Core to classify samples. When this option is enabled, classification information on the **Sample Details > Summary** and **Sample Details > Timeline** pages indicates that the sample was classified by Spectra Core Spectra Intelligence. All samples classified in this way are automatically assigned a system tag called *cloud*. | | **Enable classification propagation** | This option is enabled by default. Spectra Core performs file unpacking during analysis, then analyzes and classifies those unpacked children files along with their parent file. When this option is enabled, classification propagation makes it possible to classify parent files based on the content extracted from them. This means that a file containing a malicious/suspicious file is also considered malicious/suspicious. | | **Maximum duration of temporary report retention period** | When sample analysis reports are created on the appliance, they are collected in a queue before storing report metadata in the appliance database. After the metadata is successfully stored, report files are deleted from the appliance. To prevent premature removal of those report files, the report retention period can be configured by adjusting this value. Increase this value if large samples fail to process. If disk consumption is high, decrease this value. The value should be configured in minutes. The default is 7200 (5 days). Allowed values are 30 to 20160 (14 days). | | ***Enable classification scanners*** | These technologies work together to determine what the final file classification should be. Enabling/disabling these scanners or suppressing certain low-risk threat types allows fine-tuning of the final classification outcome. Enabling classification detection suppression for any of the threat types makes the engine report the detected threat, but this detection is ignored during file classification. Should this detection be the only one, with no higher risk detections within the same package, the file is considered graylisted due to user configuration. | | **Images** | Image format threat detection. Spectra Core applies image format specific signatures and heuristics to detect threats. Signatures are applied during format validation to detect known exploits. As opposed to them, heuristics can detect client or server-side code embedded in the image stream or data properties. Heuristics are predictive detection technologies and they refer to both manually written and machine learning algorithms. When a detection is made with this technology, the scanner name is reported as `Spectra Core / Unpacker`. | | **PECOFF** | Windows executable format validation and threat detection. PECOFF is a complex executable format for which Spectra Core has a dedicated parser. This technology performs in-depth format validation and is capable of detecting malformations that can be related to threat detection evasion attempts. Existence of such data structures and header values can be sufficient to declare the file suspicious. However, it is possible that files damaged during transport exhibit the same kind of traits as malformed ones. If there’s a high likelihood of data corruption during file collection, this option can be disabled to reduce unwanted detections. When a detection is made with this technology, the scanner name is reported as `Spectra Core PECOFF Validator`. | | **Documents** | Document format threat detection. Spectra Core applies document format-specific signatures and heuristics to detect threats. Signatures are applied during format validation to detect known exploits. Other types of threats are detected with heuristics. These refer to predictive detection technologies and they cover both manually written and machine learning algorithms. Heuristic algorithms are typically applied to scripts and macros within documents to identify threats that are hard to describe using conventional signatures. When a detection is made with this technology, the scanner name is reported as `Spectra Core Document Classifier`. | | **Certificates** | Digital certificate validation and threat detection. Certificates are used to sign documents, archives, applications and software packages. Their digital signatures guarantee the origin and integrity of the file they are signing. Spectra Core performs digital certificate chain validation and can both blocklist and allowlist files based on digital signatures. During validation, additional checks are performed to ensure that the certificate is properly formed and that it hasn’t been revoked. Issues that the engine encounters during validation can be translated to classification. For example, if a file fails integrity validation, it is classified as suspicious due to tampering after it was signed. However, it is possible that files damaged during transport exhibit the same kind of traits as tampered ones. If there’s a high likelihood of data corruption during file collection, this option can be disabled to reduce unwanted detections. When a detection is made using this technology, the scanner name is reported as `Spectra Core Certificate Validator`. | | **Hyperlinks** | Embedded hyperlink threat detection. Spectra Core performs static analysis to collect embedded hyperlinks from supported file types during extraction. Hyperlinks are identified both generically, from any file type, and specifically, from formats that have dedicated parsers. Collected hyperlinks are then classified with heuristic algorithms that look for spoofed, typosquatted, open redirect risks that could trick the user into visiting misleading websites. In addition to heuristics, Spectra Core has an offline database of blocklisted domains that are used to enhance the hyperlink classification coverage. When a detection is made using this technology, the scanner name is reported as `Spectra Core URL Classifier`. | | **Emails** | Phishing and email threat detection. Spectra Core applies email content specific heuristics to dangerous messages. These threat detection heuristics look for patterns commonly found in phishing attacks, such as deceptive senders and email bodies that resemble popular service providers. In addition to heuristics, Spectra Core has an offline database of blocklisted domains that are used to enhance the email classification coverage. When a detection is made with this technology, the scanner name is reported as `Spectra Core Email Classifier`. | | ***Ignore the following threat types*** | Select threat types to exclude from the final classification decision. Should this skipped detection be the only one with no higher risk detections within the same package, the file is considered *Goodware*, and the classification reason is *Graylisting*. | | **Ignore adware** | Ignore classification result that matches adware. | | **Ignore packer** | Ignore classification result that matches packers. | | **Ignore riskware (PUA)** | Ignore classification result that matches riskware. | | **Ignore hacktool** | Ignore classification result that matches hacktool. | | **Ignore spyware** | Ignore classification result that matches spyware. | | **Ignore spam** | Ignore classification result that matches spam. | | ***CEF classification message logging*** | | | **Enable Sending CEF Messages to Syslog Server** | Select to send sample classification messages to syslog. | | **CEF hash type** | The available hash types to be logged are *MD5*, *SHA1* or *SHA256*. | ## Resource Usage Limits | Setting | Description | | ---------------------------------- | ------------------------------------------------------------ | | **Memory limit** | The memory limit is compared to the percentage of used memory. Default is 90%, minimum is 75, maximum is 100. Set this value to 100 to disable the limit. | | **Processing queue limit** | Queue limit is compared to the number of messages in the queue. Default is 50, minimum is 10. Set this value to 0 to disable the limit. | | **Hagent input queue limit** | Queue limit is compared to the number of messages in the queue. Default is 50, minimum is 10. Set this value to 0 to disable the limit. | | **Sample submission queue limit** | Queue limit is compared to the number of messages in the queue. Default is 50, minimum is 10. Set this value to 0 to disable the limit. | | **Collector queue limit** | Queue limit is compared to the number of messages in the queue. Default is 50, minimum is 10. Set this value to 0 to disable the limit. | | **Classifier queue limit** | Queue limit is compared to the number of messages in the queue. Default is 50, minimum is 10. Set this value to 0 to disable the limit. | | **Disk limit** | The disk limit is compared to the percentage of used disk space. Default is 95, minimum is 75, maximum is 99. Set this value to 0 to disable the limit. | ## Computer Vision Analysis | Setting | Description | | ------- | ----------- | | **Enable Computer Vision Analysis** | The Computer Vision Analysis module identifies and extracts URIs, IP addresses (IPv4 and IPv6), domains, and email addresses from images and PDFs using OCR, and from QR codes by decoding them. The extracted data and their classifications (e.g., malicious) are available on the respective Sample Summary page. | ## AI Summary | Setting | Description | | ------- | ----------- | | **Enable AI Summary** | When enabled, AI-assisted summaries of analysis reports can be generated. Summaries are created using an offline version of a large language model (LLM) from a third-party service. **Note:** Ensure this feature aligns with organizational data-handling and compliance policies. | ## MCP Server | Setting | Description | | ------- | ----------- | | **Enable MCP Server** | When enabled, the appliance acts as an MCP (Model Context Protocol) server, exposing Spectra Analyze data to supported AI assistants (e.g., Claude, Gemini) that connect using the MCP protocol to inspect samples or network resources. | **Info: For instructions on configuring the MCP server with supported AI assistants, see [Configuring MCP Server with AI assistants](../appendix-tech-reference#configuring-mcp-server-with-ai-assistants).** ## Backup & Purge | Setting | Description | | ----------------------------------------------- | ------------------------------------------------------------ | | **Enable backup & purge** | Select to enable the backup and purge features. The purge task is not triggered immediately upon being enabled. Instead, when enabled, the [Backup & Purge](/SpectraAnalyze/Administration/configuration-update/backup-purge) section becomes available, allowing access to additional options. By default, a purge runs every day at midnight (00:00 UTC) and removes data according to the settings configured here. It is also possible to run the backup or purge task at any time and manage database backups from [Backup & Purge](/SpectraAnalyze/Administration/configuration-update/backup-purge). While running these tasks, the appliance enters maintenance mode and becomes unavailable. | | **Purge data older than** | Choose the time interval after which the data is purged automatically. The available options are *1 week, 2 weeks, 1 month, 3 months, 6 months, 12 months*. Default is *1 month*. This data includes samples stored on Spectra Analyze and the database. **Note:** It is recommended you start with short retention periods and monitor the disk usage, then increase the retention period incrementally to accommodate observed usage patterns. Regularly monitor disk usage to avoid outages and performance issues. | | **Select at least one classification to be purged** | When one or more classification statuses are selected here, only the samples with those statuses are removed from the appliance by the purge task. It is possible to select any combination of statuses. The available options are *Malicious, Suspicious, Goodware, Unknown, Error State*. By default, all except *Malicious* and *Error State* are selected. | | ***Purge schedule*** | This section allows users to schedule how often the purge task should run. If available, statistics from previous purge tasks are displayed to help determine the optimal schedule. | | **The purge will be run** | The available options are *monthly, weekly, daily*. | | **Day(s) of the month** | Select which days of the month to run the purge. This option only applies if you set **The purge will be run** to *monthly*. If you choose only the 29th, 30th, and/or 31st, the purge is run only in months that have that many days. | | **Day(s) of the week** | Select which days of the week to run the purge. This option only applies if you set **The purge will be run** to *weekly*. | | **Hour of the day (UTC)** | The time selected here applies to the daily maintenance purge task which can't be turned off even if **Enable backup & purge** is not selected. The daily maintenance purge task cleans up the database and removes samples without sources, such as leftover samples that the users deleted during the previous day, which helps prevent deadlocks and process scheduling issues when attempting to delete samples from the appliance. From the drop-down list, select at which hour of the day in UTC the task should run. If not specified, or if **Enable backup & purge** is not selected, the task runs at midnight (00:00 UTC) by default. Otherwise, the task runs at the specified hour if the disk usage exceeds 65% and if it has not been run in the past 24 hours. While running this task, the appliance enters maintenance mode and becomes unavailable. | | **Backup database before purging** | Select to enable automatic backups before purging the data. Every new backup overwrites the previous one, so make it sure to download and store them separately to a different location. If this option is not selected, only a purge is performed, which means samples are deleted without creating a backup first. | ## Alert Management | Setting | Description | | ----------------------- | ------------------------------------------------------------ | | **Purge alerts older than** | Choose the time interval after which the alerts collected on Spectra Analyze under [Alerts](/SpectraAnalyze/alerts/) are automatically removed. The available options are *1 month, 3 months, 6 months*. Default is *3 months*. | ## Spectra Detect Worker Store Integration **Info: If you're connecting to Spectra Detect in order to enable [pivot](/SpectraAnalyze/file-submissions/#pivoting-from-spectra-detect) links, it's preferable to do it through [Spectra Detect Manager](/SpectraDetect/Config/ApplianceConfiguration/#spectra-analyze-configuration). However, manual configuration, for example, connecting to a single pre-processing Worker, is also possible.** | Setting | Description | | -------------------------------------------------------- | ------------------------------------------------------------ | | ***Bucket connection mappings*** | Allows the use of up to 10 different mapping groups for different output buckets. Click **Add Mapping** to add a mapping. | | **AWS S3 buckets list** | A list of S3 buckets. The name can be between 3 and 63 characters long, and can contain only lower-case characters, numbers, periods, and dashes. Each label in the name must start with a lowercase letter or number. The name cannot contain underscores, end with a dash, have consecutive periods, or use dashes adjacent to periods. The name cannot be formatted as an IP address. | | **AWS S3 access key ID** | The access key ID for AWS S3 account authentication. **Note:** In cases where the appliance is hosted by ReversingLabs and Role ARN is used, this value is provided by ReversingLabs. | | **AWS S3 secret access key** | The secret access key for AWS S3 account authentication. **Note:** In cases where the appliance is hosted by ReversingLabs and Role ARN is used, this value is provided by ReversingLabs. | | **AWS S3 endpoint URL** | Enter the S3 endpoint URL to use S3 over HTTP. After providing the access key ID, secret access key, and endpoint URL values, click **Test** to verify that the appliance can successfully connect to the configured AWS S3 account. Using a custom root CA certificate can cause the connection to fail. If this happens, the custom certificate file should be uploaded to the appliance. Consult [ReversingLabs Support](mailto:support@reversinglabs.com) for assistance. | | **Enable role ARN** | Select to enable authentication using an external AWS role. This allows the customers to use the connector without forwarding their access keys between services. The IAM role used to obtain temporary tokens has to be created for the connector in the AWS console. These temporary tokens allow ingesting files from S3 buckets without using the customer secret access key. | | **Role ARN** | The role ARN created using the external role ID and an Amazon ID. In other words, the ARN which allows the appliance to obtain a temporary token, which then allows it to connect to S3 buckets without using the customer secret access key. | | **External ID** | The external ID of the assumed role. Usually, it’s an ID provided by the entity which uses but doesn’t own an S3 bucket. The owner of that bucket takes the external ID and creates an ARN with it. It is strongly recommended to use a valid External ID in production environments to maintain security. However, in non-production or test environments, you can enter a placeholder value for the External ID if your use case doesn't require a real one. This is useful when you do not want to enforce the External ID requirement while testing configurations. | | **ARN session name** | Name of the session visible in AWS logs. Can be any string. | | **Token duration in seconds** | How long before the authentication token expires and is refreshed. The minimum value is 900 seconds. | | **Refresh buffer** | Number of seconds defined to fetch a new ARN token before the token timeout is reached. This must be a positive number, and the default value is 5. | | **AWS S3 region** | Specify the correct AWS geographical region where the S3 bucket is located. The default value is *us-east-1*. | | **AWS S3 signature** | Used to authenticate requests to the S3 service. In most AWS regions, only Signature Version 4 is supported. For AWS regions other than *us-east-1*, the value *s3v4* must be configured here. | | **AWS S3 number of connection retries** | Maximum number of retries when saving a report to an S3-compatible server. | | **Verify the HTTPS connection against the CA bundle** | Select to enable SSL verification in case of an *https* connection. | | **CA path** | Enter the path on the file system pointing to the certificate of a custom self-hosted S3 server. | | **S3 bucket folder** | Enables specifying and targeting an S3 bucket folder. The folder can be up to 1024 bytes long when encoded in UTF-8, and can contain letters, numbers and special characters: "!", "-", "_", ".", "*", "'", "(", ")", "/". It must not start or end with a slash or contain leading or trailing spaces. Consecutive slashes are not allowed. | | **Spectra Detect Worker store integration behavior options** | These options allow storing samples unprotected and uncompressed with the sample SHA1 as the default S3, or storing them as ZIP files. | | **Zip password** | If you selected storing samples as ZIP files, you can optionally set the password to use for protecting compressed files. | ## YARA Spectra Intelligence Settings | Setting | Description | | ------------------------------------------------------------ | ------------------------------------------------------------ | | **Enable automatic upload of YARA ruleset to Spectra Intelligence** | Disabled by default. When enabled, new YARA rulesets created on the appliance are automatically synchronized with Spectra Intelligence. Additionally, the [Run ruleset continuously in Spectra Intelligence](/SpectraAnalyze/yara-retro/#starting-a-cloud-retro-hunt) checkbox in the YARA ruleset editor is automatically selected. Selecting this option automatically selects the option **Automatic disabling of Spectra Intelligence enabled YARA rulesets**. | | **Automatic retro run of Spectra Intelligence enabled YARA rulesets** | Disabled by default. When enabled, YARA rulesets that are synchronized with Spectra Intelligence are automatically scheduled for a Cloud retro scan. The Cloud retro scan is started after the ruleset is successfully validated. This applies to new rulesets created on the appliance, and to existing rulesets that are edited and synchronized with Spectra Intelligence by selecting the [Run ruleset continuously in Spectra Intelligence](/SpectraAnalyze/yara-retro/#starting-a-cloud-retro-hunt) checkbox in the YARA ruleset editor. The option does not apply to Spectra Core rulesets. | | **Automatic disabling of Spectra Intelligence enabled YARA rulesets** | When enabled, YARA rulesets synchronized with Spectra Intelligence are automatically de-synchronized when they reach the maximum amount of 10 000 matches in the cloud system. They stop receiving new cloud matches until at least 1000 or more matches are removed by the user from the YARA page. When 1000 matches are removed, the ruleset automatically synchronizes with Spectra Intelligence again and starts receiving new matches. This option is automatically enabled when **Enable automatic upload of YARA ruleset to Spectra Intelligence** is selected. | ## URL Analysis | Setting | Description | | -------------------------- | ------------------------------------------------------------ | | **Default crawling method** | The default crawling method to use when submitting URLs for analysis. The available options are *Local* or *Spectra Intelligence*. For more information, see [Privacy of Submitted Files and URLs](/SpectraAnalyze/file-submissions/#privacy-of-submitted-files-and-urls). | | **Enable Local Crawl Selection** | Enabling this option makes an additional **Analyze Crawled Files (Local, On-Device)** setting available under **Submit > URL Analysis > Advanced Analysis Settings > URL Crawling**. If enabled, the process initiates a website crawl directly from the Spectra Analyze host, downloading all resources at crawl depth 1. Because the crawl originates from the local host, visibility to the target site may be affected by network configurations such as firewalls. Downloaded resources are provided as a ZIP archive in the payload section of the URL analysis. **Note**: Local URL Analysis uses the same proxy configuration as Spectra Intelligence to perform the analysis request. | | **URL analysis timeout** | The time in seconds to spend downloading a URL for analysis. This setting applies only to the *Local* crawl method. | | **Maximum download size** | Set the maximum allowed file size in MiB that can be downloaded from each URL submitted to the appliance. The value configured here is not enforced when downloading a single file directly from a URL. It only applies when data is retrieved recursively by crawling links on the submitted URL. The default is 500 MiB, and the maximum is 2000 MiB. When using the *Spectra Intelligence* crawling method, individual files retrieved from the submitted URL are also compared against the **Maximum Fetch File Size** value in [**Spectra Intelligence**](#spectra-intelligence) settings and skipped if larger. | | **Maximum number of attempts** | Set the maximum number of times a file download is attempted. Fatal errors like *File Not Found* or *Connection Refused* are not retried. This setting applies only to the *Local* crawl method. | | **Enable user agent** | Allow setting a custom user agent string to be used when crawling URLs using the *Local* crawl method. | | **User agent string** | This string is used to send information about the client OS, browser, and version. Some websites may return different results based on this information. | | **Enable Spectra Analyze Networking Toolkit** | Enable the appliance to try to collect additional networking data from the following sources: `whois`, `bgpview.io`, `GeoLite City` and DNS services. | ## System Health | Setting | Description | | ----------------------------- | ------------------------------------------------------------ | | ***System health indicator*** | | | **CPU load percentage limit** | Default is 95. | | **Free memory percent limit** | Default is 10. | | **Used disk space percent limit** | Default is 70. All devices are checked and the red indicator is triggered if any of the devices is over the limit. | | ***Queue limits*** | | | **Classifier queue limit** | Default is 50. The red indicator is triggered if it contains more than the maximum number of messages. | | **Collector queue limit** | Default is 50. The red indicator is triggered if it contains more than the maximum number of messages. | | **Sample retry queue limit** | Default is 50. The red indicator is triggered if it contains more than the maximum number of messages. | | **Sample submission queue limit** | Default is 50. The red indicator is triggered if it contains more than the maximum number of messages. | ## Appliances Search | Setting | Description | | ------------------------ | ------------------------------------------------------------ | | **Enable Appliances Search** | **Note:** The appliance needs to be connected to and authorized on the Spectra Detect Manager for this option to be available. Select this option to enable searching for samples on other appliances connected to the same Manager. This feature also allows searching for samples on the current appliance from other instances connected to the same Manager. Samples can be searched by file name, and single or multiple hashes from the [Search Samples box](/SpectraAnalyze/#global-header-bar). | | **Enable Syncing** | **Note:** The appliance needs to be connected to and authorized on a Spectra Detect Manager instance with enabled synchronization for this option to be available. Select this option to enable YARA ruleset synchronization to other appliances from the current appliance, and vice versa. | ## Configuration management using Spectra Detect Manager **Info: All configuration options managed by Spectra Detect Manager are available through the [Spectra Detect Management API](/SpectraDetect/API/ManagementAPI), providing programmatic access for automation and integration purposes.** **ReversingLabs Spectra Detect Manager** allows users to create groups of preconfigured settings, and apply those settings to selected ReversingLabs appliances. This feature makes it possible to configure multiple appliances, and to ensure they all have consistent and correct settings. Spectra Analyze appliances managed by the Spectra Detect Manager have the option to disconnect the appliance from the Manager in the top right corner of the **Administration > Configuration & Update > Configuration** section. Disconnecting the appliance from the Manager reconfigures Spectra Analyze. Additionally, it is possible to confirm that the appliances are properly connected by checking the Spectra Detect Manager status on the [System Status](../../usage-alerts/system-status/) page, under **External Services Connectivity**. The same SNMP **Community** string configured on the appliance under [Administration > Configuration & Update > Configuration > SNMP](#snmp) dialog must be used when adding the appliance to the Spectra Detect Manager instance in the **Add new appliance** dialog. This ensures that Spectra Detect Manager can display the appliance status information correctly, and that changes saved on the Spectra Detect Manager can be propagated to the appliance. When configuration values are changed on Spectra Detect Manager for a group that the appliance belongs to, the appliance is restarted. Spectra Detect Manager [Central Configuration](/SpectraDetect/Config/ApplianceConfiguration/#central-configuration-page) can be used to manage the following settings on ReversingLabs Spectra Analyze appliances: - **Spectra Intelligence** **Tip: Best practice** Multiple Spectra Analyze instances should **not** be configured to use the same cloud account, as this can interfere with appliance functionality, and particularly with YARA ruleset synchronization. It is advised to use these settings only if there is just one Spectra Analyze appliance in the configuration group. - **T1000 File Reputation Appliance** - **SMTP** - **SNMP** - **Cuckoo Integration** - **User Directory** - **System Time** - **Spectra Detect Worker Store Integration** - **System Alerting** --- ## Factory Reset ***Spectra Analyze > Administration > Configuration & Update > Factory Reset*** Performing the factory reset reverts the appliance to its default state and deletes the appliance database data, including YARA rules saved to the disk. Users must input their password and check the confirmation box before performing this action to ensure it is not done by accident. Click **Delete All Data and Settings**, and confirm the deletion to remove the following: - All samples - All YARA rulesets except Spectra Core rulesets - All user accounts created on the appliance - All alerts collected on the appliance - Custom configuration values modified by the appliance users ## Solr Index Reset **Warning: This option should be used for troubleshooting only when instructed by [ReversingLabs Support](mailto:support@reversinglabs.com).** The Advanced Search feature uses Solr to index the samples on the appliance and their metadata in order to include them in the search results. Administrators can use **Solr Index Reset** to manually trigger reindexing data for the search engine. Selecting and confirming this option removes the existing data from the search database and starts importing new data into it. Reindexing the database can be helpful to resolve potential issues with advanced search when restoring the appliance database from backups. However, the reindexing process can take a long time depending on the amount of samples on the appliance. Until reindexing is complete, search results may not be accurate. --- ## Licensing ***Spectra Analyze > Administration > Configuration & Update > Licensing*** On first login after installing or updating the appliance, the appliance must be licensed. **Warning: Appliances without a license work for a trial period of 45 days from the release’s general availability date. Once the trial period expires, the appliance opens to the **Licensing** screen by default and no other actions are available.** ## Standard licensing To license the appliance, do the following: 1. Go to **Spectra Analyze > Administration > Configuration & Update > Licensing**. 2. Click **Request License** to forward the machine ID to [ReversingLabs Support](mailto:support@reversinglabs.com) via email. 3. When ReversingLabs Support responds with the requested license file, upload it using the **Upload License** dialog. **Info: If the Spectra Analyze instance was created by cloning a VM, administrators need to generate a new machine ID by clicking **Generate different Machine ID**, and they should then request a new license for every clone of the original appliance VM.** ## Licensing using Spectra Intelligence Optionally, license the appliance using Spectra Intelligence: 1. Go to **Spectra Analyze > Administration > Configuration & Update > Licensing**. 2. Click **Activate Using Spectra Intelligence**. 3. Fill out the account information, and then click **Request**. 4. A licensing request is sent to Spectra Intelligence and, if the account is valid, the appliance is activated. If a valid account is already configured under [Administration > Configuration & Update > Configuration > Spectra Intelligence](/SpectraAnalyze/Administration/configuration-update/configuration/#spectra-intelligence), the appliance is already licensed. **Warning: Licensed instances that can’t reach Spectra Intelligence work for a 14-day grace period. Once the grace period expires, the appliance opens to the **Licensing** screen by default and no other actions are available.** ## Licensing using APIs Finally, you can also license the appliance using APIs. For more information, see [Licensing API](/SpectraAnalyze/API%20Documentation/licensing). --- ## Redundancy System ***Spectra Analyze > Administration > Configuration & Update > Redundancy System*** Spectra Analyze allows administrators to set up two Spectra Analyze instances into a redundant cluster. The cluster provides switchover capabilities to ensure no data is lost during system upgrades or primary appliance failures. **Info: Only administrators can access and use the redundancy system feature.** To create or manage a redundant cluster, on the primary appliance, go to **Administration > Configuration & Update > Redundancy System**. **Note: This chapter describes redundancy on the same subnet. Spectra Analyze automatically supports redundancy on the same network and takes care of all the details, such as setting up a virtual (shared) IP address. ** However, to set up a redundant system across the internet, users need to set up their own load balancer, for example, HAProxy. This load balancer routes requests to the secondary Spectra Analyze in case the primary one fails. In that case, the procedure to set up a redundant system is the same as in the remainder of this chapter, with the exception that the **Floating IP Address** is ignored. ## How redundancy works on Spectra Analyze A redundant cluster connects two Spectra Analyze appliances: one primary (master) and one secondary (standby). Data synchronizes from primary to secondary at regular intervals, ensuring both contain identical data. The secondary appliance serves as a replica of the primary, and seamlessly takes over if the primary fails. In a cluster, the primary appliance handles tasks such as file uploads and analysis. The secondary receives all new samples and database updates from the primary but doesn't analyze or process files. When the primary appliance fails, all processing transfers to the secondary appliance through automatic switchover. Administrators can also perform manual switchovers and promote the secondary to primary at any point. The cluster is controlled from the primary appliance. The administrator decides which of the two appliances to use as the primary, and performs all cluster configuration and management actions from it. During the cluster configuration process, the primary appliance is accessible and can be used, while the secondary appliance is inaccessible and cannot be used. Once the cluster is configured, the floating IP address should be used to access the cluster instead of individual IP addresses of the appliances. **Warning: Important information about the cluster configuration process** - All data on the secondary appliance is erased during configuration. You must confirm the warning before proceeding. - System performance may be impacted during configuration due to background processes. - If cluster configuration is canceled or interrupted, the secondary appliance may become non-functional depending on the stage at which the interruption occurred. Administrators may attempt resetting it using `tcbase reset` from the appliance console. - After the cluster has been configured, the initial synchronization between the primary and secondary appliances can take up to several hours depending on data volume, increasing network traffic due to data replication. ## Prerequisites for setting up a redundant cluster - The administrator must have access to both Spectra Analyze appliances so that they can log into the secondary appliance during the configuration process. - The Spectra Analyze appliances must be running the same software version. - The system specifications of the two Spectra Analyze appliances should be as similar as possible; especially the RAM and the storage size. Considerable differences in system specifications can cause synchronization issues. - The link between the Spectra Analyze appliances must be at least 1 Gbps. Using a lower bandwidth link in situations with databases over 60 GB can cause database synchronization issues. - Both appliances must be able to connect to each other via SSH. - Host names and IP addresses must be defined for both appliances, as well as the shared (floating) IP address: 1. Go to **Administration > Configuration & Update > Configuration > General > Allowed Hosts**. 2. Add the host name and IP address of the primary and secondary appliance. 3. Add the floating IP address. 4. Perform this on the other appliance as well. ## Creating a redundant cluster Go to **Administration > Configuration & Update > Redundancy System**. If no previous cluster configuration exists, only creation options appear on this page. Click **Create redundant cluster**, and follow the wizard to configure the cluster. Under **STEP 1 - Establish connection**, provide the following information: - **Floating IP address**: IP address for cluster access. Must be in the **Allowed hosts** list on both appliances to allow them to communicate. For more information, see [Prerequisites for setting up a redundant cluster](#prerequisites-for-setting-up-a-redundant-cluster). - **Local IP address**: IP address of the current (primary) appliance. - **Secondary Spectra Analyze IP address**: IP address of the secondary appliance. - **Secondary Spectra Analyze URL**: host name of the secondary appliance in the format *http(s)://XX.XX.X.XXX*. - **Secondary Spectra Analyze user**: administrator username on the secondary appliance. - **Secondary Spectra Analyze password**: administrator password on the secondary appliance. - **Disable TLS Certificate Sharing**: machines in a redundant cluster typically share the same TLS certificate. Select this option to use individual certificates on the appliances. After providing all information, click **Next**. Under **STEP 2 - Check prerequisites**, the primary appliance checks prerequisites. If successful, click **Next** to proceed. Under **STEP 3 - Run the configuration process**, click **Start configuration** to initiate cluster configuration. A confirmation dialog warns about data removal from the secondary appliance. The configuration wizard displays background activities during configuration. In the **RL Cluster** tab, click **Toggle autoscroll on/off** to control log scrolling. When configuration completes successfully, click **Finish** to open the redundancy system page with cluster status information. ## Redundant cluster status To check cluster status, navigate to the floating IP address defined during cluster configuration and go to **Administration > Configuration & Update > Redundancy System**. The **Cluster configuration** section shows configured IP addresses and provides options for [manual switchover](#manual-switchover) or [cluster configuration removal](#removing-cluster-configuration). Under **Status**, you can see detailed information about each node and cluster component, and browse system logs related to the redundancy functionality. The status of the whole cluster is indicated by one of the following modes. | Cluster Mode | Description | | ---------------- | ------------------------------------------------------------ | | **No Cluster** | The cluster has not been defined. | | **Negotiate** | The secondary appliance is not synchronized with the primary appliance. Failover is not yet possible. The cluster needs to decide which appliance to set as the primary. | | **Syncing** | The secondary appliance is in the process of synchronizing with the primary appliance. Failover is currently not possible. | | **Maintenance** | Primary and secondary appliances are being upgraded to new versions. | | **Operational** | The cluster is operational, and the secondary appliance is synchronized with the primary one. Failover is now possible. | The status of individual nodes (appliances) in the cluster is indicated by the following modes. | Node Mode | Description | | -------------------- | ------------------------------------------------------------ | | **Single** | This node is not joined to any cluster. | | **Secondary Not Synced** | This node is configured as the secondary, but data synchronization with the primary node has not started yet. | | **Syncing** | This node is configured as the secondary. Data synchronization with the primary node is in progress. | | **Secondary** | This node is configured as the secondary and is now fully synchronized. | | **Primary** | This node is configured as the primary. | **Note: Users can also check which appliance in the cluster is acting as the primary using the [Redundant Status API](/SpectraAnalyze/API%20Documentation/redundant/).** ## Manual switchover Once operational, the redundant cluster requires minimal interaction beyond status checks. Automatic switchover occurs when the primary appliance fails. However, users can manually perform a switchover at any time if necessary. To do this, from the Spectra Analyze interface on the primary appliance's IP address, go to **Administration > Configuration & Update > Redundancy System > Cluster configuration**. Click **Manual switchover** and confirm. **Warning: Performing a manual switchover from the floating IP address of the redundancy cluster may cause issues.** A switchover promotes the secondary to primary appliance while configuring required services in the background. The duration of the process depends on system specifications and data volume. Any existing RabbitMQ file processing queues are not replicated to the secondary appliance. ## Upgrading a redundant cluster **Warning: Upgrading a redundant cluster from version 9.7.x to 9.8** When upgrading a redundant cluster from version 9.7.x to 9.8, the update may fail due to a locale setting issue, leaving one node on the old version. To prevent this, apply one of the following workarounds on the **primary node** before starting the update: **Option 1: Replace the RL resource file** 1. Download the latest `rl-resource` file. 2. Run the following commands on the primary node: ```bash sudo cp rl-resource /usr/lib/ocf/resource.d/pacemaker/RL sudo chmod 755 /usr/lib/ocf/resource.d/pacemaker/RL sudo chown root:root /usr/lib/ocf/resource.d/pacemaker/RL ``` **Option 2: Break the cluster and update individually** 1. Remove the cluster configuration. 2. Update each node separately. 3. Re-create the cluster after both nodes are on the same version. Contact [ReversingLabs Support](mailto:support@reversinglabs.com) for assistance with either option. The redundancy system feature allows Spectra Analyze administrators to upgrade the appliances in the cluster without affecting the cluster configuration. Upgrades should be performed from the primary appliance. To upgrade both appliances in the cluster, go to **Administration > Configuration & Update > System Update** on the primary appliance. Upload and apply the upgrade package to the primary appliance. After that, the upgrade package is uploaded to the secondary appliance. While the primary appliance is being upgraded, it enters maintenance mode and background services are shut down. This includes services related to the redundancy functionality, which means that the data replication from the primary to the secondary appliance is stopped during the upgrade. The redundancy functionality remains unavailable until the secondary appliance finishes upgrading. However, once the upgrade of the primary appliance is done, users can normally access and work on the primary Spectra Analyze appliance while the secondary is being upgraded. **Info: Upgrade through Spectra Detect Manager** If the primary appliance is connected to the ReversingLabs Spectra Detect Manager, it is also possible to upgrade it from the Spectra Detect Manager interface. Starting the appliance upgrade from Spectra Detect Manager automatically upgrades the entire cluster, including the secondary appliance. ## Removing cluster configuration If the cluster functionality is no longer needed, administrators can remove the cluster configuration. **Warning: Removing the cluster functionality requires a full reinstallation of the secondary appliance. For more information, see the [Setup and initial configuration](../../../initial-configuration).** To dismantle the cluster, from the Spectra Analyze interface on the cluster's floating IP address, go to **Administration > Configuration & Update > Redundancy System > Cluster configuration**. Click **Remove cluster configuration** and confirm. Note that the process of removing the cluster configuration may take some time. Appliances are removed from the cluster and the configured floating IP is deactivated. All primary appliance data is preserved, and the appliance returns to single-node operation mode where it can continue to process files. ## Troubleshooting The cluster may experience [split-brain](https://en.wikipedia.org/wiki/Split-brain_(computing)) during switchover, where both nodes in the cluster act as the primary. You can detect this under **Administration > Configuration & Update > Redundancy System > Status**, where the **Component** status table shows database issues on the secondary appliance. Other related cluster issues appear here, such as database connection failures or standby mode on the primary appliance. To further troubleshoot and mitigate cluster configuration issues, contact [ReversingLabs Support](mailto:support@reversinglabs.com). --- ## System Update ***Spectra Analyze > Administration > Configuration & Update > System Update*** Under **System Update**, update the appliance in either of the following ways: - **Select Update File**: apply an update from the local package provided by ReversingLabs. - **Available Updates**: download an update from the remote ReversingLabs repository. This functionality is available only when the appliance is connected to Spectra Intelligence. **Warning: Before updating the appliance, always create a snapshot or a backup of the appliance to allow reverting to the pre-update state in the event of critical failure.** **Tip: Best practice** It is not necessary to wait for the processing queues to clear, as the system keeps all uploaded files and resumes after the upgrade, but it is highly recommended to notify all appliance users of the impending update before it is performed. **Tip: Redundant clusters** If the appliance is part of a redundant cluster, the update process is slightly different. When the update starts on the primary node, the secondary node is automatically promoted to primary. Once the update completes, the original primary resumes its role and the temporary primary reverts to secondary. This ensures that the update process does not cause any downtime. ## Updating from a local package When an update is available for the appliance, ReversingLabs provides an update package via email or other file transfer service. To apply the update, go to **Administration > Configuration & Update > System Update** and, under **Select Update File**, click **Choose File** to locate the package `.bin` file on the local filesystem. The `.bin` file must be valid and not corrupted in order to successfully update the appliance. Administrators can enter additional information up to 250 characters long about the update into the comment field below. The comment is visible in the appliance logs and can be used for auditing purposes. The comment field is mandatory, but administrators can leave the default message *"Updating the appliance to a new version"*. After selecting the update package and filling in the comment field, click **Update**. The update is applied, and the appliance web server and services are restarted. In some cases, the whole appliance system may reboot. ## Updating from a remote ReversingLabs repository The **Available Updates** section displays one of the following states: - No access to Spectra Intelligence. - No available updates. - Incorrectly configured Spectra Intelligence account. - Appliance completely up-to-date based on the latest Spectra Intelligence data. - Updates available for download. When updates are available for download, this section indicates the current versions of the appliance and the Spectra Core engine. The recommended new version is also indicated. The Spectra Core version number is displayed next to each of the available updates, allowing administrators to quickly see which Spectra Core comes with which appliance version. In the list of available updates, administrators can retrieve one or more supported updates by clicking **Download**. It is possible to download several updates simultaneously. When the status column indicates that the download is complete, under **Selection**, select the desired version by clicking the radio button, and click **Update** to start the process. The update is applied, and the appliance web server and services are restarted. In some cases, the whole appliance system may reboot. Unnecessary update packages are automatically removed to save storage space on the appliance. The last installed package is always preserved. For example, if the appliance is currently on 5.12.0, the 5.12.0 package is preserved. If the administrator has already downloaded packages that can be applied next in the update path, those are also preserved, for example, 5.12.1 and 5.12.4. However, all packages for versions prior to the current one are removed. ### New update notifications If the appliance is connected to Spectra Intelligence, it can automatically check for new updates. When an administrator logs into the appliance, the appliance performs a check for available updates and displays a notification when a new version is available. This check is not performed when regular users log into the appliance. ## Supported update paths The appliance can be directly updated from any minor version to any other minor version of the next major version. Major/feature releases are indicated by the first two numbers of the version number, while the third number is reserved for minor/patch releases. For example, users who want to upgrade their Spectra Analyze 5.9.2 to Spectra Analyze 5.10.3 can do that without having to manually install the intermediate 5.9.3 or 5.10.1 versions. However, major versions cannot be skipped. Updating directly from 5.8.X to 5.10.X is not possible without installing 5.9.X. When updates are available for download, **Available Updates** always indicates the recommended version to install. If several new major versions are available, only one is displayed at a time. Upgrading to one major version unlocks the next major version and displays it in the list. For example, if the appliance is currently on 5.10.3, but both 5.11.0 and 5.12.0 are available in the remote repository, only the 5.11.0 is displayed in the list. When the appliance is updated to 5.11.0, the 5.12.0 is displayed in the list. --- ## Connectors ***Spectra Analyze > Administration > Integrations & Connectors > Connectors*** ## Overview The **Connectors** service allows automatically retrieving a large number of files from external sources and analyzing them on the appliance. Events for the Connectors service are logged as CEF messages and can be monitored if [System Alerting](../../configuration-update/configuration/#system-alerting) is enabled on the appliance. **Info: Connectors can only be configured by the appliance administrator(s), not by regular users.** To manage settings for each connector, go to **Administration > Integrations & Connectors > Connectors**. The sidebar on the left lists all currently supported types of connectors. Select a connector to access its configuration dialog. If a connector is disabled or if it has not been previously configured on the appliance, the dialog contains only the **Enable connector** button. Click the button to start configuring the connector. The following connectors are currently supported: - [AWS S3](#aws-s3) - [Network File Share](#network-file-share) - [Azure Data Lake](#azure-data-lake) - [IMAP - MS Exchange](#imap---ms-exchange) - [SMTP](#smtp) - [ICAP Server](#icap-server) - [CrowdStrike Falcon EDR](#crowdstrike-falcon-edr) - [SentinelOne EDR](#sentinelone-edr) - [Cortex XDR](#cortex-xdr) - [MS Defender EDR](#ms-defender-edr) The configuration of individual connectors is described below. You should also apply [global settings](#global-configuration) for the Connectors service before you [start](#starting-a-connector) or otherwise [manage](#managing-active-connectors) any of the connectors. ## Global configuration In addition to every connector service's specific configuration settings, you can also set up a **Global Configuration**. These settings can be configured once as they apply to all connectors. | Field | Description | | -------------------------------------------------------- | ------------------------------------------------------------ | | Save files with processing errors | Original files that were not successfully uploaded are saved to `/data/connectors/connector-[CONNECTOR_NAME]/error_files/`.| | Maximum upload retries | Number of times the connector attempts to upload the file to the processing appliance. Upon reaching the number of retries, it is saved in the `error_files/` destination or discarded. | | Upload timeout | Period in seconds between upload attempts of the sample being re-uploaded. | | Upload algorithm | The algorithm used for managing delays between attempting to reupload the samples. In **Exponential back-off**, the delay is defined by multiplying the *Maximum upload timeout* parameter by two, until reaching the maximum value of five minutes. **Linear back-off** always uses the *Maximum upload timeout* value for the timeout period between reuploads. | | Maximum upload delay | In case the appliance is under high load, this parameter is used to delay any new upload to the appliance. The delay parameter is multiplied by the internal factor determined by the load on the appliance. | | Database cleanup period | Specifies the number of days for which the data is preserved. | | Database cleanup interval | Specifies the time in seconds in which the database cleanup is performed. | | Max file size (MB) | The maximum sample size in megabytes that is transmitted from the connector to the appliance for analysis. Setting it to 0 disables the option. | | Disk high (%) | Disk high is used to compute the quota for the maximum amount of disk space that can be used by temporary files during transfer. Setting it to 0 disables the option and indicates that unlimited space is available. | ## Starting a connector After configuring your connector settings: - **Test connection**: if available, click to verify the appliance can access the configured item. - **Remove item**: remove all configured settings for the current item. - **Add item**: add another configuration for the current connector. Some connectors allow a limited number of configurations, in which case you must remove at least one configuration before adding another. - **Start connector**: when all items are configured successfully, click **Start connector** at the bottom of the page to initiate the connector service on the appliance. In case of advanced options, if they are not enabled, the connector service does not perform any additional actions on the retrieved files after the Spectra Analyze appliance finishes analyzing them. Users can see the analysis results for each file on its [Sample Details](../../../Sample%20Details) page. All the files retrieved and analyzed on the appliance are accessible to Spectra Analyze users on the [Search & Submissions page](../../../search-page/#results-list). Each file retrieved via a connector has a set of **User Tags** automatically assigned to it, which are based on the file metadata, and can contain information about the file source, the last modification time in the original location, file permissions, and more. Additionally, the files are distinguished from other files by a unique username based on the connector: - AWS S3: `s3_connector` - Network File Share: `fileshare_connector` - Azure Data Lake: `azure-data-lake_connector` - IMAP: `abusebox_connector` - CrowdStrike Falcon EDR: `falcon_connector` ## Managing active connectors With active connectors, you can perform the following actions: - **Pause connector**: while active, the **Start connector** button becomes **Pause connector**. Pausing temporarily halts the service while preserving the current state. Click **Start connector** again to resume scanning. - **Disable connector**: completely disable the service. While disabled, you cannot configure, start, or pause the connector. The configuration is preserved and restored when re-enabled. Previously analyzed files remain on the appliance. Additionally, you can modify connector settings and click **Save changes** while the connector is running without pausing it. If a [purge action](../../../Administration/configuration-update/backup-purge/) occurs while a connector is active, the system automatically stops the connector, performs the purge, then restarts it. ## Folder naming restrictions Some folder names can only include: - Alphanumeric characters (`A–Z`, `a–z`, `0–9`) - Spaces - The following special characters: `_`, `-`, `.`, `(`, `)` To ensure maximum compatibility, avoid using special characters beyond underscore and hyphen. **Warning: The following characters are not allowed:** `/`, `\`, `:`, `*`, `?`, `"`, `<`, `>`, `|`, and the null byte (`\0`). If specifying subfolders, each folder name must conform to these rules. ## Connectors ### AWS S3 The **AWS S3** connector allows connecting up to five S3 buckets to the appliance. When the buckets are connected and mounted to the appliance, it can automatically scan the buckets and submit files for analysis. After analyzing the files, the appliance can place them into the root of each bucket, or, optionally, sort the files into folders based on their classification status. Currently, it is not possible to assign a custom name to each S3 file storage input, and the way to distinguish between configured buckets is to look at their names. #### Configuring S3 buckets To add a new S3 bucket: - Make sure the connector is enabled. If not, click the **Enable connector** button. - Click **Add item** to expand the **S3 File Storage Inputs** section in the S3 dialog and fill in the following fields. | Field | Mandatory | Description | | --------------------------- | --------------------------------------------------- | ------------------------------------------------------------ | | **Paused** | Optional | Pauses the continuous scanning of this storage input. Applies only to Spectra Detect Hub 5.1.0 and higher. | | **AWS S3 access key ID** | Mandatory | The access key ID for AWS S3 account authentication. **Note:** In cases where the appliance is hosted by ReversingLabs and Role ARN is used, this value is provided by ReversingLabs. | | **AWS S3 secret access key** | Mandatory | The secret access key for AWS S3 account authentication. **Note:** In cases where the appliance is hosted by ReversingLabs and Role ARN is used, this value is provided by ReversingLabs. | | **AWS S3 region** | Mandatory | Specify the correct AWS geographical region where the S3 bucket is located. This parameter is ignored for non-AWS setups. | | **Enable role ARN** | Optional | Select to enable authentication using an external AWS role. This allows the customers to use the connector without forwarding their access keys between services. The IAM role used to obtain temporary tokens has to be created for the connector in the AWS console. These temporary tokens allow ingesting files from S3 buckets without using the customer secret access key. If enabled, it exposes more configuration options below. | | **Role ARN** | Mandatory and visible only if `Role ARN` is enabled. | The role ARN created using the external role ID and an Amazon ID. In other words, the ARN which allows the appliance to obtain a temporary token, which then allows it to connect to S3 buckets without using the customer secret access key. | | **External ID** | Mandatory and visible only if `Role ARN` is enabled. | The external ID of the assumed role. Usually, it’s an ID provided by the entity which uses but doesn’t own an S3 bucket. The owner of that bucket takes the external ID and creates an ARN with it. It is strongly recommended to use a valid External ID in production environments to maintain security. However, in non-production or test environments, you can enter a placeholder value for the External ID if your use case doesn't require a real one. This is useful when you do not want to enforce the External ID requirement while testing configurations. | | **Role session name** | Mandatory and visible only if `Role ARN` is enabled. | Name of the session visible in AWS logs. Can be any string. | | **ARN token duration** | Mandatory and visible only if `Role ARN` is enabled. | How long before the authentication token expires and is refreshed. The minimum value is 900 seconds. | | **AWS S3 bucket** | Mandatory | Specify the name of an existing S3 bucket which contains the samples to process. The name can be between 3 and 63 characters long, and can contain only lower-case characters, numbers, periods, and dashes. Each label in the name must start with a lowercase letter or number. The name cannot contain underscores, end with a dash, have consecutive periods, or use dashes adjacent to periods. The name cannot be formatted as an IP address. | | **Processing priority** | Mandatory | Assign a priority for processing files from this bucket from highest (1) to lowest (5). Multiple buckets may share the same priority. Default is 5. | | **AWS S3 folder** | Optional | The input folder inside the specified bucket which contains the samples to process. All other samples are ignored. The name can be between 3 and 63 characters long, and can contain only lower-case characters, numbers, periods, and dashes. Each label in the name must start with a lowercase letter or number. The name cannot contain underscores, end with a dash, have consecutive periods, or use dashes adjacent to periods. The name cannot be formatted as an IP address. If the folder is not configured, the root of the bucket is treated as the input folder. | | **S3 endpoint URL** | Optional | Enter a custom S3 endpoint URL. Specifying the protocol is optional. Leave empty if using standard AWS S3. | | **Server Side Encryption Type** | Optional | Specify the server-side encryption method managed by AWS for your S3 bucket. You can choose either **AES256** to enable Server-Side Encryption with Amazon S3-Managed Keys (SSE-S3) or **aws:kms** to enable Server-Side Encryption with AWS Key Management Service (SSE-KMS). **Note:** This setting should be left blank unless your bucket policy requires SSE headers to be sent to S3. It is mutually exclusive and should not be configured alongside **Customer Encryption Algorithm** or **Customer Encryption Key**. | | **Customer Encryption Algorithm** | Optional | Defines the encryption algorithm used when you provide your own encryption keys. The only valid value for this field is **AES256**. This option is intended for users who prefer to manage their own encryption keys rather than relying on AWS-managed keys. **Note:** It must be used in conjunction with **Customer Encryption Key** and cannot be used simultaneously with **Server Side Encryption Type**.| | **Customer Encryption Key** | Optional | Provide a customer-managed encryption key for encrypting and decrypting objects in your S3 bucket. The key must be a valid Base64-encoded AES256 key. **Note:** It must be used together with **Customer Encryption Algorithm** and is mutually exclusive with **Server Side Encryption Type**. | | **Connect securely** | Optional | If selected, the connector does not accept connections to S3 buckets with untrusted or expired certificates. This setting only applies when a custom S3 endpoint is used. | | **Enable Selection Criteria Using Metadata** | Optional | If selected, the connector only fetches files that have certain [object metadata](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html) saved. This metadata contains information about the classification of the file. This means that the files must have been pre-processed and saved with their metadata in Spectra Detect. The supported file metadata are **Classification** and **Threat name**. | #### AWS S3 connector advanced options **Advanced Options** refer to actions that the connector service can perform on the files after the Spectra Analyze appliance finishes analyzing them. The connector operates and analyzes files even if these advanced options are disabled. They only control the post-analysis activities. Advanced options can be configured for every S3 bucket individually, and the sorting criteria, folder names and folder paths can be different on each configured S3 bucket. The connector can be configured to automatically sort files into user-defined sorting folders on the S3 bucket. Files are sorted into folders based on the [classification](/General/AnalysisAndClassification/Classification) they receive during analysis. | Field | Description | | ----------------------------- | ------------------------------------------------------------ | | **Enable same hash rescan** | Allow any duplicate file hashes to be rescanned. | | **Delete source files** | Allow the connector to delete files on the S3 bucket after they have been processed. | | **Enable automatic file sorting** | Allow the connector to store analyzed files and sort them into folders on every configured S3 bucket based on their classification. Enabling any of these options also switches on **Delete source files**. For more information about naming restrictions, see [Folder naming restrictions](#folder-naming-restrictions).| | **Sort Goodware files into following folder** | Specify the path to folder into which the connector stores files classified as *Goodware/Known*. The path specified here is relative to the address of the S3 bucket. If the folder doesn’t already exist on the S3 bucket, it is automatically created after saving the configuration. This field is mandatory when **Enable automatic file sorting** is selected. | | **Sort Malware files into following folder** | Specify the path to folder into which the connector stores files classified as *Malicious*. The path specified here is relative to the address of the S3 bucket. If the folder doesn’t already exist on the S3 bucket, it is automatically created after saving the configuration. This field is mandatory when **Enable automatic file sorting** is selected. | | **Sort Unknown files into following folder** | Specify the path to the folder where the connector stores files marked as no threats found or unclassified. The path specified here is relative to the address of the S3 bucket. | | **Sort Suspicious files into following folder** | Specify the path to folder into which the connector stores files classified as *Suspicious*. The path specified here is relative to the address of the S3 bucket. If the folder doesn’t already exist on the S3 bucket, it is automatically created after saving the configuration. | ### Network File Share The **Network File Share** connector supports SMB and NFS file-sharing protocols and allows connecting up to five shared network resources to the appliance. When the network shares are connected and mounted to the appliance, it can automatically scan the network shares and submit files for analysis. After analyzing the files, the appliance can optionally sort the files into folders based on their classification status. Currently, it is not possible to assign a custom name to each network share, and the way to distinguish between configured network shares is to look at their addresses. #### Configuring network shares To add a new network share: - Make sure the connector is enabled. If not, click the **Enable connector** button. - Click **Add item** to expand the **Shares** section in the Network File Share Connector dialog and fill in the following fields. | Field | Mandatory | Description | ------------ | ------------------ | ------------------------------------------------------------ | | **Address** | Mandatory | Enter the address of the shared network resource to be mounted to the appliance. The address must include the protocol (SMB or NFS). Leading slashes are not required for NFS shares, for example: *nfs:storage.example.lan*. The address can point to the entire network drive, or to a specific folder, for example: *smb://storage.example.lan/samples/collection*. When the input folder and/or sorting folders are configured, their paths are treated as relative to the address configured here. **Note:** If the address contains special characters, it may not be possible to mount the share to the appliance. The comma character cannot be used in the address for SMB shares. Some combinations of ? and # result in errors when attempting to mount both the SMB and the NFS shares. For more information about naming restrictions, see [Folder naming restrictions](#folder-naming-restrictions). | | **Username** | Optional, SMB only | Enter the username for authenticating to the SMB network share if required. Usernames and passwords for SMB authentication can only use ASCII-printable characters excluding the comma. | | **Password** | Optional, SMB only | Enter the password for authenticating to the SMB network share if required. Usernames and passwords for SMB authentication can only use ASCII-printable characters excluding the comma. | | **Input folder** | Optional | Specify the path to the folder on the network share containing the files to be analyzed by Spectra Analyze. The folder must exist on the network share. The path specified here is relative to the root (address of the network file share). If the input folder is not configured, the root is treated as the input folder. For more information about naming restrictions, see [Folder naming restrictions](#folder-naming-restrictions). | #### Network File Share connector advanced options **Advanced Options** refer to actions that the connector service can perform on the files after the Spectra Analyze appliance finishes analyzing them. The connector operates and analyzes files even if these advanced options are disabled. They only control the post-analysis activities. Advanced options can be configured for every network share individually, and the sorting criteria, folder names and folder paths can be different on each configured network share. The connector can be configured to automatically sort files into user-defined sorting folders on the network share. Files are sorted into folders based on the [classification](/General/AnalysisAndClassification/Classification) they receive during analysis. | Field | Description | | ----------------------------- | ------------------------------------------------------------ | | **Delete source files** | Allow the connector to delete files on the network share after they have been processed. | | **Enable automatic file sorting** | Allow the connector to store analyzed files and sort them into folders on every configured network share based on their classification. Enabling any of these options also switches on **Delete source files**. For more information about naming restrictions, see [Folder naming restrictions](#folder-naming-restrictions).| | **Sort Goodware files into following folder** | Specify the path to folder into which the connector stores files classified as *Goodware/Known*. The path specified here is relative to the address of the network file share. If the folder doesn’t already exist on the network share, it is automatically created after saving the configuration. | | **Sort Malware files into following folder** | Specify the path to folder into which the connector stores files classified as *Malicious*. The path specified here is relative to the address of the network file share. If the folder doesn’t already exist on the network share, it is automatically created after saving the configuration. | | **Sort Suspicious files into following folder** | Specify the path to folder into which the connector stores files classified as *Suspicious*. The path specified here is relative to the address of the network file share. If the folder doesn’t already exist on the network share, it is automatically created after saving the configuration. | | **Sort Unknown files into following folder** | Specify the path to the folder where the connector stores files marked as no threats found or unclassified. The path specified here is relative to the address of the network file share. | | **Rescan Unknowns** | If *Sort Unknown files into following folder* is selected, check this box to allow the connector to rescan samples that were classified as unknown. | | **Rescan Unknowns interval** | If *Rescan unknowns* is selected, specify the interval in days between rescan attempts. Default is one day. | #### Handling rescanned and renamed files The Network File Share connector supports several scenarios involving rescanned and renamed files. The connector has the ability to automatically rename files, which allows it to handle duplicates and files manually renamed by the user. [Advanced file sorting options](#network-file-share-connector-advanced-options) must be configured for the connector to be able to move files after they are analyzed. | Scenario | Result | | ------------------------------------------------------------ | ------------------------------------------------------------ | | A new file is analyzed, but a file with the same filename already exists in the output folder. Their hashes are identical. | The original file remains in the output folder. The last modified timestamp value in the file metadata is updated for the original file. Its filename remains unchanged. The new file is removed after analysis. | | A new file with the same filename as an old file is analyzed. Their hashes are identical. However, the old file no longer exists in the output folder, or the new file has been uploaded for the first time. | The new file is saved to the output folder. Its filename remains unchanged. | | A new file is analyzed, but a file with the same filename already exists in the output folder. Their hashes are different. | The new file is renamed and saved to the output folder. The file renaming pattern is to add (#) after the original file name. For example *Name.extension* would be saved as *Name(1).extension*, *Name(2).extension*, *Name(3).extension*, etc. | | A file has been analyzed previously and moved into one output folder (A). Based on reanalysis, it should be moved to a different output folder (B). | The file is moved to a different output folder (B). Its filename remains unchanged. | ### Azure Data Lake The **Azure Data Lake** connector allows connecting up to five Azure Data Lake Gen2 containers to the appliance. When the containers are connected and mounted to the appliance, it can automatically scan them and submit files for analysis. After analyzing the files, the appliance can place them into the root of each container, or, optionally, sort the files into folders based on their classification status. Currently, it is not possible to assign a custom name to each Azure Data Lake container, and the way to distinguish between configured containers is to look at their names. **Note: This connector is not compatible with containers that have the **Blob Soft Delete** feature enabled.** #### Configuring Azure Data Lake containers To add a new Azure Data Lake container: - Make sure the connector is enabled. If not, click the **Enable connector** button. - Click **Add item** to expand the **Azure Data Lake Inputs** section in the Azure Data Lake dialog and fill in the following fields. | Field | Mandatory | Description | | -------------------- | --------- | ------------------------------------------------------------ | | **Storage account name** | Mandatory | The name of the storage account. | | **Storage access key** | Mandatory | The access key used for *Shared Key Authentication*. This value should end in `==`. | | **Container name** | Mandatory | Specify the name of an existing Azure Data Lake container which contains the samples to process. The name can be between 3 and 63 characters long, and can contain only lower-case characters, numbers, and dashes. Each label in the name must start with a lowercase letter or number. The name cannot contain consecutive dashes. | | **Folder** | Optional | The input folder inside the specified container which contains the samples to process. All other samples are ignored. | #### Azure Data Lake connector advanced options **Advanced Options** refer to actions that the connector service can perform on the files after the Spectra Analyze appliance finishes analyzing them. The connector operates and analyzes files even if these advanced options are disabled. They only control the post-analysis activities. Advanced options can be configured for every Azure Data Lake container individually, and the sorting criteria, folder names and folder paths can be different on each configured Azure Data Lake container. The connector can be configured to automatically sort files into user-defined sorting folders on the Azure Data Lake container. Files are sorted into folders based on the [classification](/General/AnalysisAndClassification/Classification) they receive during analysis. | Field | Description | | ----------------------------- | ------------------------------------------------------------ | | **Delete source files** | Allow the connector to delete files on the Azure Data Lake container after they have been processed. | | **Enable automatic file sorting** | Allow the connector to store analyzed files and sort them into folders on every configured Azure Data Lake container based on their classification. Enabling any of these options also switches on **Delete source files**. For more information about naming restrictions, see [Folder naming restrictions](#folder-naming-restrictions).| | **Sort Goodware files into following folder** | Specify the path to folder into which the connector stores files classified as *Goodware/Known*. The path specified here is relative to the address of the Azure Data Lake container. If the folder doesn’t already exist on the Azure Data Lake container, it is automatically created after saving the configuration. This field is mandatory when **Enable automatic file sorting** is selected. | | **Sort Malware files into following folder** | Specify the path to folder into which the connector stores files classified as *Malicious*. The path specified here is relative to the address of the Azure Data Lake container. If the folder doesn’t already exist on the Azure Data Lake container, it is automatically created after saving the configuration. This field is mandatory when **Enable automatic file sorting** is selected. | | **Sort Unknown files into following folder** | Specify the path to the folder where the connector stores files marked as no threats found or unclassified. The path specified here is relative to the address of the Azure Data Lake container. | | **Sort Suspicious files into following folder** | Specify the path to folder into which the connector stores files classified as *Suspicious*. The path specified here is relative to the address of the Azure Data Lake container. If the folder doesn’t already exist on the Azure Data Lake container, it is automatically created after saving the configuration. | ### IMAP - MS Exchange The **IMAP AbuseBox** connector allows connecting to a Microsoft Exchange server and analyzing retrieved emails on the Spectra Analyze appliance. To be able to use the IMAP AbuseBox connector, the following requirements must be met: - IMAP must be enabled on the Exchange server. - A new user account must be configured on the mail server and its credentials provided to the connector in the configuration dialog. - A dedicated email folder must be created in the Exchange user account, and its name provided to the connector in the configuration dialog. All emails forwarded to that folder are collected by the connector and automatically sent to the appliance for analysis. To improve performance and minimize processing delays, each email sample gets analyzed and classified only once. When [automatic message filing](#imap-connector-advanced-options) is enabled, each email sample is moved only once, based on its first available classification. Because of that, it is recommended you improve classification of emails with malicious attachments by enabling classification propagation and allowing the retrieval of Spectra Intelligence classification information during sample analysis instead of after. Administrators can enable these options under [**Administration > Configuration > Spectra Detect Processing Settings**](../../../Administration/configuration-update/configuration/#spectra-detect-processing-settings). #### Configuring the Exchange user account To configure a new connection with the Exchange user account, fill in the following fields. | Field | Mandatory | Description | ------------ | ------------------ | ------------------------------------------------------------ | | **Server domain** | Mandatory | Enter the domain or IP address of the Exchange server. The value should be FQDN, hostname or IP. This should not include the protocol (for example, *http*). | | **Email folder** | Mandatory | Enter the name of the email folder from which email messages are collected for analysis. This folder must belong to the same Exchange user account for which the credentials are configured in this section. The folder name is case-sensitive. | | **Connection type** | Mandatory | Supports **IMAP (Basic Authentication)** and **Exchange (OAuth2)** methods of authentication. Depending on the selection, the next section of the form asks for different user credentials. **IMAP (Basic Authentication)** requires *Username* and *Password*, **Exchange (OAuth2)** requires *Client ID*, *Client Secret* and *Tenant ID*. | | **Email address** | Mandatory | Enter the primary email address of the configured Exchange user account. | | **Access type** | Mandatory | **Delegate** is used in environments where there’s a one-to-one relationship between users. **Impersonation** is used in environments where a single account needs to access many accounts. | | **Connect securely** | Optional | Enabled by default. When enabled, the connector does not accept connections to Exchange servers with untrusted or expired certificates. | #### IMAP connector advanced options **Advanced Options** refer to actions that the connector service can perform on the files after the Spectra Analyze appliance finishes analyzing them. The connector operates and analyzes files even if these advanced options are disabled. They only control the post-analysis activities. The connector can be configured to automatically sort emails into user-defined sorting folders on the Exchange user account. Emails are sorted into folders based on the [classification](/General/AnalysisAndClassification/Classification) they receive during analysis. | Field | Description | | ------------------------------- | ------------------------------------------------------------ | | **Enable automatic message filing** | Allow the connector to move analyzed emails and sort them into folders in the configured Exchange email user account. | | **Malware folder** | Specify the name of the folder into which the connector stores emails classified as *Malicious*. If the folder doesn’t already exist on the Exchange user account, it is automatically created after saving the configuration. This field is mandatory when **Enable automatic message filing** is selected. **Note:** If **Allow suspicious** is not selected, emails classified as *Suspicious* are sorted into the *Malware* folder. | | **Unknown folder** | Specify the name of the folder into which the connector stores emails with no malicious content detected. If the folder doesn’t already exist on the Exchange user account, it is automatically created after saving the configuration. This field is mandatory when **Enable automatic message filing** is selected. **Note:** If **Allow suspicious** is selected, emails classified as *Suspicious* are sorted into the *Unknown* folder. Emails classified as *Goodware* or *No threats found* are always sorted into the *Unknown* folder. | | **Allow suspicious** | If selected, emails classified as *Suspicious* are sorted into the *Unknown* folder. If not selected, emails classified as *Suspicious* are sorted into the *Malware* folder. | ### SMTP The **SMTP** connector allows analyzing incoming email traffic on the appliance to protect users from malicious content. When enabled, the connector service collects emails with attachments and uploads them to the appliance for analysis. Each email message is saved as one file. If email uploading fails for any reason, the connector automatically retries to upload it to the appliance. When the analysis is complete, each email message receives a classification status from the appliance. In this operating mode, the connector acts as an SMTP relay. Therefore, the connector should not be used as a front-end service for accepting raw email traffic, but only as a system inside an already established secure processing pipeline for SMTP email. **Warning: To allow the SMTP connector to inspect and collect email traffic, users must ensure that the SMTP traffic in their network is diverted to **port 25/TCP** prior to configuring the connector on the appliance.** Additional port configuration may be required on the appliance. Because it involves manually modifying configuration files, this action can cause the appliance to malfunction. Contact [ReversingLabs Support](mailto:support@reversinglabs.com) for instructions and guidance. #### Configuring SMTP To configure SMTP, fill in the following fields. | Field | Mandatory | Description | | -------------------- | --------- | ------------------------------------------------------------ | | **Profile** | Mandatory | Select a profile for this connector. The available options are *Default* and *Strict* which correspond to different Postfix configuration files. For more information, see [Profiles vs. Postfix configuration](#profiles-vs-postfix-configuration). | | **Authorized networks** | Mandatory if `Profile: Strict` is selected. | With **Profile: Default**, a custom value is not allowed but is instead set to `0.0.0.0/0 [::]/0`. With **Profile: Strict**, a custom value is required. For more information, see [Profiles vs. Postfix configuration](#profiles-vs-postfix-configuration). | #### Profiles vs. Postfix configuration If **Profile** is set to *Default*, you don’t enforce TLS traffic and you accept any SMTP client. This corresponds to the following Postfix configuration: ``` mynetworks = 0.0.0.0/0 [::]/0 smtpd_tls_security_level = may smtp_tls_security_level = may ``` If **Profile** is set to *Strict*, you do enforce TLS and you can also specify trusted SMTP clients; see line 1 in the example below. In *Strict* mode, the relevant portion of the configuration looks like this: ``` mynetworks = 0.0.0.0/0 [::]/0 smtpd_tls_security_level = encrypt smtp_tls_security_level = encrypt smtpd_tls_mandatory_ciphers = high smtpd_tls_mandatory_protocols = !SSLv2, !SSLv3, !TLSv1, !TLSv1.1 smtpd_tls_mandatory_exclude_ciphers = aNULL, MD5 ``` For specific syntax, see [Postfix documentation](https://www.postfix.org/postconf.5.html#mynetworks). #### Use case: Accept email from any email client or server To configure the service to accept email from any email client or server, do the following: 1. **Enable the SMTP connector**. 2. **Contact [ReversingLabs Support](mailto:support@reversinglabs.com)** with: - Your intended email forwarding address range. - A formal request to enable email forwarding. 3. After receiving your request, ReversingLabs does the following: - Creates an MX DNS record for your hosted service. - Configures receiver restrictions to accept email only from your domain. 4. Once ReversingLabs has added the MX record to the DNS for your hosted service, **create email forwarding rules** in your email system to automatically forward emails to the hosted service for processing. ### ICAP Server The **ICAP Connector** acts as an ICAP server and processes files sent through ICAP-enabled systems. It applies rules based on classifications, file size, and processing time, ensuring files meet the specified criteria before being analyzed by Spectra Detect. #### Supported topologies The ICAP Server Connector is designed to integrate seamlessly in any ICAP deployment model, including but not limited to: - Application Delivery Controllers (ADCs) - Forward Proxy - Ingress Controller - Intrusion Prevention System - Load Balancer - Managed File Transfer - Next-Generation Firewall - Protecting Enterprise Storage - Reverse Proxies - Secure Remote Access - SSL Inspection and Termination - Web Application Firewall (WAF) - Web Gateway - Web Traffic Security #### Integration with ICAP clients - [Integration with F5](/Integrations/ICAP/f5/). - [Integration with Kiteworks](/Integrations/ICAP/kiteworks/). #### ICAP response codes The table below lists the ICAP response codes and their meanings. | ICAP response code | Description | |--------------------|-------------| | **100 Continue** | Signals the client to continue sending data to the ICAP server after the ICAP preview message. | | **200 OK** | The request was successfully processed. This status is returned whether the file is blocked or not. If the file was blocked, the `X-Blocked` header is set to `True`. In RESPMOD, a blocked file results in a **403** HTTP status code. | | **204 No modification needed** | Returned when the file was not blocked and the client sent an `Allow: 204` header in the request. | | **400 Bad request** | Indicates a failure during file submission, analysis processing, or delivering results back to the client. | | **404 Not found** | The ICAP service could not be found. | | **405 Method Not Allowed** | The requested method is not supported on the endpoint. | | **500 Internal Server Error** | A generic server-side error occurred. | #### Configuring ICAP To configure the ICAP Server connector: - Make sure the connector is enabled. If not, click the **Enable connector** button. - Fill in the following fields. | Field | Description | ------------ | ------------------ | | **Max file size** | Specify the maximum file size in megabytes that the ICAP Connector processes. Files exceeding this size are not analyzed. Default is 0, indicating that unlimited space is available. | | **Allow classifications** | Select which classifications to allow. The available options are *goodware*, *unknown*, *suspicious*, *malicious*. Files not matching the selected classifications are blocked. | | **Service alias** | The base service name is *spectraconnector* and cannot be changed. Here you may define any additional aliases your ICAP client can use to connect. Do not re-enter *spectraconnector* here.| | **Timeout** | Set the timeout period in seconds for processing requests. If a file is not processed within this time, the request is terminated. Default is 300. | | **REQMOD block page URL** | **Request Mode (REQMOD)** processes outgoing client requests before they reach the destination server. Use this mode to validate uploaded files to ensure they meet security requirements. Enter the full URL your ICAP clients fetch when a request is blocked. **Note:** To use the default block page, set it to `https://{RL_APPLIANCE_IP}/icap-block-page` and replace `{RL_APPLIANCE_IP}` with your appliance’s actual IP or hostname. If you host a custom block page, enter its URL here and ensure it's accessible to ICAP clients. In some deployments, `RL_APPLIANCE_IP` may refer to a virtual IP or a load-balancer IP. | | **RESPMOD block page** | **Response Mode (RESPMOD)** processes server responses before they are delivered to the client. Use this mode to scan downloaded files for malware or sanitize content before delivery. Click **Browse** to upload a page to replace the content of the HTTP response. The uploaded file is served to the client instead of the original response from the web server. The file size must not exceed 0.5 MB. | | **Use TLS** | Allow using a secure connection (TLS v1.3) when communicating with the ICAP server. | | **Scan raw data**| Extract the raw HTTP message body, and send it to RL scan as is. | ## Endpoint security integrations ### CrowdStrike Falcon EDR The **CrowdStrike Falcon EDR** connector integrates Spectra Analyze with your Falcon environment. It authenticates to Falcon Cloud, retrieves relevant file artifacts for analysis on the appliance, and can optionally write classification results back to Falcon events as comments. Multiple Falcon inputs are supported per appliance. #### Creating Falcon API credentials Before configuring the connector, you must create API credentials in your Falcon console. Go to **Falcon Support and resources > API Clients and keys**, click **Create API client**, and set the following API scopes: | **Scope** | **Read** | **Purpose** | **Write** | **Purpose** | | ---------------------- | -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | | **Alerts** | ✅ | Get alert details. | ✅ | Append comment. | | **Quarantined Files** | ✅ | Get quarantine file IDs, get quarantine file details. | ❌ | | | **Real Time Response (RTR)** | ✅ | Open RTR session, list files in host quarantine, delete RTR session. | ✅ | Upload file from host quarantine to Falcon Cloud, get extracted file contents. | | **Event Streams** | ✅ | List available event streams, subscribe to event stream. | ❌ | | | **Sensor Download** | ✅ | Test connection | ❌ | | **Info: Once the API client is created, note its **Client ID** and **Client Secret**.** In addition to the `api` host, the connector needs access to CrowdStrike's `firehose` host. For example, when `us-2` is selected, ensure that the connector host has network access to the following: - `api.us-2.crowdstrike.com:443` - `firehose.us-2.crowdstrike.com:443` #### Configuring Falcon EDR To add a new Falcon input, click **Configure**. If there is an existing input, you can add more by clicking **Add new connection**. Click **Get started** to start the setup wizard, and provide the following information. | Field | Description | |--------------------|-------------| | **Connector name** | A descriptive name for this connector instance. | | **Cloud region** | The region assigned to your CrowdStrike account. For example, *us-1* or *us-2*. | | **Client ID** | The Client ID for your Falcon API credentials. | | **Client secret** | The Client Secret for your Falcon API credentials. | | **Application ID** | The Application ID used by this integration. Default is *falcon-connector*. If multiple connector instances are used under the same Crowdstrike tenant, each **must** have a unique Application ID. | | **Append Spectra Analyze results to EDR events** | Enabled by default. When enabled, Spectra Analyze classification details are added as comments to related Falcon events. Analysts can view verdicts and risk information directly in CrowdStrike without switching tools. The connector operates and analyzes files even if this option is disabled. The option only controls whether results are written back to Falcon. | Click **Test connection** or **Save and test connection** to verify connectivity and save your configuration. In case of an existing configuration, you can click **Remove** to delete it. Optionally, click **Add new connection** to configure another connection. Click **Next** to configure [**General settings**](#global-configuration). Once you have configured general settings, click **Next** to go to an **Overview** of your connector(s). From this page, you can review your configurations and general settings, remove or edit them. Click **Complete setup** to save and exit the wizard. ### SentinelOne EDR #### Setting up SentinelOne permissions Before configuring the connector, ensure the following permissions are assigned to the API user in the SentinelOne management console: | **Category** | **Permissions** | |---|---| | **Endpoints** | View View Threats File Fetch | | **Endpoint Threats** | View Update Analyst Verdict Fetch Threat File Xdr Actions | | **Activity** | View | #### Configuring SentinelOne EDR To add a new SentinelOne EDR input, click **Configure**. If there is an existing input, you can add more by clicking **Add new connection**. Click **Get started** to start the setup wizard, and provide the following information. | Field | Description | |----------------------|----------------| | **Connector name** | A descriptive name for this connector instance. | | **Host** | The SentinelOne EDR host instance. | | **API key** | The SentinelOne EDR API key. | | **Agent node names** | Add multiple agent node names by separating them using the enter or tab key. Leave empty to include all agents. | | **Append Spectra Analyze results to SentinelOne EDR alerts** | When enabled, Spectra Analyze classification details are added as comments to SentinelOne alerts containing RL Spectra Analyze classification data. | Click **Test connection** or **Save and test connection** to verify connectivity and save your configuration. In case of an existing configuration, you can click **Remove** to delete it. Optionally, click **Add new connection** to configure another connection. Click **Next** to configure [**General settings**](#global-configuration). Once you have configured general settings, click **Next** to go to an **Overview** of your connector(s). From this page, you can review your configurations and general settings, remove or edit them. Click **Complete setup** to save and exit the wizard. ### Cortex XDR #### Setting up Cortex XDR permissions Before configuring the connector, ensure the following permissions are configured within Cortex XDR: | **Permission** | **Access** | |---|---| | **Alerts & Incidents** | View/Edit | | **Action Center** | View/Edit (File Retrieval, File Search) | | **Endpoint Groups** | View | #### Configuring Cortex XDR To add a new Cortex XDR input, click **Configure**. If there is an existing input, you can add more by clicking **Add new connection**. Click **Get started** to start the setup wizard, and provide the following information. | Field | Description | |--------------|----------------| | **Connector name** | A descriptive name for this connector instance. | | **Host** | The Cortex XDR host instance. | | **API key** | The Cortex XDR API key. | | **Auth ID** | The Authentication ID for the Cortex XDR integration. | | **Endpoint groups** | Add multiple groups by separating them using the enter or tab key. Leaving it empty includes all groups. | | **Endpoint names** | Add multiple names by separating them using the enter or tab key. Leaving it empty includes all names. | | **Append Spectra Analyze results to Cortex XDR alerts** | Enabled by default. When enabled, Spectra Analyze classification details are added as comments to related Cortex XDR alerts. | Click **Test connection** or **Save and test connection** to verify connectivity and save your configuration. In case of an existing configuration, you can click **Remove** to delete it. Optionally, click **Add new connection** to configure another connection. Click **Next** to configure [**General settings**](#global-configuration). Once you have configured general settings, click **Next** to go to an **Overview** of your connector(s). From this page, you can review your configurations and general settings, remove or edit them. Click **Complete setup** to save and exit the wizard. ### MS Defender EDR #### Setting up MS Defender permissions Before configuring the connector, ensure the following application permissions are assigned to the Entra ID app registration. All permissions must be of the **Application** type, not **Delegated**. | **Category** | **Permissions** | |---|---| | **Microsoft Graph** | `SecurityAlert.ReadWrite.All` `SecurityIncident.ReadWrite.All` `User.Read` | | **WindowsDefenderATP** | `Alert.ReadWrite.All` `File.Read.All` `Library.Manage` `Machine.LiveResponse` `Machine.ReadWrite.All` | #### Configuring MS Defender EDR To add a new MS Defender EDR input, click **Configure**. If there is an existing input, you can add more by clicking **Add new connection**. Click **Get started** to start the setup wizard, and provide the following information. | Field | Description | |-------------------------|----------------| | **Connector name** | A descriptive name for this connector instance. | | **Tenant ID** | The Microsoft Entra ID (Azure AD) tenant ID. | | **Client ID** | The client ID of the application registered in Azure AD. | | **Client secret** | The client secret of the application registered in Azure AD. | | **Append Spectra Analyze results to Defender alerts** | Enabled by default. When enabled, Spectra Analyze classification details are added as comments to related MS Defender EDR alerts. | Click **Test connection** or **Save and test connection** to verify connectivity and save your configuration. In case of an existing configuration, you can click **Remove** to delete it. Optionally, click **Add new connection** to configure another connection. Click **Next** to configure [**General settings**](#global-configuration). Once you have configured general settings, click **Next** to go to an **Overview** of your connector(s). From this page, you can review your configurations and general settings, remove or edit them. Click **Complete setup** to save and exit the wizard. --- ## Flexible Intel Feed ***Spectra Analyze > Administration > Integrations & Connectors > Flexible Intel Feed*** When the **Flexible Intel Feed** is enabled, the appliance uses a configured Spectra Intelligence account to generate a personalized, private, and curated Indicators of Compromise (IoCs) feed. This feed is based on all files submitted to Spectra Intelligence, enriched with metadata from across the ReversingLabs product portfolio, and served in STIX/TAXII format (version 2.1). **Important: Although Spectra Analyze submissions are used to generate the feed, the feed itself is not accessible directly from the appliance. ** To handle and manage IoCs efficiently, it is recommended you do either of the following: - Use a Threat Intelligence Platform (TIP) such as [**OpenCTI**](/Integrations/category/opencti) or [**Anomali**](/Integrations/category/anomali). These platforms support the standardized STIX/TAXII protocol for seamless integration with the FIF service. - Use [TCTF-0003 Flexible Intel Feed](/SpectraIntelligence/Feed/TAXII/tctf-0003/) to consume the feed via API. ## Prerequisites Before you can enable the Flexible Intel Feed, you must configure **Spectra Intelligence credentials** under [Administration > Configuration & Update > Configuration > Spectra Intelligence](../../../Administration/configuration-update/configuration/#spectra-intelligence). Optionally, on the same page, enable **Automatic Upload to Spectra Intelligence** to ensure continuous IoC generation. If auto-upload isn't enabled, you can submit files manually by selecting them and checking **Threat Intelligence** in the analysis settings to trigger submission to Spectra Intelligence. ## Enabling FIF To enroll the appliance into the FIF service, go to **Administration > Integrations & Connectors > Flexible Intel Feed** and click **Enable Feed**. When the process completes, a popup window displays the following information: | Component | Description | Example | |-----------|-------------|---------| | **TAXII Discovery** | Entry point for clients to discover available TAXII services and API Roots. | `https://data.reversinglabs.com/api/taxii/taxii2/` | | **TAXII API Root** | Base endpoint that hosts collections containing STIX data. | `https://data.reversinglabs.com/api/taxii/flexible-intel-feeds/` | | **Collection ID** | Unique collection ID assigned to your Spectra Intelligence account containing your personalized IoCs feed in STIX format. | Generated automatically. | | **Username** | Username used to access your FIF containing your Spectra Intelligence username with `/fif` appended. | `u/company/user/a1000/fif` | | **Password** | Access password shown only once when the feed is enabled. Save it securely. If lost, use the provided link to generate a new password. | Generated automatically. | **Warning: The password is displayed only once when the feed is enabled. Save it securely. If lost, use the provided link to generate a new password.** To revisit this information later, go to **Administration > Integrations & Connectors > Flexible Intel Feed** and click **Show Connection Details**. **Info: The feed stores information for the last 30 days.** --- ## Integrations ***Spectra Analyze > Administration > Integrations & Connectors > Integrations*** ## Overview Spectra Analyze supports optional integration with multiple first-party and third-party static and dynamic analysis services. Through these integrations, samples can be automatically submitted for dynamic analysis or reanalyzed on demand using any of the supported services. Analysis services must be configured on the **Administration > Integrations & Connectors > Integrations** page by an administrator. The administrator can determine which file types to analyze with each configured integration. First-party integrations are: - [ReversingLabs Cloud Sandbox](#reversinglabs-cloud-sandbox) for dynamic analysis. - [ReversingLabs Auxiliary Analysis](#static-analysis) for static analysis. Third-party integrations are always used for dynamic analysis, and they are: - [CAPE Sandbox](#cape-sandbox) - [Cisco Secure Malware Analytics](#cisco-secure-malware-analytics) - [Cuckoo Sandbox](#cuckoo-sandbox) - [FireEye Sandbox](#fireeye-sandbox) - [Joe Sandbox](#joe-sandbox) - [VMRay](#vmray) ## Integrations configuration Under **Administration > Integrations & Connectors > Integrations**, you can see the list of all integrations that can be configured on the appliance. To see only the configured integrations, in the top right corner, select **Configured**. To see all possible integrations, select **Show all**. ### Integrations For every integration, a subset of the following options are available: - **Enabled**: enable or disable an integration. First-party integrations are enabled by default. - **Show links**: not configurable for first-party integrations. For third-party integrations, enable or disable the display of links to the third-party web interfaces in the analysis report. - **Test connection**: click to test the connection to the integration. - **Automatic upload**: enable or disable automatic file uploads. - **Automatic file retrieval**: enabled by default for [ReversingLabs Cloud Sandbox](#reversinglabs-cloud-sandbox). When enabled, files dropped during dynamic analysis that are within configured file size limits are downloaded to the appliance and analyzed locally. - **Include in classification**: enabled by default for [ReversingLabs Cloud Sandbox](#reversinglabs-cloud-sandbox). When enabled, all future sample uploads, as well as any reanalyzed samples, may receive their final classification from the ReversingLabs Cloud Sandbox. Samples that already had a recent dynamic analysis classification before the option was enabled update their classification once their [Sample Details Summary](../../../Sample%20Details/sample-details-summary/) page is opened, or during regular appliance synchronizations with Spectra Intelligence. Only ReversingLabs Cloud Sandbox can be configured to affect the final sample classification. Other analysis results do not affect the overall final classification of the sample, but are, rather, another source of information for analysts. - **Actions**: not available for first-party integrations. Click **Configure** to configure a third-party integration for the first time, or **Edit** to update an existing third-party integration. For more information about how to configure each of the integrations, see below. ### File types On this page, you can also edit which **File types** are submitted for analysis when uploaded automatically. Click **Edit**, and for every file type group, select or remove the file types to submit. Click **Save** to save your changes. The file types configured here apply only to files uploaded automatically. However, you can analyze any file type with any enabled dynamic analysis service when manually queuing a file to be reanalyzed provided that the dynamic analysis service supports that file type. Similarly, if no file types are specified, and automatic upload is enabled, all files uploaded to the appliance are indiscriminately submitted for dynamic analysis, regardless of whether their file type is supported. **Warning: Configuration updates may take several minutes to apply. Features remain available during this time, but changes, such as enabling or disabling automatic file uploads, are not applied instantly.** #### Profiles Some dynamic analysis integrations support analysis profiles, which map file types to specific analysis environments. Profile configuration is available under **File Types > Edit**. Integrations that support profiles have a **Fetch Profiles** button that retrieves the list of available profiles from the connected service instance. After fetching, select a profile and click **Add** to add it. On each added profile, from the drop-down list, assign which file types are submitted to that profile. To remove a profile, click **Remove Profile**. ## Dynamic analysis ### ReversingLabs Cloud Sandbox Spectra Analyze is integrated with the **ReversingLabs Cloud Sandbox** by default, and configured by ReversingLabs. Optionally, administrators can enable or disable [various options](#integrations) for this integration. **Warning: Prerequisites** For this service to be available, the appliance has to be connected to [Spectra Intelligence](../../../Administration/configuration-update/configuration/#spectra-intelligence). For more information, see [Analysis services - ReversingLabs Cloud Sandbox](../../Analysis-services/cloud-sandbox.md). ### CAPE Sandbox To configure CAPE, go to **Administration > Integrations & Connectors > Integrations**. In the top right corner, click **Show all** to show all possible integrations. Find **CAPE Sandbox** and, in the **Actions** column, click **Configure**. Provide the following information: - **API scheme and host**: enter the API server scheme and host. - **API port**: enter the API server port. - **Test connection**: click to test the API connection. - **Use API host for web host**: select this option to use the API server host as the web server host. If this option is not selected, provide the web host information below. - **Web scheme and host**: enter the web server scheme and host. - **Web port**: enter the web server port. - **Test connection**: click to test the web connection. - **Submit only distinct files to CAPE**: disabled by default. Select this option to submit only distinct files to CAPE. When this option is enabled, if a file has already been submitted to Spectra Analyze and analyzed, it is not sent for reanalysis when it is submitted again. This option applies to files submitted using the GUI and the API. It does not affect the reanalysis feature - you can still submit files for reanalysis with any of the integrations even if the files have already been analyzed. To save your changes, click **Submit**. **Note: Maximum supported file size is 400 MiB.** For more information, see [Analysis services - CAPE Sandbox](../../Analysis-services/other-integrations.md#cape-sandbox). ### Cisco Secure Malware Analytics To configure Cisco Secure Malware Analytics, go to **Administration > Integrations & Connectors > Integrations**. In the top right corner, click **Show all** to show all possible integrations. Find **Cisco Secure Malware Analytics** and, in the **Actions** column, click **Configure**. Provide the following information: - **API URL**: enter the Cisco Secure Malware Analytics API URL. - **API key**: enter the API key. - **Test connection**: click to test the API connection. - **Send files privately**: select this option to send files privately. - **Populate web URL based on API URL**: select this option to populate the web URL based on the API URL. If this option is not selected, provide the web host information below. - **Web scheme and host**: enter the Cisco Secure Malware Analytics web URL. - **Test connection**: click to test the web connection. To save your changes, click **Submit**. **Note: Maximum supported file size is 250 MiB.** For more information, see [Analysis services - Cisco Secure Malware Analytics](../../Analysis-services/other-integrations.md#cisco-secure-malware-analytics). ### Cuckoo Sandbox To configure Cuckoo, go to **Administration > Integrations & Connectors > Integrations**. In the top right corner, click **Show all** to show all possible integrations. Find **Cuckoo** and, in the **Actions** column, click **Configure**. Provide the following information: - **API scheme and host**: enter the API server scheme and host. - **API port**: enter the API server port. - **Enable Cuckoo API Authentication**: select this option to enable Cuckoo API authentication. - **Token**: enter the API token. - **Test connection**: click to test the API connection. - **Use API host for web host**: select this option to use the API server host as the web server host. If this option is not selected, provide the web host information below. - **Web scheme and host**: enter the web server scheme and host. - **Web port**: enter the web server port. - **Test connection**: click to test the web connection. To save your changes, click **Submit**. **Note: Maximum supported file size is 400 MiB.** For more information, see [Analysis services - Cuckoo Sandbox](../../Analysis-services/other-integrations.md#cuckoo-sandbox). ### FireEye Sandbox To configure FireEye, go to **Administration > Integrations & Connectors > Integrations**. In the top right corner, click **Show all** to show all possible integrations. Find **FireEye** and, in the **Actions** column, click **Configure**. Provide the following information: - **API scheme and host**: enter the API server scheme and host. - **API port**: enter the API server port. - **Username**: enter the API username. - **Password**: enter the API password. - **API version**: from the drop-down list, select the API version. - **Test connection**: click to test the API connection. - **Use API host for web host**: select this option to use the API server host as the web server host. If this option is not selected, provide the web host information below. - **Web scheme and host**: enter the web server scheme and host. - **Web port**: enter the web server port. - **Test connection**: click to test the web connection. To save your changes, click **Submit**. **Note: Maximum supported file size is 100 MiB.** For more information, see [Analysis services - FireEye Sandbox](../../Analysis-services/other-integrations.md#fireeye-sandbox). ### Joe Sandbox **Info: Important** If Joe Sandbox integration is enabled, the following terms and conditions apply: [Joe Sandbox Cloud Online Service Terms and Conditions of Use](https://www.joesandbox.com/tandc). To configure Joe Sandbox, go to **Administration > Integrations & Connectors > Integrations**. In the top right corner, click **Show all** to show all possible integrations. Find **Joe** and, in the **Actions** column, click **Configure**. Provide the following information: - **API URL**: enter the Joe Sandbox API URL. For on-premise installation, the API URL is usually `schema://server-address:port/joesandbox/index.php/api`. - **API key**: enter the API key. - **Test connection**: click to test the API connection. - **Enable internet access**: select this option to enable samples to be analyzed with full internet access on Joe Sandbox systems. - **Allow URL submissions**: select this option to allow URL submissions. If enabled, URL submissions are analyzed with full internet access on Joe Sandbox systems. - **Populate web URL based on API URL**: select this option to populate the web URL based on the API URL. If this option is not selected, provide the web host information below. - **Web scheme and host**: enter the web URL. For on-premise installation, the web URL is usually `schema://server-address:port/joesandbox/index.php`. - **Test connection**: click to test the web connection. - **Submit only distinct files to Joe Sandbox**: disabled by default. Select this option to submit only distinct files to Joe Sandbox. When this option is enabled, if a file has already been submitted to Spectra Analyze and analyzed, it is not sent for reanalysis when it is submitted again. This option applies to files submitted using the GUI and the API. It does not affect the reanalysis feature - you can still submit files for reanalysis with any of the integrations even if the files have already been analyzed. To save your changes, click **Submit**. **Note: Maximum supported file size is 400 MiB.** For more information, see [Analysis services - Joe Sandbox](../../Analysis-services/other-integrations.md#joe-sandbox). ### VMRay To configure VMRay, go to **Administration > Integrations & Connectors > Integrations**. In the top right corner, click **Show all** to show all possible integrations. Find **VMRay** and, in the **Actions** column, click **Configure**. Provide the following information: - **API URL**: enter the VMRay API URL. - **API key**: enter the API key. - **Test connection**: click to test the API connection. - **Populate web URL based on API URL**: select this option to populate the web URL based on the API URL. If this option is not selected, provide the web host information below. - **Web scheme and host**: enter the VMRay web URL. - **Test connection**: click to test the web connection. To save your changes, click **Submit**. **Note: Maximum supported file size is 305 MiB.** For more information, see [Analysis services - VMRay](../../Analysis-services/other-integrations.md#vmray). ## Static analysis Static analysis services are configured by ReversingLabs. Optionally, administrators can enable or disable [Automatic upload](#integrations) for this integration. **Note: Maximum supported file size is 100 MiB.** Submitting only distinct files is not supported. For more information, see [Analysis services - ReversingLabs Auxiliary Analysis](../../Analysis-services/auxiliary-analysis.md). --- ## YARA Repositories ***Spectra Analyze > Administration > Integrations & Connectors > YARA Repositories*** YARA rulesets can be imported from preconfigured online repositories or from custom GitHub repositories added by admins or authorized users. **Warning: Only GitHub repositories are supported. GitLab repositories are not supported as a YARA rule source.** To access the page where you can add, edit and delete YARA repositories, do either of the following: - Go to **Administration > Integrations & Connectors > YARA Repositories**. - From the [**YARA**](../../../yara/#understanding-the-yara-page) page, click **Actions > Manage YARA Repositories**. On this page, click **Add Repository** and provide the following information: - **Repository URL**: mandatory. Specifying the repository URL supports including a custom port when the YARA repository is hosted on a non-standard port. Custom ports are supported for both direct connections and connections through a proxy. - **Repository name**: mandatory. - **Source branch**: optional. If the source branch is not specified, the default repository branch is used, for example, *main*. - **API token**: optional. Enter an API token if the repository requires authentication. - **Update/import preferences**: - **Manual**: selected by default. The repository appears in the [Import From Online Sources](../../../yara/#creating-new-yara-rulesets) list, and rules are only be imported when a user manually triggers the import. In this case, the imported rules are owned by the user performing the import. - **Auto-Update/Auto-Update & Auto-Import**: if either of these options is selected, the system monitors the repository for changes, and any updates are imported by the `yara_import_service_user` account once an hour. ### Adding a GitHub repository To add a private GitHub repository, you must create a personal access token in your GitHub account and provide it under **API token** when adding the repository. This token lets Spectra Analyze access the repository to import YARA rules. Choose one of the following token types: - [**Fine-grained personal access token**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) (recommended): 1. Go to [GitHub > Personal access tokens > Fine-grained tokens](https://github.com/settings/personal-access-tokens). 2. Click **Generate new token**. 3. Select **Only select repositories** and specify one or more repositories to connect. 4. Under **Repository permissions**, set **Contents** to **Read-only**. 5. Generate and copy the token. **Note that you will only see the token once.** - [**Classic personal access token**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) (alternative): this token gives access to all private repositories in your account. Spectra Analyze only uses it to fetch rulesets from the one you specify. 1. Go to [GitHub > Personal access tokens](https://github.com/settings/tokens). 2. Click **Generate new token > Generate new token (classic)**. 3. Select the **repo** scope. 4. Generate and copy the token. **Note that you will only see the token once.** --- ## Quota Usage Alerts ***Spectra Analyze > Administration > Usage & Alerts > Quota Usage Alerts*** This page allows users to configure Spectra Intelligence quota usage email notifications. Users can enable email alerting, manage recipients, and define alert thresholds based on system quotas. **Info: To receive email alerts, users must first configure the Spectra Intelligence account under [**Administration > Configuration & Update > Configuration > Spectra Intelligence**](../../../Administration/configuration-update/configuration/#spectra-intelligence).** Once you have configured the Spectra Intelligence account, provide the following information: - **Enable**: check this box to enable system alerts via email. Once enabled, quota usage alerts are sent to the specified recipients. - **Add All Users to the Recipients List**: check this box to add all system users to the recipients list for email alerts. The list is updated once a day. - **Recipients**: enter the email addresses to receive system alerts. Multiple email addresses can be added by pressing **Enter** after each one. If **Add All Users to the Recipients List** is checked, additional recipients cannot be manually added. - **Alert when quota has reached**: select one or more quota levels at which email alerts are triggered. The available options are *50%*, *75%*, and *90%*. - **Alert when quota has been exceeded**: check this box to trigger an alert when the system's quota has been exceeded. --- ## System Status ***Spectra Analyze > Administration > Usage & Alerts > System Status*** The **System Status** page shows the general health of the appliance. **Tip: Best practice** For optimal system performance, ensure that **System Services**, **Supervisor Services**, **External Services** (primarily Spectra Detect Manager and Spectra Intelligence, if configured), **system load** and **RabbitMQ queues** operate normally. Other stats depend on which services and/or third-party integrations are enabled on the appliance. This page also displays the internal build version and the version of Spectra Core at the top right, should that information be needed when interacting with [ReversingLabs Support](mailto:support@reversinglabs.com). ## Downloading logs The **Download Logs** button allows the user to download a support archive containing relevant system logs and configuration files from the Spectra Analyze instance as a single file. The archive includes connector configuration data from `/etc/connectors`, which helps ReversingLabs Support troubleshoot connector-related issues. The contents of the support archive downloaded this way are identical to the contents of the archive generated by running the `tcbase support` command directly from the console. The only difference between the two is that, when run, the `tcbase support` command may break up large log files. During processing, the button is disabled and says *Retrieving logs…*. When processing is done, the log file is downloaded to the user's hard drive, while the button is reactivated. Users should not close the page or navigate away until the logs are created. If needed, the user can then email the retrieved log file to [ReversingLabs Support](mailto:support@reversinglabs.com). ## Appliance status details | **Icon** | **Section** | **Description** | |----------|-------------|-----------------| | ![Network](images/analyze-admin-4-systemstatus-1.png) | **Network** | Network interfaces on the appliance and their current estimated transfer status for incoming and outgoing traffic. The displayed transfer rate is updated periodically, and might not capture peak traffic on the interface. To get the approximate traffic traversing through the network, multiply the numbers by 8. | | ![RabbitMQ](images/analyze-admin-4-systemstatus-2.png) | **RabbitMQ Queues** | The status of the queues on the appliance used for background tasks, such as calls to Spectra Intelligence/T1000 APIs, Spectra Core processing requests, data collection/input, and more. The size of individual queues varies and might reach low thousands.This section helps to ensure that all queues are running and have at least one consumer, and that the number of messages is not increasing. If that is not the case, especially if any of the queues show more than 100 000 messages, contact [ReversingLabs Support](mailto:support@reversinglabs.com). | | ![Connectors](images/analyze-admin-4-systemstatus-3.png) | **Connectors** | If any of the [Connectors](../../../Administration/integrations-connectors/connectors) are enabled and configured on the appliance, this section indicates the status of each connector. Otherwise, this section is empty. | | ![CPU](images/analyze-admin-4-systemstatus-4.png) ![Disk Partitions](images/analyze-admin-4-systemstatus-5.png) ![Memory](images/analyze-admin-4-systemstatus-6.png) | **CPU** **Disk Partitions** **Memory** | Current resource utilization on the appliance, showing general load, storage size, and storage usage. If there are any red icons, that means the system is under more load than it can handle, and the traffic needs to be partitioned.In case of CPU and memory indicators showing a red icon, consider increasing the CPU and RAM parameters for the Spectra Analyze virtual machine. If memory usage consistently goes over 75%, memory capacity should be increased. Similarly, if storage usage goes over 75%, consider increasing the storage capacity. | | ![System Services](images/analyze-admin-4-systemstatus-7.png) ![Supervisor Services](images/analyze-admin-4-systemstatus-8.png) | **System Services** **Supervisor Services** | Current state of the critical services on the appliance. Any failures indicated with the red icon mean the appliance is not functioning correctly and [ReversingLabs Support](mailto:support@reversinglabs.com) should be notified. | | ![Scale](images/analyze-admin-4-systemstatus-9.png) | **Scale** | A critical service for processing samples through Spectra Core. Any failures indicated with the red icon mean the appliance is not functioning correctly and [ReversingLabs Support](mailto:support@reversinglabs.com) should be notified.This section also allows users with the appropriate user roles to access the list of YARA rulesets with warnings. If there are any rulesets with warnings on the appliance, the *YaraWarnings* icon will not be green, and will show the number of warnings instead. Clicking the icon redirects to the YARA Hunting page filtered to display only rulesets with warnings. Here the offending rulesets can be edited or disabled to improve the processing speed of the appliance. | | ![External](images/analyze-admin-4-systemstatus-10.png) | **External Services Connectivity** | Current state of the services that the appliance interacts with externally.**SMTP** is the email service, typically for enabling password reset emails. **NTP** is the service for time server synchronization. **Spectra Intelligence** indicates the connectivity status for the Spectra Intelligence service.If any of the services are showing a red icon, it typically means they are not enabled or not configured properly. Check if the external services are operational, and make sure they are properly set up on the [Configuration](../../../Administration/configuration-update/configuration) page.Dynamic analysis services supported by the appliance are also listed here with icons indicating whether they are enabled and connected. These services can be configured under [Integrations](../../../Administration/integrations-connectors/integrations).If a dynamic analysis service is enabled and configured, the current number of files queued for analysis is shown here. Otherwise, this section isn't displayed. | --- ## Layouts Editor ***Spectra Analyze > Administration > Users & Personalization > Layouts Editor*** Under **Layouts Editor**, you can create a new sample summary layout or edit an existing one. ReversingLabs provides several built-in layouts that can be viewed from the drop-down list under **Manage Layout Mode > Layouts**: - **RL Default Layout**: includes all available data blocks. - **Tier 1/Tier 2+ Analyst**: corresponds to the SOC analyst role. - **Researcher**: corresponds to the researcher role. - **AI Summary**: provides an AI summary of a sample's behavior and classification. ## Adding layouts To create a new layout, do either of the following: - Use a built-in layout as a starting point for your own by selecting it from the **Manage Layout Mode > Layouts** drop-down list. Then edit it, click **Save as** and provide a new name. - Click **Create New Layout** to create a layout from scratch. The available data blocks are: - **Sample Information**: hashes, first and last seen, filenames, uploaders, user and system tags. - **Sources**: detection sources, sample data from connector EDR integrations. - **Sample Description**: detailed sample characteristics with ability to search for similar samples. - **Relationship Graph**: visual overview of sample relations and their classifications. - **MITRE ATT&CK**: triggered tactics and techniques from statis and dynamic analysis. - **Attribution Data**: LLM-generated sample attribution details (campaigns, victims, vulnerabilities, sources), malware family insights (threat name, aliases, first/last seen dates, current version, packer, targeted OS, targeted industries), and related threat actors. Shown only for suspicious and malicious samples. - **Network References**: top five extracted and contacted URIs/Domains/IPs, ranked by classification. This block also shows the number of unique references. - **Static Analysis Insights**: top five static analysis indicators, ranked by priority. This block also shows the total number of static analysis indicators. - **Dynamic Analysis Insights**: top five dynamic analysis signatures, ranked by risk factor. This block also shows the total number of RL Cloud Sandbox signatures. - **YARA Matches**: top five YARA rulesets, ranked by classification impact. This block also shows the total number of matched YARA rulesets. - **Email Information**: shown only for email samples. - **AI Summary**: provides an AI summary of a sample's behavior and classification. Any user-created layout can be saved either as personal or shared. Personal layouts are available only to the user that created them, and shared ones are available to other users on the machine. ## Deleting layouts To delete a layout, go to **Manage Layout Mode > Layouts > New Layout** and click to open the drop-down list. Select the layout to delete, click **Delete** and confirm the deletion of this layout. --- ## Risk Tolerance Levels ***Spectra Analyze > Administration > Users & Personalization > Risk Tolerance Levels*** Risk tolerance levels determine how aggressively Spectra Analyze classifies samples by configuring which analysis sources contribute to the final classification. Spectra Analyze provides multiple risk tolerance levels, each with different analysis sources and thresholds. For more context on how classification and risk factors work together, see the [Classification](/General/AnalysisAndClassification/Classification) guide. **Info: - The availability of analysis sources depends on your appliance configuration.** - **RL Cloud Sandbox** results are weighed more heavily and can classify a sample as malicious even if other sources do not. **Warning: Higher sensitivity levels include more sources and lower thresholds, which increases detection rates but may also increase false positives.** ### Default risk tolerance level **ReversingLabs Default** is the default configuration that provides balanced detection without additional analysis sources. In this case, only **RL Cloud Sandbox** can change the final classification from **Suspicious** to **Malicious**. ### Risk tolerance levels comparison | Analysis Source | ReversingLabs Default | High | Medium | Low | | --- | --- | --- | --- | --- | | **Auxiliary Analysis** | No impact | Score >1000: MaliciousScore >700: Suspicious | Score >700: MaliciousScore >300: Suspicious | Score >700: MaliciousScore >300: Suspicious | | **Network Data** | No impact | Apply payload classification to URL. | Apply payload classification to URL and consult at least two 3rd party reputation sources. | Apply payload classification to URL and consult at least one 3rd party reputation source. | | **RL Cloud Sandbox** | Can change Suspicious to Malicious (setting can be enabled on integration page). | Score >7: MaliciousScore >5: Suspicious | Score >5: MaliciousScore >3: Suspicious | Score >5: MaliciousScore >3: Suspicious | | **Joe Sandbox** | No impact | Score >8: MaliciousScore >5: Suspicious | Score >6: MaliciousScore >3: Suspicious | Score >6: MaliciousScore >3: Suspicious | | **YARA** | No impact | YARA Forge Core Ruleset | YARA Forge Extended Ruleset | YARA Forge Full Ruleset | ## Selecting a risk tolerance level To select a risk tolerance level: 1. Go to **Administration > Users & Personalization > Risk Tolerance Levels**. 2. Review the available risk tolerance levels and their respective settings. 3. Click the desired risk tolerance level to select it. 4. Click **Apply changes** to save the selection, or **Discard** to cancel. The active risk tolerance level is indicated with an ***(Active)*** label. ## Configuring a risk tolerance level To configure a risk tolerance level: 1. Go to **Administration > Users & Personalization > Risk Tolerance Levels**. 2. Click **Configure** on the desired risk tolerance level to expand the configuration options. 3. Select or clear the checkboxes next to each analysis source to enable or disable them: - **Auxiliary Analysis** - **Network Data** - **RL Cloud Sandbox** - **Joe Sandbox** - **YARA** 4. Click **Apply changes** to save the configuration, or **Discard** to cancel. --- ## Tokens ***Spectra Analyze > Administration > Users & Personalization > Tokens*** Under **Tokens**, you can manage authentication tokens, which are per-user keys for authenticating to the [Spectra Analyze APIs](/SpectraAnalyze/API%20Documentation/). ## Adding tokens To create a new token, click **Add Token** and, from the drop-down list, select a **User**. Clicking **Save**, **Save and add another**, or **Save and continue editing** assigns a token to the selected user. Optionally, do the following: | Icon | Description | | ---------- | ------------------- | | ![Change selected user](images/analyze-admin-1-tokens-changeuser.png) | Opens a new window where you can [change the selected user's information](/SpectraAnalyze/Administration/users-personalization/users#editing-users). | | ![Add another user](images/analyze-admin-1-tokens-adduser.png) | Opens a new window where you can [add another user](/SpectraAnalyze/Administration/users-personalization/users#adding-users). | | ![View selected user](images/analyze-admin-1-tokens-viewuser.png) | Leaves the **Tokens** page and opens [the selected user's information](/SpectraAnalyze/Administration/users-personalization/users#editing-users) in the same tab. | ## Searching for tokens The **Tokens** page contains a search bar for finding specific tokens. The search is case-insensitive. To search for a token, enter an exact or partial key or username, and then click **Search**. To view the full list of tokens again, click the link denoting the total number of tokens in the parentheses next to the number of search results. The token list supports multi-column ordering. The contents of every column can be sorted in ascending or descending order by clicking the column name. When another column name is clicked, the ordering priority is shifted to the new column and indicated by numbers next to the column names. ## Editing tokens To edit an existing token, from the list on the **Tokens** page, click its key. From this page, you can update any information entered while [adding the token](#adding-tokens). This page also contains a **History** link that displays the history of changes related to that particular token. ## Deleting tokens To delete one or more tokens, from the **Tokens** page, find and select the tokens you want to delete. Then, under **Action**, select **Delete Selected Tokens** and click **Go**. Alternatively, find and click the key of the token you want to delete, and at the bottom of the page, click **Delete**. On the next page, confirm the deletion of this token. --- ## User Roles ***Spectra Analyze > Administration > Users & Personalization > User Roles*** Users must have an assigned user role. ## Adding user roles To create a new user role, click **Add User Role**, and enter the following information: - **Name**: name of the new user role. Mandatory. - **Description**: description of the new user role. Optional. - **General Access > YARA View**: allow overall access to the YARA page. Without this permission, users do not see the **Yara** option in the top navigation bar. - **YARA > Publish YARA Rules**: allow users to publish YARA rules. This permission requires YARA synchronization to be enabled on the Spectra Detect Manager and then subsequently on Spectra Analyze. - **YARA > Delete YARA Rules**: allow users to delete YARA rules. Without this permission, users can only delete their own repositories. **Warning: Granting **Delete YARA Rules** without also granting **Publish YARA Rules** may cause synchronization issues with Spectra Detect Manager. A confirmation dialog is displayed in case of this configuration.** To save your changes, click **Submit**. ## Editing and deleting user roles Standard user roles cannot be deleted, but they can be edited. Custom user roles can be both edited and deleted. Standard user roles have the following permissions: | Permission | All Permissions | Researcher | YARA Developer | | ----------------------- | ---------------------------------- | --------------------------------- | ---------------------------------------- | | | All permission settings turned on. | Full access to research features. | Research access without YARA publishing. | | **Submissions** | ✓ | ✓ | ✓ | | **YARA View** | ✓ | ✓ | ✓ | | **Publish YARA Rules** | ✓ | ✓ | X | | **Delete YARA Rules** | ✓ | ✓ | X | To edit a user role, find it on the list on the **User Roles** page, and click **Edit**. Update it as appropriate, and then click **Submit**. To delete a custom user role, find it on the list on the **User Roles** page. Click **Delete**, and confirm the deletion. --- ## Users ***Spectra Analyze > Administration > Users & Personalization > Users*** ## Adding users To create a new user, click **Add User** and enter the following obligatory information: - **Username** - **Password** - **Password Confirmation** - **Email Address** - **User Role**: from the drop-down list, select the appropriate [user role](/SpectraAnalyze/Administration/users-personalization/user-roles/) for this user. The available options are *All Permissions, Researcher, YARA Developer*. Optionally, under **Personal Info**, provide the user's **First Name** and **Last Name**. To save your changes, click **Save**, **Save and add another**, or **Save and continue editing**. ## Searching for users The **Users** page contains a search bar for finding specific users. The search is case-insensitive. To search for a user, enter an exact or partial username or email address, and then click **Search**. To view the full list of users again, click the link denoting the total number of users in the parentheses next to the number of search results. The user list supports multi-column ordering. The contents of every column can be sorted in ascending or descending order by clicking the column name. When another column name is clicked, the ordering priority is shifted to the new column and indicated by numbers next to the column names. You can also use the filters in the right sidebar to filter the list of users by last login, date joined, status (active, superuser), and role. ## Editing users To edit an existing user's settings, from the list on the **Users** page, click their username. From this page, you can update any information entered while [adding the user](#adding-users). You can also update the following **Permissions**: - **Active**: designates whether this user should be treated as active. It is recommended you deactivate users by clearing this option, instead of deleting accounts. - **Superuser**: designates that this user has full access to all features, regardless of the [user role](/SpectraAnalyze/Administration/users-personalization/user-roles/) assigned to them. The **Important dates** section lists the dates when this user was added and when they last logged in. ## Removing users You can remove users in the following ways: - **Deleting users**: from the **Users** page, find and select the users you want to delete. Then, under **Action**, select **Delete Selected Users** and click **Go**. Alternatively, find and click the username of the user you want to delete, and at the bottom of the page, click **Delete**. On the next page, confirm the deletion of this user. - **Deactivating users**: from the **Users** page, find and click the username of the user you want to deactivate. Under **Permissions**, clear the **Active** checkbox, and then click **Save**. **Tip: Best practice** It is not recommended you delete users. You should instead deactivate them. When removing a user who has created YARA rulesets on the appliance, the ownership of those rulesets is automatically transferred to the administrator account that removed the previous owner account. An administrator cannot remove or deactivate their own account while they are logged in. An administrator account can only be removed or deactivated by another administrator account. ## User directory settings The Spectra Analyze appliance supports user account management with the Lightweight Directory Access Protocol (LDAP). LDAP authentication can be enabled and configured under [Administration > Configuration & Update > Configuration > Authentication](../../configuration-update/configuration/#authentication). Importantly, the existing local accounts on the appliance are not managed or in any way affected by LDAP when its configuration changes. Similarly, any username conflicts between LDAP and existing user accounts on the appliance resolve in favor of the existing account. For example, if an account named "goodware" exists on the appliance, it is not possible to assign the same name to an LDAP account. Users added via the User Directory synchronization are automatically assigned a [user role](../../users-personalization/user-roles/). Users marked as **Superuser** have the **All Permissions** user role. Otherwise, they are assigned the **Researcher** user role. --- ## Spectra Analyze Dashboard — Submission Stats, Trends & PDF Reports The **Dashboard** displays statistics related to the amount and type of files that have been [submitted](./file-submissions.md) and processed on the appliance within a specified time range. ## Dashboard UI | UI element | Description | | ---------- | ------------------- | | ![Advanced Search box](images/a1000-dash-advancedsearch.png) | [Advanced Search box](./#advanced-search-box) | | ![Time range filter](images/a1000-dash-timefilter.png) | [Time range filter](./#time-range-filter) | | ![Download Report button](images/a1000-dash-downloadreport.png) | [Download Report button](./#download-report-button) | ### Advanced Search box The [Advanced Search box](./advanced-search.md) is a text field where users can enter search queries and get a list of all supported keywords. Recent search queries are preserved across the **Dashboard** and [**Search & Submissions page**](./search-page.md). Advanced search also supports [non-keyword](../advanced-search/#non-keyword-queries) searches, allowing the users to quickly build queries without using keywords. ### Time range filter The time range filter allows users to set the period for which the data is displayed on the dashboard page. All time values refer to UTC time. By default, the time range filter is set to **Last Week**. ### Download Report button Clicking the **Download Report** button exports the current state of the dashboard page into a PDF file. ## Analysis Statistics ![Dashboard section showing analysis statistics.](images/a1000-dash-1-analysisstatistics.png) **Analysis Statistics** breaks down the number of files submitted to the appliance into the total number of submitted files, total number of files extracted from submitted files, and total size of all submitted files. These are further categorized into analyzed emails, archives, apps and other file types. Finally, this section also displays the [classification distribution](/General/AnalysisAndClassification/Classification) of analyzed files in the selected time range and their corresponding graphs. Hovering over the graphs displays the number of samples with that classification at specific points in time. ## Top Malicious Family Detections by Malware Type ![Dashboard section showing top malicious family detections by malware type.](images/a1000-dash-2-malwaretype.png) **Top Malicious Family Detections by Malware Type** displays the most common malware types detected in files analyzed in the specified time range. The most prevalent threat families for each malware type are listed with the count of samples they were detected in. Clicking any of the entries in this section opens the advanced search page with local search results for the selected threat name and time range criteria. ## YARA Matches ![Dashboard section showing a tabular overview of favorited YARA rules.](images/a1000-dash-3-yara.png) **YARA Matches** show an overview of YARA hunting activities on the appliance and in the Spectra Intelligence cloud. Users can see a list of their [**Favorite**](../yara/#results) YARA rulesets or **Last Matched** rulesets. If there are no favorited YARA rulesets, the table defaults to the **Last Matched** view. Both table views can be further filtered by match sources. Filtering can be configured to show **All**, **Local**, **Cloud**, **Local Retro**, or **Cloud Retro** matches. Each table row shows the YARA ruleset name, its owner, one or more match sources, the number of matches per classification, the latest match time, and the number of new matches in the last 24 hours/7 days/30 days. Rules with matches in the last 24 hours have the label **NEW**. Clicking a specific ruleset name opens the ruleset on the YARA page. ## Timeline Analysis for Detected Malware Samples ![Dashboard section showing a tabular overview of all malicious samples on the appliance, broken down into categories depending on the time difference between their local classification time and the "first seen" date in the Spectra Intelligence cloud](images/a1000-dash-4-malwaresamples.png) **Timeline Analysis for Detected Malware Samples** displays all malicious samples present on the appliance, highlighting the difference between their local and cloud classification times. This section always shows all available information as it is not affected by the time range filter at the top of this page. The data set displayed here includes all malicious samples on the appliance, regardless of whether they were submitted to the appliance by the users or downloaded from Spectra Intelligence. Depending on the time difference between the local and cloud classification times, all malicious samples available on the appliance fall into one of the following categories. | Category | Description | | --------------------- | ------------------------------------------------------------ | | **Never Seen** | Samples classified as malicious by the appliance that were never seen in the Spectra Intelligence cloud. If the appliance is not connected to Spectra Intelligence, all malicious samples are categorized as **Never Seen**. | | **More Than 30 Days** | Samples that were first seen in the Spectra Intelligence cloud more than 30 days after local classification as malicious. | | **30 Days Prior** | Malicious samples that were first seen in the Spectra Intelligence cloud 7-30 days after local classification as malicious. Apart from the aggregate number of samples on top, this section is broken down into columns with daily totals. | | **7 Days Prior** | Malicious samples that were first seen in the Spectra Intelligence cloud up to 7 days after local classification as malicious. Apart from the aggregate number of samples on top, this section is broken down into columns with daily totals. | | **Same Day** | Samples that were locally classified as malicious and first seen in the Spectra Intelligence cloud on the same day. | | **7 Days After** | Malicious samples that were first seen in the Spectra Intelligence cloud up to 7 days prior to local classification as malicious. Apart from the aggregate number of samples on top, this section is broken down into columns with daily totals. | | **30 Days After** | Malicious samples that were first seen in the Spectra Intelligence cloud 7-30 days prior to local classification as malicious. Apart from the aggregate number of samples on top, this section is broken down into columns with daily totals. | | **More Than 30 Days** | Malicious samples that were first seen in the Spectra Intelligence cloud 30-90 days prior to local classification as malicious. | | **More Than 90 Days** | Malicious samples that were first seen in the Spectra Intelligence cloud more than 90 days prior to local classification as malicious. | ## Top Email Threats Collected During Sample Analysis ![A table showing a list of email samples, with associated threat names and counts.](images/a1000-dash-5-emailthreat.png) **Top Email Threats Collected During Sample Analysis** shows the list of email samples grouped by email address or email subject. It can be filtered and exported using the following options: - **Classification filter**: by default, the table shows email samples classified as malicious, but it can be filtered to show goodware, suspicious, or samples with no threats found. Setting this filter to *All Classified* shows all email samples regardless of classification. If this filter option is selected, some table columns are left empty because every extracted email address/subject can originate from samples with varying classifications, and data can’t be aggregated in a meaningful way. - **Filter by Email Address/Subject and Threat Name**: text fields that can be used to filter results by threat name and, depending on the option selected under *Pivot by*, either email address or subject. Both fields support autocompletion, and suggest only those options that exist in the table. Filtering by threat name is possible only when the table is filtered to show malicious or suspicious samples. - **Pivot by**: drop-down list which controls the contents of the *Pivoting Information* column in the table (email address or email subject), and affects what can be filtered using the email filter text field. - **Email address type filter**: available only when you select *Pivot by Email address*. This filter can be used to display samples that have the extracted email address in either the *To* or *From* field. This filter is disabled when the table is filtered to *Pivot by Email Subject*. - **Export**: export the entire table as a CSV file. To export a single page, select it by clicking the checkbox on the far left, and then click *Export*. Selecting and exporting individual table rows is currently not supported. The table data is organized into the following columns: - **Checkbox**: click to select a single page when exporting data. Selecting and exporting individual table rows is currently not supported. - **Risk Score**: all emails are assigned a [risk score](/General/AnalysisAndClassification/Classification/#risk-score) that corresponds to the severity value of the most prevalent threat name detected in samples containing the extracted email address or subject. - **Last Seen**: indicates when the appliance last recorded the sample(s) containing the threat. - **Threat Name/Threat Count**: the name of the threat with the most detections related to each entry, and the number of samples containing both the pivoting information and the detected threat. Click the threat name in this column to perform an [Advanced Search](./advanced-search.md) query. - **Total Classified**: shows the number of classified email samples that contain the listed pivoting information. The title of this column dynamically changes to match the classification selected in the *Classification filter*. - **Type**: this column is visible when using *Pivot by Email Address* and shows the type of email. - **Pivoting Information**: contains the email addresses/subjects, depending on the option selected in the *Pivot by* filter. To see a list of samples containing a specific address/subject, click the links. Email-related tags are displayed below each of the entries. Click any of the links or tags to perform an [Advanced Search](./advanced-search.md) query. - **Total Emails**: total number of samples containing the pivoting information. ## Top URIs Collected During Sample Analysis **Top URIs Collected During Sample Analysis** shows a list of malicious and/or interesting URIs extracted from files analyzed in the specified time range. It can be filtered and exported using the following options: - **Filter by Threat Name**: select a threat name from the drop-down list, or type a threat name into the text field. This field supports autocompletion, and suggests only those threat names that can be found in the table. To reset the filter, select “–” from the drop-down list. - **Type**: from the drop-down list, select **Domain**, **Link** or **IP** to show URIs recognized as domains, links or IPv4 or IPv6 addresses. Click **All** to reset the filter to show all URIs. - **Origin**: from the drop-down list, select whether to see URIs extracted as a result of static analysis, dynamic analysis, and/or those that have been extracted from malware configuration files. All three origin sources are enabled by default. - **Export**: export the entire table as a CSV file. To export a single page, select it by clicking the checkbox on the far left, and then click *Export*. Selecting and exporting individual table rows is currently not supported. The table data is organized into the following columns: - **Checkbox**: click to select a single page when exporting data. Selecting and exporting individual table rows is currently not supported. - **Risk Score**: all URIs are assigned a [risk score](/General/AnalysisAndClassification/Classification/#risk-score) that corresponds to the severity value of the most prevalent threat name detected in samples containing the extracted URI. - **Last Seen**: indicates when the appliance last recorded the sample(s) containing the URI. - **Threat Name/Threat Count**: if any threats are found within samples containing a specific URI, this column lists the most prevalent threat name, and the number of samples containing both the URI and the detected threat. Click the threat name in this column to perform an [Advanced Search](./advanced-search.md) query. - **Total Count**: shows the number of samples containing the URI. Click the URI in the *Pivoting Information* column to perform an [Advanced Search](./advanced-search.md) query. - **Type**: categorizes the URI as *Domain*, *Link*, or *IP*. URIs recognized as links have a **Download** button next to them, allowing the user to download and submit the URI for analysis. If the URI points to a web page, the appliance crawls its contents and downloads the web page as a compressed file. The page is crawled one level deep, regardless of the domain. URIs pointing to files are treated as single file downloads/submissions. All downloaded URIs can be found on the [Advanced Search](./advanced-search.md) page. - **Pivoting Information**: contains all or specific URIs extracted from files on the appliance, depending on the option selected in the *Type* filter. To see a list of samples containing a specific URI, click the links. URI-related tags are displayed below each of the entries. Click any of the tags to perform an [Advanced Search](./advanced-search.md) query to find all files tagged with the same System Tag in the time range selected on the dashboard. - **Origin**: indicates the source from which the appliance extracted each URI. Supported sources are static analysis results, dynamic analysis results, and malware configuration files. --- ## File and URL Submissions ## Submitting files for analysis Files can be submitted to the appliance: - [manually](#manual-uploads) through the graphical user interface: - as a direct file upload - as a link to the file which the appliance then downloads - using the [Submissions API](API%20Documentation/submissions.md) - using [Connectors](/SpectraAnalyze/Administration/integrations-connectors/connectors/), which pull files from one or more configured sources - by pivoting from a previously analyzed sample: - from the [Spectra Detect Manager dashboard](/SpectraDetect/Usage/Dashboard/#product-integration-with-spectra-analyze) - from an S3 file link in a [Spectra Detect Worker report](/SpectraDetect/Usage/Analysis) - using the [ReversingLabs browser extension](https://chromewebstore.google.com/detail/reversinglabs-browser-ext/hdnaiimefhaiglkbjdcioegcoofbnomm). **Tip: The ReversingLabs browser extension is available on [Chromium-based browsers](https://chromewebstore.google.com/detail/reversinglabs-browser-ext/hdnaiimefhaiglkbjdcioegcoofbnomm). It enables you to query domains, URLs, IP addresses, and hashes from web pages and submit files for analysis. For more information, see [ReversingLabs browser extension documentation](https://docs.reversinglabs.com/Integrations/category/browser-extension/).** ### Manual uploads ![An image showing the file submission dialog](images/analyze-uploads-add.png) To submit files programmatically as part of an automated workflow, see the [Submissions API](./API%20Documentation/submissions.md). To submit files manually from the Spectra Analyze UI, do the following: 1. In the header bar, click **Submit**, and then select **File Analysis**. 2. In the **File Analysis** dialog, click **Browse Files** to upload files from your local system, or enter a direct **File URL**. 3. Optionally, to customize the submission, click [Advanced Analysis Options](#advanced-analysis-options) and choose specific analysis services. 4. Finally, click **Submit** to process the files using the current appliance configuration. A progress bar in the header indicates the upload status while files are uploading. **Warning: Navigating away from the page or refreshing the browser tab during upload is not supported and will cancel the upload.** #### Advanced analysis options Uploaded samples are analyzed based on your current appliance settings, but you can make a one-time adjustment for each upload, such as sending the file to Threat Intelligence (Spectra Intelligence) for threat reputation info, or using one of the sandbox integrations. The following options are available: - **Local Analysis**: all uploaded files are processed with static analysis by the Spectra Core engine. This analysis is always performed and cannot be disabled. - **Local Only Analysis**: if selected, the file is analyzed exclusively on the appliance and is not sent to any configured integrations, sandboxes, or Spectra Intelligence services. - **RL Analysis**: ReversingLabs analysis services. The following options are available if configured on the appliance: - **Threat Intelligence**: submits the file to Spectra Intelligence for threat reputation analysis. Enabled by default. Automatically selected when Cloud Sandbox or Interactive Analysis is enabled. - **Cloud Sandbox**: submits the file to [ReversingLabs Cloud Sandbox](./Analysis-services/cloud-sandbox.md) for dynamic analysis. When selected, the following additional options appear: - **Platform**: target operating system for execution, for example *Windows 11*. - **Locale**: language and regional setting, for example *en-US*. - **Geolocation**: simulated geographic location, for example *United States*. - **Execution Timeout**: duration of the sandbox session, between `30` and `500` seconds; default: `200`. - **File Name**: custom filename for the submitted sample. If not provided, the *Smart Sample Naming* algorithm is used. - **Internet Simulation**: run dynamic analysis using a simulated network environment. - **Interactive Analysis**: submits the file for [interactive analysis](./Analysis-services/cloud-sandbox.md#interactive-analysis) in a browser-based sandbox session with manual control over execution. When selected, the following additional options appear: - **Platform**: target operating system for execution, for example *Windows 11*. - **Locale**: language and regional setting, for example *en-US*. - **Geolocation**: simulated geographic location, for example *United States*. - **Execution Timeout**: duration of the sandbox session, between `30` and `500` seconds; default: `200`. - **File Name**: custom filename for the submitted sample. If not provided, the *Smart Sample Naming* algorithm is used. - **Auxiliary Analysis**: submits the file for [auxiliary analysis](./Analysis-services/auxiliary-analysis.md). - **Integration Analysis**: third-party dynamic analysis sandbox integrations. The available integrations depend on the appliance configuration. For more information, see [Third-party integrations](./Analysis-services/other-integrations.md). - **Protected File**: if submitting a password-protected archive, provide the file password here. The archive and password are discarded after unpacking. **Note: This feature expects the ZIP file to contain **only one file** and, upon successful extraction, uploads only the extracted file and discards the archive. Only CRC32 encrypted ZIP files are supported. AES encryption is not supported at this time.** This specific unpacking mechanism is triggered by providing a password. For general password-protected archive usage uploads, where multiple files can be extracted and processed, perform a regular upload with a preconfigured **Password list** set up under [Administration > Configuration > General](./Administration/configuration-update/configuration.md#general). - **Sources**: both values are displayed on the [Sample Details > Sources > Uploads](./Sample%20Details/sources.md) tab. - **Source Tag**: user-defined origin identifier for the upload. Uploads can be searched using the `upload-source-tag` keyword or `upload-data` group keyword. - **Origin Link**: an external link to the original location (URL) from which the file was obtained. ### File processing When a file is submitted to the appliance, it is [processed with Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis). Depending on the appliance configuration, samples with supported file types can be automatically sent to dynamic analysis services after they are submitted to the appliance. The file becomes visible on the [Search & Submissions > Local](./search-page.md#local-files-view) tab. Detailed analysis results can be viewed in the [Expanded Details](./search-page.md#expanded-details) section, or on the file's [Sample Details](./Sample%20Details/index.md) page. The duration of the analysis depends on file sizes and file types, as well as the number of files extracted during analysis. Extracted files are also analyzed separately. After initial processing by Spectra Core, users can optionally [submit it to Spectra Intelligence and/or supported dynamic analysis services](./search-page.md#reanalyzing-files-and-urls), if configured on the appliance. Spectra Intelligence scanners that support archive unpacking and heuristic analysis automatically perform those steps during processing. **Note: For [CAPE](./Analysis-services/other-integrations.md#cape-sandbox) and [Joe Sandbox](./Analysis-services/other-integrations.md#joe-sandbox), previously analyzed files are not automatically sent for analysis again if the **Submit only distinct files** option is configured. Administrators can configure this on the [Administration > Integrations](./Administration/integrations-connectors/integrations.md) page.** ### File size restrictions - The maximum supported file size for upload on Spectra Analyze is 10 GB. This value can be configured in [Administration > Configuration > General > File Size Limit](./Administration/configuration-update/configuration.md#general). - Files larger than 400 MB cannot be submitted for dynamic analysis (individual dynamic analysis integrations have even lower limits). - YARA rulesets are not applied to extracted files larger than 700 MB. New files cannot be submitted to Spectra Analyze if the disk space usage on the appliance exceeds the set value. If this happens: - [manually remove old samples](./search-page.md#deleting-submitted-files-and-urls) - ask the administrator to run the [Backup and Purge](/SpectraAnalyze/Administration/configuration-update/backup-purge/) action before continuing to submit new files - increase the disk size under [Administration > Configuration > Resource Usage Limits](./Administration/configuration-update/configuration.md#resource-usage-limits). ### Pivoting from Spectra Detect If Spectra Analyze is connected to Spectra Detect, either to individual Workers or a cluster managed by Spectra Detect Manager, it can pull files from a preconfigured S3 bucket or directly from Spectra Detect Manager. Both of these options must first be [configured](/SpectraDetect/Usage/Dashboard#product-integration-with-spectra-analyze) on Spectra Detect. The pivot link is present in the dashboard of Spectra Detect Manager, as well as in the Worker JSON report under `file_link`. When you open the link, Spectra Analyze pulls the previously analyzed file from the preconfigured source and reanalyzes it. Imported files are [tagged](./system-and-user-tags.md) with the `spectra_detect` tag. ## Submitting URLs for analysis The URL analysis service provides comprehensive analysis of submitted URLs through advanced web intelligence gathering and threat detection capabilities. The service performs DOM analysis to detect malicious content, captures visual evidence, maps network infrastructure, like IP addresses, DNS, SSL/TLS certificates or domain registration, and executes URLs in sandbox environments to observe runtime behavior and track redirection chains. To submit URLs programmatically as part of an automated workflow, see the [Submissions API](./API%20Documentation/submissions.md). To submit URLs manually from the Spectra Analyze UI, do the following: 1. In the header bar, click **Submit**, and then select **URL Analysis**. 2. In the **URL Analysis** dialog, enter the full URL of a website including the protocol (*https://www.example.org*), or a full link to a single file (*http://www.example.org/documents/reports/year-report.pdf*). Supported protocols are HTTP and HTTPS. **Important: Crawl depth** Files are downloaded only from the submitted URL with no recursion (crawl depth = 1). For example, if you submit `http://www.example.com/freshcontent`, only that specific URL is analyzed, and `http://www.example.com/freshcontent/newest` is not. 3. Optionally, click **Advanced Analysis Options** to configure dynamic analysis and URL crawling settings: - **Dynamic Analysis**: execute the sample in a secure virtual environment to observe runtime behavior, complementing static analysis by capturing dropped files, network activity (PCAP), memory strings, and screenshots. Available services: - **Cloud Sandbox**: same options as [file submission Cloud Sandbox](#advanced-analysis-options). - **Interactive Analysis**: same options as [file submission Interactive Analysis](#advanced-analysis-options). - **Joe Sandbox**: for more information, see [Joe Sandbox](./Analysis-services/other-integrations.md#joe-sandbox). - **URL Crawling**: download and analyze files from the submitted URL. For more information, see [Crawling methods](#crawling-methods). - **Analyze Crawled Files (Cloud)**: uses Spectra Intelligence to crawl the URL. - **Analyze Crawled Files (Local, On-Device)**: crawls the URL directly from the appliance. The machine accesses the remote site through your network. 4. Click **Submit** to confirm the submission, or **Cancel** to close the dialog. The submission cannot be confirmed if the URL is invalid. The service downloads and analyzes up to 50 samples, each up to 100 MB, per analysis, with files processed through the ReversingLabs threat detection pipeline. ### Crawling methods Under **Advanced Analysis Options**, users can optionally enable **URL Crawling** to download and analyze files from a submitted URL. Crawling options are managed by the administrator and can be configured under [Administration > Configuration > URL Analysis](./Administration/configuration-update/configuration.md#url-analysis). Crawling is done in the following ways: - **Cloud**: by default, URLs are crawled using the **Spectra Intelligence** crawling method, which requires Spectra Intelligence to be configured on the appliance. When using the Spectra Intelligence crawling method, users have the additional option of submitting the URL for automated dynamic analysis to the [ReversingLabs Cloud Sandbox](./Analysis-services/cloud-sandbox.md), for [Interactive analysis](./Analysis-services/cloud-sandbox.md#interactive-analysis), which provides manual control over the browser session during execution, or for third-party analysis if any are configured. - **Local, On-Device**: if enabled by the appliance administrator, users can also select the **Local** crawling method. This method doesn't require Spectra Intelligence to be configured, and disables all Spectra Intelligence features, such as dynamic and interactive analysis. **Important: Privacy** For more information on these methods, refer to the [Privacy of submitted files and URLs](#privacy-of-submitted-files-and-urls) chapter. ### URL analysis results The [Search & Submissions](./search-page.md) page displays comprehensive analysis results for the submitted URL, including all downloaded files, network intelligence data, visual evidence, and behavioral analysis findings. If any of the analyzed components are malicious or suspicious, the overall verdict for the URL reflects the highest threat level detected. The submission type indicator icon on the left side of the page helps distinguish between files downloaded to the appliance via a URL (the link icon) and files directly submitted to the appliance (the folder icon). ### Analyzing data from submitted URLs The analysis duration depends on multiple factors including the number of files downloaded (up to 50), their sizes and file types, DOM complexity, network infrastructure resolution, and dynamic execution requirements. Each downloaded file is also analyzed separately through the complete threat detection pipeline. The timeout for URL submissions is 45 minutes. URL submissions undergo comprehensive analysis including static file analysis with the Spectra Core engine, network infrastructure mapping, DOM analysis, and visual documentation. Users can manually send components for additional analysis to Spectra Intelligence and/or configured dynamic analysis services using the [Reanalyze option](./search-page.md#reanalyzing-files-and-urls). This integration with Spectra Intelligence and dynamic analysis services must be configured by appliance administrators. All files and websites downloaded to the appliance via the URL submission dialog are automatically assigned the *URL Download* [user tag](./system-and-user-tags.md). This tag is visible in the [Expanded Details](./search-page.md#expanded-details) and on the [Sample Details](./Sample%20Details/index.md) page for every file and website. Clicking the tag opens the **Tags** page filtered to display all files with the *URL Download* tag. Users can then sort the files and perform bulk actions, such as [reanalyzing](./search-page.md#reanalyzing-files-and-urls) them or adding them to [alert subscriptions](./alerts.md). ### URL submission restrictions The URL analysis service has the following limitations: - **File limits**: up to 50 files can be downloaded and analyzed per URL submission, with each individual file limited to 100 MB. - **Total data limit**: the maximum allowed size of all data downloaded from submitted URLs can be configured by the appliance administrator. By default, it is limited to 200 MB. This value is configurable by appliance administrators under [Administration > Configuration > URL Analysis](./Administration/configuration-update/configuration.md#url-analysis). The maximum configurable value is 700 MB. - **Crawl depth**: analysis is limited to the submitted URL only (crawl depth = 1) with no recursive crawling of linked pages. In addition to these limits, submitting a URL using the Spectra Intelligence crawling method also compares individual components of the submitted URL to the **Maximum Fetch File Size** value under [Administration > Configuration > Spectra Intelligence](./Administration/configuration-update/configuration.md#spectra-intelligence). Any files going over this limit are skipped. The maximum configurable value is 2000 MiB. If the download request fails, the URL submission is marked as failed. Users can attempt to reanalyze the submission by selecting **Reanalyze** in the **Actions** menu (**☰**). This option is available for individual submissions only, and not for multiple submissions at once. ## Privacy of submitted files and URLs **Note: For more information and best practices, see [**Privacy & Data Sharing**](/General/SecurityAndAccessControl/Privacy/).** ### File submissions All files submitted to the appliance are accessible to all users with accounts on that Spectra Analyze instance. While each submission is associated with the particular user who submitted the file or URL, actual files on the local appliance system are not owned by any of the users in the traditional sense of file ownership. Therefore, all users on the Spectra Analyze instance can download, reanalyze, subscribe/unsubscribe, add tags, and manually change classification for any file uploaded by another user. ### URL submissions When submitting URLs for analysis, be aware of the following privacy implications: - URL analysis can only access and analyze publicly reachable online resources. - All submitted URLs and downloaded files are treated as public and accessible to all Spectra Intelligence users. - URLs are automatically normalized during submission, which may remove or convert duplicate and empty elements. #### Crawling methods Depending on which crawling method is selected, files obtained from the submitted URLs are treated differently. - The **Cloud/Spectra Intelligence** crawling method (default) is more reliable when working in restricted network conditions, and ensures fewer failed URL analyses. However, all downloaded files are treated as public, and are visible and accessible to all Spectra Intelligence users. **The prerequisite for this is a properly configured Spectra Intelligence account on the appliance.** - The **Local/On-Device** crawling method treats the URL as any other locally submitted file. The contents of the URL are crawled and downloaded directly. This method can be used without a Spectra Intelligence account and must be enabled by the appliance administrator. If Spectra Intelligence is configured and is using a proxy, the same proxy is used to crawl the URLs when using this method. Appliance administrators can delete files submitted by other users. Regular users can only delete their own submissions. ### Spectra Intelligence If the appliance is connected to Spectra Intelligence, all submissions can be: - Manually uploaded to be analyzed with AV engines. This is done with the [Reanalyze option](./search-page.md#reanalyzing-files-and-urls). - Automatically uploaded if enabled under [Administration > Configuration > Spectra Intelligence > Automatic Upload to Spectra Intelligence](./Administration/configuration-update/configuration.md#spectra-intelligence). This is disabled by default. Whether submitted files are shared with other ReversingLabs customers depends on the role configured for the Spectra Intelligence account used by the appliance. **Spectra Intelligence accounts created to be used with Spectra Analyze appliances are always configured as private and non-shareable**, meaning that other ReversingLabs customers may only be able to access analysis results for the files, but not retrieve their contents. However, if those same files are uploaded to Spectra Intelligence as shareable from another source, they cease to be treated as private. In that case, other ReversingLabs customers may be able to download the files, their metadata, and their analysis results through other ReversingLabs solutions such as APIs and Feeds. If Spectra Intelligence is not configured on Spectra Analyze, files are only preserved on the local appliance system and accessible only to users on that instance. ### ReversingLabs Cloud Sandbox Whether submitted files, PCAP files, dropped files, and memory string dumps are shared with other ReversingLabs customers depends on the role configured for the Spectra Intelligence account used to upload files. If the account is configured to upload all files as not shareable (private), other ReversingLabs customers are only able to access analysis results, but not retrieve the actual contents of uploaded files, dropped files, PCAP files or memory string dumps. **This is the default setting for Spectra Intelligence accounts created to be used on Spectra Analyze appliances.** If the account is configured to upload all files as shareable (not private), other ReversingLabs customers are able to access analysis results, but also download the uploaded files, dropped files, PCAP files, and memory string dumps generated during file execution. --- ## Search & Submissions Page The Search & Submissions page is accessible from the top navigation menu. ![The search page focused on the network tab, showing a list of network resources submitted to the appliance.](images/analyze-search-network.png) At the top of the page is the [Advanced Search Box](#advanced-search-box). It is functionally identical to the one embedded in the global header bar on the other pages. Below the search box is the list of [recent submissions](#results-list) in the **Files** tab. The Files tab contains both local submissions and Spectra Intelligence results, which can be filtered using the Local/Cloud filter options. The **Network** tab lists URL, Domain and IP submissions. The appliance also crawls and downloads the submitted URLs to analyze them as files in the Files tab, so this makes it easier to distinguish between the downloaded content in the Files tab and the reputation of the network location itself. ## Advanced Search Box The *Advanced Search* box is a text field where users enter [search queries](./advanced-search.md#how-to-write-search-queries) and get a pull-down list of all [supported keywords](./advanced-search.md#supported-search-keywords). To quickly position the cursor into the search box, press ALT+S. This also applies to the search box present on the other pages of the Spectra Analyze interface. Alternatively, use the [Quick Search](#quick-search) dialog to construct a query, or the filters below the search box to add more search criteria. Read more about the filtering features in the [Filtering Results](#filtering-results) section. The maximum length of a single search query that can be entered into the *Advanced search* box is 1024 characters. For keywords that support searching by date, a date picker will open instead of the pull-down list. The *Advanced search* also has the following buttons: - the **preferences** button opens the [Quick Search](#quick-search): dialog where users can construct search queries using a graphical interface, perform [bulk searches](#bulk-search), and browse through suggested, recent and favorited search queries. - the **suggestions** button opens the Quick Search screen straight to the [Show Suggestions](#show-suggestions) tab. - the **share button** opens the dialog for sending the current query to other users via email. Available only when the users types into the *Advanced search* box. - the **star button** adds the current query and filter configuration to the list of Favorites displayed in the [Suggestions](#show-suggestions) tab of the [Quick Search](#quick-search) dialog. If the current page state is already saved as a favorite, the star will be yellow and open the “Edit favorite query” on click. Favorite queries can also be used as [a default filter](#changing-the-default-search-page-behavior) for the Search page. - the **Search** button (magnifying glass) runs the search query. Once the query is running, an option to stop it appears next to the **Files** and **Network** tabs below the search box. ### Quick Search The Quick Search dialog can be opened by clicking the Preferences button inside the Advanced Search box, or by pressing the ALT+Q keyboard shortcut. It contains multiple tabs. ![An image of the Quick Search dialog, currently showing the Files tab.](images/analyze-quick-search.png) #### Files The Files tab can be used to construct search queries without having to type them out manually. Users can fill out the form by entering values and picking options from drop-down menus, and then click the Search button in the bottom right of the dialog. #### Network The Network tab offers URL/Domain/IP search capabilities. Query can be filtered by classification, first seen date and resource type. #### Bulk Search The Bulk Search tab allows users to input up to 10 000 SHA1, SHA256, or MD5 hashes and search for them all at once. The results will be sorted into the Local and Cloud sections, depending on their availability. The list of hashes can be uploaded as a file or typed into the text field. In both cases, hashes should be separated by commas, spaces, or newlines. Mixing hash types is allowed, so all supported types of hashes can be submitted in one search request. The following examples illustrate different ways to separate hashes: ``` hash1,hash2,hash3,hash4 (...) hash1000,hash1001 ``` ``` hash1 hash2 hash3 hash4 (...) hash1000 hash1001 ``` ``` hash1 hash2 hash3 ``` To perform a bulk hash search, click the *Search* button in the dialog. Clicking *Cancel* closes the dialog. **Note: Bulk hash search differs from regular Advanced Search in several ways.**** - Bulk hash queries cannot be bookmarked in the browser or saved as favorites on the Spectra Analyze appliance. - Bulk hash queries do not appear in the *Recent queries* list. - Pivoting and combining search keywords with bulk hash queries is not possible. - Bulk hash search can take up to one minute, depending on the number of requested hashes. - Due to the way samples are processed in the Spectra Intelligence cloud, some discrepancy can arise between sample metadata in bulk search results versus regular search results. - By default, bulk hash search results are sorted by *First Seen* in descending order (most recent to oldest). This cannot be changed; the results page for bulk hash search does not support custom sorting by columns. - Different types of hashes can be submitted in one bulk hash query, but subscribing is only supported for SHA1 hashes. If multiple different hash types are selected in the list of search results, and the user attempts to subscribe to them, only the SHA1 hashes will be added to the subscription. Other hash types will be automatically filtered out from the subscription. **Tip: Instead of using the Bulk hash search dialog to look up large numbers of different hash types, the **hashes** keyword can be used for a similar purpose. The **hashes** keyword allows mixing different types of hashes in one search query, without the need to explicitly name the hash type or to group hashes by type. All hash types (MD5, SHA1, SHA256) can be used with this keyword.** An example query: `hashes: [, , , , , ]` When the **hashes** keyword is used (or when a query contains only hashes), the search automatically switches to Bulk Search, bypassing the 1024-character limit of standard queries. ### Show Suggestions Clicking the `Suggestions` button to the right of the search box will open the Quick Search pop-up window directly to the Suggestions tab, containing trending, recent and favorite advanced search queries. The tab is divided into three sections, from left to right: - **Interesting search examples** - predefined search queries that users can run to get a better understanding of the data in the results. - **Recent queries** - a list of up to 20 latest search queries performed on the Spectra Analyze instance. Clicking on any of the queries in the list automatically runs that query again, and moves it to the top of the list. Recent queries are deduplicated, so consecutively running the same query does not cause duplicate entries in the list. All recent queries from this list are also displayed in the pull-down keyword list when the user starts typing into the search box. The list of recent queries is private and visible only to the Spectra Analyze user who performed them, not to all Spectra Analyze users. - **Favorites** - a list of up to 20 user-defined favorite search queries. Users can save any query as a favorite by clicking the star button in the search box when the query is active. When a query is added to the Favorites list, clicking it automatically runs that query. Hovering over a favorite in the list displays a triple-dot menu with options to edit the query (change its name, search keywords, parameters…), copy it to clipboard, remove it from the Favorites list, or share it via email. The list of favorites is private and visible only to the Spectra Analyze user who created it; in other words, every user has their own Favorites list. Favorite queries can also be used as [a default filter](#changing-the-default-search-page-behavior) for the Search page. To start using Advanced Search, click any of the predefined search examples, or start typing into the *Advanced search* box to [create a custom search query](./advanced-search.md#how-to-write-search-queries). ### Keyword Auto-Suggestion Pull-Down List As soon as the user starts typing into the search box, the auto-suggestion pull-down list matching either the [supported search keywords](./advanced-search.md#supported-search-keywords) or their predefined values will open. User queries will be matched against keywords and their predefined values starting from any position, and not only from the beginning. For example, entering `aliciou` as a search query will match and return the entire `classification:malicious` keyword and value pair. Click the *…more* link to expand the list of keywords. Every keyword has a short explanation with examples on the right side of the list. Some keywords offer predefined values that the user can select from the pull-down list. The pull-down list also displays 20 most recent search queries performed on the Spectra Analyze appliance. Recent queries are offered as auto-suggestions when the user starts typing into the search box (if they match some of the text the user has typed). ### Date and time picker When a keyword that supports searching by date and time is typed into the search box, the date picker menu opens instead of the usual pull-down list. The user can select any of the predefined date and time values, or click “Custom” to enter their own date and time range. ![Date picker pull-down with predefined time ranges](images/analyze-search-date.png) ### Query Builder [PREVIEW] Query Builder is an alternative way of constructing and writing search queries. When activated in the gear menu on the Search Page, queries are represented as tags or blocks, allowing for better context awareness and auto-completion when adding new items in the middle of the query. Hovering the mouse between any two blocks displays a “+” button which can be used to insert an additional item anywhere in the query. Clicking the “X” button on a specific block deletes it. While the search box is focused, tags can be navigated using the arrow keys on the keyboard, and deleted using Backspace or Delete. ## Threat Intelligence Cards Threat Intelligence Cards make use of extensive ReversingLabs file metadata to provide an informative, educational overview and analytics on malware types and families in an easily accessible format on the Search page. The prerequisite for this feature is a properly configured Spectra Intelligence account on the appliance. When users perform an exact search with the `threatname` keyword for a single threat name or a list of threat names, one or more collapsible sections become available above the list of search results. At most 10 cards will be displayed, even if more threat names were provided in the query. ![A threat intelligence card displaying information about the Emotet malware family.](images/analyze-threat-intelligence-card.png) Depending on available data, Threat Intelligence Cards will either show information about a specific malware family (for example, Emotet), or a more generalized description of the family type (trojan). Cards can contain all, or a subset, of the following information: - first and last seen dates - current latest version - packer - targeted OS - targeted industries - threat name - threat name alias - actor aliases - malware family/type description - reference links - malware prevalence graph - top file types used by this malware family - weekly rankings for the current and the previous week - overall total number of unique samples containing this threat. To better reflect the popularity of the malware family in the Spectra Intelligence cloud, the **Current week** and **Last week** columns count all sample uploads and increase on repeated uploads of the same sample. The **Total number of detected samples** column shows a deduplicated count of unique samples belonging to that malware family. The malware family/type descriptions displayed here are also visible on the Sample Details > Summary page in the Malware Description section. ## Results List **Note: The terms “samples”, “files”, “submissions”, and “search results” are often used interchangeably in the appliance interface and in this documentation.** The list of files and URLs submitted to the Spectra Analyze can be found on the Search page, below the [Search box](#advanced-search-box). Drop-down menus under the Search box allow [filtering](#filtering-results) of the results list by multiple criteria. The results section of the page is divided into these general sections: 1. The action bar with the filter tabs. The action bar allows filtering the results by location (local or cloud) and availability (public or private); exporting them; configuring how the dates will be displayed in the results grid and if optional columns will be displayed. 2. Filter tabs: - **Files** - **Local** - filters the search results to display only the samples found on the local Spectra Analyze instance. The tab also shows the number of results. - **Cloud** - applies only to Spectra Intelligence search results. The maximum amount of Cloud results that can be returned for a search query is 100 000. Although the number may indicate there are more samples in the Spectra Intelligence cloud, Spectra Analyze will only allow browsing through 100 000 of them. - **Network** - lists URL, Domain and IP submissions. The appliance also crawls and downloads the submitted URLs to analyze them as files in the Local tab, so this makes it easier to distinguish between the downloaded content in the Local tab and the reputation of the network location itself. 3. Bulk Hash search only tabs: - **Not found** - displayed only when the list of results contains hashes that were not found in the ReversingLabs system. For Local results, *Not found* refers to hashes not found on the current Spectra Analyze instance. For Cloud results, *Not found* refers to hashes not found in the Spectra Intelligence cloud. - **Invalid** - displayed only when the list of results contains incomplete or erroneous hashes. It helps users identify potential formatting mistakes in their lists of hashes. 4. The samples/results list 5. The navigation bar at the bottom The samples/results list contains basic information about submitted files and URLs, or matching local/Spectra Intelligence search results after performing a search. Local results are sorted by *Last Submitted* by default, even if that column is disabled in the gear icon menu in the top right of the submissions grid. Spectra Intelligence results are sorted by *First Seen* date. Selecting the main checkbox in the topmost row will select all submissions on the current page. When submissions are selected, their highlight color changes to yellow. **Note: To improve search query responsiveness and performance, Cloud results prioritize *First Seen* within the last month by default. In case there are no results, the results page automatically extends the search query backward up to one year, until there are results. If still no results are found, users can choose to expand the search further by clicking the `Extend Search Timeframe` option. This progressively expands the search, year by year, until first results are found.** The list consists of the following columns: **Selection checkbox** - for selecting individual submissions on the page to perform bulk actions on them. When one or more items are selected on the page, an additional actions menu (☰) with bulk actions becomes active to the right of the *Size* column. **Submission type indicator** - the icon indicating whether the submission is a file or a URL. **Classification indicator** - classification status of submitted files and URLs is indicated by colored symbols: red square is malicious, orange rhombus is suspicious, green circle is goodware, black square with a circle cutout is no threats found. Inside of each of these symbols is the sample’s [risk score](/General/AnalysisAndClassification/Classification/#risk-score). Samples with no threats found (samples without classification) don’t have a risk score. Samples with a risk score of 5 are represented using a unique icon, as the indicators found during analysis were deemed insufficient to convict the file as definitively malicious or benign. These samples may be of interest, as they have a higher chance of changing classification and/or risk factor as soon as any new information becomes available. **First Seen** - time when a sample was first received by Spectra Intelligence (for Cloud results) or uploaded and analyzed on the appliance (for Local results). Open the gear icon menu next to the *Export* button on the far right of the page to change how the dates are displayed in this column (exact or relative dates). **Threat** - detected threat name for a submission, formatted according to the [Malware naming standard](/General/AnalysisAndClassification/Classification/#malware-naming-standard). Threat names are displayed only for malicious and suspicious samples. If the threat name is not detected for a suspicious submission, it receives a generic “Suspicious” threat name label. Clicking the name performs an Advanced Search for samples with the same threat name. **Name** - file name of the submission (as uploaded). For URLs, the file name corresponds to the URL submitted by the user. If the file name doesn’t contain any of the standard characters ([A-Z, a-z, 0-9]); for example, if the file name is !!!, its SHA1 hash is displayed instead to make it easier to click. Clicking the name opens the [Sample Details](./Sample%20Details/index.md) page with more information about the submission. Predicted filenames are displayed under the original filenames. They are generated by [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis), and can be helpful for distinguishing files that only have a hash value as their filename. Clicking a predicted filename redirects to the Advanced Search page and performs a search query to find other samples with the same predicted filename. The predicted filename won’t be shown if it’s a hash value. **Last Submitted** - indicates when the submission was last submitted to the appliance. Open the gear icon menu next to the *Export* button on the far right of the page to change how the dates are displayed in this column (exact or relative dates). The **Last Submitted** column can also be enabled/disabled from this menu. **Username** - indicates which Spectra Analyze user submitted each file or URL. This column can be enabled/disabled by clicking the gear icon next to the Export button. **Format** - file format of the submission, either represented as a combination of file type and subtype (e.g., PE/EXE) or as an identified format (e.g., NSIS, PDF). URLs submissions not pointing to a single file are represented as ZIP files in this column. **Files** - total count of files extracted from the submission, including the original uploaded file. **Size** - indicates the size of the submitted file, or of the contents downloaded from a submitted URL. If the file size is undefined for a Cloud result, the “Sample size currently unknown” message is displayed in the *Size* column on the Cloud results page. Those samples will be unavailable for download (the *Fetch & Analyze* option will be disabled) because it cannot be determined whether they exceed the maximum file size that can be downloaded from Spectra Intelligence (500 MB). ### Local Sample Actions **Actions menu** (☰) - contains various actions the users can perform on each submission. The actions include: - **Download sample** – downloads the submission from Spectra Analyze to local storage (compatible with modern ZIP tools such as `unzip` 6.00+, Python's `zipfile`, 7-Zip, or `bsdtar`). - **Download container** - if the file is a child (extracted from another file during analysis), downloads its top-most parent from Spectra Analyze to the local storage. - **Set classification** - opens a dialog where users can manually override the classification assigned to a submission. - **Subscribe** and **Unsubscribe** - adds or removes the sample from alert subscriptions. - **Reanalyze** - opens a floating dialog where users can reanalyze the submission with static, dynamic, or Spectra Intelligence analysis services. - **Report False Positive/Negative** - report an incorrect classification. Select either **False Positive** or **False Negative** as the report type, and optionally add a comment. The report automatically includes sample details, e.g. hash, classification, detection verdict. This option requires [SMTP](../Administration/configuration-update/configuration/#smtp) to be configured by an administrator. - **Delete sample** - removes the submission from Spectra Analyze. This action is visible to users only for files and URLs they have submitted themselves. Regular users cannot delete files and URLs submitted by other users. Administrators can see this menu item for all submissions, and delete all submissions regardless of who created them. - **Copy to my submissions** - displayed only if the sample was submitted by a different user. Selecting this adds the sample to the submissions for the current user. - **Similar by TLSH Hash** - pivots to a similarity search for samples with similar TLSH hash values. - **Similar by SSDEEP Hash** - pivots to a similarity search for samples with similar SSDEEP hash values. - **Download Extracted Files** - displayed if the sample has any extracted files. Selecting this downloads files extracted from the sample to local storage. **URL** submissions have a differently organized menu with mostly the same options. The menu is split into two sections: **Payload actions** which features the options above (as well as the option to open the [Sample Summary page](/SpectraAnalyze/Sample%20Details/sample-details-summary/#report-summary) for the payload), and **URL actions** with the option to reanalyze the URL. ### Expanded Details Each result row on the Search page can be expanded to see more details about a submission. Click anywhere in a row when the cursor changes to an up-down arrow. Expanded rows for local samples contain more information and different actions than those of samples available in the Spectra Intelligence cloud. This section describes local results. For more information on Public/Private Spectra Intelligence results, refer to the [Differences Between Local and Cloud Results chapter](#differences-between-local-and-public-cloud-results). ![Expanded row for a sample on the Search page](images/analyze-search-local-expanded-row.png) The information displayed here depends on the file type, and can include: - sample hashes - sample sources - first and last seen times (on the appliance and/or in the Spectra Intelligence cloud) - link to the parent file (if the file was extracted from another file) - RHA statistics (for supported file types) - User Tags and System Tags - comments for the sample (if any) - classification reason (see the [Threat Classification Descriptions](./Sample%20Details/threat-classification-sources.md#threat-classification-descriptions) section for more information about classification reasons) - number and percentage of Community Threat Detections - file format details - document metadata - email metadata - capabilities - indicators of interest - certificate information To add User Tags to a sample directly from the expanded details, click the **Add** link in the list of User Tags. Clicking the **Hex Preview** button opens the [Preview Sample / Visualization](./Sample%20Details/file-preview.md) pop-up modal. To see more information about a sample, click the file name to open the [Sample Details](./Sample%20Details/index.md) page. ## Filtering Results Users can filter samples by uploader (user accounts and connector services), as well as by a number of filtering criteria using the appropriate drop-down menus below the Search box. These filters vary depending on where the search query is being performed. When looking at **local** files, available filters are: time type and range, classification, submission user, processing status, and sample origin. Alternatively, instead of drop-down filters, use the following **local-only** search keywords: - `submission-user` - `submission-time` - `processing-status` - `tag-user` (not available as a menu selection) Being local-only, these keywords do not work on the **Cloud** tab. The classification filter uses the globally available `classification` keyword. The **Cloud** file list contains the time type and range filters, classification, and the cloud search dropdown, allowing the users to search for all cloud data, or just for private/public samples. **Note: Typing these keywords in a query will override and disable the respective drop-down menu under the search bar, to avoid filtering conflicts.** When added using the drop-down menus, the keywords will not be shown in the Advanced Search box as part of the query, but they will still be applied to the results, saved to the Recent queries list, and shared using the Share query button. In addition to these keywords, users can use any of the [supported keywords](./advanced-search.md#supported-search-keywords) to write [search queries](./advanced-search.md#how-to-write-search-queries) and search for samples available locally or in the Spectra Intelligence cloud. To reset the existing query and filters, click the **Clear** button next to the filters. The page also provides access to analysis reports ([Sample Details](./Sample%20Details/index.md)) and various actions that can be performed on each submission. ### Changing the default Search page behavior When the search page is opened, all of the configured filters on the page return to their default values. The gear icon next to the Export menu contains **Initial Search Results** options to change the default search page behavior: - **Use Default Filters**: If this option is selected, the search page will apply the default filters. - **Use Last Query**: If this option is selected, the search page will save the query and any filter configurations of the last performed query, and restore those values when the page is next opened. - **Use Favorite Query**: If this option is selected, users can choose a specific favorited search query from a dropdown list. This favorite will be used to configure the filters and populate the search box when the search page is next opened. - **Automatically Expand Search Period**: If this option is selected, the search period will expand until some results are found. This selection persists between sessions, and applies only to the current user. ## Exporting Results The **Export** menu contains options to export the whole page or just the selected samples. For the **Selected** samples option to become available, one or more samples on the page have to be selected. To export multiple pages of results, browse pages one by one and manually export them. It is possible to adjust the amount of results displayed per page in the navigation bar, thus increasing or decreasing the number of results that will appear in the exported file when exporting the entire page. Data can be exported as CSV, JSON or XML. To copy only the sample hashes for the desired set of samples, the menu contains options to copy SHA1, SHA256 and MD5 hashes to the clipboard. Hashes are delimited by a whitespace, so that they can be directly pasted into the search bar. The exported file can contain one or more of the following columns. They can be enabled in the **Export** menu, under **Show more Export options**. - **Files** - the number of files extracted from a sample (if the sample is a container). For Cloud results, this number is always 0, and they cannot be searched using the local-only **filecount** keyword. However, the Spectra Analyze interface displays `--` in the *Files* column for all Cloud results. For Local files, the correct file count is displayed, and extracted files can be browsed by clicking the file name and selecting the *Extracted Files* option on the Sample Details page. - **Format** - file format of each sample in the results grid. - **Name** - name under which a sample was uploaded to the appliance or to Spectra Intelligence. - **Threat** - detected threat name for malicious and suspicious samples, formatted according to ReversingLabs Malware Naming Standard. - **First seen** - time when a sample was first received by Spectra Intelligence (for Cloud results) or uploaded and analyzed on the appliance (for Local results). - **Size** - indicates the size of a sample. - **Available** - Spectra Intelligence results only. Indicates whether a sample can be downloaded from Spectra Intelligence. - **Classification** - indicates the classification status (malicious, suspicious, goodware, no threats found) assigned to a sample by any of the ReversingLabs classification sources and technologies. - **Last seen** - time when a sample was last received by Spectra Intelligence (for Cloud results) or uploaded and analyzed on the appliance (for Local results). - **Community Detections** - indicates the number of AV scanners that were used to analyze a sample in the Spectra Intelligence cloud. - **Risk Score** - the [numerical value assigned to a sample](/General/AnalysisAndClassification/Classification/#risk-score), representing its trustworthiness or malicious severity. - **SHA256, MD5** - additional sample hashes that can be included in the exported file. The SHA1 hash is always included by default. - **Last Submitted, Username** - available only for local results. If selected for Cloud results, the fields will be empty. ## Differences between Local and Public (Cloud) Results ### Spectra Intelligence Results List #### File format information In some cases, file format displayed on the Local files view can be different from the file format displayed on the Cloud files view for the same sample. Some samples will not have file format information at all. This happens when the information about a sample is returned from different sources. #### Extracted files information The number of extracted files for Cloud search results is always 0, but the Spectra Analyze interface displays `--` in the *Files* column for all Cloud results. #### Browsing and sorting Cloud results The maximum amount of Cloud results that can be returned for a search query is 100 000. Although there may be more samples matching the query in the Spectra Intelligence cloud, Spectra Analyze will only allow browsing through 100 000 of them. If the list of search results has more than 2000 samples, it is not possible to sort the results by any of the columns. ### Expanded Row Information Clicking a sample’s row in the list of results expands it to display more information about the sample. For Local results, this information includes the Spectra Core analysis report, and is generally more detailed. For Cloud results, the information in the expanded row includes sample classification received from Spectra Intelligence, sample hashes, first and last seen dates, and the results of AV scanning. Clicking the file name opens the Spectra Intelligence version of the [Sample Details](./Sample%20Details/index.md) page with more information about the sample. The **See All Scans** link leads directly to the Community Threat Detections page on the sample’s Summary page. ### Sample Availability The Local files view includes only those samples that are currently available on the local Spectra Analyze instance. The Cloud tab includes samples found in the Spectra Intelligence cloud. Select **Cloud Search** and pick *All Cloud Data* or further differentiate between public and private results. Private results may include files that have been deleted and are no longer available for download. Selecting **Public Cloud Data** shows data uploaded to Spectra Intelligence as shareable that may be available for download to the local Spectra Analyze instance. Alternatively, use the `available:true` keyword in the search query. Sample availability is indicated by a cloud icon on the left side of the results page. Samples with a black cloud icon are available for download; those with a grey icon are not. ### Spectra Intelligence Sample Actions The Cloud results page offers only the **Fetch and Analyze**, **Fetch and Analyze (Advanced)**, **Reanalyze in Spectra Intelligence** and **Subscribe/Unsubscribe** actions for each sample. **Fetch and Analyze**, **Fetch and Analyze (Advanced)**, and **Reanalyze in Spectra Intelligence** are available only for public and available samples (indicated by a black cloud icon). To learn how to subscribe to or unsubscribe from samples in the search results list, consult the [Alerts](./alerts.md) section. ### Bulk Actions for Managing Search Results Both Local and Cloud views allow users to select multiple samples at once and perform some actions on them. - **Local files view:** - Reanalyze - Download samples - Download Extracted Files - Apply User Tags - Set Classification - Delete - Subscribe - Unsubscribe - **Cloud files view:** - Fetch & Analyze (public results only) - Fetch & Analyze (Advanced) (public results only) - Subscribe - Unsubscribe To perform bulk actions, first select a number of samples to activate the bulk actions menu (☰). There are several ways to select multiple samples. 1. Manually select the checkbox on the left side of every sample. 2. Click the *Select all N samples* link that appears at the top when one or more samples are selected. This will select all samples on all pages in the results list. 3. Click the *Select All* checkbox in the top left corner of the results table. This will select all samples on the current page. Click the checkbox again to deselect all selected samples. When multiple samples are selected, a new bulk actions menu (☰) appears on the right side of the results page. Select the desired option in the menu. ![Bulk actions menu with option to download local samples highlighted](images/analyze-search-download-samples.png) ## Downloading Files from Spectra Analyze to Local Storage **Important: - Submissions selected for download are compressed and downloaded as a single ZIP file protected by a user-defined password.** - Currently, bulk downloads are limited to 15 000 files at once. The total combined size of all files selected for download should not exceed 4 GB. - If the appliance is unable to create the ZIP file within 20 minutes, the download process will time out. Files on the Spectra Analyze appliance can be downloaded to the local storage using the *Download sample* option from the actions menu (☰) for every submission (compatible with modern ZIP tools such as `unzip` 6.00+, Python's `zipfile`, 7-Zip, or `bsdtar`). Apart from downloading submissions one by one, users can also download multiple submissions at once (bulk download) to their local storage. This option is available from the **Local search results** on the **Advanced Search page\***, **YARA ruleset matches**, **Sample Details > File Similarity > Local** and from the **Submissions page**. There are several ways to select multiple items on the Search page: 1. Manually select the checkbox on the left side of every submission. 2. Select one or more submissions, then click the **Select all N samples** link that appears at the top of the page. This will select all submissions on all currently accessible pages. 3. Click the main checkbox in the topmost row of the submissions list. This will select all submissions on the current page. Click the checkbox again to deselect all selected submissions. When one or more items are selected, an additional actions menu (☰) appears highlighted on the right side of the page. Select the **Download samples** option in the menu. When the download process starts, a notification appears in the Spectra Analyze interface. The notification contains a link for canceling the download process. If the notification is dismissed (by clicking the X button), it will appear again when the page is refreshed, or when the user navigates to another part of the Spectra Analyze interface. When the download process is done, another notification appears even if previous notifications were dismissed. ## Downloading Container Files When a file is extracted from another file during analysis, the file from which it was extracted is referred to as its “container”. Extracted files have the **Download container** option in their action menu (☰) on the Search page. Selecting this option downloads the top-most container of the extracted file from Spectra Analyze to the local storage. If a file has been extracted from multiple different containers, the oldest one found on the appliance will be downloaded. Extracted files for which the top-most container has been removed from the appliance do not have this option in their action menu. The option to download the container is also available on the **YARA ruleset matches**, **Sample Details > Summary**, **Sample Details > Extracted Files**, **File Similarity > Local**, and on the **Local search results** page of the Advanced Search page. ## Downloading Files from Spectra Intelligence Apart from submitting files to the appliance manually or [through the API](./API%20Documentation/submissions.md), users can also obtain new files by downloading them from Spectra Intelligence. Downloaded files are stored on the appliance, and accessible from the **Local** files view on the Search page. The prerequisite is that the appliance is connected to Spectra Intelligence. In order to download a file from Spectra Intelligence, it has to be marked as available (in other words, uploaded to the cloud as shareable). The interface indicates this with a black cloud icon. Files with a gray cloud icon are marked as private, and are not available for download. Keep in mind that appliance administrators can configure the allowed file size for downloads from Spectra Intelligence. When this is configured, users can’t download files exceeding that file size. Regardless of the configuration, the maximum allowed file size is 500 MB per file. Files that are too large to be downloaded from Spectra Intelligence will have a special indicator icon instead of the black/gray cloud icon. Files can be downloaded from Spectra Intelligence to the Spectra Analyze appliance on the following pages: - Advanced Search results - Public tab - YARA > ruleset matches - Sample Details > File Similarity > Spectra Intelligence filter - Submissions > search results > Spectra Intelligence filter On each of the pages, files can be selected in several ways, depending on the page: 1. Manually select individual checkboxes on the left side of each file. 2. Select one or more files, then click the **Select all N samples** link that appears at the top of the page. This will select all files on all currently accessible pages. 3. Click the main checkbox (usually at the top left of the list). This will select all files on the current page. Click the checkbox again to deselect all selected files. When one or more files are selected, an additional actions menu (☰) appears highlighted on the right side of the page. Depending on the page, the following options may be available in the menu: - *Fetch selected samples* downloads the selected files from the current page to the Spectra Analyze appliance - *Subscribe* and *Unsubscribe* are used to [create an alert subscription for selected files](./alerts.md#monitoring-samples-with-alerts) Some pages on the Spectra Analyze appliance display the **Fetch All** button at the top right of the page when no files are selected. In those cases, clicking the button downloads all available files from the page to the appliance. It is also possible to choose an arbitrary amount of files by selecting individual checkboxes on the left side of each file. In this case, the **Fetch All** button changes to **Fetch Selected**. When downloading is confirmed, Spectra Analyze displays a notification about files being queued for download. Navigating away from the page will not stop the downloads. The process should only take a couple of seconds, after which the downloaded files will appear on the Search page. ## Managing Unknown (Not Found) Files **Note: “Unknown” in this context means “unknown to the system”, “not found in the system”. It does not refer to the *Unknown* status that files have when they are not classified yet.** Spectra Analyze can detect and track files that are currently not present on the appliance or in the Spectra Intelligence cloud. Users can look up hashes of specific files and set up alert subscriptions to get notified when the files become available in the cloud. **Search page** To track unknown files using the [Advanced Search](./advanced-search.md) feature, users should submit hashes through the *Bulk Hash Search* dialog. When one or more hashes are submitted through the *Bulk Hash Search* dialog, unknown hashes are automatically filtered out and displayed in a separate *Not found* tab on the search results page. When one or more **SHA1** hashes in the *Not found* list are selected, the actions menu (☰) provides options to subscribe or unsubscribe to them. Users can then create an alert description as described in the [Tracking Unknown Hashes with Alerts](./alerts.md#tracking-unknown-hashes-with-alerts) section. ## Deleting Submitted Files and URLs It is possible to manually delete files and URLs from the Search page. Users can delete only those submissions that they have added, while administrators (“superusers”) can delete any submission regardless of who added it to the appliance. There are several ways to delete a submission: 1. by selecting *Delete sample* in the actions menu (☰) on the Search page. This menu item is visible to users only for their own submissions. Administrators can see this menu item for all submissions. 2. by clicking a submission name to access its Sample Details page, then selecting *Delete sample* in the *ACTIONS* menu ![Sample Details Summary page with highlighted Actions menu](images/analyze-sample-details-actions.png) Multiple submissions can be deleted at once. To do this, select one or more items on the Search page using the checkboxes on the left side. Selected submissions are highlighted in yellow. To select all submissions at once, click the **Select all N uploads** message at the top of the list. Next, open the bulk actions menu (☰) highlighted on the right side of the list. Select *Delete* to remove selected submissions. A confirmation dialog appears, displaying the number of submissions to be deleted. Click **Yes** to proceed with deleting the submissions. Navigating away from the page will not stop the deletions. Clicking **No** or **Cancel** closes the confirmation dialog and returns to the Search page. ## Reanalyzing Files and URLs Users can perform additional analysis activities at any point after the files/URLs have initially been submitted and processed on the Spectra Analyze appliance. *Reanalyze* options are accessible on the following pages: - Advanced Search > Local, Cloud and Network tabs - the [Summary section](./Sample%20Details/sample-details-summary.md) of the Sample Details page - Extracted Files on the Sample Details page - The list of YARA matches (*local* and *local-retro* only) Depending on the currently focused search page tab and view, files/URLs can be submitted for reanalysis to the following supported services: ### Local Files View 1. Static Analysis - Spectra Core. Users can choose to reanalyze files with a newer version of the Spectra Core static analysis engine after updating the appliance. 2. Threat Intelligence - Spectra Intelligence. Users can submit a file to be reanalyzed with AV engines in the Spectra Intelligence cloud. 3. First-party analysis includes dynamic analysis with ReversingLabs Cloud Sandbox and static analysis through Auxiliary Analysis. Samples larger than 400 MB cannot be submitted to dynamic analysis services. When submitting a file to RL Cloud Sandbox, users have the option to launch an [interactive session](./Analysis-services/cloud-sandbox.md#interactive-analysis) and interact with the sample directly. 4. Third-party dynamic analysis using supported analysis services: Cuckoo, FireEye, Joe Sandbox, CAPE, Cisco Secure Malware Analytics or VMRay. Samples larger than 400 MB cannot be submitted to dynamic analysis services (100 MB for FireEye). ### Cloud Files View 1. Reanalyze on Spectra Intelligence - submit the sample to a new Spectra Intelligence analysis. Use **Fetch & Analyze** or **Fetch and Analyze (Advanced)** to make the sample available locally for more options. ### Network Tab Click the **Advanced Analysis Options** to reveal the following settings: #### Dynamic Analysis - Cloud Sandbox - submits the URL for automated dynamic analysis in ReversingLabs Cloud Sandbox - Interactive Analysis - allows real-time interaction with the URL in a controlled sandbox environment - Third-party integrations - submits the URL to configured third-party dynamic analysis services #### URL Crawling - Analyze Crawled Files (Local, On-Device) - this option crawls the URL and performs static analysis on the downloaded content. This makes the downloaded payload available as a file in the Files tab. **This setting is disabled by default. Check with your administrator to enable it.** - Analyze Crawled Files (Cloud) - the URL will be crawled using Spectra Intelligence. ### Bulk Actions On the **Files** tab, up to 100 files can be selected and reanalyzed at once. When the *Reanalyze* option is selected, a floating dialog opens, where users can select which services to use for reanalysis. ![Dialog with options for reanalyzing samples](images/analyze-reanalyze-menu.png) Multiple services can be selected in the dialog. If any of the selected files have last been analyzed with a Spectra Core version older than the current version on the Spectra Analyze appliance, the Spectra Core static analysis service is selected by default. For other services, the date of the last successful analysis is displayed under the service name. The ReversingLabs Cloud Sandbox dynamic analysis service allows the users to select the platform to which the sample will be submitted: Windows 7, Windows 10, macOS Big Sur, or Ubuntu 20 (Linux). If a service is unavailable or misconfigured on the appliance, this is indicated by a status label under the service name. If a file is already being processed by a service when submitted for reanalysis, that service will be disabled. After selecting the desired service(s), confirm by clicking **Reanalyze** to submit files for reanalysis. Integrations and assessment analysis services have additional limitations. Consult the [Analysis services](./Analysis-services/index.md) section for more details. **Important: Files without available sources cannot be reanalyzed using the *Reanalyze* option/dialog.** If file crawling is enabled, submitted URLs on the Files tab will behave exactly as files, so everything applies to URL submissions as well. To crawl a URL again, select the *Reanalyze* option in its action menu (☰). This will open the URL submission pop up window with the URL already inserted, allowing the users to select/change the crawling method. To see the URL network analysis results, switch to the *Network* tab. ## Reanalyzing Files and URLs in Error State In some cases, submissions on the Spectra Analyze appliance can remain in error state if there have been some issues during their previous analysis. Files in error state have a "Fail" indicator instead of the classification indicator on the Search page. Hovering over the indicator displays a tooltip with information about the last failed analysis. If the file name is crossed-out, that indicates the file doesn’t have a source on the appliance. Files without available sources cannot be submitted for reanalysis. To reanalyze a file or a URL submission in error state, select the *Retry Analysis* option in its actions menu (☰). This option is available for individual submissions only (not for multiple submissions at once). During reanalysis, users can normally browse pages on the Spectra Analyze appliance, including the Sample Details page of the submission that is being reanalyzed. Following a successful reanalysis, the submission will no longer display the *Fail* indicator, and will receive a classification from one of [the supported sources](./Sample%20Details/threat-classification-sources.md#threat-classification-descriptions). ## Analyzing Files with RHA Similarity Algorithm The [RHA (ReversingLabs Hashing Algorithm)](https://www.reversinglabs.com/technology/reversinglabs-hash-algorithm) is a functional similarity algorithm that classifies files based on the similarity of their features. Format-specific attributes of a file are abstracted into categories, and then evaluated for similarity at four different precision levels (25%, 50%, 75% and 100%). The precision levels represent the degree of similarity: the higher the level, the more similar attributes there are between files. **The Spectra Analyze appliance can display RHA information for PE, MachO, and ELF samples. Only the first precision level (25%) is supported for those file formats.** If RHA results are available for a file, they will be displayed next to a red RHA icon on the left side of the [Expanded Details](./search-page.md#expanded-details) section, in the sidebar of the [Sample Details](./Sample%20Details/index.md) page, and in the File Similarity section on the Summary section of the Sample Details page. ![The File Similarity section in the Sample Details page sidebar](images/analyze-file-similarity-sidebar.png) To get a list of functionally similar samples for a file: - click the links in the File Similarity section on the Sample Details page - expand the row on the Search page and click any of the numbers in the RHA section (above User and System Tags) ![RHA table with numerical callouts indicating RHA-related options](images/analyze-file-similarity.png) This will open the RHA results with samples functionally similar to the selected file. They can be filtered by threat status (All threats, Goodware, Unknown, Malicious, Suspicious) and by source (All, Local, Spectra Intelligence). Additionally, *Subscribe/Unsubscribe* options are available for those files, making it possible to create alert subscriptions for them. When the cursor changes to an up-down arrow in the RHA results list, click to expand the row and get more information about the file. ![Expanded sample row in the RHA table](images/analyze-expanded-similarity.png) Files marked with a gray cloud icon are unavailable for download, while those marked with a black cloud icon can be downloaded to the appliance. Clicking **Fetch All** at the top of the RHA results list will download all available files to the appliance, up to a maximum of 1000 files. It is also possible to manually select one or multiple files from the list and click **Fetch Selected**. The procedure is identical to the one described in the [Downloading Files from Spectra Intelligence](#downloading-files-from-spectra-intelligence) section. **Tip: When the functionally similar samples are downloaded and analyzed, it is useful to look at their “Protection” features and “Indicators” (in the Sample Details > Spectra Core section), and compare them.** --- ## Advanced Search ## Introduction The Advanced Search feature introduces rich metadata search capabilities on the ReversingLabs Spectra Analyze appliance, makes it easier to search across large data sets (both locally and in ReversingLabs Spectra Intelligence), and enables faster, more powerful malware discovery with increased coverage. With 100+ keywords, 30+ anti-virus vendors, 130+ sample types and subtypes and 280+ tags, Advanced Search makes it possible to build more than 500 unique search queries using Boolean operators and keyword auto-completion. Users can create targeted, multi-conditional queries and combine search criteria using logical operators to quickly identify potential threats. **The Advanced Search feature can be used to perform local searches without a Spectra Intelligence account. Using Advanced Search to retrieve Spectra Intelligence results is available to customers at additional cost. For more information, contact ReversingLabs Sales Support (insidesales@reversinglabs.com).** ## Important notes about the Advanced Search feature - **Different search queries return results at different speeds** - for some combinations of keywords and operators, it can take longer to load the results. To ensure quicker response times for long and complex queries, returned results may contain fewer samples than are available in the database; i.e., the service will only return the latest matches found within a reasonable timeframe. **Important: To improve search query responsiveness and performance, Cloud results prioritize *First Seen* within the last month by default. However, this may result in zero results if users specify time ranges outside this time frame. In such cases, the results page provides links to expand the search results. If the query returns some results but there are more in the previous months, clicking the link next to the query summary under the drop-down menu filters broadens the search to encompass a wider time range. Alternatively, users can set the provided drop-down filters to the desired expanded time range.** - **Local-only keywords will not work on the Cloud tab, as local-only keywords cannot be used to search for samples in the Spectra Intelligence cloud. Only actual file submissions will be returned as results.** Local-only keywords are: `filecount`, `tag-user`, `submission-user`, `submission-time` and `processing-status`. To perform Spectra Intelligence searches or search for extracted files, remove any local keywords from the query. - **The maximum length of a single search query is 1024 characters.** Queries longer than 1024 characters cannot be shared or added to Favorites. Attempting to submit queries longer than 1024 characters will result in an error. This does not apply to Bulk hash search queries. - **The maximum amount of Cloud results that can be returned for a search query is 100 000.** Although there may be more samples matching the query in the Spectra Intelligence cloud, the Spectra Analyze will only allow browsing through 100 000 of them. - **Currently it is only possible to export a single page of search results.** To export all results from the list, the user would have to browse pages one by one and manually export them. It is possible to adjust the amount of results displayed per page in the navigation bar, thus increasing or decreasing the number of results that will appear in the exported CSV file. - **The \*Fetch & Analyze\* option for Cloud results is currently limited to downloading 100 samples at a time, with a daily limit of 10 000 samples in total.** Samples that already exist on Spectra Analyze will not be downloaded again. It is not possible to fetch and analyze all samples in the Cloud results list at once. - **Large volumes of data indexed for Advanced Search in the Spectra Intelligence cloud are constantly updated in order to return the most relevant information.** During synchronization of various Spectra Intelligence services, searching for samples the cloud may return inconsistent or incorrect results in some cases. The data is updated multiple times per hour. This can cause discrepancies between the results offered on the Local and Public (Spectra Intelligence) results tabs. ## How to Write Search Queries **Local-only keywords will not work on the Cloud tab, as local-only keywords cannot be used to search for samples in the Spectra Intelligence cloud. Only actual file submissions will be returned as results.** Local-only keywords are: `filecount`, `tag-user`, `submission-user`, `submission-time` and `processing-status`. To perform Spectra Intelligence searches or search for extracted files, remove any local keywords from the query. Local-only keywords, when added using the drop-down menus, will not be shown in the Advanced Search box as part of the query, but they will still be applied to the results, saved to the *Recent queries* list, and shared using the *Share query* button. To create a search query, start typing into the *Advanced search* box. The pull-down list with all matching search keywords or their predefined values will open. The keywords are listed alphabetically. Every search query must contain at least one keyword and one value. Search queries are built according to the following formula. ``` keyword:value OPERATOR keyword2:value OPERATOR keyword3:[value1,value2,...] ``` The values for a keyword can be typed in manually, or if the keyword supports it, selected from the pull-down list. Selecting a keyword that supports predefined values (for example, *classification*, *riskscore*) displays all those values in the pull-down list. Selecting a keyword that supports date and time ranges (such as *lastseen* or *firstseen*) displays the date picker. To add a custom range to the search box, select “Custom” in the date picker and click the *Apply* button. Keywords have short usage examples in the pull-down list. For a detailed overview of supported keywords and their features, refer to the [Supported Search Keywords section](./advanced-search.md#supported-search-keywords). Some keywords have aliases - additional forms that can be used to search for the same values. Aliases are indicated in the Supported Search Keywords section in parentheses next to keyword names, and in the interface as illustrated in the screenshot below. ![Pull-down list of search keywords with aliases highlighted](./images/analyze-search-aliases-help.png) To run a search query, click the *Search* button in the search box, or press Enter. ------ The following is an example of a basic search query that returns all samples classified as suspicious: ``` classification:suspicious ``` What can and cannot be included in a search query depends on the values and operators supported by the keyword, as well as on the restricted words and characters. The maximum length of a single search query that can be entered into the *Advanced search* box is 1024 characters. ### Restricted Words and Characters All restricted words and characters should be escaped with double quotation marks in the search query. Example: a query contains one of the restricted characters **[**, **]**, **(**, **)**, **:** ``` pdb:"C:\Windows*" ``` Example: a query contains one of the restricted words (**AND**, **OR**, **NOT**) ``` cert-subject-name:"AND" ``` If the search query contains spaces, use double quotation marks around it. ``` cert-subject-org:"microsoft corporation" ``` ### Searching for Exact Matches For more precise results, use quotation marks in search queries, especially when looking for a specific string. The underscore character ( **_** ) is treated as a delimiter. Phrases containing the underscore should be enclosed in quotation marks to get exact matches. For example, searching for `pe-function:"Py_Initialize"` returns results that match the exact phrase, including the underscore character. Searching for `pe-function:Py_Initialize` returns results that match either “Py” or “Initialize”, or both. ### Using Wildcards for Partial Matching Some search keywords support partial matching with wildcard symbols. The `*` symbol matches any sequence of characters. The `?` symbol matches any single character. Example: this query returns all samples that have the string “emo” anywhere in their threat name (such as Wemosis, Remora, Temonde). ``` av-detection: *emo* ``` Example: this query returns all samples with the threat name “Emotet” and any other variant where the first letter T is replaced by any other character (such as Emonet, Emoret). ``` av-detection: emo?et ``` ### Searching for a Range and Greater/Less-Than Values For keywords that support searching for a range of values, the formula looks like this. ``` keyword:[value1 TO value2] size:[50000 TO 70000] ``` To search for greater/less-than values, create an open-ended range using the wildcard symbol `*` ``` keyword:[value TO *] - for greater-than values keyword:[* TO value] - for less-than values ``` This example returns all samples that have a trust factor lower than and equal to 4. ``` trustfactor:[* TO 4] ``` ### Searching for a List of Values To search for any of the values in a list, the following formula is used. ``` keyword:[value1, value2, value3] ``` The values must be comma-separated. ``` classification:[suspicious, unknown] av-detection:[emotet,wannacry] sha1:[91b21fffe934d856c43e35a388c78fccce7471ea,4e8c5b9fc9a6650f541fa0dbe456731309a429e4, 66720a660761e9b3b9b071ba4c16d6ab69c442bb] ``` ### Creating Multi-keyword Search Queries Search operators and parentheses can be used to combine multiple keywords and create advanced search queries. The following search operators are supported: **AND**, **OR**, **NOT** If an operator is not provided, **AND** is used as the default. Operators are case-insensitive, so the following queries all return the same results. ``` firstseen:2018-01-01T00:00:00Z AND classification:malicious firstseen:2018-01-01T00:00:00Z and classification:malicious firstseen:2018-01-01T00:00:00Z classification:malicious ``` The **NOT** operator excludes search results that match the search criteria. In the following example, malicious and suspicious files will be excluded from the results: ``` av-detection:*linux* NOT classification:[malicious, suspicious] ``` The **OR** operator can be used to look for any of the values supported by a single keyword: ``` classification:suspicious OR classification: malicious ``` It can also be used to look for any of the different keywords and their values: ``` pdb:JigsawRansomware.pdb OR uri:"http://btc.blockr.io/api/v1/" ``` The **OR** operator cannot be used instead of a comma when searching for a list of values. The following example is **not a valid query**: ``` av-detection:[emotet OR wannacry] ``` **Parentheses** can be used to combine keywords. The following two queries show how to format the same request using square brackets versus parentheses: ``` firstseen:2018-01-01T00:00:00Z av-detection:[trojan,wannacry] firstseen:2018-01-01T00:00:00Z (av-detection:trojan OR av-detection:wannacry) ``` Apart from using parentheses with the same keyword, they can be used to combine multiple different keywords, operators, and even a range: ``` firstseen:2018-01-01T00:00:00Z (av-detection:trojan AND type:binary NOT positives:[* TO 3]) ``` ### Saving and Sharing Search Queries There are several ways to save search queries on the Spectra Analyze appliance. 1. Search queries can be saved as Favorites on the Spectra Analyze appliance itself. Run any query and click the star button right of the search box to save it. The query will be listed under *Favorites* in the [Suggestions menu](./search-page.md#show-suggestions). It can be modified to include other search keywords and parameters, or removed from the appliance at any time. The maximum of 20 search queries can be saved in this way. 2. Search queries can be saved using the built-in bookmarking functionality of the web browser. Run any query and bookmark the results page. In this case, any active filtering parameters (such as sorting and number of results per page) are also preserved in the bookmarked URL. A search query saved in this way will only work on the Spectra Analyze instance specified in the bookmarked URL. Similarly, search queries can be shared in several ways: 1. by using the *Share query* option on the Spectra Analyze appliance. Type in any query and click the *Share* button right of the search box. The *Share Query* dialog opens, where recipient email addresses have to be entered. Clicking the *Share* button in the dialog will send the selected query to provided email addresses. The email *Subject* field will contain the username of the Spectra Analyze user who shared the query. 2. by copying the URL of the search results page from the address bar of the browser, and sending it manually via email or other communication channel. A search query shared in this way will only work if the recipient can log into the same Spectra Analyze instance from which the query was sent. 3. by copying a favorite query to the clipboard (hover over the query in the *Favorites* list and select the *Copy* option from the triple-dot menu), then sharing it manually via email or other communication channel. ### Non-keyword Queries Advanced search queries can be quickly built without using keywords. Non-keyword search is available only for a particular subset of indicators of compromise: > - SHA1, SHA256 and MD5 hashes > - URLs > - IP addresses > - domains > - emails #### Non-keyword Search Queries Non-keyword searches can be performed as standalone queries containing one or more non-keyword values, or be combined with traditional keyword searches. Email and IP (IPv4, IPv6) non-keyword queries support wildcard matching. If a list of non-keyword search values contains invalid entries, search will respond with the message “Unrecognized nonkeyword argument” and return the first invalid non-keyword. In cases where the query contains only hashes, the response returns “Invalid value for hashes field”. Using commas between non-keyword search values will result in an invalid query. Searching for strings containing commas and other special characters is supported by using quotation marks. For example, IPV6 addresses or URLs containing colons, commas, or brackets must be enclosed in quotation marks: ``` "2001:0db8:85a3:0000:0000:8a2e:0370:7334" ``` ``` "http://www.evildomain.com/gate.php?13,35869" ``` **Single non-keyword search** This can be any one of the IOCs listed above. Example: SHA1 ``` 0000038704cb5f0e1bd87d6a75e904529af0d6ac ``` **Multiple non-keyword search** To combine multiple non-keyword search values, separate them by space. The whole query will be enclosed in brackets and the spaces will be interpreted as the operator OR. Other operators (AND/NOT) can be explicitly provided to build more complex queries. Example: IPV4, IPV6 and domain ``` 127.0.0.1 "2620:119:35::35" google.com ``` Example: Hashes only ``` 0000038704cb5f0e1bd87d6a75e904529af0d6ac 2abcd3fb8b7761526d177ab007c40e74 4dea2daa9a41dd6c4cb172eb6d8d8a1d1811360e21c5fa0c8ce2e20fd6903041 ``` **Non-keyword with keyword** When combining non-keyword search values with keywords, consecutive non-keyword values will be enclosed in brackets and the spaces between them will be interpreted as the operator OR. Spaces between non-keyword search values and keywords will be interpreted using the operator AND, meaning that the order of keywords and non-keyword values in the query is important. Example: Samples containing the provided URL that are classified as goodware ``` "https://hope-bd.com/googledocs.php" class:goodware ``` **Combining queries with the NOT operator** The **NOT** operator excludes search results that match the defined criteria. Example: Query using the operator NOT > ``` > NOT *@mockmail.com "https://hope-bd.com/googledocs.php" AND NOT 0000038704cb5f0e1bd87d6a75e904529af0d6ac class:MALICIOUS > ``` #### Non-keyword Search Examples | Query Type | Example | Syntax | Outcome | | ----------------------------------------------------------- | ------------------------------------------------------------ | -------------------------- | --------------------------------------------------- | | Single non-keyword | 0000038704cb5f0e1bd87d6a75e904529af0d6ac | NK | NK | | Non-keyword search values combined with keywords | “https://hope-bd.com/googledocs.php” class:goodware | NK K | NK **AND** K | | Multiple non-keyword values (hashes only) | 0000038[…]af0d6ac 2abcd3[…]7c40e74 4dea2da[…]6903041 | NK NK NK NK | (NK **OR** NK **OR** NK **OR** NK) | | Multiple non-keyword values | 127.0.0.1 “2620:119:35::35” google.com | NK NK NK NK | (NK **OR** NK **OR** NK **OR** NK) | | Multiple non-keyword values with an AND operator | [mock@mockmail.com](mailto:mock@mockmail.com) 127.0.*.1 AND google.com “https://hope-bd.com/googledocs.php” | NK NK AND NK NK | (NK **OR** NK) **AND** (NK **OR** NK) | | Multiple keywords combined with multiple non-keyword values | class:MALICIOUS mock@mockmail.com google.com firstseen:2018-04-05T21:11:47Z | K NK NK K | K **AND** (NK **OR** NK) **AND** K | | Combining queries with the NOT operator | NOT [*@mockmail.com](mailto:*@mockmail.com) “https://hope-bd.com/googledocs.php” AND NOT 0000038[…]af0d6ac class:MALICIOUS | NOT NK NK AND NOT NK AND K | (**NOT** NK **OR** NK) **AND** **NOT** NK **AND** K | **Note: The final, transformed queries will be returned in the *Advanced search* box and added to the *Recent queries* list. They can be saved as favorites by clicking the star button to the right of the search box.** ## Supported Search Keywords ### User-friendly modifiers Some keywords support **modifiers** that serve as shorthand notation for search expressions. #### Numbers Keywords that accept numbers as values also accept a trailing plus or minus sign. For example: - `5+` (five or more) - `42-` (fourty-two or less) Exceptions: - Spaces are not allowed. - Prefixes are also not allowed (only trailing plus or minus). - Modifiers can't be used in range queries. For example, `[3+ to 5-]` is invalid.
List of keywords that accept numbers - `av-count` - `av-threatlevel` - `document-pages` - `elf-section-count` - `filecount` - `macho-section-count` - `macho-segment-count` - `pe-section-count` - `riskscore` - `size` - `submissions` - `threatlevel`
#### Dates Keywords that accept dates also accept period abbreviations and trailing plus/minus. Accepted abbreviations: - `h` for hours - `d` for days - `w` for weeks - `m` for months - `y` for years The trailing plus or minus sign behaves just like for numbers. For example: - `2023-04-11T08:10:00+` (on April 11 2023 at 08:10, or after that time) - `3d+` (three days or more) - `1w-` (one week or less) Exceptions: - Spaces are not allowed. - Prefixes are also not allowed (only trailing plus or minus). - Modifiers can't be used in range queries. For example, `[3d to 5w]` is invalid.
List of keywords that accept dates - `firstseen` - `lastanalysis` - `lastseen` - `pe-timestamp` - `signer-valid-from` - `signer-valid-to` - `submission-time` - `taggant-valid-from` - `taggant-valid-to`
#### Sizes Keywords that accept sizes also accept unit abbreviations (KB, MB, GB...) and trailing plus/minus. The abbreviations are case-insensitive. If an abbreviation is not specified, the expression is evaluated in bytes. [Byte multiples](https://en.wikipedia.org/wiki/Byte#Multiple-byte_units) are supported in both decimal (kilo-, mega-, giga-...) and binary (kibi-, mebi-, gibi-...) form. For example: - `5MB+` (five megabytes or larger) - `13kib-` (thirteen kibibytes or smaller) Exceptions: - Spaces are not allowed. - Prefixes are also not allowed (only trailing plus or minus). - Modifiers can't be used in range queries if they contain a trailing plus or minus sign. For example, `[3kB+ to 5MB]` is invalid. However, if you use them without a trailing plus/minus, they can be used in a range query. For example, `[3kb TO 5mb]` is allowed. The only keyword that accepts a size is `size`. ### Group keywords When using group keywords, the provided search query will be used with all single keywords in the group's respective list. Refer to the single keyword descriptions for more information. Keyword aliases are enclosed in parentheses. | `certificate` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `cert-issuer-name` `cert-issuer-org` `cert-issuer-unit` `cert-subject-name` `cert-subject-org` `cert-subject-unit` | | Examples | Case-insensitive wildcard matching is supported.Wildcard: `certificate:*micr*` | | `certificate-country` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `cert-issuer-country` `cert-subject-country` | | Examples | Case-insensitive wildcard matching is supported.List (any of the values): `certificate-country:[HR, US]` | | `document` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `document-author` `document-subject` `document-title` `document-description` | | Examples | Case-insensitive wildcard matching is supported.List (any of the values): `document:[adobe, microsoft, *confidencial]`Wildcard: `document:*soft` | | `mutex` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `mutex-config` `mutex-dynamic` | | Examples | The keyword is case-sensitive and doesn't accept wildcards.Exact: `mutex:111c`List (any of the values): `mutex:[111c, 2124]` | | `ipv4` (`ip`) | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `ipv4-static` `ipv4-dynamic` | | Examples | Wildcard matching supported.Wildcard: `ipv4:192.*`List (any of the values): `ipv4:[1.0.0.0,1.0.2.1]` | | `ipv6` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `ipv6-static` (IPv6 address strings detected by ReversingLabs Dynamic Services) | | Examples | If the address contains colons or brackets, enclose it in quotation marks.Wildcard matching supported.Wildcard: `ipv6:c*`Exact: `ipv6:"2002::/16"`List (any of the values): `ipv6:["2001:db8*", "3731:54:"]` | | `section` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `pe-section-name` `elf-section-name` `macho-section-name` | | Examples | Case-insensitive wildcard matching is supported.Wildcard: `section:*data`List (Any of the values): `section:[.ndata, bss]` | | `segment` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `macho-segment` `macho-segment-name` `elf-segment-sha1` | | Examples | Case-insensitive wildcard matching is supported.Wildcard: `segment:page*`List (any of the values): `segment:[pagezero, text]` | | `software` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `software-package` `software-description` `software-author` | | Examples | The keyword does not accept wildcards.Exact: `software:"James Newton-King"`List (any of the values): `software:[Microsoft, "This package consists of multiple activities that simplify the processes in Excel."]` | | `upload-data` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `upload-source` `upload-source-tag` | | Examples | Examples:`upload-data:myapp`, `upload-data:myemail*` | | `uri` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `uri-source` `uri-static` `uri-config` `uri-dynamic` | | Examples | Case-insensitive wildcard matching is supported. (`uri*` keywords don't support IP addresses. For that, use `ip*` keywords.)Wildcard: `uri:mozilla.org*`List (any of the values): `uri:[\*.tor,*.onion,*.exit]` | ### Single keywords | `actor` | | |-------------|---------------------------------------------------------------------------------------------------------| | Description | Search for files associated with a specific threat actor. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `actor:*APT*`List (any of the values): `actor:[Hellsing, Cycldek]` | | `android-app-name` | | |--------------------|----------------------------------------------------------------------------------------------------------------------------| | Description | Search for Android applications by their process name. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `android-app-name:*SkypeApplication*`List (any of the values): `android-app-name:[MainApp, *alt.ywuajgf*]` | | `android-features` | | |--------------------|----------------------------------------------------------------------------------------------------------------------| | Description | Search for Android applications by their features. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `android-features:*hardware.camera*`List (any of the values): `android-features:[camera, telephony]` | | `android-import` | | |------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | Description | Search for Android applications by one or more shared libraries that the applications are linked against. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `android-import:org.apache.http.legacy*`List (any of the values): `android-import:[sec_fe?ture, *google*]` | | `android-package` | | |-------------------|--------------------------------------------------------------------------------------------------------------------------------------| | Description | Search for Android applications by their package name. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `android-package:*com.picklieapps.player*`List (any of the values): `android-package:[*ruckygames*, *skype.raider*]` | | `android-permission` || |----------------------|------| | Description | Search for Android applications by their permissions. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `android-permission:*WRITE_SETTINGS*`List (any of the values): `android-permission:[*storage*, *disable_keyguard*]` | | `appid-company-name` (`appid-author`) || |-------------|------| | Description | Search for applications and libraries by their publisher. Case-insensitive wildcard matching is supported. | | Examples | Exact: `appid-company-name:"Mozilla Foundation"`List (any of the values): `appid-company-name:["Mozilla Foundation", "Microsoft Corporation"]` | | `appid-description` || |-------------|------| | Description | Search for applications and libraries by their description. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `appid-description:"*Firefox Plugin Hang UI*"*` | | `appid-product-name` | | |-------------|------| | Description | Search for files with a matching product name. Case-insensitive wildcard matching is supported. | | Examples | Exact: `appid-product-name:"Mozilla Firefox Plugin Hang UI"`List (any of the values): `appid-product-name:["Mozilla Firefox Plugin Hang UI", "Mozilla Firefox Helper"]` | | `appid-product-type` (`appid-category`) | | |-------------|------| | Description | Search for applications and libraries by their type. Case-insensitive wildcard matching is supported. | | Examples | Exact: `appid-product-type:browser`List (any of the values): `appid-product-type:[browser, development]` | | `attack-tactic` | | |-------------|------| | Description | Search for files that use a specific Mitre ATT&CK tactic. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `attack-tactic:TA0007`List (any of the values): `attack-tactic:[TA0007, TA0005]` | | `attack-technique` | | |-------------|------| | Description | Search for files that use a specific Mitre ATT&CK technique. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `attack-technique:T1222`List (any of the values): `attack-technique:[T1222, T1112]` | | `av-count` (`positives`, `p`, `antivirus`) | | |-------------|------| | Description | The number of antivirus scanners that have detected a sample as malicious. Currently supports any integer from 0 to 46 (46 being the number of active AV scanners). | | Examples | Exact: `av-count:5`Range: `positives:[10 TO 20]`Greater than 5: `positives:[5 TO *]`List (any of the values): `av-count:[5,3]` | | `av-detection` (`engines`) | | |-------------|------| | Description | Detection string generated by the antivirus engines. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `av-detection:micro*`List (any of the values): `av-detection:[W32.Duqu, *Vitro]` | | `av-` (``) | | |-------------|------| | Description | Search for all samples or samples of specific malware detected by a selected antivirus vendor. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `av-[vendor]:*wannacry*`List (any of the values): `[vendor]:[win32, emotet]` | | `available` (`in`, `shareable`) | | |-------------|------| | Description | Indicates whether a sample is available for download from the cloud. The only supported values are true and false (case-insensitive). | | Examples | `available:TRUE``in: false` | | `browser-package` | | |-------------|------| | Description | Search for web browser extensions by their package name. Supported package formats: Chrome, Safari, Firefox. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `browser-package:*Click2Save*`List (any of the values): `browser-package:[*priiceechOp*, *iCalc*]` | | `cert-issuer-country` | | |-------------|------| | Description | Search for files by the country code in the country name property field of the issuer of the certificate used to sign the file. Case-insensitive wildcard matching is supported. | | Examples | Exact: `cert-issuer-country: US`List (any of the values): `cert-issuer-country:[Z?,G*]` | | `cert-issuer-name` | | |-------------|------| | Description | Search for files by the name of the certificate authority (CA). Case-insensitive wildcard matching is supported. | | Examples | Exact: `cert-issuer-name: COMODO`List (any of the values): `cert-issuer-name:[microsoft,*VeriSign*]` | | `cert-issuer-org` | | |-------------|------| | Description | Search for files by the organization name of the certificate issuer. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `cert-issuer-org:*authority`List (any of the values): `cert-issuer-org:[verisign, microsoft]` | | `cert-issuer-unit` | | |-------------|------| | Description | Search for files by the organizational unit name of the issuer unit of the certificate authority (CA). Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `cert-issuer-unit:*root*` List (any of the values): `cert-issuer-unit:["trust network", *root*]` | | `cert-serial` | | |-------------|------| | Description | Search for a file by the serial number of the file certificate provided by the CA that issued the certificate. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `cert-serial:6101CF3E00000000000F`List (any of the values): `cert-serial:[,]` | | `cert-subject-country` | | |-------------|------| | Description | Search for files by the country code in the country name property field of the subject to which the certificate has been issued. Case-insensitive wildcard matching is supported. | | Examples | Exact: `cert-subject-country:DE`List (any of the values): `cert-subject-country:[US, B*]` | | `cert-subject-name` | | |-------------|------| | Description | Search for files by the name of the organization/system to which the certificate has been issued. Case-insensitive wildcard matching is supported. | | Examples | Exact: `cert-subject-name:Piriform`List (any of the values): `cert-subject-name:[cinectic*, google]` | | `cert-subject-org` | | |-------------|------| | Description | Search for files by the organization name of the certificate authority organization (CA). Case-insensitive wildcard matching is supported. | | Examples | Exact: `cert-subject-org:apple`List (any of the values): `cert-subject-org:[apple, Microsoft]` | | `cert-subject-unit` | | |-------------|------| | Description | Search for files by the organizational unit name inside the organization to which the certificate has been issued. Case-insensitive wildcard matching is supported. | | Examples | Exact: `cert-subject-unit:"Developer Relations"`List (any of the values):`cert-subject-unit:[Developer*, "Trust Network"]` | | `cert-thumbprint` | | |-------------|------| | Description | Search for files by their unique certificate thumbprint. A thumbprint of a file certificate is a hash value (SHA256). The keyword doesn't accept wildcards. | | Examples | Exact: `cert-thumbprint:277D42[...]2A17DD`List (any of the values): `cert-thumbprint:[, ]` | | `classification` (`class`) | | |-------------|------| | Description | Search for files by their Malware Presence status designation. Accepted values: malicious, known, suspicious, unknown (case-insensitive). | | Examples | Exact: `classification:malicious`List (any of the values): `classification:[KNOWN, suspicious]` | | `dex-class-name` | | |-------------|------| | Description | Search for DEX files by the names of classes they contain. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dex-class-name:android.content.DialogInterface.On*`List (any of the values): `dex-class-name:[android.content.DialogInterface.On*, android.support.v4.*]` | | `dex-method-name` | | |-------------|------| | Description | Search for DEX files by method names their classes call to perform an action. Method names are indexed regardless of their visibility, meaning both public and private methods are searchable. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dex-method-name:unregisterCallB*`List (any of the values): `dex-method-name:[getLocation, invok*]` | | `document-author` | | |-------------|------| | Description | Search for files by the contents of their document author metadata property. Case-insensitive wildcard matching is supported. | | Examples | List (any of the values): `document-author:[adobe, microsoft]`Wildcard: `document-author:*soft` | | `document-description` (`doc-description`) | | |-------------|------| | Description | Search for files by the document description field, as provided by the document author. Case-insensitive wildcard matching is supported. | | Examples | List (any of the values): `document-description:["Carta personal", *confidencial]`Wildcard: `document-description:*Math*` | | `document-pages` (`doc-pages`) | | |-------------|------| | Description | Search for files by their number of pages. In case of spreadsheet documents, this number represents the number of sheets. The keyword accepts only integer values. | | Examples | Exact: `document-pages:73`Range: `document-pages:[4 TO 20]`More than 4: `document-pages:[4 TO *]` | | `document-subject` | | |-------------|------| | Description | Search for files by the contents of their document subject metadata property. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `document-subject:*search`List (any of the values): `document-subject:[free, download]` | | `document-title` | | |-------------|------| | Description | Search for files by the contents of their document title metadata property. Case-insensitive wildcard matching is supported. | | Examples | Exact: `document-title:"Powered by"`List (any of the values): `document-title:[*free*, README]` | | `document-version` | | |-------------|------| | Description | Search for files by the contents of their document version metadata property. Wildcard matching is supported. | | Examples | Wildcard: `document-version:1.1*`List (any of the values): `document-version:[1.7, 2.*]` | | `domain` | | |-------------|------| | Description | Search for files by any associated domain. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `domain:mozilla.org*`List (any of the values): `domain:[*.tor,google.com,*.exit]` | | `dotnet-assembly` | | |-------------|------| | Description | Search for .NET files by assemblies they reference. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dotnet-assembly:*mscorlib*`List (any of the values): `dotnet-assembly:[*iJnJWYUQA*, "NanoCore Client"]` | | `dotnet-method-name` | | |-------------|------| | Description | Search for .NET files by method names their classes call to perform an action. Method names are indexed regardless of their visibility, meaning both public and private methods are searchable. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dotnet-method-name:get_Url`List (any of the values): `dotnet-method-name:[?oadCompl*, *HoldEnd]` | | `dotnet-module-id` | | |-------------|------| | Description | Search for .NET files by IDs of modules they contain. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dotnet-module-id:*20DEC3DA-523F*`List (any of the values): `dotnet-module-id:[*9249F5D0-1821*, *E133ACC7-60C9*]` | | `dotnet-module-name` | | |-------------|------| | Description | Search for .NET files by names of modules they contain. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dotnet-module-name:*TeSt.exe*`List (any of the values): `dotnet-module-name:[Posh.exe, adobe.exe]` | | `dotnet-pinvoke-function` | | |-------------|------| | Description | Search for .NET files by pinvoke functions. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dotnet-pinvoke-function:EncodePointer*`List (any of the values): `dotnet-pinvoke-function:["EncodePointer", "DecodePointer"]` | | `dotnet-pinvoke-import` | | |-------------|------| | Description | Search for .NET files by pinvoke imports. Case-insensitive wildcard matching is supported. | | Examples | Exact: `dotnet-pinvoke-import:kernel32.dll`List (any of the values): `dotnet-pinvoke-import:["kernel32.dll", "user32.dll"]` | | `dotnet-resource` | | |-------------|------| | Description | Search for .NET files by resources they contain. Case-insensitive wildcard matching is supported. | | Examples | Exact: `dotnet-resource:"Hidden Tear"`List (any of the values): `dotnet-resource:[*Orcus*, *Clientloaderform*]` | | `dotnet-type-name` | | |-------------|------| | Description | Search for .NET files by type names found in them. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dotnet-type-name:Form1*`List (any of the values): `dotnet-type-name:[Form1*, NetscapeRevocationUrl]` | | `elf-section-count` | | |-------------|------| | Description | Search for ELF files by the amount of sections they contain. The keyword accepts only integer values. | | Examples | Exact: `elf-section-count:5`Range: `elf-section-count:[5 TO 15]`More than 5: `elf-section-count:[5 TO *]` | | `elf-section-name` | | |-------------|------| | Description | Search for ELF files by names of the sections they contain. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `elf-section-name:*data`List (any of the values): `elf-section-name:[.rodata, .ndata, .bss]` | | `elf-segment-sha1` (`elf-segment-hash`) | | |-------------|------| | Description | Search for files by the SHA1 hash of their ELF segment. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `elf-segment-sha1:116e279b55b58e5b9619aac80a8e85bfa9c839fc` | | `email-from` | | |-------------|------| | Description | Search for files by the sender of an email associated to a file. Includes "from", "reply-to" and "sender" fields. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `email-from:*@kiski.net`List (any of the values): `email-from:[*@domain.com, *@orbitz.com]` | | `email-static` (`email`) | | |-------------|------| | Description | Search for files by associated email address(es) detected by [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis). Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `email-static:*@Compartir.es`List (any of the values): `email-static:[*@gmail.com, *@hotmail.com]` | | `email-subject` | | |-------------|------| | Description | Search for files by the subject of an email associated to a file. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `email-subject:*HackTool`List (any of the values): `email-subject:[Invitation*, *Nova*]` | | `email-to` | | |-------------|------| | Description | Search for files by the receiver of an email associated to a file, specified in the "to" field. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `email-to:*@netnook.com`List (any of the values): `email-to:[*@dekalb.net, *@rogers.com]` | | `email-x-key` | | |-------------|------| | Description | Search for files with non-standard header fields, called X-extensions. Security vendors use X-extensions to annotate emails that have been scanned using their product. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `email-x-key:*MDRemoteIP`List (any of the values): `email-x-key:[*Indiv, *Markup]` | | `email-x-value` | | |-------------|------| | Description | Search for files by values stored in non-standard (X-extension) header fields. Case-insensitive wildcard matching is supported. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `email-x-value:?HAILAND`List (any of the values): `email-x-value:[Produced*, BHUTAN]` | | `exif` | | |-------------|------| | Description | Search for multimedia files by the contents of their EXIF metadata fields. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `exif:Picasa*`List (any of the values): `exif:["Paint.NET v3.5.8", Picasa*]` | | `exploit` | | |-------------|------| | Description | Search for samples that are exploiting a specific vulnerability, identified either by ReversingLabs or by antivirus scanners. | | Examples | Examples Wildcard: `exploit:cve-2024-*`*List (any of the values): `exploit:["CVE-2014-0114", "CVE-2018-15982"]` | | `filecount` | | |-------------|------| | Description | Search for a file by the number of unpacked files it contains (if it's a container). Accepts any integer number. **Note: this keyword currently returns only Local samples as results.** | | Examples | Exact: `filecount:25`Range: `filecount:[3 TO 10]`More than 20: `filecount:[20 TO *]` | | `filename` (`name`) | | |-------------|------| | Description | Search for a file by its full or partial file name, predicted file name (generated by Spectra Core for samples without a file name), or file extension. Case-insensitive wildcard matching is supported. | | Examples | Exact: `filename:notepad.exe`List (any of the values): `filename:[*.PDF, *.epub]` | | `firstseen` (`fs`) | | |-------------|------| | Description | Time when a file was first analyzed by Spectra Intelligence. Supported time format is UTC timestamp. | | Examples | Exact: `fs:2018-04-03T12:58:27Z`Range (time period):`firstseen:[2017-12-01T11:36:59Z TO 2018-03-06T11:36:59Z]` | | `hashes` | | |-------------|------| | Description | Allows mixing different types of hashes in one search query, without the need to explicitly name the hash type or to group hashes by type. All hash types (MD5, SHA1, SHA256) can be used with this keyword. The maximum length of a single query is 1024 characters. The keyword is case-sensitive and doesn't support wildcards. | | Examples | Exact: `hashes: `List (any of the values): `hashes:[, , , , ]` | | `imphash` | | |-------------|------| | Description | Hash based on library/API names and their specific order within the executable. Used to find similar PE files. The keyword doesn't support wildcards. | | Examples | Exact: `imphash:f34d5f2d4577ed6d9ceec516c1f5a744`List (any of the values): `imphash [, ]` | | `indicators` | | |-------------|------| | Description | Search for files by their static analysis behaviors. The keyword is case-sensitive and doesn't accept wildcards. The full list of indicator IDs and their descriptions can be found [here](/General/SpectraCore/indicators/). | | Examples | Exact: `indicators:"2150"`List (any of the values): `indicators:["2150", "2102"]` | | `ios-app-name` | | |-------------|------| | Description | Search for iOS applications by their name. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `ios-app-name:FruitNinja*`List (any of the values): `ios-app-name:[FruitNinja*, *facebook*]` | | `ios-author` | | |-------------|------| | Description | Search for iOS applications by their author name. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `ios-author:*halfbrick*`List (any of the values): `ios-author:[*halfbrick*, Apple*]` | | `ios-package` | | |-------------|------| | Description | Search for iOS applications by their package name. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `ios-package:*FruitNinja*`List (any of the values): `ios-package:[*FruitNinja*, *facebook*]` | | `ipv4-dynamic` | | |-------------|------| | Description | Search for files by IPv4 address strings detected by ReversingLabs Dynamic Services. Wildcard matching supported. | | Examples | Wildcard: `ipv4-dynamic:192.*`List (any of the values): `ipv4-dynamic:[1.0.0.0,1.0.2.1]` | | `ipv4-static` | | |-------------|------| | Description | Search for files by IPv4 address strings detected by Spectra Core analysis. Wildcard matching supported. | | Examples | Wildcard: `ipv4-static:192.*`List (any of the values): `ipv4-static:[1.0.0.0,1.0.2.1]` | | `ipv6-static` | | |-------------|------| | Description | Search for files by IPv6 address strings detected by Spectra Core analysis. If the address contains colons or brackets, enclose it in quotation marks. Wildcard matching supported. | | Examples | Wildcard: `ipv6-static:c*`Exact: `ipv6-static:"2002::/16"`List (any of the values): `ipv6-static:["2001:db8*", "3731:54:"]` | | `lastanalysis` (`la`) | | |-------------|------| | Description | Search for files by the date and time of their last AV scan. Supported time format is UTC timestamp. | | Examples | Exact: `lastanalysis:2018-05-17T11:27:19Z`Range (time period):`lastanalysis:[2018-05-17T11:27:19Z TO 2018-05-24T11:27:19Z]` | | `lastseen` (`ls`) | | |-------------|------| | Description | Time when a file was last analyzed by Spectra Intelligence. Supported time format is UTC timestamp. | | Examples | Exact: `ls:2018-04-03T12:58:27Z`Range (time period):`lastseen:[2017-12-01T11:36:59Z TO 2018-03-06T11:36:59Z]` | | `macho-import` | | |-------------|------| | Description | Search for MachO files by the names of imported libraries found in them. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `macho-import:*/usr/lib/*`List (any of the values): `macho-import:[/usr/lib/libgcc_s.1.dylib, /usr/lib/libSystem.B.dylib]` | | `macho-section-count` | | |-------------|------| | Description | Search for MachO files by the number of sections they contain. The keyword accepts only integer values. | | Examples | Exact: `macho-section-count:10`Range: `macho-section-count:[5 TO 15]`More than 5: `macho-section-count:[5 TO *]` | | `macho-section-name` | | |-------------|------| | Description | Search for MachO files by the names of the sections they contain. Case-insensitive wildcard matching supported. | | Examples | Exact: `macho-section-name:data`List (any of the values): `macho-section-name:[bss, common, data]` | | `macho-segment` (`macho-segment-name`) | | |-------------|------| | Description | Search for MachO files by their segment names. Case-insensitive wildcard matching supported. | | Examples | Exact: `macho-segment:pagezero`List (any of the values): `macho-segment:[linkedit, pagezero, text]` | | `macho-segment-count` | | |-------------|------| | Description | Search for MachO files by the count of segments they contain. The keyword accepts only integer values. | | Examples | Exact: `macho-segment-count:30`Range: `macho-segment-count:[2 TO 8]`More than: `macho-segment-count:[11 TO *]` | | `macho-segment-sha1` (`macho-segment-hash`) | | |-------------|------| | Description | Search for files by the SHA1 hash of their MachO segment. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `macho-segment-sha1:116e279b55b58e5b9619aac80a8e85bfa9c839fc` | | `macho-symbol` | | |-------------|------| | Description | Search for MachO files by their symbol names. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `macho-symbol:f*`List (any of the values): `macho-symbol:[exit, malloc, umask]` | | `md5` | | |-------------|------| | Description | String of hexadecimal digits representing a MD5 hash of the file sample. Keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `md5:76baa04885ec40af25294a51d8e7c006`List (any of the values): `md5:[, ]` | | `mutex-config` | | |-------------|------| | Description | Search for files by their malware configuration mutexes detected by Spectra Core. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `mutex-config:")!VoqA.I4"`Exact: `mutex-config:"--((Mutex))--"`List (any of the values): `mutex-config:[111c, 2124]` | | `mutex-dynamic` | | |-------------|------| | Description | Search for files by malware configuration mutexes detected by ReversingLabs Dynamic Services. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Wildcard: `mutex-dynamic:111c*`List (any of the values): `mutex-dynamic:[111c, 2124]` | | `pdb-path (pdb)` | | |-------------|------| | Description | Search for files associated with specific PDB (program database) paths. Used to find files with the same PDB path created during file sample compilation. If the path contains restricted characters, enclose it in quotation marks. | | Examples | Exact: `pdb:"D:DevTin7InstallDir"`List (any of the values):`pdb:["C:Windows", "c:Program FilesPerforce"]` | | `pe-company-name` | | |-------------|------| | Description | Search for PE files by the contents of their company name field in the version information metadata. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-company-name:*enix`List (any of the values): `pe-company-name:[microsoft, ADOBE]` | | `pe-copyright` | | |-------------|------| | Description | Search for PE files by the contents of their legal copyright field in version information metadata. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-copyright:Copyright*`List (any of the values): `pe-copyright:[*Corporation, regsvr32]` | | `pe-description` | | |-------------|------| | Description | Search for PE files by the contents of their file description field in version information metadata. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-description:*proged`List (any of the values): `pe-description:[DisplaySwitch, WizardFramework]` | | `pe-export` (`exports`) | | |-------------|------| | Description | Search for PE files by exported symbol names. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-export:MS*`List (any of the values): `exports:[GetMemoSize, DeleteFile]` | | `pe-function` | | |-------------|------| | Description | Search for PE files by the name of the function that the PE file imports. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-function:RegEnum*`List (any of the values):`pe-function:[RegEnumKeyW, GetUserNameA]` | | `pe-import (imports)` | | |-------------|------| | Description | Search for PE files by the name of the dynamic link library that the PE file imports. Case-insensitive wildcard matching supported. | | Examples | Exact: `pe-import:URLMON.DLL`List (any of the values): `imports:[win*, url*]` | | `pe-language` | | |-------------|------| | Description | Find PE files by languages mentioned in the PE file resources. Case-insensitive wildcard matching supported. [Supported Languages for PE and Document Formats](#supported-languages-for-pe-and-document-formats). | | Examples | Exact: `pe-language:russian`List (any of the values): `pe-language:[eng*, Russian]` | | `pe-original-name` | | |-------------|------| | Description | Search for PE files by the contents of their file description field in version information metadata, and any other fields using the original name of the file. The keyword can be used to investigate how the file was named during compilation. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-original-name:crack*`List (any of the values): `pe-original-name:[*install.exe, "sample doc.exe"]` | | `pe-overlay-sha1` (`pe-overlay-hash`) | | |-------------|------| | Description | Find PE files by the SHA1 hash calculated for their overlay part. Overlay hashes are calculated by Spectra Core to better represent the true boundary of the file region. Users should use hash values calculated by ReversingLabs products with this keyword. Keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `pe-overlay-sha1:4b4a2436b827d42b204b1f112b45d7a6d1b7ca52`List (any of the values): `pe-overlay-sha1:[, , ]` | | `pe-product-name` | | |-------------|------| | Description | Search for PE files by the contents of their product name field in version information metadata. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-product-name:*shop`List (any of the values):`pe-product-name:[Firefox, "Microsoft Word"]` | | `pe-resource` | | |-------------|------| | Description | Search for PE files by name or type of resources they contain. Case-insensitive wildcard matching supported. | | Examples | Exact: `pe-resource:Properties`List (any of the values): `pe-resource:[Tcpview, Aboutbox]` | | `pe-resource-sha1` (`pe-resource-hash`) | | |-------------|------| | Description | Find PE files by the SHA1 hash calculated for their resources part. Keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `pe-resource-sha1:4260284ce14278c397aaf6f389c1609b0ab0ce51`List (any of the values): `pe-resource-sha1:[, ]` | | `pe-section-count` | | |-------------|------| | Description | Search for PE files by the count of sections they contain. The keyword accepts only integer values. | | Examples | Exact: `pe-section-count:15`Range: `pe-section-count:[2 TO 10]`More than: `pe-section-count:[5 TO *]` | | `pe-section-name` | | |-------------|------| | Description | Search for PE files by names of the sections they contain. The maximum section name length is 8 characters. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-section-name:*rdata`List (any of the values): `pe-section-name:[.Rdata, .Ndata, *rsrc]` | | `pe-section-sha1` (`pe-section-hash`) | | |-------------|------| | Description | Find PE files by the SHA1 hash calculated for their section part. Section hashes are calculated by Spectra Core to better represent the true boundary of the file region. Users should use hash values calculated by ReversingLabs products with this keyword. Keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `pe-section-sha1:7640a007e39b487bf1dbbde6487724faa131f6a8`List (any of the values): `pe-section-sha1:[, , ]` | | `pe-timestamp` (`pets`) | | |-------------|------| | Description | Search for a PE file by the date when it was compiled. Supported time format is UTC timestamp. | | Examples | Exact: `pets:2017-06-26T00:00:00Z`Range (newer than): `pets:[2018-03-06T10:57:29Z TO *]` | | `sampletype` (`filetype`, `type`, `format`) | | |-------------|------| | Description | Search for files by type as detected by Spectra Core. Case-insensitive wildcard matching supported. `Appendix B - Supported Sample Types`_ | | Examples | Exact: `sampletype:Image/None`List (any of the values): `type:[elf*,macho*]` | | `sha1` | | |-------------|------| | Description | String of hexadecimal digits representing a SHA-1 hash of the file. Keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `sha1:f1a62a7092e49577206b7361bf1a7ff0776bb6a4`List (any of the values):`sha1:[, ]` | | `sha256` | | |-------------|------| | Description | String of hexadecimal digits representing a SHA-256 hash of the file sample. Keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `sha256:f35a3(...)1d2d5`List (any of the values): `sha256:[, ]` | | `signer-valid-from` (`cert-valid-from`) | | |-------------|------| | Description | Search for files that have been signed by certificates valid from a specific time. | | Examples | Range (newer than): `signer-valid-from:[2018-03-06T10:57:29Z TO *]` | | `signer-valid-to` (`cert-valid-to`) | | |-------------|------| | Description | Search for files that have been signed by certificates valid to a specific time. | | Examples | Range (newer than): `signer-valid-to:[2018-03-06T10:57:29Z TO *]` | | `similar-to` | | |-------------|------| | Description | Search for files that are functionally similar to the requested file hash. Functionally similar files are defined by RHA (ReversingLabs Hashing Algorithm) that identifies code similarity between unknown samples and previously seen malware samples. All hash types (MD5, SHA1, SHA256) can be used with this keyword. Only one similar-to keyword can be used in a single query. The keyword is case-sensitive and doesn't support wildcards. | | Examples | Exact: `similar-to: ` | | `size` | | |-------------|------| | Description | Search for files by size (in bytes). Accepts integers up to 2147483647. | | Examples | Exact: `size:30000`Range: `size:[1000 TO 50000]`Greater than: `size:[500000 TO *]` | | `software-author` | | |-------------|------| | Description | Search for software packages by their author/publisher. | | Examples | Exact: `software-author:"James Newton-King"`List (any of the values): `software-author:["Amazon Web Services", Microsoft]` | | `software-description` | | |-------------|------| | Description | Search for software packages by their description. | | Examples | Exact: `software-description:"This package consists of multiple activities that simplify the processes in Excel."` | | `software-package` | | |-------------|------| | Description | Search for specific software packages. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `software-package:tidal`List (any of the values): `software-package:[tidal, "AWSSDK.WorkLink"]` | | `ssdeep` | | |-------------|------| | Description | Search for files with similar SSDEEP fuzzy hash values. Returns up to 100 closest matches with a similarity score. This keyword cannot be combined with other keywords or sort options. The time range filter is not available for this search type. | | Examples | Exact: `ssdeep:` | | `submissions` | | |-------------|------| | Description | Search for files by the amount of times they have been submitted for analysis. The keyword accepts only integer values. | | Examples | Exact: `submissions:3`Greater than: `submissions:[3 TO *]`Less than: `submissions:[* TO 4]` | | `tag` | | |-------------|------| | Description | Search for files by metadata tags generated by Spectra Core. Tags identify interesting properties of a sample, such as being packed, password-protected, or digitally signed. [Supported Tags](#supported-tags). | | Examples | Exact: `tag:packed`List (any of the values): `tag:[capability-execution, cert, crypto]` | | `tag-yara` | | |-------------|------| | Description | YARA supports adding custom tags to rules. Files that match those rules get automatically tagged after analysis. This keyword looks for files tagged by YARA rules, including those that were classified by YARA tags ("malicious" and "suspicious"). Case-insensitive wildcard matching is supported. Note that changes to YARA tags are not immediately reflected in search results. For example, if a tag is removed from a YARA rule, it will still return search results until files that match the rule are reanalyzed with Spectra Core. | | Examples | Exact: `tag-yara:malicious`List (any of the values): `tag-yara:[malicious, suspicious]` | | `taggant-name` | | |-------------|------| | Description | Search for PE files by name of the packer that was used to pack them. Taggant is a technology that guarantees the packed file came from a reliable source. Case-insensitive wildcard matching supported. | | Examples | Exact: `taggant-name:themida`List (any of the values): `taggant-name:[enigma*, vmprotect*]` | | `taggant-valid-from` | | |-------------|------| | Description | Search for files by the time it was signed using taggant. | | Examples | Range (newer than): `taggant-valid-from:[2018-03-06T10:57:29Z TO *]` | | `taggant-valid-to` | | |-------------|------| | Description | Search for files by the expiry time provided by taggant. | | Examples | Range (newer than): `taggant-valid-to:[2018-03-06T10:57:29Z TO *]` | | `third-party-library` | | |-------------|------| | Description | Search for PE files by the name(s) of third-party libraries they contain. Case-insensitive wildcard matching is supported. | | Examples | Exact: `third-party-library:Microsoft.WindowsAPICodePack-Core`List (any of the values): `third-party-library:[*oak-json*, Microsoft.Web.WebJobs*]` | | `third-party-publisher` | | |-------------|------| | Description | Search for PE files by publishers of the third-party libraries found in the files. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `third-party-publisher:Microsoft*`List (any of the values): `third-party-publisher:[Microsoft*, "Xamarin Inc."]` | | `tlsh` | | |-------------|------| | Description | Search for files with similar TLSH values. Returns up to 100 closest matches with a similarity score. Hovering over a TLSH similarity score displays the original TLSH distance value. This keyword cannot be combined with other keywords or sort options. The time range filter is not available for this search type. | | Examples | Exact: `tlsh:` | | `threatlevel` | | |-------------|------| | Description | Search for files by ReversingLabs scale of threat severity. Higher number indicates higher severity. Accepted values are 0-5. | | Examples | Exact: `threatlevel:3`Greater than: `threatlevel:[2 TO *]`Range: `threatlevel:[0 TO 3]`List (any of the values): `threatlevel:[2, 3]` | | `threatname` | | |-------------|------| | Description | Search for files by malware threat name according to [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). Case-insensitive wildcard matching supported. | | Examples | Exact: `threatname:Win32.PUA.Casonline`List (any of the values):`threatname:["WIN32.PUA.casino eldorado", *crytex]` | | `trustfactor` | | |-------------|------| | Description | Search for files by the ReversingLabs trust factor. Trust factor indicates the trustworthiness of files. Lower number means higher trust. Accepted values are 0-5. | | Examples | Exact: `trustfactor:1`List (any of the values): `trustfactor:[4, 5]`Range: `trustfactor:[1 TO 3]`Greater than: `trustfactor:[3 TO *]` | | `upload-source` | | |-------------|------| | Description | Search for samples that were uploaded with a specific source parameter. Possible sources: `s3`, `fileshare`, `azure-data-lake`, `smtp`, `abusebox`, `icap-proxy`, `falcon`, `api`, `rlsdk` | | Examples | `upload-source:api`, `upload-source:s3` | | `upload-source-tag` | | |-------------|------| | Description | Search for samples uploaded with a specific user-defined source tag. | | Examples | `upload-source-tag:myapp`, `upload-source-tag:myemail*` | | `uri-config` (`c2`) | | |-------------|------| | Description | Malware configuration C&C (Command & Control), extracted by Spectra Core. C&C infrastructure is used to control malware, particularly botnets. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `c2:*dns*`List (any of the values): `uri-config:[dydns.org, hldns.ru]` | | `uri-dynamic` | | |-------------|------| | Description | Search for files by URI strings (URLs, domains) detected by ReversingLabs Dynamic Services. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `uri-dynamic:mozilla.org*`List (any of the values): `uri-dynamic:[*.tor,*.onion,*.exit]` | | `uri-source` (`itw`) | | |-------------|------| | Description | Search for files by the URI source from which they were downloaded. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `uri-source:*warez*`List (any of the values): `itw:[softonic.com, *cnet.com]` | | `uri-static` | | |-------------|------| | Description | Search for files by URI strings (URLs, domains) detected by Spectra Core. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `uri-static:mozilla.org*`List (any of the values): `uri-static:[*.tor,*.onion,*.exit]` | | `vertical` | | |-------------|------| | Description | Search for files by the type of vertical feed in which they were found. Case-insensitive wildcard matching is supported. | | Examples | Exact: `vertical:ransomware`List (any of the values): `vertical:[ransomware,apt,financial]` | ### Supported File Types and Subtypes - [Native files and subtypes](/General/SpectraCore/report-section/) - [Native binary file types and identifications](/General/SpectraCore/report-native-binary/) - [Native PE file types and identifications](/General/SpectraCore/report-native-pe/) - [Native PE SFX file types and identifications](/General/SpectraCore/report-native-pe-sfx/) - [Native multimedia file types and identifications](/General/SpectraCore/report-native-multimedia/) - [Native text file types and identifications](/General/SpectraCore/report-native-text/) - [Native ELF file types and identifications](/General/SpectraCore/report-native-elf/) - [Native ELF SFX file types and identifications](/General/SpectraCore/report-native-elf-sfx/) - [Native script file types and identifications](/General/SpectraCore/report-native-script/) - [Verified software and package identities](/General/SpectraCore/appid-software/) - [Known vulnerabilities](/General/SpectraCore/cve-list/) - [Supported unpacking format list](/General/SpectraCore/report-unpacking/) - [Spectra Core certificate trust store](/General/SpectraCore/cert-trust-store/) ### Supported Tags See the complete list of [supported tags](/General/SpectraCore/core-tags/). ### Indicators See the complete list of [Spectra Core Indicators](/General/SpectraCore/indicators/). ### Supported Languages for PE and Document Formats | | | | | -------------------------- | --------------------------- | ----------------------- | | afrikaans | english belize | kannada | | albanian | english can | kashmiri india | | arabic algeria | english caribbean | kashmiri sasia | | arabic bahrain | english eire | kashmiri | | arabic egypt | english jamaica | kazak | | arabic iraq | english nz | konkani | | arabic jordan | english philippines | korean | | arabic kuwait | english south africa | korean | | arabic lebanon | english trinidad | kyrgyz | | arabic libya | english uk | latvian | | arabic morocco | english us | lithuanian classic | | arabic oman | english zimbabwe | lithuanian | | arabic qatar | english | lithuanian | | arabic saudi arabia | esperanto | macedonian | | arabic syria | estonian | malay brunei darussalam | | arabic tunisia | faeroese | malay malaysia | | arabic uae | farsi | malay | | arabic yemen | finnish | malayalam | | arabic | french belgian | maltese | | armenian | french canadian | manipuri | | assamese | french luxembourg | maori | | azeri cyrillic | french monaco | marathi | | azeri latin | french swiss | mongolian | | azeri | french | nepali india | | basque | french | nepali | | belarusian | gaelic manx gaelic scottish | neutral | | bengali | gaelic | norwegian bokmal | | breton | gaelic | norwegian nynorsk | | bulgarian | galician | norwegian | | catalan | georgian | oriya | | chinese hongkong | german austrian | polish | | chinese macau | german liechtenstein | portuguese brazilian | | chinese simplified | german luxembourg | portuguese | | chinese singapore | german swiss | portuguese | | chinese traditional | german | punjabi | | chinese | german | rhaeto_romance | | cornish | greek | romanian moldavia | | croatian | gujarati | romanian | | croatian | hebrew | romanian | | czech | hindi | russian moldavia | | danish | hungarian | russian | | default | icelandic | russian | | divehi | indonesian | saami | | dutch belgian | invariant | sanskrit | | dutch surinam | italian swiss | serbian cyrillic | | dutch | italian | serbian latin | | dutch | italian | serbian | | english aus | japanese | sindhi | | slovak | spanish peru | tswana | | slovenian | spanish puerto rico | turkish | | sorbian | spanish uruguay | ukrainian | | spanish argentina | spanish venezuela | urdu india | | spanish bolivia | spanish | urdu pakistan | | spanish chile | spanish | urdu | | spanish colombia | sutu | uzbek cyrillic | | spanish costa rica | swahili | uzbek latin | | spanish dominican republic | swedish finland | uzbek | | spanish ecuador | swedish | venda | | spanish el salvador | swedish | vietnamese | | spanish guatemala | syriac | walon | | spanish honduras | sys default | welsh | | spanish mexican | tamil | xhosa | | spanish modern | tatar | zulu | | spanish nicaragua | telugu | | | spanish panama | thai | | | spanish paraguay | tsonga | | --- ## Discussion The *Discussion* page displays the comments that have been added to a sample, either by the user who uploaded it or by other users. The appliance can also automatically add comments to a sample; for example, when a user manually changes its classification. Users can add new comments and apply some basic formatting, as well as insert links into the comment text field. Another way to access the *Discussion* page for a sample is to click the *Comments* entry in the expanded details view on the uploads page. --- ## Dynamic Analysis Results Each dynamic analysis integration adds its own section to the Sample Details page. Depending on the service, you may find: - Screenshots from the sandbox execution, with a gallery view and slideshow option. - Dropped files and other artifacts (such as PCAPs and memory strings), available for download within the service's retention period. - Behavioral and network indicators of compromise (IoCs), including URIs, IP addresses, and domains seen during execution. - History of past analyses for the same sample, with the ability to download reports for each run. Each entry displays the configuration used for that analysis, including platform, locale, and geolocation, with a tooltip showing additional details such as installed software. - Interactive report tabs showing processes, network activity, file system changes, registry modifications, and other runtime behavior. - Links to full reports in the service's native interface. - Export options to generate HTML or PDF reports (where supported). Dynamic analysis services must be configured by the appliance administrator. For more information, see [Analysis services](../Analysis-services/index.md). --- ## Extracted Files The *Extracted Files* page allows browsing through the entire hierarchy of files extracted from a sample. Below the Extracted Files page link in the sidebar, all extracted files are broken down by their classification. The Spectra Analyze performs recursive sample analysis where each file extracted from a sample is analyzed separately. The “parent” file then inherits classification (for example, malicious) if the “child” file is deemed malicious. This is also known as **classification propagation**. There are two views for extracted files: 1. Breadcrumb view. 2. Flat view. Both views have options for filtering and exporting, while the flat view has additional filters (name, threat, and format). The **Export** menu contains options to export the whole page or just the files extracted from a sample. For the **Selected** option to become available, one or more files on the page have to be selected. To export multiple pages of results, browse pages one by one and manually export them. Data can be exported as CSV, JSON or XML. To copy only the file hashes for the desired set of extracted files, the menu contains options to copy SHA1, SHA256 and MD5 hashes to the clipboard. Hashes are delimited by a whitespace, so that they can be directly pasted into the search bar. The exported file can contain one or more of the following columns. They can be enabled in the **Export** menu, under **Show more Export options** - **Files** - the number of files extracted from a sample (if the sample is a container). - **Format** - file format of each file in the results grid. - **Name** - extracted file name - **Time** - timestamp when a file was extracted - **Threat** - detected threat name for malicious and suspicious files, formatted according to ReversingLabs Malware Naming Standard. - **Size** - indicates the size of a file. - **SHA256, MD5** - additional file hashes that can be included in the exported file. The SHA1 hash is always included by default. The actions menu (☰) on the right contains options for downloading the sample, reclassifying and reanalyzing it, downloading unpacked files, downloading the top-most container of the selected file, and previewing the selected file (described in the [File Preview / Visualizations](./file-preview.md) section). When one or more files are selected, another actions menu (☰) appears highlighted to the right of the *Size* column. The menu contains the *Apply tags* and *Subscribe/Unsubscribe* options that can be used on files individually or in bulk. --- ## File Preview / Visualization There are several ways to preview a file: - by clicking the “Preview / Visualizations” link in the persistent sample summary above the navigation sidebar - from the Preview / Visualizations menu item in the sidebar - by clicking the *View HEX* option in the actions menu (☰) for a file on the *Extracted Files* page The file preview window contains three tabs: Hex, Structure and Entropy. For samples that matched a YARA rule, the Hex tab displays a YARA Matches filter, allowing the users to see the exact parts of the file that matched a specific YARA rule. Matches can be filtered by ruleset, rule or matched value. For supported image formats (PNG, JPG, GIF), an additional “View” will be present, allowing the users to preview the image. The appliance displays a warning message before allowing the image preview. ![Sample Details page showing the File Preview of a JPEG image](images/analyze-file-preview-image.png) A similar principle applies for other supported file formats, such as text documents and some script languages, where the code is displayed and can be beautified in the “PREVIEW” tab. ![Preview tab showing a section of code](images/analyze-file-preview.png) The *Entropy* tab visualizes the amount of entropy per each section of the file. Entropy is used to express “randomness” of the data in a file, or to measure predictability of any character in the file based on preceding character distribution. It is measured in a scale of 1 to 8, where 8 indicates highest entropy (highest measure of randomness). Typical user data, such as text files, rarely exhibits true randomness. On the other hand, encrypted or compressed files have a high measure of entropy. Therefore, entropy can be used to detect encryption and compression in suspicious files. The *Structure* tab visualizes the sections of a PE/PE+ file, such as PE header, Import table, and Overlay. It is possible to click the items in the list on the right (Virtual, Physical, Import table, Resource table…). Clicking an item redirects the user to the related section of the static analysis results (on the [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) page). --- ## Sample Details Page ## Types of Sample Details pages The Sample Details page presents all the available information about a sample. ### Local For local files, the information is collected from [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) static analysis results, Spectra Intelligence, dynamic analysis, and auxiliary analysis. Administrators can configure processing settings on the appliance (“Fast”, “Normal”, “Best”). This will impact which file formats will be fully processed and how much information will be presented for them. ![An image showing the local version of the Sample Summary page.](images/local.png) ### Cloud For samples that are not local, the scope of information will depend on the information provided by Spectra Intelligence. This is usually a subset of what is available for locally available files: a section of static analysis results and Spectra Intelligence scanning results. ![An image showing the cloud version of the Sample Summary page.](images/cloud.png) ### Network Threat Intelligence For URLs, domains and IP addresses, the appliance displays a different type of [sample details page focused on Network Threat Intelligence](./network-threat-intelligence.md). Additionally, information displayed on the Sample Details page differs based on the file type and classification status of each sample. ![An image showing the network threat intelligence version of the Sample Summary page.](images/url.png) ## Accessing Sample Details pages To access the Sample Details page for a sample, click the sample name in any of the following pages: - Search > Local, Cloud and Network results - Alerts - YARA > Local and local-retro ruleset matches The page consists of a navigation sidebar on the left and the main information area on the right. The sidebar can be collapsed or expanded by clicking the Show/Hide Panel button at the top of the sidebar. At the top of the navigation sidebar, there’s a persistent short summary showing information such as file hash, predicted filename (if it exists), file size, file type and format, and the **Preview / Visualizations** link to open the [File Preview Dialog](./file-preview.md). If the predicted filename exists, it can be found right below the file hash. The right section of the page is the main information area. Its contents change depending on the section selected in the navigation sidebar. The navigation sidebar provides quick access to all parts of the analysis report. The sidebar sections are collapsed by default, unless the Sample Details page is accessed via a specific link targeting a section in the sidebar. ## Main Page Actions When any item from the *File Analysis Detail* section is selected in the sidebar, the main information area will contain the following options in the top right of the page: ### Reanalyze Opens a floating dialog where users can reanalyze the submission with static, dynamic, or Spectra Intelligence analysis services. ### Similarity Contains advanced search pivot options to search for similar and [functionally similar](../search-page.md#analyzing-files-with-rha-similarity-algorithm) samples. ### Fetch & Analyze *Only on cloud samples.* Opens a dialog with analysis options for the user to choose from. Available analysis options are Static Analysis (always enabled and cannot be modified), Threat Intelligence (Spectra Intelligence), Cloud Sandbox (Dynamic Analysis), Interactive Analysis (interactive RL Cloud Sandbox session) Auxiliary Analysis, and Integration Analysis. This option will download the sample from the Spectra Intelligence cloud and analyze it locally on the appliance. If the sample is not available for download, the button will be disabled. ### Actions Button Depending on the [type](#types-of-sample-details-pages) of page, different choices are available. [Local](#local) samples: - PDF: - **Create PDF** option exports the whole *Summary* page as a PDF file. - **Export PDF (Short)** exports a shortened version, with the current [layout](#layouts-). PDF reports have a retention period of 30 minutes and will not reflect changes that happened after they were generated. If a sample’s classification changed after the PDF report was already created, users must wait for the retention period to expire before requesting it again or use the [PDF Report API](../API%20Documentation/pdf-report-api) endpoints to immediately generate and download an updated PDF report. **Warning: Because some PDF viewers automatically convert all strings with an `http[s]*` schema into clickable hyperlinks, it is not recommended to click any links in the generated PDF as they may lead to malicious content.** - Downloading samples (both extracted files and original samples) always uses ZIP archives (optionally password-protected, compatible with modern ZIP tools such as `unzip` 6.00+, Python's `zipfile`, 7-Zip, or `bsdtar`). - Sample management options: - editing classification or tags - subscribing and unsubscribing - deleting the sample - Reporting false positives or negatives: select **Report FP/FN** from the action menu on the summary page. Select either **False Positive** or **False Negative** as the report type, and optionally add a comment. The report automatically includes sample details, e.g. hash, classification, detection verdict. The dialog displays the email address where you will receive any updates regarding your report. **Info: This option is only available if [SMTP](./../Administration/configuration-update/configuration/#smtp) has been configured by an administrator. ** [Cloud](#cloud) samples: Only subscribing and unsubscribing is available. [URLs](#network-threat-intelligence): - Reanalyze - Reporting false positives or negatives (same as for local samples above) - Download options: - Payload: scraped content (if you used *local analysis* when submitting the URL). - Screenshots and dropped files: OS artifacts taken from [ReversingLabs Cloud Sandbox analysis](../Analysis-services/cloud-sandbox.md). The artifacts are in a 7z archive (password: `infected`). ### Layouts ⚙ **Info: This button is available only on local samples.** Click ⚙ and, from the drop-down list, select one of the preconfigured layouts of the report summary page. Optionally, click **Manage Layouts** to edit the existing layouts or create your own. For more information, see [Layouts Editor](/SpectraAnalyze/Administration/users-personalization/layouts-editor/). ------- --- ## Network Threat Intelligence Page ![description](images/url.png) The Network Threat Intelligence sample details pages are reserved for URLs, IP addresses and domains. They can be accessed by clicking any submission in the Network tab on the Search & Submissions Page, by clicking the Network Threat Intelligence link in the Sample Summary header of samples that correlate to some network resource, or by clicking the Network Threat Intelligence link that is displayed in the search box if the search query contains a single URI. The report summary section is an overview of all information available for a specific network resource, with additional information accessible using the sidebar menu. **Info: If Spectra Intelligence is unreachable, misconfigured, or not configured, the Network Threat Intelligence page displays a corresponding error message indicating the issue. Ensure your Spectra Intelligence account is properly configured to access network threat intelligence data. For more information, see [Spectra Intelligence configuration](../../Administration/configuration-update/configuration#spectra-intelligence).** The Network Threat Intelligence sidebar menu section contains the following items: - URL Analysis Contains the top threats found on the URL, as well as historical data for that URL. This data comes from the ReversingLabs [Network Threat Intelligence API](https://docs.reversinglabs.com/SpectraIntelligence/API/NetworkThreatIntel/tca-0403/). - Domain Analysis Contains the top threats found on the domain, as well as historical data for that domain. This data comes from the ReversingLabs [Domain Threat Intelligence API](https://docs.reversinglabs.com/SpectraIntelligence/API/NetworkThreatIntel/tca-0405/). - IP Analysis Contains the top threats found on the IP address, as well as historical data for that address. This data comes from the ReversingLabs [IP Threat Intelligence API](https://docs.reversinglabs.com/SpectraIntelligence/API/NetworkThreatIntel/tca-0406/). - Attribution Data Displays threat actor information and malware family insights for URLs, IPs, and domains. The page is organized into **Attribution** showing actor details, campaigns, and related IOCs, and **Malware Family Insights** showing malware family data and consolidated IOCs. For more details, see [Attribution Data](../sample-details-summary#attribution-data). - Screenshots & DOM The Screenshots & DOM section shows the raw Document Object Model (DOM) of the analyzed page, a list of extracted links grouped by type (link, script, image, other), and a screenshot of the page as it appeared during analysis. This allows users to review both the underlying code and the rendered view in a single place. ![description](images/url-dom-screenshot.png) In addition to network threat intelligence, users can also inspect previous ReversingLabs Cloud Sandbox dynamic analysis results, submit the network resource for (re)analysis, or interact with related files. --- ## Sample Details Summary ## Report Summary The **Report Summary** page highlights the most interesting information from the sample analysis report. It contains several sections with links to more detailed information. Many elements on the page are clickable and pivot to related pages or search queries, including threat names, file formats, file sizes, threat actors, and various indicators. The information on the Summary page will be different for every sample analyzed on the appliance, depending on the file type and classification status. For more information on interpreting the Sample Summary page, see [Interpreting analysis results](../index.md#interpreting-analysis-results). ### Report Summary Header ![Report Summary page header](images/local.png) The sample summary landing page starts with a header section. It is colored according to the sample’s classification, and it contains the most important information about the analyzed file. #### Risk score and threat name These tiles show the final classification of the sample. If a sample is goodware, its risk score will be in the 0 - 5 range. For suspicious and malicious files, the risk score will be in the 6 - 10 range. Risk scores depend on the severity of the threat. Read about the [ReversingLabs classification algorithm and risk score](/General/AnalysisAndClassification/Classification/#risk-score). Threat names follow our [malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). Clicking the threat name pivots to a search query for samples with the same threat name. If the threat is associated with a specific actor, that actor is displayed below the threat name and can be clicked to search for samples associated with that actor. #### Classification Reason The ReversingLabs classification algorithm uses a number of techniques and classifiers to detect threats. This tile shows the classifier that caused the final classification of the sample. More information about classification reasons can be found in the [Threat Classification Descriptions](./threat-classification-sources.md#threat-classification-descriptions) section. The list of classification reasons can be expanded by configuring [Risk Tolerance Levels](../Administration/users-personalization/risk-tolerance-levels.md). When risk tolerance is set up, a header indicator displays the **Risk Tolerance** level to inform users when classification results are influenced by risk tolerance. #### Detections Shows the number of Community Threat Detections and YARA matches for the sample. Click the tiles for more information. #### Community Threat Detections The number of community threat detections for this sample. #### YARA Matches The number of YARA rulesets that matched this sample. Visit the [YARA](../yara.md) chapter for more information on using YARA for threat hunting on Spectra Analyze. --------- Below the header, the page displays a list of available or configurable analysis methods for the sample. Methods can be clicked to open a menu with more details or analysis options. The method responsible for the sample's classification is highlighted in the final classification color and labeled as (decisive). Not all analysis methods can be decisive for the final sample classification. These are indicated by a (i) tooltip icon saying "Does not impact final classification." Analysis methods that are configured but not yet performed display an Analyze button, while unconfigured methods offer a link to their configuration page. ### Customizing the Report Summary page The remainder of the report summary page contains **data blocks**. Each data block contains a shortened report for a specific subject, such as sample attribution and threat intelligence, relationship graphs, or static analysis insights. The layout of data blocks is [configurable](/SpectraAnalyze/Administration/users-personalization/layouts-editor/). When you hover over the title of a data block, a short explanation is presented in the tooltip. ## Sample Details The **Sample Details** report section is broken into multiple tabs containing more information about the sample. Tab sections containing a large amount of entries will be paginated, and can be navigated using the arrow buttons in the top right corner of the section. ### Sample Details (tab) **Tags and Uploads** - lists a sample’s System and User Tags. Clicking the *Add* link opens a dialog where it is possible to add tags to the sample. Each tag is clickable and, when clicked, automatically performs a search query for samples based on the selected tag. **Capabilities** are displayed as a horizontal bar with icons, but only for supported file formats. The same information can be found in the *Static Analysis > FileType > Capabilities* section. **Hash values** for the sample. Hovering over any of the hashes displays a button to copy the hash to clipboard. SHA1 and SHA256 are shown by default, and the section can be expanded to show the remaining hashes (MD5, IMPHASH, SHA512, SSDEEP, TLSH). Hovering over hash values displays a tooltip button that can be clicked to copy the hash to the clipboard. **Similarity search** is available for TLSH and SSDEEP hashes. Click the similarity dropdown or the hash values to pivot to a search for samples with similar TLSH or SSDEEP values. Results display a similarity score. For TLSH results, hovering over the score displays the original TLSH distance value. The similarities section is also accessible from the left navigation. **Malware Description / Sample Description** shows a short textual summary (“Storyteller”) that describes the sample’s properties in a user-friendly language. The Storyteller can contain links provided by [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis). Each link leads to the Search & Submissions page, automatically performing a search query for samples based on the selected IOC. Links are also part of the exported PDF report (except those leading outside of the Spectra Analyze instance). **AI Summary** provides an LLM-generated overview covering the sample's behavior, classification, and executive summary. The summary displays extracted indicators of compromise (IoCs) in a structured format with pivot links. IOCs can be exported using the **Export** dropdown, which supports copying to clipboard, and exporting to CSV, JSON, and XML formats. Users can export all IOCs or a selected subset. Click **Refresh** to generate a new summary. This feature can be enabled or disabled by administrators via [AI Summary](../Administration/configuration-update/configuration.md#ai-summary). In addition to the Storyteller, this section contains the same malware family/type description from the Threat Intelligence Cards on the Advanced Search results page. Clicking the See Full Details link in the section header opens the Advanced Search results page for the sample’s threat name. If a sample is not malware, this section is titled Sample Description, and does not contain threat intelligence information about malware type or family. Storyteller text is present in all cases. **Comments** This section displays comments that have been added to a sample, either by the user who uploaded it or by other users. The appliance can also automatically add comments to a sample; for example, when a user manually changes its classification. ### How We Caught This **Prevalence** The graphs in the *Prevalence* section track the history of malware detections for the sample. The first graph, *Threat Reputation Scans*, shows the percentage of Threat Reputation scanners that have detected the malware over time. The *Malware Prevalence* graph shows how many overall samples have been detected as belonging to the malware family over the last N months, with the total number of unique samples shown underneath it. Hovering over the dots in the graph displays the exact dates and the amount of detections for each date. The *Total* amount displayed below the graph refers to the current month. The *Uploads* list shows the users who have uploaded the sample, and the number of times the sample has been uploaded. Clicking the number redirects to a search results page with all upload records of this particular sample. The next part of the *Summary* page contains information about malware prevalence and the results of the RHA File Similarity ([RHA File Similarity](../search-page.md#analyzing-files-with-rha-similarity-algorithm)) analysis, extracted files and the timeline. **File classifications** - displayed for samples that have been classified as suspicious or malicious. The *Threat Name* information indicates which threat names and classification statuses the sample has received from which classifier. The *File* information indicates the files within the sample that have been classified with each status and threat name. Clicking a link under *File* opens the Sample Details page for the selected file. ![Sample Details Summary showing the prevalence graph and the file similarity chart](images/analyze-sample-details-summary3.png) **Extracted Files** The *Extracted Files* section displays the information about the number and type of file(s) extracted from the sample. If a sample has no extracted files, this section is not displayed at all. If there have been issues while extracting the file, this is indicated by “Failed” and “Partial” status labels on the right side. **Additional sections** Additional sections may be present on the *Summary* page depending on the metadata extracted from the sample during analysis: - **Files with indicators** - **Files with signatures** - **Files with descriptions** - **YARA matches** - displayed if the sample matches any of the YARA rules on the appliance. Clicking a matched ruleset name pivots to the YARA Matches page filtered by the selected rule. - **Network references** - samples analyzed by dynamic analysis services can have a *Network connections* section. Clicking any link in the *File* column redirects to the *Interesting strings* section of the file associated with that network reference. ![Network References section of the Sample Details Summary page](images/analyze-uri-stats-network-references.png) - **Embedded scripts** - offers quick access to the contents of scripts found in the sample. The “eye” icon next to each script opens the floating [File Preview dialog](./file-preview.md). Clicking any of the links (embedded script names) in the *File* column opens the Sample Details page for that script. ![Embedded Scripts section of the Sample Details Summary page](images/analyze-sample-details-embedded-scripts.png) - **Malware configurations** - samples with detected malware configurations will have a section with URI stats. Clicking any of the URIs opens the search results page for that URI. ![Malware Configurations section of the Sample Details Summary page](images/analyze-uri-stats-malware-configurations.png) ### Analysis Results **ReversingLabs Analysis** is a collapsible table showing an overview of sample processing activities and results. The table records and displays the last time when the sample was (re)analyzed by ReversingLabs services - Static Analysis (Spectra Core), Threat Intelligence (Spectra Intelligence) and the ReversingLabs Cloud Sandbox (dynamic analysis). The method that resulted in the final classification of the sample will be highlighted in the appropriate classification color and marked as the **Decisive Classification Reason**. This table is collapsed by default, unless processing is still taking place, the sample is missing Spectra Intelligence results, or there is a special point of interest like the sample classification coming from a Local / Spectra Intelligence user override, an extracted file or from goodware overrides. When applicable, these special/additional classification reasons will be highlighted in a colored bar at the top of the table. Depending on the current status of the sample and the last analysis time, the table will offer useful suggestions, indicators and possible error messages. For example, it will display a message if Spectra Core was updated to a newer version since the last analysis, if the sample might have outdated Spectra Intelligence classification data, or if the file type is not supported by the Cloud Sandbox. The far right of the column contains context-dependent buttons for reanalyzing the sample, uploading it to the cloud, or accessing the Spectra Intelligence configuration page. Sample classification can be manually changed by clicking the **OVERRIDE** button in the top right corner of the table. See [Setting Custom Classifications](./threat-classification-sources.md#setting-custom-classification) for more information. If the appliance detects a possible discrepancy between the Spectra Core and Spectra Intelligence classification results, it will automatically submit the sample for reanalysis. This functionality is available only when the *Enable ReversingLabs File Reputation* option is active in **Administration ‣ Configuration ‣ Spectra Detect Processing Settings**. The classification will not necessarily change after reanalysis. Keep in mind that samples previously processed by Spectra Intelligence will still retain their analysis result in the table even after Spectra Intelligence configuration is disabled on the appliance **Integrations Analysis** is a collapsible table showing an overview of dynamic analysis services and results. Items in this section do not affect the final classification of the sample, but can be useful as additional sources of metadata. The table records and displays the last time when the sample was (re)analyzed by integrated dynamic analysis services, if any are configured. The far right of each table row contains context-dependent buttons for reanalyzing the sample or, if the service is not configured, accessing the configuration page for the respective service. **Classification Timeline** The *Timeline* provides a historical overview of activities performed on the sample. It records the dates when the sample was first seen by Spectra Intelligence and on the local appliance, when it was classified by Spectra Core, (re)analyzed by static or dynamic analysis services, and more. ### Attribution Data The Attribution Data page provides comprehensive threat intelligence about the malware family and threat actors associated with the analyzed sample. The page is organized into **Attribution** and **Malware Family Insights**. **Important: The information on this page is predominantly LLM-generated, indicated by the star icon next to the section title. Review the information for accuracy before relying on it.** ![Attribution data page](images/attribution-data.png) #### Attribution tab The Attribution tab displays threat actor information and related indicators. When a sample is attributed to multiple actors, you can switch between them using tabs or selectors. **Sample Attribution** Maps the sample to known threat actors and campaigns: - **Actor Name** - The threat actor or group attributed to the malware. - **Campaigns** - Known malicious campaigns associated with the sample. - **Victims** - Targeted entities or sectors. - **Vulnerabilities** - CVEs or weaknesses exploited by the malware. - **Sources** - Intelligence sources supporting the attribution. **Actor Insights** Displays detailed information about the threat actor, including an AI-generated actor image or a fallback image if no specific image is available, and country flags: - Actor description and operational history - Aliases used across different threat intelligence vendors - Country of origin with flag indicator (if known) - Group type (e.g., state-sponsored, cybercrime group, APT) - Known tactics employed by the actor **Actor-Related IOCs** A searchable and filterable table listing indicators of compromise (IOCs) linked to the actor, including IP addresses, domains, and other artifacts. The table includes: - Search bar for finding specific IOCs - Type filter for filtering by IOC type (Domain, IP, etc.) - Export dropdown for exporting selected or all IOCs in CSV or JSON format - Row selection for bulk actions **Actor-Related Campaigns** A table of campaigns attributed to the actor. Each campaign can be expanded to reveal additional details: - **Date** - When the campaign was active. - **Techniques** - Tactics and techniques used during the campaign. - **IOCs** - Associated indicators including hashes, URLs, IPs, and domains. **Actor-Related TTPs** A table of tactics, techniques, and procedures (TTPs) associated with the actor. Each entry includes: - **Name** - The technique or tool identifier. - **Description** - How the actor employs the technique. **Related Vulnerabilities** A list of vulnerabilities exploited by the actor. Each entry shows the CVE identifier and a brief description of how it was used. **Referenced Actors** Connections to other threat groups. **Sources** Intelligence reports and documentation used to generate the attribution data. #### Malware Family Insights tab The Malware Family Insights tab provides comprehensive information about the malware family: **Malware Family** Core identification details including threat name, aliases, first/last seen dates, current version, packer information, targeted operating systems, and industries. - **Detection Statistics** - Weekly ranking, total detected samples, and week-over-week detection trends. - **Top File Types** - Distribution of file formats commonly used by the malware family (e.g., PE executables, DLLs, archives, Office documents). - **Malware Family Prevalence** - Timeline graph showing detection activity over the past six months. - **Threat Description** - A detailed narrative explaining the malware's history, capabilities, infection vectors, persistence mechanisms, and communication protocols. - **References** - External sources and research publications for further reading. **Actor-Related IOCs** A consolidated searchable and filterable table of all IOCs related to actors for the given threat name. The table includes: - Search bar for finding specific IOCs - Type filter for filtering by IOC type (Domain, IP, etc.) - Export dropdown for exporting selected or all IOCs in CSV or JSON format - Row selection for bulk actions **Sources** Intelligence reports and documentation used to generate the malware family data. ### Relationship Graph The relationship graph visualizes connections between the analyzed sample and related entities such as extracted files, contacted URLs, extracted domains, contacted domains, and contacted IP addresses. Each node type is represented by a distinct icon, and relationships are shown through connecting lines. Clicking anywhere on the graph on the Sample Summary page opens the full Explore Relationship Graph page with the sample data loaded. The graph can be filtered and searched, with controls available at the top of the page. ### Network References The network references tab contains all URLs, IP addresses and domains found *in relation* to the sample. This includes network locations that the file attempted to visit during a dynamic analysis run, IP addresses found inside the sample during static analysis, as well as sources, or places where the URL was found. ### MITRE ATT&CK **MITRE ATT&CK** is a section mapping indicators detected by Spectra Core to MITRE threat IDs. This section can be displayed for all samples regardless of their classification status (malicious / suspicious / known / no threats found), as long as they have indicators that can be appropriately mapped to the ATT&CK framework. Samples without indicators will not have this section on their Sample Details page at all. The section lists MITRE tactics in the table header. MITRE techniques are grouped under each tactic. Every technique can be clicked to show Spectra Core indicators mapped to it. Clicking a technique pivots to a search query for samples with that attack technique. The table can be further filtered to show all techniques or just the triggered ones, and technique IDs can be either shown or hidden. --- ## Sources The **Sources** page displays different types of sources for the selected sample. Sources are categorized into tabs, each one showing relevant information about the origin of the sample. - **Spectra Intelligence**: a list of all locations from which the sample was retrieved, and the time and date of retrieval. If available, this tab shows additional information about the sample, such as versions or descriptions. - **Uploads**: submission details for files uploaded to Spectra Analyze, including submission user, timestamp, source file path, source tag, and connector configuration details. - **Network locations**: a list of all locations from which the sample was retrieved. - **Parents**: the top-level containers and direct parents that contain the relevant sample. --- ## Spectra Core - Static Analysis Results The *[Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis)* page visualizes the static analysis report for every sample. The information is organized into sections which can be expanded using the accordion menus. The amount of information and the available sections vary based on file type. ## File information and statistics The *Info* section displays basic information such as file type, predicted filename (if it exists), file size, and entropy; file validation; the set of hashes computed for the sample; as well as statistics about other files contained within the original sample. If there are any errors or warnings detected during sample analysis, they are listed as individual entries in this section. ## File type-specific information This section contains detailed information about the sample based on the metadata extracted by Spectra Core. As the name implies, the information in this section depends on the file type of the sample. In the example of an Application (Portable Executable), the following information may be included: ### Identity Application identity takes whitelisting and certificates into consideration and labels applications with their correct software versions. It removes the ambiguity left by source and certificate whitelisting as it can pinpoint the exact software release. Furthermore, it can identify the correct identity for software that isn’t typically signed or published on a reputable source. ### Capabilities Capabilities are actions the sample can perform without executing an application. Insight into capabilities is obtained exclusively through static analysis of the sample. **Tip: To find samples that exhibit specific capabilities, use the **tag** keyword in [Advanced Search](../advanced-search.md). For example, *tag:capability-cryptography* will find samples that can encrypt data. Consult the [full list of supported tags](../advanced-search.md#supported-tags).** ### Analysis Shows the security grade and detected security issues for the analyzed sample. Depending on the security issues, the sample can get one of the following grades: - Grade A. Best security grade. The application follows the latest standards and policies. - Grade B. Good security grade. The application has sufficient security mechanisms implemented, but does not have all the latest features enabled. - Grade C. Minor security issues detected. The application has some security mechanisms implemented, but is not considered safe to use in all environments. - Grade D. Major security issues detected. The application should only be executed in secured environments. - Grade E. Major security issues detected. The application should only be executed in highly secured environments. - Grade F. Major security issues detected. Consider the application unsafe to run. ### DOS Header Historical header that serves as a pointer to the *File Header* through *e_lfanew* entry. ### File Header Important entries in the *File Header* include: - Machine - target architecture for which the PE file was compiled - Time Date Stamp - date when the PE file was compiled - Characteristics – PE file attributes - Number of Sections, Number of Symbols ![Sample Details page with visible File Header](images/analyze-sample-details-header.png) ### Optional Header Describes elements such as import and export directories that make it possible to locate and link DLL libraries. Other entries provide structural information about the layout of the file, such as the alignment of its sections. ### Sections Describes each of the sections making up the file. Sections can contain code, initialized and uninitialized data, resources and any other data. The following information may be of particular interest to malware analysts: - Flags show whether the section contains executable code, can be read from, written to or has other properties - Hashes can be used to correlate with other files - Entropy can show if a section is encrypted or compressed **Note: **Physical Size** does not always match the raw size value in the PE header section. It is derived from actual loader behavior and the resulting bytes of the file as loaded into memory.** Section hashes are calculated using the Physical Size, which may differ from hashes computed with the raw size. ### Imports Contains an array of import directory entries; one entry for each DLL to which the file refers. Every entry can be expanded to reveal the list of symbols that are being imported. ### Resources Indicates what resources the file contains, together with all the details about them (such as type, language, and whole resource data hashes). The language can be an indicator of the machine locale settings used by the person who developed and/or compiled the file. Hashes can be used to look up and correlate which files contain the same resources. Additional information can include **version info, dynamic libraries, symbols, segments**, and more, depending on the file type. If the sample is an email message, the sections can include information about from, sender, and reply-to email addresses, email message subject and headers, as well as attachments (if there are any). If the sample is an image, EXIF metadata will be extracted and included in the sections (for example, camera make and model). For mobile applications, the sections can include information about the application package, activities, services, receivers, and permissions. Currently supported mobile platforms are iOS, Android, and Windows Phone. ### Software Packages Relevant information for files recognized as software packages, which are archive files containing an assortment of individual files or resources and related metadata (such as name, vendor, version number, version number) that work together to provide users with a particular functionality. For the full list of supported package formats, refer to [this article](https://docs.secure.software/concepts/language-coverage). ## Signatures The *Signatures* section contains tabbed information about signatures, digital certificates and their validation states reported by the Spectra Core engine, including the certificate trust chain with signer and counter-signer details. The chain of trust starts with a certificate authority and ends with the signer. Clicking any of the individual elements in the signer/counter signer chains will show more detailed information below. In case there are multiple signatures found, results will be paginated. ![Sample Details page showing a Certificate Trust Chain of a sample](images/analyze-sample-details-certificates.png) Spectra Core supports classifying samples based on digital certificate blacklists and whitelists. By default, it provides more than 300 CA (Certificate Authority) certificates in its certificate store. The certificate store is a set of trusted CA certificates imported from sources such as Microsoft Windows, Mozilla Firefox, and Apple, which are included in Spectra Core and, by extension, in the Spectra Analyze system. Samples classified on the basis of their certificates receive the “Classified by Digital Certificate” [threat description](./threat-classification-sources.md#threat-classification-descriptions). Spectra Analyze also provides information about certificate status. Check the **Sample Details > Static Analysis > Info > Validation** section to see how Spectra Core validated the certificate(s) for a sample. | Certificate Status | Detailed Status Description | | --------------------------- | ------------------------------------------------------------ | | **Valid certificate** | Any certificate with an intact digital certificate chain that confirms the integrity of the signed file. The hash within Signer Info matches the hash of the file contents. | | **Invalid certificate** | Any certificate with an intact digital certificate chain, but for which the certificate chain validation failed due to other reasons (e.g. because of attribute checks). Without a valid digital certificate chain, the integrity of the signed file cannot be validated. | | **Bad checksum** | The integrity of the signed file could not be verified, because the hash within Signer Info does not match the hash of the file contents. | | **Bad signature** | Any certificate with an intact digital certificate chain, but for which the signature validation failed. Without a valid signature, the integrity of the signed file cannot be validated. | | **Malformed certificate** | Any certificate that does not have an intact digital certificate chain. The digital certificate is corrupted or incomplete, but that doesn’t mean the file is also corrupted. Without a valid digital certificate chain, the integrity of the signed file cannot be validated. | | **Self-signed certificate** | A self-signed certificate is a certificate that is signed by the same entity whose identity it certifies. In other words, this is a certificate that is used to sign a file, but is its own CA (certificate authority), and doesn’t have a CA that issued it. If CA information is present, but not found within the Spectra Core certificate store, the CA will be considered plausible and files signed with it will be declared valid (i.e., they will not be considered as self-signed). | | **Impersonation attempt** | Any self-signed certificate is a candidate for an impersonation check. Impersonation means that the signer is trying to misrepresent itself as a trusted party, where “trusted party” is defined by the certificate whitelist. Any self-signed certificate that matches the common name of another certificate on the Spectra Core whitelist is marked as an impersonation attempt. | | **Expired certificate** | Any certificate with signing time information is checked for expiration. When the time on the local machine indicates that the certificate has passed its “valid to” date and time, the certificate is considered expired. The “Expired” certificate status is merely informative, and expired certificates cannot influence certificate classification. | | **Untrusted certificate** | Any valid certificate for which the digital certificate chain cannot be validated against a trusted CA. Untrusted certificates are valid certificates, but they cannot be whitelisted because their chain does not terminate with a CA in the Spectra Core certificate store. | **Tip: To find samples by their certificate status, use the **tag** keyword in [Advanced Search](../advanced-search.md). For example, *tag:cert-invalid* will find samples signed with invalid certificates. Consult the [full list of supported tags](../advanced-search.md#supported-tags).** ## Indicators Indicators are extracted by Spectra Core during static analysis and displayed as human-readable descriptions of sample behavior. There are many indicators that are common in regular applications, like opening files, writing to files, and so on. The full list of indicator IDs and their descriptions can be found [here](/General/SpectraCore/indicators/). The *Indicators* section shows what a sample is capable of doing, with more significant indicators listed first. If static analysis indicates that an application contains an encrypted executable or that it is capable of accessing passwords, those indicators will get much higher priority than if the application can just open files. The former indicators are more important in this context and not common at all in legitimate applications. Therefore, they will be listed before other indicators. ![img](images/analyze-sample-details-indicators.png) Spectra Analyze displays special icons next to indicators that contributed to the final classification by a Machine Learning model. This applies only when Machine Learning is among the engines that classified the file, and is limited to Worm, Ransomware, Keylogger, and Backdoor (RAT) malware types. This indicator is not be displayed if classification is propagated, or if Machine Learning is not on the list of engines used to classify the sample. **Tip: To find samples with specific indicators, use the **tag** keyword in [Advanced Search](../advanced-search.md). For example, *tag:indicator-macro* will find samples that contain or execute macros. Consult the [full list of supported tags](../advanced-search.md#supported-tags).** ## ATT&CK The ATT&CK section maps indicators detected by Spectra Core to MITRE threat IDs. This section can be displayed for all samples regardless of their classification status (malicious / suspicious / known / no threats found) as long as they have indicators that can be appropriately mapped to the ATT&CK framework. Samples without indicators will not have this section on their Sample Details page at all. MITRE tactics are listed as table columns, and MITRE techniques are grouped under each tactic. Every technique can be clicked to show Spectra Core indicators mapped to it. The same technique can be listed under multiple different tactics. The mapping is limited to indicators that Spectra Core can detect with static analysis, so it does not cover the full range of MITRE tactics and techniques, but only a subset of it. Buttons above the table can be used to filter Techniques to only those that were triggered, and to show or hide technique IDs. ## Classification If the sample has been classified, this section shows its status and a list of scanners that determined the classification. If the sample has been classified by a YARA rule, this section contains the relevant YARA ruleset metadata. More information on sample classification can be found on the [Sample Details Summary](./sample-details-summary.md) page. To find out more about classification methods and reasons, consult the [Threat Classification Descriptions](./threat-classification-sources.md#threat-classification-descriptions) chapter. ## Protection Shows the protection features with which this file was compiled, and other protection mechanisms that were detected while analyzing the file (such as cryptographic or compression algorithms). ## Strings and Interesting strings Spectra Analyze extracts all strings from samples and separates *Interesting strings* into their own section. Strings are considered interesting if they contain information related to network resources and addresses (for example IP addresses, HTTP, HTTPS, FTP or SSH). Interesting strings are usually found in binary files, documents and text files. If available, reputation statistics are displayed next to URIs in the *Interesting strings* section. In both sections related to strings, results can be searched with regular expression patterns and filtered by string length for more dynamic hunting. Additionally, Interesting Strings can be filtered by category (all, http, https) and by classification (all, malicious, suspicious, goodware, no threats found). Strings can be filtered by their origin. - CARVED - String is generically extracted from the file. - TABLE - String is found within a file format specific strings table. - DEEP - String is found within a compressed part of the file or a non-offset accessible location. Any of these strings can be deemed human readable by a ML model. This filter is available as a separate button. ![Sample Details showing string filtering options](images/analyze-filter-strings.png) Very long strings can exceed the display length and appear as if they are cut off. To see the entire string, click the **Show more** button. ## Tags When Spectra Core analyses a file, it assigns it different [tags](../system-and-user-tags.md) which help when searching for specific capabilities. ## Email If the analyzed file is an email, the structure extracted by Spectra Core will be presented on this page. This includes email headers (subject, sender, date...). The content of the email itself is available on the [preview page](file-preview.md). The attachments are available in the [extracted files](extracted-files.md) section. --- ## Threat Classification Sources In addition to classification from the [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) engine included in the Spectra Analyze appliance, the threat classification for samples comes from either the Spectra Intelligence service or an on-premises T1000 File Reputation Appliance. Appliance administrators should configure access to the desired reputation service (Spectra Intelligence or T1000) via the [System Configuration](/SpectraAnalyze/Administration/configuration-update/configuration/) page. **Only one of those services should be configured, not both. If both are configured, the T1000 service will be used by default.** If the appliance is not connected to the Spectra Intelligence or to the T1000 appliance, then no classification or AV scan information (malicious, suspicious, known) will be present. However, classifications will still come from Spectra Core (RHA1, signatures and so forth), which is locally installed on the appliance. When either the Spectra Intelligence or the T1000 reputation service is properly configured, the sample threat status will incorporate data from Spectra Core and from the configured reputation service. ## Threat Classification Descriptions The following is a list of all possible classification reasons a sample can have. The classification reason specifies which technology detected this threat. It is visible on the [landing page of the Sample Summary page](./sample-details-summary.md) and in the expanded row on the Search & Submissions page. Files will usually have multiple detections from more than one classifier, but the classification reason tile on the Sample Summary page always shows the one that produced the final classification. **Note: The list of classification reasons can be expanded by configuring [Risk Tolerance Levels](../Administration/users-personalization/risk-tolerance-levels.md).** ### **Classified by: Threat Reputation** The sample was classified by the Threat Reputation scanner. ### **Classified by: Certificate Validation** Digital signatures include a file integrity validation hash. Validating digital certificates is a multi-step process. Valid certificates have a properly formed digital certificate chain and pass file hash integrity validation. Spectra Core detects signed file tampering and is capable of detecting signer impersonation, certificate malformation and content modification. Failing to comply with any of these checks will classify the file as at least suspicious. The displayed threat name will reflect the detected type of the tampering attempt. When a self-signed certificate is trying to misrepresent itself and emulates a trusted certificate, the displayed threat name will be `{Platform}.Certificate.Impersonation`. On the other hand, when a file fails integrity validation, the threat name can appear as `{Platform}.Certificate.Invalid` or `{Platform}.Certificate.Malformed`. In case of valid signing time, with signature that is created after signing certificate is already expired or revoked by Certificate Authority, threat name will be `{Platform}.Certificate.SignedAfterExpiration` and `{Platform}.Certificate.SignedAfterRevocation` respectively. ### **Classified by: Threat Signature** Rules, Indicators, Classifications and Capabilities (RICC) is an offline database that applies static analysis rules to analyzed content. Part of its responsibility is to classify files based on signatures and unique metadata properties found only in malicious files. Two such classification technologies are deployed through RICC. Byte Pattern Matches as signatures that detect known threats, and Malware Artifacts Classifier that looks at the metadata for malware clues. Both of these technologies correlate the detection to a named threat. In terms of classification, they are the most specific detection technologies within the engine, and are reserved to be used only for precise threat detections. ### **Classified by: Format Structure** The sample was classified based on the format structure of the file determined by Spectra Core. Spectra Core contains a large collection of file format parsers. Some file formats are used exclusively by malware, while other, “legit” file formats, can be structured in a suspicious manner. Samples containing those file formats receive this classification. Unlike file or threat reputation results, this classification method is not constantly updated. New information and signatures for this method can only be obtained by updating the entire appliance to a new release. ### **Classified by: Email Contents** Email messages are stored in structured file formats. This encapsulation includes email headers, message body and a number of attachments. Any of these components can be malicious and therefore needs to be inspected. Email headers are checked for identity misrepresentation that relates to phishing and BEC attacks. Message bodies are inspected for URLs that could lead to phishing and malware downloads. Attachments are decomposed through static analysis in search for malicious code. Additionally, any attached file is also inspected for embedded URLs that themselves are checked for malicious intent. When this technology detects phishing, it will name the threat as `Email.Phishing.{ServiceName}`. The following services can be identified: Adobe, Amazon, AmericanExpress, Apple, BankOfAmerica, ChaseBank, DocuSign, Dropbox, Ebay, Facebook, Google, LinkedIn, Microsoft, Netflix, PayPal, Twitter and WhatsApp. If the email was detected as malicious due to embedded URL, the threat name can appear as `Email.Hyperlink.Homoglyph` ### **Classified by: Exploit Signature** During engine analysis, parsed format structure is validated and any departures from specification are reported. Detected malformations are automatically mapped back to exploits that are known to abuse format parsing bugs. Exploit detectors are a special kind of signature detection. They are implemented individually for each supported format, and are made to detect known exploits. Exploit detection is available for images, documents, archives and mobile application package formats. When an exploit is detected within an image format, the reported threat name can be `{Platform}.Exploit.CVE-{ID}`. ### **Classified by: File Contents** During automated file extraction, the supported formats are decomposed recursively. Unexpected format combinations can be discovered during extraction. For example, documents and multimedia files should never embed executable files. If such unusual format combinations are discovered, the engine will declare those files as suspicious with the following threat name: `{Platform}.Format.Content`. ### **Classified by: Explainable Machine Learning** Machine learning is a predictive detection technology. Explainable Machine Learning, a concept unique to ReversingLabs, bases its classification on the principles of expandability, transparency and relevancy. Based solely on human readable indicators, machine learning models detect specific threat types and can differentiate between threats and benign files. When the machine learning model predicts that a threat type falls into a recognized category, it will name the threat as `Win[32|64].{ThreatType}.Heuristic`. However, if the model is certain that the file is a threat, but can’t place it into a threat category, it will name the threat as `Win[32|64].Malware.Heuristic`. Machine learning models are made to detect Windows executable and fileless malware types. ### **Classified by: File Similarity** ReversingLabs Hashing Algorithm (RHA1) is a proprietary functional file similarity algorithm. It is primarily designed for executable formats, and as such it is specifically implemented for each supported format. RHA1 converts functional file features, both the code and its layout, to four precision level hashes. Each precision level represents a 25% increase in similarity between files that share the same hash at the same precision level. Lowest precision is 25% and highest is a 100%. Spectra Core comes with an offline database of blacklisted RHA1 hashes. This technology is capable of detecting polymorphic threats and their variants. Even though threats are detected based on similarity, they are still named after the threat the file is most similar to. ### **Classified by: Embedded HyperLink** Many file formats enable active linking to content hosted on remote servers. These are commonly referred to as hyperlinks or uniform resource locators (URL). Since the active content is on a remote server, it can change at any time. However, some URLs themselves do contain information that helps to infer the content type to which they are pointing to. With static analysis, Spectra Core can detect various kinds of deceptive links without visiting the content targeted by the URL. Attacker techniques such as typosquatting, domain spoofing, and homoglyphs are detected for more than 5000 popular websites. In addition to deceptive links, the solution includes an offline database of blacklisted domains and known malicious URL patterns. When the engine finds an embedded link that points to a blacklisted domain, it will name the threat as `{Platform}.Hyperlink.Blacklisted`. ### **Classified by: Goodware Override** Any files extracted from a parent and whitelisted by a high trust certificate, source or user override can no longer be classified as malicious or suspicious. Goodware Overrides propagate from parents to children. The goodware overrides will not apply if the extracted file is found by itself (for example, if an extracted file is rescanned without its container). ### **Classified by: Extracted Files** The classification of certain samples originates from children samples extracted during analysis. It propagates from children to the parent, for example from a malicious executable file to the zip archive where it originated from. If this is the case, the description beneath the classification will highlight that it was based on an extracted file. ### **Classified by: YARA Rule** The sample was classified based on YARA rules provided by ReversingLabs or by the user. ### **Classified by: NextGen Antivirus** Sample was classified by an antivirus engine considered to be next-generation, such as those that use machine learning. ### **Classified by: File Reputation** The sample was classified by Threat Intelligence Database. It can be obtained from a trusted source, or it was unpacked from the file originating from a trusted source. ### **Classified by: User Classification** The sample has been manually classified locally or in the Spectra Intelligence cloud, overriding any classification from ReversingLabs. Local classifications only apply to the Spectra Analyze instance they are set on, while cloud overrides get synchronized to other ReversingLabs appliances using the same Spectra Intelligence account and to other cloud accounts with the matching company username segment (u/**company**/user) ### **Classified by: Spectra Core Classification** The sample was classified by the Spectra Core static analysis engine. ### **Classified by: Certificate Reputation** Applications, archives, documents and software packages can all be digitally signed. These signatures guarantee integrity and certify the origin of the content they are signing. Spectra Core comes with a customizable list of signers, or identities, that own recognized certificates. These identities can be added to either the Spectra Core certificate blacklist or whitelist. The former will declare signed content as malicious, while the latter will classify analyzed content as goodware. When a file is declared to be malicious due to a blacklisted certificate, the threat name will be displayed as `{Platform}.Certificate.Blacklisted` ### **Classified by: Sandbox** The sample was classified by the ReversingLabs Cloud Sandbox. ## Setting Custom Classification Users can manually override a sample’s classification: - by selecting the **Set classification** option in the actions menu (☰) in the [Results List](../search-page.md#results-list) list, or in the *ACTIONS* menu on the [Sample Details](./sample-details-summary.md) page - by selecting the **OVERRIDE** option in the *ReversingLabs Analysis Table* on the Sample Details page Selecting either of those options opens the *Set classification* dialog. It consists of two tabs: **Spectra Intelligence** and **Local**. They are identical in design, but behave differently. Local classification overrides persist only on the current Spectra Analyze appliance, they are not propagated to any other service or Spectra Analyze instance. Spectra Intelligence overrides get synchronized to other ReversingLabs appliances using the same Spectra Intelligence account, but also to other Spectra Intelligence accounts with the matching company username segment (u/**company**/user). Samples that have both the local and the Spectra Intelligence override will be classified according to the local override. Users can change the sample classification by modifying the threat status and trust factor values of the sample. Clicking **Save** in the dialog applies the new classification to the sample. ![Set Classification dialog with options to modify the risk score](images/analyze-set-classification.png) For every sample classified in this way, manual classification changes are recorded in the **Sample Details > Timeline** section. Any user of the current Spectra Analyze instance can manually change the classification of any file submitted to the appliance, regardless of who submitted the file. For both local and Spectra Intelligence overrides, users who wish to closely keep track of classification changes to their important files should [create an alert subscription](../alerts.md#creating-a-new-alert-subscription) to get notified as soon as there is a change (by another user or by any of the ReversingLabs classification methods). --- ## Threat Intelligence (Spectra Intelligence) The *Cloud Threat Intelligence > Community Threat Detections* page contains statistics about malware detection for the sample based on the results of Threat Reputation scanning in the ReversingLabs Spectra Intelligence system. The information is obtained from a number of AV engines and organized by the time and date of each AV scan. The upper half of the page contains a graph that shows how malware detections for the sample changed over time. More specifically, the graph indicates changes in the maximum detection rate for the sample. The graph always displays the same time range regardless of the currently selected scan date. The lower half of the page contains a list of all AV vendors used to scan the sample for each recorded scan date. If an AV engine produced a detection, the detected threat name is listed next to the AV vendor name. Every result on this page is clickable and, when clicked, automatically performs a search query. Users can navigate between recorded scan dates by clicking the arrows above the list of AV vendors, and compare the differences between each scan. The number of AV engines used can differ between recorded scan dates, depending on which vendors/engines were available at the time of each scan. Text formatting in the list of AV vendors also carries important information. - If the name of an AV vendor is greyed out, that indicates their AV engine(s) did not produce a detection for the sample. This can happen for a variety of reasons (e.g. the AV engine does not support the file format of the sample, or it did not have the relevant signature at the time of the scan). In case of goodware, this is the intended behavior. - If there is a number next to the AV vendor name, that indicates how many AV engines of that vendor were used to scan the sample. - If an AV vendor name is displayed above the black line in the list, that indicates their AV engines are considered next-generation (such as those that use machine learning). - If a detection name is red, that indicates it is a new detection for the AV vendor. This means the AV vendor did not produce a detection for the sample in any of the previous scans. - If a detection name is red with another name crossed-out next to it, that indicates the detection name has changed in the currently selected scan. This means the AV vendor previously produced a different detection for the sample. The crossed-out detection name is the old name, and the red detection name is new. - If a detection name is crossed-out, but there is no other name next to it, that indicates the AV vendor is no longer producing detections for that particular threat. Some AV vendors indicate that a threat has been detected in a sample, but they do not expose the full threat name. Their detection still influences the final classification of the sample, and in some cases affects the final threat name assigned to the sample. **Tip: The information from the Spectra Intelligence section can be used with [Advanced Search](../advanced-search.md) keywords for targeted malware hunting. Use the **av-detection** keyword with any of the detected threat names (*av-detection: Adware/Genieo!OSX*), or specific AV vendor keywords with the threat name detected by a particular vendor (*av-[vendor]/Clovis-A*). To find samples by the number of Community Threat Detections, use the **antivirus** keyword. Consult the [full list of supported search keywords](../advanced-search.md#supported-search-keywords).** ### File Similarity The *Cloud Threat Intelligence > File Similarity* section of the sidebar displays the amount of [functionally similar samples](../search-page.md#analyzing-files-with-rha-similarity-algorithm), grouped by their threat status. Clicking the links in the File Similarity section redirects to the list of similar samples, where it is possible to download them to the appliance as described in the [Downloading Files from Spectra Intelligence](../search-page.md#downloading-files-from-spectra-intelligence) section. --- ## YARA Retroactive Hunting The YARA Retroactive Hunting feature is an extension of the already powerful yara capabilities available on the Spectra Analyze appliance. With standard YARA hunting, only new samples are compared against YARA rules, and new matches are reported as they happen. Retroactive Hunting allows users to scan through old samples to uncover YARA rule matches that would otherwise remain hidden. Three types of YARA Retroactive Hunting are supported on Spectra Analyze, with one being available only if the appliance is in a [Spectra Detect](/SpectraDetect/) cluster: - [Cloud Retro Hunting](#local-retro-hunting), which applies to samples in the Spectra Intelligence cloud that were analyzed in the past 90 days. Archives and samples larger than 200 MB are excluded from the sample set, but samples extracted from those archives are not. - [Local Retro Hunting](#local-retro-hunting), which applies to all samples on the local Spectra Analyze instance regardless of their age and analysis date. **Local Retro Hunts across large datasets are processing-intensive and may negatively impact the performance and stability of the appliance.** - **Remote Storage Hunting**, which applies to samples stored in S3 buckets configured on a Spectra Detect Hub group S3 connector service. Such retro hunts will be executed using the Worker appliances, and the results will be visible on the Manager dashboard. Links to remote storage retro hunts can be found in the **YARA Retro Hunt** pop-up dialog. ## Local Retro Hunting **Important notes** 1. Local Retro Hunting can be performed on all active rulesets on the appliance, including [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) rulesets. 2. Local Retro Hunting cannot be performed on individual rulesets - it runs on all active rulesets at once. 3. To exclude a ruleset from Local Retro Hunting, disable it before running Local Retro. 4. Local Retro does not submit samples to dynamic analysis services (such as Cuckoo or FireEye) during a scan. ### Starting a Local Retro Hunt To start a Local Retro scan on all active rulesets on the appliance, click the **Run Retro Hunt** button at the top right of the YARA page. This opens a pop-up with the options to perform a retro hunt on local samples, or to initiate a retro hunt on remote storage. **Tip: Performing retro YARA hunts on remote storage is available only if the appliance is in a Spectra Detect cluster comprising a Spectra Detect Manager, Hub and Worker with a configured S3 connector on the Hub group. Users can select the buckets from those added to the Hub group’s S3 connector and configure the desired file age and folder/prefix for the files to be included in the hunt. Such retro hunts will be executed using the Worker appliances, and the results will be visible on the Manager dashboard. Links to remote retro hunts can be found in the **YARA Retro Hunt** pop-up dialog.** ![Section of the YARA page with the Local Retro indicator](images/analyze-yara-local-retro.png) To stop a retro scan, open the **YARA Retro Hunt List** menu (the clock icon) and click the stop button next to the retro hunt listing. Local Retro does not submit samples to dynamic analysis services (such as Cuckoo or FireEye) during a scan. When the scan completes, the results will be available in the list of YARA matches for every active ruleset. The results for Local Retro scans cannot be cleared, and samples cannot be removed from the list of matches. ### Stopping and Restarting a Local Retro Hunt While a Local Retro scan is in progress, it can be stopped by clicking the stop button next to the retro hunt listing in the **YARA Retro Hunt List** dialog. After a Local Retro scan is stopped or completed, it can be restarted at any point. However, the next scan behaves as a fresh start - it does not continue from where it previously stopped. The *YARA Retro Hunt List* dialog contains detailed information about all previous Local Retro scans, including whether they were stopped or not. ## Cloud Retro Hunting **Important notes** 1. Cloud Retro Hunting can be performed only on rulesets that are saved in the Spectra Intelligence cloud, because the Cloud Retro sample set resides there. For a successful Cloud Retro scan, a ruleset needs to be able to access that sample set. 2. The Cloud Retro sample set includes samples analyzed in the Spectra Intelligence cloud over the last 90 days. Archives and samples larger than 200 MB are excluded, but samples extracted from those archives are not. The sample set is not static, and it changes daily. 3. Cloud Retro Hunting cannot be performed on Spectra Core rulesets. 4. The maximum number of Cloud Retro scans that can be executed depends on the license purchased by the customer. 5. The maximum amount of rules and rulesets that can be scheduled for Cloud Retro Hunting at a time depends on the license purchased by the customer. ### Starting a Cloud Retro Hunt To enable Cloud Retro Hunting for a ruleset, the selected ruleset must first be saved to Spectra Intelligence. To do this, open the ruleset editor by clicking the *Edit* item in the ruleset action menu (☰). In the editor, select the *Run ruleset continuously in Spectra Intelligence* checkbox and click the *Save* or *Save & Close* button. Alternatively, open the ruleset's page and enable the *Run Ruleset in Cloud* switch. The indicators on the YARA page should show that the ruleset is active in the cloud and ready for Cloud Retro. An indicator of synchronization status will be visible in the upper right part of the YARA page. The indicator displays the date and time of last synchronization, and allows skipping the synchronization until the next day. The action menu for the ruleset should now have the *Run Cloud Retro Hunt* option. Selecting it will schedule the ruleset for a Cloud Retro Hunting scan. If the ruleset has been successfully validated, the retroactive scan will start shortly. Alternatively, the appliance administrator can enable automatic Cloud Retro hunting for YARA rulesets saved to Spectra Intelligence in the **Administration > Configuration > YARA Cloud Settings** configuration dialog. If this option is enabled, YARA rulesets that are synchronized with Spectra Intelligence will be automatically scheduled for a Cloud retro scan that will start after successful ruleset validation. This applies to new rulesets created on the appliance, and to existing rulesets that are edited and synchronized with Spectra Intelligence by selecting the “Run ruleset continuously in Spectra Intelligence” checkbox in the YARA ruleset editor. ![Section of the YARA page with highlighted Run Cloud Retro Hunt option](images/analyze-yara-run-retro-sample.png) If new samples are uploaded to the Spectra Analyze appliance while a Cloud Retro scan is in progress, they will be also matched against the ruleset that is being scanned. During a Cloud Retro scan, the progress for the ruleset is displayed next to the status indicator icons on the YARA page. ![Section of the YARA page with Retro Hunt progress tooltip](images/analyze-yara-retro-running.png) When the Cloud Retro scanning for a ruleset is completed, the *RETRO* indicator on the YARA page will reflect that the scan was successful. Hovering over the indicator displays a tooltip with more information on the ruleset’s Cloud Retro status. If the scan has completed successfully, the tooltip will show the date and time when the latest Cloud Retro hunt started and finished. ### Stopping and Restarting a Cloud Retro Hunt It is possible to stop a Cloud Retro scan if the user needs to modify the ruleset for accuracy, or because of performance concerns. While a Cloud Retro scan is in progress, click the triple bar button (☰) on the right side of the selected ruleset. Choose the *Stop Retro Hunt* item from the menu. After a Cloud Retro scan is stopped or completed, it can be restarted at any point (as long as the ruleset remains saved to Spectra Intelligence). However, restarting a Cloud Retro scan on a ruleset will remove the results from the previous Cloud Retro scan. The restarted scan behaves as a fresh start - it does not continue from where it previously stopped. ## Managing YARA Retroactive Hunting Results To view and manage the results of Retroactive Hunting scans, click a ruleset name to expand the list of matched samples. Cloud Retro scan results will have their source displayed as a cloud icon. If the file is not available for download from Spectra Intelligence, a light gray cloud icon is displayed The list of matches for Retroactive Hunting contains similar options as described in the [Managing YARA Ruleset Matches](yara.md#managing-yara-ruleset-matches) section. Users can choose the ruleset version from the dropdown list below the ruleset name to compare scan results for each version. Every sample in the list of results can be selected and managed individually using the options in the action menu (☰). Clicking the file name opens the local or the Spectra Intelligence version of the [Sample Details](./Sample%20Details/index.md) page for the selected file, depending on if the sample is locally available. The Retroactive Hunting results can also be managed in bulk. Selecting one or more samples in the list of results activates the triple bar button (☰) on the right side of the *Size* column. The button opens the bulk action menu with options for: - downloading and analyzing selected samples on the Spectra Analyze appliance, if the samples are available for download (*cloud* and *cloud-retro* only), - removing samples from the list of matches (*cloud* and *cloud-retro* only), - reanalyzing samples (*local* and *local-retro* only), - applying tags to samples (*local* and *local-retro* only), - downloading samples to local storage, - adding/removing samples in new or existing alert subscriptions, - exporting data about selected samples as a CSV file. ### Removing Samples from the Cloud Retro Results YARA rulesets that are saved to Spectra Intelligence can match up to 10 000 samples. When a ruleset reaches that many matches, it will be capped and new matches will no longer be stored on the Spectra Analyze appliance. To free up space and continue collecting new matches for the ruleset, users have to remove at least 1000 old matches. - Samples can be removed from the list of Cloud Retro results manually by selecting them and choosing the *Remove Cloud Matches* option from the action menu (☰). Using this method, samples can be removed one by one, or the user can select and remove multiple samples at once. - Additionally, it is possible to clear all Cloud Retro results for a selected YARA ruleset. To do this, select a ruleset and click the triple bar button (☰) on the right side of the ruleset row. In the action menu that opens, select *Clear Retro Hunt*. ![Section of the YARA page with Clear Retro Hunt option highlighted](images/analyze-yara-retro-clear.png) When the Cloud Retro results for a ruleset are cleared, the icon for the *RETRO* indicator on the YARA page will change, showing that the results have been cleared. Users can then run a new Cloud Retro scan on the ruleset at any point. --- ## YARA Hunting ## Classifying files with YARA rules If a file has been classified by a YARA rule, the **Static Analysis > Classification** section on the [Sample Details](./Sample%20Details/index.md) page includes links to YARA rules that the file has matched. Clicking the link to a ruleset redirects to the YARA page containing the selected ruleset and its matches. To find files tagged by YARA rules on the appliance or in the Spectra Intelligence cloud, use the **tag-yara** keyword on the Search & Submissions page. For example, the search query `tag-yara:malicious threatname:*ransomware*` returns all files classified as malicious by YARA rules, with “ransomware” in their detected threat name. All files that match the YARA rule are automatically tagged with those custom tags after analysis. If a file has any YARA tags, they can be found in the **Static Analysis > Classification > YARA > Tags** section on the [Sample Details](./Sample%20Details/index.md) page. **Note: Changes to YARA tags are not immediately reflected in the Search results. When a YARA tag is added, changed, or removed from a rule, the files that match the rule must be reanalyzed with [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) first. Alternatively, you can also run a local [retro scan](./yara-retro.md#starting-a-local-retro-hunt).** For example, if a YARA tag “test” is renamed to “test2”, searching for *tag-yara:test* returns the same results until all matching files are reanalyzed with Spectra Core. After they are reanalyzed, the files can be found with the new tag, *tag-yara:test2*, and the old tag will not return any results. ## How YARA Hunting Works on Spectra Analyze Spectra Analyze contains default YARA rulesets, but also allows users to [create and edit custom rulesets](#creating-new-yara-rulesets), as well as to synchronize rulesets with other ReversingLabs products. The default YARA rulesets are called Spectra Core rulesets. They can be accessed by selecting the “Spectra Core Rulesets” option in the filter pull-down menu on the YARA Hunting page. Those rulesets are applied only to local files on the appliance (through Continuous Local Matching). Spectra Core rulesets cannot be saved to the cloud or modified (edited, disabled, or deleted) in any way by any type of user. Rulesets present on Spectra Analyze by default are open source, and published by ReversingLabs in [a public GitHub repository](https://github.com/reversinglabs/reversinglabs-yara-rules). Additional rulesets can be imported as files, or from online sources, straight from the YARA page. For more information on importing rulesets, refer to [YARA Repositories](./Administration/integrations-connectors/yara-repositories.md). Files are matched against YARA rulesets on the Spectra Analyze appliance in four different ways. 1. **Continuous Local Matching (Default)** When a YARA ruleset is created on or uploaded to Spectra Analyze, it continuously looks for matches among local files that are added to the Spectra Analyze appliance after the ruleset has been created. This is the default behavior when Spectra Intelligence is not configured on the appliance, and when a YARA ruleset is not saved to Spectra Intelligence. Local matches for rulesets cannot be removed from the list of matches on the YARA page. 2. **Continuous Cloud Matching** When a new or existing YARA ruleset is selected to run continuously in the Spectra Intelligence cloud, it looks for matches among files that are added after the ruleset has been created. This includes local files added to the Spectra Analyze appliance, and files in the cloud uploaded through various ReversingLabs services (such as APIs). The prerequisite for Continuous Cloud Matching is that the Spectra Analyze appliance is connected to Spectra Intelligence. Important Note Every Spectra Analyze instance must be connected to a different Spectra Intelligence account. Sharing accounts between multiple instances can interfere with the functionality of the appliance (particularly with YARA rule synchronization). Appliance administrators should ensure that the cloud account credentials are properly configured in the **Administration ‣ Configuration ‣ Spectra Intelligence** dialog. YARA rulesets that are saved to Spectra Intelligence can match up to 10 000 samples. When a ruleset reaches that many matches, it will be capped and new matches will no longer be stored on the Spectra Analyze appliance. To free up space and continue collecting new matches for the ruleset, users have to remove at least 1000 old matches. Find more information in the [Hunting for Malware in the Spectra Intelligence cloud with YARA](#hunting-for-malware-in-the-spectra-intelligence-cloud-with-yara) section. 3. **Retroactive Cloud Matching** When a new or existing YARA ruleset is selected to run continuously in the Spectra Intelligence cloud, and the YARA Retroactive Hunting feature is enabled on the appliance, the ruleset can be selectively matched against files in the cloud that have been analyzed in the past 90 days. The ruleset will continuously look for new matches among local files that are added to the Spectra Analyze appliance while a Cloud Retro scan is in progress. Find more information in the [Cloud Retro Hunting](./yara-retro.md#cloud-retro-hunting) section. 4. **Retroactive Local Matching** When the YARA Retroactive Hunting feature is started, all rulesets that are active (enabled) on the appliance will be included in a Local Retro scan. This also includes the default Spectra Core rulesets. While a Local Retro scan is in progress, the appliance still continues to analyze new files that are added to the appliance. The processing priority is given to newly added files to prevent delays. The Local Retro scan runs against all local files regardless of their age and analysis date. If users want to prevent the Local Retro scan for one or more rulesets, those rulesets have to be disabled on the appliance. Local Retro matches for rulesets cannot be removed from the list of matches on the YARA page. Find more information in the [Local Retro Hunting](./yara-retro.md#local-retro-hunting) section. ## Understanding the YARA Page Clicking the *Yara* item in the top-level menu brings the user to the YARA Hunting page, which displays a list of rulesets (collections of YARA rules) and matching statistics. ![Overview of the YARA page](images/analyze-yara.png) ### Filters The search bar allows users to filter the list of rulesets by typing the full or partial name of a ruleset. Enclose the search string in quotation marks for exact name matching. Next to the search bar, several menus allow filtering according to ruleset ownership, status and source (for imported rulesets). Some notes on the possible choices: - Under the ownership menu, "User Rulesets" will show all rulesets from all users except the current user ("My Rulesets") - Under the status menu, you can find rulesets with warnings (for example, with a syntax error), as well as rulesets that were [capped in Spectra Intelligence](#managing-yara-rulesets-with-warnings) **Tip: Filters are reflected in the URL (as query parameters), which means that you can share a filtered page. For example:** ``` ?name=yippee-ki-yay&owner=owner_user_jmcclane&status=enabled ``` ...will present a page where the ruleset names contain "yippee-ki-yay", where their owner is user `jmcclane` (note the "owner_user_" prefix), and where such rulesets are enabled. ### Actions The indicators and buttons in the top right of the page display the actions and status information related to [YARA Retroactive Hunting](./yara-retro.md). - The **Add Ruleset** button provides the options to [create, import or upload rulesets](#creating-new-yara-rulesets). - The **Actions** button allows starting a [Local Retro Scan](./yara-retro.md#local-retro-hunting) on all active rulesets on the appliance, and contains links to the list of previous retro hunts and YARA repository management. The retro hunt list is also accessible via the *Open Retro Hunt List* button. - The **gear icon** menu allows the users to customize the YARA table columns and date format. - The synchronization status indicator is visible only if Spectra Intelligence is correctly configured on the appliance, and if at least one YARA ruleset on the appliance is saved in the Spectra Intelligence cloud. Hovering over the indicator with the mouse activates a “Skip To” link that can be used to postpone ruleset synchronization. ### Results If a ruleset is greyed out on the page, it is disabled. Disabled rulesets are not active on the appliance and are not included in any of the Local, Cloud, or Retro scans. Clicking the star icon next to the ruleset adds it to favorites for the current user. Favorite rulesets are listed in the YARA Matches section on the [Dashboard](./dashboard.md). Up to 10 rulesets can be added to favorites. Every ruleset has one or more status indicators. **Hovering over the indicator icon displays a tooltip with more information about every status.** The far right action menu (☰) for each ruleset contains options for testing, editing, exporting, disabling, and deleting the ruleset, and options to subscribe (create [Alerts](./alerts.md) for new YARA matches) or unsubscribe from a ruleset. **Note: Spectra Core rulesets can only be edited and exported, but not disabled or deleted. Selecting the **Edit** option for a Spectra Core ruleset opens the ruleset editor where the user can preview and copy the contents of the ruleset, but cannot save any changes to it.** ### Creating New YARA Rulesets YARA rulesets on the Spectra Analyze appliance can be created from scratch, uploaded as files, or imported from a number of popular online sources. There is also a [YARA API](./API%20Documentation/yara-api.md). ReversingLabs products, including Spectra Analyze, support the following YARA modules: - PE - ELF - Dex - Macho - String - Math - Hash - Time - Dotnet **Note: “Import” and “include” statements are not supported.** To upload or import rulesets from external files and sources, click the **Add Ruleset** button at the top right of the YARA page. The dropdown menu offers three options: **Create Ruleset**, **Upload File** and **Import from Online Sources**. Importing from online sources provides a list of predefined and custom (if configured) sources, and contains an additional step of allowing the selection of which rulesets or individual rules to import. Invalid rules will, depending on the parser, be either imported as disabled or not imported at all. ![The ruleset import selection screen, allowing granular import of rulesets and individual rules.](images/analyze-yara-ruleset-import-online.png) Once the process finishes, imported rulesets can be edited and synced to other appliances if YARA sync is enabled. To write a new ruleset, select the **Add Ruleset > Create Ruleset** option in the top right of the page. This opens the YARA Ruleset Editor **Tip: For more information on writing YARA rulesets, consult one of the following sources:** - ReversingLabs publishes guidance for using YARA on the official blog. See the blog posts [“Level up your YARA game”](https://blog.reversinglabs.com/blog/level-up-your-yara-game) , [“Writing detailed YARA rules for malware detection”](https://www.reversinglabs.com/blog/writing-detailed-yara-rules-for-malware-detection) and [“Five Uses of YARA”](https://blog.reversinglabs.com/blog/five-uses-of-yara) to learn more. - The official YARA documentation offers detailed advice on [how to write YARA rules](https://yara.readthedocs.io/en/stable/writingrules.html). - Use Spectra Core rulesets present on the appliance as reference. #### YARA Ruleset Restrictions - Naming restrictions: - YARA ruleset names must be between 3 and 48 characters. - The underscore ( _ ) should be used instead of spaces, and any other special characters should be avoided. Ruleset names should only use numbers (0-9) and a-z/A-Z letters. - Ruleset size restrictions: - A ruleset file should not be larger than 40 MB. - A ruleset larger than 1 MB (1048576 bytes) cannot be saved and run in the Spectra Intelligence cloud. When creating a new ruleset in the editor, you can select whether the ruleset will be immediately enabled after saving changes by selecting the **Enable Ruleset** checkbox. If the checkbox is not selected, the ruleset will be disabled after it is created, and files will not be matched against it until the you enable it. To save a newly created ruleset in the Spectra Intelligence cloud, select the *Run ruleset continuously in Spectra Intelligence* checkbox in the ruleset editor. The appliance administrator can enable automatic upload of YARA rulesets to Spectra Intelligence in the **Administration > Configuration > YARA Cloud Settings** configuration dialog. If this option is enabled on the appliance, the *Run ruleset continuously in Spectra Intelligence* option will be automatically selected by default in the YARA ruleset editor. When done making changes to the new ruleset in the editor, click the *Save & Close* button. If the new ruleset is validated, it appears in the list of rulesets on the YARA page. Clicking *Save & Publish* will save the ruleset and add it to the synchronization queue. This button will be visible only to users with the appropriate [user role](/SpectraAnalyze/Administration/users-personalization/user-roles/). If one or more rulesets are saved in Spectra Intelligence, an indicator of synchronization status is visible in the upper right part of the YARA page. ### Editing Rulesets and Restoring Previous Ruleset Versions All Spectra Analyze users with the appropriate user roles can edit or delete all YARA rulesets on the appliance, except Spectra Core rulesets. Clicking the *Edit* item in the ruleset action menu (☰) on the YARA page opens the ruleset editor. The editor allows modifying an existing YARA ruleset, saving it to Spectra Intelligence, and managing different versions of the same ruleset. Users can also manually enable or disable a ruleset by selecting the *Enable ruleset* checkbox. Every time a ruleset is edited and saved, a new version of the ruleset is created. The versions are visible both in the Version filter on the ruleset's page and in the YARA ruleset editor. The statistics about matches of every ruleset version are preserved and displayed, allowing users to compare their efficacy. In the YARA ruleset editor, the user can restore any previous version of a ruleset to overwrite new changes. Click the *History* menu to open the pull-down list with ruleset versions. Click the **Load** link next to the ruleset version that should be restored, then click the *Save* button to apply changes and activate the selected version. Clicking **Save & Close** returns to the YARA page after saving changes, while clicking *Save* allows the user to remain in the ruleset editor and keep making changes. It is not possible to save an empty ruleset (a ruleset without any text in the *Rules* field), or a ruleset without a name. The **Save & Publish** button saves the ruleset and add it to the synchronization queue. This button is visible only to users with the appropriate [user role](/SpectraAnalyze/Administration/users-personalization/user-roles/). Optionally, [test the ruleset](#yara-test-run-page-testing-rulesets) before saving and/or publishing to check if it’s correctly matching the desired samples. ![YARA ruleset editor with highlighted History link](images/analyze-yara-rule-history-editor.png) The ruleset editor also displays information about the user who added the ruleset, and the user who last edited it. Editing a ruleset does not change its ownership. For example, if user *test1* creates a ruleset and another user *test2* saves changes to the same ruleset, user *test1* is still the owner of the ruleset. In this scenario, only the user *test1* can delete the ruleset. When a user account is deleted from the Spectra Analyze appliance, all YARA rulesets owned by that deleted user are automatically transferred to the administrator account that deleted the user. Validation indicators visible on the main YARA page are also displayed in the ruleset editor. Depending on the modifications made to the ruleset, the validation indicators can change (for example, when a ruleset is saved to Spectra Intelligence). ### YARA Test Run Page: Testing Rulesets When writing a new ruleset in the editor, you can test run a ruleset against a predefined set of samples to check if the ruleset matches everything it should. The YARA Test Run page can be accessed via the ruleset editor, or using the **Test Ruleset** option in the (☰) menu of a particular ruleset in the table. Samples can be added to the testing page either directly by hash, or using tags. You can select up to 5 tags, which will load 100 latest submitted samples from the selected tags. If unsure about a specific tag name, the tag menu also serves as a search box. Once the page is populated with samples, you can tweak the ruleset by clicking the **Edit Ruleset** button, or perform a YARA test run by clicking the **Run Test** button. After the test is complete, the samples list shows the test results in the far right column of the table. If you tweak the ruleset again and **Retest** it, new test results will show up alongside the old ones in the rightmost column. This way, you can compare the results of up to four previous runs. Test result icons, when clicked, open up a hex preview with the highlighted portion of the binary that was matched in the test run, as well as its ASCII representation. **Run New Test** clears the previous results. ### Enabling and Disabling Rulesets **Note: YARA rulesets cannot be enabled or disabled while their Cloud or Retro validation is pending, or while a Retro scan on the rulesets is in progress.** For individual rulesets: on the right side of the page, click the triple bar button (☰) to open the ruleset action menu. In the menu, click *Enable* or *Disable*. Alternatively, click the ruleset to open its page showing a list of matches, and disable the "Enable Ruleset" switch in the top right of the page. For multiple rulesets at once: select the checkboxes to the left of each ruleset name. When the rulesets are selected, open the main action menu by clicking the triple bar button (☰) in the toolbar, on the right side of the YARA page. In the menu, select the *Enable* or *Disable* option. The YARA page dynamically displays rulesets as enabled or disabled, one by one. ### Managing YARA Ruleset Matches Every ruleset on the YARA page can be clicked to show a list of files that matched one or more YARA rules in the selected ruleset. When a ruleset is opened, various statistics are displayed below the ruleset name and filters: Total Matched Samples, Most Matched Rule, Most Matched Format, Most Matched Threat Type. The top left of the page contains the ruleset name with a tooltip displaying the ruleset's creation and last updated date, commit ID and source repository information (where the ruleset was imported from). The top right of the page contains options to **Edit Ruleset**, and an **Actions** menu allowing the users to test, edit, export, disable or delete the ruleset, and to subscribe/unsubscribe. In addition to these buttons, there are switches to enable/disable the ruleset, and to run the ruleset in Spectra Intelligence cloud. To the right of the statistics boxes is an arrow button that expands each of the statistics into a graphical display. Colored sections on the graph can be clicked to actively filter out the results table below. The table can also be filtered using the dropdown menus at the top of the ruleset’s page: by ruleset version, by a specific rule, classification, format, threat type, first seen date, and match type. The classification filter uses checkboxes for multi-selection. Several different filters can be active at the same time. The filters can be cleared to their default values by clicking the **Clear** button. Ruleset matches can be filtered to display only those files that matched a particular rule. To do that, select the rule in the pull-down list under the ruleset name. ![YARA matches filtered by classification: Malicious.](images/analyze-yara-matches-filter-by-classification.png) The information about ruleset matches is divided into columns. All columns can be sorted in ascending or descending order by clicking the column name. From left to right, the columns are: - source indicator (local or cloud; if the file is not available for download from Spectra Intelligence, a light gray cloud icon is displayed), - status indicator (as explained in the [About Spectra Analyze](./index.md#color-coding-and-sample-status) section), - time when the file matched the selected ruleset, - time when the sample was first seen, - time when the sample was last seen, - threat name (if detected; applies to malicious and suspicious samples only), - file name (or SHA1 hash), - name of the YARA rule that triggered the match, - file format (for cloud matches, displays “Unknown” if file format information for a sample is not stored in the Spectra Intelligence cloud), - the number of extracted files, - the file size. The right side of the page contains two buttons with more options to filter the list of ruleset matches: On the right side of every match in the list, there is a triple bar button (☰) that activates the actions menu with different options. For local matches, the options include: - *Delete sample* - removes the submission. This action is visible to users only for files and URLs they have submitted themselves. Regular users cannot delete files and URLs submitted by other users. Administrators can see this menu item for all submissions, and delete all submissions regardless of who created them. - *Copy to my submissions* - available only if the sample was submitted by a different user. Selecting this adds the sample to the submissions for the current user. - *Download sample* – downloads the submission from Spectra Analyze to local storage (compatible with modern ZIP tools such as `unzip` 6.00+, Python's `zipfile`, 7-Zip, or `bsdtar`). - *Download container* - if the file is extracted, downloads its top-most parent from the appliance to the local storage - *Set classification* - allows users to manually override file classification - *Subscribe* and *Unsubscribe* - adds or removes the file from alert subscriptions - *Reanalyze* - allows users to reanalyze the file with static, dynamic, or Spectra Intelligence analysis services - *Download Extracted Files* - downloads files extracted during analysis to local storage For cloud and cloud retroactive hunting matches, the options include: - *Fetch & Analyze* - downloads the file to the appliance - *Reanalyze on Spectra Intelligence* - reanalyzes individual files using the Spectra Intelligence analysis services - *Subscribe* and *Unsubscribe* - adds or removes the file from alert subscriptions Clicking a row in the list of matches expands it to show additional information about the file, as described in the [Expanded Details](./search-page.md#expanded-details) section. Clicking the file name opens the local or the Spectra Intelligence version of the [Sample Details](./Sample%20Details/index.md) page for the selected file, depending on if the sample is locally available. #### Performing Bulk Actions on Ruleset Matches Multiple files can be selected in the list of ruleset matches, and supported bulk actions can be performed on them. Select the checkboxes on the left side of each individual file, or click the *Select all N YARA matches* link that appears above the list of matches when at least one sample is selected. It is also possible to select all matches by clicking the *Select All* checkbox on the left side of the *Match Time* column. When one or more files are selected, the bulk action menu (☰) appears on the right side of the list (next to the *Size* column). **For local matches, the supported bulk actions include:** - *Download samples* – downloads the submission from Spectra Analyze to local storage (compatible with modern ZIP tools such as `unzip` 6.00+, Python's `zipfile`, 7-Zip, or `bsdtar`). - *Reanalyze* - allows users to reanalyze the files with static, dynamic, or Spectra Intelligence analysis services - *Subscribe* and *Unsubscribe* - adds or removes the files from alert subscriptions - *Apply User Tags* - allows users to add custom tags to selected files - *Download Extracted Files* - downloads files extracted during analysis to local storage **For cloud and retro matches, the supported bulk actions include:** - *Fetch And Analyze* - downloads and analyzes the files to the Spectra Analyze appliance - *Remove Cloud Matches* - removes selected files from the list of matches for that particular ruleset - *Subscribe* and *Unsubscribe* - adds or removes the files from alert subscriptions - *Download Samples* – downloads the submission from Spectra Analyze to local storage (compatible with modern ZIP tools such as `unzip` 6.00+, Python's `zipfile`, 7-Zip, or `bsdtar`). - *Download Extracted Files* - downloads files extracted during analysis to local storage #### Exporting Ruleset Matches The *Export* button is available at the top of the ruleset matches list. It supports exporting data for the whole page or only for selected samples. Supported options include copying SHA1, SHA256, or MD5 hashes to clipboard, and exporting as CSV, JSON, or XML. The exported CSV file with YARA matches contains the following information: - threat status, - risk score, - threat name (if detected), - time when the file matched the selected ruleset, - file name, - YARA rule that triggered the match, - file format, - the number of extracted files, - the file size, - SHA1 hash, - SHA256 hash, - MD5 hash, - first-seen timestamp. ### Managing YARA Rulesets with Warnings Some YARA rulesets can slow down file processing on the Spectra Analyze appliance due to their length, scope, and other factors. When uploading, editing, enabling and disabling such rulesets, the Spectra Analyze appliance displays a notification. The ruleset(s) are marked with a warning icon on the YARA Hunting page. ![Section of the YARA page with highlighted ruleset warning message](images/analyze-yara-ruleset-warning.png) It is possible to filter the YARA Hunting page to display only rulesets with warnings by choosing the *Rulesets with warnings* item from the pull-down menu on the right. Those rulesets can then be disabled or edited to resolve the issue. It takes some time for the system to update the ruleset status, so the warning icon does not disappear immediately after modifying a problematic ruleset. Appliance administrators can access the list of rulesets with warnings from the *Scale* section of the [System Status](/SpectraAnalyze/Administration/usage-alerts/system-status/) page. If there are any rulesets with warnings, the *YaraWarnings* icon will not be green, and will show the number of warnings instead. ![Section of the System Status page with YARA ruleset warning indicator](images/analyze-yara-ruleset-warning-status.png) Clicking the icon redirects to the YARA Hunting page filtered to display only rulesets with warnings. Here the offending rulesets can be edited or disabled to improve the processing speed of the appliance. ## Hunting for Malware in the Spectra Intelligence cloud with YARA By default, rulesets only run on files processed on the Spectra Analyze appliance (through Continuous Local Matching). However, rulesets can be synchronized with Spectra Intelligence and run on a massive amount of files processed daily by ReversingLabs systems, greatly expanding the potential for YARA matches. If [YARA Retroactive Hunting](./yara-retro.md#cloud-retro-hunting) is enabled on the appliance, rulesets synchronized with Spectra Intelligence can also be run on files analyzed in the Spectra Intelligence cloud over the last 90 days. To synchronize a YARA ruleset with Spectra Intelligence: - Click the ruleset's name on the YARA page to open the page displaying a list of its matches. Enable the **Run Ruleset in Cloud** switch in the top-right corner of the page. - Open the ruleset editor by clicking the *Edit* item in the ruleset action menu (☰). In the editor, select the *Run ruleset continuously in Spectra Intelligence* checkbox and click the *Save* or *Save & Close* button. - Alternatively, the appliance administrator can enable automatic upload of YARA rulesets to Spectra Intelligence in the **Administration > Configuration > YARA Cloud Settings** configuration dialog. If this option is enabled on the appliance, the *Run ruleset continuously in Spectra Intelligence* option is automatically selected by default in the YARA ruleset editor. ![Section of the YARA ruleset editor with the options for saving the ruleset to Spectra Intelligence](images/analyze-yara-edit-ruleset.png) When synchronized with Spectra Intelligence, the ruleset displays a cloud status indicator on the YARA page. Additionally, an indicator of synchronization status is visible in the upper right part of the YARA page. The indicator displays the date and time of last synchronization, and allows skipping the synchronization until the next day. The number of matches stored for a ruleset synchronized with Spectra Intelligence is currently capped at 10 000 to limit the impact on Spectra Analyze. If a ruleset has hit this limit, its CLOUD status indicator on the YARA page gets a red X badge icon. New matches are no longer preserved for a ruleset that hits this limit. If the appliance administrator has enabled the *Automatic disabling of Cloud enabled YARA rulesets* option in the **Administration > Configuration > YARA Cloud Settings** configuration dialog, every ruleset that reaches the limit are automatically de-synchronized from Spectra Intelligence. To continue receiving new cloud matches for a ruleset that has reached the limit, users have to remove previous retro results from the ruleset’s action menu (☰) by clicking the Clear Retro Hunt option. Alternatively, open the ruleset’s page, configure the filters so no matches of importance are removed, select all samples in the table and pick the Remove Cloud Matches option from the upmost (☰) menu. To clear matches even more selectively, configure the filters, sort the table by source (click the first table column title so that the cloud matches are listed first) and select individual samples or entire pages of results and use the Remove Cloud Matches option on the selected samples. ## Synchronizing YARA Rulesets with Other Appliances **Note: Only appliance administrators can access the option to synchronize YARA rulesets.** If the Spectra Analyze appliance is connected to the ReversingLabs [Spectra Detect](/SpectraDetect/) Manager, it is possible to synchronize YARA rulesets to other appliances (Spectra Analyze, Spectra Detect Worker) connected to the same Spectra Detect Manager. The synchronization needs to be configured on Spectra Detect Manager first, and then enabled in the *Spectra Detect Manager* section of the Spectra Analyze [System Configuration](/SpectraAnalyze/Administration/configuration-update/configuration/) page. ![System Configuration page with highlighted option for YARA ruleset synchronization](images/analyze-yara-sync.png) Select the *Enable Syncing* checkbox to enable YARA rule synchronization to other appliances from the current Spectra Analyze instance. When synchronization is enabled, every new ruleset created on the appliance automatically gets sent to the Spectra Detect Manager, and from there to other appliances that support YARA rule synchronization. The synchronization is bidirectional, so any changes made to YARA rules on other appliances connected to Spectra Detect Manager also reach the current Spectra Analyze instance. New rulesets automatically appear on the Spectra Analyze YARA page. Rulesets retrieved from other appliances via Spectra Detect Manager synchronization are not visually distinguished from other rulesets on the YARA page. Ruleset synchronization includes deleting and disabling rulesets. Deleting a ruleset on one appliance also deletes it on the others, if they are synchronized via Spectra Detect Manager. When creating, deleting or editing rulesets, only users with the **YARA Publish and Delete** permission have the additional options to **Save & Publish / Delete & Publish** that add the ruleset action to the synchronization queue. Other users with the appropriate, **YARA**, permission are only able to manage rulesets locally. ### Important notes 1. Spectra Core rulesets are not synchronized. 2. If two users on different appliances make changes to the same ruleset at the same time, only the changes from the appliance that syncs with Spectra Detect Manager first will be applied. Synchronization with Spectra Detect Manager happens approximately every ten minutes. ### YARA Status If YARA syncing is enabled, the YARA page shows a YARA Status indicator to show the current synchronization status, and to indicate if any rulesets are out of sync. In case some rulesets are not synchronized, which is indicated by a red X badge, users can click the **Show Status** link to see which rulesets are not synchronized and **Republish** them. --- ## Spectra Analyze Alerts — Subscriptions, Delivery Methods & Notifications The Alerts feature allows real-time monitoring to track changes in malware classification and analysis results. It automates notifications for specific events, allowing users to utilize their time more efficiently and be informed of malware status changes on-the-go. ![The action menu on the Alerts page with Configure option highlighted](./images/analyze-alerts-page.png) Users can receive notifications about changes related to the samples on the appliance and in Spectra Intelligence. The notifications make it easy to monitor and track various malware analysis activities even when the users are away from the appliance. Users can choose how often they want to be notified, and where they want to receive the notifications. [Unresolved](#marking-alerts-as-resolved) alerts are indicated by a red badge on the alerts indicator in the top right of the interface, and by blue stripes to the left of the alerts grid. The conditions that define when an alert should be generated are called **subscriptions**. Every subscription can be associated with one or more **delivery methods**. Users can create and modify alert subscriptions from the [Subscriptions and Actions Management page](#managing-alerts). It is also possible to [create alert subscriptions for individual samples](#creating-a-new-alert-subscription) in the GUI. Every alert subscription can have one or more delivery methods. Users can create and modify actions from the [Subscriptions and Actions Management page](./alerts.md#managing-alerts). When an alert is triggered, the notification is delivered to the destination(s) specified in the associated action(s). If an alert subscription doesn’t have any associated delivery methods, the alert will only be visible on the Alerts page. The Alerts page provides an overview of all events on the appliance, including the ones generated by user-defined subscriptions. Users can filter the Alerts page to display only the alerts related to specific alert subscriptions. **Important notes about the Alerts feature** 1. Alerts are sent only if there is a new event matching the conditions configured in the subscription. Alerts cannot be sent for events that occurred before a subscription was created. 2. Multiple alerts triggered for one subscription in the selected notification period will be aggregated and sent in a single email message. 3. The SMTP service must be configured on the appliance in order to receive emails about new alerts. 4. The maximum amount of hashes that the user can add to one subscription is 1000. 5. Only SHA1 hashes can be added to alert subscriptions. 6. The maximum amount of subscriptions a user can create is 10 000. This limit is not user-configurable. When the limit is reached, a notification appears in the GUI, warning the user that some old subscriptions should be removed in order to create new ones. 7. Alert subscriptions are private and visible only to the user who created them. When other users are logged into their accounts, they will not be able to see or modify subscriptions created by other users. ## Alert Types The following table lists the currently supported types of alerts (notifications). To set up an alert and get notified when it is triggered, users have to [create a new subscription](./alerts.md#creating-a-new-alert-subscription). | Alert Type | Alert Trigger | |-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Analysis Alerts | Analysis Alerts include notifications for Static Analysis, Threat Intelligence and RL Cloud Sandbox, tracking the progress of automated analysis. It also covers third-party sandbox integrations like Cuckoo and Joe Sandbox. | | Classification change | A sample’s threat status has changed (e.g., from “suspicious” to “malicious”). | | Sample available for download | A previously unavailable sample has become available for download from the Spectra Intelligence cloud. | | YARA matches | A new sample has matched one or more YARA rulesets. [YARA Retroactive Hunting matches](./yara-retro.md) are also included. | ## Managing Alert Subscriptions and Delivery Methods Users can view and manage their alert subscriptions from the [Alerts Configuration](#managing-alerts) page. To access the page, click *Configure* on the Alerts page. Alternatively, select **User menu > User profile** from the main menu. This opens the [User Settings](./initial-configuration.md#user-settings) page. Alternatively, click *Configure* on the Alerts page. The *Alerts Configuration* page is divided into two sections: *Alerts* and *Delivery Methods*. All currently active subscriptions are listed in the *Alerts* section. Users can modify existing subscriptions by clicking *Edit*, or [create new ones](#creating-a-new-alert-subscription) by clicking **New Alert**. ![List of active alert subscriptions on the User Settings page](./images/analyze-alerts-configuration.png) Similarly, all actions that can be associated with alert subscriptions are listed in the *Delivery Methods* section. Users can modify existing actions by clicking *Edit*, or [create new ones](#creating-a-delivery-method) by clicking **New Method**. ### Creating a New Alert Subscription To create a new alert subscription, open the *Alerts Configuration* page, and click **New Alert**. The *New Subscription* dialog allows users to choose one or more event types and the associated delivery methods. Users can also add a custom name and description to every subscription, which makes it easier to distinguish between subscriptions and quickly check their scope. In order to associate an alert subscription with a delivery method, users must first [create some delivery methods](#creating-a-delivery-method). When a delivery method is associated with an alert subscription, the details configured for the delivery method apply to that particular subscription. Any method can be associated with any number of active alert subscriptions. Likewise, any subscription can have more than one delivery method associated with it. For example, if an action can define that email should be sent to *test@user.example* every 2 hours, any associated alert subscription will send alerts to that particular address at that particular frequency. Saving the alert subscription makes it active on the appliance. ![Dialog for creating a new alert subscription](images/analyze-subscription-dialog.png) ### Event Types Depending on the selected event types, additional options become available in the *New Subscription* dialog. **Analysis Alerts** Subscribe to notifications for ReversingLabs services (Static Analysis, Threat Intelligence and RL Cloud Sandbox) and third-party services. Available alert stages depend on the analysis method and may include *Started*, *Finished*, and/or *Failed*. **Classification Changes** The Classification Changes event type allows choosing which changes in sample threat status will trigger an alert (for example, from goodware and suspicious to malicious). It is possible to select multiple threat status values in both configuration fields. ![Dialog for creating a new Classification change alert subscription](images/analyze-alerts-classification-changes.png) There are several optional checkboxes that allow setting up more fine-grained alerting criteria. 1. **On Risk Score change** - becomes visible for this event type when threat status values that support it are selected. Selecting the checkbox sends an alert when there is a transition in the [risk score](/General/AnalysisAndClassification/Classification/#risk-score) of a sample (for example, from low (6) to medium (7)), even if the threat status does not change. For example, a sample's risk score can increase from 6 to 9, but the sample will still be classified as malicious. The alert is not sent when the risk score transition is within the same severity range (for example, medium (8) to medium (7)). Transitions in risk score values for goodware samples do not generate alerts. 2. **On threat name change** - selecting it will send an alert when the threat name of a sample changes, even if its threat status remains unchanged. 3. **Notify on specific hash(es)** - when this checkbox is selected, an additional *Sample hash values* text field becomes available. If any SHA1 hashes are entered into the text field, the alert is sent only for classification changes to those samples. When this checkbox is not selected, and no SHA1 hashes are provided, the alert is sent for classification changes to all samples on the appliance. **Sample Available for Download** The Sample available for download event type requires users to provide a list of at most 100 SHA1 hashes to monitor for availability. If **Fetch and analyze** is enabled, samples will automatically be downloaded to the appliance when they become available. **YARA Matches** The YARA Matches event type accepts a list of YARA rulesets that a sample should match to trigger the alert. There is an autocomplete pull-down list with names of all YARA rulesets on the appliance. The maximum number of YARA rulesets is 20. ### Creating a Delivery Method To create a new delivery method, open the *Alerts Configuration* page, and click **New Delivery Method**. The *New Delivery Method* dialog allows users to choose the delivery method (where to send alerts about triggered events) and set the notification frequency (how often the alerts should be sent). Users can also add a custom name for every action. Currently supported delivery methods include *E-mail* and *Syslog*. Clicking *Save* saves the method, making it visible in the *Delivery Methods* section and available when creating or modifying an alert subscription ![Dialog for creating a delivery method](images/analyze-alerts-delivery-method.png) #### Creating a New Email Delivery Method When the *E-mail* method is selected, an additional checkbox **Deliver to logged in user** becomes available. Selecting this checkbox will send alerts to the currently logged-in user, in addition to other email addresses provided in the *Additional email addresses* field. Each address should be in its own line in the text field. The SMTP service must be configured on the appliance in order to receive alert emails from it. Appliance administrators should make sure the settings are properly configured in the **Administration > Configuration > SMTP** dialog. When delivered to the configured address, the alert email contains information about which subscriptions have new alerts, and how many new alerts were generated for each subscription. The email also contains a link for each subscription. The link leads to the Alerts page on the appliance, filtered to display only alerts for the specified subscription. #### Creating a New Syslog Delivery Method When the *Syslog* method is selected, additional options become available in the dialog. **Host** - requires the user to input the host address of the syslog server that should receive alerts **Port** - requires the user to configure the port on which the syslog server should listen for alerts. **Transport protocol** - allows choosing which communication protocol should be used to send alerts to the syslog server. Supported protocols are TCP and UDP. The protocol selected here affects which port number can be configured in the previous field The **Message format** option allows users to customize how the alerts will appear in the logs. Users can combine any number of supported fields with custom text to adjust the contents of each alert. The default format (``*{sha1} - {alert_type} - {description}*``) is already configured here when creating a new action. **Custom Message Examples** ``` {sha1} - {alert_type} - {description} b8b3b60c13d3fbb6e1932dab72264410bab0a2ce - classification_change - Threat Status changed from 2 to 1 via Spectra Intelligence ``` ``` The alert {label} was triggered on sample {sha1} The alert New Malicious Detection was triggered on sample b8b3b60c13d3fbb6e1932dab72264410bab0a2ce ``` ``` New {alert_type} alert received on file {sha1} with status {threat_status} New classification_change alert received on file b8b3b60c13d3fbb6e1932dab72264410bab0a2ce with status 1 ``` **Supported Message Fields** | FIELD NAME | DESCRIPTION | TYPE | | ---------------------- | ------------------------------------------------------------ | ------------- | | alert_type | Type of the triggered alert - can be one of the currently supported types: classification_change, sample_available, ticloud_analysis_complete, ticloud_upload_complete, cuckoo_analysis_complete, yara_match | string | | category | File category of the sample for which the alert was triggered, expressed as a number. The numbers correspond to the following categories: 0 - Other, 1 - Application, 2 - Mobile, 3 - Document, 4 - Web, 5 - Archive, 6 - Media, 7 - Email | integer | | classification | Classification of the sample in human-readable format. | string | | threat_status | Threat status assigned to the sample that triggered the alert, expressed as a number. The numbers correspond to the following threat statuses: 0 - No Threats Found, 1- Good, 2 - Suspicious, 3 - Malicious | integer | | classification_reason | Reason for the classification that the sample received, expressed as a number. The numbers correspond to the following classification reasons: 0 - No Threats Found, 1 - Antivirus, 2 - Signature, 3 - Certificate, 4 - Format, 5 - Exploit, 6 - YARA, 7 - RHA1, 128 - User, 256 - Cloud | integer | | threat_name | Detected malware threat name for the sample that triggered the alert (for example, Win32.Trojan.Adams). | string | | classification_source | Source of the classification for the sample that triggered the alert, expressed as a number. The numbers correspond to the following sources: 0 - None, 1 - Spectra Intelligence, 2 - [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis), 4 - User, 257 - Spectra Intelligence from Parent, 258 - Spectra Core from Parent, 260 - User from Parent, 513 - Spectra Intelligence from Child, 514 - Spectra Core from Child, 516 - User from Child | integer | | description | The full description of the triggered alert, as displayed in the *Details* column on the Alerts page. Depending on the alert, it may include the username of the user who submitted the sample for analysis, the analysis duration, analysis parameters, or the reasons the analysis failed (for example, "Static Intelligence Analysis Started for 72bbd2513901b1bda0f3a0fdc257d347531a8e7a by admin" or "Threat Intelligence analysis complete with classification Goodware."). | string | | string | | factor | The risk score value, expressed as a number from 0 to 10, where 0 indicates the most trusted samples, and 10 indicates the most dangerous threats. | integer | | family_name | The malware family name part of the threat name detected for the sample (for example, Marsdaemon, Orcus, Androrat…). | string | | file_size | Size of the sample for which the alert was triggered, expressed in bytes. | integer | | file_subtype | Subtype of the sample for which the alert was triggered, as detected by ReversingLabs static analysis (for example, TIFF, Clojure, HTML…). [See full list of file subtypes](./advanced-search.md#supported-file-types-and-subtypes) | string | | file_type | Type of the sample for which the alert was triggered, as detected by ReversingLabs static analysis (for example, Document, Image, PE…). [See full list of file types](./advanced-search.md#supported-file-types-and-subtypes) | integer | | hostname | Hostname of the system on which the sample that triggered the alert was analyzed or submitted. | | identification_name | Identification of the sample for which the alert was triggered, as detected by ReversingLabs static analysis. Identification is not generated for all file types and subtypes; it is an optional field in the static analysis report that indicates a more detailed (usually signature-based) file detection. | string | | identification_version | Version of the identified file format for the sample that triggered the alert (for example, Generic, 1.0, Container…). This is an optional field that is not generated for all file types and subtypes. | string | | json | Returns all available information about the alert, serialized in JSON format. | string | | label | Name of the alert subscription provided in the *Name* field of the *New Subscription* dialog. Users can modify the name for all alert subscriptions on the appliance. | string | | malware_type | The malware type part of the threat name detected for the sample that triggered the alert (for example, Trojan, Adware, Rootkit…). | string | | platform | The platform part of the threat name detected for the sample that triggered the alert (for example, Win32, Script-PHP, Linux…). | string | | sha1 | SHA1 hash of the sample for which the alert was triggered. | string | | subplatform | The subplatform part of the threat name detected for the sample that triggered the alert (for example, HTML, Macro, PDF…). The subplatform part is present in the threat name only for specific platforms (ByteCode, Document, Script). | string | | timestamp | Date and time when the alert was triggered. | UTC timestamp | | uuid | Unique string identifying the triggered alert. | string | ### Modifying Existing Alert Subscriptions Only the user who created a subscription can modify it. To modify an existing alert subscription, click the *Edit* link next to the subscription name in the *Subscriptions* tab on the *Subscriptions and Actions Management* page. The dialog that opens is the same as for [creating a new subscription](#creating-a-new-alert-subscription). Here you can enable more, or modify any existing event types, or add/remove delivery methods. If a YARA ruleset with an active subscription gets deleted from the appliance, the dialog will warn the user when modifying the subscription for the missing ruleset. ### Deactivating Alert Subscriptions There are several ways to deactivate an existing alert subscription. 1. Click the *Edit* link next to the subscription name in the *Subscriptions* tab. In the dialog that opens, modify the *Actions* field and remove all selected actions from it. The subscription itself remains on the appliance, and can be reactivated at any point by adding new actions. 2. Click the *Delete* link next to the subscription name in the *Subscriptions* tab. This completely removes the subscription from the appliance. Alerts for the removed subscription will no longer be sent. ## Managing Alerts The Alerts page displays all generated events on the appliance. Users receive alert emails only for those events that match the criteria defined in their subscriptions. Alerts are displayed in a list and sorted by the time when they occurred (in descending order, with newest alerts at the top). The list contains information about every alert, including: - alert resolution status (unresolved alerts are indicated by a blue stripe to the left of the table) - type of alert; - threat status indicator of the sample associated with the alert; - time when the alert was triggered; - full notification text - threat name (if detected); - file format and size; ![Overview of the Alerts page](images/analyze-alerts-page.png) Clicking the sample name in the notification column opens the [Sample Details](./Sample%20Details/sample-details-summary.md) page for the selected sample. Clicking any of the sample rows will expand it, showing additional information about a sample like in other pages on the appliance. The action menu (☰) to the right of the *Resolved* column contains the *Configure* item, which opens the [Subscriptions and Actions Management page](#managing-alerts). The total amount of triggered alerts on the appliance is displayed in the pagination section at the bottom of the page. ### Filtering Alerts The toolbar above the list of alerts allows the users to filter alerts: - by status (All, Resolved, Unresolved) - by event type (All, Classification change, Sample available for download, YARA match, Cuckoo analysis complete, Spectra Intelligence upload complete, Spectra Intelligence analysis complete); - by classification of the sample associated with an alert (All, Unknown, Goodware, Suspicious, Malicious); - by the time when the alert was triggered (All, Custom, Today, Last Week…); - by user or by alert subscription When a subscription is deleted from the appliance, it is no longer visible in the user/subscription filtering menu. However, alerts triggered by that subscription will still be visible when the *My Alerts* option is selected. ![Subscriptions menu that allows filtering alerts by user-created subscriptions](images/analyze-alerts-my-alerts.png) Filters can be combined to get a more precise overview of the triggered alerts (for example, show all YARA match alerts for subscriptions created this week that returned malicious samples). When the *Classification change* alert type is selected in the toolbar, there is an additional option to choose which classification changes should be listed (for example, from no threats found to malicious or from suspicious to malicious). For the *YARA match* alert type, an additional field *Enter ruleset name* becomes available, allowing users to display only the alerts related to a specific YARA ruleset. ### Exporting Alerts The *Export* pull-down menu in the toolbar allows copying the list of SHA1 hashes or exporting the list of alerts as a CSV file. Users can select which columns should be included in the exported CSV file. Only the current page will be copied/exported, not the entire list of all alerts on the appliance. The number of alerts per page - that is, the number of alerts that will be included in each exported file - can be increased or decreased in the navigation bar at the bottom of the Alerts page. ### Marking Alerts as Resolved When an incoming alert has been acknowledged and dealt with, it is possible to mark it as *Resolved* to keep the Alerts page up-to-date. To mark an alert as *Resolved*, select the *Resolve* option in the action menu on the right. The blue highlight will then be removed from the alert. ![Triple bar menu on the Alerts page with the Resolve option highlighted](images/analyze-alerts-resolve.png) It is also possible to resolve multiple alerts at once. This is done by selecting several alerts and choosing the *Resolve selected* option from the topmost action menu (☰) in the Alerts page toolbar. Only the current page of alerts can be resolved. Up to 1000 alerts can be resolved at once by increasing the amount of alerts per page in the navigation toolbar to 1000, then selecting and resolving all alerts on the page. When the selected alerts are resolved, a notification appears with the total number of resolved alerts. If some alerts had previously been resolved, the appliance will detect this and will not count them towards the total. Filtering the Alerts page by resolution status will show only resolved alerts, hide resolved alerts, or show all alerts on the appliance. The filter can also be used to show and export all resolved alerts as described in the [Exporting Alerts](#exporting-alerts) section. Users can also undo the alert resolution by clicking *Unresolve* (for a single alert) or *Unresolve Selected* (for multiple alerts) in the action menu on the Alerts page. ### Automatically Removing Alerts **Only appliance administrators can enable this option.** Users who would like to enable this option should contact their appliance administrator. Depending on the number of alert subscriptions configured on the appliance, alerts can quickly accumulate, making it difficult to browse the Alerts page. To prevent this, appliance administrators can define how long the alerts should be kept on the appliance. When the alerts are older than the configured period, they are automatically removed from the appliance. The alert retention period can be configured in the **Administration > Configuration > Alert Management** dialog. By default, alerts are kept for 3 months and automatically deleted after that period. Other supported options are 1 month and 6 months. ## Monitoring Samples with Alerts Apart from creating and editing alert subscriptions on the [Subscriptions and Actions Management page](#managing-alerts), users can quickly modify subscriptions by adding new samples from different sections of the GUI. This is useful for adding interesting samples to an existing alert, or for creating a new alert that will monitor the activity on multiple samples. The following table lists the interface sections where samples can be added to a subscription using the *Subscribe* option, or removed from a subscription using the *Unsubscribe* option. The table also indicates which sections support bulk actions (adding/removing multiple samples to/from a subscription). | Section | Supported Alert Types | Bulk Actions | | -------------------------------- | ---------------------------------------------------- | ------------ | | Advanced Search Results - Local | Classification change, Sample available for download | Yes | | Advanced Search Results - Cloud | Classification change, Sample available for download | Yes | | YARA ruleset matches | Classification change, Sample available for download | Yes | | Sample Details | Classification change, Sample available for download | No | | Sample Details > RHA results | Classification change, Sample available for download | Yes | | Sample Details > Extracted Files | Classification change, Sample available for download | Yes | | Tags | Classification change, Sample available for download | Yes | To start monitoring a sample, open the action menu (☰) on the right side of the sample and select the *Subscribe* option. ![Section of the Spectra Analyze Web Interface with Subscribe option highlighted in the Sample Actions menu](images/analyze-alerts-subscribe.png) This opens the *Subscribe to Hash Alert* dialog that allows creating a new alert or selecting an existing alert from the pull-down list. Supported alert types are **Classification change** and **Sample available for download**. The dialog for creating a new alert is the same as in the [Creating a New Alert Subscription](#creating-a-new-alert-subscription) section. If an existing alert is chosen in the pull-down list, the SHA1 hash of the selected sample is automatically added to the alert subscription. Users can then modify other fields in the subscription dialog, such as actions, before clicking *Submit* to save changes. ### Subscribing to Samples in Bulk It is also possible to add more than one sample to an existing subscription, or to create a new subscription that will monitor several samples. When multiple samples are selected on a page, the bulk actions menu (☰) is available in the header row of the sample list. To add the selected samples to an alert subscription, click the *Subscribe* item in the bulk actions menu. Sample hashes can also be added to an existing alert subscription manually. To do that, access the *Subscriptions* tab on the [Subscriptions and Actions Management page](#managing-alerts) and click the *Edit* link next to the desired subscription. In the dialog that opens, paste the SHA1 sample hashes into the *Sample hash values* text field and click *Submit*. Each hash should be in its own line in the text field. ### Removing Samples from Alert Subscriptions Samples can also be removed from existing subscriptions. To remove one or more samples, use the *Unsubscribe* item from the sample action menu (or the bulk actions menu, if two or more samples are selected). A dialog appears, prompting the user to confirm the action. Clicking *Unsubscribe* in the confirmation dialog removes the selected sample hashes from all subscriptions to which they were added. The subscriptions themselves are not removed or deactivated, and if they were configured to monitor other samples, the alerts will still be sent out for those samples. Alternatively, samples can be removed from alert subscriptions manually, by editing the subscription from the *Subscriptions* tab. Click the *Edit* link next to a subscription, and in the dialog that opens, remove sample hashes from the *Sample hash values* text field. ## Tracking Unknown Hashes with Alerts When searching for sample hashes on the appliance, the results can sometimes include unknown hashes. Those are hashes of samples that have not yet been found in the ReversingLabs system, or that are not available locally. (Note: this does not refer to hashes found in the system, but classified as Unknown.) If the list of search results includes unknown hashes, they will be listed separately and accessible by clicking the *Not Found* filter/tab on the search results page. Users can subscribe to those hashes and get notified when they appear in the ReversingLabs system for the first time. Supported alert types for unknown hashes are **Classification change** and **Sample available for download**. Unknown hashes can be added to new or existing alert subscriptions in the same way as described in the [Monitoring Samples with Alerts](#monitoring-samples-with-alerts) section. ## Setting Up Alerts for New YARA Ruleset Matches The list of YARA rulesets on the YARA page also integrates with the Alerts feature. Apart from subscribing to individual samples from the list of matches on a YARA ruleset, it is also possible to subscribe to rulesets themselves. This type of alert is triggered when there is a new match for the subscribed ruleset. To subscribe to a YARA ruleset from the YARA page, open the action menu (☰) on the right side of the ruleset and select the *Subscribe* option. This opens the [New Alert dialog](#creating-a-new-alert-subscription) with the YARA Matches event type enabled, and the selected YARA ruleset automatically filled in. Alternatively, users can create YARA ruleset match alert subscriptions from the [Alerts Configuration page](#managing-alerts). --- ## Advanced Search API — Query Samples on Spectra Analyze ``` POST /api/samples/v3/search/ ``` ## Search for samples Search for samples available on the local Spectra Analyze instance and Spectra Intelligence using the Advanced Search capabilities. Users can authenticate with their regular [Spectra Analyze tokens](./tokens.md). - All [restricted words and characters](../advanced-search.md#restricted-words-and-characters) must be escaped with double quotation marks. - All datetime fields are in UTC format: YYYY-MM-DDThh:mm:ssZ. - The default and only supported response format is JSON. - Requests must contain the HTTP header field with *Content-­Type: application/json*. - By default, the API returns 20 samples per page. ### Request Format ```json { "query": ": : ...", "page": 1, "records_per_page": 20, "sort": " desc" } ``` **Request Parameters** | NAME | DESCRIPTION | REQUIRED | | :---------------- | :----------------------------------------------------------- | :-------------------------------------- | | query | String representing the search expression. | Yes | | ticloud | Show only cloud results in the response. This parameter is false by default. If omitted, the response will show only local results. | No | | page | If more than ```` records match the requested criteria, the response will have a next_page value, which can be used in the request to fetch the next page with up to ```` results. This is the value defining which page of results to return in the response. Defaults to first page (1) if omitted. | No | | records_per_page | Value defining how many results should be returned per page. Defaults to 20 if omitted. Maximum value is 100. | No | | sort | String that allows sorting the results by one of the supported fields: **sha1**, **firstseen**, **threatname**, **sampletype**, **filecount**, **size**. The results can be sorted in ascending or descending order by using the *asc* or *desc* keywords. By default, the results are sorted by **firstseen** in descending order (most recent to oldest). | No | | start_search_date | The starting date for the search. This parameter represents the later date, as searches are performed backwards in time. | Only used if `ticloud` is set to `true` | | end_search_date | The ending date for the search. This parameter represents the earlier date, as searches are performed backwards in time. | Only used if `ticloud` is set to `true` | ### Using time range parameters Both time range parameters should be formatted as strings in the “YYYY-MM-DD” format. For further granularity, the `firstseen` keyword can be used to specify a particular time of day. Search queries progress backward in time, meaning that results are first returned closer to the `end_search_date`. Both `start_search_date` and `end_search_date` are included in the search, allowing the query to return results for both dates, if available. It is possible that the query only returns results until some point in time, instead of for the whole given time range. In that case, the `last_search_date` parameter will be returned, which can be used as `end_search_date` in the next query. **Note:** The **last_search_date** is not included in search. When the `end_of_dataset` parameter is returned in the response, it means that the query found all samples which meet the search criteria in the given time range. This parameter applies only to Cloud searches, and should be ignored in local queries. **Note:** Time range parameters are not supported for `tlsh` and `ssdeep` similarity queries. Any provided time range values are ignored for these search types. ### Advanced Search Queries The *query* field contains the search expression that will be submitted to the API. Every search expression must contain at least one keyword and one value. Search expressions are built according to the following formula: ``:``. Supported values for *field_name* correspond to [keywords currently supported by Advanced Search](../advanced-search.md#supported-search-keywords). For *field_value*, the following are supported: - equals operator - to search for exact matches (classification:malicious, available:true…) - range operator - to search for closed ranges of values, including the upper and lower boundary (firstseen:[2018-01-01T00:00:00Z TO 2018-01-02T00:00:00Z]) or open-ended ranges indicating greater/less-than values (threatlevel:[0 TO *]) - in operator - to search for any value in the specified list (classification:[malicious, suspicious]) - [wildcard symbols](../advanced-search.md#using-wildcards-for-partial-matching) - for search keywords that support them (av-detection:*crypto) It is also possible to use [operators and multi-keyword combinations](../advanced-search.md#creating-multi-keyword-search-queries). **Search Query Example** ```json { "query": "firstseen:2018-01-01T00:00:00Z (av-detection:trojan AND type:binary NOT positives:[* TO 3])" } ``` ### Request Examples Format of the POST request body: ```json { "query":"classification:[malicious, suspicious]", "records_per_page":10, "start_search_date":"2023-01-01", "end_search_date":"2023-07-01", "ticloud":True } ``` `Query` contains all the keywords related to the sample, while the other fields specify the format of the response. **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/samples/v3/search/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{"query":"classification:[malicious, suspicious]","records_per_page":10,"start_search_date":"2023-01-01","end_search_date":"2023-07-01","ticloud":True}' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://appliance.example.com/api/samples/v3/search/" json = {"query":"classification:[malicious, suspicious]","records_per_page":10,"start_search_date":"2023-01-01","end_search_date":"2023-07-01","ticloud":True} headers = {'Authorization': f'Token {token}'} # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, json=json) print(response.text) ``` ### Response Format ```json { "rl":{ "web_search_api":{ "next_page":2, "more_pages":true, "sample_count":10, "entries":[ { "sha1":"465aa6e49e02cd677924a6c4486f82f53a6a90f1", "sha256":"92fdba6367ea91001515b3b1a0a47892fb04a3606fe7c339a95431ea71467c43", "md5":"d35bd156250608f3a182fe75a72cd032", "filename":"_00145", "antivirus":28, "firstseen":"2023-07-01T23:59:59Z", "lastseen":"2023-07-04T08:05:19Z", "available":true, "size":52175, "sampletype":"PE/Exe", "classification":"malicious", "threatname":"Win32.Worm.Eggnog", "factor":10, "filecount":0 }, "..." ], "last_search_date":"2023-06-30", "end_of_dataset":false } } } ``` If the ticloud parameter is set and the available field is true, the sample is shareable in the Spectra Intelligence cloud, but if it is false, the sample is private. The `total_count` field will be returned only if `"ticloud"=false`. Total sample count for Spectra Intelligence data must be retrieved with the Total Count endpoint documented below. **Additional fields for similarity searches** When the query uses the `tlsh` or `ssdeep` keyword, each entry in the response includes the following additional fields: | FIELD | DESCRIPTION | | :---- | :---------- | | `sim_score` | Similarity score on a scale from 0 to 100, where higher values indicate greater similarity. | | `tlsh_distance` | Original TLSH distance value. Returned only for `tlsh` queries. Lower values indicate greater similarity. | | `ssdeep_score` | SSDEEP match score on a scale from 0 to 100. Returned only for `ssdeep` queries. | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | OK | | 400 | Bad request. E.g. invalid value for a field, or other validation error. | | 403 | Forbidden. This response is returned when the request isn’t authenticated. | | 404 | Not found. E.g. wrong URL. | ## Total Count ``` POST /api/samples/v3/search/total-count ``` This endpoint returns total counts for samples present in the Spectra Intelligence cloud. It always behaves as if the `ticloud` parameter is set to `true`. Total counts for local samples are returned in regular search query responses as the `total_count` field, if `ticloud=false`. It supports single queries and follows the same rules as the search query endpoint. Bulk queries return response code 400 with the message “Bulk query not supported on total count endpoint”. Since the total count query goes backwards in time, it is possible that the `total_count` query only returns count until some point in time, instead of for the whole given time range. In that case, the `last_search_date` parameter will be returned, which can be used as `end_search_date` in the next query. Note: **last_search_date** is not included in the count. **Request Format** ``` { "query": ": : ...", "start_search_date": "YYYY-MM-DD", "end_search_date": "YYYY-MM-DD" } ``` **Request Parameters** | NAME | DESCRIPTION | REQUIRED | | :---------------- | :----------------------------------------------------------- | :------- | | query | String representing the search expression. Refer to the Advanced Search endpoint documentation above for more information. | Yes | | start_search_date | The starting date for the search. This parameter represents the later date, as searches are performed backwards in time. | Yes | | end_search_date | The ending date for the search. This parameter represents the earlier date, as searches are performed backwards in time. | Yes | ### Request Examples ```json { "query":"classification:[malicious, suspicious]", "start_search_date":"2023-01-01", "end_search_date":"2023-07-01", } ``` #### Response Format ```json { "total_count": 1510377, "last_search_date": "2023-06-30", "end_of_dataset": false } ``` --- ## Classification Status API — Spectra Analyze ## Retrieve classification status for a sample ``` GET /api/samples/v3/{hash_value}/classification/ ``` Get classification results for a sample. The sample must be present on the appliance. By default, if the requested sample is not found on the appliance, or if **classification** for the sample is “UNKNOWN”, the API automatically sends a request to Spectra Intelligence for any classification information and return it in the response. The prerequisite for this functionality is a properly configured Spectra Intelligence account on the appliance. To disable automatic Spectra Intelligence querying, the optional parameter `localonly` can be used in the request. When set to `localonly=1`, it specifies that only local classification data should be returned for the sample, without falling back to querying Spectra Intelligence. Queries from the appliance to Spectra Intelligence are limited to 10 000 requests per day. If the user makes 10 000 requests to Spectra Intelligence via this endpoint (by querying hashes that don’t exist on the appliance), the endpoint will respond with a 429 HTTP status code until the start of the next calendar day (00:01 UTC). **Important: Spectra Intelligence queries for samples that exist on the appliance, but don’t have a local classification (samples with *Unknown* status) **do not count** towards the daily limit. Spectra Intelligence queries for samples that don’t exist on the appliance are the only ones that count towards the limit.** ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :---------- | :------- | :----------------------------------------------------------- | :------------ | | hash_value | Required | Hash of the sample for which the classification status should be returned. Only one hash can be submitted in one request. Supported hash types: SHA1, SHA256, MD5 | path, string | | localonly | Optional | Defines the source of the classification data to be returned. Supported values: 0, 1. If it is set to 1, automatic requests to Spectra Intelligence are disabled, and `av_scanners=1` cannot be used in the same request. If the parameter is omitted from the request, or submitted with the value of 0 (default), the API returns classification status for samples on the Spectra Analyze appliance. If the requested samples are not found on the appliance, it automatically sends a request to Spectra Intelligence. If the parameter is submitted with the value of 1, the API returns classification status only for samples on the appliance and does not send requests to Spectra Intelligence. | query, string | | av_scanners | Optional | Specifies whether to include the AV scanners summary information in the response. Supported values: 0, 1. If the parameter is omitted from the request, or submitted with the default value of 0, the AV scanners metadata is not included in the response. When set to 1, AV scanners metadata is included in the response. The API first looks for any existing local metadata. If there is no local metadata, a request is sent to Spectra Intelligence. **This request counts towards the Spectra Intelligence usage quota.** This parameter cannot be used with `localonly=1` in the same request, because that disables requests to Spectra Intelligence. | query, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/samples/v3/cf8e42c4a0862c807f0de3c656d2cd1c99cc5a27/classification/' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the host name in the URL and the fields to be included in the response url = f"https://appliance.example.com/api/v2/samples/{hash_value}/classification/" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` **Python with optional parameters** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the host name in the URL and the fields to be included in the response url = f"https://a1000.example.com/api/v2/samples/{hash_value}/classification/?av_scanners=1" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Examples** Default response ```json { "classification": "malicious", "riskscore": 10, "first_seen": "2014-08-27T04:35:43Z", "last_seen": "2016-04-30T04:11:00Z", "classification_result": "Win32.Backdoor.Poison", "classification_origin": { }, "classification_reason: "CLOUD" } ``` Response when the requested sample is not found on the appliance ```json { "message": "Hash not found.", "hash_value": "3d879d037184b17e47bc3391ff6c0b72" } ``` **Response Fields** | FIELD NAME | TYPE | DESCRIPTION | | :-------------------- | :------ | :----------------------------------------------------------- | | sha1 | string | SHA1 hash of the sample | | sha256 | string | SHA256 hash of the sample | | md5 | string | MD5 hash of the sample | | classification | string | Indicator of sample status (MALICIOUS, SUSPICIOUS, GOODWARE, UNKNOWN) | | riskscore | integer | Risk score value of the sample (0-10, lowest to highest) | | first_seen | string | UTC date-time (example: “2014-08-27T04:35:43Z”) | | last_seen | string | UTC date-time (example: “2014-08-27T04:35:43Z”) | | classification_result | string | RL normalized threat name (example: “Win32.Backdoor.Poison”) | | classification_origin | object | List of hashes that the sample classification came from. Returns null if the request has been made directly to Spectra Intelligence, or if Spectra Intelligence has not been queried for local samples. | | classification_reason | string | Indicates the reason for the sample’s classification. Can be one of the following: UNKNOWN, THREAT REPUTATION, SIGNATURE, CERTIFICATE, FORMAT, EXPLOIT, YARA, RHA1, USER, CLOUD | | cloud_last_lookup | string | Timestamp when the last response from Spectra Intelligence was received (if the sample resides on the appliance). Returns null if the request has been made directly to Spectra Intelligence, or if Spectra Intelligence has not been queried for local samples. | | data_source | string | Indicates the source of the provided data set - either the appliance or Spectra Intelligence. | | av_scanners | object | Returned only if the `av_scanners=1` parameter is included in the request. Provides information about AV scanner count, matches, and percentage for the requested sample. Corresponds to the `av_scanners_summary` object from the [Sample Details API](./full-report-api.md) response. | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | This response is returned even when the sample is not found on the appliance. | | 403 | This response is returned when the request isn’t authenticated. | | 404 | Invalid or malformed hash. | | 429 | Too many requests (daily Spectra Intelligence query max limit reached). | | 503 | Service unavailable (Spectra Intelligence API-related errors, i.e., Unauthorized). | --- ## Containers API — Spectra Analyze ## List containers for every requested hash ``` POST /api/samples/containers/ ``` Get a list of all top-level containers from which the requested sample has been extracted during analysis. This is a bulk API, meaning that a single request can be used to simultaneously query containers for multiple file hashes. If a requested hash doesn’t have a container, it will not be included in the response. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :---------- | :------- | :----------------------------------------------------------- | :----- | | hash_values | Required | A list of one or more hash values for which to retrieve the top-level container hashes. The hashes in the request can be SHA1, SHA256, or MD5, but must all be of the same type. | string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/samples/containers/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{"hash_values":["9dc5e23c7ab2692b83f0690a736b123a1837ae56", "4b21a49eadac1bc01477eff778041fdb765b8139"]}' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://appliance.example.com/api/samples/containers/" json = { "hash_values": ["examplehash1", "examplehash2"] } headers = {'Authorization': f'Token {token}'} # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, json=json) print(response.text) ``` ### Response Format **Response Examples** ```json { "count": 1, "next": null, "previous": null, "results": [ { "sha1": "68f04f6ecbf628029e4e0061392029edec2b0e43", "sha256": "cb7421b5c6af74c3159c361f3bb78bba8a488d8979d1250e106fa96cbf928789", "sha512": "689e93297dca84a0d63d7934d3fd233b7c90e5270693564e7ac2fe2c6b6a60d40e082446d7ec1aa04c4f954f5fff130eae2f0407e915a109fc854afbea902aac", "md5": "1021657335ba4838db07f5231723df3b", "containers": [ "b3af773210970296f69733eba53e88d2bd449630", "ffaf7dfd50471b28b7e8533ea866ec06066a3c80", "1005def47073d5b7b19c99a8bd0cff153d0626aa", "c6a9457236ce673cecfdaa3b01f4dbf79a1e3b75", "997af5d888b8e95d985eafc36d8abb7269ddae51" ] } ] } ``` **Response Fields** | FIELD NAME | DESCRIPTION | | :--------- | :----------------------------------------------------------- | | count | The number of hashes with results. Hashes without results are not included in the response. | | results | The list of results: for every hash with top-level containers, every object contains the `sha1`, `sha25`, `sha512` and `md5` hashes of the requested sample, and a list of container hashes inside the `containers` object | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------- | | 200 | OK | | 400 | Bad Request | | 404 | Not Found | --- ## Delete API — Remove Samples from Spectra Analyze ## Delete a sample ``DELETE /api/samples/{hash_value}/`` Delete the sample with the requested hash value. All related data, including extracted samples and metadata, will be deleted from the Spectra Analyze instance. **Note:** there are two exceptions when the sample will not be deleted: 1. when the requested hash matches an extracted file rather than an independently uploaded sample 2. when the requested hash matches an uploaded sample that is currently being processed In these cases, the `405 Method Not Allowed` status code is returned in the response for SHA1 hashes. The 404 status code is returned instead of 405 for MD5 and SHA256 hashes. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--------- | :------- | :----------------------------------------------------------- | :----------- | | hash_value | Required | Hash of the sample that should be deleted from the appliance. Only one hash can be submitted in one request. Supported hash types: SHA1, SHA256, SHA512, MD5 | path, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X DELETE 'https://appliance.example.com/api/samples/00d33e57051fdd38407b9251bf2843645d567342/' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of hash_value and token hash_value = "examplehash" token = "exampletoken" # Change the hostname in the URL url = f"https://appliance.example.com/api/samples/{hash_value}/" headers = {'Authorization': f'Token {token}'} # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.delete(url, headers=headers) print(response.text) ``` ### Response Format **Response Examples** ```json "code": 200, "message": "Sample deleted successfully.", "detail": { "md5”: "07958b6f37e9f49ca71c3b4ebf755d26" "sha1": "00d33e57051fdd38407b9251bf2843645d567342" "sha256": "0249d5eeeca4c373af785047f7ac488f1632a20ee97acdba81b1bcbb89cf6b86" "sha512": "1bbe06bcc7052503f65ed4ae2e4c93e4875170b7863 …" } } ``` **Empty response** When trying to delete a sample that does not exist on the Spectra Analyze instance, an empty response is returned. ``` { "message":"Not found.", "code":404, "detail":{} } ``` **Response Fields** | FIELD NAME | TYPE | | :--------- | :------ | | code | integer | | message | string | | detail | object | `detail`: | FIELD NAME | TYPE | | :--------- | :----- | | sha1 | string | | sha256 | string | | sha512 | string | | md5 | string | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------- | | 200 | OK | | 404 | Not Found | | 405 | Method Not Allowed | ## Delete multiple samples **Important: The API should be used with caution, because using it simultaneously with other actions such as uploading or reanalyzing samples may cause issues.** This API provides two endpoints: - Endpoint 1 is used to send a list of samples that should be removed. - Endpoint 2 is used to check the status of the sample removal task. ### Request removing samples ``` POST /api/samples/v2/delete_bulk/ ``` Endpoint 1 accepts a POST request with a list of sample hashes to be deleted from the Spectra Analyze appliance. Sample removal is initialized as an asynchronous task. Requested samples, their extracted files, and all their metadata are deleted from the appliance database and from the disk. Samples that cannot be deleted will be skipped. The response to the POST request contains the ID of the removal task. This ID can then be used in a GET request to Endpoint 2 to check the status of the removal task. The status can be checked for up to 36 hours from the moment the task is initialized. #### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :---------- | :------- | :----------------------------------------------------------- | :---------- | | hash_values | Required | Hash of the sample(s) that should be deleted from the appliance. At least one hash must be provided in the request. Different hash types can be used in a request. Supported hash types: SHA1, SHA256, MD5 | form, array | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/samples/v2/delete_bulk/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{"hash_values":["988881adc9fc3655077dc2d4d757d480b5ea0e11", "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15"]}' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://appliance.example.com/api/samples/v2/delete_bulk/" json={"hash_values": ["988881adc9fc3655077dc2d4d757d480b5ea0e11", "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15"]} headers = {'Authorization': f'Token {token}'} # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, json=json) print(response.text) ``` #### Response Format **Response Examples** ```json { "id": "516164e6-4e4a-b18c-0cc51a1368d2" } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :--------------------------- | | 200 | Task successfully initiated. | | 400 | Validation error. | ### Check sample removal status ``` GET /api/samples/v2/delete_bulk/status/?id={task_id} ``` The second endpoint accepts a GET request with the required *id* parameter. The value of this parameter should match the *id* value returned in the response to the POST request previously sent to Endpoint 1. The sample removal task may not delete all requested samples, even if the request is successful. Likewise, even if the request fails, some hashes may still be deleted from the appliance. The response to the GET request contains information about the status of the sample removal task, expressed as a standard status code and a descriptive message. Additionally, it can contain the *details* section, listing which hashes from the POST request are currently (not) present on the appliance. #### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :------ | :------- | :----------------------------------------------------------- | :------------ | | task_id | Required | The ID of the sample removal task. Use the *id* value from the **Endpoint 1** response with this parameter. | query, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/samples/v2/delete_bulk/status/?id=1234' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of url, token, and ID token = "exampletoken" ID = "123" # From the response of the bulk delete API url = f"https://appliance.example.com/api/samples/v2/delete_bulk/status/?id={ID}" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` #### Response Format **Response Examples** ```json { "msg": "Task {task_id} finished successfully. Note: this does not necessarily mean that all requested samples were deleted. See detail for samples that currently exist and samples that do not." "detail": { "samples_not_exists": [ "988881adc9fc3655077dc2d4d757d480b5ea0e11", "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15"], "samples_exists": [ "f14cede58a12140639e3cffbb7c6dc97ed74fd86"], } } ``` **Response Fields** | FIELD NAME | DATA TYPE | | :--------- | :-------- | | code | integer | | msg | string | | detail | array | | FIELD NAME | DESCRIPTION | TYPE | | :----------------- | :----------------------------------------------------------- | :----- | | samples_not_exists | Hashes that were requested to be deleted and are currently not present on the appliance. | string | | samples_exists | Hashes that were requested to be deleted and are currently present on the appliance. | string | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | Task finished. | | 202 | Task is still running. | | 404 | Task ID not found. | | 500 | Error while executing task. It is possible that some samples were deleted; check the response for more details. | --- ## Deprecated Endpoints — Spectra Analyze API ## Advanced Search API V2 **Important: This endpoint is kept for backwards compatibility. Users are advised to migrate to the [new version of the endpoint](./advanced-search-api.md). V2 does not support the new `start_search_date` and `end_search_date` parameters and doesn’t have the Total Count endpoint. The rest of the V3 documentation can be used for the V2 API.** ``` POST /api/samples/v2/search/ ``` ## V1.0 Obtain classification results for a local sample ``` GET /api/samples/{hash_value}/classification/?localonly=[1,0] ``` **Important: Users are advised to migrate to the [new version of the endpoint](./classification-status-api.md).** ## Delete a set of samples ``` POST /api/samples/delete_bulk/ ``` **Important: Users are advised to migrate to the [new version of the endpoint](./delete-api.md).** ## Obtain Spectra Intelligence File Reputation Classification results ``` GET /api/samples/{hash_value}/ticloud/ ``` **Important: Users are advised to migrate to the [upgraded endpoint](./classification-status-api.md).** ## Submit samples for analysis **Important: This endpoint is kept for backwards compatibility. Users are advised to migrate to the [new endpoints](./submissions.md) which provide additional options and parameters.** ``` POST /api/uploads/ ``` The Submissions API accepts a file or a URL to be analyzed. Only one file or URL can be submitted in a single request. For additional workflows, such as scanning entire [directories](), see our [SDK](https://github.com/reversinglabs/reversinglabs-sdk-py3) documentation and its [cookbook](https://github.com/reversinglabs/reversinglabs-sdk-cookbook). After submitting a file or URL, users can check the status of individual submissions by: - sending POST requests to [Processing Status API](./processing.md#check-status-of-submitted-files) - sending GET requests to [Check status of submitted URLs](./processing.md#check-status-of-submitted-urls) If the user submits a URL which links to a single file, the file is downloaded to the appliance in its original format (for example: PDF, EXE, RTF…). If the user submits a link to a website, the appliance uses a simple web crawler that retrieves the content up to 1 level from the submitted URL (including links to other domains). The scraped content is downloaded to the appliance in a single ZIP file. By default, submitted files and content downloaded from URLs are analyzed with the [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) static analysis engine built into Spectra Analyze. Additional analysis options depend on the configuration of the appliance (such as the enabled dynamic analysis services), and on the optional parameters provided by the user in the request. The duration of the analysis depends on the number of submitted files (or downloaded from the submitted URL), their sizes and file types, as well as the amount of files extracted during analysis, which are also analyzed separately. The timeout for URL submissions is 45 minutes. ### Supported analysis / crawling options **For sample submissions: Spectra Intelligence** To ensure that the sample receives a classification status other than *Unknown* (not classified), it is recommended to include the optional `analysis` parameter with the `cloud` value in the request. This will send the sample to Spectra Intelligence for scanning, which does not happen by default. The prerequisite for this is a properly configured Spectra Intelligence account on the appliance. **For URL submissions: Local / Spectra Intelligence** Depending on which crawling method parameter is provided, submitted URLs will be treated differently. - The `local` crawling method will treat the URL as any other locally submitted file, as a private submission. The contents of the URL will be crawled and downloaded directly. This method can be used without a Spectra Intelligence account. - The `cloud` crawling method is more reliable when working in restricted network conditions and ensures fewer failed URL analyses, but all submitted URLs and downloaded files will be treated as public, and will be visible and accessible to all Spectra Intelligence users. The prerequisite for this is a properly configured Spectra Intelligence account on the appliance. **Dynamic Analysis Services** Samples with supported file types can be automatically submitted to dynamic analysis services after they are uploaded to the appliance. This depends on the configuration of each dynamic analysis service on the appliance. For the CAPE Sandbox service, a sample can be automatically submitted if: - its file type matches the file types supported by and configured for the CAPE integration - it has not been analyzed by CAPE before, or the *Submit only distinct files to CAPE* option is disabled in the CAPE integration configuration dialog. If that option is disabled, all samples of supported file types can be submitted to CAPE for analysis. If that option is enabled, only the samples that have never been analyzed with CAPE can be submitted for analysis. If a file has been previously uploaded to Spectra Analyze and already analyzed with CAPE, it will not be automatically sent for analysis when uploaded again. However, it can be [manually submitted for reanalysis](../search-page.md#reanalyzing-files-and-urls). ### Submission restrictions The same privacy and file size restrictions apply when submitting files via this API as [when submitting them from the Spectra Analyze GUI](../file-submissions.md#file-size-restrictions). The maximum allowed size of data to download from submitted URLs can be configured by the appliance administrator. By default, it is limited to 200 MB. This refers to all data downloaded from a URL, not just to the size of a single file. By default, download requests from the appliance to a submitted URL time out after 300 seconds (5 minutes), and each download is reattempted 3 times. These restrictions are configurable by appliance administrators in the Administration ‣ Configuration ‣ URL Analysis dialog. ### Request Parameters | NAME | REQUIRED | DESCRIPTION | TYPE | | :------------------------ | :----------------------------------------------------------- | :----------------------------------------------------------- | :----------- | | file | Required if submitting a file, mutually exclusive with `url` | Contents of the file to upload to the appliance for analysis. Only one file can be submitted in a single request. If this parameter is used in the request, the `url` parameter cannot be used in the same request. | body, file | | url | Required if submitting a URL, mutually exclusive with `file` | URL from which the appliance should download the data and submit it for analysis. Only one URL can be submitted in a single request. If this parameter is used in the request, the `file` parameter cannot be used in the same request. The URL must be valid and include the protocol. Supported protocols are HTTP and HTTPS. | form, string | | analysis | Optional, works only with `file` | Comma-separated list of analysis types the sample should be queued for. Supported values: `cloud`. | form, string | | crawler | Optional, works only with `url` | Defines the crawling method that will be used to crawl the submitted URL. Supported values: `local`, `cloud`. The default crawling method is `cloud`. If omitting the parameter from their submission requests, users should contact their appliance administrator to check if this setting has been changed. | form, string | | archive_password | Optional | When submitting a password-protected archive, this parameter can be used to provide the password required to unpack it. If this parameter is provided in the request, the ZIP file must contain only one file. Upon successful extraction, only the extracted file will be uploaded, and the archive discarded. If the extracted file type is supported by the ReversingLabs Cloud Sandbox, and automatic uploading of files is enabled, it will be forwarded for dynamic analysis. | form, string | | rl_cloud_sandbox_platform | Optional | The platform to be used when executing the sample on the ReversingLabs Cloud Sandbox. Supported values: `windows7`, `windows10`, `windows11`, `macos_11`, `ubuntu_20`. Including this parameter will forward the sample to the ReversingLabs Cloud Sandbox even if automatic submission of samples is disabled. | form, string | | comment | Optional, works only with `file` | Optional comment to add to the uploaded sample. If added, the comment will be visible on the *Sample Details > Discussion* page. Supports the following HTML tags: `p`, `br`, `a`, `strong`, `b`, `em` and `i`. These tags are rendered in the UI. | form, string | | filename | Optional, works only with `file` | Explicitly set a filename for the uploaded file. If not provided, the default filename or SHA1 hash of the uploaded file is used as its name on the appliance. | form, string | | tags | Optional, works only with `file` | One or more User Tags to assign to the uploaded sample. If adding multiple tags, they should be comma-separated. Supported characters for tags are `[a-z0-9][a-z0-9 /._-]`. Tags are case-sensitive and distinguish spaces from underscores. In other words, `Example` and `example` are two separate tags; `test_tag` and `test tag` are separate tags, too. The total length of the submitted value(s) for this parameter must not exceed 42 characters. | form, string | ### Response Format #### Response Examples Response for a submitted file ```json { "code": 201, "message": "Done.", "detail": { "id": 1234, "sha1": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "user": 1, "created": "2015-06-18T12:01:15.123456Z", "filename": "test.txt", "href": "/88881adc9fc3655077dc2d4d757d480b5ea0e11" } } ``` Response for a submitted URL ```json { "code": 201, "message": "Done.", "detail": { "id": 22912, "user": 1, "created": "2020-05-13T10:07:07.933860Z", "filename": "https://www.example.com", } } ``` #### Response Fields | FIELD NAME | DESCRIPTION | TYPE | | :--------- | :------------------------------------------------------- | :------ | | code | Status response code | integer | | message | Informative message describing the status of the request | string | | detail | Additional details | object | | FIELD NAME | DESCRIPTION | TYPE | | :--------- | :----------------------------------------------------------- | :------ | | id | Identification number of the submission processing task on the appliance. For URL submissions, this value should be used with the [Check status of submitted URLs](./processing.md#check-status-of-submitted-urls) endpoint to check their status. | integer | | sha1 | SHA1 hash of the submitted file. This field is not returned for submitted URLs. | string | | user | Identification number of the Spectra Analyze appliance user who submitted the file or URL. | integer | | created | Timestamp indicating the date and time when the processing task was created on the appliance. | string | | filename | Automatically assigned filename for the submitted file or URL. For file submissions, this can be overrriden by explicitly specifying the filename in the request with the optional `filename` parameter. | string | | href | URL fragment that can be appended to the appliance hostname to access the sample analysis report directly on the appliance. This field is not returned for submitted URLs. | string | #### Response Status Codes | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 201 | Sample or URL successfully submitted for analysis. | | 400 | Bad Request. Validation error. Parameters in the request are invalid or missing. | | 403 | Authentication credentials are invalid or missing. | | 405 | It is not possible to upload samples while the appliance is in maintenance mode. | | 413 | Request Entity Too Large. File exceeds the maximum configured file size. | | 429 | This happens if system resources are depleted. This can mean that the system is using 90% or more of its available memory, or that it holds more than 50 items in the processing queue. The precise values are configurable (either on the *Administration > Configuration > Resource Usage Limits* page or via [Spectra Detect](/SpectraDetect/) Manager). Alternatively, this response may indicate that the Spectra Intelligence quota has been exceeded. | | 503 | The appliance storage space is close to being full. When there is less than 25% of free space on the disk, it is not possible to upload new samples until disk space is freed up. | ### Submitting a file #### Request Examples **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/uploads/' \ --header 'Authorization: Token exampletoken' \ --form 'file=@test.exe' # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://a1000.example.com/api/uploads/' \ --header 'Authorization: Token exampletoken' \ --form 'file=@test.exe' \ --form 'filename=custom-filename.exe' \ --form 'analysis=cloud' \ --form 'tags=tag1,tag2,tag3' \ --form 'comment=Custom comment' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://appliance.example.com/api/uploads/" files=[ ('file', ('test.exe', open('test.exe','rb'),'application/octet-stream')) ] headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, files=files) print(response.text) # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://a1000.example.com/api/uploads/" payload= { "filename": "custom-filename.txt", "analysis": "cloud", "tags": "tag1,tag2,tag3", "comment": "This is a custom comment" } files=[ ('file',('test.exe',open('test.exe','rb'),'application/octet-stream')) ] headers = {"Authorization": f"Token {token}"} # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, data=payload, files=files) print(response.text) ``` For additional workflows, such as scanning entire [directories](), see our [SDK](https://github.com/reversinglabs/reversinglabs-sdk-py3) documentation and its [cookbook](https://github.com/reversinglabs/reversinglabs-sdk-cookbook). ### Submitting a URL #### Request Examples **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/uploads/' \ --header 'Authorization: Token exampletoken' \ --form 'url=http://www.example.com' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://appliance.example.com/api/uploads/" payload = {'url': 'https://example.com'} headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, data=payload) print(response.text) ``` --- ## Download API — Download Samples from Spectra Analyze ## Download samples from Spectra Analyze to local storage ``` GET /api/samples/{hash_value}/download/ ``` Download a sample from Spectra Analyze to the local storage (compatible with modern ZIP tools such as `unzip` 6.00+, Python's `zipfile`, 7-Zip, or `bsdtar`) ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--------- | :------- | :----------------------------------------------------------- | :------------ | | hash_value | Required | Hash of the sample to download. Only one hash can be submitted in one request. Supported hash types: SHA1, SHA256, SHA512, MD5 | path, string | | fetch | Optional | If this parameter is provided in the request, samples not available locally will be downloaded from Spectra Intelligence, provided they are available and there’s enough free disk space on the appliance. Once downloaded, samples will be submitted for analysis on Spectra Analyze and downloaded to local storage. | query, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/samples/988881adc9fc3655077dc2d4d757d480b5ea0e11/download/?fetch' \ --header 'Authorization: Token exampletoken' \ --output ``` **Python** ```python # Change the values of hash_value and token hash_value = "examplehash" token = "exampletoken" # Change the hostname in the URL url = f"https://appliance.example.com/api/samples/{hash_value}/download/" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) with open("filename", "wb") as f: f.write(response.content) ``` ### Response Format **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | Download is successful | | 404 | Sample not found on the appliance, and is not available for download in the Spectra Intelligence cloud (in case the `fetch` parameter was used) | | 410 | Unable to retrieve sample content | | 503 | The appliance storage space is close to being full. When there is less than 25% of free space on the disk, it is not possible to upload or download new samples until disk space is freed up. | --- ## Dynamic Analysis Report API — Spectra Analyze This API allows creating and downloading PDF or HTML reports for samples that have gone through dynamic analysis in the [ReversingLabs Cloud Sandbox](../Analysis-services/cloud-sandbox.md). ``` GET /api/rl_dynamic_analysis/export/summary/{hash_value}/{format}/{endpoint}/ ``` ## Request Format ### Request Parameters All parameters are **path parameters** and all are required. | NAME | DESCRIPTION | | :----------- | :----------------------------------------------------------- | | `hash_value` | The hash value of the sample for which the dynamic analysis report should be returned. Supported hash types: **SHA1**. | | `format` | The format of the report. Supported types: `html`, `pdf`. | | `endpoint` | This parameter defines whether the report is being created or downloaded, or its status checked. Possible values: `create`, `download`, `status`. The request must end with a trailing forward slash (`/`) after this parameter. | ### Request Examples **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/rl_dynamic_analysis/export/summary/1eb64281e23c4af1b655f7f90b3d8bce723acaf7/pdf/download/ \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the host name in the URL and the fields to be included in the response url = f"https://appliance.example.com/api/rl_dynamic_analysis/export/summary/{hash_value}/html/create/" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` ## Response Format The `download` endpoint returns an HTML or PDF file. The other endpoints return a JSON response with relevant information. Depending on which endpoint is used, the following fields will be present: ```yaml properties: status: type: int message: type: string status_endpoint: type: string download_endpoint: type: string ``` ### Response Examples **Creation**: ```json { "status_endpoint": "/api/rl_dynamic_analysis/export/summary/1eb64281e23c4af1b655f7f90b3d8bce723acaf7/pdf/status/", "download_endpoint": "/api/rl_dynamic_analysis/export/summary/1eb64281e23c4af1b655f7f90b3d8bce723acaf7/pdf/download/" } ``` **Status check**: ```json { "status": 2, "message": "PDF is ready for download." } ``` --- ## Extracted Files API — Spectra Analyze ## List files extracted from a local sample ``` GET /api/samples/v2/{hash_value}/extracted-files/ ``` Get a list of all files the [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) engine extracted from the requested sample during static analysis. The requested sample must be present on the appliance prior to sending a request to this endpoint. If the requested sample doesn’t have any extracted files, an empty response body is returned with the status code 200. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--------- | :------- | :----------------------------------------------------------- | :------------ | | hash_value | Required | Hash of the sample for which the extracted files should be listed. Only one hash can be submitted in one request. Supported hash types: SHA1, SHA256, SHA512, MD5 | path, string | | page | Optional | Optional parameter used for pagination. When this parameter is omitted from the request, all available samples are returned at once. **This parameter cannot be used without** `page_size`. Use `page_size` to set how many samples should be on each page, and then specify which page to return with `page` in the same request. The `count` value in the response indicates the total number of samples. Use this number as guidance for pagination. The values of `page size` and `page` multiplied must not exceed the `count` value. For example, if `count` is 80 and `page_size` is set to 10, it is not possible to request `page=9`. | query, string | | page_size | Optional | Optional parameter that controls how many samples to return in the response. It can be used with or without the `page` parameter. When this parameter is included in the request, the response contains the `next` field with the link to the next page of results. When this parameter is omitted from the request, all available samples are returned at once. | query, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/samples/v2/cf8e42c4a0862c807f0de3c656d2cd1c99cc5a27/extracted-files/' \ --header 'Authorization: Token exampletoken' ``` **cURL with pagination** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://a1000.example.com/api/samples/v2/cf8e42c4a0862c807f0de3c656d2cd1c99cc5a27/extracted-files/?page_size=10&page=2' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the host name in the URL url = f"https://appliance.example.com/api/samples/v2/{hash_value}/extracted-files/" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Examples** ```json { "count": 5, "next": null, "previous": null, "results": [ { "id": 197, "parent_relationship": null, "sample": { "id": 192, "sha1": "9ef1d22739a73f659f6b6491690902a33bdfea5d", "sha256": "21b4f2da06f71e05f8c1c01093aae34231890e05ce366c98e3f09b6a7cdfc703", "md5": "63f6eb996dcc1d09eb7a73cde1f55179", "type_display": "PE/Exe", "category": "application", "file_type": "PE", "file_subtype": "Exe", "identification_name": "", "identification_version": "", "file_size": 267278, "extracted_file_count": 2, "local_first_seen": "2016-05-05T09:57:50.910412Z", "local_last_seen": "2016-05-05T13:43:21.282072Z", "classification": "malicious", "riskscore": 10, "classification_result": "Win32.Trojan.Bitman" }, "filename": "DeVuongHoi.exe", "path": "DeVuongHoi.exe" }, { "id": 198, "parent_relationship": null, "sample": { "id": 198, "sha1": "9ef1d22739a73f659f6b6491690902a33bdfea5d", "sha256": "21b4f2da06f71e05f8c1c01093aae34231890e05ce366c98e3f09b6a7cdfc703", "md5": "63f6eb996dcc1d09eb7a73cde1f55179", "type_display": "PE/Exe", "category": "application", "file_type": "PE", "file_subtype": "Exe", "identification_name": "", "identification_version": "", "file_size": 290816, "extracted_file_count": 1, "local_first_seen": "2016-05-05T09:58:27.096525Z", "local_last_seen": "2016-05-05T09:58:27.096525Z", "classification": "malicious", "riskscore":7, "classification_result": "Win32.Malware.YARA" }, "filename": "DieGroupv8.exe", "path": "DieGroupv8.exe" }, ... ``` **Response Fields** | FIELD NAME | TYPE | | :------------------ | :------ | | id | integer | | parent_relationship | string | | sample | object | | filename | string | | path | string | | FIELD NAME | DATA TYPE | | :--------------------- | :-------- | | id | integer | | sha1 | string | | sha256 | string | | md5 | string | | type_display | string | | category | string | | file_type | string | | file_subtype | string | | identification_name | string | | identification_version | string | | file_size | integer | | extracted_file_count | integer | | local_first_seen | string | | local_last_seen | string | | classification | string | | riskscore | integer | | classification_result | string | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------- | | 200 | OK | | 400 | Bad Request | | 403 | Forbidden | | 404 | Not Found | ## Download files extracted from a local sample ``` GET /api/samples/{hash_value}/unpacked/ ``` Download files extracted from the requested sample to the local storage. The files are obtained through the unpacking process during sample analysis with the Spectra Core static analysis engine. The requested sample must be present on the appliance prior to sending a request to this endpoint. Extracted files are downloaded in a single compressed archive file. If the requested sample doesn’t have any extracted files, the `404 Not Found` response is returned. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--------- | :------- | :----------------------------------------------------------- | :----------- | | hash_value | Required | Hash of the sample for which the extracted files should be downloaded. Only one hash can be submitted in one request. Supported hash types: SHA1, SHA256, SHA512, MD5 | path, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/samples/98a353d6d06cbdfd1146b3c917da9efacd90349c/unpacked/' \ --header 'Authorization: Token exampletoken' \ --output ``` **Python** ```python # Change the values of hash_value and token hash_value = "examplehash" token = "exampletoken" # Change the hostname to the one you use url = f"https://appliance.example.com/api/samples/{hash_value}/unpacked/" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) with open("filename", "wb") as f: f.write(response.content) ``` ### Response Format **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------------------------------------- | | 200 | OK | | 403 | Forbidden | | 404 | Sample not found | | 410 | Unable to retrieve extracted file content | --- ## Full Report API — Retrieve Complete Analysis Reports ## Retrieve a detailed analysis report for local samples ``` POST /api/samples/v2/list/details/ ``` Retrieve all or selected parts of the analysis report - including static, dynamic, and cloud analysis results - for one or more samples in a single request, instead of having to send requests to multiple endpoints. Report parts that can be requested correspond to sidebar sections on the [Sample Details](..//Sample%20Details/index.md) page. Sample hashes must be provided using the `hash_values` parameter in the request. The samples must be present on the Spectra Analyze appliance. Response speeds are highly variable based on the information available for each requested file. The optional `fields` parameter can be included in the request to specify which parts of the report should be returned in the response. When this parameter is not provided in the request, all available report fields for the requested sample(s) are returned in the response. If no data is available for a requested field, it is included in the response as an empty field. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :-------------------------------- | :------- | :----------------------------------------------------------- | :-------------------------- | | hash_values | Required | One or more hashes of samples for which the analysis report should be returned. The samples must be present on the appliance. Supported hash types are SHA1, SHA256, SHA512, MD5. All hashes in a request must be of the same type. | array | | fields | Optional | Comma-separated list of additional report fields to include in the response. The default response contains this set of default fields:`rl_auxiliary_analysis, av_scanners, av_scanners_summary, cape, cisco_secure_malware_analytics, cuckoo, discussion, joe, fireeye, rl_cloud_sandbox, sources, sample_summary, ticore, tags, ticloud, vmray_tcbase` Additional supported values: `id, sha1, sha256, sha512, md5, category, file_type, file_subtype, identification_name, identification_version, file_size, extracted_file_count, local_first_seen, local_last_seen, classification_origin, classification_reason, classification_source, classification, riskscore, classification_result, ticore, tags, summary, discussion, ticloud, aliases, proposed_filename, networkthreatintelligence, domainthreatintelligence, av_scanners, av_scanners_summary` Network and domain threat intelligence results won’t be applied unless the parameter `include_networkthreatintelligence` is set to true. | array | | include_networkthreatintelligence | Optional | Include or exclude network or domain threat intelligence. If this is set to true, parameters `networkthreatintelligence` and `domainthreatintelligence` have to be included in the `fields` parameter. Applies only to URLs, not files. | boolean (but inside quotes) | | skip_reanalysis | Optional | Whether to reanalyze a file when fetching its report. False by default (if omitted, files will be reanalyzed when their reports are fetched). | boolean (but inside quotes) | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/samples/v2/list/details/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{"hash_values":["6cadcefb80b7e757323aa46fba909d72"], "fields": ["classification_result", "sources", "av_scanners_summary"]}' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = f"https://appliance.example.com/api/samples/v2/list/details/" json = { "hash_values": ["examplehash1", "examplehash2"], "fields": ["sha256", "extracted_file_count"] } headers = {'Authorization': f'Token {token}'} # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, json=json) print(response.text) ``` ### Response Format **Response Examples** ```json { "count": 1, "next": null, "previous": null, "results": [ { "av_scanners_summary": { "scanner_count": 38, "scanner_match": 36, "scanner_percent": 94.73684210526315 }, "sources": { "ticloud_sources": { }, "other_sources": [] }, "classification_result": "Win32.Backdoor.Prorat" } ] } ``` **Response Fields** | FIELD NAME | DESCRIPTION | | :----------------------------- | :----------------------------------------------------------- | | ticore | Corresponds to the `ticore` object from the [Spectra Core Report API](./static-analysis-report-api.md) | | ticloud | Corresponds to the `cloud` object from the [Summary Report API](./report-summary-api.md) | | rl_cloud_sandbox | Contains dynamic analysis results from ReversingLabs Cloud Sandbox according to the integration configuration on the appliance | | rl_auxiliary_analysis | Contains dynamic analysis results from the RL Auxiliary Analysis service | | joe | Contains dynamic analysis results from Joe Sandbox according to the integration configuration on the appliance | | cisco_secure_malware_analytics | Contains dynamic analysis results from Cisco Secure Malware Analytics according to the integration configuration on the appliance | | cuckoo | Contains dynamic analysis results from Cuckoo according to the integration configuration on the appliance | | fireeye | Contains dynamic analysis results from FireEye according to the integration configuration on the appliance | | cape | Contains dynamic analysis results from CAPE according to the integration configuration on the appliance | | vmray_tcbase | Contains dynamic analysis results from VMRay according to the integration configuration on the appliance | | sources | Groups sources of the file in the ReversingLabs system (Spectra Intelligence sources, external, other) | | av_scanners | Lists detailed results from every AV scanner that scanned the file | | sample_summary | Combines the default response and the `summary` object of the [Summary Report API](./report-summary-api.md) with the `aliases` field to return a more complete summary report | | av_scanners_summary | Lists the total number of AV scanners used to scan the file; the number and the percentage of AV scanners out of the total that matched the sample | | tags | Lists labels automatically generated by [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) during analysis based on the sample’s metadata properties (“ticore”) or added by the users on the appliance (“user”) | | discussion | Contains comments attached to the requested sample(s), if there are any | | networkthreatintelligence | Only for URLs | | domainthreatintelligence | Only for URLs | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | Returned on successful requests. Also returned for samples that don’t exist on the appliance, and for empty report fields. | | 400 | Malformed hash or invalid field name. | | 403 | Authentication credentials were not provided. / Invalid token. | | 404 | Malformed endpoint. | --- ## Spectra Analyze API Documentation — REST Endpoints & Authentication **Tip: The Spectra Analyze API documentation is now also available as an Open API specification, accessible from the Help > API Docs item from the main menu. Authorizing the API docs using a valid appliance token makes it possible to send API requests directly from there.** The Spectra Analyze appliance provides a number of REST APIs that allow seamless integration with automated workflows. In order to send requests and interact with the APIs, users need to authenticate to the appliance with their API tokens. A prerequisite for receiving an API token is an existing, active user account on the appliance. Prior to using any of the APIs, users should request a token as described in the following section. For additional workflows, such as scanning entire [directories](https://github.com/reversinglabs/reversinglabs-sdk-cookbook/blob/main/Scenarios%20and%20Workflows/directory_scanning.ipynb), see our [SDK](https://github.com/reversinglabs/reversinglabs-sdk-py3) documentation and its [cookbook](https://github.com/reversinglabs/reversinglabs-sdk-cookbook). --- ## Licensing API — Spectra Analyze ## Generate Machine ID ``` POST /api/v1/license/machine-id/generate ``` Generates a machine ID for the Spectra Analyze appliance. This machine ID can be emailed to ReversingLabs support to obtain a valid license file. If the machine ID is regenerated, the appliance has to be licensed again, unless it is licensed using a Spectra Intelligence account. Once ReversingLabs support replies with a license file, upload it to the appliance using the [Upload license file](#upload-license-file) endpoint, or using the GUI. **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------- | | 201 | OK | | 400 | Bad Request | ### Response Format ```json { "machineId": "string" } ``` ### Request Examples **cURL** ```bash curl -X POST 'https://example.appliance.com/api/v1/license/machine-id/generate' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://example.appliance.com/api/v1/license/machine-id/generate" payload = {} headers = { "Authorization": f"Token {token}" } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` ## Upload license file ``PUT /api/v1/license/upload`` Uploads a license file to Spectra Analyze. To obtain a license file, request it from ReversingLabs support by sending the Spectra Analyze machine ID which can be found in the Licensing section of the appliance, in the [License information](#license-information) query response, or (re)generated using the [Generate Machine ID endpoint](#generate-machine-id). This API requires a valid [token](./tokens.md). ### Request Parameters The file must be provided as an argument to the `file` parameter. The request payload type must be `multipart/form-data`. **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------- | | 200 | OK | | 201 | OK | | 400 | Bad Request | | 502 | Bad Gateway | ### Request Examples **cURL** ``` # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X PUT 'https://appliance.example.com/api/v1/license/upload' \ --header 'Authorization: Token exampletoken' \ --form 'file=@licensefile' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://example.appliance.com/api/v1/license/upload" files=[ ('file',('license',open('/path/to/license','rb'),'multipart/form-data')) ] headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.request("PUT", url, headers=headers, files=files) print(response.text) ``` ## Spectra Intelligence License ``` POST /api/v1/license/configure/cloud ``` Configures the Spectra Intelligence account on the appliance. Appliances with a valid Spectra Intelligence account are considered licensed as long as they can reach Spectra Intelligence. If not, the appliance enters a 14-day grace period during which it’s still considered licensed. **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------- | | 200 | OK | ### Request Parameters | url | The host address for the Spectra Intelligence service. The default URL is *https://appliance-api.reversinglabs.com* | | -------------- | ------------------------------------------------------------ | | user | Spectra Intelligence username for authentication. Every Spectra Analyze instance must be connected to its own Spectra Intelligence account. Sharing accounts between multiple instances can interfere with the functionality of the appliance (particularly with YARA rule synchronization). | | token | Spectra Intelligence password for authentication. Every Spectra Analyze instance must be connected to its own Spectra Intelligence account. Sharing accounts between multiple instances can interfere with the functionality of the appliance (particularly with YARA rule synchronization). | | timeout | Default Spectra Intelligence service connection timeout in seconds (maximum 1000). | | proxy_host | Optional proxy host name for routing requests from the appliance to Spectra Intelligence (e.g., 192.168.1.15). If configured, this proxy will also be used by the Local URL crawling method and all integrations on the Spectra Analyze appliance. | | proxy_port | Optional proxy port number (e.g., 1080). | | proxy_user | Username for proxy authentication (if proxy is configured). | | proxy_password | Password for proxy authentication (if proxy is configured). | **POST Body Example** ```json { "url": "https://appliance-api.reversinglabs.com", "user": "string", "token": "string", "timeout": 1, "proxy_host": "string", "proxy_port": 0, "proxy_user": "string", "proxy_password": "string" } ``` ### Request Examples **cURL** ``` # Add --insecure before the URL if you are using a self-signed SSL curl -X POST 'https://appliance.example.com/api/v1/license/configure/cloud' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token exampletoken' \ --data '{ "url": "https://appliance-api.reversinglabs.com", "user": "string", "token": "string", "timeout": 1, "proxy_host": "string", "proxy_port": 0, "proxy_user": "string", "proxy_password": "string" }' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://appliance.example.com/api/v1/license/configure/cloud" json = { "url": "https://appliance-api.reversinglabs.com", "user": "string", "token": "string", "timeout": 1, "proxy_host": "string", "proxy_port": 0, "proxy_user": "string", "proxy_password": "string" } headers = { "Authorization": f"Token {token}" } response = requests.request("POST", url, headers=headers, json=json) print(response.text) ``` ## License Information ``` GET /api/v1/license/ ``` Retrieves the status of the license and generates a machine ID if it doesn’t already exist. Unlicensed appliances can be licensed by connecting the appliance to Spectra Intelligence using the [Spectra Intelligence License](#spectra-intelligence-license) endpoint, or by sending the Machine ID to ReversingLabs support via email and uploading the license file they provide to the appliance using the [Upload license file](#upload-license-file) endpoint. **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------- | | 200 | OK | | 502 | Bad Gateway | ### Response Format ``` { "status": "VALID", "product": "A1000", "machineId": "string", "version": 0, "serialNumber": "string", "licenseType": "WILDCARD", "company": "string", "expiryDate": "2024-08-24", "creationDate": "2023-08-24" } ``` ## License status ``` GET /api/v1/license/status/ ``` Returns the current status of the license. **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------- | | 200 | OK | | 502 | Bad Gateway | ### Response Format ``` { "status": "VALID" } ``` ### Request Examples **cURL** ``` curl -X GET 'https://example.appliance.com/api/v1/license/status/' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://example.appliance.com/api/v1/license/status/" payload = {} headers = { "Authorization": f"Token {token}" } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` --- ## Network Threat Intelligence API — Spectra Analyze ## URL ``` GET /api/network-threat-intel/url/ ``` Returns information about the provided URL. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--- | :------- | :------------------------------------------------------ | :------------ | | url | Required | The requested URL. This string needs to be URI-encoded. | query, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/network-threat-intel/url/?url=https%3A%2F%2Fwww.example.com' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # change the values of url, token, and requested_url token = "exampletoken" requested_url = "https%3A%2F%2Fwww.example.com" url = f"https://appliance.example.com/api/network-threat-intel/url/?url={requested_url}" headers = { "authorization": f"token {token}" } # add verify=False in the request if you are using a self-signed ssl certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Schema** ```yaml properties: third_party_reputations: type: object properties: sources: type: array items: type: object properties: source: type: string detection: type: string category: type: string update_time: type: string detect_time: type: string statistics: type: object properties: total: type: integer malicious: type: integer clean: type: integer undetected: type: integer classification: type: string analysis: type: object properties: analysis_history: type: array items: type: object properties: domain: type: string final_url: type: string http_response_code: type: integer analysis_id: type: string availability_status: type: string serving_ip_address: type: string analysis_time: type: string last_analysis: type: object properties: domain: type: string http_response_code: type: integer analysis_id: type: string availability_status: type: string serving_ip_address: type: string analysis_time: type: string first_analysis: type: string analysis_count: type: integer top_threats: type: array items: type: object properties: threat_name: type: string files_count: type: integer risk_score: type: integer statistics: type: object properties: unknown: type: integer suspicious: type: integer total: type: integer malicious: type: integer goodware: type: integer requested_url: type: string ``` ### Response Examples ```json { "third_party_reputations": { "sources": [ { "detection": "undetected", "source": "phishing_database", "update_time": "2022-11-28T10:43:53" }, { "detection": "undetected", "source": "cyren", "update_time": "2022-11-28T06:12:42" }, { "detection": "undetected", "source": "cyradar", "update_time": "2022-11-28T06:36:08" }, { "detection": "undetected", "source": "netstar", "update_time": "2022-11-28T11:39:32" }, { "detection": "undetected", "source": "malsilo", "update_time": "2022-11-28T00:06:54" }, { "detection": "undetected", "source": "mute", "update_time": "2022-11-28T10:37:58" }, { "detection": "undetected", "source": "adminus_labs", "update_time": "2022-11-28T11:53:02" }, { "detection": "undetected", "source": "apwg", "update_time": "2022-11-28T02:20:40" }, { "detection": "undetected", "source": "0xSI_f33d", "update_time": "2022-11-28T06:22:08" }, { "detection": "undetected", "source": "threatfox_abuse_ch", "update_time": "2022-11-28T08:22:21" }, { "detection": "undetected", "source": "alphamountain", "update_time": "2022-11-28T10:47:29" }, { "detection": "undetected", "source": "phishstats", "update_time": "2022-11-28T05:20:19" }, { "detection": "undetected", "source": "comodo_valkyrie", "update_time": "2022-11-27T15:42:30" }, { "detection": "undetected", "source": "alien_vault", "update_time": "2022-11-28T02:02:35" }, { "detection": "undetected", "source": "osint", "update_time": "2022-11-28T01:31:05" }, { "detection": "undetected", "source": "openphish", "update_time": "2022-11-27T18:02:25" }, { "detection": "undetected", "source": "mrg", "update_time": "2022-11-28T10:44:41" }, { "detection": "undetected", "source": "phishtank", "update_time": "2022-11-28T11:24:33" }, { "detection": "undetected", "source": "crdf", "update_time": "2022-11-28T08:30:08" }, { "detection": "undetected", "source": "urlhaus", "update_time": "2022-11-28T11:20:58" } ], "statistics": { "total": 20, "malicious": 0, "clean": 0, "undetected": 20 } }, "classification": "goodware", "analysis": { "analysis_history": [ { "domain": "example.com", "final_url": "http://example.com/", "http_response_code": 200, "analysis_id": "16685201231489dc", "availability_status": "online", "serving_ip_address": "93.184.216.34", "analysis_time": "2022-11-15T12:53:25" }, { "domain": "example.com", "http_response_code": 200, "analysis_id": "1668516805009c17", "availability_status": "online", "serving_ip_address": "93.184.216.34", "analysis_time": "2022-11-15T12:53:25" }, { "domain": "example.com", "final_url": "http://example.com/", "http_response_code": 200, "analysis_id": "16685489790689dc", "availability_status": "online", "serving_ip_address": "93.184.216.34", "analysis_time": "2022-11-15T20:53:28" }, { "domain": "example.com", "http_response_code": 200, "analysis_id": "1668545608009c17", "availability_status": "online", "serving_ip_address": "93.184.216.34", "analysis_time": "2022-11-15T20:53:28" }, { "domain": "example.com", "final_url": "http://example.com/", "http_response_code": 200, "analysis_id": "16685921996389dc", "availability_status": "online", "serving_ip_address": "93.184.216.34", "analysis_time": "2022-11-16T08:53:58" }, { "domain": "example.com", "http_response_code": 200, "analysis_id": "1668588838009c17", "availability_status": "online", "serving_ip_address": "93.184.216.34", "analysis_time": "2022-11-16T08:53:58" }, { "domain": "example.com", "final_url": "http://example.com/", "http_response_code": 200, "analysis_id": "16691106111989dc", "availability_status": "online", "serving_ip_address": "93.184.216.34", "analysis_time": "2022-11-22T08:54:43" }, { "domain": "example.com", "http_response_code": 200, "analysis_id": "1669107283009c17", "availability_status": "online", "serving_ip_address": "93.184.216.34", "analysis_time": "2022-11-22T08:54:43" }, { "domain": "example.com", "final_url": "http://example.com/", "http_response_code": 200, "analysis_id": "1669636389639c17", "availability_status": "online", "serving_ip_address": "93.184.216.34", "analysis_time": "2022-11-28T10:57:09" }, { "domain": "example.com", "http_response_code": 200, "analysis_id": "1669633029009c17", "availability_status": "online", "serving_ip_address": "93.184.216.34", "analysis_time": "2022-11-28T10:57:09" } ], "last_analysis": { "domain": "example.com", "http_response_code": 200, "analysis_id": "1669633029009c17", "availability_status": "online", "serving_ip_address": "93.184.216.34", "analysis_time": "2022-11-28T10:57:09" }, "first_analysis": "2022-11-15T12:53:25", "analysis_count": 171, "statistics": { "unknown": 0, "suspicious": 0, "total": 2, "malicious": 0, "goodware": 2 } }, "requested_url": "www.example.com" } ``` ## Domain ``` GET /api/network-threat-intel/domain/{domain}/ ``` Returns information about the provided domain. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :----- | :------- | :-------------------- | :----------- | | domain | Required | The requested domain. | path, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/network-threat-intel/domain/example.com/' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # change the values of url, token, and domain token = "exampletoken" domain = "example.com" url = f"https://appliance.example.com/api/network-threat-intel/domain/{domain}/" headers = { "authorization": f"token {token}" } # add verify=false in the request if you are using a self-signed ssl certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Schema** ```yaml properties: parent_domain: type: string last_dns_records: type: array items: type: object properties: type: type: string value: type: string provider: type: string last_dns_records_time: type: string third_party_reputations: type: object properties: sources: type: array items: type: object properties: source: type: string detection: type: string category: type: string update_time: type: string detect_time: type: string statistics: type: object properties: total: type: integer malicious: type: integer undetected: type: integer clean: type: integer top_threats: type: array items: type: object properties: threat_name: type: string files_count: type: integer risk_score: type: integer modified_time: type: string downloaded_files_statistics: type: object properties: unknown: type: integer suspicious: type: integer total: type: integer malicious: type: integer goodware: type: integer requested_domain: type: string ``` **Response Example** ```json { "last_dns_records": [ { "type": "A", "value": "93.184.216.34", "provider": "ReversingLabs" } ], "last_dns_records_time": "2022-11-28T10:57:09", "third_party_reputations": { "sources": [ { "detection": "undetected", "source": "phishing_database", "update_time": "2022-11-28T02:24:00" }, { "detection": "undetected", "source": "0xSI_f33d", "update_time": "2022-11-28T06:22:08" }, { "detection": "malicious", "source": "cyradar", "update_time": "2022-11-28T06:36:08", "detect_time": "2022-06-08T12:55:18" }, { "detection": "undetected", "source": "adminus_labs", "update_time": "2022-11-28T12:39:42" }, { "detection": "undetected", "source": "apwg", "update_time": "2022-11-28T04:06:58" }, { "detection": "undetected", "source": "netstar", "update_time": "2022-11-28T12:33:27" }, { "detection": "undetected", "source": "threatfox_abuse_ch", "update_time": "2022-11-28T08:22:21" }, { "detection": "undetected", "source": "botvrij", "update_time": "2022-11-28T02:25:14" }, { "detection": "undetected", "source": "alphamountain", "update_time": "2022-11-28T12:54:06" }, { "detection": "undetected", "source": "comodo_valkyrie", "update_time": "2022-11-28T05:54:08" }, { "detection": "undetected", "source": "web_security_guard", "update_time": "2022-01-21T06:56:15" }, { "detection": "undetected", "source": "osint", "update_time": "2022-11-28T01:31:05" }, { "detection": "undetected", "source": "crdf", "update_time": "2022-11-28T08:30:08" } ], "statistics": { "total": 13, "malicious": 1, "undetected": 12, "clean": 0 } }, "top_threats": [], "modified_time": "2022-11-28T12:54:06", "downloaded_files_statistics": { "unknown": 0, "suspicious": 0, "total": 2, "malicious": 0, "goodware": 2 }, "requested_domain": "example.com" } ``` ## IP Address The IP Address API has four separate endpoints: - report - resolutions - URLs - downloaded files ### Report ``` GET /api/network-threat-intel/ip/{ip}/report/ ``` Returns: - Third-party IP address reputation and categorization. - Counters of samples downloaded from the IP address, mapped to their classification status (malicious, suspicious, known, no threats found). - The most common threats (malware type, family) hosted on the submitted IP address. #### Request Format | NAME | REQUIRED | DESCRIPTION | TYPE | | :--- | :------- | :------------------------ | :----------- | | ip | Required | The requested IP address. | path, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/network-threat-intel/ip/93.184.216.34/report/' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # change the values of url, token, and ip token = "exampletoken" ip = "93.184.216.34" url = f"https://appliance.example.com/api/network-threat-intel/ip/{ip}/report/" headers = { "authorization": f"token {token}" } # add verify=false in the request if you are using a self-signed ssl certificate response = requests.get(url, headers=headers) print(response.text) ``` #### Response Format **Response Schema** ``` properties: third_party_reputations: type: object properties: statistics: type: object properties: total: type: integer malicious: type: integer undetected: type: integer clean: type: integer sources: type: array items: type: object properties: source: type: string detection: type: string category: type: string update_time: type: string detect_time: type: string downloaded_files_statistics: type: object properties: total: type: integer unknown: type: integer suspicious: type: integer malicious: type: integer goodware: type: integer top_threats: type: array items: type: object properties: threat_name: type: string files_count: type: integer risk_score: type: integer requested_ip: type: string modified_time: type: string ``` **Response Example** ``` { "third_party_reputations": { "statistics": { "total": 6, "malicious": 0, "undetected": 5, "clean": 1 }, "sources": [ { "detection": "clean", "update_time": "2022-11-28T12:54:06", "detect_time": "2022-08-02T17:50:15", "category": null, "source": "alphamountain" }, { "detection": "undetected", "update_time": "2022-11-28T08:22:21", "detect_time": null, "category": null, "source": "threatfox_abuse_ch" }, { "detection": "undetected", "update_time": "2022-11-28T13:05:55", "detect_time": null, "category": null, "source": "adminus_labs" }, { "detection": "undetected", "update_time": "2022-11-28T01:31:05", "detect_time": null, "category": null, "source": "osint" }, { "detection": "undetected", "update_time": "2022-11-28T05:28:18", "detect_time": null, "category": null, "source": "feodotracker" }, { "detection": "undetected", "update_time": "2022-11-28T13:31:27", "detect_time": null, "category": null, "source": "crdf" } ] }, "downloaded_files_statistics": { "total": 1, "unknown": 0, "suspicious": 0, "malicious": 0, "goodware": 1 }, "top_threats": [], "requested_ip": "93.184.216.34", "modified_time": "2022-11-28T13:31:27" } ``` ## Resolutions ``` GET /api/network-threat-intel/ip/{ip}/resolutions/ ``` Provides a list of IP-to-domain mappings. ### Request Format | NAME | REQUIRED | DESCRIPTION | TYPE | | :-------- | :------- | :--------------------------------- | :------------ | | ip | Required | The requested IP address. | path, string | | page | Optional | SHA1 hash of the next page. | query, string | | page_size | Optional | Number of records in the response. | query, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/network-threat-intel/ip/142.250.186.142/resolutions/?page=973f00c91945cb04b89f0657b581974156ad4922&page_size=2' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # change the values of url, token, and ip token = "exampletoken" ip = "142.250.186.142" url = f"https://appliance.example.com/api/network-threat-intel/ip/{ip}/resolutions/?page=973f00c91945cb04b89f0657b581974156ad4922&page_size=2" headers = { "authorization": f"token {token}" } # add verify=false in the request if you are using a self-signed ssl certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Schema** ```yaml properties: next_page: type: string nullable: true description: If there is no next page, this field is ``null``. resolutions: type: array items: type: object properties: provider: type: string last_resolution_time: type: string host_name: type: string requested_ip: type: string ``` **Response Example** ```json { "next_page": null, "resolutions": [ { "provider": "ReversingLabs", "last_resolution_time": "2022-11-28T10:57:09", "host_name": "example.com" }, { "provider": "ReversingLabs", "last_resolution_time": "2022-11-26T10:17:43", "host_name": "example.org" }, { "provider": "ReversingLabs", "last_resolution_time": "2022-10-23T09:19:51", "host_name": "iplogger.com" }, { "provider": "ReversingLabs", "last_resolution_time": "2021-09-21T18:38:46", "host_name": "example.net" }, { "provider": "ReversingLabs", "last_resolution_time": "2022-03-14T19:26:01", "host_name": "savemoneyindia.com" }, { "provider": "ReversingLabs", "last_resolution_time": "2022-03-24T17:44:25", "host_name": "denylist-api.herokuapp.com" } ], "requested_ip": "93.184.216.34" } ``` ## URLs ``` GET /api/network-threat-intel/ip/{ip}/urls/ ``` Returns a list of URLs hosted on the submitted IP address. ### Request Format | NAME | REQUIRED | DESCRIPTION | TYPE | | :-------- | :------- | :--------------------------------- | :------------ | | ip | Required | The requested IP address. | path, string | | page | Optional | SHA1 hash of the next page. | query, string | | page_size | Optional | Number of records in the response. | query, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/network-threat-intel/ip/93.184.216.34/urls/?page=973f00c91945cb04b89f0657b581974156ad4922&page_size=2' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # change the values of url, token, and ip token = "exampletoken" ip = "142.250.186.142" url = f"https://appliance.example.com/api/network-threat-intel/ip/{ip}/urls/?page=973f00c91945cb04b89f0657b581974156ad4922&page_size=2" headers = { "authorization": f"token {token}" } # add verify=false in the request if you are using a self-signed ssl certificate response = requests.get(url, headers=headers) print(response.text) ``` #### Response Format **Response Schema** ```yaml properties: next_page: type: string nullable: true description: If there is no next page, this field is ``null``. urls: type: array items: type: object properties: url: type: string requested_ip: type: string ``` **Response Example** ```json { "next_page": null, "urls": [ { "url": "https://example.org/" }, { "url": "http://example.com/index.html" }, { "url": "https://example.com/?amp;elq=bfa5214c59ef4b51b9356f3b8d8dd10b&elqCampaignId=10525985&elqTrackId=230b8353717a4ce89604e386558dad08&elq_cid=82168169&elqaid=17733&elqat=1&elqcsid=46283&elqcst=272&elq_mid=17733" }, { "url": "http://example.org/)" }, { "url": "https://example.com/?elq=bfa5214c59ef4b51b9356f3b8d8dd10b&elqCampaignId=10525985&elqTrackId=230b8353717a4ce89604e386558dad08&elq_cid=82168169&elq_mid=17733&elqaid=17733&elqat=1&elqcsid=46283&elqcst=272" }, { "url": "http://example.net/" }, { "url": "http://:a@example.com/" }, { "url": "https://iplogger.com/2gJez3" }, { "url": "https://savemoneyindia.com/url.php?go=http://tiny.cc/gd6anz" }, { "url": "http://example.com/~user/ispscript.cgi" }, { "url": "http://denylist-api.herokuapp.com/" }, { "url": "http://example.com/" }, { "url": "https://example.com/" }, { "url": "http://a:@example.com/" }, { "url": "http://example.org/" }, { "url": "http://a:b@example.com/" } ], "requested_ip": "93.184.216.34" } ``` ## Downloaded Files ``` GET /api/network-threat-intel/ip/{ip}/downloaded_files/ ``` Provides a list of hashes and classifications for files found on the submitted IP address. ### Request Format | NAME | REQUIRED | DESCRIPTION | TYPE | | :------------- | :------- | :----------------------------------------------------------- | :------------- | | ip | Required | The requested IP address. | path, string | | page | Optional | SHA1 hash of the next page. | query, string | | page_size | Optional | Number of records in the response. | query, string | | extended | Optional | Include additional information on downloaded files. | query, boolean | | classification | Optional | Include classification of downloaded files. Allowed values: `MALICIOUS`, `SUSPICIOUS`, `GOODWARE`, `UNKNOWN`. | query, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/network-threat-intel/ip/93.184.216.34/downloaded_files/?page=973f00c91945cb04b89f0657b581974156ad4922&page_size=2&extended=true&classification=MALICIOUS' \ --header 'Authorization: Token exampletoken' ``` **Python** ```json # change the values of url, token, and ip token = "exampletoken" ip = "142.250.186.142" url = f"https://appliance.example.com/api/network-threat-intel/ip/{ip}/downloaded_files/?page=973f00c91945cb04b89f0657b581974156ad4922&page_size=2&extended=true&classification=MALICIOUS" headers = { "authorization": f"token {token}" } # add verify=false in the request if you are using a self-signed ssl certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Schema** ```yaml properties: next_page: type: string nullable: true description: If there is no next page, this field is ``null``. downloaded_files: type: array items: type: object properties: sha1: type: string last_download_url: type: string classification: type: string first_download: type: string last_seen: type: string sample_size: type: integer sample_available: type: boolean last_download: type: string first_seen: type: string sha256: type: string md5: type: string risk_score: type: integer sample_type: type: string threat_name: type: 'null' malware_family: type: 'null' malware_type: type: 'null' platform: type: 'null' subplatform: type: 'null' requested_ip: type: string ``` **Response Example** ```json { "next_page": null, "downloaded_files": [ { "sha1": "4a3ce8ee11e091dd7923f4d8c6e5b5e41ec7c047", "last_download_url": "http://example.com/", "classification": "GOODWARE", "first_download": "2022-08-24T12:14:03", "last_seen": "2022-11-21T12:04:31", "sample_size": 1256, "sample_available": true, "last_download": "2022-11-28T10:57:09", "first_seen": "2019-10-19T19:48:47", "sha256": "ea8fac7c65fb589b0d53560f5251f74f9e9b243478dcb6b3ea79b5e36449c8d9", "md5": "84238dfc8092e5d9c0dac8ef93371a07", "risk_score": 5, "sample_type": "Text/HTML/HTML", "threat_name": null, "malware_family": null, "malware_type": null, "platform": null, "subplatform": null } ], "requested_ip": "93.184.216.34" } ``` --- ## PDF Report API — Spectra Analyze With this API, users can download a PDF report of the analysis results for any sample on the Spectra Analyze appliance. The contents of the PDF file downloaded with this API are identical to the PDF report downloaded from the [Sample Details](../Sample%20Details/index.md) page by clicking the Create PDF button. The API provides 3 endpoints: 1. Create PDF Report 2. Check PDF Report Status 3. Download PDF Report To download the PDF report for a sample, users first have to initiate report creation by sending a request to Endpoint 1. The next step is to check report creation status by sending a request to Endpoint 2. When the response indicates that the report is ready, users should send a request to Endpoint 3 to download the PDF file. All three endpoints accept GET requests with a single sample hash per request. Supported hash types are SHA1, SHA256, MD5. The sample hash is a required parameter that must be provided in every request. For each sample, the same hash type used to send the initial request to Endpoint 1 should be used in requests to other endpoints. In other words, if a user requests the PDF by sending a MD5 hash to Endpoint 1, they must also use MD5 when downloading the PDF file from Endpoint 3. When a PDF is initially requested from Endpoint 1, it is created and remains available for download on the appliance for 30 minutes. During this time, users can download it as many times as they want from Endpoint 3. When the report expires, it will no longer be available for download, and should be requested again. ## Create PDF Report ``` GET /api/pdf/{hash}/create ``` Endpoint 1 accepts a GET request with the required `hash` parameter. The hash provided in the request should correspond to the hash of an existing sample on the appliance for which the user wants to generate a PDF report. Supported hash types are MD5, SHA1, SHA256. For each sample, the same hash type used to send the initial request to Endpoint 1 should be used in requests to other endpoints. Sending a request to Endpoint 1 initiates the creation of a PDF analysis report for the requested sample. The response includes links to the Endpoint 2 and Endpoint 3 for the requested sample. Users can then send requests to those endpoints directly, or open them as links in their browser by appending them to the Spectra Analyze appliance host name (for example: `https://a1000-example.com/api/pdf/862adc63da7c3737aad42458e22f99666f47ce0d/status`). ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--- | :------- | :----------------------------------------------------------- | :----------- | | hash | Required | Hash of the sample for which the user wants to generate a PDF report. The sample must exist on the appliance prior to requesting a PDF report. Supported hash types: SHA1, SHA256, MD5. The same hash type that is used in the initial request to Endpoint 1 must be used in requests to other endpoints. | path, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/pdf/07dbef34d2996447ffa8e8230f17d538e88f6ad6/create' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the hostname in the URL url = f"https://appliance.example.com/api/pdf/{hash_value}/create" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Examples** ```bash 200 OK { "status_endpoint": "/api/pdf/862adc63da7c3737aad42458e22f99666f47ce0d/status", "download_endpoint": "/api/pdf/862adc63da7c3737aad42458e22f99666f47ce0d/download" } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | Returned on successful requests. | | 403 | Authentication credentials were not provided. / Invalid API token. | | 404 | Malformed hash. / Sample does not exist on the appliance. | ## Check PDF Report Creation Status ``` GET /api/pdf/{hash}/status ``` Endpoint 2 accepts a GET request with the required `hash` parameter. The hash provided in the request should correspond to the hash used in the request to Endpoint 1, using the same hash type. Supported hash types are MD5, SHA1, SHA256. Do not send requests to Endpoint 2 before sending the initial PDF creation request to Endpoint 1. The response includes an informative message about the status of the PDF report previously requested via Endpoint 1. One of the following status messages may be returned in the response: ``` PDF is ready for download. PDF does not exist and must be created. PDF is being created. Wait. There was an error creating the PDF. ``` ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--- | :------- | :----------------------------------------------------------- | :----------- | | hash | Required | Hash of the sample for which the user wants to generate a PDF report. The sample must exist on the appliance prior to requesting a PDF report. Supported hash types: SHA1, SHA256, MD5. The same hash type that is used in the initial request to Endpoint 1 must be used in requests to other endpoints. | path, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/pdf/07dbef34d2996447ffa8e8230f17d538e88f6ad6/status' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the hostname in the URL url = f"https://appliance.example.com/api/pdf/{hash_value}/status" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Examples** ```json 200 OK { "status": 2, "status_message": "PDF is ready for download." } ``` The following response is returned if Endpoint 2 is called before Endpoint 1. ```json 200 OK { "status": 1, "status_message": "PDF does not exist and must be created." } ``` **Response Status Codes** | CODE | DESCRIPTION | | :------------ | :----------------------------------------------------------- | | 200 OK | PDF is ready for download. | | | PDF does not exist and must be created. Returned if the sample exists on the appliance, but the user has not sent the initial PDF creation request to Endpoint 1. | | 403 Forbidden | Authentication credentials were not provided. | | | Invalid token. | | 404 Not Found | Malformed hash. | | | Sample does not exist on the appliance. | ## Download PDF Report ``` GET /api/pdf/{hash}/download ``` Endpoint 3 accepts a GET request with the required `hash` parameter. The hash provided in the request should correspond to the hash used in the request to Endpoint 1 and Endpoint 2, using the same hash type. Supported hash types are MD5, SHA1, SHA256. Do not send requests to Endpoint 3 before Endpoint 2 indicates that the PDF is ready. Sending a request to Endpoint 3 starts the download of the PDF analysis report for the requested sample. Users who are sending their requests to Endpoint 3 directly should include an option to save the response as a PDF file (see *Request Examples*). Alternatively, users can open the link to Endpoint 3 in their browser (for example: `https://a1000-example.com/api/pdf/862adc63da7c3737aad42458e22f99666f47ce0d/download`) where they have previously logged into their Spectra Analyze appliance. Depending on the browser settings, the dialog for saving the PDF file will automatically open when they access the link. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--- | :------- | :----------------------------------------------------------- | :----------- | | hash | Required | Hash of the sample for which the user wants to generate a PDF report. The sample must exist on the appliance prior to requesting a PDF report. Supported hash types: SHA1, SHA256, MD5. The same hash type that is used in the initial request to Endpoint 1 must be used in requests to other endpoints. | path, string | **Request Examples** **cURL** ``` bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/pdf/07dbef34d2996447ffa8e8230f17d538e88f6ad6/download' \ --header 'Authorization: Token exampletoken' \ --output report.pdf ``` **Python** ``` python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the hostname in the URL url = f"https://appliance.example.com/api/pdf/{hash_value}/download" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) with open("report.pdf", "wb") as f: f.write(response.content) ``` ### Response Format **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | Returned on successful requests. | | 403 | Authentication credentials were not provided. / Invalid token. | | 404 | Malformed hash. | | 404 | Sample does not exist on the appliance. | | 404 | PDF does not exist. Returned if the sample exists on the appliance, but the user has not sent the initial PDF creation request to Endpoint 1. | --- ## Processing Status API — Monitor File Analysis Progress ## Check status of submitted files ``` POST /api/samples/status/ ``` Provides information on the processing status of requested samples in the Spectra Analyze system. All hash values in the request must be of the same type (SHA1, SHA256, SHA512, or MD5). The response returns “not_found” status for sample hashes that don’t exist on the current Spectra Analyze instance, and “processed” for samples already on the current Spectra Analyze instance. Optionally, the results can be filtered by “processed” or “not_found” status by providing the “status” parameter in the request. If *status=not_found* in the request, the response will include only the values for samples with the “not found” status on the appliance. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :---------- | :------- | :----------------------------------------------------------- | :--------------- | | hash_values | Required | Hash of the sample for which the user wants to check the processing status. At least one hash must be provided in the request. All hashes in a request must be of the same type. Supported hash types: SHA1, SHA256, SHA512, MD5 | application/json | | status | Optional | Optional parameter that allows filtering hashes by their status. When this parameter is included in the request, only the hashes matching the requested status are returned in the response. Supported values: `processed`, `not_found` | query, string | **Request Examples** **cURL** ``` # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/samples/status/?status=processed' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{"hash_values": ["9dc5e23c7ab2692b83f0690a736b123a1837ae56", "4b21a49eadac1bc01477eff778041fdb765b8139"]}' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://appliance.example.com/api/samples/status/" params = {"status": "processed"} json = { "hash_values": [ "a0a968161aec928a45b0b9340eecfa5ec41fe9f2", "713e365e6e03d1e0b16c802a177fb94330cbe6e0" ] } headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, params=params, headers=headers, json=json) print(response.text) ``` ### Response Format **Response Examples** ```json { "hash_type": "sha1", "results": [ { "hash_value": "9dc5e23c7ab2692b83f0690a736b123a1837ae56", "status": "processed" }, { "hash_value": "4b21a49eadac1bc01477eff778041fdb765b8139", "status": "processed" } ] } ``` **Response Fields** | FIELD NAME | TYPE | | :--------- | :----- | | hash_type | string | | results | array | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | OK | | 400 | Validation error, JSON parse error, or other error related to the validity of the data passed in the request. | ## Check status of submitted URLs ``` GET /api/uploads/v2/url-samples/{ID} ``` Check the processing status of a submitted URL. The `ID` path parameter is required and must correspond to the **id** value in the response from the Submissions API. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--- | :------- | :----------------------------------------------------------- | :----------- | | id | Required | Identification number of the submission processing task on the appliance. This number is automatically generated and returned in the response of the Submissions API. | path, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/uploads/v2/url-samples/1234' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of token and ID token = "exampletoken" ID = "123" # From the response of the URL submission API # Change the hostname in the URL url = f"https://appliance.example.com/api/uploads/v2/url-samples/{ID}" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Examples** The `processing_status` field in the response indicates the status of the URL submission. ```json { "processing_status": "downloading", "message": "", "report": {} } { "processing_status": "processing", "message": "", "report": {} } ``` When the URL is successfully submitted and processed on the appliance, the full analysis report is returned in the response. ```json { "processing_status": "complete", "message": "", "report": {} } ``` If the URL submission fails, the response indicates that with the `"processing_status": "error"` field. In this case, the `message` field contains a more detailed message explaining why the URL submission failed. ```json { "processing_status": "error", "message": "the following error occured - Server responded with error 404: Not Found. Logs may contain more information on why this happened.", "report": {} } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------- | | 200 | OK | --- ## Reanalyze Local Samples API V2 — Spectra Analyze ## Reanalyze multiple samples with selected services ``` POST /api/samples/v2/analyze_bulk/ ``` Submit a set of samples that already exist on the Spectra Analyze appliance (previously uploaded) to be analyzed again with one or more supported services. Unlike the “Reanalyze a set of samples with [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) and Spectra Intelligence” endpoint, this one allows reanalyzing samples on each service independently, and provides more control over which service(s) should be used. The `analysis` parameter is required, and it accepts one or more of the following values: - **rl_auxiliary_analysis** - reanalyze samples with the RL Auxiliary Analysis service - **core** - reanalyze samples with the Spectra Core static analysis engine - **cloud** - reanalyze samples with AV engines in the Spectra Intelligence cloud - **cape** - reanalyze samples with the CAPE dynamic analysis service - **cisco_secure_malware_analytics** - reanalyze samples with the Cisco Secure Malware Analytics dynamic analysis service - **cuckoo** - reanalyze samples with the Cuckoo Sandbox dynamic analysis service - **fireeye** - reanalyze samples with the FireEye dynamic analysis service - **joe** - reanalyze samples with the Joe Sandbox dynamic analysis service - **rl_cloud_sandbox** - reanalyze samples with the ReversingLabs Cloud Sandbox - **vmray_tcbase** - reanalyze samples with the VMRay dynamic analysis service **Note: Dynamic analysis services must be enabled and properly configured on the appliance in order to submit files for reanalysis via this endpoint. Dynamic analysis services have their own maximum size limits. Consult the [Analysis services](../Analysis-services/index.md) section for more details.** ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :------------------------ | :------- | :----------------------------------------------------------- | :----------- | | analysis | Required | Types of analysis that the requested sample(s) should be queued for. At least one value must be provided in the request. If providing multiple values, they should be comma-separated. Supported values:`rl_auxiliary_analysis``cloud``core``cape``cisco_secure_malware_analytics``cuckoo``fireeye``joe``rl_dynamic_analysis``vmray_tcbase` | form, string | | hash_value | Required | Hash of the sample(s) that should be reanalyzed. At least one hash must be provided in the request. The sample(s) must be present on the Spectra Analyze appliance to be submitted for reanalysis. Different hash types can be used in a request. Supported hash types: SHA1, SHA256, SHA512, MD5 | form, array | | rl_cloud_sandbox_platform | Optional | The platform to be used when executing the sample on the ReversingLabs Cloud Sandbox. Supported values:`windows7``windows10``windows11``macos_11``ubuntu_20` | form, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/samples/v2/analyze_bulk/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{"hash_value":["0000014db72d1427c8b34ba152476a9bfdb27844", "f51ef127e79bf2f59dc82cf993f8315967e4bbfe"], "analysis": "core,cloud,fireeye,joe,cuckoo,rl_cloud_sandbox,cape,vmray", "rl_cloud_sandbox_platform": "windows10"}' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://appliance.example.com/api/samples/v2/analyze_bulk/" headers = {'Authorization': f'Token {token}'} json={"hash_value": ["0000014db72d1427c8b34ba152476a9bfdb27844", "f51ef127e79bf2f59dc82cf993f8315967e4bbfe"], "analysis": "core,cloud,fireeye,joe,cuckoo,rl_cloud_sandbox,vmray"} # Change the hashes # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, json=json) print(response.text) ``` ### Response Format **Response Examples** ```json { "results": [ { "analysis": [ { "name": "cloud", "code": 201, "message": "Sample is queued for analysis." }, { "name": "core", "code": 201, "message": "Sample is queued for core analysis." }, { "name": "rl_cloud_sandbox", "code": 201, "message": "Sample is queued for analysis." }, { "name": "cuckoo", "code": 201, "message": "Sample is queued for analysis." }, { "name": "fireeye", "code": 201, "message": "Sample is queued for analysis." }, { "name": "joe", "code": 201, "message": "Sample is queued for analysis." }, { "name": "cape", "code": 201, "message": "Sample is queued for analysis." } ], "detail": { "sha1": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "sha256": "aec070645fe53ee3b3763059376134f0 #shortened for clarity, "sha512": "0b8754b06ca408c09e8672bce675f3d #shortened for clarity, "md5": "14758f1afd44c09b7992073ccf00b43d" } }, { "analysis": [ { "name": "cloud", "code": 201, "message": "Sample is queued for analysis." }, { "name": "core", "code": 201, "message": "Sample is sent to core analysis." }, { "name": "rl_cloud_sandbox", "code": 201, "message": "Sample is queued for analysis." }, { "name": "cuckoo", "code": 201, "message": "Sample is queued for analysis." }, { "name": "fireeye", "code": 201, "message": "Sample is queued for analysis." }, { "name": "joe", "code": 201, "message": "Sample is queued for analysis." }, { "name": "cape", "code": 201, "message": "Sample is queued for analysis." } ], "detail": { "sha1": "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15", "sha256": "b5bb9d8014a0f9b1d61e21e796d78dcc #shortened for clarity, "sha512": "1b8754b06ca408c09e8672bce675f3dd5 #shortened for clarity, "md5": "d3b07384d113edec49eaa6238ad5ff00" } } ] } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | Sample is already queued for analysis. | | 201 | Sample is queued for analysis. / Sample is queued for core analysis. | | 400 | Validation error. Value is not valid sha1, sha256, sha512 or md5 hash value. | | 405 | Reanalysis not allowed for extracted samples. | | 405 | Not allowed for this type of appliance. | | 405 | File oversized. | | 405 | File type is not supported. | | 405 | Sandbox integration is not configured. | --- ## Reanalyze Local Samples API V1 — Spectra Analyze ## Reanalyze a single sample with [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) and Spectra Intelligence ``` POST /api/samples/{hash_value}/analyze/ ``` Schedule a single sample that already exists on the Spectra Analyze (previously uploaded) to be analyzed again. The `analysis` parameter is required and supports the following values: - **cloud** - schedules the sample to be sent to Spectra Intelligence for reanalysis - **core** - schedules the sample to be reanalyzed with Spectra Core At least one `analysis` value must be specified in the request. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--------- | :------- | :----------------------------------------------------------- | :----------- | | analysis | Required | Types of analysis that the requested sample should be queued for. At least one value must be provided in the request. If providing multiple values, they should be comma-separated. Supported values: **cloud**, **core**, where *cloud* refers to Spectra Intelligence analysis and requires that the appliance is connected to Spectra Intelligence, and *core* refers to Spectra Core static analysis. | form, string | | hash_value | Required | Hash of the sample that should be reanalyzed. Only one hash can be submitted in one request. Supported hash types: SHA1, SHA256, SHA512, MD5 | path, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/samples/988881adc9fc3655077dc2d4d757d480b5ea0e11/analyze/' \ --header 'Authorization: Token exampletoken' \ --form 'analysis=cloud,core' ``` **Python** ```python # Change the values of hash_value and token hash_value = "examplehash" token = "exampletoken" # Change the hostname in the URL url = f"https://appliance.example.com/api/samples/{hash_value}/analyze/" headers = { 'Authorization': f'Token {token}' } json = {"analysis": "cloud,core"} # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, json=json) print(response.text) ``` ### Response Format **Response Examples** **Note: The top-level “code” and “message” values in the response are deprecated and are returned only for compatibility reasons. The “code” and “message” from the “analysis” section contain relevant information, and should be referred to instead.** ``` { "code": 201, "message": "Sample is queued for analysis.", "analysis": [ { "name": "cloud", "code": 201, "message": "Sample is queued for analysis." }, { "name": "core", "code": 201, "message": "Sample is sent to core analysis." } ], "detail": { "sha1": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "sha256": "aec070645fe53ee3b3763059376134f...", #shortened for clarity "sha512": "0b8754b06ca408c09e8672bce675f...", #shortened for clarity "md5": "14758f1afd44c09b7992073ccf00b43d" } } ``` **Response Fields** | FIELD NAME | TYPE | | :--------- | :------ | | code | integer | | message | string | | analysis | object | | detail | object | | FIELD NAME | DESCRIPTION | TYPE | | :--------- | :---------- | :----- | | sha1 | | string | | sha256 | | string | | sha512 | | string | | md5 | | string | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | Sample is already queued for analysis. | | 201 | Sample is queued for analysis. / Sample is queued for core analysis. | | 400 | Validation error. Value is not valid sha1, sha256, sha512 or md5 hash value. | | 404 | Sample is not found on the appliance. | | 405 | Reanalysis not allowed for extracted samples. | | 405 | Not allowed for this type of appliance. | ## Reanalyze multiple samples with Spectra Core and Spectra Intelligence ``` POST /api/samples/analyze_bulk/ ``` Schedule a set of samples that already exist on the Spectra Analyze appliance (previously uploaded) to be analyzed again. The `analysis` parameter is required. It supports the following values: - **cloud** - sends the samples to Spectra Intelligence for reanalysis - **core** - reanalyzes the samples with Spectra Core. When this option is provided in the request, it also triggers dynamic analysis processing if any of the supported dynamic analysis services is connected and configured on the appliance, and if the sample filetype matches the filetypes configured for any of those services. For more information about file type support, see [File types](../Administration/integrations-connectors/integrations.md#file-types). At least one `analysis` value must be specified in the request. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--------- | :------- | :----------------------------------------------------------- | :--------------- | | analysis | Required | Types of analysis that the requested sample(s) should be queued for. At least one value must be provided in the request. If providing multiple values, they should be comma-separated. Supported values: **cloud**, **core**, where *cloud* refers to Spectra Intelligence analysis and requires that the Spectra Analyze is connected to Spectra Intelligence, and *core* refers to Spectra Core static analysis. | application/json | | hash_value | Required | Hash of the sample(s) that should be reanalyzed. At least one hash must be provided in the request. All hashes in a request must be of the same type. Supported hash types: SHA1, SHA256, SHA512, MD5 | application/json | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/samples/analyze_bulk/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{"hash_value":["0000014db72d1427c8b34ba152476a9bfdb27844", "f51ef127e79bf2f59dc82cf993f8315967e4bbfe"], "analysis": "core,cloud"}' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = "https://appliance.example.com/api/samples/analyze_bulk/" headers = {'Authorization': f'Token {token}'} # Change the hashes json = { "hash_value": ["0000014db72d1427c8b34ba152476a9bfdb27844", "f51ef127e79bf2f59dc82cf993f8315967e4bbfe"], "analysis": "cloud,core" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, json=json) print(response.text) ``` ### Response Format **Response Examples** **Note: The top-level “code” and “message” values in the response are deprecated and are returned only for compatibility reasons. The “code” and “message” from the “analysis” section contain relevant information, and should be referred to instead.** ```json { "results": [ { "code": 201, "message": "Sample is queued for analysis.", "analysis": [ { "name": "cloud", "code": 201, "message": "Sample is queued for analysis." }, { "name": "core", "code": 201, "message": "Sample is sent to core analysis." } ], "detail": { "sha1": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "sha256": "aec070645fe53ee3b37630593 (...)", #shortened for clarity "sha512": "0b8754b06ca408c09e8672bce675f (...)", #shortened for clarity "md5": "14758f1afd44c09b7992073ccf00b43d" } }, { "code": 200, "message": "Sample is already queued for analysis.", "analysis": [ { "name": "cloud", "code": 201, "message": "Sample is queued for analysis." }, { "name": "core", "code": 201, "message": "Sample is sent to core analysis." } ], "detail": { "sha1": "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15", "sha256": "b5bb9d8014a0f9b1d61e21e796d (...)", #shortened for clarity "sha512": "1b8754b06ca408c09e8672bce (...)", #shortened for clarity "md5": "d3b07384d113edec49eaa6238ad5ff00" } } ] } ``` **Response Fields** | FIELD NAME | TYPE | | :--------- | :------ | | code | integer | | message | string | | analysis | object | | detail | object | | FIELD NAME | TYPE | | :---------------------- | :----- | | sha1 | string | | sha256 | string | | sha512 | string | | md5 | string | | imphash (PE files only) | string | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | Sample is already queued for analysis. | | 201 | Sample is queued for analysis. / Sample is queued for core analysis. | | 400 | Validation error. Value is not valid sha1, sha256, sha512 or md5 hash value. | | 405 | Reanalysis not allowed for extracted samples. / Not allowed for this type of appliance. | --- ## Redundant Status API — Spectra Analyze ``` GET /cluster_primary ``` In redundant (cluster) deployments, the primary node will respond with **200** at this address. If the queried appliance is not the primary node for whatever reason (instance is down, instance serves as the secondary node), it will respond with **404**. --- ## Report Summary API — Get Analysis Report Summaries ## Retrieve a summary analysis report for local samples ``` POST /api/samples/v2/list/ ``` Get a summary of the analysis report for a single sample or for multiple samples. The samples must be present on the Spectra Analyze appliance. Sample hashes must be provided using the `hash_values` parameter in the request. If the optional `fields` parameter is not included in the request, all available report fields for the requested sample(s) are returned in the response. The fields “ticore”, “ticloud”, “summary” and “aliases” are returned only if they are explicitly specified in the request. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :-------------------------------- | :------- | :----------------------------------------------------------- | :-------------------------- | | hash_values | Required | One or more hashes of samples for which the analysis report should be returned. The samples must be present on the appliance. Supported hash types are SHA1, SHA256, SHA512, MD5. All hashes in a request must be of the same type. | array | | fields | Optional | Comma-separated list of report fields to include in the response. When this parameter is not included in the request, all available fields are returned, except “ticore”, “ticloud”, “summary” and “aliases”. Supported values: `id, sha1, sha256, sha512, md5, category, file_type, file_subtype, identification_name, identification_version, file_size, extracted_file_count, local_first_seen, local_last_seen, classification_origin, classification_reason, classification_source, classification, riskscore, classification_result, ticore, tags, summary, ticloud, aliases, networkthreatintelligence, domainthreatintelligence, imphash, discussion, proposed_filename, av_scanners, av_scanners_summary` Network and domain threat intelligence results won’t be applied unless the parameter `include_networkthreatintelligence` is set to true. | array | | include_networkthreatintelligence | Optional | Include or exclude network or domain threat intelligence. If this is set to true, parameters `networkthreatintelligence` and `domainthreatintelligence` have to be included in the `fields` parameter. Applies only to URLs, not files. | boolean (but inside quotes) | | skip_reanalysis | Optional | Whether to reanalyze a file when fetching its report. False by default (if omitted, files will be reanalyzed when their reports are fetched). | boolean (but inside quotes) | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/samples/v2/list/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{"hash_values":["9dc5e23c7ab2692b83f0690a736b123a1837ae56", "4b21a49eadac1bc01477eff778041fdb765b8139"]}' ``` **cURL with optional parameters** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://a1000.example.com/api/samples/v2/list/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{"hash_values":["0da28a5159bee9cd930403023230f2e918b0334d"], "fields": ["summary"]}' ``` **Python** ```python # Change the token token = "exampletoken" # Change the hostname in the URL url = f"https://appliance.example.com/api/samples/v2/list/" json = { "hash_values": ["examplehash1", "examplehash2"], "fields": ["sha256", "extracted_file_count"] } headers = {'Authorization': f'Token {token}'} # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, json=json) print(response.text) ``` ### Response Format **Response Examples** Default response - all available fields ```json { "count": 1, "next": null, "previous": null, "results": [ { "id": 215590, "sha1": "3ecb56536b58d2e2ec0779d1c28a9f20024d6b66", "sha256": "eac444d6cddbae6972f0af91da5a89b0eb370c2f7bbe6f9706aaaf1f25f6c0d3", "sha512": "5586169dc50e339789b75f469e3 (...)", "md5": "6cadcefb80b7e757323aa46fba909d72", "imphash": "9612c82b4c865e0bf6797463aa91292a", "category": "application", "file_type": "PE", "file_subtype": "Exe", "identification_name": "UPX", "identification_version": "0.60-3.x", "file_size": 350720, "extracted_file_count": 9, "local_first_seen": "2017-02-06T18:10:54.594306Z", "local_last_seen": "2020-02-27T11:37:37.954472Z", "classification_origin": { "sha1": "8d0cbc4f10b2aa40f849bda9ee2524146870cc7a", "sha256": "cc8698fac45061e5bb1a2cc712d25c5ed5977f3b5b5cc55978562df942777815", "sha512": "96bf5eba3dfd04a5bccaeb45 (...)", "md5": "cf87a4c0f97ef995221650b4c8116e04", "imphash": "fe93401dae4bdb92076a6adf424ffc73" }, "classification_reason": "cloud", "classification": "malicious", "riskscore": 8, "classification_result": "Win32.Backdoor.Prorat", "tags": { "ticore": [ "yara", "indicator-network", "string-http", "capability-execution", "capability-filesystem", "capability-networking", "desktop", "indicator-execution", "indicator-monitor", "arch-x86", "gui", "packed", "entropy-high", "contains-pe", "file-download", "privacy-intrusion", "ftp-use", "compression-nrv", "cloud" ], "user": [ "RSA2016", "testtag1" ] } } ] } ``` Response for the optional `summary` field ```json { "count": 1, "next": null, "previous": null, "results": [ { "summary": { "id": 215600, "sha1": "0da28a5159bee9cd930403023230f2e918b0334d", "indicators": [ { "priority": 7, "category": 22, "description": "Deletes files in Windows system directories." }, { "priority": 7, "category": 11, "description": "Requests permission required to shut down a system." } ], "unpacking_status": { "failed": 0, "success": 1, "partial": 0 } } } ] } ``` **Response Fields** | FIELD NAME | TYPE | | :------------------------ | :----------------------------------------------------------- | | id | integer | | sha1 | string | | sha256 | string | | md5 | string | | category | string | | file_type | string | | file_subtype | string | | identification_name | string | | identification_version | string | | file_size | integer | | extracted_file_count | integer | | local_first_seen | string | | local_last_seen | string | | classification_origin | object | | classification_reason | string | | classification | string | | riskscore | integer | | classification_result | string | | tags | array | | aliases | array | | summary | *Summary* object | | ticore | corresponds to the `ticore` object from the [Spectra Core Report API](./static-analysis-report-api.md) | | ticloud | *Cloud* object | | imphash | string | | classification_source | integer | | discussion | array | | proposed_filename | string | | networkthreatintelligence | object | | domainthreatintelligence | object | | av_scanners | object | | av_scanners_summary | object | | FIELD NAME | DATA TYPE | | :--------- | :-------- | | sha1 | string | | sha256 | string | | sha512 | string | | md5 | string | | imphash | string | | FIELD NAME | DATA TYPE | | :--------------- | :------------------ | | id | integer (sample id) | | sha1 | string | | indicators | array | | unpacking_status | string | | FIELD NAME | DATA TYPE | | :-------------------- | :-------- | | classification | string | | riskscore | integer | | classification_result | string | | classification_reason | string | | first_seen | string | | last_seen | string | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | Returned on successful requests. | | 400 | Malformed hash or invalid field name. | | 403 | Authentication credentials were not provided. / Invalid token. | | 404 | Malformed endpoint. | --- ## Set Classification API — Override Sample Verdicts This API allows the user to set the classification of a sample, either in the Spectra Intelligence cloud or locally. ``` POST /api/samples/{hash_value}/setclassification/{system}/ ``` ``DELETE /api/samples/{hash_value}/setclassification/{system}/`` ## Request Format ### Request Parameters | NAME | REQUIRED | DESCRIPTION | TYPE | | :-------------- | :------------------------- | :----------------------------------------------------------- | :---------------------------- | | hash_value | Required | The sample hash for which the classification is being set or removed. If local, the sample must be present on the appliance. Supported hash types are SHA1, SHA256, SHA512, MD5. | path, string | | system | Required | `local` or `ticloud`. The request **must** end with a trailing slash. | path, string | | classification | Required for POST requests | Classification must be one of these values:`goodware``suspicious``malicious` | *multipart/form-data*, string | | risk_score | Optional | If specified, it must be within range for the specified classification. If not specified, a default value is used:Goodware: 0Suspicious: 6Malicious: 10 | *multipart/form-data*, string | | threat_platform | Optional | If specified, it must be on the [supported list](/General/AnalysisAndClassification/Classification/#malware-naming-standard) (platforms and subplatforms). If not specified, the default value is `Win32`. | *multipart/form-data*, string | | threat_type | Optional | If specified, it must be on the [supported list](/General/AnalysisAndClassification/Classification/#malware-naming-standard) (malware types). If not specified, the default value is `Malware`. | *multipart/form-data*, string | | threat_name | Optional | If specified, must be an alphanumeric string not longer than 32 characters. If not specified, the default value is `Generic`. | *multipart/form-data*, string | ### Request Examples **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/samples/cf8e42c4a0862c807f0de3c656d2cd1c99cc5a27/setclassification/local/' \ --form classification=goodware \ --form risk_score=0 \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the hostname in the URL url = f"https://appliance.example.com/api/samples/{hash_value}/setclassification/local/" payload = { "classification": "goodware", "risk_score": "0" } headers = {'Authorization': f'Token {token}'} # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, data=payload) print(response.text) ``` ## Response Format ### Response Examples ```json { 'classification': 'suspicious', 'risk_score': 6, 'threat_name': 'Win32.Malware.Generic' } ``` ### Response Fields **Local POST** ```yaml properties: classification: type: string enum: - goodware - suspicious - malicious risk_score: type: integer minimum: 0 maximum: 10 threat_name: type: string ``` **Local DELETE** ``` properties: code: type: integer detail: type: object properties: error: type: string message: type: string ``` **Spectra Intelligence POST** Response body is available only in case of an error. If the return code is 200, no response body is included. ### Response Status Codes - 201 POST success. - 204 DELETE success. - 400 Bad Request. Validation error. Parameters in the request are invalid or missing. - 403 Forbidden. Authentication credentials are invalid or missing. - 404 Local only: - POST and DELETE: sample does not exist on the appliance. - DELETE: sample has no current override to remove. Spectra Intelligence only: - Spectra Intelligence system is not configured. - 429 Too Many Requests. This happens if system resources are depleted. By default, this means that the system is using 90% or more of its available memory, or that it holds more than 50 items in the processing queue. The precise values are configurable (either on the *Administration > Configuration > Resource Usage Limits* page or via [Spectra Detect](/SpectraDetect/) Manager). --- ## Static Analysis Report API — Get Spectra Core Results ## Retrieve [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) analysis results for a local sample ``` GET /api/v2/samples/{hash_value}/ticore/ ``` Get the full Spectra Core static analysis report for the requested sample. The requested sample must be present on the appliance. If the optional `fields` parameter is not provided in the request, all available parts of the static analysis report are returned in the response. With this parameter, users can select which parts of the report they want to receive in the response. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--------- | :------- | :----------------------------------------------------------- | :------------ | | hash_value | Required | Hash of the sample for which the analysis report should be returned. The sample must be present on the appliance. Supported hash types are SHA1, SHA256, SHA512, MD5. | path, string | | fields | Optional | Comma-separated list of report fields to include in the response. Supported values: `sha1, sha256, sha512, md5, imphash, info, application, protection, security, behaviour, certificate, document, mobile, media, web, email, strings, interesting_strings, classification, indicators, tags, attack, story, signatures, browser, software_package, malware` | query, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/v2/samples/988881adc9fc3655077dc2d4d757d480b5ea0e11/ticore/?fields=sha256,story,interesting_strings' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the host name in the URL and the fields to be included in the response url = f"https://appliance.example.com/api/v2/samples/{hash_value}/ticore/?fields=sha256,story,interesting_strings" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Examples** ```json { "sha1": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "sha256": "aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f", "sha512": "e79b8ad22b34a54be999f4eadde2ee895c208d4b3d83f1954b61...", # shortened for clarity "md5": "14758f1afd44c09b7992073ccf00b43d", "imphash": # for PE files only "info": {...}, "application": {...}, "protection": {...}, "security": {...}, "behaviour": {...}, "certificate": {...}, "signatures": {...}, "document": {...}, "mobile": {...}, "media": {...}, "web": {...}, "email": {...}, "strings": [...], "interesting_strings": [...], "classification": {...}, "indicators": [...], "attack": [...], "tags": [...], "story": {...}, } ``` **Response Fields** | FIELD NAME | TYPE | DESCRIPTION | | :------------------ | :----- | :----------------------------------------------------------- | | sha1 | string | SHA1 hash of the sample | | sha256 | string | SHA256 hash of the sample | | sha512 | string | SHA512 hash of the sample | | md5 | string | MD5 hash of the sample | | imphash | string | Import hash of the sample. Retrieved only for PE files | | info | object | Information about file type, size, embedded files, and hashes computed for the sample | | application | object | If the sample is an application, contains information about its structure and capabilities | | protection | object | Detected protection features and mechanisms such as cryptographic or compression algorithms | | security | object | Detected security-related features, such as exploits | | behaviour | object | Detected behavior properties of the sample | | certificate | object | Certificate-related information extracted from the sample, such as issuer, thumbprint, signature | | signatures | object | Signature-related information extracted from the sample, such as issuer, thumbprint, signature | | document | object | If the sample is a document, contains information about its structure and capabilities | | mobile | object | If the sample is a mobile application, contains information about its structure and capabilities | | media | object | If the sample is a multimedia file, such as an image, contains information about its properties | | web | object | If the sample is a web application or browser addon, contains information about its structure and capabilities | | email | object | If the sample is an email message, contains information about its metadata | | strings | array | Strings extracted from the sample | | interesting_strings | array | URI strings extracted from the sample | | classification | object | Sample status and source of classification | | indicators | array | Detected actions that the sample is capable of performing, and their descriptions | | attack | array | Spectra Core indicators mapped to MITRE threat IDs and techniques | | tags | array | Labels automatically generated by Spectra Core during analysis based on the sample’s metadata properties (“ticore”) or added by the users on the appliance (“user”) | | story | string | Natural language file behavior description | | browser | object | Browser-related data | | software_package | object | Software package data | | malware | object | Malware-related data | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------- | | 200 | OK | | 403 | Forbidden | | 404 | Not found | --- ## Submissions API — Upload Files & URLs to Spectra Analyze ## Submitting a File ``` POST /api/submit/file/ ``` This endpoint allows users to submit a single file to the appliance for analysis using static and (optionally) dynamic services. Only one file can be submitted per request. ### Request parameters | NAME | REQUIRED | TYPE | DESCRIPTION | | ------------------ | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- | | `file` | Yes | `file` (binary) | The file to be uploaded for analysis. Only one file is allowed per request. | | `filename` | No | `string` | Custom filename to assign. If omitted, the SHA1 or original filename is used. | | `tags` | No | `string` (CSV) | Comma-separated user tags (case-sensitive). Spaces and underscores are distinct. | | `comment` | No | `string` (HTML) | Visible in the UI. Supports: ``, ``, ``, ``, ``, ``, ``. | | `archive_password` | No | `string` | Password for ZIP file. Archive must contain exactly one file. Only the extracted file is analyzed. | | `analysis` | No | `object` (JSON) | Optional dictionary that defines which analyses are triggered. If omitted, automatic rules from **Administration > Integrations** apply. | | `metadata` | No | `object` (JSON) | Optional metadata about file origin, connector, or source. | ## Submitting a URL ``` POST /api/submit/url/ ``` This endpoint allows users to submit a single URL for crawling and analysis. The downloaded content is analyzed as a ZIP archive. ### Request parameters | NAME | REQUIRED | TYPE | DESCRIPTION | | ---------- | -------- | --------------- | --------------------------------------------------------------------------------------------------- | | `url` | Yes | `string` | The URL to be crawled and analyzed. Must use HTTP or HTTPS. | | `crawler` | No | `string` | Defines crawler behavior: `local` (private) or `cloud` (Spectra Intelligence). Defaults to `local`. | | `analysis` | No | `object` (JSON) | Optional dictionary to trigger specific analyses.| **Note: If `rl_dynamic_analysis` is specified in `analysis`, the URL is also sent to **Network Analysis**, and the downloaded archive is sent to **static and dynamic file analysis**.** #### `analysis` dictionary structure (file and URL submissions) ```json { "local_only": boolean "rl_dynamic_analysis": { "platform": Platforms, "geolocation": Geolocations, "locale": Locales "sample_name": string "internet_simulation": boolean "timeout": integer }, "rl_auxiliary_analysis": boolean, "cloud": boolean, "cape": boolean, "cisco_secure_malware_analytics": { "profile": string }, "cuckoo": boolean, "fireeye": { "profile": string }, "joe": { "profile": string }, "vmray_tcbase": boolean } ``` All fields are optional. If `local-only` is set to `true`, the file is analyzed exclusively on the appliance. The sample is **not** sent to any configured integrations, sandboxes, or Spectra Intelligence services. Other analysis profiles are defined in **Administration → Integrations → Profiles**. If omitted or empty, automatic profile selection is applied. To exclude a service, omit it. For more information, see [ReversingLabs Cloud Sandbox analysis service integration](../Analysis-services/cloud-sandbox.md). #### Supported values * `platform`: `windows7`, `windows10`, `windows11`, `macos_11`, `linux` * `geolocation`: `us`, `uk`, `in`, `br`, `de`, `jp`, `sg`, `it`, `es`, `fr`, `tor` * `locale`: `en-US`, `en-GB`, `pt-BR`, `de-DE`, `ja-JP`, `it-IT`, `es-ES`, `fr-FR` #### `metadata` dictionary structure (file submissions) ```json { "source_address": "string" "file_dir": "string", "file_origin_link": "string", "hostname": "string", "filter_name": "string", "source_tag": "string", "additional_data": "{"key": "value"}" } ``` ### Response format ```json { "code": 201, "message": "Done.", "detail": { "id": 1, "sha1": "0000000000000000000000000000000000000000", "user": 1, "created": "2020-20-20T20:20:20.000000Z", "filename": "some_archive.zip" } } ``` ### Response fields | FIELD NAME | DESCRIPTION | | ---------- | ------------------------------------------ | | `code` | Status response code (e.g., `201`). | | `message` | Descriptive response message. | | `detail` | Object with metadata about the submission. | **detail fields:** | FIELD NAME | DESCRIPTION | | ---------- | -------------------------------------------- | | `id` | Submission task ID. | | `sha1` | SHA1 hash of the uploaded or extracted file. | | `user` | Internal user ID of the submitter. | | `created` | UTC timestamp of submission creation. | | `filename` | Final name assigned to the file. | --- ## Response Status Codes | CODE | DESCRIPTION | | ----- | ------------------------------------------------------------------- | | `201` | Submission accepted and queued for analysis. | | `400` | Bad request. Validation error or missing/invalid parameters. | | `403` | Authentication failed or token missing. | | `405` | Appliance is in maintenance mode. Uploads disabled. | | `413` | File or download exceeds configured size limits. | | `429` | Too many submissions. Resource limits (RAM, queue, quota) exceeded. | | `503` | Appliance disk usage too high. Uploads temporarily blocked. | --- ## Tags API — Manage User Tags for Samples With this API, users can list existing tags and add/remove one or more tags for any sample on the Spectra Analyze appliance. The API only allows working with User Tags (custom tags created by users), and cannot be used to modify System Tags (non-editable tags generated by Spectra Core during file analysis). Learn more about [tags and how they work](../system-and-user-tags.md) on the Spectra Analyze appliance. The API accepts GET, POST, and DELETE requests with a single sample hash per request. Supported hash types are SHA1, SHA256, MD5. The sample hash is a required parameter that must be provided in every request. ## Retrieve User Tags for a sample ``` GET /api/tag/{sample_hash}/ ``` Lists existing tags for the requested sample, if there are any. The sample hash is a required parameter that must be provided in the request. Supported hash types are SHA1, SHA256, MD5. Only User Tags are returned in the response - if the sample has any System Tags, they will not be included in the response. If the requested sample doesn’t have any User Tags at all, the response contains an empty list. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :---------- | :------- | :----------------------------------------------------------- | :----------- | | sample_hash | Required | Hash of the sample for which the user wants to list existing User Tags. The sample must be present on the appliance prior to sending a request. Supported hash types: SHA1, SHA256, MD5 | path, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/tag/00b814bad1ede64dd87ecf218d5e90f13dd408ae/' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of url, token, and hash_value token = "exampletoken" hash_value = "6229448f764c8692579e242d1479ee529632203a" url = f"https://appliance.example.com//api/tag/{hash_value}/" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Examples** ```json [ "tag1", "tag2", "tag3", "Tag_1" ] ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | Successful request | | 403 | Authentication credentials were not provided. The API token must be included in every request. / Invalid API token. | | 404 | Malformed hash or missing trailing slash in the endpoint. / Sample does not exist on the appliance. | ## Create User Tags for a sample ``` POST /api/tag/{sample_hash}/ ``` Adds one or more User Tags to the requested sample, regardless of whether the sample already has any tags. The prerequisite is that the sample exists on the appliance. **Tip: Users who wish to add tags to samples that exist in the ReversingLabs Spectra Intelligence cloud, but are not present on the appliance, can download them from the cloud using the [Download API](./download-api.md).** Alternatively, the ReversingLabs Spectra Intelligence File Download API (TCA-0201) can be used in combination with the [Submissions API](./submissions.md). In this workflow, the Spectra Intelligence File Download API is used to fetch samples from the cloud to the local system. The users can then upload those samples to Spectra Analyze and add tags to them in the upload POST request. For more information about using the Spectra Intelligence File Download API, contact ReversingLabs Support. The sample hash is a required parameter that must be provided in the request. Supported hash types are SHA1, SHA256, MD5. All POST requests to this API must contain the `Content-Type: application/json` header. Tags must be provided in the request body according to the following format: ```json {"tags": ["tag1", "tag2", ...]} ``` The response to a successful request is a list of tags added to the sample. If the request contains one or more duplicate User Tags (tags that have already been added to the sample), those will be ignored. Such duplicate tags won’t be added to the sample, and won’t be listed in the response. If the user attempts to add a tag that is identical to a System Tag already added to the sample, it will be ignored. However, it is possible to add a User Tag identical to a System Tag if the requested sample does not have that System Tag. For example, `antisandbox` is a System Tag. If the requested sample has this tag, attempting to add a tag called `antisandbox` will not succeed. If the requested sample doesn’t have it, the `antisandbox` tag will be added as a User Tag, and listed in the response. If the request contains only duplicate tags, the response will be empty. If other valid, unique tags are sent in the same request with duplicate tags, then only the unique tags will be added to the sample and listed in the response. If any of the tags in the request is malformed, the request will fail and no tags will be added to the sample. The response will indicate which tag was malformed by the number of its element in the `tags` array. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :---------- | :------- | :----------------------------------------------------------- | :----------- | | sample_hash | Required | Hash of the sample to which the user wants to add one or more User Tags. The sample must be present on the appliance prior to sending a request. Supported hash types: SHA1, SHA256, MD5 | path, string | | tags | Required | One or more tags to add to the requested sample. A single tag must be between 2 and 40 characters long (including spaces), matching the supported pattern. Supported characters for tags are `[a-z0-9][a-z0-9 /._-]`. Tags are case-sensitive and distinguish spaces from underscores. In other words, `Example` and `example` are two separate tags; `test_tag` and `test tag` are separate tags, too. The following examples are **valid tags**: `malware_1`, `ClassifiedByYARA`, `false-positive`, `Better.Test/Tag`. The following examples illustrate **invalid tags**: `Ž++`, `#hashtag`, `*.exe`. | form, array | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/tag/00b814bad1ede64dd87ecf218d5e90f13dd408ae/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{"tags":["new-tag", "Another_Tag"]}' ``` **Python** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the hostname in the URL url = f"https://appliance.example.com/api/tag/{hash_value}/" json = {"tags": ["new-tag", "Another_Tag"]} headers = {'Authorization': f'Token {token}'} # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, json=json) print(response.text) ``` ### Response Format **Response Examples** ```json [ "new-tag", "Another_Tag" ] ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | Successful request | | 403 | Authentication credentials were not provided. The API token must be included in every request. / Invalid API token. | | 404 | Malformed hash or missing trailing slash in the endpoint. / Sample does not exist on the appliance (but may exist in the Spectra Intelligence cloud). | ## Delete User Tags from a sample ``DELETE /api/tag/{sample_hash}/`` Removes one or more User Tags from the requested sample. The prerequisite is that the sample exists on the Spectra Analyze appliance. The sample hash is a required parameter that must be provided in the request. Supported hash types are SHA1, SHA256, MD5. All POST requests to this API must contain the `Content-Type: application/json` header. Tags must be provided in the request body according to the following format: ```json {"tags": ["tag1", "tag2", ...]} ``` The response to a successful request is a list of removed tags. If any of the tags in the request is malformed, the request will fail and no tags will be removed. The response will indicate which tag was malformed by the number of its element in the `tags` array. Tags that don’t exist for the sample are ignored and not included in the response. If the request contains a combination of tags that exist and tags that don’t, only the existing ones will be removed and included in the response. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :---------- | :------- | :----------------------------------------------------------- | :----------- | | sample_hash | Required | Hash of the sample from which the user wants to remove one or more User Tags. The sample must be present on the appliance prior to sending a request. Supported hash types: SHA1, SHA256, MD5 | path, string | | tags | Required | One or more tags to remove from the requested sample. A single tag must be between 2 and 40 characters long (including spaces), matching the supported pattern. Supported characters for tags are `[a-z0-9][a-z0-9 /._-]`. Tags are case-sensitive and distinguish spaces from underscores. In other words, `Example` and `example` are two separate tags; `test_tag` and `test tag` are separate tags, too. The following examples are **valid tags**: `malware_1`, `ClassifiedByYARA`, `false-positive`, `Better.Test/Tag`. The following examples illustrate **invalid tags**: `Ž++`, `#hashtag`, `*.exe`. | form, array | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X DELETE 'https://appliance.example.com/api/tag/00b814bad1ede64dd87ecf218d5e90f13dd408ae/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{"tags":["new-tag", "Another_Tag"]}' ``` **Python** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the hostname in the URL url = f"https://appliance.example.com/api/tag/{hash_value}/" json = {"tags": ["example-tag-1", "Example_Tag_2"]} headers = {'Authorization': f'Token {token}'} # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.delete(url, headers=headers, json=json, verify=False) print(response.text) ``` ### Response Format **Response Examples** ```json [ "delete-this-tag", "Old Tag" ] ``` **Response Status Codes** | CODE | DESCRIPTION | | :-------------- | :----------------------------------------------------------- | | 200 | Successful request | | 400 Bad Request | Validation error. Returned when the list of tags is empty, when one or more tags contain unsupported characters, and when the `tags` field is missing in the request body. | | 403 | Authentication credentials were not provided. The API token must be included in every request. / Invalid API token. | | 404 | Malformed hash or missing trailing slash in the endpoint. / Sample does not exist on the appliance (but may exist in the Spectra Intelligence cloud). | --- ## Timezone API — Spectra Analyze This API allows users to set the timezone for the appliance and list available timezones. ## Set the timezone for the appliance This API allows users to set the timezone for the appliance. ``` POST api/v1/config/configure-timezone/ ``` ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | |:-------------|:---------|:---------------------------------------|:-----------------| | timezone | Required | Timezone to set for the appliance. | application/json | **Request Examples** **cURL** ```shell # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X 'POST' \ 'http://api.example.com/api/v1/config/configure-timezone/' \ -H 'Authorization: Token ' \ --json '{"timezone": "Europe/Zagreb"}' ``` **Python** ```python # Change the values of the URL, headers, and data url = "http://api.example.com/api/v1/config/configure-timezone/" headers = { "Authorization": f"Token ", "Accept": "application/json", "Content-Type": "application/json" } data = { "timezone": "Europe/Zagreb" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, json=data, verify=False) print(response.status_code) print(response.text) ``` ### Response Format The response does not return any data or response body. ## List available timezones This API allows users to list available timezones for the appliance. ``` GET api/v1/config/list-available-timezones/ ``` **Request example** **cURL** ```shell curl 'http://api.example.com/api/v1/config/list-available-timezones/' \ -H 'Authorization: Token ' ``` ### Response Format The response format returns a list of available timezones. ```json { "timezones": [ "Africa/Abidjan", "Africa/Accra", "Africa/Addis_Ababa", "Africa/Algiers", "Africa/Asmara", "Africa/Bamako", "Africa/Bangui", "Africa/Banjul", "Africa/Bissau", "Africa/Blantyre", "Africa/Brazzaville", "Africa/Bujumbura", "Africa/Cairo", "Africa/Casablanca", "Africa/Ceuta", "Pacific/Wallis", "UTC" ] } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------- | | 200 | OK | --- ## Obtain API Authentication Tokens for Spectra Analyze The appliance relies on token-based authentication for all its APIs. This means that every user must include their API token in all API requests. An existing user can get an API token if their user account is active on the appliance, and if they are not locked out of the appliance because of login security settings at the time of requesting a token. If a user does not have an account on the instance, or if their account exists but is not active, they will not be able to receive an API token. If this happens, contact the appliance administrator. Regular users can request their API token via the Authentication API. Administrators can use the Authentication API to request a token, or they can use the options on the Administration ‣ Tokens page. ## Obtaining a token via Authentication API (All users) ``` POST /api-token-auth/ ``` Administrators and regular users can request an API token by sending a request to the Authentication API. Users must submit their Spectra Analyze username and password in a POST request to the Authentication API endpoint on the same instance where their user account has been created. An authentication token is not required for requests to this API. If the request has succeeded, the Authentication API responds with a status code 200 and the user’s token in the response body. Users should copy and save this token, because it must be used in requests to all other appliance APIs. Username and password are required for obtaining an API token. If any or both of those parameters are missing or incorrect in the request, the Authentication API responds with a status code 400 and an error message in the response body. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :------- | :------- | :----------------------------------------------------------- | :----------- | | username | Required | Username of an existing, active account on the appliance instance for which the user wants to obtain an API token. | form, string | | password | Required | Password of an existing, active account on the appliance instance for which the user wants to obtain an API token. | form, string | ### Request Examples Using these examples will expose the password in the shell history. **cURL** ``` # Add --insecure before the URL if you are using a self-signed SSL certificate curl --request POST 'https://appliance.example.com/api-token-auth/' --form 'username="example_user"' --form 'password="example_password"' ``` **Python** ``` # Change the hostname in the URL url = "https://appliance.example.com/api-token-auth/" json = {'username': 'example_user', 'password': 'example_password'} # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.request("POST", url, json=json) print(response.text) ``` ### Response Format **Response Examples** ``` { "token": "988881adc9fc3655077dc2d4d757d480b5ea0e11" } ``` The token received from the Authentication API must be used in the *Authorization* header when sending requests to all other APIs, for example: ``` curl -H "Authorization: Token 988881adc9fc3655077dc2d4d757d480b5ea0e11" https://a1000.example.com/api/samples/B12B33EAA90E3A3C34D3366254224EA15CF9CC52/ticore/ ``` **Response Fields** | FIELD NAME | DESCRIPTION | TYPE | | :--------- | :----------------------------------------------------------- | :----- | | token | Authentication token for the user who sent the request. This token must be used in the *Authorization* header of all API requests. The token is tied to the user account, meaning it works only on the appliance instance where it was generated. | string | **Response Status Codes** | CODE | DESCRIPTION | | :--- | :------------------------------------------ | | 200 | OK | | 400 | Unable to log in with provided credentials. | ## Obtaining a token from the Spectra Analyze GUI (Administrators only) In addition to using the Authentication API, administrators can obtain tokens and create tokens for other users from the Spectra Analyze **Administration** page. On the Administration page, click the *Tokens* icon to open the Tokens page. On the [Tokens](/SpectraAnalyze/Administration/users-personalization/tokens/) page, create a new token key by clicking the Add Token button to navigate to the *Add token* dialog. Select the desired user and click the *Save* button. ![_images/analyze-restapi-1-tokens.png](images/analyze-restapi-1-tokens.png) The new key will be listed in the token table. The key can now be copied and inserted into requests to the Spectra Analyze APIs. ![_images/analyze-restapi-2-tokens.png](images/analyze-restapi-2-tokens.png) --- ## YARA API — Manage YARA Rulesets on Spectra Analyze ## Retrieve a list of YARA rulesets on the appliance ``` GET /api/yara/v2/rulesets/ ``` Retrieve a list of YARA rulesets that are on the Spectra Analyze appliance. The list can be filtered by several criteria (ruleset status, source, and owner) using optional parameters. For every ruleset in the list, the output includes additional information such as: ruleset name, total number of matches, last matched date, and more. If the optional `type` parameter is not provided in the request, the response includes only the default ruleset type (“my”, meaning the rulesets owned by the user sending the request). By default, Spectra Core rulesets are not included in the response. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :-------- | :------- | :----------------------------------------------------------- | :------------ | | type | Optional | Filter YARA rulesets on the appliance by their owner. When this parameter is provided in the request, only the rulesets matching the specified type are returned in the response. Supported values: `my` (default - currently authenticated user), `user`, `system`, `all` | query, string | | status | Optional | Filter YARA rulesets on the appliance by their status. When this parameter is provided in the request, only the rulesets matching the specified status are returned in the response. Supported values: `all` (default), `error`, `active`, `disabled`, `pending`, `invalid`, `capped` | query, string | | source | Optional | Filter YARA rulesets on the appliance by their source. When this parameter is provided in the request, only the rulesets matching the specified source are returned in the response. Supported values: `all` (default), `local`, `cloud` | query, string | | page | Optional | Optional parameter used for pagination. When this parameter is omitted from the request, all available results are returned at once. **This parameter cannot be used without** `page_size`. Use `page_size` to set how many results should be on each page, and then specify which page to return with `page` in the same request. The `count` value in the response indicates the total number of results. Use this number as guidance for pagination. The values of `page size` and `page` multiplied must not exceed the `count` value. For example, if `count` is 80 and `page_size` is set to 10, it is not possible to request `page=9`. | query, string | | page_size | Optional | Optional parameter that controls how many results to return per page in the response. **This parameter cannot be used without** `page`. When this parameter is omitted from the request, all available results are returned at once. | query, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/yara/v2/rulesets/' \ --header 'Authorization: Token exampletoken' ``` **cURL with pagination** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://a1000.example.com/api/yara/v2/rulesets/?page_size=10&page=2' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the host name in the URL and the fields to be included in the response url = f"https://appliance.example.com/api/yara/v2/rulesets/" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Examples** ```json { "count": , "next": "http://192.168.1.101/api/yara/rulesets/?type=&status=&source=&page=&page_size=", "results": [{ "status": "active", "suspicious_match_count": 10, "goodware_match_count": 1, "cloud_synced": False, "malicious_match_count": 100, "name": 'ruleset name", "owner": "user name", "last_matched": "2017-03-14T11:19:31.978544Z", "system_ruleset": False, "unknown_match_count": 0 }, ... ] } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :------------------------------ | | 200 | OK | | 400 | Parameter not in expected range | | 401 | Unauthorized | ## Retrieve the contents of a YARA ruleset ``` GET /api/yara/ruleset/content/?name={ruleset_name} ``` Retrieve the full contents of the requested ruleset in raw text/plain format. All rulesets can be retrieved, regardless of their current status on the appliance (enabled, disabled…). ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :--- | :------- | :----------------------------------------------------------- | :------------ | | name | Required | Name of the YARA ruleset to retrieve. Ruleset names are case-sensitive. | query, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/yara/ruleset/content/?name=example_ruleset' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the host name in the URL and the fields to be included in the response url = f"https://appliance.example.com/api/yara/ruleset/content/?name=example_ruleset" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Example** ``` { "code": 200, "detail":{ "name":"ruleset_name" "content":"import \"pe\"\n\nrule TestYaraRule : malicious\n{\n ... \n \n}", } } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------------------------------------- | | 200 | OK | | 400 | Missing or invalid ruleset name parameter | | 404 | Ruleset not found | ## Retrieve YARA matches for specified rulesets ``` GET /api/yara/v2/ruleset/matches/?name={ruleset_name} ``` Retrieve the list of YARA matches (both local and cloud) for requested rulesets. If multiple rulesets are provided in the request, only the samples that match all requested rulesets are listed in the response. The *cloud* field in the response indicates whether the match happened locally (returns “false”) or in the Spectra Intelligence cloud (returns “true”). The same sample can return different values for the *cloud* field, if that sample is found on the Spectra Analyze instance and in the cloud. **Known issue**: if the sample is not found locally but only in the cloud, the `extracted_file_count` and `sha256` fields contain `null`. If the requested rulesets don’t have any matches, an empty response is returned. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | | :-------- | :------- | :----------------------------------------------------------- | :------------ | | name | Required | Name of the YARA ruleset for which to retrieve matches. At least one value must be provided in the request. Ruleset names are case-sensitive. If multiple ruleset names are provided in the request, only the samples that match all requested rulesets are listed in the response. When providing multiple ruleset names, they should be serialized as form-style query expansion (example: `/?name=ruleset1&name=ruleset2&name=...`). | query, string | | page | Optional | Optional parameter used for pagination. When this parameter is omitted from the request, all available results are returned at once. **This parameter cannot be used without** `page_size`. Use `page_size` to set how many results should be on each page, and then specify which page to return with `page` in the same request. The `count` value in the response indicates the total number of results. Use this number as guidance for pagination. The values of `page size` and `page` multiplied must not exceed the `count` value. For example, if `count` is 80 and `page_size` is set to 10, it is not possible to request `page=9`. | query, string | | page_size | Optional | Optional parameter that controls how many results to return per page in the response. **This parameter cannot be used without** `page`. When this parameter is omitted from the request, all available results are returned at once. | query, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/yara/v2/ruleset/matches/?name=example_ruleset' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the values of token and hash_value token = "exampletoken" hash_value = "examplehash" # Change the host name in the URL and the fields to be included in the response url = f"https://appliance.example.com/api/yara/v2/ruleset/matches/?name=example_ruleset" headers = { "Authorization": f"Token {token}" } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` ### Response Format **Response Examples** ```json { "count": , "next": "http://192.168.1.101/api/yara/ruleset/matches/?name=&page=&page_size=", "results": [{ "classification": 3, "sha1": "4e43fa0f1c715ea704102a9a4f59bfe0520419b8", "sha256": "250c3b6198639bead80aee27825cd9aadf774f747a392e7c30984cf78277c422", "created": "2017-03-14T11:19:31.978544Z", "file_type": "PE/Exe", "extracted_file_count": 60, "rule": "test", "filename": "4e43fa0f1c715ea704102a9a4f59bfe0520419b8", "classification_result": "Win32.Trojan.Injector", "downloadable": true, "file_size": 608768, "riskscore": 10, "cloud": false, "md5": "6867a9aaa3666c511163ee4fe513f038" }, ... ] } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :---------------------------------------- | | 200 | OK | | 400 | Missing or invalid ruleset name parameter | | 404 | Ruleset not found | ## Create or update a YARA ruleset ``` POST /api/yara/ruleset/ ``` Creates a new YARA ruleset if it doesn’t exist. If a ruleset with the specified name already exists, a new revision (update) of the ruleset is created. Spectra Core rulesets cannot be modified with this API. Pass the entire ruleset as **form data** under `content`. The content type is `application/x-www-form-urlencoded`. **Restrictions** 1. YARA ruleset names on Spectra Analyze are case-sensitive and character-limited. When naming rulesets, keep the name between 3 and 48 characters. Generally, the underscore ( _ ) should be used instead of spaces, and any other special characters should be avoided. It is recommended to only use numbers (0-9) and a-z/A-Z letters in YARA ruleset names. 2. Rulesets larger than 1 MB (1048576 bytes) can be created and used on the appliance, but they cannot be saved and executed in the Spectra Intelligence cloud. 3. YARA rulesets on Spectra Analyze are not applied to files larger than 700 MB. ### Request Format **Request Parameters** | FIELD | REQUIRED | DATA TYPE | DESCRIPTION | PARAMETER TYPE | | :------ | :------- | :-------- | :----------------------------------------------------------- | :------------- | | name | required | string | Name of the ruleset to create or update. | form | | content | required | string | Content of the YARA ruleset to create or update. | form | | publish | optional | string | Determines whether the ruleset should be synchronized to other appliances in the same [Spectra Detect](/SpectraDetect/) Manager cluster. Usable only with administrator tokens if the Spectra Analyze is configured to allow only users with the appropriate user roles to synchronize YARA actions. Requires YARA synchronization to be enabled on the Spectra Analyze appliance. | form | | ticloud | optional | bool | Determines whether the ruleset should be synchronized with Spectra Intelligence or not. The value can be true or false; default is false. This parameter is equivalent to the *Run ruleset continuously in Spectra Intelligence* option in the graphical Spectra Analyze YARA editor. | form | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/yara/ruleset/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'name=example_ruleset' \ --data-urlencode 'content=rule example_rule {condition:false}' ``` **Python** ```python # Change the token token = "exampletoken" # Change the host name in the URL url = "https://appliance.example.com/api/yara/ruleset/" payload='name=example_ruleset&content=rule example_rule {condition: false}' headers = { 'Authorization': f'Token {token}', 'Content-Type': 'application/x-www-form-urlencoded' } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, data=payload) print(response.text) ``` ### Response Format **Response Example** ```json { "code": 200, "message": "Ruleset updated/created successfully." "detail": { "name": "ruleset_name" } } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | OK | | 400 | Parameter not in expected range | | 401 | “Core ruleset cannot be updated” for Spectra Core rulesets. | | 403 | This response is returned when the request isn’t authenticated. Possible cause is that the publish parameter was provided, but the token doesn’t have permission. | | 409 | Rulesets cannot be updated while their Spectra Intelligence validation is pending, or while a Cloud Retro hunt is running. | | 500 | Error while creating or updating ruleset. Ruleset saved successfully, but due to errors the system cannot run it. | ## Delete a YARA ruleset and its matches from the appliance ``DELETE /api/yara/ruleset/`` Delete the specified YARA ruleset and its matches from the appliance. Spectra Core rulesets cannot be deleted. Only users with the appropriate user roles can delete rulesets created by other users. ### Request Format **Request Parameters** | | REQUIRED | DATA TYPE | DESCRIPTION | PARAMETER TYPE | | :------ | :------- | :-------- | :----------------------------------------------------------- | :------------- | | name | required | string | Name of the ruleset to delete. Ruleset names are case-sensitive. | form | | publish | optional | string | Determines whether the ruleset deletion should be synchronized to other appliances in the same Spectra Detect Manager cluster, if the appliance is configured to allow only users with the appropriate user roles to synchronize YARA actions. Requires YARA synchronization to be enabled on the appliance, as well as on the connected Spectra Detect Manager. Usable only with administrator tokens. | form | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X DELETE 'https://appliance.example.com/api/yara/ruleset/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'name=example_ruleset' ``` **Python** ```python # Change the token token = "exampletoken" # Change the host name in the URL url = "https://appliance.example.com/api/yara/ruleset/" payload='name=example_ruleset' headers = { 'Authorization': f'Token {token}', 'Content-Type': 'application/x-www-form-urlencoded' } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.delete(url, headers=headers, data=payload) print(response.text) ``` ### Response Format **Response Example** ```json { "core": 200 "message": "Ruleset deleted successfully.", "detail":{ "name": "example_ruleset" } } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | OK | | 400 | Missing or invalid ruleset name parameter | | 401 | Unauthorized action; ruleset is a Spectra Core ruleset or was created by another user | | 403 | This response is returned when the request isn’t authenticated. Possible cause is that the publish parameter was provided, but the token doesn’t have permission. | | 404 | Ruleset not found | | 500 | Error occurred while deleting ruleset | ## Enable/Disable a YARA ruleset ``` POST /api/yara/ruleset/{enable | disable}/ ``` Enables a previously disabled YARA ruleset, or disables a currently enabled YARA ruleset. Administrators can enable/disable any ruleset on the appliance via this endpoint. Regular Spectra Analyze users can only enable/disable their own rulesets. ### Request Format **Request Parameters** | FIELD | REQUIRED | DATA TYPE | DESCRIPTION | PARAMETER TYPE | | :------------- | :------- | :-------- | :----------------------------------------------------------- | :------------- | | enable/disable | required | string | Whether to enable or disable the specified ruleset. | path | | name | required | string | Name of the ruleset to enable/disable. Ruleset names are case-sensitive. | form | | publish | optional | string | Determines whether the ruleset action should be synchronized to other appliances in the same Spectra Detect Manager cluster. Usable only with administrator tokens if the appliance is configured to allow only users with the appropriate user roles to synchronize YARA actions. Requires YARA synchronization to be enabled on the appliance, as well as on the connected Spectra Detect Manager. | form | The URL must end with a forward slash (`/`). **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/yara/ruleset/disable/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'name=example_ruleset' ``` **Python** ```python # Change the token token = "exampletoken" # Change the host name in the URL url = "https://appliance.example.com/api/yara/ruleset/disable/" payload = 'name=example_ruleset' headers = { 'Authorization': f'Token {token}', 'Content-Type': 'application/x-www-form-urlencoded' } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, data=payload) print(response.text) ``` ### Response Format **Response Examples** ``` { "code": 200, "message": "Ruleset enabled successfully." "detail": { "name: "ruleset name" } } { "code": 200, "message": "Ruleset disabled successfully." "detail": { "name": "ruleset name" } } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--------------- | :----------------------------------------------------------- | | 200 | In case the user also provides the publish parameter, but doesn’t have permissions due to appliance configuration, this response will contain the “Publish requests with non-admin token - not published” error message. | | 400 | Missing or malformed name parameter | | 401 Unauthorized | “Ruleset cannot be enabled/disabled. It is created by another user.” or “Core ruleset cannot be enabled/disabled” for Spectra Core rulesets. The first reason does not apply to administrators. | | 404 | Ruleset with that name does not exist | | 500 | Error occurred while enabling/disabling ruleset | ## Get YARA ruleset synchronization time ``` GET /api/yara/ticloud/time/ ``` Provides information about the current synchronization status for Spectra Intelligence-enabled rulesets. There are no required parameters for this endpoint. The URL must end with a forward slash (`/`). **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/yara/ticloud/time/' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the token token = "exampletoken" # Change the host name in the URL url = "https://appliance.example.com/api/yara/ticloud/time/" headers = { 'Authorization': f'Token {token}', } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` **Response Example** ```json { "code": 200, "message": "TiCloud matches are syncing from 2017-03-14T11:19:31.978544Z" "detail": { "time": "2017-03-14T11:19:31.978544Z" } } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | OK | | 403 | This response is returned when the request isn’t authenticated. | | 405 | YARA Spectra Intelligence synchronization is currently not enabled. | ## Set YARA ruleset synchronization time ``` POST /api/yara/ticloud/time/ ``` Allows modifying the Spectra Intelligence synchronization time for Spectra Intelligence-enabled YARA rulesets. The **time** parameter can be supplied either as a query string or in the JSON request payload. The time format should be UTC (YYYY-MM-DD hh:mm:ss) or Unix epoch time as the number of seconds since 1970-01-01. The URL must end with a forward slash (`/`). ### Request Format **Request Parameters** | FIELD | REQUIRED | DATA TYPE | DESCRIPTION | PARAMETER TYPE | | :---- | :------- | :-------- | :----------------------------------------------------------- | :------------- | | time | required | string | Sets the date and time for YARA Spectra Intelligence synchronization. Format should be UTC (YYYY-MM-DD hh:mm:ss) or Unix epoch time as the number of seconds since 1970-01-01 | form | The `time` parameter should be passed in the body of the request, and its content type is `application/x-www-form-urlencoded`. **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/yara/ticloud/time/' \ --header 'Authorization: Token exampletoken' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'time=999999999' ``` **Python** ```python # Change the token token = "exampletoken" # Change the host name in the URL url = "https://appliance.example.com/api/yara/ticloud/time/" payload = 'time=2020-04-20 04:20' headers = { 'Authorization': f'Token {token}', 'Content-Type': 'application/x-www-form-urlencoded' } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers, data=payload) print(response.text) ``` ### Response Format **Response Example** ``` { "code": 200, "message": "TiCloud matches are syncing from 2017-03-14T11:19:31.978544Z" "detail": { "time": "2017-08-10 11:53:24+00:00" } } ``` **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------------------------------------------- | | 200 | OK | | 404 | Malformed time parameter | | 405 | YARA Spectra Intelligence synchronization is currently not enabled. | ## Remove all Spectra Intelligence matches from a YARA ruleset ``` POST /api/yara/revisions/matches/bulk-delete/ ``` Removes all Spectra Intelligence matches from a YARA ruleset revision based on the provided filters. This endpoint can be used to clear both continuous and retro cloud matches. YARA rulesets saved to Spectra Intelligence can match up to 10 000 samples. When a ruleset reaches that limit, it is capped and new matches are no longer stored. Use this endpoint to clear old matches and resume collecting new ones. ### Request Format **Request Parameters** | FIELD | REQUIRED | DATA TYPE | DESCRIPTION | | :-------------- | :------- | :-------- | :----------------------------------------------------------- | | name | required | string | Name of the YARA ruleset for which to remove matches. Ruleset names are case-sensitive. | | rule_id | optional | integer | ID of a specific rule within the ruleset. | | query | optional | object | Additional query filters for match removal. | **Request Examples** **JSON** ```json { "name": "my-ruleset" } ``` **cURL** ```bash # Add --insecure before the URL if you are using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/yara/revisions/matches/bulk-delete/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'name=my-ruleset' ``` **Python** ```python # Change the token token = "exampletoken" # Change the host name in the URL url = "https://appliance.example.com/api/yara/revisions/matches/bulk-delete/" payload = 'name=my-ruleset' headers = { 'Authorization': f'Token {token}', 'Content-Type': 'application/x-www-form-urlencoded' } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.post(url, headers=headers, data=payload) print(response.text) ``` ### Response Format **Response Status Codes** | CODE | DESCRIPTION | | :--- | :----------------------- | | 200 | Returns the number of matches removed and the remaining threat counts. | | 400 | Validation error in request parameters. | | 403 | User is not authenticated. | | 404 | Ruleset not found. | --- ## YARA Repository Management API — Spectra Analyze ## Retrieve a list of all configured repositories ``` GET /api/yara/repositories/ ``` Retrieve a list of all configured YARA repositories, with optional filtering by page, and custom or system repositories. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | |:----------------|:---------|:-----------------------------------------------------------------------------------------------------------------------------|:---------------| | `active_filter` | Optional | Filter repositories by type. Supported values: `all`, `user` (custom repositories only), `system` (system repositories only) | query, string | | `page` | Optional | A page number within the paginated result set. | query, integer | | `page_size` | Optional | Number of results to return per page. | query, integer | **Request Examples** **cURL** ```bash # Add --insecure before the URL if using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/yara/repositories/' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python token = "exampletoken" url = "https://appliance.example.com/api/yara/repositories/" headers = { "Authorization": f"Token {token}" } # Add verify=False for self-signed SSL certificates response = requests.get(url, headers=headers) print(response.json()) ``` ### Response Format **Response Example** ```json { "count": 123, "next": "http://api.example.org/api/yara/repositories/?page=4", "previous": "http://api.example.org/api/yara/repositories/?page=2", "results": [ { "id": 0, "url": "string", "name": "string", "source_branch": "string", "source_type": 0, "api_token": "string", // Not returned in plain text. Empty string if unset, '********' if set. "import_update_preferences": 0, "is_custom": true, "last_modified": "2025-07-04T12:22:33.472Z", "user": 0 } ] } ``` **Response Status Codes** | CODE | DESCRIPTION | |:-----|:------------| | 200 | | ## Create a new repository ``` POST yara/repositories/ ``` Create a new YARA repository for fetching and managing YARA rules. The system will verify connectivity to the provided repository before creation. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | |:----------------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------|:---------------| | `url` | Required | URL pointing to the remote ruleset repository. | query, string | | `name` | Required | Display name for the repository. | query, string | | `source_branch` | Optional | Git branch to pull rulesets from. Defaults to `main` or `master` if omitted. | query, string | | `api_token` | Optional | Token used to authenticate to private remote repositories. | query, string | | `import_update_preferences` | Optional | Integer enum representing importing update preferences. Supported values: `0` - Manual, `1` - Auto-Update, `2` - Auto-Update and Auto-Import. | query, integer | **Request Examples** **cURL** ```bash curl -X POST 'https://appliance.example.com/api/yara/repositories/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{ "url": "string", "name": "string", "source_branch": "string", "api_token": "string", "import_update_preferences": 0 }' ``` **Python** ```python token = "exampletoken" url = "https://appliance.example.com/api/yara/repositories/" data = { "url": "string", "name": "string", "source_branch": "string", "api_token": "string", "import_update_preferences": 0 } headers = { "Authorization": f"Token {token}", "Content-Type": "application/json" } response = requests.post(url, headers=headers, json=data) print(response.json()) ``` ### Response Format **Response Example** ```json { "message": "string" } ``` **Response Status Codes** | CODE | DESCRIPTION | |:-----|:-----------------------| | 201 | | | 400 | Validation error | | 404 | Connection test failed | ## Update existing repository ``` PUT /api/yara/repositories/{repository_id} ``` Update the configuration of an existing YARA repository. The system will verify connectivity to the provided repository before updating. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | |:----------------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------|:---------------| | `repository_id` | Required | The ID of the repository to update. | path, integer | | `url` | Required | URL pointing to the remote ruleset repository. | query, string | | `name` | Required | Display name for the repository. | query, string | | `source_branch` | Optional | Git branch to pull rulesets from. Defaults to `main` or `master` if omitted. | query, string | | `api_token` | Optional | Token used to authenticate to private remote repositories. | query, string | | `import_update_preferences` | Optional | Integer enum representing importing update preferences. Supported values: `0` - Manual, `1` - Auto-Update, `2` - Auto-Update and Auto-Import. | query, integer | **Request Examples** **cURL** ```bash curl -X PUT 'https://appliance.example.com/api/yara/repositories/' \ --header 'Authorization: Token exampletoken' \ --header 'Content-Type: application/json' \ --data '{ "url": "string", "name": "string", "source_branch": "string", "api_token": "string", "import_update_preferences": 0 }' ``` **Python** ```python token = "exampletoken" url = "https://appliance.example.com/api/yara/repositories/" data = { "url": "string", "name": "string", "source_branch": "string", "api_token": "string", "import_update_preferences": 0 } headers = { "Authorization": f"Token {token}", "Content-Type": "application/json" } response = requests.put(url, headers=headers, json=data) print(response.json()) ``` ### Response Format **Response Example** ```json { "message": "string" } ``` **Response Status Codes** | CODE | DESCRIPTION | |:-----|:--------------------------------| | 200 | Repository updated successfully | | 400 | Validation error | | 404 | Connection test failed | ## Delete existing repository ``` DELETE /api/yara/repositories/{repository_id} ``` Delete a configured YARA repository by ID. Only custom repositories can be deleted, and only by their owner or a superuser. Associated rulesets with the repository can optionally be removed. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | |:-----------------------|:---------|:----------------------------------------------------------------------------|:---------------| | `repository_id` | Required | The ID of the repository to delete. | query, integer | | `shouldRemoveRulesets` | Optional | Remove all rulesets associated with the repository. Default value: `false`. | query, boolean | **Request Examples** **cURL** ```bash # Add --insecure before the URL if using a self-signed SSL certificate curl -X DELETE 'https://appliance.example.com/api/yara/repositories/1' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python token = "exampletoken" url = "https://appliance.example.com/api/yara/repositories/1" headers = { "Authorization": f"Token {token}" } # Add verify=False for self-signed SSL certificates response = requests.delete(url, headers=headers) print(response.status_code) ``` ### Response Format **Response Example** ```json { "message": "string" } ``` **Response Status Codes** | CODE | DESCRIPTION | |:-----|:---------------------------------------| | 200 | Repository deleted successfully | | 400 | Permission denied or system repository | | 404 | Repository not found | ## Configure update job cadence ``` POST /api/yara/update/set-interval/{value} ``` Configure the interval (in seconds) at which the YARA update job runs automatically. Set the value in seconds. Setting the value to `0` disables automatic updates. **Note: Sending a request to this endpoint introduces a short maintenance downtime.** ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | |:-------------------|:---------|:---------------------------------------------------------------------------|:---------------| | `value_in_seconds` | Required | Interval in seconds between automatic update job runs. Use `0` to disable. | path, integer | **Request Examples** **cURL** ```bash # Add --insecure before the URL if using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/yara/update/set-interval/3600' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python token = "exampletoken" url = "https://appliance.example.com/api/yara/update/set-interval/3600" headers = { "Authorization": f"Token {token}" } # Add verify=False for self-signed SSL certificates response = requests.post(url, headers=headers) print(response.status_code) ``` ### Response Format **Response Example** ```json { "message": "Job cadence configured to 3600!" } ``` **Response Status Codes** | CODE | DESCRIPTION | |:-----|:------------------------------------| | 200 | Job cadence configured successfully | | 403 | Permission denied | ## Reset update job cadence ``` POST /api/yara/update/reset-interval ``` Reset the update interval for repositories to the default value of `3600` seconds (1 hour). **Note: Sending a request to this endpoint introduces a short maintenance downtime.** ### Request Format **Request Examples** **cURL** ```bash # Add --insecure before the URL if using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/yara/update/reset-interval' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python token = "exampletoken" url = "https://appliance.example.com/api/yara/update/reset-interval" headers = { "Authorization": f"Token {token}" } # Add verify=False for self-signed SSL certificates response = requests.post(url, headers=headers) print(response.status_code) ``` ### Response Format **Response Example** ```json { "message": "Job cadence configured to 3600!" } ``` **Response Status Codes** | CODE | DESCRIPTION | |:-----|:-------------------------------| | 200 | Job cadence reset successfully | | 403 | Permission denied | ## Run update job on demand ``` POST /api/yara/update/run ``` Manually trigger YARA update job execution. If an update job is currently running, the API request will fail with a conflict status code. ### Request Format **Request Examples** **cURL** ```bash # Add --insecure before the URL if using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/yara/update/run' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python token = "exampletoken" url = "https://appliance.example.com/api/yara/update/run" headers = { "Authorization": f"Token {token}" } # Add verify=False for self-signed SSL certificates response = requests.post(url, headers=headers) print(response.status_code) ``` ### Response Format **Response Example** ```json { "message": "Job running!" } ``` **Response Status Codes** | CODE | DESCRIPTION | |:-----|:-------------------------| | 200 | Job started successfully | | 403 | Permission denied | | 409 | Job is already running | ## Publish rulesets ``` POST /api/yara/publish/all ``` Trigger a publishing process for all available non-system YARA rulesets in the appliance. Publishing process makes the latest revisions of YARA rulesets active and available for further use. This is a separate step from [creating or updating a ruleset](./yara-api.md#create-or-update-a-yara-ruleset). When you create or update a ruleset, the change is saved as a new revision, but it is not automatically published. Rulesets must be explicitly published to apply changes system-wide. If YARA synchronization is enabled, publishing also propagates the updated rulesets to other appliances in the cluster. See [Synchronizing YARA Rulesets with Other Appliances](../yara.md#synchronizing-yara-rulesets-with-other-appliances) for more information. ### Request Format **Request Examples** **cURL** ```bash # Add --insecure before the URL if using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/yara/publish/all' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python token = "exampletoken" url = "https://appliance.example.com/api/yara/publish/all" headers = { "Authorization": f"Token {token}" } # Add verify=False for self-signed SSL certificates response = requests.post(url, headers=headers) print(response.status_code) ``` ### Response Format **Response Example** ```json { "error_messages": [ { "revision_id": 0, "ruleset_name": "string", "message": "string" } ], "successful_publish_count": 0, "total_count": 0 } ``` **Response Status Codes** | CODE | DESCRIPTION | |:-----|:--------------------------------------------------------------------------| | 200 | The publish process has completed. Check error_messages for any failures. | | 403 | User is not authorized or Yara Sync is not enabled | ## Publish a ruleset ``` POST /api/yara/publish/{ruleset_name} ``` Trigger a publishing process for a single, non-system YARA ruleset in the appliance. ### Request Format **Request Parameters** | NAME | REQUIRED | DESCRIPTION | TYPE | |:---------------|:---------|:--------------------------------|:-------------| | `ruleset_name` | Required | Name of the ruleset to publish. | path, string | **Request Examples** **cURL** ```bash # Add --insecure before the URL if using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/yara/publish/my_ruleset' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python token = "exampletoken" ruleset_name = "my_ruleset" url = f"https://appliance.example.com/api/yara/publish/{ruleset_name}" headers = { "Authorization": f"Token {token}" } # Add verify=False for self-signed SSL certificates response = requests.post(url, headers=headers) print(response.status_code) ``` ### Response Format **Response Example** ```json { "message": "Publishing my_ruleset ruleset!" } ``` **Response Status Codes** | CODE | DESCRIPTION | |:-----|:----------------------------------------------------------------| | 200 | The publish process has been initiated successfully. | | 400 | The publish process has failed. Check message for more details. | | 403 | User is not authorized or Yara Sync is not enabled | --- ## YARA Retro API — Spectra Analyze ## Start/Stop a YARA Local Retro scan ``` POST /api/uploads/local-retro-hunt/ ``` Allows users to initiate the Local Retro scan on the Spectra Analyze appliance, and stop the Local Retro scan that is in progress on the appliance. ### Request Format **Request Parameters** | FIELD | REQUIRED | DATA TYPE | DESCRIPTION | PARAMETER TYPE | | :-------- | :------- | :-------- | :----------------------------------------------------------- | :------------- | | operation | required | string | Name of the operation to perform for YARA Local Retro scan. Supported operations are starting and stopping a Local Retro scan. Accepted values: `START`, `STOP` (case-sensitive). Only one value can be submitted at a time. | form-data | **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/uploads/local-retro-hunt/' \ --header 'Authorization: Token exampletoken' --form 'operation="START"' ``` **Python** ```python # Change the token token = "exampletoken" # Change the host name in the URL url = "https://appliance.example.com/api/uploads/local-retro-hunt/" payload = {'operation': 'START'} headers = { 'Authorization': f'Token {token}', 'Content-Type': 'multipart/form-data' } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers, data=payload) print(response.text) ``` ### Response Format **Response Examples** ```json { "status": { "state": "STARTING", }, "message": null, "success": true } { "status": { "state": "STOPPED", }, "message": null, "success": true } ``` **Response Status Codes** | CODE | NAME | DESCRIPTION | | :--- | :-------------------- | :----------------------------------------------------------- | | 200 | OK | The request has succeeded | | 400 | Bad Request | The request could not be understood by the server due to malformed syntax | | 403 | Forbidden | The request requires user authentication | | 404 | Not Found | The ruleset cannot be found | | 412 | Precondition Failed | The ruleset is not saved to Spectra Intelligence, or is in the wrong state for this operation | | 424 | Failed Dependency | An underlying call caused an error | | 428 | Precondition Required | The server is not connected to Spectra Intelligence, or Cloud Retro hunting is not enabled | | 500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request | | 503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server | ## Manage YARA Cloud Retro scans ``` POST /api/yara/ruleset/{ruleset_name}/cloud-retro-hunt/ ``` Allows users to start and stop a Cloud Retro scan for a specified ruleset on the Spectra Analyze appliance, as well as to clear all Cloud Retro results for the ruleset. The ruleset must be enabled and saved in the Spectra Intelligence cloud in order to successfully start a Cloud Retro scan. ### Request Format **Request Parameters** | FIELD | REQUIRED | DATA TYPE | DESCRIPTION | PARAMETER TYPE | | :----------- | :------- | :-------- | :----------------------------------------------------------- | :------------- | | operation | required | string | Name of the operation to perform for YARA Cloud Retro scan. Supported operations are starting and stopping a Cloud Retro scan, and clearing the results of a previous Cloud Retro scan. Accepted values: START, STOP, CLEAR. Only one value can be submitted at a time. | form | | ruleset_name | required | string | Name of the YARA ruleset that the Cloud Retro scan should be run on. The ruleset must exist on the appliance, and be enabled and saved in the Spectra Intelligence cloud. Ruleset names are case-sensitive. | path | **Request Examples** **cURL** ``` # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X POST 'https://appliance.example.com/api/yara/ruleset/example_ruleset/cloud-retro-hunt/' \ --header 'Authorization: Token exampletoken' --form 'operation="START"' ``` **Python** ```python # Change the token token = "exampletoken" # Change the host name and the name of the ruleset url = "https://appliance.example.com/api/yara/ruleset/example_ruleset/cloud-retro-hunt/" payload = {'operation': 'START'} headers = { 'Authorization': f'Token {token}', 'Content-Type': 'multipart/form-data' } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers, data=payload) print(response.text) ``` ### Response Format **Response Examples** Starting a Cloud Retro scan ```json { "status": { "state": "RUNNING", }, "message": null, "success": true } ``` Stopping a Cloud Retro scan ```json { "status": { "state": "CANCELLED", }, "message": null, "success": true } ``` Clearing all Cloud Retro results for a ruleset ```json { "status": { "state": "CLEARED", }, "message": null, "success": true } ``` **Response Status Codes** | CODE | NAME | DESCRIPTION | | :--- | :-------------------- | :----------------------------------------------------------- | | 200 | OK | The request has succeeded | | 400 | Bad Request | The request could not be understood by the server due to malformed syntax | | 403 | Forbidden | The request requires user authentication | | 404 | Not Found | The ruleset cannot be found | | 412 | Precondition Failed | The ruleset is not saved to Spectra Intelligence, or is in the wrong state for this operation | | 424 | Failed Dependency | An underlying call caused an error | | 428 | Precondition Required | The server is not connected to Spectra Intelligence, or Cloud Retro hunting is not enabled | | 500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request | | 503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server | ## Check YARA Retro status on the appliance ### YARA Local Retro status ``` GET /api/uploads/local-retro-hunt/ ``` Allows users to check the status of Local Retro on the Spectra Analyze appliance. The response indicates the current state of Local Retro, time and date when the latest Local Retro scan was started and/or stopped, and a list of previous Local Retro scans with the same details. There are no required parameters for this endpoint. **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/uploads/local-retro-hunt/' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the token token = "exampletoken" # Change the host name in the URL url = "https://appliance.example.com/api/uploads/local-retro-hunt/" headers = { 'Authorization': f'Token {token}', } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` **Response Example** ```json { "status": { "started": "2019-05-13T16:02:35.209613+00:00", "state": "COMPLETED", "stopped": "2019-05-13T16:39:34.468029+00:00", "processed": 3197, "samples": 3197, "history": [ { "started_username": "test", "started": "2019-05-13T16:02:35.209613+00:00", "stopped_username": null, "state": "COMPLETED", "stopped": "2019-05-13T16:39:34.468029+00:00", "samples": 3197 }, { "started_username": "test", "started": "2019-05-13T15:46:05.917547+00:00", "stopped_username": "test2", "state": "STOPPED", "stopped": "2019-05-13T16:02:27.349033+00:00", "samples": 3197 }, ] }, "message": null, "success": true } ``` **Response Fields** | NAME | DESCRIPTION | | :--------------- | :----------------------------------------------------------- | | success | Indicates whether the operation was successful. Returns *true* or *false*. | | message | Contains a success message, or reason the operation was not successful. | | status | Indicates the Local Retro scan status, or returns null if Local Retro has never been run on the appliance. | | history | Contains detailed *status* entries for previous Local Retro scans on the appliance, if there have been any. | | state | The state of the Local Retro scan process. Returns one of the following values: RUNNING, COMPLETED, STOPPED, STARTING | | started | Date and time when the Local Retro scan was started. | | stopped | Date and time when the Local Retro scan was completed or stopped. | | started_username | Username associated with the Spectra Analyze account that started the Local Retro scan. | | stopped_username | Username associated with the Spectra Analyze account that stopped the Local Retro scan. Returns *null* if the scan completed on its own (if it has not been stopped by any user). | | samples | The total number of samples included in the Local Retro scan. | | processed | The number of samples that have already been processed by the Local Retro scan. | **Response Status Codes** | CODE | NAME | DESCRIPTION | | :--- | :-------------------- | :----------------------------------------------------------- | | 200 | OK | The request has succeeded | | 400 | Bad Request | The request could not be understood by the server due to malformed syntax | | 403 | Forbidden | The request requires user authentication | | 404 | Not Found | The ruleset cannot be found | | 412 | Precondition Failed | The ruleset is not saved to Spectra Intelligence, or is in the wrong state for this operation | | 424 | Failed Dependency | An underlying call caused an error | | 428 | Precondition Required | The server is not connected to Spectra Intelligence, or Cloud Retro hunting is not enabled | | 500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request | | 503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server | ### YARA Cloud Retro status ``` GET /api/yara/ruleset/{ruleset_name}/cloud-retro-hunt/ ``` Allows users to check the status of Cloud Retro for the specified YARA ruleset. The response indicates the current state of Cloud Retro, time and date when the latest Cloud Retro scan was started and/or stopped, and a list of previous Cloud Retro scans with the same details. The `ruleset_name` is a required parameter. The specified ruleset must be present on the appliance. Ruleset names are case-sensitive. **Request Examples** **cURL** ```bash # Add --insecure before the URL if you're using a self-signed SSL certificate curl -X GET 'https://appliance.example.com/api/yara/ruleset/example_ruleset/cloud-retro-hunt/' \ --header 'Authorization: Token exampletoken' ``` **Python** ```python # Change the token token = "exampletoken" # Change the host name and the name of the ruleset url = "https://appliance.example.com/api/yara/ruleset/example_ruleset/cloud-retro-hunt/" headers = { 'Authorization': f'Token {token}', } # Add verify=False in the request if you are using a self-signed SSL certificate response = requests.get(url, headers=headers) print(response.text) ``` **Response Example** ```json { "status": { "cloud_status": "ACTIVE", "scale_status": "DISABLED", "retrohunt_status": "CLEARED", "retrohunt_start_time": "2019-05-13T16:02:35.209613+00:00", "retrohunt_finish_time": "2019-05-13T16:39:34.468029+00:00", "retrohunt_estimated_finish_time": null, "retrohunt_progress": null, "reason": null }, "message": null, "ruleset_name": testruleset, "success": true } ``` **Response Fields** | NAME | DESCRIPTION | | :------------------------------ | :----------------------------------------------------------- | | success | Indicates whether the operation was successful. Returns *true* or *false*. | | message | Contains a success message, or reason the operation was not successful. | | ruleset_name | Name of the YARA ruleset for which the status information is retrieved. | | cloud_status | The status of the YARA ruleset for Spectra Intelligence operations. Can be one of the following values: ERROR, ACTIVE, DISABLED, DELETED, PENDING, INVALID, CAPPED | | scale_status | The status of the YARA ruleset for local (Spectra Detect operations). Can be one of the following values: ERROR, ACTIVE, DISABLED, DELETED, PENDING, INVALID, CAPPED | | retrohunt_status | The status of the ruleset for Cloud Retro scans. Can be one of the following values: IDLE, VALIDATING, ERROR, READY, RUNNING, COMPLETE, CANCELLED, CLEARED | | retrohunt_start_time | The starting time for running or complete Cloud Retro scans. | | retrohunt_finish_time | The finishing time for a completed Cloud Retro scan. | | retrohunt_estimated_finish_time | The estimated time for completing the Cloud Retro scans in progress. | | retrohunt_progress | Number in the range of 0 to 1 indicating the completeness of the Cloud Retro scan in progress, where 1 indicates that it is fully completed. | | reason | If the ruleset is in an error state, this field returns a short explanation. | **Response Status Codes** | CODE | NAME | DESCRIPTION | | :--- | :-------------------- | :----------------------------------------------------------- | | 200 | OK | The request has succeeded | | 400 | Bad Request | The request could not be understood by the server due to malformed syntax | | 403 | Forbidden | The request requires user authentication | | 404 | Not Found | The ruleset cannot be found | | 412 | Precondition Failed | The ruleset is not saved to Spectra Intelligence, or is in the wrong state for this operation | | 424 | Failed Dependency | An underlying call caused an error | | 428 | Precondition Required | The server is not connected to Spectra Intelligence, or Cloud Retro hunting is not enabled | | 500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request | | 503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server | --- ## Open source packages and licenses --- ## Self-Service Registration This guide describes how to set up self-service registration for Spectra Analyze using Okta as the identity provider. It can be set up with SAML or OIDC integration. ## Setting up Okta with Spectra Analyze In the Okta Administration interface, navigate to **Applications > Applications** and click **Create App Integration**. Set up either OIDC or SAML integration. ### SAML 1. Enter the required username and password attribute statements. **Info: Group attributes are only necessary if the groups functionality is intended to be used.** ![Attribute settings](../images/analyze-self-service-attribute-settings.png) 2. When the integration is configured, navigate to the **Assignments** tab and assign at least one group to the application. 3. Navigate to the **Sign On** tab and download the metadata. ![Okta Sign On tab with metadata download option](../images/analyze-sign-on.png) 4. Set up the SAML configuration in Spectra Analyze with matching claims and upload the metadata. **Info: Make sure to select the `Allow unsolicited responses from IdP` checkbox.** ![Spectra Analyze SAML configuration with claim matching settings](../images/analyze-self-service-saml-configuration.png) ## Enabling Sign Up 1. In **Security > Profile Enrollment**, create a new **Profile Enrollment Policy**. 2. Set the **Self-service registration** to `Allowed`, and select the **Email verification** checkbox. ![Profile Enrollment Policy configuration with self-service registration option](../images/analyze-self-service-profile-enrollment.png) 3. Navigate to **Manage apps** and add your application to the created policy. 4. In **Security > Authenticators**, edit the **Email authenticator**, and enable it to be used for both authentication and recovery. ![Email authenticator settings for authentication and recovery](../images/analyze-self-service-email.png) 5. In the **Enrollment** tab, add a new policy for the same group that was assigned to the application, and set the **Email** authenticator to at least `Optional`. ![Email authenticator enrollment policy configuration](../images/analyze-self-service-edit-policy.png) 6. In **Security > Authentication Policies**, click **Add a policy**. 7. Add your application to this policy, and edit the **Catch-all Rule** by setting it to deny access. 8. Add a new rule, and configure it so that the access is allowed, and the user must authenticate using Password / IdP + another factor. 9. For the **Possestion factor constraints**, set `Require user interaction`. 10. Set up the Authentication methods according to your requirements, and set it to allow at least password and email. **Frequency of password** and other factors of authentication can be configured at the bottom. ![Conditions](../images/analyze-self-service-conditions.png) **Note: To add additional conditions, such as limiting the eligible emails for sign up to a certain domain, add a custom expression in the **IF** section, such as `user.profile.email.substringAfter('@') == 'reversinglabs.com'`.** Any failed attempts will create inactive user accounts in Okta's directory. An alternative involves [inline hooks](https://help.okta.com/oie/en-us/content/topics/automation-hooks/inline-hooks-main.htm?cshid=csh-inlinehooks), making the web service require additional filtering capabilities. This approach should not result in inactive user accounts. ![Edit Rule](../images/analyze-self-service-edit-rule.png) ## Customizing the Sign Up Screen 1. In **Customizations > Other**, you can change the error message for failed sign-up attempts, and other error messages. ![Error Messages](../images/analyze-self-service-error-message.png) 2. In **Customizations > Brands**, you can configure the appearance of the screens, including the sign in screens and emails sent by Okta. The sign up form inputs are configured in **Security > Profile Enrollment** by selecting the policy used for the application. ![Profile Enrollment Form](../images/analyze-self-service-profile-enrollment-form.png) ## Allowing Sign Up with other Identity Providers In **Security > Identity Providers**, you can add a number of identity providers, including Microsoft IdP, Google IdP, and others. They can be assigned to certain applications through the **Routing rules** tab. ## User Management User management can be done by using both fetch and delete methods through the API. To use the API, you need to generate an API token. 1. In **Security > API**, navigate to the Token tab to generate a new token. ### Fetching Users Fetching all users assigned to the created application can be done via the `/api/v1/apps/:appId/users` endpoint. ``` GET /api/v1/apps/:appId/users ``` Path parameter: - `appId` - The ID of the application. - Required Query parameter: - `expand=user` - Find user accounts that did not fit the criteria for the sign up, but were still created and are inactive. - Optional #### Example An example of a request to fetch all user IDs, their usernames, and statuses of the users assigned to the application. ``` curl "https://${OKTA_INSTANCE_URL}/api/v1/apps/${APP_ID}/users?expand=user" \ --header 'Authorization: SSWS ${TOKEN_VALUE}' \ --header 'Accept: application/json' | jq '.[] | [.id, .credentials.userName, ._embedded.user.status]' ``` Once the results are fetched, the `STAGED` status indicates that the user account was created, but the user has not yet activated it because they did not match the criteria for the sign up. You can take the IDs of these users and delete them. ### Deleting Users Deleting users assigned to the created application can be done via the `/api/v1/users/:userId` endpoint. ``` DELETE /api/v1/users/:userId ``` Path parameter: - `userId` - The ID of the user to be deleted. - Required Query parameter: - `sendEmail` - If set to `true`, an email will be sent to the user notifying them of the deletion. - Optional #### Example An example of a request to delete a user with the `STAGED` status. ``` curl -X DELETE "https://${OKTA_INSTANCE_URL}/api/v1/users/${USER_ID}?sendEmail=false" \ --header 'Authorization: SSWS ${TOKEN_VALUE}' \ --header 'Accept: application/json' ``` **Info: You will need to execute the request twice because the first request deprovisions the account, while the second request deletes it.** --- ## ReversingLabs Auxiliary Analysis ## Overview **ReversingLabs Auxiliary Analysis** is a static analysis service that provides deeper inspection and enrichment for samples processed by Spectra Analyze. When enabled, it runs additional specialized analysis services and returns detailed results that appear on the **Sample Details** page under **Auxiliary Analysis**. Auxiliary Analysis is configured centrally and can be enabled as part of first-party integrations. ## Configuration For more information about configuring this integration, see [Integrations - Static analysis](../Administration/integrations-connectors/integrations.md#static-analysis). ## Auxiliary analysis reports | Maximum supported file size | Submitting only distinct files | | ------------------------------ | ------------------------------ | | 100 MiB | Not supported | When ReversingLabs Auxiliary Analysis finishes processing a sample, a report with the analysis results is sent to the Spectra Analyze appliance. This report can be accessed from the [Sample Details page](../Sample%20Details/index.md) under **Auxiliary Analysis**. The report for this integration includes detailed inspection data, such as: - **General sample information**: basic metadata and file identification. - **Detected heuristics**: specialized static analysis heuristics that identify suspicious patterns and behaviors. - **ATT&CK information**: mapping of detected behaviors to the MITRE ATT&CK framework. - **Extracted files**: list of files extracted during the analysis process, each with its own threat score. - **IOCs**: indicators of compromise discovered during the static inspection. - **Threat score**: a numerical value representing the overall risk of the sample. The threat score of each file, including the sample and all extracted files, indicates its severity and helps interpret the classification. | Score | Classification interpretation | |-----------|-------------------------------| | - 1000 | Clean | | 0 - 299 | Informational | | 300 - 699 | Suspicious | | 700 - 999 | Highly suspicious | | >= 1000 | Malicious | ## Auxiliary analysis services Auxiliary Analysis combines multiple specialized services, each focused on a particular file type or analysis technique: | Service name | Speciality | |:---------------------|:-------------------| | APKaye | Android APK | | Ancestry | File genealogy | | Batchdeobfuscator | Deobfuscation | | CAPA | Windows binaries | | Characterize | Entropy analysis | | ConfigExtractor | IoC extraction | | DeobfuScripter | Deobfuscation | | DocumentPreview | Visualization | | EmlParser | Email | | Espresso | Java | | Extract | Compressed file | | Floss | IoC extraction | | FrankenStrings | String extraction | | JsJaws | Javascript | | MetaPeek | Meta data analysis | | Oletools | Office documents | | Overpower | PowerShell | | PDFId | PDF | | PE | Windows binaries | | PeePDF | PDF | | PixAxe | Images | | Swiffer | Adobe Shockwave | | TorrentSlicer | Torrent files | | Unpacker | UPX Unpacker | | ViperMonkey | Office documents | | XLMMacroDeobfuscator | Office documents | --- ## ReversingLabs Cloud Sandbox ## Overview **ReversingLabs Cloud Sandbox** executes files in isolated sandbox environments to observe runtime behavior, complementing static analysis for comprehensive threat detection. For more information about how dynamic and static analysis work together, see [Static vs. Dynamic Analysis](/General/AnalysisAndClassification/static-vs-dynamic-analysis/). The Cloud Sandbox supports the following analysis modes: - **Automatic analysis** — the sample is detonated automatically and the results are collected without user interaction. - **[Interactive analysis](#interactive-analysis)** — the sample is executed in a live session where the analyst can manually interact with it in real time. This is useful for malware that requires user interaction, such as clicking through installer menus or entering passwords. Samples can be analyzed on the following platforms: **Windows**, **macOS**, and **Linux**. The sandbox automatically selects the most appropriate platform based on the detected file type, but users can also choose a specific platform when submitting a sample. See [Analysis profiles](#analysis-profiles) for more details. Each completed analysis produces a behavior report that includes network indicators, behavioral indicators, process activity, registry and file system changes, and downloadable artifacts. If the service is enabled, historic dynamic analysis results are shown for all samples that have them. Detected indicators of compromise are available through [Advanced Search](../advanced-search.md) using the `uri-dynamic` and `ipv4-dynamic` keywords, as well as through sections on the [Sample Details Summary](../Sample%20Details/sample-details-summary.md) page. Files can also be submitted directly to the ReversingLabs Cloud Sandbox via the [Dynamic Analysis Submission API](/SpectraIntelligence/API/DynamicAnalysis/tca-0207/). **Warning: Prerequisites** For this service to be available, the appliance has to be connected to [Spectra Intelligence](../Administration/configuration-update/configuration.md#spectra-intelligence). For more information about configuring this integration, see [ReversingLabs Cloud Sandbox](../Administration/integrations-connectors/integrations.md#reversinglabs-cloud-sandbox). ## Dynamic analysis reports Full report details consist of: - **General file details**: file name, size, type, and hashing information (MD5, SHA1, SHA256). - **Network indicators**: detailed list of URLs, domains, and IP addresses contacted by the sample during detonation. - **Behavioral indicators**: chronological list of actions taken by the sample, categorized by severity and severity level. - **Process activity**: process creation tree and details about each process run during the analysis. - **Registry and file activity**: comprehensive log of registry changes and file system modifications. - **Screenshot gallery**: click the thumbnail on the right to open a gallery of all collected screenshots, with the option to automatically advance through them in a slideshow. At the top of the gallery dialog, users can switch between different analyses to see the related screenshots. - **History of dynamic analysis results**: table with the option to download dropped files and other artifacts for every individual analysis. These files are available for download for 1 year. If the analyzed sample is an email, this table also contains expandable sections with analysis reports for attachments and URLs found within the analyzed email sample. - **Additional information**: available in a tabbed section with specific information obtained in dynamic analysis. This section can be filtered to show information from all performed analyses, or from a specific analysis. See [ReversingLabs Cloud Sandbox API](/SpectraIntelligence/API/DynamicAnalysis) for a detailed explanation of individual fields. After a dynamic analysis run is completed, the following artifacts are available for download: - **Screenshots** - **PCAP file** - **Memstrings** - **Dropped files** The artifacts depend on each dynamic analysis run and can be downloaded from the **History of Dynamic Analysis Results** table, while the dropped files are available for download in the **Dropped Files** tab. These files are available for download for 1 year, the standard retention period for the Cloud Sandbox. The artifacts are downloaded as `.7zip` archives and their password is ***infected***. Downloading artifacts is possible only through the GUI. On the report page, you can also click the buttons in the top right corner to do the following: - **Reanalyze**: reanalyze the sample using the ReversingLabs Cloud Sandbox. - **Actions**: - **Create PDF/HTML**: download the report as HTML or PDF. When a PDF or HTML report is created, a new one cannot be created before 30 minutes have expired. Downloading HTML or PDF reports for dynamic analysis is also possible via API. If a new report export is necessary before the 30 minute period expires, use the [Dynamic Analysis Report API](../API%20Documentation/dynamic-analysis-api.md). - **Download Latest Dropped Files**: download the latest dropped files. - **Send Latest Dropped Files to Static Analysis**: send the latest dropped files to static analysis. ## Android analysis reports When the analyzed sample is an Android application, the report tabs are adjusted to show Android-specific information. The following tabs are available for Android samples: - **APK**: static analysis data extracted from the APK, including the application icon, label, minimum and target SDK versions, package name, permissions, activities, services, receivers, and certificate details. - **Android Behavior**: behavioral data collected during dynamic analysis, including started services, registered receivers with their intents, and requested permissions with their execution status. The **Malware Config** tab is not available for Android samples, as it is not supported on the Android analysis platform. ## Analysis options | Option | Description | |--------|-------------| | **Platform** | Determines the platform the sample is executed on. Available as a per-analysis setting during file submission, and default settings per file type can be configured under [Administration > Integrations & Connectors > Integrations](../Administration/integrations-connectors/integrations.md). | | **Timeout** | How long in seconds a sample can run in the sandbox virtual machine. Default: `200`, Min: `30`, Max: `500`. ReversingLabs Cloud Sandbox may allow the VM to run longer if additional runtime could extract more intelligence. The **timeout** value may differ from the total analysis time which is reported as **duration**, and which includes sample execution including any extra time granted by RLCS, VM restore, client setup, and post-processing, for example, sending dropped files to the host. | | **Custom filename** | A custom filename that helps track the file across ReversingLabs services. If omitted, the system applies smart sample naming automatically. | | **Internet simulation** | Defaults to `false`. If set to `true`, dynamic analysis is performed without connecting to the internet and uses a simulated network instead. Setting to `false` is the same as omitting it from the request. HTTPS traffic information is not monitored when using this parameter. | | **Network traffic obfuscation** | When internet simulation is disabled/omitted and samples are allowed to connect to the internet, network traffic obfuscation measures are implemented to protect the analysis infrastructure. Traffic obfuscation is achieved through VPN routing that masks the origin of network requests, preventing external entities from identifying the analysis environment. | | **Geolocation** | Geographic location associated with the sample's network activity, reflecting the configured country from which the network traffic is egressed, set via VPN or similar routing methods. | | **Interactive analysis** | Execute the sample and interact with it in an interactive session. Only available through **Analyze/Reanalyze** dialogs. If selected, a new tab opens with the interactive session. Once the session expires or is stopped by the user, its results are visible under [Dynamic Analysis > Cloud Sandbox](../Sample%20Details/dynamic-analysis-results.md). | ## Interactive analysis ![Interactive dynamic analysis session](../images/analyze-dynamic-interactive.png) **ReversingLabs Interactive Analysis** allows analysts to execute a sample and manually interact with it within an isolated virtual environment. This is particularly useful for dealing with malware that requires user interaction, such as clicking through installer menus or entering passwords, or for observing real-time behavior. **Important: Windows Support** At this time, Interactive Analysis is supported only for **Windows** platforms. ### Interactive file analysis Interactive sessions for files allow users to observe the detonation process in real-time. Analysts can: - Manually trigger malicious payloads. - Navigate through evasion-check delays. - Observe file system and registry modifications as they happen. ### Interactive URL analysis Interactive sessions for URLs provide a way to safely browse to a suspicious link and observe the results. This includes: - Following redirections to final landing pages. - Interacting with phishing forms to observe downstream behavior. - Identifying drive-by-download attempts and subsequent file execution. ## Analysis profiles The Cloud Sandbox detonates samples in controlled virtual environments to capture behavior across different operating systems. Supported platforms include: - **Windows**: modern Windows versions including **Windows 10 x64** and **Windows 11 (22H2)** are standard for dynamic detonation. - **Linux**: general-purpose Linux environments for analyzing ELF binaries and scripts. - **macOS**: specific macOS versions (including **macOS 11 Big Sur**) for inspecting Darwin-based threats. The sandbox automatically selects the most appropriate profile based on the detected file type, ensuring the sample is executed in its native runtime environment. ## Configuration settings For more information about configuring this integration, see [ReversingLabs Cloud Sandbox](../Administration/integrations-connectors/integrations.md#reversinglabs-cloud-sandbox). By default, Spectra Analyze automatically retrieves existing ReversingLabs Cloud Sandbox reports for files submitted to the appliance. If a file wasn't previously scanned in the ReversingLabs Cloud Sandbox, it can be manually uploaded for dynamic analysis, or you can enable [Automatic upload](../Administration/integrations-connectors/integrations.md#integrations) to do this automatically. **Important: While the retrieval of existing reports is a basic Spectra Analyze feature, submitting files for dynamic analysis using the ReversingLabs Cloud Sandbox is available only as a feature preview with an upload limit of five samples per day. When the analysis quota is exceeded, the appliance shows a warning message whenever a new file is manually submitted for analysis. ** Full access to this feature is available at additional cost. For more information, contact [ReversingLabs Sales Support](mailto:insidesales@reversinglabs.com). If the [Automatic file retrieval](../Administration/integrations-connectors/integrations.md#integrations) option is enabled, all files dropped during dynamic analysis that are within configured file size limits are downloaded to the appliance and analyzed locally. To allow dynamic analysis results to affect the final sample classification, enable the [Include in classification](../Administration/integrations-connectors/integrations.md#integrations) option. When enabled, all future sample uploads, as well as any reanalyzed samples, may receive their final classification from the ReversingLabs Cloud Sandbox. Samples that already had a recent dynamic analysis classification before the option was enabled update their classification once their [Sample Details Summary](../Sample%20Details/sample-details-summary.md) page is opened, or during regular appliance synchronizations with Spectra Intelligence. Only ReversingLabs Cloud Sandbox can be configured to affect the final sample classification. Other analysis results do not affect the overall final classification of the sample, but are, rather, another source of information for analysts. Administrators can also specify which [File types](../Administration/integrations-connectors/integrations.md#file-types) are automatically submitted for dynamic analysis. The maximum supported file size of each individual sample submitted to the ReversingLabs Cloud Sandbox is 400 MB. --- ## Analysis services ## Overview Spectra Analyze supports optional integration with multiple first-party and third-party static and dynamic analysis services. Through these integrations, samples can be automatically submitted for dynamic analysis or reanalyzed on demand using any of the supported services. All integrations work with samples submitted through the graphical user interface, as well as with those submitted via the [Submissions API](../API%20Documentation/submissions/). Analysis results are organized by analysis type in the navigation bar on the left of the [Sample Details Page](../Sample%20Details). First-party integrations are: - [ReversingLabs Cloud Sandbox](./cloud-sandbox.md) for dynamic analysis. - [ReversingLabs Auxiliary Analysis](./auxiliary-analysis.md) for static analysis. Third-party integrations are always used for dynamic analysis, and they are: - [CAPE Sandbox](./other-integrations.md#cape-sandbox) - [Cisco Secure Malware Analytics](./other-integrations.md#cisco-secure-malware-analytics) - [Cuckoo Sandbox](./other-integrations.md#cuckoo-sandbox) - [FireEye Sandbox](./other-integrations.md#fireeye-sandbox) - [Joe Sandbox](./other-integrations.md#joe-sandbox) - [VMRay](./other-integrations.md#vmray) ## Integrations configuration Analysis services must be configured on the **Administration > Integrations & Connectors > Integrations** page by an administrator. For more information, see [Integrations](../Administration/integrations-connectors/integrations). ### Notes on configuration options #### Submitting distinct files Some analysis services have the option to submit only distinct files; however, it is disabled by default. Administrators can [enable this option](../Administration/integrations-connectors/integrations) to allow submitting only distinct files to an analysis service. When this option is enabled, if a file has already been submitted to Spectra Analyze and analyzed, it is not sent for reanalysis when it is submitted again. This option applies to files submitted using the GUI and the API. It does not affect the reanalysis feature - you can still submit files for reanalysis with any of the integrations even if the files have already been analyzed. #### Queue limits and behavior Some analysis services have queue limit for how many submissions can be simultaneously queued for analysis. Samples are considered queued if they are waiting for analysis or, in some cases, if they are in a processing state. If the queue is full, the appliance attempts to resubmit a sample up to five times, with a delay of 20 seconds between each attempt, before timing out. If it fails to resubmit the sample, that sample is removed from the queue. --- ## Third-party integrations ## CAPE Sandbox For more information about configuring this integration, see [Integrations - CAPE Sandbox](../Administration/integrations-connectors/integrations.md#cape-sandbox). | Maximum supported file size | Submitting only distinct files | Queue limit & behavior | | --------------------------- | ------------------------------ | ---------------------- | | 400 MiB | [Supported](./index.md#submitting-distinct-files) | Up to 60 submissions. Samples are considered queued if waiting for analysis. Running/processing samples do not count towards limit. For more information, see [Queue limits and behavior](./index.md#queue-limits-and-behavior). | CAPE analysis reports are added under [Dynamic Analysis > CAPE](../Sample%20Details/dynamic-analysis-results.md). CAPE offers two types of analysis: *Behavioral* and *Network*. If enabled by an administrator, there is also a **See Task on CAPE** button at the top right of the section. This button redirects to the CAPE web interface, where it is possible to see more information about the file, and compare it to other analysis results. ## Cisco Secure Malware Analytics For more information about configuring this integration, see [Integrations - Cisco Secure Malware Analytics](../Administration/integrations-connectors/integrations.md#cisco-secure-malware-analytics). | Maximum supported file size | Submitting only distinct files | | ------------------------------ | ------------------------------ | | 250 MiB | Not supported | When Cisco Secure Malware Analytics finishes processing a sample, a report with the analysis results is sent to the Spectra Analyze appliance. This report can be accessed under [Dynamic Analysis > Cisco Secure Malware Analytics](../Sample%20Details/dynamic-analysis-results.md). Available reports from this integration include: - **Dropped files** - **Indicators of compromise** - **Networking** ## Cuckoo Sandbox For more information about configuring this integration, see [Integrations - Cuckoo Sandbox](../Administration/integrations-connectors/integrations.md#cuckoo-sandbox). | Maximum supported file size | Submitting only distinct files | Queue limit & behavior | | ---------------------------- | ------------------------------ | ---------------------- | | 400 MiB | Not supported | Up to 60 submissions. Samples are considered queued if waiting for analysis. Running/processing samples do not count towards limit. For more information, see [Queue limits and behavior](./index.md#queue-limits-and-behavior). | Cuckoo reports are added under [Dynamic Analysis > Cuckoo](../Sample%20Details/dynamic-analysis-results.md). Cuckoo offers two types of analysis: *Behavioral* and *Network*. If enabled by an administrator, there is also a **See Task on Cuckoo** button at the top right of the section. This button redirects to the Cuckoo interface, where it is possible to see more information about the file, and compare it to other analysis results. ## FireEye Sandbox For more information about configuring this integration, see [Integrations - FireEye Sandbox](../Administration/integrations-connectors/integrations.md#fireeye-sandbox). | Maximum supported file size | Submitting only distinct files | Queue limit & behavior | | ---------------------------- | ------------------------------ | ---------------------- | | 100 MiB | Not supported | Up to 100 submissions. Samples are considered queued if waiting for analysis or already being processed. For more information, see [Queue limits and behavior](./index.md#queue-limits-and-behavior). | If FireEye is enabled by an administrator, the [Fetch profiles](../Administration/integrations-connectors/integrations.md#profiles) button retrieves a list of profiles available on the FireEye instance. Supported file types can be assigned to profiles that are used for dynamic analysis. Each file type can be assigned to only one profile. New samples of the supported file type assigned to a profile are automatically sent for dynamic analysis. When FireEye finishes processing a sample, a report with the analysis results is sent to the Spectra Analyze appliance. This report can be accessed under [Dynamic Analysis > FireEye](../Sample%20Details/dynamic-analysis-results.md). For more details on configuring and using the FireEye integration, contact [ReversingLabs Support](mailto:support@reversinglabs.com). ## Joe Sandbox For more information about configuring this integration, see [Integrations - Joe Sandbox](../Administration/integrations-connectors/integrations.md#joe-sandbox). | Maximum supported file size | Submitting only distinct files | Queue limit & behavior | | ---------------------------- | ------------------------------ | ---------------------- | | 400 MiB | [Supported](./index.md#submitting-distinct-files) | Up to 20 submissions. Samples are considered queued if waiting for analysis. Running/processing samples do not count towards limit. On timeout, displays "Failed Upload" status message under [Dynamic Analysis > Joe Sandbox](../Sample%20Details/dynamic-analysis-results.md). If this happens, the failed sample no longer remains in the queue. For more information, see [Queue limits and behavior](./index.md#queue-limits-and-behavior). | If Joe Sandbox is enabled by an administrator, the [Fetch profiles](../Administration/integrations-connectors/integrations.md#profiles) button retrieves a list of profiles available on the Joe Sandbox instance. Supported file types can be assigned to profiles that are used for dynamic analysis. Each file type can be assigned to only one profile. New samples of the supported file type assigned to a profile are automatically sent for dynamic analysis. Appliance administrators can check the status of the Joe Sandbox service on the [System Status](../Administration/usage-alerts/system-status.md) page, under **External Services Connectivity**. Joe Sandbox analysis reports are added under [Dynamic Analysis > Joe Sandbox](../Sample%20Details/dynamic-analysis-results.md). Clicking the section name in the sidebar opens the page with general information about Joe Sandbox, and details about the latest analysis. If enabled by an administrator, there is also a **See Task on Joe Sandbox** button at the top right of the page. Additional information is available on the following tabs: - **Behavior Analysis**: contains the process tree menu obtained from the Joe Sandbox JSON report. - **Network Analysis**: displays all network activity detected during dynamic analysis. The following protocols are listed: TCP, UDP, DNS, HTTP, HTTPS, FTP, ICMP, IRC and SMTP. - **Domains/IPs/URLs**: shows the extracted URIs in three separate tabs as they are differentiated in the HTML report. Public and private IP addresses are not in separate tabs; instead, they have a boolean attribute *Private* visible in the list. ## VMRay For more information about configuring this integration, see [Integrations - VMRay](../Administration/integrations-connectors/integrations.md#vmray). | Maximum supported file size | Submitting only distinct files | | ------------------------------ | ------------------------------ | | 305 MiB | Not supported | There is no need to retrieve available profiles/environments from VMRay and assign file types to specific platforms. Samples are sent to dynamic analysis according to how the VMRay instance is configured. When VMRay finishes processing a sample, a report with the analysis results is sent to the Spectra Analyze appliance. This report can be accessed under [Dynamic Analysis > VMRay](../Sample%20Details/dynamic-analysis-results.md). --- ## Graph ## Overview The **Graph** page is accessible from the top navigation menu. It provides an interactive visualization of relationships between malware samples, files, domains, IPs, and other entities. Users can create, view, and manage graphs to explore these connections. The landing page displays a list of saved graphs, each represented by a thumbnail preview, name, creator, and last modified date. On this page, users can do the following: - **Search by graph name** using the search bar at the top. - Create graphs by clicking **+ New graph**. - Share graphs by copying links to individual graphs under **☰ > Copy link**. - Delete individual graphs by clicking **☰ > Delete**. - Bulk delete graphs by checking the boxes next to the graphs and clicking **Delete**. Select any existing graph or create a new one to get started. ### Graph navigation Use the mouse to navigate: click and drag the canvas to move around, scroll to zoom in or out, and click and drag the nodes to move them around. Click a node to open a [sidebar](#sidebar) on the right side of the canvas, providing information on that specific node. Right-click a node to access the context menu with options specific to that node. [Control nodes](#control-nodes), for example, offer options to **Load more** child nodes or **Export** a list of them. ## Nodes ### Root nodes For graphs created by adding a single hash or by navigating from the sample summary page, the icon in the center of the graph represents the sample. *Sample nodes* are also known as **root nodes**, as they serve as the starting points in the graph. To add more root nodes to the graph, enter a hash into the **Graph search bar** and click **+**, or promote an existing file node to a new root node. The Graph search only accepts valid SHA-1 hashes. Other *file nodes* are displayed on the graph because of some relationship to the root node. These can be promoted to root nodes via the sidebar or right-click menu by selecting **Expand** or **Fetch & Analyze** (for cloud samples). Their transformation from a file node into a new root node adds more [control nodes](#control-nodes) and integrates their relationships into the existing graph. ### Control nodes Root nodes branch into **control nodes**, each representing a distinct type of relationship. Control nodes act as entry points for exploring data. Each node is visualized as a color-coded pie chart showing the number of *subnodes* per classification: goodware, suspicious, malicious, or unknown. Initially, each control node displays up to 20 unique subnodes. For cloud samples, fewer control nodes are available until the sample is fetched and analyzed from either the node sidebar or the search page to display additional relationship data. The available control nodes are: - Dropped files - Extracted Files - Parents and Sources - (RHA) Similarity - Static Network References - Dynamic Network References - Network References: Contacted URLs, Domains and IPs ## Sidebar The sidebar provides details and actions based on the selected node: - **Control nodes** show statistics on subnodes. - **Extracted file nodes** display file reputation and threat names. - **Network reference nodes** provide third-party reputations and classification reasons. When available, network reference nodes for extracted and contacted IP addresses display their country of origin. To load more subnodes, select a control node and click **Show more**. Highlighted and underlined items in the sidebar can be clicked to navigate to a different sample summary page, or to perform an advanced search query. ## Filtering Graphs can be filtered by classification, file type or file name. The filtering options are accessible via the **Show Filters** button in the top left of the canvas. ## Saving and updating Click **Save** when working on a new graph to open the save dialog, and give it a name. When you open a saved graph, it loads all references from the previous session, plus any new ones discovered since then. --- ## Spectra Analyze Tags — System Tags, User Tags & Advanced Search The Spectra Analyze appliance supports two types of tags: System Tags and User Tags. Both types of tags are visible for every sample in the [Expanded Details](./search-page.md#expanded-details) and on the **Sample Details ‣ Summary** page. [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) automatically adds System Tags to new samples during analysis based on their metadata properties. It is not possible to change or add new System Tags to samples manually. Samples analyzed with Spectra Core version 3.7.1 will not have any System Tags. Users should submit such samples for reanalysis with Spectra Core to receive System Tags. User Tags are completely custom; any Spectra Analyze user can add and remove User Tags on all local samples on the appliance. User Tags are shared between all users of a Spectra Analyze instance. In other words, every user can see the tags created by other users, assign those tags to samples, or remove them from samples. User Tags are local-only and unique to each Spectra Analyze instance. They are not stored in the Spectra Intelligence cloud when a sample with User Tags is submitted for analysis. ## Searching for Samples by Tags There are several ways to find all samples tagged with a particular tag. 1. Use the Sample Search bar on the uploads page. Type in the hash symbol (#) followed by the tag (for example, #desktop). The search feature supports partial matching, so searching for #desktop will also find tags that contain the word “desktop” (for example, #desktop_app, #malicious_desktop, #zdesktop) 2. Or, click the tag in the list of User Tags on [Expanded Details](./search-page.md#expanded-details) or on the **Sample Details ‣ Summary** page In both cases, the Tags page will be displayed and filtered by the selected tag. This applies to both System Tags and User Tags. 3. If access to the [Advanced Search](./advanced-search.md) feature is enabled on the appliance, use the `tag` keyword to find samples with System Tags, and the `tag-user` keyword to look for samples with User Tags. Both keywords are case-insensitive and support wildcard matching. All samples with the queried tags are listed on the search results page, and divided into Local and Cloud depending on their location. ## Adding User Tags to Samples All Spectra Analyze users can create their own User Tags or add already existing ones to samples on the appliance. Keep in mind the following rules and limitations when creating new User Tags: - User Tags are case-sensitive and distinguish spaces from underscores. In other words, `Example` and `example` are two separate tags; `test_tag` and `test tag` are separate tags, too. - A single tag must be between 2 and 40 characters long (including spaces), matching the supported pattern. Supported characters for tags are [a-z0-9][a-z0-9 /._-]. The following examples are valid tags: `malware_1, ClassifiedByYARA, false-positive, Better.Test/Tag`. The following examples illustrate invalid tags: `Ž++, #hashtag, *.exe`. - It is possible to create a User Tag with the same name as a System Tag. For example, there can be an `indicators` System Tag, and a user can create their own `indicators` tag. Removing a User Tag does not affect the System Tag in any way. - If the user attempts to add a tag that is identical to a System Tag already added to the sample, it will be ignored (not added to the sample). However, it is possible to add a User Tag identical to a System Tag if the sample does not have that System Tag. For example, `antisandbox` is a System Tag. If a sample has this System Tag, attempting to add a User Tag called `antisandbox` will fail. If the sample doesn’t have it, `antisandbox` will be added as a User Tag. User Tags can be added to local samples (or removed from them) in several ways. **Adding User Tags to individual samples** 1. In the [Expanded Details](./search-page.md#expanded-details) for a sample, click **Edit Tags** button in the list of User Tags, or click the icon to the right of the list. This can be done from any Spectra Analyze page that supports Expanded Details (Search results, Alerts, YARA, Tags, Sample Details > Extracted Files). 2. Or, on the **Sample Details ‣ Summary** page, find the list of User Tags and click **Edit Tags**. 3. Or, on the Search & Submissions page, select a sample and click the triple bar button next to the *Size* column title. In the menu that opens, select the **Apply tags** option. In all three cases, the *Edit tags* dialog opens and displays the current list of User Tags if any are assigned to the sample. Start typing into the dialog and a pull-down menu with suggestions will appear if the letters match any of the existing tags. Select the desired tags from the pull-down, or type in the name of a new tag. To remove existing tags from the sample, if there are any, delete them from the input field in the dialog. Click **Save** to confirm the changes. 4. Use the [Modify tags API](./API%20Documentation/tags-api.md) to list User Tags for a sample, add new ones, and remove existing ones. **Adding User Tags to samples in bulk** Select one or more samples on any of the pages that support bulk tagging (Submissions, YARA, Tags, Sample Details > Extracted Files). While the samples are selected, choose the **Apply tags** option from the bulk actions menu next to the *Size* column title. This opens the *Edit tags* dialog. Start typing into the dialog and a pull-down menu with suggestions will appear if the letters match any of the existing tags. Select the desired tags from the pull-down, or type in the name of a new tag. To add multiple tags at once, separate them with commas (e.g., *tag1*, *tag2*, *tag3*). To remove existing tags from the sample, if there are any, delete them from the input field in the dialog. ![Dialog for adding tags with autocomplete pull-down menu](images/analyze-tags-new.png) Click **Save** to confirm the changes. The dialog will automatically close, and a notification will appear in the upper right corner, informing about changed tags. To add User Tags to samples from Spectra Intelligence, the samples must first be [downloaded to the appliance](./search-page.md#downloading-files-from-spectra-intelligence). When they are downloaded, User Tags can be added in any of the ways described on this page. --- ## Spectra Analyze Troubleshooting — Upload Failures, API Errors & Licensing # Troubleshooting This guide covers common issues with [Spectra Analyze](./index.md) and the steps to resolve them. --- ## File upload fails or hangs **Symptom** The upload progress bar in the header stalls or the browser shows no response after selecting a file via the **Submit** button. The upload may fail silently, or the browser displays a network error. **Cause** The most common causes are: - The file exceeds the configured maximum upload size. - The browser tab was navigated away from or refreshed during upload, which interrupts the transfer. - A network timeout or proxy between the browser and the appliance terminated the connection. - Disk space on the appliance is critically low, causing the upload to be rejected at the server. **Solution** 1. Check the appliance's configured maximum file size limit under **Administration > Configuration > General** and compare it to the file you are trying to submit. Files larger than this limit are rejected with an HTTP 413 error when submitted via the API. When submitted via the GUI, files exceeding the limit display a modal: "File Size Exceeds Spectra Analyze Upload Limit! Analyze large files with Spectra Detect!" 2. Do not navigate away from the page or refresh the browser tab while an upload is in progress. The upload status bar in the header indicates active transfers. 3. If you are uploading over a proxy or VPN, check that the proxy is not terminating idle connections prematurely. Increase the proxy timeout or upload directly if possible. 4. Check available disk space on the appliance using the [Health Status Indicator](./index.md#health-status-indicator) or the **Administration > System Status** page. See [Storage space warning](#storage-space-warning) for remediation steps. 5. For large files, use the [Submissions API](./API%20Documentation/submissions.md) directly with a tool like `curl`: ```bash curl -X POST https:///api/submit/file/ \ -H "Authorization: Token " \ -F "file=@/path/to/large-file.exe" ``` --- ## File stuck in "Processing" status **Symptom** A submitted file remains in the **Processing** state on the [Search & Submissions](./search-page.md) page for an extended period (more than 15–30 minutes for typical files) and never transitions to a classified state. **Cause** - The appliance analysis queue is backed up due to a large number of submissions. - A Spectra Core analysis instance has become unresponsive processing an unusually complex or deeply nested archive. - The appliance has insufficient CPU or memory resources to keep up with the current submission rate. **Solution** 1. Check the [Health Status Indicator](./index.md#health-status-indicator) for CPU, memory, and queue size warnings. Navigate to **Administration > System Status** for a detailed breakdown. 2. If the queue is congested, reduce the rate of new submissions and allow existing jobs to drain. 3. Check the appliance system logs for errors related to analysis workers. If an individual analysis instance is hung, the appliance will typically restart it automatically. 4. For files that are persistently stuck, try resubmitting the file after the queue clears. You can also use the [Reanalyze API](./API%20Documentation/reanalyze-api.md) to trigger reanalysis: ```bash curl -X POST https:///api/samples//analyze/ \ -H "Authorization: Token " \ -F "analysis=core" ``` 5. If the issue persists across multiple files, contact [ReversingLabs Support](mailto:support@reversinglabs.com) with system logs. --- ## Classification result is unexpected (false positive or false negative) **Symptom** A file is classified as malicious when it is known to be clean (false positive), or a known malicious file is classified as goodware or receives a low risk score (false negative). **Cause** - A custom YARA rule with overly broad pattern matching is triggering on clean files. - The file is new and has not yet been seen by enough classification sources to produce a confident verdict. - The classification was manually overridden by another user on the appliance. - The file is a compressed or packed variant not yet in the threat database. **Solution** 1. Review the **Classification Reason** in the [Report Summary Header](./Sample%20Details/sample-details-summary.md) to identify which classifier produced the final verdict. 2. If the classification originates from a YARA rule, navigate to the [YARA](./yara.md) page and review the matching ruleset. Tighten the rule conditions to reduce false positives. See [Interpreting Analysis Results](./getting-started.md#understanding-the-classification-reason) for guidance on evaluating classification confidence. 3. Check whether a user override is in effect. The classification sources table on the sample details page shows if a manual override is present. 4. For false negatives on known malware, check whether Spectra Intelligence enrichment is configured and reachable (see [Cannot connect to Spectra Intelligence for enrichment](#cannot-connect-to-spectra-intelligence-for-enrichment)). Intelligence feed data significantly improves classification confidence. 5. If the sample is a known false positive, apply a classification override directly on the sample details page or use the [Set Classification API](./API%20Documentation/set-classification-api.md). See [Administering classification overrides](./getting-started.md#administering-classification-overrides) for details. 6. Submit persistent false positives or false negatives to ReversingLabs for analyst review at [support@reversinglabs.com](mailto:support@reversinglabs.com). --- ## Cannot log in / authentication error **Symptom** Attempting to log in to the Spectra Analyze web interface returns "Invalid credentials", "Account locked", or redirects back to the login page without an error message. **Cause** - Incorrect username or password. - The user account has been disabled or locked after repeated failed login attempts. - An SSO or LDAP integration is misconfigured, causing authentication to fail silently. - The session cookie is stale or the browser has cached an old session. **Solution** 1. Verify you are entering the correct credentials. Passwords are case-sensitive. 2. Clear browser cookies and cache, then retry the login. 3. If the account is locked due to failed login attempts, it cannot be manually unlocked by an administrator. The account will automatically unlock after the configured block timeout expires. See [Login Security](./Administration/configuration-update/configuration.md#login-security) for details on the lock duration. 4. If LDAP or SSO integration is in use, verify the configuration under **Administration > Configuration**. Confirm that the LDAP server is reachable from the appliance and that bind credentials are correct. 5. If you have lost administrator access entirely, contact [ReversingLabs Support](mailto:support@reversinglabs.com) to arrange account recovery. --- ## Appliance shows license warning or expiry **Symptom** A banner appears in the interface warning that the license is expiring soon or has already expired. The [Health Status Indicator](./index.md#health-status-indicator) shows a red icon. Certain features or API endpoints may become unavailable. **Cause** - The appliance license has reached or passed its expiration date. - A new license file has been issued but not yet applied to the appliance. - The appliance cannot reach the ReversingLabs license server for validation (for cloud-validated licenses). **Solution** 1. Navigate to **Administration > Configuration > Licensing** to view the current license status and expiration date. See [Licensing](./Administration/configuration-update/licensing.md). 2. If you have received a new license file, upload it through the licensing page. 3. If the license appears valid but the warning persists, verify that the appliance can reach the ReversingLabs license server. Check for firewall rules blocking outbound HTTPS traffic. 4. Contact your ReversingLabs account manager or [support@reversinglabs.com](mailto:support@reversinglabs.com) to request a license renewal. --- ## API returns 401 Unauthorized **Symptom** API requests return: ```json {"detail": "Invalid token."} ``` or ```http HTTP/1.1 401 Unauthorized ``` **Cause** - The API token is missing from the request headers. - The token has been revoked or has expired. - The token is being passed incorrectly (wrong header name or format). **Solution** 1. Confirm that every API request includes the `Authorization` header with the correct token format, for example: ```bash curl -X POST https:///api/samples//analyze/ \ -H "Authorization: Token " \ -F "analysis=core" ``` 2. Verify that the token is still valid by checking **Administration > Tokens** if you manage tokens for multiple users. See [Tokens](./Administration/users-personalization/tokens.md). 3. If the token was recently regenerated or revoked, update all integrations and scripts that use the old token. 4. Check that the token belongs to a user account that is still active and has not been disabled. --- ## API returns 403 Forbidden **Symptom** API requests return: ```http HTTP/1.1 403 Forbidden ``` ```json {"detail": "You do not have permission to perform this action."} ``` **Cause** - The authenticated user's role does not grant access to the requested endpoint or resource. - A per-user or per-group permission restriction is in place for the specific operation (for example, deleting samples or accessing administration endpoints). **Solution** 1. Check the user's assigned role under **Administration > User Roles**. See [User Roles](./Administration/users-personalization/user-roles.md) for a full list of permissions associated with each role. 2. If the operation requires elevated privileges, ask an administrator to assign the appropriate role or a higher-privilege role to the user. 3. If the 403 is returned for a specific resource (for example, a private sample), check whether the sample's visibility settings restrict access. --- ## Slow analysis performance **Symptom** Files take significantly longer than expected to complete analysis. The queue displayed on the **Administration > System Status** page is consistently non-zero. Analysis that normally completes in seconds takes minutes. **Cause** - The appliance is receiving more submissions than its current Spectra Core capacity can handle. - Large or deeply nested archives (for example, multi-layer ZIP files) are consuming disproportionate analysis time. - CPU or memory resources on the appliance are under heavy load from other processes. - The appliance hardware does not meet recommended specifications for the current submission volume. **Solution** 1. Check CPU and memory utilization via **Administration > System Status** or the [Health Status Indicator](./index.md#health-status-indicator). Look for sustained CPU above 90% or memory above 85%. 2. Review the configured system health thresholds under **Administration > Configuration > System Health Indicator** and adjust alert thresholds to get earlier warnings. 3. Identify if specific file types (large archives, firmware images) are consistently slow. Consider rate-limiting submission of such files during peak periods. 4. If the appliance is persistently under-resourced, consider adding a Spectra Detect Worker cluster and connecting it via [Spectra Detect Manager](/SpectraDetect/Admin/ManagerSettings/) to offload processing. 5. Review the [platform requirements](/General/DeploymentAndIntegration/PlatformRequirements) to confirm the appliance meets minimum hardware specifications for the current submission rate. --- ## Storage space warning **Symptom** The [Health Status Indicator](./index.md#health-status-indicator) shows a red icon with a disk-related warning. The hover tooltip or **System Status** page displays a message similar to: ``` Disk usage: 94% — threshold exceeded ``` New file uploads may be rejected. **Cause** - The appliance disk has accumulated a large number of stored samples and analysis results. - Log files or system backups have consumed available space. - The configured disk usage threshold has been set too conservatively relative to actual growth patterns. **Solution** 1. Navigate to **Administration > Configuration > Backup & Purge** to configure automated sample purge policies. Samples older than a specified retention period can be removed automatically. See [Backup & Purge](./Administration/configuration-update/backup-purge.md). 2. To reclaim space immediately, navigate to **Administration > Configuration & Update > Backup & Purge** and click **Run Purge** to trigger a manual purge according to the configured retention criteria. 3. If log files are consuming space, rotate or archive them per your appliance OS procedures. 4. Adjust the disk usage alert threshold under **Administration > Configuration > System Health Indicator** if the current threshold triggers too early for your capacity. 5. If disk space is chronically insufficient, consider expanding the appliance storage volume or archiving older samples externally before deleting them from the appliance. --- ## Cannot connect to Spectra Intelligence for enrichment **Symptom** The [Health Status Indicator](./index.md#health-status-indicator) shows a red icon. The hover tooltip displays: ``` Spectra Intelligence: not reachable ``` Samples on the appliance lack Spectra Intelligence enrichment data such as scanner detections, threat names, or community classifications. **Cause** - The Spectra Intelligence credentials configured on the appliance are incorrect or have expired. - Network connectivity from the appliance to `data.reversinglabs.com` is blocked by a firewall or proxy. - The Spectra Intelligence account has exceeded its quota, causing requests to be rejected with HTTP 429. **Solution** 1. Navigate to **Administration > Configuration > Spectra Intelligence** and verify that the username and password are correct. Test the connection using the built-in connectivity check. 2. From the appliance, test outbound connectivity to the Spectra Intelligence API server: ```bash curl -I https://data.reversinglabs.com ``` If this times out or is refused, check firewall rules and proxy configuration. The appliance must be able to reach `data.reversinglabs.com` over HTTPS (port 443). 3. If a proxy is required, configure the proxy address in **Administration > Configuration > General** under the proxy settings, or contact your network team to allow direct HTTPS access to `data.reversinglabs.com`. 4. Check your Spectra Intelligence quota via the **Quota Indicator** in the appliance header bar, or via the [Customer Usage API](/SpectraIntelligence/API/CustomerUsage/tca-9999). If the quota is exhausted, contact [support@reversinglabs.com](mailto:support@reversinglabs.com) to review your entitlements. --- ## Analysis Timeout Issues File analysis timeouts can occur when processing complex or large files that require extensive analysis time. Understanding the causes and solutions helps ensure successful file processing. ## Common Causes Analysis timeouts typically happen due to: - **Large file sizes** - Files approaching or exceeding the size limits for your appliance tier - **Deep nesting** - Archives containing multiple layers of compressed files - **Extensive unpacking** - Files that trigger recursive decompression operations - **Complex file structures** - Files with intricate internal structures requiring detailed parsing - **Resource constraints** - Insufficient RAM or CPU allocation for the analysis workload ## Configuration Options ### Spectra Analyze The analysis timeout can be adjusted in the appliance configuration: 1. Navigate to **Administration > Configuration** 2. Locate the analysis timeout setting 3. Increase the timeout value based on your file processing requirements 4. Save the configuration changes ### File Inspection Engine Use the `--analysis-timeout` flag to control the per-file time limit: ```bash rl-scan --analysis-timeout 300 /path/to/file ``` The timeout value is specified in seconds. ## Troubleshooting Steps If analysis timeouts persist: 1. **Increase allocated resources** - Ensure the appliance or container has sufficient RAM (32 GB+ recommended) and CPU cores 2. **Check decompression ratio limits** - Verify that recursive unpacking isn't exceeding configured limits 3. **Review file characteristics** - Examine the file structure to identify potential issues 4. **Monitor system resources** - Check if the appliance is under heavy load from concurrent analyses 5. **Adjust timeout values** - Increase timeout settings for complex file processing workflows ## Related Topics - [Platform Requirements](/General/DeploymentAndIntegration/PlatformRequirements) - Hardware specifications for different appliance tiers - [How Spectra Core analysis works](/General/AnalysisAndClassification/SpectraCoreAnalysis) - Understanding the analysis process --- ## Antivirus Result Availability When a sample is uploaded or rescanned in Spectra Intelligence, it will usually get new antivirus results **within 30 minutes**. When a sample has new antivirus results, these will available in relevant APIs, for example [TCA-0104 File analysis](/SpectraIntelligence/API/FileThreatIntel/tca-0104/). --- ## Certificate Revocation ReversingLabs maintains a certificate revocation database that is updated with each [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) release. Because the database is offline, some recently revoked certificates may not appear as revoked until the next update. Certificate Authority (CA) revocation alone is not sufficient to classify a sample as malicious. Most CAs backdate revocations to the certificate's issuance date, regardless of when or whether the certificate was abused. When additional context is available, ReversingLabs adjusts the revocation date to reflect the most appropriate point in time. If a certificate is whitelisted, this correction is not applied. ## Searching for Revoked Certificates You can find samples signed with revoked certificates using **Advanced Search** with the `tag:cert-revoked` keyword. Advanced Search is available both through the [Spectra Analyze user interface](/SpectraAnalyze/search-page/) and as the [TCA-0320 Advanced Search](/SpectraIntelligence/API/MalwareHunting/tca-0320/) API. --- ## File Classification and Risk Scoring — ReversingLabs # Classification File classification assigns a risk score (0-10) and threat verdict (malicious, suspicious, goodware, or unknown) to every analyzed file using ReversingLabs Spectra Core. The classification algorithm combines YARA rules, machine learning, heuristics, certificate validation, and file similarity matching to determine security status. YARA rules take precedence as the most authoritative signal, followed by other detection methods that contribute to the final verdict. The classification of a sample is based on a comprehensive assessment of its assigned risk factor, threat level, and trust factor; however, it can be manually or automatically overridden when necessary. Based on this evaluation, files are placed into one of the following buckets: - No threats found (unclassified) - Goodware/known - Suspicious - Malicious The classification process weighs signals from all available sources to arrive at the most accurate verdict. Some signals are considered more authoritative than others and take priority. For example, [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) YARA rules always take precedence because they are written and curated by ReversingLabs analysts. These rules provide the highest degree of accuracy, as they target specific, named threats. This does not mean that other classification methods are less important. Similarity matching, heuristics, and machine learning still contribute valuable signals and may produce additional matches. In cases where multiple detections apply, YARA rules simply serve as the deciding factor for the final classification. ## Risk score A risk score is a value representing the trustworthiness or malicious severity of a sample. Risk score is expressed as a number from 0 to 10, with 0 indicating whitelisted samples from a reputable origin, and 10 indicating the most dangerous threats. At a glance: Files with no threats found don't get assigned a risk score and are therefore **unclassified**. Values from 0 to 5 are reserved for samples classified as **goodware/known**, and take into account the source and structural metadata of the file, among other things. Since goodware samples do not have threat names associated with them, they receive a description based on their risk score. Risk scores from 6 to 10 are reserved for **suspicious** and **malicious** samples, and express their severity. They are calculated by a ReversingLabs proprietary algorithm, and based on many factors such as file origin, threat type, how frequently it occurs in the wild, YARA rules, and more. Lesser threats like adware get a risk score of 6, while ransomware and trojans always get a risk score of 10. ### Malware type and risk score In cases where multiple threats are detected and there are no other factors (such as user overrides) involved, the final classification is always the one that presents the biggest threat. If they belong to the same risk score group, malware types are prioritized in this order: | Risk score | Malware types | |------------|---------------------------------------------------------------------------------------------------------------------| | 10 | EXPLOIT > BACKDOOR > RANSOMWARE > INFOSTEALER > KEYLOGGER > WORM > VIRUS > CERTIFICATE > PHISHING > FORMAT > TROJAN | | 9 | ROOTKIT > COINMINER > ROGUE > BROWSER | | 8 | DOWNLOADER > DROPPER > DIALER > NETWORK | | 7 | SPYWARE > HYPERLINK > SPAM > MALWARE | | 6 | ADWARE > HACKTOOL > PUA > PACKED | ## Threat level and trust factor The [risk score table](#risk-score) describes the relationship between the risk score, and the threat level and trust factor used by the [File Reputation API](/SpectraIntelligence/API/FileThreatIntel/tca-0101). The main difference is that the risk score maps all classifications onto one numerical scale (0-10), while the File Reputation API uses two different scales for different classifications. ### Nomenclature The following classifications are equivalent: | File Reputation API | Spectra Analyze | Spectra Detect Worker | | ------------------- | --------------- | ------------------------ | | known | goodware | 1 (in the Worker report) | In the Worker report, the [risk score](#risk-score) is called `rca_factor`. ## Deciding sample priority The [risk score table](#risk-score) highlights that the a sample's risk score and its classification don't have a perfect correlation. This means that a sample's risk score cannot be interpreted on its own, and that the primary criterion in deciding a sample's priority is its classification. Samples classified as suspicious can be a result of heuristics, or a possible early detection. A suspicious file may be declared malicious or known at a later time if new information is received that changes its threat profile, or if the user manually modifies its status. The system always considers a malicious sample with a risk score of 6 as a higher threat than a suspicious sample with a risk score of 10, meaning that samples classified as malicious always supersede suspicious samples, regardless of the calculated risk score. The reason for this is certainty - a malicious sample is decidedly malicious, while suspicious samples need more data to confirm the detected threat. It is a constant effort by ReversingLabs to reduce the number of suspicious samples. While a suspicious sample with a risk score of 10 does deserve user attention and shouldn't be ignored, a malicious sample with a risk score of 10 should be triaged as soon as possible. ## Acting on classification and risk tolerance When appliances or integrations surface data from ReversingLabs Threat Intelligence lookups, the **classification** and **rca_factor** fields are the primary signal to act upon. - Always evaluate the `classification` field first: it determines whether a sample is known goodware, suspicious, or malicious and therefore dictates priority. - Use `rca_factor` to adjust the risk aversion profile and suppress alerts for low-level threats when appropriate. Lower factors correspond to less severe detections. Additional fields worth reviewing: - `propagated`: `true` means one of the extracted child files caused the verdict, so you may need to investigate nested artifacts. - `scan_results`: contains all malicious detections found in the file; the worst detection is propagated as the final file verdict. - `result`: verbal verdict name. - `factor`: can usually be ignored because it is actionable only in conjunction with clean samples. - `propagated_source`: contains the extracted file hash that was found to be malicious and triggered propagation. ### Risk tolerance profiles 1. **Low risk tolerance**: the user wants to be alerted about any possible threat. In this profile, act on both **Suspicious** and **Malicious** verdicts, which generates the maximum number of matches. 2. **High risk tolerance**: the user only wants to be notified about highly impactful threats. In this profile, filter for `classification:Malicious` and `rca_factor >= 7` so only the most severe detections surface. For deployments using Spectra Analyze, the [Risk Tolerance Levels](/SpectraAnalyze/Administration/users-personalization/risk-tolerance-levels) guide explains how appliance sensitivity settings choose which analysis sources count toward classification. For more context on interpreting the classification structure and `rca_factor`, refer to the [Spectra Detect Analysis](/SpectraDetect/Usage/Analysis) documentation, which outlines the fields returned in Worker reports. ## Malware naming standard --- ## Handling False Positives # Handling False Positives A false positive occurs when a legitimate file is incorrectly classified as malicious. While ReversingLabs strives for high accuracy, false positives can occasionally happen due to the complexity of malware detection across hundreds of file formats and millions of samples. ## What You Can Do If you encounter a false positive, you have several options: ### 1. Local Classification Override On Spectra Analyze, you can immediately override the classification using the classification override feature: - Navigate to the file's Sample Details page - Use the classification override option to manually set the file as goodware - The override takes effect immediately on your appliance - All users on the same appliance will see the updated classification ### 2. Spectra Intelligence Reclassification Request Submit a reclassification request through Spectra Intelligence: - The override propagates across all appliances connected to the same Spectra Intelligence account - Other appliances in your organization will automatically receive the updated classification - This is the recommended approach for organization-wide corrections ### 3. Goodware Overrides Use Goodware Overrides to propagate trusted parent classifications to extracted child files: - If a trusted parent file (e.g., from Microsoft or another reputable vendor) contains files that trigger false positives - The parent's goodware classification can automatically override the child files - This is particularly useful for legitimate installers that may contain components flagged by heuristics ## How ReversingLabs Handles False Positive Reports If a customer reports a false positive (through Zendesk, or by contacting the Support team at support@reversinglabs.com), the first thing we do is re-scan the sample to make sure that the results are up-to-date. If the results are still malicious, our Threat Analysis team will: 1. Conduct our own research of the software and the vendor 2. Contact the AV scanners and notify them of the issue 3. Change the classification in our system (we do not wait for AVs to correct the issue) --- If the file is confirmed to be a false positive, we begin by analyzing why the incorrect classification occurred. Then we try to correct the result by making adjustments related to file relationships, certificates, AV product detection velocity (e.g. are detections being added or removed), we will re-scan and reanalyze samples, adjust/add sources and, if necessary, manually investigate the file. If these efforts do not yield a correct result, we have the ability to **manually override the classification** — but we only do so after thorough analysis confirms the file is benign. --- ## ReversingLabs malware naming standard The ReversingLabs detection string consists of three main parts separated by dots. All parts of the string will always appear (all three parts are mandatory). ``` platform-subplatform.type.familyname ``` 1. The first part of the string indicates the **platform** targeted by the malware. This string is always one of the strings listed in the [Platform string](#platform-string) table. If the platform is Archive, Audio, ByteCode, Document, Image or Script, then it has a subplatform string. Platform and subplatform strings are divided by a hyphen (`-`). The lists of available strings for Archive, Audio, ByteCode, Document, Image and Script subplatforms can be found in their respective tables. 2. The second part of the detection string describes the **malware type**. Strings that appear as malware type descriptions are listed in the [Type string](#type-string) table. 3. The third and last part of the detection string represents the malware family name, i.e. the name given to a particular malware strain. Names "Agent", "Gen", "Heur", and other similar short generic names are not allowed. Names can't be shorter than three characters, and can't contain only numbers. Special characters (apart from `-`) must be avoided as well. The `-` character is only allowed in exploit (CVE/CAN) names (for example CVE-2012-0158). #### Examples If a trojan is designed for the Windows 32-bit platform and has the family name "Adams", its detection string will look like this: ``` Win32.Trojan.Adams ``` If some backdoor malware is a PHP script with the family name "Jones", the detection string will look like this: ``` Script-PHP.Backdoor.Jones ``` Some potentially unwanted application designed for Android that has the family name "Smith" will have the following detection string: ``` Android.PUA.Smith ``` Some examples of detections with invalid family names are: ``` Win32.Dropper.Agent ByteCode-MSIL.Keylogger.Heur Script-JS.Hacktool.Gen Android.Backdoor.12345 Document-PDF.Exploit.KO Android.Spyware.1a Android.Spyware.Not-a-CVE Win32.Trojan.Blue_Banana Win32.Ransomware.Hydra:Crypt Win32.Ransomware.HDD#Cryptor ``` #### Platform string The platform string indicates the operating system that the malware is designed for. The following table contains the available strings and the operating systems for which they are used. | String | Short description | | ----------- | ------------------------------------------------------------------------------------------ | | ABAP | SAP / R3 Advanced Business Application Programming environment | | Android | Applications for Android OS | | AOL | America Online environment | | Archive | Archives. See [Archive subplatforms](#archive-subplatforms) for more information. | | Audio | Audio. See [Audio subplatforms](#audio-subplatforms) for more information. | | BeOS | Executable content for Be Inc. operating system | | Boot | Boot, MBR | | Binary | Binary native type | | ByteCode | ByteCode, platform-independent. See [ByteCode subplatforms](#bytecode-subplatforms) for more information. | | Blackberry | Applications for Blackberry OS | | Console | Executables or applications for old consoles (e.g. Nintendo, Amiga, ...) | | Document | Documents. See [Document subplatforms](#document-subplatforms) for more information. | | DOS | DOS, Windows 16 bit based OS | | EPOC | Applications for EPOC mobile OS | | Email | Emails. See [Email subplatforms](#email-subplatforms) for more information. | | Firmware | BIOS, Embedded devices (mp3 players, ...) | | FreeBSD | Executable content for 32-bit and 64-bit FreeBSD platforms | | Image | Images. See [Image subplatforms](#image-subplatforms) for more information. | | iOS | Applications for Apple iOS (iPod, iPhone, iPad…) | | Linux | Executable content for 32 and 64-bit Linux operating systems | | MacOS | Executable content for Apple Mac OS, OS X | | Menuet | Executable content for Menuet OS | | Novell | Executable content for Novell OS | | OS2 | Executable content for IBM OS/2 | | Package | Software packages. See [Package subplatforms](#package-subplatforms) for more information. | | Palm | Applications for Palm mobile OS | | Script | Scripts. See [Script subplatforms](#script-subplatforms) for more information. | | Shortcut | Shortcuts | | Solaris | Executable content for Solaris OS | | SunOS | Executable content for SunOS platform | | Symbian | Applications for Symbian OS | | Text | Text native type | | Unix | Executable content for the UNIX platform | | Video | Videos | | WebAssembly | Binary format for executable code in Web pages | | Win32 | Executable content for 32-bit Windows OS's | | Win64 | Executable content for 64-bit Windows OS's | | WinCE | Executable content for Windows Embedded Compact OS | | WinPhone | Applications for Windows Phone | ##### Archive subplatforms | String | Short description | | ---------------------------------- | ------------------------------------------------------------ | | ACE | WinAce archives | | AR | AR archives | | ARJ | ARJ (Archived by Robert Jung) archives | | BZIP2 | Bzip2 archives | | CAB | Microsoft Cabinet archives | | GZIP | GNU Zip archives | | ISO | ISO image files | | JAR | JAR (Java ARchive) archives | | LZH | LZH archives | | RAR | RAR (Roshal Archive) archives | | 7ZIP | 7-Zip archives | | SZDD | Microsoft SZDD archives | | TAR | Tar (tarball) archives | | XAR | XAR (eXtensible ARchive) archives | | ZIP | ZIP archives | | ZOO | ZOO archives | | *Other Archive identification* | All other valid [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) identifications of Archive type | ##### Audio subplatforms | String | Short description | | -------------------------------- | ---------------------------------------------------------- | | WAV | Wave Audio File Format | | *Other Audio identification* | All other valid Spectra Core identifications of Audio type | ##### ByteCode subplatforms | String | Short description | | ------ | ----------------- | | JAVA | Java bytecode | | MSIL | MSIL bytecode | | SWF | Adobe Flash | ##### Document subplatforms | String | Short description | | ----------------------------------- | ------------------------------------------------------------ | | Access | Microsoft Office Access | | CHM | Compiled HTML | | Cookie | Cookie files | | Excel | Microsoft Office Excel | | HTML | HTML documents | | Multimedia | Multimedia containers that aren't covered by other platforms (e.g. ASF) | | Office | File that affects multiple Office components | | OLE | Microsoft Object Linking and Embedding | | PDF | PDF documents | | PowerPoint | Microsoft Office PowerPoint | | Project | Microsoft Office Project | | Publisher | Microsoft Office Publisher | | RTF | RTF documents | | Visio | Microsoft Office Visio | | XML | XML and XML metafiles (ASX) | | Word | Microsoft Office Word | | *Other Document identification* | All other valid Spectra Core identifications of Document type | ##### Email subplatforms | String | Short description | | ------ | ------------------------------------- | | MIME | Multipurpose Internet Mail Extensions | | MSG | Outlook MSG file format | ##### Image subplatforms | String | Short description | | -------------------------------- | ------------------------------------------------------------ | | ANI | File format used for animated mouse cursors on Microsoft Windows | | BMP | Bitmap images | | EMF | Enhanced Metafile images | | EPS | Adobe Encapsulated PostScript images | | GIF | Graphics Interchange Format | | JPEG | JPEG images | | OTF | OpenType Font | | PNG | Portable Network Graphics | | TIFF | Tagged Image File Format | | TTF | Apple TrueType Font | | WMF | Windows Metafile images | | *Other Image identification* | All other valid Spectra Core identifications of Image type | ##### Package subplatforms | String | Short description | | ---------------------------------- | ------------------------------------------------------------ | | NuGet | NuGet packages | | DEB | Debian Linux DEB packages | | RPM | Linux RPM packages | | WindowStorePackage | Packages for distributing and installing Windows apps | | *Other Package identification* | All other valid Spectra Core identifications of Package type | ##### Script subplatforms | String | Short description | | --------------------------------- | ------------------------------------------------------------ | | ActiveX | ActiveX scripts | | AppleScript | AppleScript scripts | | ASP | ASP scripts | | AutoIt | AutoIt scripts (Windows) | | AutoLISP | AutoCAD LISP scripts | | BAT | Batch scripts | | CGI | CGI scripts | | CorelDraw | CorelDraw scripts | | Ferite | Ferite scripts | | INF | INF Script, Windows installer scripts | | INI | INI configuration file | | IRC | IRC, mIRC, pIRC/Pirch Script | | JS | Javascript, JScript | | KiXtart | KiXtart scripts | | Logo | Logo scripts | | Lua | Lua scripts | | Macro | Macro (e.g. VBA, AmiPro macros, Lotus123 macros) | | Makefile | Makefile configuration | | Matlab | Matlab scripts | | Perl | Perl scripts | | PHP | PHP scripts | | PowerShell | PowerShell scripts, Monad (MSH) | | Python | Python scripts | | Registry | Windows Registry scripts | | Ruby | Ruby scripts | | Shell | Shell scripts | | Shockwave | Shockwave scripts | | SQL | SQL scripts | | SubtitleWorkshop | SubtitleWorkshop scripts | | WinHelp | WinHelp Script | | WScript | Windows Scripting Host related scripts (can be VBScript, JScript, …) | | *Other Script identification* | All other valid Spectra Core identifications of Script type | #### Type string This string is used to describe the general type of malware. The following table contains the available strings and describes what each malware type is capable of. For a catalog of common software weaknesses that enable malware, see [CWE](https://cwe.mitre.org/) maintained by MITRE. CISA maintains advisories on actively exploited vulnerabilities at [cisa.gov/known-exploited-vulnerabilities](https://www.cisa.gov/known-exploited-vulnerabilities). | String | Description | | ----------- | ------------------------------------------------------------ | | Adware | Presents unwanted advertisements | | Backdoor | Bypasses device security and allows remote access | | Browser | Browser helper objects, toolbars, and malicious extensions | | Certificate | Classification derived from certificate data | | Coinminer | Uses system resources for cryptocurrency mining without the user's permission | | Dialer | Applications used for war-dialing and calling premium numbers | | Downloader | Downloads other malware or components | | Dropper | Drops malicious artifacts including other malware | | Exploit | Exploits for various vulnerabilities, CVE/CAN entries | | Format | Malformations of the file format. Classification derived from graylisting, validators on unpackers | | Hacktool | Software used in hacking attacks, that might also have a legitimate use | | Hyperlink | Classifications derived from extracted URLs | | Infostealer | Steals personal info, passwords, etc. | | Keylogger | Records keystrokes | | Malware | New and recently discovered malware not yet named by the research community | | Network | Networking utilities, such as tools for DoS, DDoS, etc. | | Packed | Packed applications (UPX, PECompact…) | | Phishing | Email messages (or documents) created with the aim of misleading the victim by disguising itself as a trustworthy entity into opening malicious links, disclosing personal information or opening malicious files. | | PUA | Potentially unwanted applications (hoax, joke, misleading...) | | Ransomware | Malware which encrypts files and demands money for decryption | | Rogue | Fraudulent AV installs and scareware | | Rootkit | Provides undetectable administrator access to a computer or a mobile device | | Spam | Other junk mail that does not unambiguously fall into the Phishing category, but contains unwanted or illegal content. | | Spyware | Collects personal information and spies on users | | Trojan | Allows remote access, hides in legit applications | | Virus | Self-replicating file/disk/USB infectors | | Worm | Self-propagating malware with exploit payloads | --- ## Risk score reference table --- ## How Spectra Core analysis works # How Spectra Core Analysis Works All ReversingLabs products are powered by [Spectra Core](https://www.reversinglabs.com/products/spectra-core) - the engine that analyzes every file and sample. The process of analyzing software involves several steps, and the final output are the analysis reports. To better understand the source and significance of the information contained in those reports, it's helpful to learn what Spectra Core does in the background of ReversingLabs products. This page provides an overview of the Spectra Core analysis process and explains what happens with files in each of the analysis steps. The following main steps have dedicated sections where they are described in detail: 1. [Identification](#1-identification) 2. [Unpacking](#2-unpacking) 3. [Validation](#3-validation) 4. [Metadata processing](#4-metadata-processing) 5. [Classification](#5-classification) ## Automated static analysis When you scan a file with Spectra Core, the engine automatically performs static analysis on the file and all files extracted from it. Automated static analysis is also referred to as **complex binary analysis**. This unique approach to software analysis decomposes files, collects their metadata, and classifies them in terms of the security risk they pose to end-users. Files are analyzed recursively, which means that every file extracted from the software package goes through the same analysis process like its container software package. As implemented in Spectra Core, automated static analysis does not require access to the source code (like SAST tools typically do). It can directly examine compiled software binaries to determine their structure, dependencies and behaviors. In addition to analyzing software binaries (which is the primary use-case), Spectra Core can analyze library code and source code for specific scripting languages. Another benefit of automated static analysis is that **files are not executed during the analysis process**. All available data is extracted even if the files are compressed, executable, or damaged - regardless of their target OS or platform. Because the analysis process does not execute any files, it can be completed in milliseconds and performed on very large files without significant performance penalties. All these features of automated static analysis give Spectra Core a unique advantage - it can analyze post-build artifacts and detect more novel, sophisticated software supply chain attacks than SCA tools are able to. SCA tools typically analyze package managers, manifest files, or source code repositories to find vulnerabilities. They are limited by the need for known signatures of open source dependencies that have to be cross-referenced against a vulnerability database. Being used in pre-build environments, SCA tools lack visibility into deep file structures and build process tampering evidence - insights that Spectra Core readily provides. ## The Spectra Core analysis process The process starts with the input file. The analysis engine performs several distinct steps on every object it extracts from the input file. The following diagram illustrates the flow that every object goes through. You can interact with the diagram to learn more about the process: - Select steps in the diagram to access their dedicated sections on this page ### 1. Identification Format identification is the initial step of the Spectra Core analysis process. To successfully perform the subsequent analysis steps, we first need to know the file format of every object we are analyzing. Specifically, this step analyzes the object structure to determine whether it's **binary** or **text**, and assigns the analyzed object a unique file format description. This description - file format identification - instructs the analysis engine on which rules and modules to use for further file processing. Two main approaches are used for format identification: - **Signatures** - created by ReversingLabs researchers to identify **binary** file formats based on their unique features. For example, Windows .exe files start with bytes "MZ", while PNG files will usually start with "‰PNG". Signatures describe expectations of what a file format should contain. Using heuristics, the analysis process checks whether those expectations align with the actual file structure. In addition to signatures, the analysis process also evaluates any relevant YARA rules (built into the engine as well as user-provided). If there are multiple matches, those from signatures take priority over YARA rule matches. - **Machine learning models** - created and trained by ReversingLabs researchers to identify **textual** file formats based on statistical text identification. The models are able to recognize basic text objects as scripting languages and distinguish software source code from other types of textual content. **Note: ✅ Completing the identification step** The results of the format identification step are: - File hashes - calculated by the analysis engine - File format descriptions - represented as File type.File subtype.Identification (for example, `Binary/Archive/ZIP`). If there are multiple versions of a file format, they can be identified through the additional `version` field. After the format has been identified, the file is either directed to the proper unpacking module according to its signature, or to the validation step. ### 2. Unpacking Unpacking, also referred to as **file decomposition**, is a step in the Spectra Core analysis process where the analyzed file is taken apart to extract all available components and metadata. During the unpacking process, the analysis engine eliminates obfuscation, encryption, compression, and any other protections that may have been applied to the file and its contents. The engine has built-in mechanisms to prevent infinite recursion, and supports configuring the decompression ratio and unpacking depth (how many layers of a file to extract). Different file formats require different unpacking approaches because of their structure and complexity. Because static analysis does not execute a file, it requires **unpackers** - specialized tools for parsing and unpacking individual file formats. ReversingLabs develops in-house static unpackers tailored to specific file formats, and Spectra Core relies on those unpackers during analysis. Generally speaking, goodware file formats are easier to unpack because their structure is known and well-defined, and file behavior can be observed from the format definition. File formats commonly used for malware are good at hiding code, which makes their unpacking more challenging. To create an unpacker for malware file formats, researchers have to identify each format and document its structure. The unpacker must be able to simulate file execution so that its code can be reconstructed and its behavior observed. Any obfuscation and protection artifacts must also be removed to allow extracting further objects. Information about the file behavior allows the unpacker - and consequently, the analysis process - to reveal the original software intent and to let users understand the true meaning of the code that was packed in that particular file format. The ability to unpack a file format makes it possible for the Spectra Core analysis engine to extract a wealth of metadata and critical information often not available from other tools. The collected metadata includes but is not limited to: format header details, strings (including secrets and URIs), function names, library dependencies, and file segments. Unpacking greatly increases the surface that can be analyzed and helps file classification by providing more metadata to look at. This makes it easier to confirm classification verdicts and increases the chance to catch every threat. **Note: ✅ COMPLETING THE UNPACKING STEP** After the file has been successfully unpacked, all collected metadata and the unpacked file content are passed to the validator assigned to the file format. The validator then performs integrity checks on the available data. ### 3. Validation Validation is a step in the Spectra Core analysis process where the **structure** and the **digital signatures** of the analyzed file are verified according to specific criteria for each file format. In the validation step, the previously identified file format is checked against its specification (the formal definition of the file format by its designer). In other words, the validation process looks for differences between the file format specification and its implementation. By doing this, we can gather additional information about the file format and detect anomalies in it. Any malformations that violate the file format specification are further examined to determine if they are capable of triggering potentially malicious behavior. Such malformations may be reported as known vulnerabilities. ReversingLabs uses these malformation patterns to create heuristics for potential future exploits and predictive vulnerability detection. Multiple validators may be used to verify a file format. They are called successively, first to last, or until one of them acknowledges that it recognizes and can handle the specific file format. If validation fails for one of them, the entire file is marked as invalid. Detected issues are reported as validation warnings or errors, depending on their severity. In addition to performing integrity checks of the file format structure, the validation step also verifies any digital certificates that have been used for code signing. Depending on its status, a certificate may influence the classification of files signed with it. The validation step assigns one of the following statuses to every detected certificate: - Valid certificate - Invalid certificate - Bad checksum - Bad signature - Malformed certificate - Self-signed certificate - Impersonation attempt - Expired certificate - Untrusted certificate - Revoked certificate **Note: ✅ COMPLETING THE VALIDATION STEP** After the file has been validated, all collected metadata is processed, evaluated, and transformed into actionable information that can be used to deliver the final file classification. ### 4. Metadata processing Metadata processing is a step in the Spectra Core analysis process where all previously collected metadata is translated into **human-readable**, **explainable information**. That information is used to produce or support the final file classification. Most of it is surfaced in Spectra Core analysis reports. In this step, metadata is converted into **capabilities** and **indicators**. They build up on the file format properties and platform-specific features of the analyzed file to describe software behavior and intent in more detail. The goal is to make it clearer what the analyzed code means and what each object is trying to do. #### Indicators Indicators can be described as behavior markers that are triggered when a specific pattern is found in the collected metadata or in the file content. An indicator may be triggered for multiple reasons. While some indicators can only be found in specific file formats, most are universal and therefore generally applicable. Indicators contribute to the final file classification, but not in an equal measure. Those deemed highly relevant are better at describing the detected malware type, while those with less relevant contributions help in solidifying the machine learning detection. #### Capabilities Based on the indicators triggered on a file, the analysis engine infers that the file exhibits a specific behavior, or that it is capable of performing specific actions. Similar software behaviors are grouped into broader categories - capabilities - according to the features they have in common. For example, a file can have the filesystem capability, which is a broad description that says the file can access the filesystem or perform filesystem operations, but doesn't describe which operation will actually take place. More fine-grained software behavior descriptions are derived from the indicators (e.g. "Accesses the httpd.conf file"). #### Tags The metadata processing step also assigns tags to files based on their properties such as certificate information, software behaviors, file contents, and many more. Some tags can only be applied to specific file types (for example, web browsers or mobile applications). Tags are visible in [Spectra Analyze](/SpectraAnalyze/system-and-user-tags) and can be queried through the [Spectra Intelligence Advanced Search (TCA-0320)](/SpectraIntelligence/API/MalwareHunting/tca-0320) API. In SAFE reports generated by Spectra Assure, tags appear for all unpacked files and for URIs in the Networking section, where they can be used for filtering. **Note: ✅ COMPLETING THE METADATA PROCESSING STEP** After the metadata has been fully processed, the file receives its classification status in the next step of the analysis. ### 5. Classification Classification is a step in the Spectra Core analysis process where the analysis engine produces a **verdict** on whether the analyzed file contains threats harmful to the end-user. Multiple technologies are used for file classification: - format identification - signatures (byte pattern matches) - file structure validation - extracted file hierarchy - file similarity (RHA1) - certificates - machine learning - heuristics (for scripts and fileless malware) - YARA rules included in the analysis engine They are shipped with the analysis engine and can be used offline, without connecting to any external sources. Their coverage varies based on threat and file format type. In other words, not all technologies can detect all threat types, and not all of them work on all file formats. Those default classification abilities of the Spectra Core platform can be extended with **threat intelligence from the ReversingLabs Cloud** to retrieve file reputation information, and with **custom YARA rules for user-assisted classification**. Some classification approaches are more specific than others, with signatures being the most specific. The final classification result relies on the information from all analysis steps, and it is a combination of all technologies applicable to the file format. It will always match one of the technologies even though they may have differing results between them. Because of differences in how malicious files and malware families behave, some files might end up classified as malicious by one technology, and still be considered goodware by others. This doesn’t negate or diminish the final classification. #### Explainable Machine Learning Spectra Core is the first and only solution on the market that relies on [Explainable Machine Learning (xAI)](https://www.reversinglabs.com/blog/machine-learning-for-humans) for threat detection. Explainable Machine Learning was launched by ReversingLabs in 2020 as a predictive threat detection method that can detect novel malware. It focuses on providing threat analysts with human-readable insights into machine learning-driven classifications. The goal of ReversingLabs Explainable Machine Learning is to go beyond the basic verdict of "goodware vs malware", and to help analysts understand **what type of threat was found**, **why it was detected**, and **what to do with it next**. To achieve that, the classification system combines: - **explainability** (by surfacing software behaviors in the form of indicators), - **relevance** (by ranking behaviors based on their contribution to the final verdict), - and **transparency** (by displaying why each software behavior was triggered). Using natural language to provide clear explanations for classification decisions helps security analysts understand how analyzed software behaves and what malware is capable of doing to the system. This transparency fosters trust, facilitates informed decision-making, and makes the logic behind machine learning classification verdicts easier to follow. Over the years, ReversingLabs threat analysts and researchers have carefully transformed raw code and metadata produced by static analysis into indicators - descriptions of software intent. Those indicators are used in training machine learning (ML) models to recognize if a file is malicious based on the described software functionality and behavior. Many of the threats in the training datasets are hand-picked by ReversingLabs experts and fully, correctly labeled so that ML models can learn what constitutes a specific threat type, and distinguish it from other threat types as well as from clean software. This allows ML models to proactively detect and describe threats - even brand new malware - without the need for additional training. When Spectra Core scans a file and extracts some indicators from it, ML models can match them against the indicators they have learned to recognize as typical for malware or a specific threat type. Some indicators are more meaningful in the context of a malware or threat type, so they contribute more to the classification. When the model decides that something is malicious, the decision can be verified through indicators and reasons why they were triggered. This makes the decision more transparent, relevant, and explainable in terms that are familiar to human analysts. ReversingLabs ML models are tailored to threat types to increase accuracy and [continuously improved](https://www.reversinglabs.com/blog/how-to-harden-ml-models-against-adversarial-attacks) to boost their resilience. All classification models can detect if a file is malicious or not. The PE (Portable Executable) malware classifier is also able to provide the information on the detected threat type. The exact threat type indicates higher confidence in the classification result, while threats that get assigned a generic threat type ("Malware") may point to new, emerging malware. The following ML models are used for malware classification: - PE malware classifier - detects if a file is malicious (that covers all the threat types) and if it is a specific malware type (one of **Backdoor**, **Downloader**, **Infostealer**, **Keylogger**, **PUA**, **Ransomware**, **Worm**) - Script classifiers - apply to `Text/