Investigations v2 GraphQL API の使用を開始する🔗

重要

Investigations v2 API は現在 非推奨 です。代わりに Cases GraphQL API を使用してください。

重要

続行する前に、動作する client_id と client_secret を取得するために、API Authentication の手順を完了してください。

地域

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に置き換えてください。

注意

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

Investigation を作成する🔗

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

Variables🔗

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

Example 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"}}}'

注意🔗

Investigation の割り当ては、特定のユーザーまたは @customer や @secureworks などのグループメンションのいずれかに設定できます。
Investigation を作成するユーザーまたはクライアント以外のユーザーを指定してステータスを AWAITING_ACTION に設定すると、そのユーザーまたはグループにメールが送信されます。
create investigation 呼び出しでは、alerts、events、alertsSearchQueries フィールドを使用して、1 回のリクエストでエビデンスを添付することもできます。
- alertsSearchQueries フィールドは、CQL 検索を受け入れ、アラートを Investigation に一括追加します。
- create 呼び出しでエビデンスを添付した場合、processingStatus フィールドが更新され、その後の Investigation に対するクエリでは、エビデンス処理の完了に伴って更新されたステータスが返されます。

Investigation を更新する🔗

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

Variables🔗

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

Example 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 を介した Investigation の更新は、RESTful PATCH 更新と同様に機能します。フィールドが null または未送信の場合、そのフィールドは無視され更新されません。したがって、変更が必要なフィールドのみを送信する必要があります。
- type、assigneeId、priority など、一部のフィールドは空または null にできません。そのような操作を試みた場合、API はリクエストを拒否します。
Investigation を更新しているユーザーまたはクライアント、あるいは現在担当者として設定されているユーザー以外のユーザーを指定してステータスを AWAITING_ACTION に設定すると、そのユーザーまたはグループにメールが送信されます。
- 担当者が変更されてもステータスが AWAITING_ACTION のままであれば、メールは引き続き送信されます。ステータスが AWAITING_ACTION から変更された場合は、メールは送信されません。

Investigation に追加のエビデンスを追加する🔗

Mutation🔗

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

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

Example 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 は、Investigation を要求するクエリで取得できます。

Investigation からエビデンスを削除する🔗

Mutation🔗

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

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

Example 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 は、Investigation を要求するクエリで取得できます。
アラートを削除しても、関連するエビデンスは削除されません。
- アラートに関連して追加されたイベントおよび資産は、個別に削除する必要があります。同様に、資産またはイベントを削除する場合も、その他の関連エビデンスは手動で削除する必要があります。

Investigation をクローズする🔗

Mutation🔗

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

Variables🔗

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

Example 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"}}}'

注意🔗

アラートを含む Investigation をクローズする場合、alertsResolutionStatus が必要であり、関連付けられているすべてのアラートのステータスが更新されます。
クローズの reason は、Investigation と、この操作によってクローズされるすべてのアラートの両方に設定されます。
Investigation のクローズ自体は即時ですが、関連付けられているアラートの更新は非同期操作です。
エビデンスの processingStatus は、Investigation を要求するクエリで取得できます。

Investigation をアーカイブする🔗

Mutation🔗

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

Variables🔗

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

Example 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>"]}}}'

注意🔗

アーカイブできるのはクローズ済みの Investigation のみです。
Investigation のアーカイブ中に問題が発生した場合（例: クローズされていない、存在しない）、API はアーカイブ可能なものは引き続きアーカイブし、その他についてはエラーを返します。
archiveInvestigationV2 mutation もあり、これを使用すると 1 件の Investigation のみをアーカイブし、レスポンスとして完全な Investigation を受け取ることができます。

Investigation のアーカイブを解除する🔗

Mutation🔗

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

Variables🔗

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

Example 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>"]}}}'

注意🔗

Investigation のアーカイブ解除中に問題が発生した場合（例: 存在しない）、API はアーカイブ解除可能なものは引き続きアーカイブ解除し、その他についてはエラーを返します。
unarchiveInvestigationV2 mutation もあり、これを使用すると 1 件の Investigation のみをアーカイブ解除し、レスポンスとして完全な Investigation を受け取ることができます。

ID によって Investigation をクエリする🔗

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

Variables🔗

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

Example 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>"}}}'

Investigation を検索する🔗

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

Variables🔗

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

Example 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}}}'

注意🔗

パートナーテナントのコンテキストから検索する場合、検索はすべての子テナントに対して実行されます。
Investigations の CQL 検索では次はサポートされていません
- 集計
- HEAD または TAIL（page/perPage を使用）
- 結合

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

investigationsV2 クエリで使用できる CQL クエリフィールドには、次のものがあります。

Field	Type	Example Values	Notes
`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, zrZXXgfKZKSiphdZ71aL4ILVvWZYBIvM@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, zrZXXgfKZKSiphdZ71aL4ILVvWZYBIvM@clients
`createdAt`	Timestamp	2024-08-14T15:52:30.509542Z
`updatedBy`	String	6f2fed75-ce7f-4790-9ea1-849b9615c87d, 1534, zrZXXgfKZKSiphdZ71aL4ILVvWZYBIvM@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, zrZXXgfKZKSiphdZ71aL4ILVvWZYBIvM@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, zrZXXgfKZKSiphdZ71aL4ILVvWZYBIvM@clients	`createdByPartner` が true の場合にのみ設定されます。

次のステップ🔗

詳細については、Investigations v2 GraphQL API Documentation を参照してください。