Associating finding with a configuration item using lookup rules

  • Release version: Xanadu
  • Updated July 31, 2025
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Associating finding with a configuration item using lookup rules

    Unified Security Exposure Management in ServiceNow uses lookup rules to associate imported third-party exposure findings with Configuration Items (CIs) in the Configuration Management Database (CMDB). Because findings from external scanners like Qualys, Tenable, and Rapid7 often lack direct CI references, lookup rules apply matching logic to link findings accurately to existing CIs. This association is vital for precise asset identification and effective remediation of security exposures.

    Show full answer Show less

    Key Features

    • Domain Separation and Source Specificity: Lookup rules are domain-separated and specific to each scanner source, allowing multiple deployments per source.
    • Shared Across Deployments: Rules are shared across all deployments for a given scanner source integration; changes affect all deployments.
    • Three-Step Matching Process:
      • Initial Lookup: Matches third-party asset IDs in the Discovered Items list to populate the Configuration Item field.
      • Matching Process: Uses other asset details if no ID match exists, mapping findings to the correct CI.
      • Placeholder CI Creation: Creates an Unmatched CI placeholder if no match is found.
    • Rule Execution Logic: Rules run in ascending priority order, stopping at the first single CI match. If the matched CI is a low-level networking element, its parent CI is returned to ensure meaningful associations.
    • Excluding CI Classes: A system property allows exclusion of specific CI classes from matching to refine accuracy.
    • Integration-Specific Rules: Each scanner integration plugin (Qualys, Rapid7, Tenable.io, Tenable.sc) has tailored lookup rules matching on attributes like HOST ID, FQDN, MacAddress, IP, and others, optimized per source.
    • Managing Lookup Rules Safely: Custom or modified rules should be tested to avoid performance degradation. It is recommended to deactivate rather than delete rules to prevent data loss.
    • Reapplying Updated Rules: Updated lookup rules can be reapplied to unmatched or previously matched discovered items to refresh CI associations in findings and detections.

    Managing Unmatched and Unclassed Items

    • Unmatched CIs: Assets without a CMDB match appear under Discovered Items with Class set as Unmatched CI, allowing you to track and manage them.
    • Unclassed Hardware: Assets that fail to categorize using lookup rules are labeled as unclassed hardware, indicating the need for further classification or CMDB updates.
    • Preventing Duplicate and Orphan Records: Best practices and steps exist to avoid duplicate or orphaned records after running lookup rules, preserving CMDB integrity.

    Practical Outcomes for ServiceNow Customers

    By leveraging lookup rules, ServiceNow customers can ensure that exposure findings from various vulnerability scanners are accurately tied to relevant CIs in their CMDB. This association enhances visibility into asset vulnerabilities, streamlines remediation workflows, and reduces manual data reconciliation. Maintaining and updating lookup rules carefully helps avoid performance issues and data inconsistencies, ultimately enabling more effective security exposure management within the ServiceNow platform.

    Unified Security Exposure Management uses lookup rules to associate imported third-party exposure findings with configuration items (CIs) in the Configuration Management Database (CMDB). These rules match asset data to existing CIs, enabling accurate remediation.

    Findings imported from external scanners such as Qualys, Tenable, and Rapid7 often lack direct CI references. Lookup rules bridge this gap by applying matching logic to map findings to CIs in the CMDB.

    Characteristics of lookup rules

    • Domain separation and source specificity: Lookup rules can be domain-separated and are specific to each source, enabling multiple deployments according to source.
    • Shared across deployments: Rules are shared across all deployments of a scanner source integration. Any changes or deletions affect all deployments.

    How lookup rules work

    The lookup rules follow a three-step process.
    1. Initial lookup: When assets or findings are imported, the system first checks the Discovered Items list using third-party IDs. If an asset ID matches, it populates the Configuration Item field in the finding record.
    2. Matching process: If no asset ID match exists, the rules use other asset details to identify the correct CI. You can view mappings in the Discovered Items list.
    3. Placeholder CI creation: If no match is found, a placeholder CI is created and marked as an Unmatched CI.
      • Matching starts with a vendor ID lookup across source, source_instance, and vendor ID.
      • The rules execute in ascending order and stop when a single CI match is found.
      • If the matched CI is a low-level networking element (for example, dscy_switchport, cmdb_ci_network_adapter, cmdb_ci_nic, or cmdb_ci_ip_address), the parent CI is returned.
    4. Rule execution: Rules run from lowest to highest priority until a single match is found. If multiple matches occur, only the first is used.

    Special considerations

    • Excluding CI classes: A system property enables excluding certain CI classes from matching. See Ignore CI classes for upgrade information and instructions on setting the property.
    • Parent CI return: To avoid matching low-level networking elements, the parent CI is returned if the matched CI is a network adapter, Network Interface Cards (NICs), or IP address.

    Lookup rules for specific integrations

    Each integration plugin includes its own set of rules:

    • Qualys: Qualys HOST ID, FQDN, NetBIOS, DNS, IP
    • Rapid7: MacAddress, FQDN, HostName, IP
    • Tenable.io: FQDN, NETBIOS, HOSTNAME, MacAddress, DNS
    • Tenable.sc: MacAddress, FQDN, NETBIOS
      Note:
      Tenable.io lookup rules prioritize and populate the non-empty network interface values (FQDN, IPV4, and MacAddress) over the regular FQDN, IPV4, and MacAddress values for a discovered item. When these network interface values are empty, the regular FQDN, IPV4, and MacAddress values are populated for a discovered item.
    Managing Lookup rules
    • Test custom rules: Test custom or modified lookup rules to avoid performance issues.
    • Deactivate instead of delete: Deactivate rules rather than deleting them to avoid data loss.
    If rules aren’t carefully constructed, importing exposure findings data can be taxing on an instance and performance issues with resources can occur. The logic used to iterate through and perform matching within the CMDB can result in lengthy processing times. To avoid any potential degradation of resources or performance complications, test any custom-written lookup rules or modifications to pre-defined Lookup Rules. See Steps to help prevent duplicate or orphaned records after running lookup rules for more information on helping prevent duplicate orphan records, deleting data, and cleaning up data.
    Note:
    For information on CI matching, see KB0998706.

    Reapplying updated lookup rules

    After updating rules, use Reapply to rerun them on unmatched or previously matched discovered items. This updates CI information in findings and detections. You can also run lookup rules on specific selected discovered items. For more information, see Reapply lookup rules on selected discovered items.

    Unmatched CIs and unclassed hardware

    • Unmatched CIs: CIs without a match in the CMDB are listed under Discovered Items with Class set to Unmatched CI.
      Note:
      Each discovered item includes a Class field. If a CI is unmatched, this field is set to Unmatched CI.
    • Unclassed hardware: Assets that can’t be categorized by lookup rules are referred to as unclassed hardware.

    By effectively managing lookup rules, Unified Security Exposure Management can help with identifying accurate ownership and streamlining remediation.