コンテンツにスキップ

Bring Your Own Intelligence (BYOTI) API の開始方法🔗

重要

先に、API認証 の手順を完了し、動作する client_id および client_secret を取得してください。

地域

XDR APIにアクセスするためのURLは、お客様の環境が展開されているリージョンによって異なる場合があります。

  • 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

このXDR APIドキュメントの例では、https://api.ctpx.secureworks.com を使用しています。別のリージョンをご利用の場合は、適切なURLに置き換えてください。

BYOTI-API APIはGraphQLに基づいており、読み取り（Query）または書き込み（Mutation）操作が可能です。Mutationは値の書き込みや投稿を行います。レスポンスはJSON形式で提供されます。

これらの操作により、Bring Your Own Threat Intel (BYOTI) 検知機 で利用される脅威インジケーターを管理できます。この検知機は、お客様のインジケーターに基づいて検知を生成します。

インジケーターの検索🔗

searchIndicatorsクエリは、クエリ言語を使用してお客様のインジケーターを検索します。

注意

この例で使用されているすべてのタイムスタンプは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
    }
}

レスポンス🔗

{
    "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
        }
    }
}

インジケーターの取得🔗

次の例は、object_typeに基づくシンプルな検索を実行します。

注意

この例で使用されているすべてのタイムスタンプは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
    }
}

レスポンス🔗

{
    "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
        }
    }
}

インジケーターのアップサート🔗

mutation upsertIndicatorsは、基本的なインジケーターのリストをアップロードできます。次の例では、2つのインジケーターをアップサートしています。

注意

この例で使用されているすべてのタイムスタンプは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
        }
    }
}

レスポンス🔗

{
    "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
        }
    }
}

STIXドキュメントのアップサート🔗

このmutationは、複数のSTIXドキュメントからのデータを1回のmutationで受け付けます。以下は2つのドキュメントを追加する例です。

注意

この例で使用されているすべてのタイムスタンプは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
        }
    }
}

レスポンス🔗

{
    "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
        }
    }
}

インジケーターの削除🔗

deleteIndicators mutationは、インジケーターを削除対象としてマークします。削除するインジケーターを指定するクエリを受け付けます。この例では、すべてのurlインジケーターを削除します。

注意

この例で使用されているすべてのタイムスタンプは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
        }
    }
}

レスポンス🔗

{
    "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"
                }
            ]
        }
    }
}