Qualys SCA via API

About this document

This document provides the step-by-step procedure to integrate SAFE with Qualys Policy Compliance (PC)and Security Configuration Assessment (SCA).

Introduction

SAFE integrates with Qualys Policy Compliance (PC)and Security Configuration Assessment (SCA) to fetch the configuration assessment results based on CIS benchmarks into SAFE.

You can configure Qualys PC and SCA in SAFE via SAFE REST APIs only.

Prerequisites

The Qualys asset’s Operating System is used to map it to the SAFE asset type. The mapping can be viewed or updated using GET and POST <SAFE_URL>/api/v3/settings/os-to-safe-asset-type-mapping API.

To configure Qualys, you need the following details:

• Qualys API URL - The URL should start with qualysapi, and not qualysguard.
• Qualys API Credentials (Refer to Creating a user in Qualys with API access )
• Verifying that the SAFE Instance’s IP address is whitelisted in the user’s Qualys Instance.

Configure Qualys CA in SAFE via API

Navigat to SAFE API documentation

1. Log into SAFE.
2. In the top-right, click on the help icon and select SAFE API. The system opens the SAFE API documentation in a new tab.

Testing if SAFE can connect with Qualys

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

Payload

{
"type": "plugin",
"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 CA, this value defaults to “plugin.”
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 Qualys Security and Compliance Suite Login 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"
}

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

{
  "type": "plugin",
  "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"],
    "allowedPolicyNames": ["<QUALYS_TAG_ID_1>","<QUALYS_TAG_ID_2"],
    "assetMatchingCriteria": [
      "fqdn",
      "asset_name",
      "ip_address"
    ]
  }
}

Details of payload arguments

1. type: The type of Integration configuration being saved. For Qualys CA, this value defaults to “plugin”.
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 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 fetch the configuration assessments for onboarded assets. Any period between 1 day and 30 days can be specified.
   5. shouldImportAssets: This config option specifies whether safe should create new assets available in Qualys in SAFE. If an imported asset matches an existing asset in SAFE, then the assessment would be pushed against the asset, if there is no match found in safe, and if shouldImportAssets is set to true, it will create a new asset in SAFE else, it will skip adding the asset in SAFE. It can be set as true or false.
   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 CA results for all assets to which the user has access will be pulled to SAFE. Eg. ["15627033", "15627031", ...]. Users can call action tags on saved integration to fetch all the tags available. Refer Qualys - Qualys for steps on how to get Tag IDs from Qualys.
   8. allowedPolicyNames (Optional): SAFE allows the user to filter the data being fetched from Qualys based on Policy Names of compliance policies in Qualys. This is an Optional field. Based on the policy names provided, SAFE will sync configuration data for the given policy names only. If no policy name is provided, SAFE syncs data for all policies available in Qualys SCA. Eg. ["CIS Benchmark for Red Hat Enterprise Linux 8, v2.0.0 [Automated and Manual, Level 1 and Level 2] v.1.0", ...]. Users can call action policies on saved integration to fetch all the policies available.
   9. assetMatchingCriteria (Optional): 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 asset-matching-criteria settings would be used, and can be fetched using API GET v3/settings/asset-matching-criteria.

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.

Viewing All supported operations for Qualys CA Integration

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

Response

[
{
"type": "plugin",
"subtype": "qualys",
"actions": [
{
"name": "sync",
"description": "This action is used to sync data from the Qualys to SAFE"
},
{
"name": "tags",
"description": "This action is used to get tags data from the Qualys, doing this doesn't change anything in SAFE."
},
{
"name": "test",
"description": "This action is used to test the connection for the Qualys"
},
{
"name": "policies",
"description": "This action is used to get policies data from the Qualys, doing this doesn't change anything in SAFE."
},
{
"name": "enable",
"description": "This action is to enable integration instance"
},
{
"name": "disable",
"description": "This action is to disable integration instance"
}
]
}
]

Perform an action over a saved Qualys CA 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 is the action you want to perform.

Perform manual sync of CA results from Qualys

Using a saved configuration to sync the CA 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 CA results for the assets onboarded in confirmed verticals in SAFE.

By default, manual sync is allowed once every 24 hours. To override this and trigger sync again within 24 hours, use force=true as a query parameter in API request, i.e. the effective URL will be POST <SAFE_URL>/api/v3/integrations/:instance_id?action=sync&force=true.

Checking the Sync status for Qualys CA 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": "plugin",
"subtype": "qualys",
"config": {
"url": "https://www.test.com/",
"username": "username",
"sensitiveFields": [
"password"
],
"autoSyncFrequency": 1,
"shouldImportAssets": true,
"assetMatchingCriteria": [
"asset_name",
"ip_address",
"mac_address"
]
},
"state": {
"error": null,
"stage": "TRANSFORMING",
"status": 0,
"totalAssets": 43,
"failedAssets": 0,
"lastScanTriggerTs": "2022-08-30T12:30:29.502Z",
"completionPercentage": 100,
"lastScanCompletionTs": "2022-08-30T12:34:17.173Z"
},
"isEnabled": true
}

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.

View results of Qualys Configuration Assessments

After a successful sync of Qualys CA integration, the Qualys assets are automatically imported to SAFE along with CA data. These assets can be viewed in SAFE as per the vertical corresponding to their Safe asset type on the Technology > Inside-Out page. Any asset where mapping to a safe asset type is not found will still be onboarded into OTHERS vertical. Assets onboarded in OTHERS will not have CA assessment done for them until they are moved to another vertical.