Querying the Servers Affected by a Vulnerability

Function

This API is used to query the servers affected by a vulnerability.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, no identity policy-based permission required for calling this API.

URI

GET /v5/{project_id}/vulnerability/hosts

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID, which is used to specify the project that an asset belongs to. After the project ID is configured, you can query assets in the project using the project ID. For details about how to obtain it, see Obtaining a Project ID. Constraints N/A Range The value can contain 1 to 256 characters. Default Value N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
enterprise_project_id	No	String	Definition Enterprise project ID, which is used to filter assets in different enterprise projects. For details, see Obtaining an Enterprise Project ID. To query assets in all enterprise projects, set this parameter to all_granted_eps. Constraints You need to set this parameter only after the enterprise project function is enabled. Range The value can contain 1 to 256 characters. Default Value 0: default enterprise project.
limit	No	Integer	Definition Number of records displayed on each page. Constraints N/A Range Value range: 10-200 Default Value 10
offset	No	Integer	Definition Offset, which specifies the start position of the record to be returned. Constraints N/A Range The value range is 0 to 2,000,000. Default Value The default value is 0.
host_name	No	String	Definition Server name. Constraints N/A Range The value contains 1 to 256 characters. Default Value N/A
host_ip	No	String	Definition Server IP address Constraints N/A Range The value can contain 1 to 256 characters. Default Value N/A
vul_id	Yes	String	Definition Vulnerability ID. Constraints N/A Range The value can contain 0 to 64 characters. Default Value N/A
type	Yes	String	Definition Vulnerability type to be queried. Constraints N/A Range linux_vul: Linux vulnerability windows_vul: windows vulnerability web_cms: Web-CMS vulnerability app_vul: application vulnerability urgent_vul: emergency vulnerability Default Value N/A
status	No	String	Definition Vulnerability status. Constraints N/A Range vul_status_unfix: not handled vul_status_ignored: ignored vul_status_verified: verification in progress vul_status_fixing: fixing vul_status_fixed: fixed vul_status_reboot: fixed and pending restart vul_status_failed: fix failed vul_status_fix_after_reboot: Restart the server and try again. Default Value N/A
asset_value	No	String	Definition Asset importance. Constraints N/A Range important common test Default Value N/A
group_name	No	String	Definition Server group name. Constraints N/A Range The value can contain 0 to 256 characters. Default Value N/A
handle_status	No	String	Definition Vulnerability handling status. Constraints N/A Range unhandled handled Default Value N/A
severity_level	No	String	Definition Severity (risk level). Constraints N/A Range Critical: The CVSS score of the vulnerability is greater than or equal to 9, corresponding to the high risk level on the console. High: The CVSS score of the vulnerability is greater than or equal to 7 and less than 9, corresponding to the medium risk level on the console. Medium: The CVSS score of the vulnerability is greater than or equal to 4 and less than 7, corresponding to the medium risk level on the console. Low: The CVSS score of the vulnerability is less than 4, corresponding to the low risk level on the console. You can use commas (,) to separate multiple values. Default Value N/A
is_affect_business	No	Boolean	Definition Whether services are affected. Constraints N/A Range true: Services are affected. false: Services are not affected. Default Value N/A
repair_priority	No	String	Definition Fixing priority. Constraints N/A Range Critical High Medium Low You can use commas (,) to separate multiple values. Default Value N/A
cluster_name	No	String	Definition Cluster name. Constraints N/A Range The value can contain 1 to 64 characters. Default Value N/A
cluster_id	No	String	Definition Cluster ID. Constraints N/A Range The value can contain 1 to 64 characters. Default Value N/A
is_container	No	Boolean	Definition Whether it is the container scenario. Constraints N/A Range true: container scenario false: non-container scenario Default Value false
container_name	No	String	Definition Container name (valid in container scenarios). Constraints N/A Range The value can contain 0 to 128 characters. Default Value N/A
min_scan_time	No	Long	Definition Minimum start time of a scan task (valid in container scenarios). Constraints N/A Range Minimum value: 0; maximum value: 2^63-1 Default Value N/A
max_scan_time	No	Long	Definition Maximum start time of a scan task (valid in container scenarios). Constraints N/A Range Minimum value: 0; maximum value: 2^63-1 Default Value N/A

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token, which contains user identity and permissions. The token can be used for identity authentication when an API is called. For details about how to obtain the token, see Obtaining a User Token. Constraints N/A Range The value can contain 1 to 32,768 characters. Default Value N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
total_num	Integer	Definition Number of affected cloud servers. Range The value range is 0 to 10,000.
data_list	Array of VulHostInfo objects	Definition List of affected cloud servers. Range The value range is 1 to 10,000.

**Table 5** VulHostInfo
Parameter	Type	Description
host_id	String	Definition ID of the server affected by a vulnerability. Range The value can contain 1 to 128 characters.
agent_id	String	Definition Agent ID of a server. Range The value can contain 1 to 128 characters.
repair_necessity	String	Definition Repair urgency. Range Critical: The CVSS score of the vulnerability is greater than or equal to 9, corresponding to the high risk level on the console. High: The CVSS score of the vulnerability is greater than or equal to 7 and less than 9, corresponding to the medium risk level on the console. Medium: The CVSS score of the vulnerability is greater than or equal to 4 and less than 7, corresponding to the medium risk level on the console. Low: The CVSS score of the vulnerability is less than 4, corresponding to the low risk level on the console.
severity_level	String	Definition Severity. Range Critical: The CVSS score of the vulnerability is greater than or equal to 9, corresponding to the high risk level on the console. High: The CVSS score of the vulnerability is greater than or equal to 7 and less than 9, corresponding to the medium risk level on the console. Medium: The CVSS score of the vulnerability is greater than or equal to 4 and less than 7, corresponding to the medium risk level on the console. Low: The CVSS score of the vulnerability is less than 4, corresponding to the low risk level on the console.
host_name	String	Definition Name of an affected server. Range The value can contain 1 to 256 characters.
host_ip	String	Definition IP address of an affected server. Range The value can contain 1 to 256 characters.
cve_num	Integer	Definition Number of vulnerability CVEs. Range The value range is 0 to 10,000.
cve_id_list	Array of strings	Definition CVE ID list of vulnerabilities. Range The value range is 1 to 10,000.
status	String	Definition Vulnerability status. Range vul_status_unfix: not fixed vul_status_ignored: ignored vul_status_verified: verification in progress vul_status_fixing: fixing vul_status_fixed: fixed vul_status_reboot: fixed and pending restart vul_status_failed: fix failed vul_status_fix_after_reboot: Restart the server and try again.
remark	String	Definition Handling remarks. Range The value can contain 1 to 65,535 characters.
repair_cmd	String	Definition Command line to be executed to fix the vulnerability. (This field is available only for Linux vulnerabilities.) Range The value can contain 1 to 256 characters.
version	String	Definition Edition of a quota bound to a server. Range The value can contain 1 to 128 characters.
app_path	String	Definition Path of the application software. (This field is available only for application vulnerabilities.) Range The value can contain 1 to 512 characters.
is_affect_business	Boolean	Definition Whether services are affected. Range true: Services are affected. false: Services are not affected.
asset_value	String	Definition Asset importance. Range important: important asset common: common asset test: test asset
private_ip	String	Definition Server private IP address. Range The value can contain 0 to 128 characters.
group_name	String	Definition Server group name. Range The value can contain 0 to 256 characters.
group_id	String	Definition Server group ID. Range The value can contain 0 to 128 characters.
os_type	String	Definition OS type. Range Linux Windows
os_name	String	Definition OS name. Range The value can contain 1 to 256 characters.
os_version	String	Definition OS version. Range The value can contain 1 to 255 characters.
os_kernel	String	Definition OS kernel. Range The value can contain 1 to 64 characters.
host_status	String	Definition Server status. Range ACTIVE: running SHUTOFF: shut down BUILDING: creating ERROR: faulty Default Value N/A
first_scan_time	Long	Definition First scan time. Range The value range is 0 to 9,223,372,036,854,775,807.
scan_time	Long	Definition Scan time, in ms. Range The value range is 0 to 9,223,372,036,854,775,807.
failed_reason	String	Definition Cause of fix failure. Range The value can contain 1 to 65,535 characters.
support_restore	Boolean	Definition Whether data can be rolled back to the backup created when the vulnerability is fixed. Range true: Rollback is allowed. false: Rollback is not allowed.
backup_name	String	Definition Backup name. Range The value contains 1 to 2,048 characters.
agent_status	String	Definition Agent status. Range installed not_installed online offline install_failed installing
disabled_operate_types	Array of disabled_operate_types objects	Definition List of operation types that cannot be performed on the current server. Range The value range is 1 to 10,000.
repair_priority	String	Definition Fixing priority. Its value can be: Range Critical High Medium Low**

**Table 6** disabled_operate_types
Parameter	Type	Description
operate_type	String	Definition Operation type. Range ignore: ignore not_ignore: unignore immediate_repair: fix manual_repair: manual fix verify add_to_whitelist
reason	String	Definition Reason why an operation cannot be performed. Range The value can contain 0 to 512 characters.

Example Requests

Query the first 10 records in the list of servers with EulerOS-SA-2021-1894 vulnerability.

GET https://{endpoint}/v5/2b31ed520xxxxxxebedb6e57xxxxxxxx/vulnerability/hosts?vul_id=EulerOS-SA-2021-1894&offset=0&limit=10

Example Responses

Status code: 200

Request succeeded.

{
  "total_num" : 1,
  "data_list" : [ {
    "host_id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "severity_level" : "Low",
    "host_name" : "ecs",
    "host_ip" : "xxx.xxx.xxx.xxx",
    "agent_id" : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "version" : "hss.version.enterprise",
    "cve_num" : 1,
    "cve_id_list" : [ "CVE-2022-1664" ],
    "status" : "vul_status_ignored",
    "repair_cmd" : "zypper update update-alternatives",
    "app_path" : "/root/apache-tomcat-8.5.15/bin/bootstrap.jar",
    "support_restore" : true,
    "disabled_operate_types" : [ {
      "operate_type" : "immediate_repair",
      "reason" : "The kernel vulnerability of CCE container node cannot be automatically fixed."
    } ],
    "repair_priority" : "Critical"
  } ]
}