Qualys CMDB Sync User Guide
Qualys CMDB Sync User Guide
User Guide
Version 2.5.0
February 2, 2023
Verity Confidential
Copyright 2022-2023 by Qualys, Inc. All Rights Reserved.
Qualys and the Qualys logo are registered trademarks of Qualys, Inc. All other trademarks
are the property of their respective owners.
Qualys, Inc.
919 E Hillsdale Blvd
4th Floor
Foster City, CA 94404
1 (650) 801 6100
Table of Contents
About this guide................................................................................................ 5
About Qualys ........................................................................................................................... 5
Qualys Support ........................................................................................................................ 5
Syncing ..............................................................................................................28
Sync Queue ............................................................................................................................ 28
Download: Qualys to ServiceNow ................................................................................. 28
Upload: ServiceNow to Qualys ...................................................................................... 29
Approve Qualys Assets ......................................................................................................... 29
Failed Qualys Assets ............................................................................................................. 32
View Reports....................................................................................................43
Customize Overview Page .................................................................................................... 46
Verity Confidential
Add a Report .................................................................................................................... 46
Remove a Report ............................................................................................................. 47
Refresh Overview page .......................................................................................................... 47
Migration Support............................................................................................71
Why Migration Needed? ................................................................................................. 71
Get Started ....................................................................................................................... 71
About Qualys
Qualys, Inc. (NASDAQ: QLYS) is a pioneer and leading provider of cloud-based security and
compliance solutions. The Qualys Cloud Platform and its integrated apps help businesses
simplify security operations and lower the cost of compliance by delivering critical
security intelligence on demand and automating the full spectrum of auditing,
compliance and protection for IT systems and web applications.
Founded in 1999, Qualys has established strategic partnerships with leading managed
service providers and consulting organizations including Accenture, BT, Cognizant
Technology Solutions, Deutsche Telekom, Fujitsu, HCL, HP Enterprise, IBM, Infosys, NTT,
Optiv, SecureWorks, Tata Communications, Verizon and Wipro. The company is also a
founding member of the Cloud Security Alliance (CSA). For more information, please visit
www.qualys.com
Qualys Support
Qualys is committed to providing you with the most thorough support. Through online
documentation, telephone help, and direct email support, Qualys ensures that your
questions will be answered in the fastest time possible. We support you 7 days a week,
24 hours a day. Access support information at www.qualys.com/support/
5
Qualys CMDB Sync App
Welcome to Qualys CMDB Sync App 2.5
Key Features
- Asset information is automatically enriched with additional context such as lifecycle
date and support stage, license category
- For assets that already exist in both, asset metadata can be synchronized
- Optionally, asset information is staged for user approval before being written to CMDB
- Support for multiple Qualys accounts/API sources
- Synchronization schedules can be configured and saved
- Preconfigured table transform maps for open ports, assets, network interfaces, software,
processors and volumes
- Preconfigured reports
- Preconfigured CI Class Manager that pre-populates the source-destination field
mappings and also allows you to create your own mappings for CI Class.
- Support for Cloud Data (metadata) synchronization for Amazon Web Services, Microsoft
Azure, Google Cloud Platform cloud providers till staging area.
- The SSL certificate information can be synced to ServiceNow for the assets imported
from Qualys.
What’s New
Here's what's new in Qualys CMDB Sync App 2.5.0!
- WhoIs
- Domain
- Subdomain
- ASN
- ISP
- The SSL certificate information can be synced to ServiceNow for the assets imported
from Qualys.
6
Qualys CMDB Sync App
Welcome to Qualys CMDB Sync App 2.5
7
Qualys CMDB Sync App
Welcome to Qualys CMDB Sync App 2.5
Pre-requisites
You must have a valid Qualys account subscription with API Access and access to
following modules:
- Qualys Subscription with CyberSecurity Asset Management (Qualys to ServiceNow Sync)
- Asset Inventory CMDB Sync enabled within your Qualys subscription (Qualys to
ServiceNow Sync)
- Vulnerability Management (ServiceNow to Qualys Sync)
- To sync from ServiceNow to Qualys, you need a Qualys account with a Manager role.
- The user's role must have the "Update Asset" permission for the CSAM module.
(ServiceNow to Qualys Sync - Business Information Sync)
- Ensure that the "Enable ServiceNow integration" option from BO is enabled to allow
business metadata sync in ServiceNow to Qualys flow.
- Qualys Certificate View subscription is needed for syncing SSL certificates from Qualys to
ServiceNow.
- For ServiceNow to Qualys sync user requires specific tagging permission: Create User
Tag, Edit User Tag, Delete User Tag, and Modify Dynamic Tag Rules.
8
Qualys CMDB Sync App
Get Started
Get Started
Here we’ll help you with the initial configuration and setup needed to get started.
Quick Steps
Install the App - You’ll get the app from the ServiceNow app store.
Add API Source- Provide the API Source details and use Test Connection to know if the
connection between ServiceNow and the defined source is working fine.
Create Schedules - Provide details to create a schedule. Once a schedule is successfully
created, the sync between the source and CMDB gets working as per the schedule.
Update Properties - The Properties have pre-defined values, however you can always
update a property to better suit your needs.
9
Qualys CMDB Sync App
Get Started
Select Sync Software Catalog option to enable software sync to staging tables.
10
Qualys CMDB Sync App
Get Started
By default, this check box is disabled. Only after you enable the Sync Software Catalog
check box, the Sync Software Catalog to CMDB check box is displayed. Use this check box
to enable software sync and add the software data to CMDB tables. Once the sync cycle is
complete, the sync details are populated in Last Sync Timestamp, Last Sync Key and in
Sync notes fields.
Click Submit to create the API source.
Then, after configuring and saving the API source, choose the record you just created from
the API source list, open the record and click Test Connection.
Sync Certificates
Using this option, you can sync certificates from Qualys to ServiceNow.
Click Sync Certificate. You can see the Sync Certificates checkbox. Enable the Sync
Certificates checkbox If you want to sync Certificates from Qualys.
You can also set up a relationship between CI records and certificates using the relation
type listed in the Relation Type dropdown.
Note: By default, the relation type is Owns::Owned by.
Click Submit to create the API source.
After configuring and saving the API source, choose the record created from the API source
list, open it, and click Test Connection.
11
Qualys CMDB Sync App
Get Started
12
Qualys CMDB Sync App
Get Started
Create Schedules
You need to set up at least one schedule. You may eventually want many more. Once a
schedule is successfully created, the sync between the source and CMDB gets working as
per the defined schedule.
13
Qualys CMDB Sync App
Get Started
Exclude Unmanaged Assets - Enable this checkbox if you want to exclude unmanaged
assets or do not want to sync unmanaged assets from Qualys to ServiceNow.
Qualys to ServiceNow Sync - Select the information we should fetch for each asset: Sync
Ports Info, Sync Volumes Info, Sync Network Interfaces Info, Sync Software Info.
For initial sync from Qualys to ServiceNow, we recommend that you plan your schedules
at an interval of every fifteen minutes.
Once you configure your selections, click Submit to create the schedule.
Note: The Meta Info fields and few other blank fields such as Last Run Timestamp, Last
Fetched Host Id are populated with information only after the schedule is executed.
14
Qualys CMDB Sync App
Get Started
15
Qualys CMDB Sync App
Get Started
Name - Provide a unique name for your schedule that helps you identify your schedule.
Active - Select to enable and activate the schedule you create. If you want to activate a
schedule sometime later, you can disable this option.
API Source - Select the API source.
Sync Direction - Select ServiceNow to Qualys.
Run, Starting, Repeat Interval - Tell us the frequency of the schedule to be executed. For
example, we could configure to execute schedule only on-demand.
ServiceNow to Qualys Sync - You can sync the IPs and Asset Metadata from ServiceNow
to Qualys.
For initial sync from ServiceNow to Qualys, we recommend that you plan your schedules
at an interval of every ten minutes.
Asset Scope: - Define the scope of assets to be synced.
The Table and Query components allow you to select the asset metadata table as per
your requirement.
Filter the query by choosing from the default fields to sync asset metadata to Qualys.
16
Qualys CMDB Sync App
Get Started
You can sync business information along with asset metadata to Qualys then enable the
Sync Business Information to Qualys checkbox.
Note: If you do not enable the checkbox then the asset metadata will not get synced. Only
the asset with new IP addresses will get synced to Qualys.
Asset Metadata Attributes: Unlock the Asset Metadata Attributes option by clicking the
unlock button > Click Add/Remove multiple option.
A new pop-up window appears, and you can select the attributes from the list. Use Add
Filter and Run Filter options to isolate the records > click Save > Click the lock button to
lock your selected attributes.
17
Qualys CMDB Sync App
Get Started
All of the selected attributes from the list can sync asset metadata from ServiceNow to
Qualys.
Appendix to view the mapping of the fields for asset and business application metadata
Business Application Table: Select the table for business applications or services to get
sync from ServiceNow
- Business applications: Use to sync the CMDB configuration item application data.
A new pop-up window appears, and you can select the attributes from the list. Use Add
Filter and Run Filter options to isolate the records > click Save > Click the lock button to
lock your selected attributes.
All of the selected attributes for the business applications or services can get synced from
ServiceNow to Qualys.
18
Qualys CMDB Sync App
Get Started
Note: For Business Metadata sync, if CI is present in Qualys, then it must be synced into
ServiceNow and transformed to CMDB tables at least once. That CI will be associated
with a Qualys Asset ID, and it will be used to sync Business Metadata from ServiceNow to
Qualys.
Note: For Asset Metadata and Business Applications, 'created' and 'last updated' fields are
mandatory for asset metadata sync and should not be removed; if these fields are
removed, API calls to sync data will fail.
If Sync Business Information to Qualys is enabled, you can configure the application to
create dynamic tags for asset/business metadata attributes.
To configure Dynamic Tagging for asset/business metadata attributes, navigate to
Configuration > Dynamic Tagging Configuration.
19
Qualys CMDB Sync App
Get Started
20
Qualys CMDB Sync App
Get Started
Enter Parent Tag Name - Use this option to provide and set the name of your parent tag.
The Select Tag will appear on the page if you select the “Use Existing Tag” option from the
Parent Tag Creation field. It will make it easier for you to choose the appropriate tag.
Select Tag - Use this option to select an existing tag. Select any existing tag from the Asset
Tag List by using the Search button.
Note: You can select the existing tag as a parent tag to create dynamic tags for the
business metadata. If a parent tag doesn't exist in the Qualys Subscription, the application
will create a new static tag with the same name.
Save - Click save to save your parent tag configuration.
Once the tags for the attributes have created, the business metadata will get synced.
When the business metadata get synced, Qualys automatically generates the tags for the
asset's attributes in the backend.
You can select or deselect attributes from the attribute list to create the tag according to
your preferences.
Note: If you don't want to tag to be created for any attribute, then make that attribute
active false.
21
Qualys CMDB Sync App
Get Started
Attribute - This field shows the attribute name and will be similar to the parent tag name
e.g. 'Department'
Active - Select the checkbox to activate the dynamic tag for the by default selected
attribute.
Use Parent Tag - Select the checkbox to appear the new options on the page - It will help
you to create a new tag or select any existing parent tag.
Parent Tag type - Use this option to create a new tag or select any existing parent tag.
Selected Parent Tag - Use this option to select any existing parent tag. Use the Search
button to find and select any existing parent tag from the Asset Tag List.
22
Qualys CMDB Sync App
Get Started
The Parent Tag Name will appear on the page if you select the “Create New Tag” option
from the Parent Tag Type field. It will make it easier for you to give the appropriate name
to your tag.
Parent Tag Name - Use this option to provide and set the name of your parent tag.
Once you enable the Tag Prefix checkbox then Tag Prefix Value text-box will appear on
the page.
Tag Prefix - Select the checkbox and enable the tag prefix to add a prefix to your tag.
Tag Prefix Value - Use this field to enter your tag prefix value.
The prefix will be appended to that specific attribute tag once you enter it.
Sample Tag Name - This text box displays the details of your attribute tag.
Update - Click update to update your newly created parent tag attribute configuration.
23
Qualys CMDB Sync App
Get Started
Tracking Method - Choose the tracking method from IP, DNS, or NETBIOS for assets when
syncing from ServiceNow to Qualys.
Assign Tag/Group (Optional) - We modified this functionality by adding a dropdown that
includes Dynamic Asset Group, Dynamic Asset Tag, Static Asset Group, and Static Asset
Tag.
When you select Dynamic Asset Group from the dropdown, an empty text box appears,
which you can use to create the asset group on the runtime to sync the assets or CI with
the Qualys.
When you select the Dynamic Asset Tag, an empty text box appears, which you can use to
create a dynamic asset tag on the runtime to sync the assets or CI with the Qualys.
- To create the dynamic asset group name or tag name, a plain string and attributes name
can be used. The attribute name can be used in format ${attribute name} e.g.,
${environment}
24
Qualys CMDB Sync App
Get Started
You can use the Show available fields/columns option to add the attributes from the
target table. It is a read-only list of available attributes from the target table, where you
can copy the available attributes and paste them into the dynamic group or tag name field
using the format ${attribute_name}
- If the dynamic tag name or group name is already present in staging tables, i.e.,
x_qual5_itam_nwapp_qualys_asset_groups or x_qual5_itam_nwapp_qualys_asset_tags -
in that case, the Service graph connector will not initiate to create a call for another
duplicate group or tag name. Instead, it will fetch and use the tag id or group id of the
existing tag/group from staging tables.
When you select Static Asset Group, an empty text box appears, which you can use to
search and enter the existing qualys asset group. Click the Search button to select the
qualys asset group from the list.
When you select Static Asset Tag, an empty text box appears, which you can use to search
and enter the existing qualys asset tag. Click the Search button to select the qualys asset
tag from the list.
A Static Asset Tag or Static Asset Group. The "Static Asset Tag" or "Static Asset Group" box
will assign that tag in Qualys Cloud Platform to any assets synced from ServiceNow.
Note: The Asset Tags that belong to only the NETWORK_RANGE type are populated. All
other asset tags are ignored.
We also highly recommend adding filter conditions (at minimum IP Address) to assets to
be synced. When selecting a TABLE, ensure that the table has a column with the
"ip_address" name; otherwise, the ServiceNow > Qualys sync may not function.
VM (Vulnerability Management) is optional but enabled by default to scan the assets you
sync. We recommend that you do not disable this option. It is optional to enable PC (Policy
Compliance).
Note: If both VM and PC options are disabled, the Add IP flow will not work.
Once you configure your selections, click Submit to create the schedule.
Note: The Meta Info fields and few other blank fields such as Last Run Timestamp are
populated with information only after the schedule is executed.
25
Qualys CMDB Sync App
Get Started
Update Properties
The Asset Sync Properties have pre-populated values. However, you can always change the
values to suit your needs. To view the existing properties or update the values, go to
Qualys CMDB Sync App > Configuration > Properties.
26
Qualys CMDB Sync App
Get Started
Software catalog API page size - The number of software catalog records to be fetched in
a single API request call made by the Software Catalog Sync – Scheduled job.
Certificate API Page Download size - The maximum number of records to be fetched at
one call by the Sync certificate processor.
2) The Available list includes columns that are currently hidden. From this list, select the
column you want to display. For example, double-click the column “Updated by” and you’ll
see it moved to the Selected list.
3) Enable or disable other settings like Wrap column text, double click to edit, and so on.
4) Click OK.
You’ll start seeing the Updated by column. If for some columns, the data is not available,
the value in the column will be empty.
27
Qualys CMDB Sync App
Syncing
Syncing
Start syncing your asset information between Qualys and ServiceNow CMDB.
In Summary
Sync Queue: This is where you’ll see all jobs involved during the flow of assets between
Qualys and ServiceNow.
Approve Qualys Assets: This is where you’ll see assets that need manual approval when
auto-approval is not enabled.
Failed Qualys Assets: This is where you’ll see assets that failed to get transformed.
Sync Queue
The Sync Queue lists jobs of two types: Upload and Download. The Type column indicates
the direction of the flow of assets.
28
Qualys CMDB Sync App
Syncing
29
Qualys CMDB Sync App
Syncing
AWS
30
Qualys CMDB Sync App
Syncing
Microsoft Azure
31
Qualys CMDB Sync App
Syncing
GCP
32
Qualys CMDB Sync App
Advanced Configuration
Advanced Configuration
The Advanced Configuration tells you about various pre-defined configurations and steps
to customize them to your need. Transform Maps and Identification Engine are methods
you can use to add data to your CMDB.
In Summary
App Scheduled Jobs - List of all scheduled jobs. Update or change the frequency of
scheduled jobs as per your needs.
Transform Maps - Use transform mapping to map source and destination fields
dynamically. Use predefined Transform Maps.
Identification Engine - Use this method to define the criteria using single or multiple
attributes that uniquely identify the source assets and asset information before the assets
get approved and are added to the CMDB system.
Qualys Category - CI Class Mappings - Provides pre-defined class mappings to identify
source assets.
Application Log - All log entries related to the important activities in Qualys App.
We support the following App Scheduled Jobs. The function and frequency of execution of
each job is described. However, you can always update or change the frequency of
scheduled jobs as per your needs.
Auto Approval Processor - Checks the records to know which schedule does it belong to
and processes it further. Only records that have auto-approval enabled are processed by
the Auto Approval Processor.
33
Qualys CMDB Sync App
Advanced Configuration
Download Processor - Picks the records of type Download with Queued status from sync
queue and parses the XML. The number of records to be picked in a batch is defined by the
Size of Download batch setting in Properties section. Currently, we support three
download processors that work in parallel to fasten the process.
Fetch Qualys Asset Groups Schedule - By default, this schedule is executed once daily.
Once executed, it syncs all of the Asset Groups in Qualys Cloud Platform for use within
the App. You may run this more than once a day if you generate Asset Groups in Qualys
Cloud Platform frequently.
Fetch Qualys Asset Tags Schedule - By default, this schedule is executed once daily. Once
executed, it syncs all of the Asset Tags in Qualys Cloud Platform for use within the App.
You may run this more than once a day if you generate Asset Tags in Qualys Cloud
Platform frequently.
Migration 1.x - By default, this job is deactivated. The purpose of this job is only for
migration of approved assets that belong to Computer Extended table and need to be in
production tables. To know more about the complete migration process, refer to Migration
Support.
Qualys Sync Queue Cleanup Job - Clears the Sync Queue records with 'SUCCESS' status
(older than 30 days) and records with 'ERROR' status (older than 60 days) on daily
schedule.
Qualys Terminate Schedule Logs - Maintains a log of the transactions that are
terminated due to exceeding the time required to execute the transaction.
Software Catalog Sync - This schedule fetches Software Catalog records from Qualys to
ServiceNow. By default, this schedule is executed every 4 hours. Once executed, it syncs
all the Software Catalog records from Qualys Cloud Platform. You may run this more than
the default frequency (4 hours) if Software Catalog details get updated in Qualys Cloud
Platform frequently.
Uploader - Picks the records of type Upload with Queued status from Sync Queue and
sends it to Qualys.
Sync Software Catalog - This can sync the software catalog details separately using
Qualys software catalog APIs. This help in reducing the payload for asset list API.
Sync Certificate - Syncs the SSL certificate and its relationship with assets from Qualys to
ServiceNow.
34
Qualys CMDB Sync App
Advanced Configuration
Transform Maps
A transform map is a set of field maps that determine the relationships between fields in
an import set and fields in an existing ServiceNow table.
After creating a transform map, you can reuse it to map data from another import set to
the same ServiceNow table. The Transform Maps module allows an administrator to
define destinations for imported data on any ServiceNow table. Transform mapping can
be as simple as a drag and drop operation to specify linking between source fields on an
import set table and destination fields on any ServiceNow table.
Use transform mapping to map source and destination fields dynamically. You could
easily use the predefined Transform Maps or create one to suit your need.
Qualys Pre-defined Transform Map Type of Asset Information Affected
Qualys CMBD Sync OS Details Transform Map Qualys OS Details
Qualys CMBD Sync Software Instance Transform Map Software Instance
Qualys CMBD Sync Computer Transform Map Computer
Qualys CMBD Sync Network Interface Transform Network Adapter
Map
Qualys CMBD Sync Master Software Transform Map Software
Qualys CMBD Sync Hardware Details Transform Map Additional Hardware Details
35
Qualys CMDB Sync App
Advanced Configuration
Learn more
Please refer to the ServiceNow documentation to learn more about transform maps.
Identification Engine
You could opt to use Identification Engine instead of Transform Maps. Similar to
transform maps, the identification engine helps you to decide which assets should be
added to CMDB system. You can to define the criteria using single or multiple attributes
that uniquely identify the source assets and asset information before the assets get
approved and are added to the CMDB system.
Pre-requisites
- Identification Engine uses the “Configuration Management for Scoped Apps” plugin
which must be installed before you start using it. Please refer to the ServiceNow
documentation for detailed installation steps.
36
Qualys CMDB Sync App
Advanced Configuration
- Ensure that you add Qualys as Choices in the Discovery Source (column) of the
Configuration Item (cmdb_ci table). Go to System Definition > Tables and search for
Configuration Item table. In the table, open the Discovery Source column. Click New
under Choices section and add Qualys as Label and Qualys as Value and click Submit.
37
Qualys CMDB Sync App
Advanced Configuration
Classified Tables
The classified table includes the mapping of source fields with target fields that are
recommended/used by ServiceNow.
38
Qualys CMDB Sync App
Advanced Configuration
Active: The status of the mapping indicating if the current mapping is active or not. True
indicates mapping being active.
Deprecated: The status of the record if it is displayed in the table or not while creating new
rule. This is a read-only field used by application for processing purposes.
Priority: The priority decides the sequence in which the mappings should be acted upon. In
case of multiple mappings for similar fields, the mapping with lowest number gets higher
priority. For example, if there are two mappings with priority 50 and 100. The mapping
with priority 50 gets higher precedence than 100.
Rules: The rule that forms the criteria to select the assets from the source table (Qualys).
Table: The column used to hold reference to staging table on which rules conditions are
being executed
Target CI Class: The name of the destination/target table (defined by ServiceNow) on the
production environment where the data should be inserted. If you want change
destination table, you can change the target CI class for the corresponding source field.
For detailed list of field mappings for classified tables, refer to the Classified Tables.
1. Provide a name for the record you want to create. For example, Windows Server Sample
as we are creating mapping for Windows server.
2. Select the Active check box to activate the mapping you create. If the check box is clear,
it indicates that the current mapping will not be used for inserting data in production
table of ServiceNow.
3. Define the priority for the mapping. For highest precedence, use the lowest number in
priority.
4. Select the Target CI Class table from the pre-populated list. The table you choose forms
the destination table for the mapping.
5. Define the rule that would form the criteria to choose the source assets to be picked and
mapped. You could form a rule using single or multiple attributes and filters.
Click Submit to complete the mapping process.
39
Qualys CMDB Sync App
Advanced Configuration
How to identify and view related table entries in out of the box table entries
1. Open the CMDB Table Record Entry (cmdb_ci_computer.list).
2. On the top grey bar, right-click and choose Configure > Related lists from the menu.
40
Qualys CMDB Sync App
Advanced Configuration
4. Select the required column names from Available and then click the > (Add) button to
Selected check box and then click Save.
You can then view the details for the added columns in Related Links section.
Application Log
Log entries are listed under Advanced > Application Logs.
41
Qualys CMDB Sync App
Advanced Configuration
42
Qualys CMDB Sync App
View Reports
View Reports
Go to Qualys CMDB Sync App > Overview. The Overview page displays a consolidated view
of all the reports. If you view this page before syncing the assets, it may display all values
as zero.
Note: From version 1.0 onwards, the Reports option is merged in the Overview option.
Thus, you will no longer see the Reports option in the menu.
Note: From v2.3.0 onwards all these widgets - Application Categories, Application
Publishers, Database Distributors will get updated from the Additional software details
table when software catalog sync for CMDB is enabled.
When the Overview page is launched for the first time, you see a list of 10 default reports.
However, the reports can be customized based on your preference. For more information,
see, Customize Overview Page.
43
Qualys CMDB Sync App
View Reports
44
Qualys CMDB Sync App
View Reports
45
Qualys CMDB Sync App
View Reports
Add a Report
Click on Add content, the Add content pop-up appears. Select one of the following options
to add reports:
-To add Qualys Assets reports: Select Reports from the first column, Qualys Assets from the
second column and in the third column, select the required report from the displayed list.
-To add Software reports: Select Reports from the first column, Staging Master Software
from the second column and in the third column, select the required report from the
displayed list.
Once you select the required report, click one of the Add here options. The 10 Add here
options indicate different locations where you can add the report on the Overview page.
46
Qualys CMDB Sync App
View Reports
Remove a Report
To remove a report from the overview page, click on the close option. Once you delete
the report, you cannot undo the process. To add the same report again, see Add a Report.
47
Qualys CMDB Sync App
View Reports
- Synced Qualys Certificate: The Synced Qualys Certificates report lists the certificates
synced from Qualys to ServiceNow.
- Approved Qualys Certificate: The Approved Qualys Certificates report lists the
certificates transformed successfully into the CMDB tables.
- Pending Qualys Certificate: The Pending Qualys Certificate report lists the assets which
are not transformed.
- Failed Qualys Certificate: The Failed Qualys Certificate lists the number of certificates
that are not suc-cessfully transformed into the CMDB table.
- Expired Certificates: The count of expired and invalid certificates.
- Certificates Expiring in 30 Days: The count of certificates expiring between 0 to 30 days.
- Certificates Expiring in 60 Days: The count of certificates expiring between 30 to 60
days.
- Certificates Expiring in 90 Days: The count of certificates expiring between 60 to 90
days.
- Qualys Certificate By Issuer Authority: A chart that shows certificates by issuing
authority.
- Qualys Certificates By Key Length: A Pie chart that shows certificates by key length.
- Qualys Certificate Sync Queue: This shows the list of Sync Queues for certificate
download from Qualys.
- Sync Certificate Log: This lists the logs of the Sync Certificate schedule.
48
Qualys CMDB Sync App
Debugging and Troubleshooting
How to debug
In case of any unexpected application behavior one should check the application logs.
The application log has four different levels of logging: Information, Error, Warning, Debug
The application writes log entries after important transitions. For example, Schedule run,
on click of test connection to API Server [Qualys CMDB Sync App > Advanced >
Application Log]
Observed Issues
Scenario: Sometimes clicking on 'Test Connection” gives 'error' response to user.
Workaround: Check the error message.
- Try to repeat the ‘Test Connection’ a couple more times (if all input parameters are
correct then ‘success’ message will be displayed)
- One can get the error message under ‘Schedule Logs’ for related entries in schedule
record
- If no valid error is displayed (i.e. you are sure that the credentials are correct but API
reported “unauthorized”), try again after some time. If error persists, contact Qualys
Support
49
Qualys CMDB Sync App
Debugging and Troubleshooting
To verify the issue, you can to navigate to Failed Qualys Assets > Open the asset record
and see the Notes section. This section contains the detailed error response, as received
from Identification and Reconciliation API.
Scenario: Duplicate entries found in cmdb_ci_computer for assets which were synced
from ServiceNow to Qualys, scanned and then synced back from Qualys to ServiceNow
Workaround:
- If the user has added only IP address for the asset in the 'cmdb_ci_computer' table
Reason: Name is a mandatory parameter for ServiceNow IRE mechanism.
- If user added both name (any dummy name) and IP Address for the asset in
'cmdb_ci_computer' table
Reason: After scanning the asset, the name discovered during the authenticated /
unauthenticated scan and the dummy name that was provided could be different.
Note: There would be no duplicate entry in 'cmdb_ci_computer' if the name is exactly
same for the asset before sending the data from ServiceNow to SericeNow
50
Qualys CMDB Sync App
Debugging and Troubleshooting
IDENTIFICATION_RULE_FOR_RELATED_ITEM_MISSING
- This error will be logged in IRE notes if the identification rule is present, but related
entries for the target class in question are not present in the cmdb_related_entry table.
Also, it can be fixed by adding respective entries manually in the cmdb_related_entry
table for the identifier table, e.g., IP phone (cmdb_ci_ip_phone). It is user configurable.
Sample IRE notes containing the following error:
{
"error": "IDENTIFICATION_RULE_FOR_RELATED_ITEM_MISSING",
"message": "Identity Rule for table [cmdb_ci_ip_phone]
missing Related Rule for class
[x_qual5_itam_app_qualys_asset_details]"
},
51
Qualys CMDB Sync App
Debugging and Troubleshooting
1. Navigate to My company applications > installed CMDB sync app > installed Files ->
filter all the installed files by the class name 'Related Entry.' Refer to the screenshot below
2. Here, open one of the four empty entries created for the IP Phone class.
3. Update the 'Identifier' field with 'cmdb_ci_ip_phone'
4. Repeat the same steps for the rest of the three entries as well.
52
Qualys CMDB Sync App
Debugging and Troubleshooting
You can create additional dependent Containedby: contains relation with hardware
class.
53
Qualys CMDB Sync App
Debugging and Troubleshooting
Scenario: When an asset belongs to hardware and its child class (except for the
computer and its child classes) and contains volume information approved using the
identification engine, approval fails with the 'MISSING_DEPENDENCY' error pointing
cmdb_ci_file system class is logged in IRE notes.
"error": "MISSING_DEPENDENCY",
"message": "In payload no relations defined for dependent class
[cmdb_ci_file_system] that matches any containment/hosting rules:
[cmdb_ci_storage_volume >> Managed by >>
cmdb_ci_rubrik_cluster,cmdb_ci_storage_volume >> Contained by >>
cmdb_ci_computer,cmdb_ci_storage_volume >> Owned by >>
cmdb_ci_storage_cluster,cmdb_ci_storage_volume >> Hosted on >>
cmdb_ci_logical_datacenter]. Add appropriate relations in payload for
'{\"className\":\"cmdb_ci_file_system\",\"values\":
{\"size_bytes\":\"53833891\",\"discovery_source\":\"Qualys\",\"name\":\"/
\",\"provided_by\":\"3a2402ac1b328510626e6579b04bcb10\",\"free_space_byte
s\":\"47112519\"}
,\"internal_id\":\"fe69ef14f7c38910252c174f3b9fd2a3\",\"sys_object_source
_info\":{\"source_name\":\"Qualys\"},\"settings\":{},\"sys_ire_info\":{\"
ire_received_time\":\"2022-04-20 10:29:44\"},\"display_values\":{}}'"
},
MISSING_MATCHING_ATTRIBUTE
When the Target class has an identification entry with a specific attribute missing in the
payload.
Scenario: When the asset approval fails due to an IRE with an error MISSING
MATCHING ATTRIBUTE.
Workaround: We have given the following workaround for asset approval fails due to an
IRE with an error missing matching attribute.
- Navigate to CI Class Manager.
- Browse the specific target class throwing an error.
- Navigate to 'Identification Rule' Section.
- Go to sub-section 'Identifier entries'.
- Add an additional entry for the target class with,
54
Qualys CMDB Sync App
Debugging and Troubleshooting
Anticipated Issues
It is quite frequent to have error in opening/viewing attached ‘response.xml’ from sync
queue records. Those response.xmls are considered as incomplete.
List of expected failure modes
- Qualys API server is undergoing maintenance/downtime
- Qualys subscription expired
- User credentials used are incorrect
- User credentials are correct, but user has no Qualys App subscription from Qualys
Common Questions
Do you currently support the Identification and Reconciliation API for CMDB CRUD
actions?
Yes, Qualys App supports Identification and Reconciliation APIs. The goal of this API is to
maintain the integrity of the database, and to correctly identify CIs so that new records
are created only if CI is truly new to CMDB. See CMDB Identification and Reconciliation
55
Qualys CMDB Sync App
Debugging and Troubleshooting
You can change how to add data in CMDB from default Transform Map to Identification
Engine from Properties page. You also need to create CI Identifier Rule for Target table.
Can user add data to ServiceNow app from different Qualys servers?
Yes, user can add asset data from different Qualys PODs. User needs to create different
API Sources and Schedules as per Qualys servers.
The Schedules I defined pulled the data accurately till yesterday. But, today, the same
schedule is unable to fetch any assets or related data.
Check your application logs. The reason the schedules are unable to fetch assets is
because either your trial period or your subscription has expired. Contact your TAM to
extend your subscription. Once you have an active subscription, you need to activate your
API Source and the schedules will fetch the assets.
If an asset is purged from Qualys, what will its status be in ServiceNow CMDB?
The asset purged from Qualys will not automatically be purged in ServiceNow CMDB. The
asset must be manually purged from ServiceNow.
What is the difference between Computer CI Class Mapping and Qualys Category
Hardware Device CI Mappings?
The Computer CI Class Mapping is the main base table and contains the hierarchy for
assets and tables. It also has higher priority in comparison to Qualys Category Hardware
Device CI Mappings. As a result, assets to be transferred to destination tables are checked
56
Qualys CMDB Sync App
Debugging and Troubleshooting
against rules in Computer CI Class Mapping first. Only if they do not satisfy/meet any of
the rules in Computer CI Class Mapping, the Qualys Category Hardware Device CI
Mappings are used.
Application Log
After you upgrade 2.1.1 version, when the transformation mode set to 'Transform Map'
and if you have assets in the staging area, on approval of such assets, the assets are
transformed to the correct CI Classes. But, the application log may not reflect this
correctly.
For example: Asset abcd (AssetID) Manually Approved using Transform Map updated in
x_qual5_itam_app_computers_extended.
Although the asset has been correctly transformed to the CI Class, the application log
incorrectly states name of computer extended table instead of the CI class name where
the asset has been correctly moved.
Resolution: Ignore the application log in such cases.
57
Qualys CMDB Sync App
Debugging and Troubleshooting
- IRE version needs name and version of the data being transformed. Name being
mandatory parameter for transformation. If name is missing for asset, then the asset may
not get approved and instead get failed. Such entries are listed in the application log.
For example, if a software has no Name/Version: The software without a name doesn't
make any sense, The Software (OOB table) uses a 'key' attribute consisting of name and
version. Thus, empty names causes assets to fail.
- If there are multiple records with same name. Assets get approved, on production class,
not all will be added as separate records. The first asset which is approved gets added as a
separate record. All the other assets with same name get approved, but the IRE version
creates multiple records or skips records.
For example, software have same name and version number in staging area. In such case,
duplicate entries may be created. Check application log. Skipping duplicate entry.
Truncated Value
If the field value exceeds the field limit then the value may get truncated. The application
does not update any of the OOB table structures: like field value lengths.
58
Qualys CMDB Sync App
Debugging and Troubleshooting
Recommendations
We recommend following tips for better and smooth data migration.
59
Qualys CMDB Sync App
Field Mapping for Tables
Classified Tables
The classified table includes the mapping of source fields with target fields that are
recommended/used by ServiceNow
60
Qualys CMDB Sync App
Field Mapping for Tables
61
Qualys CMDB Sync App
Field Mapping for Tables
Related Tables
The related tables list the custom field mappings that could not be accommodated in the
classified tables. We recommend that you do not alter the mappings in the related tables.
62
Qualys CMDB Sync App
Field Mapping for Tables
os_lifecycle_ga os_lifecycle_ga
os_lifecycle_stage os_lifecycle_stage
os_market_version os_market_version
os_product_name os_product_name
os_publisher os_publisher
os_architecture os_architecture
os_full_name os_full_name
os_install_date os_install_date
63
Qualys CMDB Sync App
Field Mapping for Tables
processor_description processor_description
processor_speed processor_speed
64
Qualys CMDB Sync App
Field Mapping for Tables
65
Qualys CMDB Sync App
Field Mapping for Tables
Note: ServiceNow has soft-deprecated the following classes for Qubec version:
- Human Machine Interface [cmdb_ci_hmi]
- Manufacturing Device [cmdb_ci_manufacturing]
- Programmable Logic Controller [cmdb_ci_plc]
For more information on alternative solutions, see ServiceNow notification.
66
Qualys CMDB Sync App
Field Mapping for Tables
67
Qualys CMDB Sync App
Field Mapping for Tables
68
Qualys CMDB Sync App
Field Mapping for Tables
Appendix
The below table shows the mapping between ServiceNow fields and Qualys.
69
Qualys CMDB Sync App
Field Mapping for Tables
Asset Metadata
ServiceNow Field Label Qualys UI Field
Asset ID Qualys Asset ID
name Host Name
company Company
created First Seen (On Connector Screen)
department Department
environment Environment
ip_address IPv4 Address
last_updated Last Updated Date (On Connector screen)
location Assigned Location
managed_by Managed By
owned_by Owner/Custodian
status Operational Status
supported_by Supported By
support_group Support Group
70
Qualys CMDB Sync App
Migration Support
Migration Support
We provide you with migration scheduled job to assist you with data migration from your
previous versions of Qualys CMDB Sync App to the latest version of the app. The Qualys
CMDB Sync App 2.1 provides you with usage of out of box production tables by
ServiceNow.
Once upgrade to 2.1 version and before you sync assets or create schedules, we
recommend you to migrate assets available in computer extended tables to out of box
production tables provided by ServiceNow. To ease migration task, we provide you with a
scheduled job for migration of assets (optional).
Get Started
We provide the you with ready to use Migration 1.x app scheduled job. The function and
frequency of execution this job is explained below. You can always update or change the
frequency of the scheduled job as per your needs.
Migration 1.x- By default, this job is deactivated. The purpose of this job is only for
migration of assets that belong to Computer Extended table and need to be migrated to
production tables.
Assets that belong to Computer extended table are migrated to the respective CMDB
tables on production. For example, assets in computer extended table that belong to
Windows server are migrated to the Windows Server CI class.
71
Qualys CMDB Sync App
Migration Support
2. Click Edit.
3. Select Active check box to enable activation.
If activated, the default configured frequency is 100 assets for every 15 minutes. You can
also alter the frequency to suit your requirements of asset migration.
4. Click Update.
Alternately, you could click Execute Now to immediately run the job.
72
Qualys CMDB Sync App
Migration Support
Once the job is executed, the application logs reflect migration. Once the migration is
completed, the application log lists the number of assets are migrated.
If any assets fail to migrate, the Migration State and Migration Notes indicate that the
migration has failed. Migration Notes field is available only for assets whose criteria is
defined by Identification engine rule. For assets using transform maps, only migration
state is available.
To trigger migration for failed migration assets, reset the migration state to None for all
such assets and clear the Migration Notes field.
Once, all the assets are migrated, you can de-activate the Migration 1.x job.
73
Qualys CMDB Sync App
Known Issues
Known Issues
The following are the few known issues/limitations you may find in the CMDB Sync App:
- We have observed that in some cases, there is a discrepancy in certificate count between
Cert View V2 API and Cert View Qualys UI. ServiceNow certificate details will be based on
the API response, so in such cases, the discrepancy between ServiceNow and Qualys UI
can be observed. We have logged a ticket for the Certificate View team to investigate it
further.
74