HCL Connectors 

HCL AppScan is an application security testing platform that identifies vulnerabilities across web applications and APIs using dynamic, static, and interactive testing methodologies. 

What is the HCL AppScan API Connector?

The HCL AppScan API Connector creates a secure bridge between your HCL AppScan platform and Qualys Enterprise TruRisk Management (ETM). When configured, it automatically transfers application asset data and associated security vulnerabilities through scheduled API calls. Qualys ETM then processes this data by:

  • Deduplicating redundant entries

  • Normalizing data formats

  • Enriching findings with additional context

  • Calculating risk scores using TruRisk

Category Supported Asset Type Supported Finding Type
API Connector Applications App Issues

Prerequisites

These are the required configurations to successfully create an HCL AppScan connection with Qualys ETM.

User Roles and Permissions

To establish a secure connection between HCL AppScan and Qualys ETM, you must generate HCL API credentials that authorize data access. This involves retrieving a Key ID and Key Secret from your HCL environment, which are used to authenticate API requests and retrieve application and vulnerability data.

How to Generate Key ID and Key Secret

  1. Sign in to your HCL AppScan account at: https://cloud.appscan.com/

  2. From the left-hand navigation pane, go to Tools > API.

  3. On the API Key page, click Generate.

  4. The system will create and display your Key ID and Key Secret. Ensure you copy and store these credentials securely. They will be required during the connector setup process in Qualys ETM.

These credentials are used to authenticate to the AppScan API endpoint.

Create a New API Connector

Basic Details

  1. Provide the Connector's Name and Description.
  2. Select the type of findings you want to import or export - currently, we support Vulnerability.
  3. Select the Asset Type - currently we support Application.
    The following screenshot displays the Basic Details fields.

    Basic Details

  4. Next, provide the API authentication details of the HCL environment. You need to provide the following.

    1. Domain

    2. API Key

    The steps to generate the above values are described in the Prerequisites section.

Data Model

The Qualys Connector for HCL offers an out-of-box data model mapping for you to map with the Qualys ETM schema. You can view the schema to understand the attributes in the data model.

Data Model

Transform Maps

Transform Maps ensure the data is transformed correctly during the import or export process.

The HCL Connector offers an out-of-box transform map for you to proceed without further configuration. View the map to understand the data transformation or clone the map to edit its configurations.

Click Create New for a new Transform Map.

Perform the following steps to configure a Transform Model:

  1. Transform Map Name: Enter a unique name for the Transform Map. This name helps identify the specific transformation configuration within this connector.
  2. Source Data Model: Select the data model that serves as the input for the transformation. This is the model from which data will be extracted.
  3. Target Data Model: Choose the data model that receives the transformed data. This model defines how the data will be structured after the transformation.

    Refer the following Transform Map screenshot:

Fields Mapping

The Fields Mapping section maps fields from the Source Data Model to the Target Data Model.

  1. Source Field: Specify the field in the Source Data Model containing the transformed data.
  2. Data Type: Indicate the data type of the Source Field (e.g., string, integer, date).
  3. Target Field: Designate the corresponding field where the transformed data will be placed in the Target Data Model.

Click Add to create and display the mapping for the Source Field, Data Type, and Target Field below the section. This visual helps ensure that all necessary fields are mapped correctly and allows easy verification and adjustments.

Profile

Create a profile for your connector. A profile decides the connector status, execution schedule and transform map to choose. The connector follows the configurations of this profile for all future executions.

Click the "+" to create a new profile.

In the Add Profile screen, provide the necessary inputs for your new profile.

Provide a Name and Description.

Select the required Transform Map for the data mapping.

The Detection of DataTypes determine which findings to select for the profile. The Asset Types determine the required resource whose findings should be ingested by Qualys ETM.

The Filter field allows you to define specific conditions to refine which data is imported from HCL AppScan into Qualys Enterprise TruRisk Management (ETM). By applying filters, you can limit the dataset based on specific attributes such as application name, last updated time, or other metadata supported by the AppScan API.

Sample Filters
To import data only for a specific application:

Name eq 'www.test.com'

To import data updated after a specific timestamp:

LastUpdated ge 2024-11-18T18:09:14.4291021Z

These filters are passed with the API requests and help in optimizing performance, reducing data noise, and focusing on relevant findings.

The Status field determines whether the connector should be in Active or Inactive state after creation. 

Lastly, the Schedule section lets you either create a Single Occurrence schedule or a Recurring schedule. Provide the exact date and time for the Single Occurence execution and provide the Start and End date/time for the Recurring schedule.

Scoring

The Scoring screen lets you map non-CVE vulnerability scores from your vendors to Qualys Detection Score (QDS) system.

Score mapping screen.

You have two columns with 5 input fields in each of them. These fields correspond to a specific severity starting from the least severe (1), to the most severe (5).

Fill out all 5 rows to create a comprehensive score mapping. This allows for translation between various vendor scoring systems and Qualys' Detection Score.

The specifics of the mapping is explained below.

Expected Source Values - Enter the vendor's original score or rating for non-CVE vulnerabilities.
This can be alphanumeric values. (e.g., "High", "Critical", "A", "3", etc.).

Severity - This column is pre-populated with severity levels from 1-5. These represent the severity levels in Qualys. The Source Value must be mapped such that it utilizes these 5 severity levels.

QDS - Enter the corresponding Qualys Detection Score. Use values from 0-100, where higher numbers indicate higher severity.

Default Severity

Below the scoring map, find the 'Default Severity' dropdown menu.

Select a default severity level from 1-5, this is applied when a vendor's score for a non-CVE vulnerability doesn't match any 'Expected Source Value' in your mapping table.

Review and Confirm

Review the configurations provided in the previous steps. Ensure all details are correct and complete. Confirm the setup to finalize the configuration of the API connector.

This streamlined process allows for efficient data integration, ensuring accuracy and consistency across systems.

Saving and Running the Connector

Save and run the connector to process the data accordingly, transforming and importing it as per the configurations set.

How Does a Connection Work?

The HCL AppScan connector functions through configured profiles that determine what data gets synchronized and when.

A connection usually involves creating a profile that defines which vulnerabilities to import based on detection data types and asset types. The connector then automatically executes according to the schedule (or on-demand), pulling vulnerability data from HCL AppScan into Qualys ETM where it can be viewed alongside other security findings.

With the HCL AppScan API Connector successfully configured, you are almost ready to view all the assets and findings of your HCL AppScan environment.

In the Connector screen, you can find your newly configured connector listed and marked in the Processed state.

Connector States

A successfully configured connector goes through the following four states:

  • Registered – The connector is successfully created and registered to fetch data from the vendor.

  • Scheduled – The connector is scheduled to execute a connection with the vendor.

  • Processing – A connection is executed and the connector is fetching the asset and findings data.

  • Processed – The connector has successfully fetched the assets; it may still be in the process of fetching the findings. Wait for some more time for the connector to fetch the findings completely.

The Processed state indicates that the connector is successfully configured but is still importing all your assets and findings. This process (specifically for findings) may take some time.

This entire process may take up to 2 hours for completion. Once complete, the imported data can be found in Enterprise TruRisk Management (ETM).

View Assets and Findings in ETM

Navigate to Enterprise TruRisk Management (ETM) to get started with analyzing your connector's vulnerability findings.

You can view the assets imported from the HCL AppScan connection by navigating to the Inventory tab in ETM.

Go to Assets > Application to find all of your imported assets.

Use the token: inventory: (source: HCL AppScan)to view all the imported HCL AppScan assets.

Here, you can learn about the criticality of your assets and their associated Risk Scores. Click any asset to find more details.

Next, you can navigate to the Risk Management tab to view your vulnerability findings.

Go to Findings > Vulnerability to view all discovered vulnerabilities.

Use the token: finding.vendorProductName: HCL AppScan to filter and view all the discovered HCL AppScan vulnerabilities.

The imported vulnerability findings from HCL AppScan provide rich context and integrate seamlessly with Qualys' native TruRisk scoring system. Use these findings in Qualys ETM to enhance your risk prioritization workflows and make informed security decisions.

To know more about ETM, refer to the Qualys ETM Documentation.

Additional Information

Additional information related to the HCL AppScan Connector.

API Reference

Here are the APIs executed for the HCL AppScan connection:

Name Endpoint Info
Auth API /api/v4/Account/ApiKeyLogin/ Authentication token is valid for 30 minutes and is auto-refreshed.
Fetch Applications /api/v4/Apps Default batch size: 50
API Limitations: (Pending)
Fetch Vulnerabilities /api/v4/Issues/Application/{ApplicationId} Default batch size: 50
API Limitations: (Pending)

Data Model Mapping

This section explains the attribute mappings of the values from HCL and Qualys ETM.

HCL AppScan Vulnerability Transformation Mapping

Source Attribute Key Target Attribute Label
apps.Url webAppUrl (Required)
apps.Name webAppName (Required)
Items[].Id externalFindingId (Required)
Items[].IssueType findingName (Required)
Items[].Cve cveId
Items[].CvssVersion cvss3Base
Items[].Cwe cweId
Items[].DateCreated findingFirstFoundOn
Items[].IssueXml detectionResult
Items[].LastFound findingLastFoundOn
Items[].Port findingPort
Items[].Scheme findingProtocol
Items[].IssueTypeId findingSubType
Items[].SeverityValue findingSeverity (Required)

Status

Open | In Progress | Noise | Fixed | Passed | Reopened

findingStatus

NEW | ACTIVE | NONE | FIXED | IGNORED | REOPENED

 

© Qualys , Inc. All rights reserved. Privacy Policy.