Getting Started with the Assets GraphQL API
Important
Before proceeding, complete the API Authentication steps in order to obtain a working client_id
and client_secret
.
Regions
The URL to access XDR APIs may differ according to the region your environment is deployed in:
- US1—
https://api.ctpx.secureworks.com
- US2—
https://api.delta.taegis.secureworks.com
- US3—
https://api.foxtrot.taegis.secureworks.com
- EU—
https://api.echo.taegis.secureworks.com
The examples in this XDR API documentation use https://api.ctpx.secureworks.com
throughout. If you are in a different region substitute appropriately.
Working with Assets ⫘
Most asset types share a common set of fields as defined in the schema.
type Asset implements Node {
id: ID!
hostId: String!
rn: String!
tenantId: String!
sensorTenant: String!
sensorId: String!
ingestTime: Time!
createdAt: Time!
updatedAt: Time!
biosSerial: String
firstDiskSerial: String
systemVolumeSerial: String
sensorVersion: String
endpointType: String
endpointPlatform: String
hostnames: [Hostname]
ethernetAddresses: [EthernetAddress]
ipAddresses: [IpAddress]
users: [User]
architecture: String
osFamily: String
osVersion: String
osDistibutor: String
osRelease: String
systemType: String
osCodename: String
kernalRelease: String
kernalVersion: String
tags: [Tag]
}
Show All Assets ⫘
query allAssets($offset: Int = 0, $limit: Int = 3, $order_by: AssetsOrderByInput = hostname, $order_direction: AssetsOrderDirectionInput = asc, $filter_asset_state: AssetStateFilter = All, $only_most_recent: Boolean = false)
{
allAssets(offset: $offset, limit: $limit, order_by: $order_by, order_direction: $order_direction, filter_asset_state: $filter_asset_state, only_most_recent: $only_most_recent)
{
totalResults offset limit assets { id hostId rn tenantId sensorTenant sensorId ingestTime createdAt updatedAt deletedAt lastSeenAt biosSerial firstDiskSerial systemVolumeSerial sensorVersion endpointType endpointPlatform hostnames { id createdAt updatedAt hostId hostname } ethernetAddresses { id createdAt updatedAt hostId mac } ipAddresses { id createdAt updatedAt ip hostId } users { id createdAt updatedAt hostId username } architecture osFamily osVersion osDistributor osRelease systemType osCodename kernelRelease kernelVersion tags { id hostId tenantId createdAt updatedAt tag key } connectionStatus model cloudProviderName cloudInstanceId endpointGroup { id } status }
}
}
Delete an Asset ⫘
mutation deleteAssets($ids: [ID!]! = ["asset-uuid-here"], $undelete: Boolean = false)
{
deleteAssets(ids: $ids, undelete: $undelete)
}
Get an Asset Count ⫘
Important
assetCountGroupByEndpointType
does not return data for Taegis Endpoint Agents. Use facetInfoV2
with the Endpoint Assets GraphQL API to return data for all endpoint types instead.
query assetCountGroupByEndpointType
{
assetCountGroupByEndpointType
{
endpointType count
}
}
Query by Host IDs ⫘
query assetsByHostIds($hostIds: [String!] = ["host/sensor-id-here"])
{
assetsByHostIds(hostIds: $hostIds)
{
id hostId rn tenantId sensorTenant sensorId ingestTime createdAt updatedAt deletedAt lastSeenAt biosSerial firstDiskSerial systemVolumeSerial sensorVersion endpointType endpointPlatform hostnames { id createdAt updatedAt hostId hostname } ethernetAddresses { id createdAt updatedAt hostId mac } ipAddresses { id createdAt updatedAt ip hostId } users { id createdAt updatedAt hostId username } architecture osFamily osVersion osDistributor osRelease systemType osCodename kernelRelease kernelVersion tags { id hostId tenantId createdAt updatedAt tag key } connectionStatus model cloudProviderName cloudInstanceId endpointGroup { id } status
}
}
Next Steps ⫘
For more information, see the Assets GraphQL API Documentation.