File-Based Discovery Deep Dive - Support and Troubleshooting

File-Based Discovery Deep Dive Summary .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } File-Based Discovery (FBD) Technical Reference Guide Complete technical documentation for ServiceNow File-Based Discovery implementation, configuration, and troubleshooting

Table of Contents Phase 0: Setup & Activation Phase 1: Probe Execution Phase 2: Sensor Logic Phase 3: FileBasedDiscoveryAPI Phase 4: Configuration & Properties Phase 5: Troubleshooting Phase 0: Setup & Activation Goal: Activate required FBD plugins and verify prerequisites Prerequisites ServiceNow instance with SAM (Software Asset Management) module MID Server(s) deployed and active Windows 7+ or Unix/Linux target systems Local administrator or equivalent privileges PowerShell 3.0+ (Windows) Standard shell access (Unix/Linux) Step 1: Activate FBD Plugins Navigate to System Applications > Plugins Search for File-based Discovery Activate the following plugins: Plugin Name Plugin ID Status File-based Discovery com.snc.discovery.file_based_discovery Active Software Asset Management - File Signature Normalization com.snc.file_signature_normalization Active Software Asset Management Professional com.snc.samp Active ✓ Phase 0 Complete: FBD plugins activated. Proceed to Phase 1. Phase 1: Probe Execution Goal: Collect file metadata from Windows and Unix/Linux targets The probe executes on target systems to discover files and extract metadata. Separate probe implementations exist for Windows (PowerShell) and Unix/Linux (shell script).

1.1 Windows Probe Execution Probe Placement & Initialization MID Server places PowerShell script on target: C:\Windows\Temp\snc_fbd_probe_ .ps1 Execution parameters: Scan directories: c:\program files*|c:\windows File extensions: .exe|.dll|.jar|.aspx|.vbs|.bat Max files: 10000 Instance ID: discovery_12345 Executes via WinRM with full command path and parameters PowerShell Startup Sequence Checks PowerShell version (≥ 3.0 required) Creates temp file: C:\Windows\Temp\snc_tmp_discovery_12345.tmp Sets process priority to Idle Loads scan parameters Directory Traversal & File Collection Depth-first directory traversal with 10-second throttle sleep between directory scans to avoid target system overload.

File Size (bytes) FileVersion ProductVersion AcroRd32.exe 2048576 2023.001.12345 2023.001 Acrobat.dll 1024000 2023.001.10000 2023.001 ℹ️ Note: Files not matching specified extensions are skipped. Non-PE files omit version information. Output Format Results written to snc_tmp_discovery_12345.tmp with special markers:

| = directory marker Pipe-delimited file info: filename|size|fileVersion|productVersion # = completion message > = summary statistics Scan Completion Temp file renamed on completion:

BEFORE: C:\Windows\Temp\snc_tmp_discovery_12345.tmp (IN PROGRESS) AFTER: C:\Windows\Temp\snc_tmp_discovery_12345.result (COMPLETE) 1.2 Unix/Linux Probe Execution Goal: Collect file metadata from Unix/Linux targets using an SSH-executed shell script.

Probe Execution MID Server copies the script to the target: /tmp/snc_fbd_probe_ .sh Executes via SSH with parameters such as: Scan directories: /usr|/opt|/bin|/sbin File extensions: .so|.jar|.sh|.pl|.py Max files: 10000 Instance ID: discovery_12345 Scan Process Creates a temporary output file: /tmp/snc_tmp_discovery_12345.tmp Uses standard Unix utilities ( find , stat , file ) to: Traverse directories recursively Identify files matching configured extensions Collect metadata such as file name, size, type, and version (when available) Output Format Results are written to the temporary file using markers:

| = directory marker filename|size|version|product # = completion marker > = summary statistics Example:

java|143360|17.0.8|OpenJDK libssl.so|684032|3.0.8|OpenSSL ℹ️ Note: Unlike Windows executables, Unix/Linux files often do not contain embedded version information, so version fields may be empty. Scan Completion The output file is renamed when the scan finishes:

BEFORE: /tmp/snc_tmp_discovery_12345.tmp AFTER: /tmp/snc_tmp_discovery_12345.result The MID Server retrieves the result file and passes it to the File-Based Discovery sensor for processing.

Phase 2: Sensor Logic Universal Sensor Logic (All Platforms) The following processing steps apply identically to Windows, Unix, and Linux:

processJSON() — Main Entry Point Receives file discovery data from probe/MID Server (any platform) Normalizes and unpacks directory-mapped files into flat array Handles wildcard file paths separately Checks discovery status: STARTED → RUNNING → FINISHED Logs messages uniformly across all systems Orchestrates file identification and reconciliation pipeline Key Processing Steps Step Description Platform Scope File Data Unpacking Transforms discovered files into flat objects with name, path, size, version All File Filtering Removes files matching exclusion extensions ( swid_tags_software_exclusion_list ) All Software Identification Calls FileBasedDiscoveryAPI.identifyFilePackages() to match files against known signatures All ℹ️ Key Point: FBD sensor logic is universal across all platforms . Probes differ by platform, but sensor processing is identical. ✓ Phase 2 Complete: All files processed uniformly with optional SAM enrichment. Proceed to Phase 3. Phase 3: FileBasedDiscoveryAPI Goal: Match files against signature database and populate output tables Data Flow Discovered Files → FileBasedDiscoveryAPI.identifyFilePackages() → File Signature Matching (samp_file_map: Rank 1 → Rank 0) → Publisher/Product Identification (samp_file_set enrichment) → cmdb_file_information → cmdb_sam_sw_install

SAM Output Tables Table Content Platform cmdb_file_information File metadata and fingerprints from FBD All cmdb_sam_sw_install Software Installation records for discovered packages All ✓ Phase 3 Complete: API processed signatures and populated output tables. Configuration & Properties Goal: Configure FBD scan parameters and system properties Configuration Location All > Discovery Definition > Configuration Console

Key Configuration Items Enable/Disable FBD: Master on/off switch Scan Directories: Paths to scan (e.g., c:\program files*, /opt, /usr/local) File Extensions: Extensions to include (.exe, .dll, .jar, .so) Max Files: Maximum files per scan (default: 100000) Frequency: Scan frequency (monthly recommended) Performance Tuning: Sleep time and throttle settings SWID Scanning: Enable/disable SWID tag collection Exclusions: Exclude paths and file patterns Troubleshooting Goal: Diagnose and resolve common FBD issues Issue 1: FBD is Disabled via System Property Problem: System property enabled=false Symptoms:

FBD probes not running No file data collected Discovery logs show FBD disabled messages Resolution:

Navigate to Configuration Console Verify glide.discovery.file_discovery.enabled = true Save and test Issue 2: CDS Content Has Not Been Synched Problem: Timestamps show 1970-01-01 in samp_file_* records Symptoms:

File signatures not matching Incorrect software identification No SAM output generated Resolution:

Navigate to All > Discovery Definition > CDS Client Schedule Select cds_client_schedule record Click Execute Now Wait for sync completion Re-run FBD discovery Issue 3: Interval Has Not Passed Since Last Execution Problem: Scheduled frequency not yet expired Symptoms:

Discovery skipping scheduled FBD scans Scheduled probes not running Stale file data in CMDB Resolution:

Navigate to Configuration Console Adjust glide.discovery.file_discovery.frequency property Save changes Re-run discovery manually or wait for next scheduled interval For questions or updates, contact ServiceNow support team