Release 3.3.2.0 API

January 10, 2025

Before understanding the API release highlights, learn more about the API server URL to be used in your API requests by referring to the Know Your Qualys API Server URL section. For this API Release Notes, <qualys_base_url> is mentioned in the sample API requests.

What's New?

New API - List Software Components for All Assets 

New or Updated API New
API Endpoint /rest/2.0/asset/component
Method POST 
DTD or XSD changes Not Applicable

With this release, we introduced a new API to get the list of all components discovered from the SwCA scan.  

Input ParametersInput Parameters

Parameter

Sub
Parameter

Mandatory
/Optional

Data Type

Description

pageSize

NA

Mandatory

Number

Provide the input for the page size between 1 to 1000. The default value is 500.

componentFilter component
.name
Optional String Provide the name of the component.
component
.version
Optional String Provide the version of the component.
component
.technology
Optional String Provide the technology used by the component.
assetSoftwareFilter NA Optional String All QQL tokens prefixed with asset and software are supported.
lastSeen
AssetComponentId
NA Optional Number You can see the value of the attribute assetComponentId at the last JSON object at the end of the API response. This value is a reference to fetch the asset-component details for the next page. For the first page request, this value is not required. After you get the response of the first page, this value should be added to the API request to get the next page of the asset-component details.

Sample - List of Software Components for All AssetsSample - List of Software Components for All Assets

API Request - without parameter

curl --location --request POST 
'<qualys_base_url>/rest/2.0/asset/component?pageSize=500' 
--header 'Authorization: Bearer <JWT Token>' 
--header 'Content-Type: application/json'

API Request - with parameter

curl --location --request POST 
'<qualys_base_url>/rest/2.0/asset/component?pageSize=500&lastSeenAssetComponentId=1735285554060' 
--header 'Authorization: Bearer <JWT Token>' 
--header 'Content-Type: application/json' 
--data-raw '<AssetSoftwareComponentFilterRequest>'

API Request - with parameter example

curl --location --request POST 
'<qualys_base_url>/rest/2.0/asset/component?pageSize=500&lastSeenAssetComponentId=1735285554060' 
--header 'Authorization: Bearer <JWT Token>' 
--header 'Content-Type: application/json' 
--data-raw '<AssetSoftwareComponentFilterRequest>'

API Request Body - with component filter

<AssetSoftwareComponentFilterRequest>
    <componentFilter>
        <filters>
            <criteria field="component.name" operator="EQUALS">
                <value>log4j</value>
            </criteria>
        </filters>
    </componentFilter>
</AssetSoftwareComponentFilterRequest>

API Request Body - with assetSoftware filter

<AssetSoftwareComponentFilterRequest>
    <assetSoftwareFilter>
        <filters>
            <criteria field="asset.riskScore" operator="GREATER">
                <value>800</value>
            </criteria>
        </filters>
    </assetSoftwareFilter>
</AssetSoftwareComponentFilterRequest>

The following filter example states that the response will include all components with the name "log4j" on assets with asset.riskScore greater than 800. The AND operation is performed between componentFilter and assetSoftwareFilter.

API Request Body - component and assetSoftware filters

<AssetSoftwareComponentFilterRequest>
    <componentFilter>
        <filters>
            <criteria field="component.name" operator="EQUALS">
                <value>log4j</value>
            </criteria>
        </filters>
    </componentFilter>
    <assetSoftwareFilter>
        <filters>
            <criteria field="asset.riskScore" operator="GREATER">
                <value>800</value>
            </criteria>
        </filters>
    </assetSoftwareFilter>
</AssetSoftwareComponentFilterRequest>

API Request Body - with multiple combinations of component and assetSoftware filters

<AssetSoftwareComponentFilterRequest>
    <componentFilter operation="AND">
        <filters>
            <criteria field="component.name" operator="EQUALS">
                <value>log4j</value>
            </criteria>
            <criteria field="component.technology" operator="EQUALS">
                <value>Java</value>
            </criteria>
        </filters>
    </componentFilter>
    <assetSoftwareFilter operation="AND">
        <filters>
            <criteria field="asset.riskScore" operator="GREATER">
                <value>800</value>
            </criteria>
            <criteria field="operatingSystem" operator="EQUALS">
                <value>Windows</value>
            </criteria>
            <criteria field="software.lifecycle.stage" operator="EQUALS">
                <value>EOL/EOS</value>
            </criteria>
        </filters>
    </assetSoftwareFilter>
</AssetSoftwareComponentFilterRequest>

API Response

{
  "responseMessage": "Valid API Access",
  "count": 4,
  "responseCode": "SUCCESS",
  "hasMore": 1,
  "lastAssetComponentId": 1735285554060,
  "assetComponentsList": [
    {
      "assetId": 40338595,
      "component": {
        "assetComponentId": 1735285554050,
        "name": "apache-common-utils",
        "version": "1.1",
        "technology": ".NET",
        "installPath": "/usr/bin/apache-http/1.1/lib",
        "firstFoundAt": 1733129365228,
        "lastFoundAt": 1733129366228
      }
    },
    ...
    {
      "assetId": 51449686,
      "component": {
        "assetComponentId": 1735285554060,
        "name": "apache-common-utils",
        "version": "2.2",
        "technology": ".NET",
        "installPath": "/opt/apache/bin/apache-http/2.2/lib",
        "firstFoundAt": 1733129367228,
        "lastFoundAt": 1733129367228
      }
    }
  ]
}

Response codes

  • responseCode= "200", description= "SUCCESS"
  • responseCode= "204", description= "NO_CONTENT: The server has not found anything matching the Request"
  • responseCode= "400", description= "The request could not be understood by the server due to malformed syntax"
  • responseCode= "500", description= "Failure: The server encountered an unexpected condition which prevented it from fulfilling the request"

New API - List Software Components for Specific Asset ID

New or Updated API New
API Endpoint /rest/2.0/asset/component/{assetId}
Method POST
DTD or XSD changes Not Applicable

With this release, we have introduced a new API to get the list of software components for a specific assetId discovered from the SwCA scan. 

Input ParametersInput Parameters

Parameter

Mandatory
/Optional

Data Type

Description

assetId Mandatory String Provide the assetId. You get the list of components for the assetId you provide.
pageSize Mandatory Number Provide the input for the page size between 1 to 1000. The default value is 500.
lastSeenAssetComponentId Optional Number You can see the value of the attribute assetComponentId at the last JSON object at the end of the API response. This value is a reference to fetch the asset-component details for the next page. For the first page request, this value is not required. After you get the response of the first page, this value should be added to the API request to get the next page of the asset-component details.

Sample - List of Software Components for Specific AssetIDSample - List of Software Components for Specific AssetID        

API Request - without filter

curl --location --request POST 
'<qualys_base_url>/rest/2.0/asset/component/{assetId}?pageSize=500&lastSeenAssetComponentId=1735285554061' 
--header 'Authorization: Bearer <JWT Token>' 
--header 'Content-Type: application/json'

API Request - with filter

curl --location --request POST 
'<qualys_base_url>/rest/2.0/asset/component/51449686?pageSize=500&lastSeenAssetComponentId=1735285554061' 
--header 'Authorization: Bearer <JWT Token>' 
--header 'Content-Type: application/json' 
--data-raw '<SoftwareComponentFilterRequest>'

API Request Body - with component filter

<SoftwareComponentFilterRequest>
    <componentFilter>
        <filters>
            <criteria field="component.name" operator="EQUALS">
                <value>log4j</value>
            </criteria>
        </filters>
    </componentFilter>
</SoftwareComponentFilterRequest>

API Request Body - with Software filter

<SoftwareComponentFilterRequest>
    <softwareFilter>
        <filters>
            <criteria field="software.lifecycle.stage" operator="EQUALS">
                <value>EOL/EOS</value>
            </criteria>
        </filters>
    </softwareFilter>
</SoftwareComponentFilterRequest>

The following filter example states that the response will include all components with the name "log4j" on assets with asset.riskScore greater than 800. The AND operation is performed between componentFilter and assetSoftwareFilter.

API Request Body - component and assetSoftware filters

<SoftwareComponentFilterRequest>
    <componentFilter>
        <filters>
            <criteria field="component.name" operator="EQUALS">
                <value>log4j</value>
            </criteria>
        </filters>
    </componentFilter>
    <softwareFilter>
        <filters>
            <criteria field="software.lifecycle.stage" operator="EQUALS">
                <value>EOL/EOS</value>
            </criteria>
        </filters>
    </softwareFilter>
</SoftwareComponentFilterRequest>

API Request Body - with multiple combinations of component and software filters

<SoftwareComponentFilterRequest>
    <componentFilter operation="AND">
        <filters>
            <criteria field="component.name" operator="EQUALS">
                <value>log4j</value>
            </criteria>
            <criteria field="component.technology" operator="EQUALS">
                <value>Java</value>
            </criteria>
        </filters>
    </componentFilter>
    <softwareFilter operation="OR">
        <filters>
            <criteria field="software.authorization" operator="EQUALS">
                <value>Unauthorized</value>
            </criteria>
            <criteria field="operatingSystem" operator="EQUALS">
                <value>Windows</value>
            </criteria>
            <criteria field="software.lifecycle.stage" operator="EQUALS">
                <value>EOL/EOS</value>
            </criteria>
        </filters>
    </softwareFilter>
</SoftwareComponentFilterRequest>

API Response

{
  "responseMessage": "Valid API Access",
  "count": 2,
  "responseCode": "SUCCESS",
  "hasMore": 1,
  "lastAssetComponentId": 1735285554061,
  "assetId": 51449686,
  "componentsList": [
    {
      "assetComponentId": 1735285554060,
      "name": "apache-common-utils",
      "version": "2.2",
      "technology": ".NET",
      "installPath": "/opt/apache/bin/apache-http/2.2/lib",
      "firstFoundAt": 1733129367228,
      "lastFoundAt": 1733129367228
    },
    {
      "assetComponentId": 1735285554061,
      "name": "apache-common-utils",
      "version": "2.3",
      "technology": ".NET",
      "installPath": "/opt/apache/bin/apache-http/2.3/lib",
      "firstFoundAt": 1733129367228,
      "lastFoundAt": 1733129367228
    }
  ]
}

Response codes

  • responseCode= "200", description= "SUCCESS"
  • responseCode= "204", description= "NO_CONTENT: The server has not found anything matching the Request"
  • responseCode= "400", description= "The request could not be understood by the server due to malformed syntax"
  • responseCode= "500", description= "Failure: The server encountered an unexpected condition which prevented it from fulfilling the request"