Get Started with the Bring Your Own Intelligence (BYOTI) 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 - EU1โ
https://api.echo.taegis.secureworks.com - EU2โ
https://api.golf.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.
The BYOTI-API API is based on GraphQL, which can either be a read (Query) or a write (Mutation) operation. Mutations write or post values. Responses are provided in a JSON format.
These operations enable you to manage Threat Indicators utilized by the Bring Your Own Threat Intel (BYOTI) Detector, which generates detections based on your indicators.
Search Indicators๐
The searchIndicators query searches your indicators using the Query Language.
Note
All timestamps used in this example are UTC.
query searchIndicators(
$input: SearchIndicatorsInput = {
with_partner_tenants: true
page: 1
per_page: 10
query: "from byoti_indicator where object_type = 'url' and deleted_at is null"
}
) {
searchIndicators(input: $input) {
indicators {
id
object_type
name
description
value
created_at
updated_at
deleted_at
severity
__typename
}
page
per_page
total_entries_size
current_entries_returned
total_pages
}
}
Response๐
{
"data": {
"searchIndicators": {
"indicators": [
{
"id": "74e7231b-9463-5634-b91a-43d2ccaa0299",
"object_type": "url",
"name": "name test4",
"description": "description test4",
"value": "http://www.evil.url/post.php4]",
"created_at": "2023-09-30T14:37:33.021439Z",
"updated_at": "2023-09-30T15:04:18.532431Z",
"deleted_at": null,
"severity": "HIGH",
"__typename": "ByotiIndicator"
}
],
"page": 1,
"per_page": 10,
"total_entries_size": 1,
"current_entries_returned": 1,
"total_pages": 1
}
}
}
Get Indicators๐
The following example performs a simple search based on object_type.
Note
All timestamps used in this example are UTC.
query getIndicators($input: GetIndicatorsInput = {
object_type: url,
page: 1,
per_page: 1000
}) {
getIndicators(input: $input) {
indicators {
id
object_type
name
description
created_at
updated_at
severity
object_type
value
__typename
}
page
per_page
total_entries_size
current_entries_returned
total_pages
}
}
Response๐
{
"data": {
"searchIndicators": {
"indicators": [
{
"id": "74e7231b-9463-5634-b91a-43d2ccaa0299",
"object_type": "url",
"name": "name test4",
"description": "description test4",
"value": "http://www.evil.url/post.php4]",
"created_at": "2023-09-30T14:37:33.021439Z",
"updated_at": "2023-09-30T15:04:18.532431Z",
"deleted_at": null,
"severity": "HIGH",
"__typename": "ByotiIndicator"
}
],
"page": 1,
"per_page": 10,
"total_entries_size": 1,
"current_entries_returned": 1,
"total_pages": 1
}
}
}
Upsert Indicators๐
The mutation upsertIndicators permits you to upload a list of basic indicators. The following example upserts two indicators.
Note
All timestamps used in this example are UTC.
mutation {
upsertIndicators(
input: [{
object_type: ip
object_subtype: ipv4
name: "ip name test1"
description: "description ip test 1"
value: "5.5.5.1"
},
{
object_type: url
name: "url name test 1"
description: "url description 1"
value: "http://www.evil.url/post.php/6"
severity: HIGH
source_name: "manual entry"
}]
) {
accepted_indicators {
id
object_type
name
description
value
updated_at
deleted_at
}
rejected_indicators {
value
reason
}
}
}
Response๐
{
"data": {
"upsertIndicators": {
"accepted_indicators": [
{
"id": "b195b9cd-925d-5ac2-91fc-2cd45db864c9",
"object_type": "ip",
"name": "ip name test1",
"description": "description ip test 1",
"value": "5.5.5.1",
"updated_at": "2023-09-22T18:40:14.986308Z",
"deleted_at": null
},
{
"id": "f2955b5e-d5cf-54a3-8a25-8179b1fd649f",
"object_type": "url",
"name": "url name test 1",
"description": "url description 1",
"value": "http://www.evil.url/post.php/6",
"updated_at": "2023-09-22T18:40:14.988111Z",
"deleted_at": null
}
],
"rejected_indicators": null
}
}
}
Upsert STIX Documents๐
This mutation accepts data from multiple STIX documents in a single mutation. The following is an example adding two documents.
Note
All timestamps used in this example are UTC.
mutation {
upsertSTIXDocuments(
input: [{
id: "id test5"
type: "indicator"
name: "name test5"
description: "description test5"
pattern: "[url:value = 'http://www.bad.url/post.php']"
pattern_type: "stix"
},
{
id: "id test6"
type: "indicator"
name: "name test 6"
description: "description test6"
pattern: "[url:value = 'http://www.bad.url/post.php/6']"
pattern_type: "stix"
}]
) {
accepted_indicators {
id
object_type
name
description
value
updated_at
}
rejected_indicators {
value
reason
}
}
}
Response๐
{
"data": {
"upsertSTIXDocuments": {
"accepted_indicators": [
{
"id": "e14226e1-95c6-5b64-7291-560e2fc5a023",
"object_type": "url",
"name": "name test5",
"description": "description test5",
"value": "http://www.what.com/bright1/post.php",
"updated_at": "2023-09-22T18:40:09.788133Z"
},
{
"id": "8808fa2b-3384-5a85-3268-199379e9bc93",
"object_type": "url",
"name": "name test 6",
"description": "description test6",
"value": "http://www.what.com/bright1/post.php/6",
"updated_at": "2023-09-22T18:40:09.791724Z"
}
],
"rejected_indicators": null
}
}
}
Delete Indicators๐
The deleteIndicators mutation marks indicators for deletion. It accepts a query to specify the indicators to be deleted. In this example, we delete all url indicators.
Note
All timestamps used in this example are UTC.
mutation DeleteIndicators(
$query: String = "from byoti_indicator where object_type = 'url'" ) {
deleteIndicators(query: $query) {
status
indicators {
id
object_type
name
description
value
updated_at
deleted_at
}
}
}
Response๐
{
"data": {
"deleteIndicators": {
"status": true,
"indicators": [
{
"id": "74e7231b-9463-5634-b91a-d9d0ccaa0299",
"object_type": "url",
"name": "name test4",
"description": "description test4",
"value": "http://www.evil.url/post.php4]",
"updated_at": "2023-10-02T20:50:55.501418Z",
"deleted_at": "2023-10-02T20:50:55.500368787Z"
}
]
}
}
}