Skip to main content

ServiceNow SIR Integration with ReversingLabs Spectra Analyze

Version: 1.0.0 Status: Production Ready Last Updated: July 2026

Introduction​

The ReversingLabs ServiceNow SIR Integration brings powerful threat intelligence from ReversingLabs Spectra Analyze directly into your ServiceNow Security Incident Response (SIR) workflows. Security teams can enrich indicators of compromise (IOCs) — including file hashes, domains, IP addresses, URLs, and binary files — against ReversingLabs' comprehensive threat database without leaving the ServiceNow platform.

Key Features​

  • File Hash Enrichment — MD5, SHA-1, SHA-256, SHA-512, SSDEEP, TLSH analysis results
  • Domain Enrichment — DNS records, threat classifications, associated IPs, subdomain cascade
  • IP Enrichment — Threat reputation, associated domains, historical resolution data
  • URL Enrichment — Domain extraction, content analysis, threat classification
  • Binary File Upload — Asynchronous file upload with polling queue (up to 500 MB)
  • Automatic Observable Cascade — Creates child observables from DNS records and extracted files
  • Role-Based Access Control — Admin, analyst, and read-only roles for secure operations
  • Audit Logging — Comprehensive integration logs for troubleshooting and compliance
  • Auto-Enrichment on Creation — Business rule triggers enrichment when observables are created
  • Enterprise Ready — Proxy support, configurable timeouts

Snapshot: Enrichment Summary

Snapshot: Security Tags

Snapshot: Enrichment Button

Snapshot: Observable Results

How It Works​

Observable Enrichment​

  1. Enrich — Once an observable (hash, domain, IP, URL, or file) is added to a Security Incident, ReversingLabs enrichment triggers automatically. The analyst can optionally click the ReversingLabs Enrichment button for newly added observables or to refresh enrichment for existing observables.
  2. Analyze — The integration queries ReversingLabs Spectra Analyze for threat intelligence on your indicator.
  3. Results — The observable is updated with threat score, verdict (MALICIOUS / SUSPICIOUS / CLEAN / UNKNOWN), classification, threat names, related indicators and RL specific tags which are both visible and searchable within ServiceNow. Child observables (e.g., IPs from a domain) are created automatically when enabled.

File Upload​

Unknown or suspicious files which are uploaded via ServiceNow's Upload Secure File Attachment feature are automatically sent to ReversingLabs for binary analysis (up to 500 MB). Files are processed asynchronously, and the observable is updated with results once analysis is complete.

Data Flow Diagram​

Data Flow

Requirements​

ServiceNow Instance​

  • ServiceNow version Orlando or later (recommended: Paris, Zurich, or later)
  • Security Incident Response (SIR) plugin (sn_si) — active
  • Threat Intelligence plugin (sn_ti) — installed with SIR
  • System Administrator role for installation
  • ~10 MB available database space

ReversingLabs Account​

  • Active Spectra Analyze subscription (Standard User Role)
  • Valid API key and endpoint URL (typically https://a1000.reversinglabs.com)
  • Optional: Spectra Intelligence for enrichment of IOCs not yet analyzed by your Spectra Analyze instance

Network​

DirectionProtocolPortDestinationPurpose
OutboundHTTPS443a1000.reversinglabs.comPrimary API endpoint
OutboundHTTPS443*.reversinglabs.comRecommended wildcard for future endpoints
  • No inbound connections required
  • Optional: Proxy support for corporate environments with TLS inspection bypass for *.reversinglabs.com

Supported Observable Types​

IOC TypeSupportedExamples
File Hash✓MD5, SHA-1, SHA-256, SHA-512, SSDEEP, TLSH
Domain✓example.com, malicious.net
IPv4 Address✓192.168.1.1, 8.8.8.8
IPv6 Address✓::1, 2001:4860:4860::8888
URL✓https://example.com/path, http://malicious.com
Binary File✓Executables, documents, archives (up to 500 MB)

Installation & Deployment​

Overview​

After installing the app from the ServiceNow Store, you must run two setup scripts to activate the integration. All resources are created with safe defaults — nothing runs until you complete both steps.

note

A guided setup wizard will be available in a future release to automate these steps.

Step 1: Run Infrastructure Setup Script​

After installing the app, run the infrastructure setup script:

  1. Navigate to System Definitions > Scripts - Background
  2. Ensure scope is set to Global (top-right dropdown — critical!)
  3. Open the script file: 01_INSTALL_RL_GLOBAL_SERVICES.js
  4. Paste the entire script content into the Script field
  5. Click Run
  6. Review output for [RL-MASTER-INSTALL] messages
warning

This script must run in Global scope, not the app scope. All created resources are set to safe, inactive defaults — nothing runs until Step 2.

Step 2: Configure and Run Activation Script​

2a. Set the Service Account Password​

Before running the activation script, you must generate a password for the service account:

  1. Navigate to User Administration > Users
  2. Search for rl_service_worker
  3. Open the user record
  4. Click Generate password
  5. Verify the generated password:
    • Is 100+ characters long
    • Contains no colons (:)
  6. If it contains colons, regenerate until you get one without
  7. Click Update to save the password
  8. Copy the password — you'll need it in the next step
warning

The password must not contain colons (:). Colons break HTTP Basic Authentication parsing (username:password format). The script will reject passwords with colons.

2b. Edit and Run the Activation Script​

  1. Open the script file: 02_START_RL_SERVICES.js
  2. Edit the CFG section at the top of the script:
var CFG = {
    srrPassword: '[PASTE PASSWORD FROM STEP 2a]',
    apiKey: '[YOUR SPECTRA ANALYZE API KEY]',
    apiUrl: 'https://a1000.reversinglabs.com',
    pollingIntervalSeconds: 5
};

  1. Replace the placeholders:

    • srrPassword — The password you generated in Step 2a
    • apiKey — Your ReversingLabs API key (from your Spectra Analyze portal)
    • apiUrl — Your Spectra Analyze instance URL
    • pollingIntervalSeconds — Adjust polling frequency if needed (default: 5 seconds)

  2. Navigate to System Definitions > Scripts - Background

  3. Ensure scope is set to Global (top-right dropdown)

  4. Paste the edited script content

  5. Click Run

  6. Review output for [RL-SERVICE-CONTROL] messages

Verify the Installation​

  1. Navigate to Workspaces > Security Incident Response Workspace
  2. Create or open an existing Security Incident
  3. Go to the Investigation tab
  4. Find the link dropdown and choose add multiple
  5. Paste a test hash: d41d8cd98f00b204e9800998ecf8427e
  6. Wait 5-10 seconds, refresh — threat score and classification should populate

Configuration​

System Properties​

All properties are configured in System Definition > System Properties after installation.

Core Configuration​

PropertyDefaultDescription
API Key(empty)ReversingLabs API key used for authentication to ReversingLabs Spectra Analyze.
API URLhttps://a1000.reversinglabs.comSpectra Analyze API endpoint URL.
Auto UploadtrueAutomatically upload unknown files for analysis.
Max Upload Size (MB)500Maximum file size for upload.
Polling Interval (seconds)5Base polling tick. Actual intervals follow a tiered exponential backoff strategy — see note below.
Max Polling Attempts20Max polling retries (up to a 60-minute monitoring window using the tiered backoff strategy).
note

File upload status polling uses a tiered exponential backoff strategy with a 5-second polling tick: intervals start short and progressively lengthen across the 20 attempts, covering a maximum monitoring window of 60 minutes.

Feature Toggles​

PropertyDefaultDescription
Update Observable NotestrueWrite analysis notes to observable.
Update Observable FindingstrueWrite detailed findings to observable.
Update Observable Threat LookuptrueCreate threat lookup records.
Update Child Observable EnrichmenttrueEnrich child observables (cascade).
Update Child Observable DNStrueCreate DNS-based child observables from domain enrichment.
Update Child Observable Extracted FilesfalseCreate observables for files extracted during analysis.

API Coverage & Enrichment Examples​

File Hash Enrichment​

When you enrich a file hash (MD5, SHA-1, SHA-256, or other hash type), the integration returns:

  • Classification — MALICIOUS, SUSPICIOUS, GOODWARE, or UNKNOWN
  • Threat Score — 0–100 severity rating
  • File Metadata — Type, size, build date, compiler information
  • Threat Names — Detected malware family names
  • Digital Signatures — Certificate details and signer information
  • Related Indicators — Associated domains, IPs, extracted files

Example enrichment result:

Observable: 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (SHA-256)
├── Threat Score: 85
├── Verdict: MALICIOUS
├── Classification: Malware
├── Threat Names: Trojan.Generic, Ransomware.Lock
├── File Type: PE32 executable (GUI) Intel 80386
├── File Size: 1,234,567 bytes
├── Analysis Details: "This is a known ransomware variant..."
└── Tags: rl:classification=MALICIOUS

Domain Enrichment​

Domain enrichment provides:

  • DNS Records — A, AAAA, MX, NS, CNAME records
  • Associated IPs — Current and historical IP resolutions (auto-created as child observables)
  • Threat Status — Classification and risk rating
  • Whois Information — Registrant details, registration date

Example:

Domain: malicious.net
├── Threat Score: 90
├── Verdict: MALICIOUS
├── A Records: 93.184.216.34, 93.184.216.35
├── MX Records: mail.malicious.net
├── Child Observables Created: 2 IP addresses
└── Associated Threats: Trojan.Generic, Adware.Minor

IP Address Enrichment​

IP enrichment reveals:

  • Geolocation — ASN and network information
  • Reverse DNS — Associated domains
  • Historical Data — Previous domain resolutions
  • Threat Reputation — Known malicious activity classification

URL Enrichment​

URL enrichment extracts:

  • Domain & Host — Parsed from the URL
  • Threat Classification — URL-level threat status
  • Content Analysis — Detected threats in page content
  • Redirects — Chained URL relationships

File Upload (Binary Analysis)​

File upload adds:

  • Asynchronous Processing — Files queued and processed in background
  • Status Tracking — Polling queue shows pending → processing → completed
  • Analysis Results — Classification, threat score, extracted indicators
  • Progress Monitoring — Navigate to ReversingLabs Polling Queues to check status

Testing & Validation​

Quick Test​

  1. Navigate to Security Incident Response > Incidents
  2. Open an existing incident or create a new test incident
  3. Add an observable using one of the following known test values:
TypeTest Value
MD5 Hashe4d909c290d0fb1ca68ffaddb3940226
Domainmalicious.net (if known in RL database)
IP Address8.8.8.8
URLhttps://example.com
  1. The observable should auto-enrich within seconds, or click the ReversingLabs Enrichment button

Expected Output​

Successful enrichment populates the observable record with:

  • Threat Score — Numeric value (0–100)
  • Verdict — Clean, Suspicious, Malicious, or Unknown
  • Analysis Details — File type, metadata, and notes
  • Security Tags — ReversingLabs tags that are visible on the record and searchable within ServiceNow, for example rl:classification=MALICIOUS
  • Integration Log — An info level entry in ReversingLabs Integration Logs

Troubleshooting​

Enrichment Button Not Visible​

Symptom: The ReversingLabs Enrichment button does not appear on the observable form.

Causes:

  1. Missing user role — user must have x_rligh_revers_0.user
  2. Observable is not a supported type (e.g., File Name, Registry Key)
  3. UI Action condition not met

Solutions:

  1. Verify the user has x_rligh_revers_0.user assigned
  2. Navigate to User Administration > Users, open the user record, check the Roles tab
  3. Confirm the observable type is one of: HASH, IP_ADDRESS, DOMAIN_NAME, URL, FILE

Authentication Failed / Invalid API Key​

Symptom: Enrichment fails with an authentication error. Integration logs show "401 Unauthorized" or "Invalid API key".

Causes:

  1. API key is incorrect or expired
  2. API key has leading or trailing spaces from copy-paste
  3. API key doesn't match the configured endpoint

Solutions:

  1. Re-enter your API key by running the 02_START_RL_SERVICES.js script again with the correct key, or manually set x_rligh_revers_0.reversinglabs_api_key in System Properties
  2. Verify x_rligh_revers_0.reversinglabs_api_url matches your Spectra Analyze instance
  3. If credentials are older than 12 months, contact support@reversinglabs.com

Connection Timeout / Unable to Connect​

Symptom: Enrichment fails with a network error. Observables stay in "pending" state.

Causes:

  1. Outbound HTTPS blocked by firewall or proxy
  2. DNS resolution failure
  3. ReversingLabs API temporarily unavailable

Solutions:

  1. Verify outbound HTTPS (port 443) access from ServiceNow to a1000.reversinglabs.com
  2. If behind a corporate proxy, configure proxy settings or whitelist *.reversinglabs.com from TLS inspection
  3. Check ReversingLabs status at https://status.reversinglabs.com
  4. Review integration logs at ReversingLabs Integration Logs

File Upload Fails​

Symptom: Polling queue records show failed status with error message.

Causes:

  1. File exceeds the maximum upload size (default 500 MB)
  2. Network timeout during multipart upload
  3. Unsupported file format

Solutions:

  1. Check error_message field on the polling queue record
  2. Verify the file size is under the configured limit (x_rligh_revers_0.reversinglabs_upload_max_size_mb)
  3. Adjust x_rligh_revers_0.reversinglabs_polling_interval_seconds if timing out
  4. Ensure the global script include is installed (run Step 1 again if needed)

Empty Results from Known Malicious IOCs​

Symptom: Enrichment runs successfully but returns no threat data.

Causes:

  1. IOC not in ReversingLabs database (not yet analyzed by Spectra Analyze)
  2. IOC is legitimate or clean (classification: GOODWARE)
  3. API quota exhausted

Solutions:

  1. Try a known malicious hash for testing
  2. Check API quota status — contact your ReversingLabs account team
  3. Enable Spectra Intelligence integration for broader coverage
  4. Review integration logs for throttling or rate limit errors

Slow Enrichment​

Symptom: Enrichment takes longer than expected.

Solutions:

  1. Check network latency: Verify connectivity from ServiceNow to a1000.reversinglabs.com
  2. Check API status at https://status.reversinglabs.com
  3. Reduce queue congestion: Sequential processing means many pending items take time
  4. Verify x_rligh_revers_0.reversinglabs_polling_interval_seconds is set correctly

See also​