Qualys Connector User Guide

Instructions for deploying and operating the Qualys Connector within the Keyfactor AgileSec Platform for processing and analysis.

Overview

The Qualys Connector integrates the Qualys Cloud Platform with Keyfactor's AgileSec Platform. This Connector retrieves vulnerability scan reports from Qualys and extracts cryptographic protocol findings, bringing protocol and cipher visibility into the AgileSec ecosystem.

What Gets Scanned

The Qualys Connector can discover the following cryptographic asset types from Qualys scan reports:

• TLS/SSL Protocol Versions: Identifies which protocol versions are in use on scanned hosts.

• Cipher Suites: Extracts cipher suite information from protocol scan results.

• Key Exchange Algorithms: Identifies key exchange algorithms observed during scans.

• Host Information: Captures IP addresses, DNS names, operating systems, and tracking metadata.

Prerequisites

Ensure you meet the following requirements to enable scanning.

Network Access

Ensure HTTPS network connectivity from AgileSec platform or remote execution machine to the Qualys API. See Qualys Platform Identification for more details from Qualys. unles

Supported Authentication Methods

The Qualys Connector uses Basic Authentication (username and password) to access Qualys:

• Same credentials you would use to log into the Qualys Cloud Platform.

• The user must have API access enabled in Qualys.

Qualys Required Access Rights

The Qualys user account must have the following permissions:

Remote Execution Requirements

If running the Connector remotely using CLI, the remote execution machine must meet these requirements:

Qualys Connector and Template Initialization

Before running the Qualys Connector the first time, users must initialize the Connector and generate a report template in Qualys.

Scans may be run on remote host machines with the AgileSec Remote Sensor Package.

Download Remote Sensor Package

1. Open your browser and navigate to the Keyfactor AgileSec Platform Web URL

2. Log in with your credentials

3. Click on "Sensors" in the left navigation menu under Scan

   

4. Click Remote Scan.

   

5. Click + Download Remote Sensor.

   

6. Download the sensor binary for your remote machine’s operating system

   

Generate Platform Token

7. In the Download Remote UI, click "Generate Token"

8. Copy the generated token

9. Store securely in an environment variable such as SENSOR_TOKEN:

    export SENSOR_TOKEN="your-generated-token"
   

Create Configuration File

10. Create a file isg_qualys.json with the following variables:

    {
      "qualys": {
        "url": "QUALYS_URL",
        "username": "QUALYS_USERNAME",
        "password": "QUALYS_PASSWORD"
      }
    }
    

11. Set the QUALYS_URL, QUALYS_USERNAME, and QUALYS_PASSWORD variables.

12. Create and save the template infosec-protocol-template.xml provided below:

<?xml version="1.0" encoding="UTF-8"?>
<!-- <!DOCTYPE REPORTTEMPLATE SYSTEM
"https://qualysapi.qg3.apps.qualys.com/api/2.0/fo/report/template/scan/scanreporttemplate_info.dtd"> -->
<REPORTTEMPLATE>
  <SCANTEMPLATE>
    <TITLE>
      <INFO key="title"><![CDATA[InfosecGlobal-Kex-Scan-Report]]></INFO>
    </TITLE>
    <TARGET>
      <INFO key="scan_selection"><![CDATA[HostBased]]></INFO>
      <INFO key="include_trending"><![CDATA[0]]></INFO>
      <INFO key="asset_groups"><![CDATA[All]]></INFO>
      <INFO key="ips"><![CDATA[]]></INFO>
      <INFO key="host_with_cloud_agents"><![CDATA[all]]></INFO>
    </TARGET>
    <DISPLAY>
      <INFO key="display_text_summary"><![CDATA[0]]></INFO>
      <INFO key="graph_severity"><![CDATA[0]]></INFO>
      <INFO key="graph_potential_severity"><![CDATA[0]]></INFO>
      <INFO key="graph_ig_severity"><![CDATA[0]]></INFO>
      <INFO key="graph_os"><![CDATA[0]]></INFO>
      <INFO key="graph_services"><![CDATA[0]]></INFO>
      <INFO key="display_custom_footer"><![CDATA[0]]></INFO>
      <INFO key="display_custom_footer_text"><![CDATA[]]></INFO>
      <INFO key="sort_by"><![CDATA[host]]></INFO>
      <INFO key="cvss"><![CDATA[all]]></INFO>
      <INFO key="qualys_system_ids"><![CDATA[0]]></INFO>
      <INFO key="include_vuln_details"><![CDATA[1]]></INFO>
      <INFO key="include_vuln_details_threat"><![CDATA[0]]></INFO>
      <INFO key="include_vuln_details_impact"><![CDATA[0]]></INFO>
      <INFO key="include_vuln_details_solution"><![CDATA[0]]></INFO>
      <INFO key="include_vuln_details_compliance"><![CDATA[0]]></INFO>
      <INFO key="include_vuln_details_exploit"><![CDATA[0]]></INFO>
      <INFO key="include_vuln_details_malware"><![CDATA[0]]></INFO>
      <INFO key="include_vuln_details_results"><![CDATA[1]]></INFO>
      <INFO key="include_vuln_details_appendix"><![CDATA[0]]></INFO>
      <INFO key="exclude_account_id"><![CDATA[0]]></INFO>
      <INFO key="metadata_ec2_instances"><![CDATA[0]]></INFO>
      <INFO key="cloud_provider_metadata"><![CDATA[0]]></INFO>
      <INFO key="include_vuln_details_detection_logic"><![CDATA[0]]></INFO>
      <INFO key="include_trurisk_details"><![CDATA[0]]></INFO>
    </DISPLAY>
    <FILTER>
      <INFO key="selective_vulns"><![CDATA[custom]]></INFO>
      <INFO key="search_list_ids"><![CDATA[9408879]]></INFO>
      <INFO key="exclude_qid_option"><![CDATA[0]]></INFO>
      <INFO key="exclude_search_list_ids"><![CDATA[]]></INFO>
      <INFO key="included_os"><![CDATA[ALL]]></INFO>
      <INFO key="status_new"><![CDATA[1]]></INFO>
      <INFO key="status_active"><![CDATA[1]]></INFO>
      <INFO key="status_reopen"><![CDATA[1]]></INFO>
      <INFO key="status_fixed"><![CDATA[0]]></INFO>
      <INFO key="vuln_active"><![CDATA[0]]></INFO>
      <INFO key="vuln_disabled"><![CDATA[0]]></INFO>
      <INFO key="vuln_ignored"><![CDATA[0]]></INFO>
      <INFO key="potential_active"><![CDATA[0]]></INFO>
      <INFO key="potential_disabled"><![CDATA[0]]></INFO>
      <INFO key="potential_ignored"><![CDATA[0]]></INFO>
      <INFO key="ig_active"><![CDATA[1]]></INFO>
      <INFO key="ig_disabled"><![CDATA[0]]></INFO>
      <INFO key="ig_ignored"><![CDATA[0]]></INFO>
      <INFO key="display_non_running_kernels"><![CDATA[0]]></INFO>
      <INFO key="exclude_non_running_kernel"><![CDATA[0]]></INFO>
      <INFO key="exclude_non_running_services"><![CDATA[0]]></INFO>
      <INFO key="exclude_superceded_patches"><![CDATA[0]]></INFO>
      <INFO key="exclude_qids_not_exploitable_due_to_configuration"><![CDATA[0]]></INFO>
      <INFO key="categories_list"><![CDATA[ALL]]></INFO>
      <INFO key="qds_score_min"><![CDATA[1]]></INFO>
    </FILTER>
    <SERVICESPORTS>
      <INFO key="required_services"><![CDATA[]]></INFO>
      <INFO key="unauthorized_services"><![CDATA[]]></INFO>
      <INFO key="services_info"><![CDATA[]]></INFO>
      <INFO key="required_ports"><![CDATA[]]></INFO>
      <INFO key="unauthorized_ports"><![CDATA[]]></INFO>
    </SERVICESPORTS>
    <USERACCESS>
      <INFO key="global"><![CDATA[1]]></INFO>
      <INFO key="report_access_users"><![CDATA[]]></INFO>
    </USERACCESS>
  </SCANTEMPLATE>
</REPORTTEMPLATE>

13. Initialize the connector and Qualys report template with the following commands:

    1. On Linux:

       Bash

       ./bin/isg_qualys_linux --config <path-to-isg_qualys.json> \
       --template <path-to-infosec-protocol-template.xml>
       

    2. On Windows:

       .\bin\isg_qualys_windows.exe --config <path-to-isg_qualys.json> \
       --template <path-to-infosec-protocol-template.xml>
       

This initialization command will:

1. Use the infosec-protocol-template.xml to create a search list with the minimum required configuration.

2. Generate a report template named InfosecGlobal-Kex-Scan-Report.

3. Exit without initiating a scan.

Running the Connector

AgileSec Qualys scans can be executed using the following methods:

1. Platform Scan Execution: Configure and execute scans directly through the Keyfactor AgileSec web UI with on-demand or scheduled execution options.

2. API Scan Execution: Programmatically trigger scans through REST API calls, enabling integration with CI/CD pipelines and automation workflows.

3. Remote Scan Execution: Deploy and run the connector via CLI on customer-managed infrastructure for scenarios such as:

   1. Scanning air-gapped or internal instances the platform cannot directly reach

   2. Customers wanting to manage their own scheduling and execution environment.

Configuration Fields

The following parameters are used to configure AgileSec Qualys scans.

Platform Scan Execution

Running scans through the user interface is the simplest and fastest way to get started. The platform enables running on-demand or scheduled scans in a dedicated environment.

Platform Scan Configuration

1. Open your browser and navigate to the Keyfactor AgileSec Platform Web URL

2. Log in with your credentials

3. Click on "Sensors" in the left navigation menu under Scan

   

4. Click "+ New Sensor".

   

5. Click on the correct card to open the configuration interface.

Configure Parameters and Start Scan

6. Fill in the required configuration parameters.

7. Click Save.

8. Click Action then Scan to begin a scan.
   Note: Click Edit to reconfigure parameters.

   

API Scan Execution

Scans may be programmatically triggered through REST API calls, enabling seamless integration with CI/CD pipelines, automation workflows, and custom applications. API execution provides flexibility for developers to incorporate cryptographic scanning into their existing development and deployment processes.

Generate AgileSec API Access Token

1. Open your browser and navigate to AgileSec Platform UI

2. Log in with your Keyfactor credentials

3. Click "Access Tokens" in the main navigation menu

4. Click "Generate Token" button

5. Set Token Type to API Token and provide the required details

6. Click "Generate" and copy the generated token

   

AgileSec API Endpoint

POST https://<platform-url>/v3/scan/create/

Request Format

Headers

Content-Type: application/json
isg-api-token: <your-api-token>

Request Body

  {
    "sensorName": "<sensor name>",
    "sensorType": "Qualys Network",
    "sensorConfig": {
       "url": "<qualys api url>",
       "username": "<qualys username>",
       "password": "<qualys password>",
       "report_title": "agilesec"
    },
    "callbackId": "<callback id>",
    "labels": [
        {
            "<label name>": "<label value>"
        }
    ],
    "priority": "<priority>"
  }

Remote Scan Execution

Scans may be run on remote host machines with the AgileSec Remote Sensor Package.

Download Remote Sensor Package

1. Open your browser and navigate to the Keyfactor AgileSec Platform Web URL

2. Log in with your credentials

3. Click on "Sensors" in the left navigation menu under Scan

   

4. Click Remote Scan.

   

5. Click + Download Remote Sensor.

   

6. Download the sensor binary for your remote machine’s operating system

   

Generate Platform Token

7. In the Download Remote UI, click "Generate Token"

8. Copy the generated token

9. Store securely in an environment variable such as SENSOR_TOKEN:

    export SENSOR_TOKEN="your-generated-token"
   

Create Configuration File

Create a YAML configuration file (e.g., qualys-config.yml) with your scan settings. An example configuration can be found in config/sample-configs/qualys.yml.

Step 4: Run the Connector

Execute the Connector with your configuration file:

• Linux/macOS

  Bash

  # Set environment variables
  export SENSOR_TOKEN="your-sensor-token"
  
  # Run Connector
  ./unified_sensor_linux -c qualys-config.yml
  

• Windows (PowerShell)

  PowerShell

  # Set environment variables
  $env:SENSOR_TOKEN = "your-sensor-token"
  
  # Run Connector
  .\\unified_sensor_windows.exe -c .\\qualys-config.yml
  

Remote Scan Execution Configuration Examples

• Basic Configuration

  YAML

  scan_config:
    plugins:
      - qualys
      - export
    config:
      qualys:
        name: qualys
        plugin_config:
          url: "<https://qualysguard.qg3.apps.qualys.com/>"
          username: "${env:QUALYS_USER}"
          password: "${env:QUALYS_PASS}"
  

• With Custom Report Title Filter

  YAML

  scan_config:
    plugins:
      - qualys
      - export
    config:
      qualys:
        name: qualys
        plugin_config:
          url: "<https://qualysguard.qg3.apps.qualys.com/>"
          username: "${env:QUALYS_USER}"
          password: "${env:QUALYS_PASS}"
          report_title: "crypto-scan"
  

Known Limitations

Report Format

Only XML-format reports are supported. Reports in other formats (PDF, CSV) are ignored.

Report Title Matching

Reports are selected based on a case-insensitive title keyword match. If no reports match, no findings are produced.

Troubleshooting Common Errors

• CONFIG-404 – Unable to read/parse configuration file

  • Cause: The configuration file path is incorrect or the file is malformed.

  • Fix: Verify the config file path and validate JSON syntax.

• CONFIG-422 – Required attribute not found

  • Cause: A required configuration field is missing.

  • Fix: Ensure url, username, and password are present in the configuration.

• 401 Unauthorized

  • Cause: Invalid Qualys credentials.

  • Fix: Verify the username and password are correct and have API access enabled.

• No reports found

  • Cause: No reports match the configured title keyword, or no reports are in XML format with "Finished" status.

  • Fix: Verify reports exist in Qualys. Verify the report title contains report_title, report status is Finished, and report has not expired or been removed from Qualys history. Default report_title is agilesec.

Getting Support

Collect diagnostic information:

• Connector version

• Configuration file (redact passwords)

• Log output

• Qualys platform details (URL, API version)

Contact Support

• Portal: https://support.keyfactor.com