Custom Assessment and Remediation Release 2.5 API

April 07, 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.

Updated API: Execute Script API

New or Updated API	Updated
API Endpoint	/sm/v1/scripts/{scriptId}/execute
Method	POST
DTD or XSD changes	Not Applicable

We have updated this API to simplify script execution on lab assets. You can now provide lab asset tags instead of individual assets in the API request to execute scripts on lab assets.

When executing a script on lab assets in evaluation mode, make sure the testMode parameter value is set to true. This ensures that the script executes in a non-production environment.

New Input Parameters in the Execute Script APINew Input Parameters in the Execute Script API

Parameter	Mandatory/ Optional	Data Type	Description
testTags	Optional (Mandatory when `testMode` is `true`)	List	It includes the list of lab tag IDs and UUIDs.
id	Optional (Mandatory when `testMode` is `true`)	String	Provide the identification number of the lab tag.
UUId	Optional (Mandatory when `testMode` is `true`)	String	Provide the UUID of the lab tag.

You can fetch the lab asset tags id and UUid using the Fetch Asset Tags List API.

Sample: Execute Script on the Lab Assets using Lab Asset TagsSample: Execute Script on the Lab Assets using Lab Asset Tags

API Request

curl -X POST 
'<qualys_base_url>/sm/v1/scripts/{scriptId}/execute'
--header 'accept: application/json'
--header 'Content-Type: application/json'
--data '{
  "testMode": true,
  "testTags": [
    {
      "id": "7512812",
      "UUId": "a3258427-cce3-4459-9cad-81dcdb1cb33e"
    }
  ],
  "user": {
    "id": "f0bbece3-a15d-f536-83c4-aed67c7f0b9b",
    "name": "Username"
  },
  "executionPolicyBypassEnabled": false,
  "description": "Sample description",
  "rebootAfterScriptExecution": false,
  "rebootDelayInSeconds": null,
  "rebootDelayTimeUnit": null
}'

API Response

{
  "body": {
      "correlationUuid": "81761e17-470b-40ab-89db-ef02607e00ab"
  }
}

Updated API: Fetch Asset Tags List API

New or Updated API	Updated
API Endpoint	/sm/v1/assettags/search
Method	POST
DTD or XSD changes	Not Applicable

We have updated this API to fetch the list of lab asset tags. A new flag, labTag, has been added to the API to fetch the list of lab asset tags. You need to include the filter value as (labTag:true) in the API request.

Input ParameterInput Parameter

Parameter Mandatory/
Optional Data Type Description

filter

Parameter	Mandatory/ Optional	Data Type	Description
filter	Optional (Mandatory when you want to fetch lab asset tags)	String	Provide the value as, `(labTag:true)`: to fetch lab asset tags list. `(labTag:false)`: to fetch list of asset tags other than lab asset tags. By default the value of `labTag` is `false`.
pageSize	Optional	Integer	Provide the maximum number of lab asset tags you want to fetch.
pageNumber	Optional	Integer	Provide the page index for pagination.

Optional

(Mandatory when you want to fetch lab asset tags)

String

Provide the value as,

(labTag:true): to fetch lab asset tags list.
(labTag:false): to fetch list of asset tags other than lab asset tags.

By default the value of labTag is false.

pageSize Optional Integer Provide the maximum number of lab asset tags you want to fetch.

pageNumber Optional Integer Provide the page index for pagination.

Sample: Fetch Lab Asset Tags ListSample: Fetch Lab Asset Tags List

API Request

curl -X POST
'<qualys_base_url>/sm/v1/assettags/search'
--header 'accept: application/json'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <authToken>'
--data '{
  "filter": "(labTag:true)",
  "pageSize": 50,
  "pageNumber": 0
}'

API Response

{
  "body": {
    "totalCount": 1,
    "list": [
      {
        "sortValues": [],
        "data": {
          "customerUuid": "74c1bcdd-9bbb-e9dd-802a-65e2c579abc0",
          "tagId": 28902062,
          "customerId": 1076635,
          "name": "Tag name",
          "tagUuid": "3dff19c9-e7cc-4e41-91f9-c324c850dfa9",
          "id": "28902062",
          "labTag": true,
          "addedToGlobalExclusion": false
        }
      }
    ]
  }
}

Updated API: Create Script API

New or Updated API	Updated
API Endpoint	/sm/v5/script
Method	POST
DTD or XSD changes	Not Applicable

We have updated this API to add support for Custom QID detection based on the script output. To support this functionality, new input parameters have been introduced.

New Input Parameters in the Create Scripts APINew Input Parameters in the Create Scripts API

Parameter	Sub-parameter	Mandatory/ Optional	Data Type	Description
detectionRegex		Optional	List	Contains the cardinality and regular expression values.
	cardinality	Optional	String	Provide a cardinality value. The values are: CONTAINS DOES_NOT_CONTAIN INTERSECT MATCHES IS_CONTAINED_IN CUSTOM_REGEX
	regex	Optional	List of string	Provide regular expression values. These values are evaluated on script output to mark a Custom QID Detected or Not-Detected.
	status	Optional	String	Provide the custom QID detection status values. The supported values are: Detected Not-detected

When specifing the regex values for cardinalities, follow these guidelines:

CONTAINS, DOES_NOT_CONTAIN, INTERSECT, and IS_CONTAINED_IN: Provide a list of string values.
MATCHES: Provide only one string value.
CUSTOM_REGEX: Provide only one regex value.

Sample: Create Script to Detect Custom QID Based on the Script OutputSample: Create Script to Detect Custom QID Based on the Script Output

API Request

curl -X POST
'<qualys_base_url>/sm/v5/script'
--header 'Accept: application/vnd.qualys.car.api.v5.0+json'
--header 'Authorization: Bearer <authToken>'
--header 'Content-Type: application/json'
--data-raw
'{
    "categoryId": 605,
    "content": "bHMgLWx0cg==",
    "description": "sample description",
    "platform": "WINDOWS",
    "severity": "3",
    "threshold":300,
    "thresholdTimeUnit": "SECOND",
    "title": "Sample title",
    "typeId": 2,
    "languageId": 204,
    "scriptApprovalUserConsent": true,
    "hasParameters": true,
    "customQid": {
        "title": "Sample QID title",
        "type": "Detection QID",
        "severity": "4",
        "qds": "75",
        "vulnerabilityType": "Information_Gathered",
        "cveIds": "CVE-2023-3452",
        "detectionLogic": "Use Script",
        "detectionRegex": {
            "cardinality": "CONTAINS",
            "regex": [
               "3.6.9"
               ],
            "status": "detected"
              },
    "params": [
        {
            "key": "string",
            "value": "string"
        }
    ]
}'

API Response

{
  "errorCode": "0",
  "message": "Script created successfully",
  "body": {
    "id": 213673
  }
}

Updated API: Update Scripts API

New or Updated API	Updated
API Endpoint	/sm/v4/script/{ScriptId}
Method	PATCH
DTD or XSD changes	Not Applicable

We have updated this API to add support for Custom QID detection based on the script output. You can use this API to update new parameters as required.

New Input Parameters in the Update Scripts APINew Input Parameters in the Update Scripts API

Parameter	Sub-parameter	Mandatory/ Optional	Data Type	Description
detectionRegex		Optional	List	Contains the cardinality and regular expression values.
	cardinality	Optional	String	Provide a cardinality value. The values are: CONTAINS DOES_NOT_CONTAIN INTERSECT MATCHES IS_CONTAINED_IN CUSTOM_REGEX
	regex	Optional	List	Provide regular expression values. These values are evaluated on script output to mark a Custom QID Detected or Not-Detected.
	status	Optional	String	Provide the custom QID detection status values. The supported values are: Detected Not-detected

Sample: Update script to modify the "detectionRegex" valuesSample: Update script to modify the "detectionRegex" values

API Request

curl -X PATCH
'<qualys_base_url>/sm/v4/script/{Scriptid}'
--header 'Accept: application/vnd.qualys.car.api.v4.0+json'
--header 'Authorization: Bearer <authToken>'
--header 'Content-Type: application/json'
--data-raw 
'{
    "categoryId": 605,
    "content": "bHMgLWx0cg==",
    "description": "sample description",
    "platform": "WINDOWS",
    "severity": "3",
    "threshold":300,
    "thresholdTimeUnit": "SECOND",
    "title": "Sample title",
    "typeId": 2,
    "languageId": 204,
    "scriptApprovalUserConsent": true,
    "hasParameters": true,
    "customQid": {
        "title": "Sample QID title",
        "type": "Detection QID",
        "severity": "4",
        "qds": "75",
        "vulnerabilityType": "Information_Gathered",
        "cveIds": "CVE-2023-3452",
        "detectionLogic": "Use Script",
        "detectionRegex": {
            "cardinality": "CONTAINS",
            "regex": [
               "3.6.9"
               ],
            "status": "detected"
              },
    "params": [
        {
            "key": "string",
            "value": "string"
        }
    ]
}'

API Response

{
  "id": 213673,
  "message": "Updated Successfully."
}

New API: Add Tags to Lab Asset Tags List API

New or Updated API	New
API Endpoint	/sm/v1/lab-tags
Method	POST
DTD or XSD changes	Not Applicable

Use this API to add existing asset tags to the lab asset tags list, which can then be used in the Execute Scripts API to test scripts on lab assets.

Input ParametersInput Parameters

Parameter	Sub-parameter	Mandatory/ Optional	Data Type	Description
ids		Mandatory	List	Provide the list of tag IDs.
user		Optional	String	Provide the details of a user such as ID and name.
	id	Optional	String	Provide the ID of the user.
	name	Optional	String	Provide the name of the user.

Sample: Add Tags to Lab Asset Tags ListSample: Add Tags to Lab Asset Tags List

API Request

curl -X POST
'<qualys_base_url>/sm/v1/lab-tags'
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d '{
  "ids": [4561,4562],
   "user": {
      "id": "bfd96a2f-854b-f8fd-8005-69374a3cd2b3",
      "name": "Username"
      }
    }'

API Response

{
  "body": {
    "success": {
      "ids": [
        4561
      ],
      "message": "Ids are processed"
    },
    "failure": {
      "ids": [
        4562
      ],
      "message": "Ids are Invalid"
    }
  }
}

New API: Remove Tags form Lab Asset Tags List API

New or Updated API	New
API Endpoint	/sm/v1/lab-tags/delete
Method	POST
DTD or XSD changes	Not Applicable

Use this API to remove asset tags from the lab asset tags list, ensuring they are no longer available for use in the Execute Scripts API for testing scripts on lab assets.

Input ParametersInput Parameters

Parameter	Sub-parameter	Mandatory/ Optional	Data Type	Description
ids		Mandatory	List	Provide the list of tag IDs.
user		Optional	String	Provide the details of a user such as ID or name.
	id	Optional	String	Provide the ID of the user.
	name	Optional	String	Provide the name of the user.

Sample: Remove Tags from Lab Asset TagsSample: Remove Tags from Lab Asset Tags

API Request

curl -X POST
'<qualys_base_url>/sm/v1/lab-tags/delete'
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d '{
   "ids": [4561,4562],
   "user": {
      "id": "bfd96a2f-854b-f8fd-8005-69374a3cd2b3",
      "name": "Username"
      }
    }'

API Response

{
  "body": {
    "success": {
      "ids": [
        4561
      ],
      "message": "Ids are processed"
    },
    "failure": {
      "ids": [
        4562
      ],
      "message": "Ids are Invalid"
    }
  }
}