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 |
Mandatory |
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 |
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"