Qualys VMDR via API - Advanced

1. About this document

This document gives you the step-by-step procedure to configure Qualys VMDR in SAFE via APIs.

2. Prerequisites

Refer to Prerequisites.

3. Identifying the common identifier for Assets between SAFE and Qualys

With the change in how Qualys is adapting its vulnerability assessment to handle remote endpoints, the fundamentals to identify an asset uniquely have changed. To tackle this issue, SAFE allows the user to specify the assetMatchingCriteria to customize the common identifiers between SAFE Assets and Qualys Assets so that the VA results get tagged to the correct asset in SAFE every time a Qualys VA sync is performed.

The default assetMatchingCriteria order is - ["asset_name", "ip_address", "mac_address"]

1. FQDN or Hostname - Identified by asset_name value in SAFE.
2. IP Address - identified by ip_address value in SAFE.
3. Mac Address - identified by mac_address value in SAFE.

The Mac Address criterion is not applicable for SAFE-Qualys integration, as it is not retrieved during a Qualys Data pull. 

The user has an option to reorder the priority order for the aforementioned identifier field. The corresponding changes should be specified while configuring Qualys. These can be changed any number of times by updating the configuration. 

4. Configuring Qualys Integration with SAFE

4.1. Testing if SAFE can connect with Qualys

Before configuring a Qualys Integration instance with SAFE we need to make sure that we can connect to the instance using SAFE.

To do that we need to use POST <SAFE_URL>/api/v3/integratisons/test.

Payload

{
  "type": "vaplugin",
  "subtype": "qualys",
  "config": {
    "url": <QUALYS_URL>,
    "username": <QUALYS_USERNAME>,
    "password": <QUALYS_PASSWORD>
  }
}

Details of payload arguments

1. type: The type of Integration configuration being saved. For Qualys, this value defaults to “vaplugin”.
2. subtype: The tool-name for Integration configuration being saved. For Qualys, this value defaults to “qualys”.
3. config: The configuration properties allow SAFE to connect to Qualys.
   1. url: The API URL for Qualys instance. Eg. If you’re accessing the Qualys instance using a URL https://qualysguard.qg1.apps.qualys.in corresponding to that the API endpoint will be https://qualysapi.qg1.apps.qualys.in i.e., to identify the API URL, just replace qualysguard with qualysapi in the Qualys instance URL.
      Note- This configuration requires the use of qualysapi URLs. qualysguard URLs are not supported.
   2. username: Username which has the Qualys API access enabled.
   3. password: Password corresponding to the provided username.

Response

On a successful test connection, a 200 OK status response would be returned with the following response body.

{
  "success": true,
  "message": "Test connection success"
}

4.2. Adding a Qualys Configuration to SAFE

Once the credentials are tested using the test connection API; to create a new instance of Qualys integration within SAFE, we need to use the POST <SAFE_URL>/api/v3/integrations.

Payload

{
  // "id": 1 (Required only for updating existing configuration)
  "type": "vaplugin",
  "subtype": "qualys",
  "config": {
    "url": <QUALYS_URL>,
    "username": <QUALYS_USERNAME>,
    "password": <QUALYS_PASSWORD>,
    "autoSyncFrequency": 1,
    "shouldImportAssets": true,
    "sensitiveFields": [
      "password"
    ],
    "allowedTags": ["<QUALYS_TAG_ID_1>","<QUALYS_TAG_ID_2"],
    "assetMatchingCriteria": [
      "asset_name",
      "ip_address",
      "mac_address"
    ]
  }
}

Details of payload arguments

1. id: The id field refers to the instance_id of an existing Qualys Configuration, and is required while updating an existing configuration. It should not be provided while creating a new Qualys Configuration instance in SAFE.
2. type: The type of Integration configuration being saved. For Qualys, this value defaults to “vaplugin”.
3. subtype: The tool-name for Integration configuration being saved. For Qualys, this value defaults to “qualys”.
4. config: The configuration properties allow SAFE to connect to Qualys.
   1. url: The URL for Qualys instance. Eg. https://qualysapi.qg1.apps.qualys.in
      Note- This configuration requires the use of qualysapi URLs. qualysguard URLs are not supported.
   2. username: Username which has the Qualys API access enabled.
   3. password: Password corresponding to the provided username.
   4. autoSyncFrequency: The period (in the number of days) after which SAFE connects to Qualys to fetch the latest vulnerabilities for onboarded assets. Any period between 1 day and 30 days can be specified.
   5. shouldImportAssets: This config option specifies whether safe should import assets available in Qualys to Unconfirmed Assets vertical in SAFE. It can be set as true or false. A total of 50K assets can be there is a SAFE instance. If the flag is set to true, assets will be onboarded to SAFE from Qualys till the 50K limit is met.
   6. sensitiveFields: SAFE allows the flexibility for the user to select any fields which they want to store as encrypted in the SAFE DB. By providing the field names as an array of strings as input, the specified fields will be stored as encrypted (eg. ["username", "password", ...]). For Qualys only username, password, and url fields can be encrypted. Regardless of whether this input is provided or not password will always be encrypted.
   7. allowedTags (Optional): SAFE allows the user to filter the data being fetched from Qualys based on Qualys Asset Tag Ids. This is an Optional field. If no tags are provided, the pulled data will not be filtered and VA results for all assets to which the user has access will be pulled to SAFE. Eg. ["15627033", "15627031", ...]. Refer to the above section for detailed steps on how to retrieve Asset Tag Ids from Qualys.
   8. assetMatchingCriteria: Asset matching criteria is a SAFE-specific field available to provide the user flexibility to configure their criteria for identifying any existing assets in SAFE. Eg. FQDN, DNS Name, or IP Address. The user can arrange the order of the assetMatchingCriteria if required to suit their Qualys configurations. The field can also be left blank in which case the default order - ["asset_name", "ip_address", "mac_address"] is used.

Response

On a successful save of the new configuration, a 200 OK status response should be returned with the following response body.

{
  "success": true,
  "message": "Integration configuration saved successfully.",
  "data": {
    "id": 1
  }
}

The data.id field signifies the Integration configuration’s instance_id which will be used for all operations over this saved configuration.

4.3. Viewing All supported operations for Qualys Integration

To check what operations can be performed over a stored configuration in this case for type= vaplugin and subtype= qualys we can use GET <SAFE_URL>/api/v3/integrations/details?type=vaplugin&subtype=qualys. This will return a list of supported actions and their description for Qualys.

Response

[
  {
    "type": "vaplugin",
    "subtype": "qualys",
    "actions": [
      {
        "name": "enable",
        "description": "This action is to enable integration instance"
      },
      {
        "name": "disable",
        "description": "This action is to disable integration instance"
      },
      {
        "name": "test",
        "description": "This action is used to test the connection for the integration"
      },
      {
        "name": "sync",
        "description": "This action is used to sync data from the integration"
      },
      {
        "name": "sync-tags",
        "description": "This action is used to sync the qualys tags information to SAFE"
      }
    ]
  }
]

4.4. Perform an action over a saved Qualys configuration

Using the instance_id which was retrieved on saving a configuration to SAFE DB, we can now perform a host of operations specific to the Qualys Integration. To perform any action, we simply need to POST <SAFE_URL>/api/v3/integrations/:instance_id?action={action}. Replace :instance_id with the id of the Qualys configuration and {action} which the action you want to perform.

4.5. Perform manual sync of VA results from Qualys

Using a saved configuration to sync the VA results from Qualys we simply need to do a POST <SAFE_URL>/api/v3/integrations/:instance_id?action=sync. This will trigger sync in the background and will start populating the VA results for the assets onboarded in confirmed verticals in SAFE. 

As a safety measure to prevent multiple sync triggers, by default the manual sync is allowed once every 24 hours. To trigger sync again within 24 hours, one needs to provide another query parameter to the request i.e., force=true. So the effective url becomes POST <SAFE_URL>/api/v3/integrations/:instance_id?action=sync&force=true.

4.6. Checking the Sync status for Qualys Integration

To view the information related to any saved configuration GET /integrations/:instance_id can be used. It will return all config fields except the fields which are encrypted using the sensitiveFields array. It will also return the information regarding the config state and the current Sync status.

Response

{
  "id": 1,
  "type": "vaplugin",
  "subtype": "qualys",
  "config": {
    "url": "https://www.test.com/",
    "username": "username",
    "sensitiveFields": [
      "password"
    ],
    "autoSyncFrequency": 1,
    "shouldImportAssets": true,
    "assetMatchingCriteria": [
      "asset_name",
      "ip_address",
      "mac_address"
    ]
  },
  "state": {
    "status": 0,
    "message": "Success"
    "newAssets": 0,
    "lastScanTime": "2021-11-16T14:08:53.920Z"
  },
  "isEnabled": true
}

4.7. Getting all configured Integrations

To view the information related to all saved configurations GET /integrations can be used. It will return all config fields except the fields which are encrypted using the sensitiveFields array. It will also return the information regarding the current state of each configured integration instance.

The GET /integrations API takes in a few query parameters to help filter the information:

1. page: Pagination parameter for the page number.
2. pagelen: Number of items to be displayed per page. (Default is 100)
3. id: Filter the results using integration instance id. Using this filter will return only one item as the id is unique for each integration instance.
4. type: Filter the results using the integration type eg., vaplugin. This will return integration configuration instances for any integration which can be qualified as vaplugin.
5. subtype: Filter the results using the integration subtype eg., qualys. This will return all integration configuration instances which have a subtype value qualys.

Response

{
  "page": 1, // the page number for which the results are displayed
  "pagelen": 100, // max items per page
  "previous": null, // previous page url, if not the first page
  "next": null, // next page url, if not the last page
  "size": 1, // total number of items across all pages qualifying the filter criteria
  "values": [ // an array of items corresponding to the page
    {
      "id": 1,
      "type": "vaplugin",
      "subtype": "qualys",
      "config": {
        "url": "https://www.example.url/",
        "username": "username",
        "sensitiveFields": [
          "password"
        ],
        "autoSyncFrequency": 1,
        "shouldImportAssets": true,
        "assetMatchingCriteria": [
          "asset_name",
          "ip_address",
          "mac_address"
        ]
      },
      "state": null,
      "isEnabled": true
    }
  ]
}

5. Deleting a stored integration instance

To delete an already stored integration instance from SAFE, the user needs to send a request to DELETE /integration/:instance_id. This will delete the integration instance and all stored credentials corresponding to that instance from SAFE. 

6. FAQs

6.1. Why is my test-connection request for Qualys failing?

There can be several reasons why the test connection request might be failing for the provided creds. To troubleshoot, follow the below steps:

1. Make sure that the API URL provided starts with qualysapi and not qualysguard.
2. Reverify if the provided credentials are correct and whether you can log in to Qualys UI using the same credentials. 
3. Verify if the provided credentials have minimum Reader access and have API access enabled. This can be checked by verifying user details under the Administration option in Qualys.
4. After verifying both steps 1 and 2, if the test connection is still failing, it might be a case of IP restriction in Qualys. Qualys provides functionality to the users to allow traffic from specific IPs, and if that is enabled, we need to whitelist SAFE's NAT gateway IP in Qualys. Please get in touch with the customer support team for help.

6.2. I am not sure what should be the assetMatchingCriteria for my Qualys instance?

The assetMatchingCriteria SAFE uses to map Qualys Assets' VA data to SAFE assets. It can be simplified in two ways:

1. Suppose the Qualys Asset(s) for which the VA data is being pulled can be identified uniquely using the FQDN or Hostname value in Qualys. In that case, we can use the default assetMatchingCriteria. In this situation, no customization will be needed. If an asset does not have a value for FQDN or Hostname fields in Qualys, in that scenario, IP Address will be used to identify the asset.
2. Suppose the Qualys Asset(s) for which the VA data is being pulled can be identified uniquely by IP Address value in Qualys. In that case, we need to give higher precedence to IP Addresses in asset matching criteria. The assetMatchingCriteria in such situation would become ["ip_address", "asset_name"]. If an IP address is not available, then FQDN or Hostname will be used to identify the asset.

6.3. Is it mandatory to provide allowedTags in Qualys Configuration?

No, it is not mandatory to provide the allowedTags in Qualys Configuration. allowedTags helps a user to configure a filter for the assets whose VA data is being pulled by SAFE. This is useful if Qualys has a large data set and the user only wants to import a section of the whole data in SAFE.

6.4Is it possible to configure more than one Qualys Instance to connect with SAFE?

Yes, it is possible. Since Qualys has different API URLs for different regions, SAFE provides functionality to the users where they can add more than one Qualys configuration to SAFE. All that's needed after that is to use the correct integration instance id to initiate actions (e.g., sync) over a stored configuration.

6.5. Is it possible to update an already stored Qualys configuration?

Yes, it's possible to update a stored configuration. The user needs to provide an id, the id of the configuration instance that needs the update, and provide the updated config object.

6.6. Why I am not able to trigger a sync action over a Qualys configuration?

1. Make sure the stored credentials are still valid.
2. By default, only one sync in 24 hours is allowed. To trigger sync again within 24 hours, please provide a query parameter force=true with the request. This should bypass the 24-hour restriction. We DO NOT advise using this parameter. This is for urgent use cases only.