Investigations v2 GraphQL 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
EU— https://api.echo.taegis.secureworks.com

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

注意

Taegis XDRでは、Alerts および Investigations という用語が、最近検出および ケース に変更されました。SophosとTaegisテクノロジーのプラットフォーム統合作業が進行中のため、引き続き旧用語が参照されている場合があります。詳細については、Taegis用語の更新をご覧ください。

インベスティゲーションの作成🔗

Mutation🔗

mutation createInvestigationV2($input: CreateInvestigationInput!) {
    createInvestigationV2(input: $input) {
        id
        shortId
        title
        keyFindings
        priority
        type
        status
        contributorIds
        assigneeId
        tenantId
        createdById
        createdAt
        updatedById
        updatedAt
        processingStatus {
            alerts
            events
            assets
        }
    }
}

変数🔗

{
    "input": {
        "title": "My Example Investigation",
        "assigneeId": "<assignee_user_id>",
        "status": "OPEN",
        "keyFindings": "Example Key Findings",
        "priority": 2,
        "type": "SECURITY_INVESTIGATION"
    }
}

Curl の例🔗

curl --request POST \
  --url <Environment Specific URL/Endpoint> \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Context: <tenant id>' \
  --data '{"query":"mutation createInvestigationV2($input: CreateInvestigationInput!) {\n\tcreateInvestigationV2(input: $input) {\n\t\tid\n\t\tshortId\n\t\ttitle\n\t\tkeyFindings\n\t\tpriority\n\t\ttype\n\t\tstatus\n\t\tcontributorIds\n\t\tassigneeId\n\t\ttenantId\n\t\tcreatedById\n\t\tcreatedAt\n\t\tupdatedById\n\t\tupdatedAt\n\t\tprocessingStatus {\n\t\t\talerts\n\t\t\tevents\n\t\t\tassets\n\t\t}\n\t}\n}\n","operationName":"createInvestigationV2","variables":{"input":{"title":"My Example Investigation","assigneeId":"<assignee_user_id>","status":"OPEN","keyFindings":"Example Key Findings","priority":2,"type":"SECURITY_INVESTIGATION"}}}'

注意事項🔗

インベスティゲーションの割り当ては、特定のユーザーまたは @customer や @secureworks のようなグループメンションに設定できます。
ステータスを AWAITING_ACTION に設定し、インベスティゲーションを作成した本人またはクライアント以外のユーザーに割り当てた場合、そのユーザーまたはグループにメールが送信されます。
インベスティゲーション作成時のリクエストでは、alerts、events、alertsSearchQueries フィールドを使用して証拠を一度に添付することも可能です。
- alertsSearchQueries フィールドは、CQL検索を受け付け、インベスティゲーションにアラートを一括で追加できます。
- 作成時に証拠を添付した場合、processingStatus フィールドが更新され、証拠処理が完了するとインベスティゲーションの後続クエリで更新されたステータスが返されます。

インベスティゲーションの更新🔗

Mutation🔗

mutation updateInvestigationV2($input: UpdateInvestigationV2Input!) {
    updateInvestigationV2(input: $input) {
        id
        shortId
        title
        keyFindings
        priority
        type
        status
        contributorIds
        assigneeId
        tenantId
        createdById
        createdAt
        updatedById
        updatedAt
        processingStatus {
            alerts
            events
            assets
        }
    }
}

変数🔗

{
    "input": {
        "id": "<investigation_id>",
        "title": "My Updated Example Investigation",
        "assigneeId": "@customer",
        "status": "AWAITING_ACTION",
        "keyFindings": "Updated Example Key Findings"
    }
}

Curl の例🔗

curl --request POST \
  --url <Environment Specific URL/Endpoint> \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Context: <tenant id>' \
  --data '{"query":"mutation updateInvestigationV2(\n\t$input: UpdateInvestigationV2Input!\n) {\n\tone: updateInvestigationV2(input: $input) {\n\t\tid\n\t\ttitle\n\t\tassigneeId\n\t\tstatus\n\t}\n}\n","operationName":"updateInvestigationV2","variables":{"input":{"id": "<investigation_id>", "title":"My Updated Example Investigation","assigneeId":"@customer","status":"AWAITING_ACTION","keyFindings":"Updated Example Key Findings"}}}'

注意事項🔗

GraphQL を通じたインベスティゲーションの更新は、RESTful の PATCH 更新と同様に動作します。フィールドが null または送信されなかった場合は無視され、更新されません。したがって、変更が必要なフィールドのみ送信してください。
- type、assigneeId、priority など、空や null にできないフィールドもあります。その場合、APIはリクエストを拒否します。
ステータスを AWAITING_ACTION に設定し、インベスティゲーションを更新した本人または現在割り当てられている担当者以外のユーザーに割り当てた場合、そのユーザーまたはグループにメールが送信されます。
- 担当者が変更されてもステータスが AWAITING_ACTION のままの場合はメールが送信されますが、ステータスが AWAITING_ACTION から変更された場合はメールは送信されません。

インベスティゲーションへの追加証拠の追加🔗

Mutation🔗

mutation addEvidenceToInvestigation($input: AddEvidenceToInvestigationInput!) {
    addEvidenceToInvestigation(input: $input) {
        investigationId
        alerts
        events
        alertsSearchQuery
        searchQueries
    }
}

変数🔗

{
    "input": {
        "investigationId": "<investigation_id>",
        "alerts": [
            "alert://priv:stolen-user-credentials:11772:1723482198701:9640c014-cd59-448d-b47d-aa8e8e3747fe",
            "alert://priv:stolen-user-credentials:11772:1723473198181:4c919a6b-0eee-4876-9d34-7cdbb5afe48b"
        ],
        "events": [
            "event://priv:scwx.auth:11772:1708626661995:422496f6-a491-4983-af90-020a4b46a0e8"
        ]
    }
}

Curl の例🔗

curl --request POST \
  --url <Environment Specific URL/Endpoint> \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Context: <tenant id>' \
  --data '{"query":"mutation addEvidenceToInvestigation($input: AddEvidenceToInvestigationInput!) {\n\taddEvidenceToInvestigation(input: $input) {\n\t\tinvestigationId\n\t\talerts\n\t\tevents\n\t\talertsSearchQuery\n\t\tsearchQueries\n\t}\n}\n","operationName":"addEvidenceToInvestigation","variables":{"input":{"investigationId":"4697e8fb-44f1-4221-951c-309b14f1f1aa","alerts":["alert://priv:stolen-user-credentials:11772:1723482198701:9640c014-cd59-448d-b47d-aa8e8e3747fe","alert://priv:stolen-user-credentials:11772:1723473198181:4c919a6b-0eee-4876-9d34-7cdbb5afe48b"],"events":["event://priv:scwx.auth:11772:1708626661995:422496f6-a491-4983-af90-020a4b46a0e8"]}}}'

注意事項🔗

証拠の追加は非同期処理であり、受け付けられたIDが返されます。
証拠の processingStatus は、インベスティゲーションをリクエストするクエリで取得できます。

インベスティゲーションから証拠の削除🔗

Mutation🔗

mutation removeEvidenceFromInvestigation($input: RemoveEvidenceFromInvestigationInput!) {
    removeEvidenceFromInvestigation(input: $input) {
        investigationId
        alerts
        events
        assets
    }
}

変数🔗

{
    "input": {
        "investigationId": "<investigation_id>",
        "alerts": [
            "alert://priv:stolen-user-credentials:11772:1723482198701:9640c014-cd59-448d-b47d-aa8e8e3747fe",
            "alert://priv:stolen-user-credentials:11772:1723473198181:4c919a6b-0eee-4876-9d34-7cdbb5afe48b"
        ],
        "events": [
            "event://priv:scwx.auth:11772:1708626661995:422496f6-a491-4983-af90-020a4b46a0e8"
        ]
    }
}

Curl の例🔗

curl --request POST \
  --url <Environment Specific URL/Endpoint> \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Context: <tenant id>' \
  --data '{"query":"mutation removeEvidenceFromInvestigation($input: RemoveEvidenceFromInvestigationInput!) {\n\tremoveEvidenceFromInvestigation(input: $input) {\n\t\tinvestigationId\n\t\talerts\n\t\tevents\n\t\tassets\n\t}\n}\n","operationName":"removeEvidenceFromInvestigation","variables":{"input":{"investigationId":"<investigation_id>","alerts":["alert://priv:stolen-user-credentials:11772:1723482198701:9640c014-cd59-448d-b47d-aa8e8e3747fe","alert://priv:stolen-user-credentials:11772:1723473198181:4c919a6b-0eee-4876-9d34-7cdbb5afe48b"],"events":["event://priv:scwx.auth:11772:1708626661995:422496f6-a491-4983-af90-020a4b46a0e8"]}}}'

注意事項🔗

証拠の削除は非同期処理であり、受け付けられたIDが返されます。
証拠の processingStatus は、インベスティゲーションをリクエストするクエリで取得できます。
アラートを削除しても、関連する証拠は削除されません。
- アラートに関連して追加されたイベントや資産は、別途削除する必要があります。同様に、資産やイベントを削除する場合も、他の関連証拠は手動で削除する必要があります。

インベスティゲーションのクローズ🔗

Mutation🔗

mutation closeInvestigation($input: CloseInvestigationInput!) {
    closeInvestigation(input: $input) {
        id
        title
        status
        closeReason
    }
}

変数🔗

{
    "input": {
        "id": "<investigation_id>",
        "reason": "Example reason for closing this investigation",
        "status": "CLOSED_NOT_VULNERABLE",
        "alertsResolutionStatus": "NOT_ACTIONABLE"
    }
}

Curl の例🔗

curl --request POST \
  --url <Environment Specific URL/Endpoint> \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Context: <tenant id>' \
  --data '{"query":"mutation closeInvestigation($input: CloseInvestigationInput!) {\n\tcloseInvestigation(input: $input) {\n\t\tid\n\t\ttitle\n\t\tstatus\n\t\tcloseReason\n\t}\n}\n","operationName":"closeInvestigation","variables":{"input":{"id":"<investigation_id>","reason":"Example reason for closing this investigation","status":"CLOSED_NOT_VULNERABLE","alertsResolutionStatus":"NOT_ACTIONABLE"}}}'

注意事項🔗

アラートを含むインベスティゲーションをクローズする場合、alertsResolutionStatus が必須となり、関連するすべてのアラートのステータスが更新されます。
クローズ時の reason は、インベスティゲーションおよびこの操作でクローズされたすべてのアラートに設定されます。
インベスティゲーションのクローズは即時ですが、関連アラートの更新は非同期処理です。
証拠の processingStatus は、インベスティゲーションをリクエストするクエリで取得できます。

インベスティゲーションのアーカイブ🔗

Mutation🔗

mutation archiveInvestigationsV2($input: ArchiveInvestigationsInput!) {
    archiveInvestigationsV2(input: $input) {
        ids
    }
}

変数🔗

{
    "input": {
        "ids": [
            "<investigation_id_1>",
            "<investigation_id_2>"
        ]
    }
}

Curl の例🔗

curl --request POST \
  --url <Environment Specific URL/Endpoint> \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Context: <tenant id>' \
  --data '{"query":"mutation archiveInvestigationsV2($input: ArchiveInvestigationsInput!) {\n\tarchiveInvestigationsV2(input: $input) {\n\t\tids\n\t}\n}","operationName":"archiveInvestigationsV2","variables":{"input":{"ids":["<investigation_id_1>","<investigation_id_2>"]}}}'

注意事項🔗

アーカイブできるのはクローズ済みのインベスティゲーションのみです。
インベスティゲーションのアーカイブに問題がある場合（例：クローズされていない、存在しないなど）、APIはアーカイブ可能なものだけをアーカイブし、他についてはエラーを返します。
1件のみアーカイブし、レスポンスとして完全なインベスティゲーションを受け取る場合は、archiveInvestigationV2 mutation も利用できます。

インベスティゲーションのアーカイブ解除🔗

Mutation🔗

mutation unarchiveInvestigationV2($input: UnarchiveInvestigationInput!) {
    unarchiveInvestigationV2(input: $input) {
        ids
    }
}

変数🔗

{
    "input": {
        "ids": [
            "<investigation_id_1>",
            "<investigation_id_2>"
        ]
    }
}

Curl の例🔗

curl --request POST \
  --url <Environment Specific URL/Endpoint> \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Context: <tenant id>' \
  --data '{"query":"mutation unarchiveInvestigationV2($input: UnarchiveInvestigationInput!) {\n\tunarchiveInvestigationV2(input: $input) {\n\t\tids\n\t}\n}","operationName":"unarchiveInvestigationV2","variables":{"input":{"ids":["<investigation_id_1>","<investigation_id_2>"]}}}'

注意事項🔗

インベスティゲーションのアーカイブ解除に問題がある場合（例：存在しないなど）、APIは解除可能なものだけを解除し、他についてはエラーを返します。
1件のみアーカイブ解除し、レスポンスとして完全なインベスティゲーションを受け取る場合は、unarchiveInvestigationV2 mutation も利用できます。

IDによるインベスティゲーションのクエリ🔗

Query🔗

query investigationV2($arguments: InvestigationV2Arguments!) {
    investigationV2(arguments: $arguments) {
        id
        shortId
        title
        keyFindings
        priority
        type
        status
        contributorIds
        assigneeId
        tenantId
        createdById
        createdAt
        updatedById
        updatedAt
        processingStatus {
            alerts
            events
            assets
        }
    }
}

変数🔗

{
    "arguments": {
        "id": "<investigation_id>"
    }
}

Curl の例🔗

curl --request POST \
  --url <Environment Specific URL/Endpoint> \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Context: <tenant id>' \
  --data '{"query":"query investigationV2($arguments: InvestigationV2Arguments!) {\n\tinvestigationV2(arguments: $arguments) {\n\t\tid\n\t\tshortId\n\t\ttitle\n\t\tkeyFindings\n\t\tpriority\n\t\ttype\n\t\tstatus\n\t\tcontributorIds\n\t\tassigneeId\n\t\ttenantId\n\t\tcreatedById\n\t\tcreatedAt\n\t\tupdatedById\n\t\tupdatedAt\n\t\tprocessingStatus {\n\t\t\talerts\n\t\t\tevents\n\t\t\tassets\n\t\t}\n\t}\n}\n","operationName":"investigationV2","variables":{"arguments":{"id":"<investigation_id>"}}}'

インベスティゲーションの検索🔗

Query🔗

query investigationsV2($arguments: InvestigationsV2Arguments!) {
    investigationsV2(arguments: $arguments) {
        investigations {
            id
            shortId
            title
            keyFindings
            priority
            type
            status
            contributorIds
            assigneeId
            tenantId
            createdById
            createdAt
            updatedById
            updatedAt
            processingStatus {
                alerts
                events
                assets
            }
        }
        totalCount
    }
}

変数🔗

{
    "arguments": {
        "cql": "status IN ('Open', 'Awaiting Action') and createdAt >= '2024-07-19T21:55:28.163531Z' | sort by createdAt asc",
        "page": 1,
        "perPage": 100
    }
}

Curl の例🔗

curl --request POST \
  --url <Environment Specific URL/Endpoint> \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Context: <tenant id>' \
  --data '{"query":"query investigationsV2($arguments: InvestigationsV2Arguments!) {\n\tinvestigationsV2(arguments: $arguments) {\n\t\tinvestigations {\n\t\t\tid\n\t\t\tshortId\n\t\t\ttitle\n\t\t\tkeyFindings\n\t\t\tpriority\n\t\t\ttype\n\t\t\tstatus\n\t\t\tcontributorIds\n\t\t\tassigneeId\n\t\t\ttenantId\n\t\t\tcreatedById\n\t\t\tcreatedAt\n\t\t\tupdatedById\n\t\t\tupdatedAt\n\t\t\tprocessingStatus {\n\t\t\t\talerts\n\t\t\t\tevents\n\t\t\t\tassets\n\t\t\t}\n\t\t}\n\t\ttotalCount\n\t}\n}\n","operationName":"investigationsV2","variables":{"arguments":{"cql":"status IN ('\''Open'\'', '\''Awaiting Action'\'') and createdAt >= '\''2024-07-19T21:55:28.163531Z'\'' | sort by createdAt asc","page":1,"perPage":100}}}'

注意事項🔗

パートナーテナントのコンテキストで検索する場合、すべての子テナントを対象に検索が実行されます。
インベスティゲーションのCQL検索では、以下はサポートされていません
- 集計
- HEAD または TAIL（page/perPage を使用してください）
- ジョイン

CQLでサポートされているフィールド🔗

investigationsV2 クエリで利用可能なCQLクエリフィールドは以下の通りです：

フィールド	型	例	備考
`id`	string	d638e49d-a3b5-421e-b28d-cb9322a5eaa6
`title`	String	My Investigation Title
`tenantId`	String	11772
`keyFindings`	String	Investigation Key Findings
`status`	String	Open, Awaiting Action, Active, Suspended, Closed: Confirmed Security Incident, Closed: Authorized Activity, Closed: Threat Mitigated, Closed: Not Vulnerable, Closed: False Positive Alert, Closed: Inconclusive, Closed: Informational	GraphQLスキーマで定義されたenumはそのままでは使用できず、有効な値のいずれかと一致する必要があります。
`tags`	String	Tag1	TagsはString Listですが、論理型Stringを用いたクエリを受け付けます。
`contributors`	String	6f2fed75-ce7f-4790-9ea1-849b9615c87d, 1534, zrZXXgfKZKSiphdZ71aL4ILVvM@clients	`contributors`はString Listですが、論理型Stringを用いたクエリを受け付けます。
`assigneeId`	String	6f2fed75-ce7f-4790-9ea1-849b9615c87d, 1534, @customer	ユーザーID、クライアントID、@customer を受け付けます。パートナーのメンションコードも受け付けます。
`createdBy`	String	6f2fed75-ce7f-4790-9ea1-849b9615c87d, 1534, zrZXXgfKZKSiphdZ71aL4ILVvM@clients
`createdAt`	Timestamp	2024-08-14T15:52:30.509542Z
`updatedBy`	String	6f2fed75-ce7f-4790-9ea1-849b9615c87d, 1534, zrZXXgfKZKSiphdZ71aL4ILVvM@clients
`updatedAt`	Timestamp	2024-08-14T15:52:30.509542Z
`archivedAt`	Timestamp	2024-08-14T15:52:30.509542Z
`priority`	Number	1, 2, 3, 4
`type`	String	Security Investigation, Incident Response, Threat Hunt, MDR Threat Hunt, CTU Threat Hunt, MDR Elite Threat Hunt, Secureworks Incident Response, Unlimited Response, OT Investigation, MDR OT Investigation, Detection Research, Informational	GraphQLスキーマで定義されたenumはそのままでは使用できず、有効な値のいずれかと一致する必要があります。
`shortId`	String	INV00026
`closeReason`	String	Investigation Close Reason
`createdByPartner`	Bool	true, false
`handedOffAt`	Timestamp	2024-08-14T15:52:30.509542Z	`createdByPartner` が true の場合のみ設定されます。
`timeToHandOff`	Number	360	`createdByPartner` が true の場合のみ設定されます。単位は秒です。
`handedOffBy`	String	6f2fed75-ce7f-4790-9ea1-849b9615c87d, 1534, zrZXXgfKZKSiphdZ71aL4ILVvM@clients	`createdByPartner` が true の場合のみ設定されます。
`acknowledgedAt`	Timestamp	2024-08-14T15:52:30.509542Z	`createdByPartner` が true の場合のみ設定されます。
`timeToAcknowledgement`	Number	800	`createdByPartner` が true の場合のみ設定されます。単位は秒です。
`acknowledgedBy`	String	6f2fed75-ce7f-4790-9ea1-849b9615c87d, 1534	`createdByPartner` が true の場合のみ設定されます。
`resolvedAt`	Timestamp	2024-08-14T15:52:30.509542Z	`createdByPartner` が true の場合のみ設定されます。
`timeToResolution`	Number	687	`createdByPartner` が true の場合のみ設定されます。単位は秒です。
`resolvedBy`	String	6f2fed75-ce7f-4790-9ea1-849b9615c87d, 1534, zrZXXgfKZKSiphdZ71aL4ILVvM@clients	`createdByPartner` が true の場合のみ設定されます。

次のステップ🔗

詳細については、Investigations v2 GraphQL API ドキュメントを参照してください。