Querying ECSs

Function

This API is used to query ECSs.

URI

GET /v5/{project_id}/host-management/hosts

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
enterprise_project_id	No	String	Enterprise project ID. To query all enterprise projects, set this parameter to all_granted_eps.
version	No	String	HSS edition. Its value can be: hss.version.null hss.version.basic: basic edition hss.version.advanced: professional edition hss.version.enterprise: enterprise edition hss.version.premium: premium edition hss.version.wtp: WTP edition hss.version.container.enterprise: container edition
agent_status	No	String	Agent status. Its value can be: not_installed online offline install_failed installing not_online: All status except online, which is used only as a query condition.
detect_result	No	String	Detection result. Its value can be: undetected clean risk scanning
host_name	No	String	Server name
host_id	No	String	Server ID
host_status	No	String	Host status. Its value can be: ACTIVE SHUTOFF BUILDING ERROR
os_type	No	String	OS type. Its value can be: Linux Windows
private_ip	No	String	Server private IP address
public_ip	No	String	Server public IP address
ip_addr	No	String	Public or private IP address
protect_status	No	String	Protection status. Its value can be: closed opened
group_id	No	String	Server group ID
group_name	No	String	Server group name
has_intrusion	No	Boolean	Alarms exist.
policy_group_id	No	String	Policy group ID
policy_group_name	No	String	Policy group name
charging_mode	No	String	Billing mode. Its value can be: on_demand: pay-per-use
refresh	No	Boolean	Whether to forcibly synchronize servers from ECSs
above_version	No	Boolean	Whether to return all the versions later than the current version
outside_host	No	Boolean	Cloud server or not
asset_value	No	String	Asset importance. Its value can be: important common test
label	No	String	Asset tag
server_group	No	String	Asset server group
agent_upgradable	No	Boolean	Whether the agent can be upgraded
limit	No	Integer	Number of records on each page
offset	No	Integer	Offset, which specifies the start position of the record to be returned.

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is a token.
region	No	String	Region ID

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
total_num	Integer	Total number of records
data_list	Array of Host objects	Query on the cloud server status and list

**Table 5** Host
Parameter	Type	Description
host_name	String	Server name
host_id	String	Server ID
agent_id	String	Agent ID
private_ip	String	Private IP address
public_ip	String	Elastic IP address
enterprise_project_id	String	Enterprise project ID
enterprise_project_name	String	Enterprise project name
host_status	String	Server status. Its value can be: ACTIVE SHUTOFF BUILDING ERROR
agent_status	String	Agent status. Its value can be: not_installed online offline install_failed installing
install_result_code	String	Installation result. Its value can be: install_succeed network_access_timeout: Connection timed out. Network error. invalid_port auth_failed: The authentication failed due to incorrect password. permission_denied: Insufficient permissions. no_available_vpc: There are no servers with an online agent in the current VPC. install_exception invalid_param install_failed package_unavailable os_type_not_support: Incorrect OS type os_arch_not_support: Incorrect OS architecture
version	String	HSS edition. Its value can be: hss.version.null: none hss.version.basic: basic edition hss.version.advanced: professional edition hss.version.enterprise: enterprise edition hss.version.premium: premium edition hss.version.wtp: WTP edition hss.version.container.enterprise: container edition
protect_status	String	Protection status. Its value can be: closed opened
os_image	String	System disk image
os_type	String	OS type. Its value can be: Linux Windows
os_bit	String	OS bit version
detect_result	String	Server scan result. Its value can be: undetected clean risk scanning
expire_time	Long	Expiration time of the trial version. (The value -1 indicates that the quota is non-trial version. If the value is not -1, the value indicates the expiration time of the trial version.)
charging_mode	String	Billing mode. Its value can be: on_demand: pay-per-use
resource_id	String	Cloud service resource instance ID (UUID)
outside_host	Boolean	Whether a server is on-premises
group_id	String	Server group ID
group_name	String	Server group name
policy_group_id	String	Policy group ID
policy_group_name	String	Policy group name
asset	Integer	Asset risk
vulnerability	Integer	Total number of vulnerabilities, including Linux, Windows, Web-CMS, and application vulnerabilities.
baseline	Integer	Total number of baseline risks, including configuration risks and weak passwords.
intrusion	Integer	Total intrusion risks
asset_value	String	Asset importance. Its value can be: important common test
labels	Array of strings	Tag list
agent_create_time	Long	Agent installation time, which is a timestamp. The default unit is milliseconds.
agent_update_time	Long	Time when the agent status is changed. This is a timestamp. The default unit is milliseconds.
agent_version	String	Agent version
upgrade_status	String	Upgrade status. Its value can be: not_upgrade: Not upgraded. This is the default status. The customer has not delivered any upgrade command to the server. upgrading: The upgrade is in progress. upgrade_failed: The upgrade failed. upgrade_succeed
upgrade_result_code	String	Upgrade failure cause. This parameter is displayed only if upgrade_status is upgrade_failed. Its value can be: package_unavailable: The upgrade package fails to be parsed because the upgrade file is incorrect. network_access_timeout: Failed to download the upgrade package because the network is abnormal. agent_offline: The agent is offline. hostguard_abnormal: The agent process is abnormal. insufficient_disk_space: The disk space is insufficient. failed_to_replace_file: Failed to replace the file.
upgradable	Boolean	Whether the agent of the server can be upgraded
open_time	Long	Time when the protection is enabled. This is a timestamp. The default unit is milliseconds.
protect_interrupt	Boolean	Whether protection is interrupted

Example Requests

Query the 10 Linux servers in all enterprise projects whose agent status is online.

GET https://{endpoint}/v5/{project_id}/host-management/hosts?limit=10&offset=0&agent_status=online&os_type=Linux&enterprise_project_id=all_granted_eps

Example Responses

Status code: 200

Request succeeded.

{
  "total_num" : 1,
  "data_list" : [ {
    "agent_id" : "2758d2a61598fd9144cfa6b201049e7c0af8c3f1280cd24e3ec95a2f0811a2a2",
    "agent_status" : "online",
    "asset" : 0,
    "asset_value" : "common",
    "baseline" : 0,
    "charging_mode" : "on_demand",
    "detect_result" : "risk",
    "enterprise_project_id" : "all_granted_eps",
    "enterprise_project_name" : "default",
    "group_id" : "7c659ea3-006f-4687-9f1c-6d975d955f37",
    "group_name" : "default",
    "host_id" : "caa958ad-a481-4d46-b51e-6861b8864515",
    "host_name" : "ecs-r00431580-ubuntu",
    "host_status" : "ACTIVE",
    "intrusion" : 0,
    "expire_time" : -1,
    "os_bit" : "64",
    "os_type" : "Linux",
    "outside_host" : false,
    "policy_group_id" : "2758d2a61598fd9144cfa6b201049e7c0af8c3f1280cd24e3ec95a2f0811a2a2",
    "policy_group_name" : "wtp_ecs-r00431580-ubuntu(default)",
    "private_ip" : "192.168.0.182",
    "protect_status" : "opened",
    "protect_interrupt" : false,
    "public_ip" : "100.85.123.9",
    "resource_id" : "60f08ea4-c74e-4a45-be1c-3c057e373af2",
    "version" : "hss.version.wtp",
    "vulnerability" : 97,
    "labels" : [ "" ],
    "agent_create_time" : 0,
    "agent_update_time" : 0,
    "open_time" : 0
  } ]
}