🌙
 

Subscribe to the Taegis™ XDR Documentation RSS Feed at .

Learn more about RSS readers or RSS browser extensions.

Using the Bring Your Own Intelligence (BYOTI) API

api guides

Important

Before proceeding, complete the API Authentication steps in order to obtain a working client_id and client_secret.

Regions

The URL to access Taegis™ 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 Taegis™ 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"
                }
            ]
        }
    }
}

 

On this page: