Using 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 - 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.
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 alerts 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"
}
]
}
}
}