Qualys VMDR

About this document

This document provides step-by-step instructions to configure the Qualys VMDR integration in SAFE and pull assets and vulnerability findings from Qualys Vulnerability Management, Detection and Response (VMDR), enriched with asset context from Qualys CSAM or Global AssetView (GAV).

Introduction

The SAFE Qualys VMDR connector  pulls asset inventory and vulnerability data from Qualys VMDR. It enriches each VMDR host with hardware, software, network, cloud and lifecycle context from Qualys CSAM when available, or from Global AssetView (GAV) when CSAM is unavailable.

What SAFE Pulls from Qualys VMDR

Prerequisites

1. A Qualys VMDR subscription with access to the Host List, Host List Detection and KnowledgeBase APIs.
2. A Qualys administrator account to create the integration user and assign it to all asset groups, business units, networks or tags SAFE should sync.
3. SAFE admin access.
4. Outbound HTTPS from SAFE to the Qualys API Server (for example https://qualysapi.<pod>.apps.qualys.com). If the customer restricts access by source IP, allowlist the SAFE egress IPs first.
5. (Optional) For richer software and asset context, either:
   • CSAM: the API Gateway URL (for example https://gateway.<pod>.apps.qualys.com) and CSAM / Global AssetView API access, or
   • GAV: Asset Management access for the Host Asset search.If neither is available, SAFE syncs VMDR assets and vulnerabilities only, with no software.

Minimum privileges

Generate connection details

You need the following from the customer's Qualys environment: the API Server URL, the Username and Password of a dedicated API user, and optionally the API Gateway URL, a Tag Filter and an Asset last seen days filter.

Confirm the Qualys platform URLs

1. Identify the customer's Qualys platform / pod. Common URL patterns are:
   • Qualys portal: https://qualysguard.<pod>.apps.qualys.com
   • API Server: https://qualysapi.<pod>.apps.qualys.com
   • API Gateway: https://gateway.<pod>.apps.qualys.com
2. Confirm the exact API Server URL from the customer's Qualys documentation or subscription details. The Qualys Platform Identification page also lists the correct URLs for each pod (see API URLs below).
3. If the customer has CSAM and wants richer context, confirm the API Gateway URL as well.

Create a dedicated SAFE integration user

1. Log in to the Qualys platform with an administrator account.
2. Go to the user administration area. In many Qualys tenants this is under Administration or Users.
3. Create a new user for the SAFE integration, for example safe-qualys-vmdr-api.
4. Set a strong password and store it securely.
5. Enable API access for the user (under Allow access to, select API).
6. Assign the user only to the asset groups, tags, business units, networks or scopes that SAFE should ingest.
7. Assign the user a role with Reader or higher access.

Note: Use a dedicated integration user rather than a named administrator account, and grant read-only access wherever possible. Rotate the password periodically (see the FAQ).

Assign the required VMDR permissions

SAFE needs the permissions below. Missing VMDR Host List, Host List Detection or KnowledgeBase access can cause Test Connection or Sync to fail.

1. Read VMDR host inventory through the Host List API.
2. Read Host List Detection / vulnerability detections.
3. Read KnowledgeBase vulnerability details.
4. Do not grant write, remediation, scan launch or asset management modification permissions unless the customer's internal process requires them for unrelated use cases.

Assign tag and context permissions, if applicable

1. Tag filter: if the connector uses a tag filter, grant Asset Management and Tagging access so SAFE can resolve tag names to tag IDs.
   • Go to Role Management within the Administration utility to check or create a custom role.
   • Ensure the role includes the necessary Tagging Permissions (such as Create User Tag, Edit User Tag, Delete User Tag or Modify Dynamic Tag Rules, depending on the level of control needed).
   • Ensure asset management permissions (such as Read Asset or Update Asset) are active in the role.
2. GAV context: grant Asset Management access for Host Asset search.
3. CSAM context: ensure the user has CSAM / Global AssetView API access, access through the Qualys API Gateway, and App API Enabled (or equivalent API enablement in the customer's Qualys subscription).
4. Confirm the user's asset scope includes all hosts that SAFE should sync.

Note: A missing CSAM or GAV permission does not necessarily fail the connector. SAFE falls back to the next available context source.

API URLs

Use the API Gateway URL for Asset Inventory (CSAM context). Use the API Server URL for everything else in this connector. Customers can confirm their pod and URLs on the official Qualys Platform Identification page.

Configure in SAFE

1. Sign in to SAFE as an admin and go to Integrations.
2. Select the Qualys VMDR card.
3. Enter a unique Integration Name (mandatory).
4. Enter the API Server URL.
5. (Optional) Enter the API Gateway URL if CSAM context is licensed and should be attempted.
6. Enter the Username and Password of the dedicated integration user.
7. (Optional) Enter a Tag Filter as comma-separated tag names or tag IDs.
8. Review the Asset last seen days filter. The default is 30. Increase it if the customer has valid hosts with older scan timestamps.
9. Enter the Auto Sync (in Days) interval at which SAFE runs a sync automatically. The default is 1.
10. Click Test Connection and confirm that it succeeds.
11. Once the connection is verified, click Save.
12. Click Sync Now to run the first sync, and monitor the sync status until it completes.
13. Validate a sample of synced assets in SAFE. Confirm host name, IP address, OS, tags and vulnerability findings. If CSAM or GAV context is available, also validate software inventory, network interfaces, cloud identifiers, hardware attributes and open ports where present in Qualys.

Configuration notes

• API Gateway URL: If it is set and CSAM is available, SAFE uses CSAM context. Otherwise SAFE tries GAV. If neither is available, only VMDR assets and vulnerabilities are synced.
• Tag Filter: Only assets with at least one matching tag are synced. Verify that the tag names resolve exactly in Qualys. If none of the configured tag names or IDs resolve, SAFE fails closed rather than syncing all assets.
• Asset last seen days filter: Hosts older than this many days are excluded as stale. Hosts with no scan date are kept. Increase the value if valid assets are scanned less often than every 30 days.
• Software: Software is synced only when CSAM or GAV returns context for the VMDR asset ID.

View Result

To view the assets and the findings:

1. From the SAFE Integrations page, click on the Qualys VMDR card.
2. A page with "Finding View" and "Asset View" tabs will open up.
3. Asset View will list the hosts pulled or updated from Qualys VMDR, one device per VMDR host.
4. Open an asset to check its host name, IP address, OS and tags. When CSAM or GAV context is available, it also shows software, network interfaces, cloud identifiers, hardware attributes and open ports.
5. Finding View will list the vulnerability findings from VMDR Host List Detection, with QID, CVE, severity, detection type and status.

API Details

The Qualys VMDR connector pulls data from Qualys over outbound HTTPS. API Server calls use HTTP Basic authentication. API Gateway calls for CSAM use a JWT bearer token obtained from /auth. The POST calls below are search and list requests; SAFE does not write to Qualys.

FAQs

Q: How frequently does SAFE sync data from Qualys VMDR?

A: Sync frequency depends on the Auto Sync configuration. The default is every 1 day. You can also trigger an on-demand sync at any time using Sync Now.

Q: Does SAFE need write permissions in Qualys?

A: No. The integration is read-only.

Q: Can we use an existing Qualys admin account?

A: It may work if the account has the required permissions. SAFE recommends a dedicated integration user with least-privilege access so access can be audited, rotated and revoked independently.

Q: Is CSAM required?

A: No. VMDR access is required. CSAM is optional and provides richer context. If CSAM is unavailable, SAFE attempts Global AssetView. If neither is available, SAFE syncs VMDR assets and vulnerabilities only.

Q: Are CSAM-only assets imported?

A: No. The connector imports only assets reported by the VMDR Host List. CSAM and GAV enrich those VMDR assets by Qualys asset ID.

Q: Is EASM data imported?

A: No. EASM-only assets and EASM vulnerabilities are out of scope for this connector.

Q: Why are software details missing for some assets?

A: Software is available only when CSAM or GAV returns context for the VMDR asset ID. Some VMDR hosts may not have a Qualys asset ID or may not have context available. If no context source is available at all, configure the API Gateway URL for CSAM or grant GAV Host Asset access.

Q: Test Connection fails with 401 / 403.

A: Likely causes are invalid credentials, API access disabled, a missing permission or insufficient asset scope. Verify the username and password, API access, VMDR permissions and the asset group / tag scope. A 401 or 403 on a VMDR, Detection or KnowledgeBase test means the corresponding required permission is missing or the user is outside the required asset scope.

Q: Test Connection succeeds, but the context says "none".

A: The CSAM and GAV context APIs are unavailable or not permitted. Grant GAV or CSAM / API Gateway access if software and enriched context are required.

Q: Zero assets were synced.

A: Possible causes are a tag filter that resolves to no tags, an API user with limited scope, the wrong Qualys pod, or a last-seen filter that excludes the hosts. Check the tag names or IDs, the asset scope, the API Server URL and the Asset last seen days filter.

Q: Expected vulnerabilities are missing.

A: The user may lack Host List Detection or KnowledgeBase access, the assets may be outside the user's scope, or the detections may not be in a supported status or type. Verify the Host List Detection and KnowledgeBase permissions and confirm the detections in Qualys.

Q: What happens if the tag filter is configured incorrectly?

A: If none of the configured tag names or IDs resolve, SAFE fails closed rather than syncing all assets.

Q: Qualys returned HTTP 409 or 429.

A: The tenant may have reached an API rate or concurrency limit. Retry later, reduce concurrent Qualys API activity, or review the tenant's API limits.

Q: The API Gateway URL is unreachable.

A: The URL may be incorrect, a network block may be in place, or the platform may not match. Confirm the customer's Qualys Gateway URL and allowlist the SAFE egress IPs if required.

Q: How should credentials be rotated?

A: Update the dedicated Qualys user's password in Qualys, update the password in the SAFE connector configuration, and run Test Connection before the next sync.