Associating finding with a configuration item using lookup rules

  • Release version: Zurich
  • 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 (from scanners like Qualys, Tenable, and Rapid7) with configuration items (CIs) in the Configuration Management Database (CMDB). Since these findings often lack direct CI references, lookup rules apply matching logic based on asset data to accurately map findings to existing CIs. This association enables precise remediation and ownership identification.

    Show full answer Show less

    How Lookup Rules Work

    • Initial Lookup: The system first checks the Discovered Items list for third-party asset IDs to populate the Configuration Item field in the finding.
    • Matching Process: If no asset ID match is found, other asset attributes are used to find the correct CI. Mappings can be reviewed in the Discovered Items list.
    • Placeholder CI Creation: If no match is found, a placeholder CI labeled as an Unmatched CI is created.
    • Rules execute sequentially by priority until a single CI match is identified; if the match is a low-level networking element (e.g., network adapter or IP address), the parent CI is used instead.

    Key Features and Special Considerations

    • Domain Separation and Source Specificity: Lookup rules are domain-separated and specific to each scanner source, supporting multiple deployments per source.
    • Shared Across Deployments: Changes to rules apply across all deployments of the same scanner source integration.
    • Excluding CI Classes: Certain CI classes can be excluded from matching via system properties to optimize results.
    • Lookup Rules per Integration: Each scanner integration includes specific matching attributes, for example:
      • Qualys: HOST ID, FQDN, NetBIOS, DNS, IP
      • Rapid7: MacAddress, FQDN, HostName, IP
      • Tenable.io: FQDN, NETBIOS, HOSTNAME, MacAddress, DNS (prioritizes network interface values)
      • Tenable.sc: MacAddress, FQDN, NETBIOS

    Managing Lookup Rules and Data Integrity

    • Testing Custom Rules: Always test custom or modified lookup rules before deployment to prevent performance degradation and resource issues.
    • Deactivating vs. Deleting: Deactivate rules rather than delete to avoid data loss and maintain system stability.
    • Reapplying Rules: After updates, use the Reapply function to rerun lookup rules on unmatched or previously matched discovered items to refresh CI associations.
    • Preventing Duplicate or Orphaned Records: Follow recommended steps after running lookup rules to avoid duplicates and orphaned CIs, ensuring CMDB data quality.

    Handling Unmatched and Unclassed Items

    • Unmatched CIs: Assets that cannot be matched are listed under Discovered Items with the Class set to "Unmatched CI".
    • Unclassed Hardware: Assets that cannot be categorized by lookup rules during import remain unclassed, highlighting the need for ongoing rule refinement.

    Effectively managing these lookup rules empowers ServiceNow customers to maintain accurate CMDB records, streamline exposure remediation, and enhance asset ownership clarity within their security operations.

    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.