Investigations GraphQL API

Important

This version of the Investigations API is now deprecated; use Investigations v2 GraphQL API instead.

Note

The terms Alerts and Investigations have recently been changed to Detections and Cases in Taegis XDR. You may still see references to the old terms while we continue to work towards platform convergence of Sophos and Taegis technologies. For more information, see Taegis Terminology Updates.

Uint64

Description: Uint64 is a custom scalar type that represents an unsigned 64 bit integer.

Query

Description: Red Cloak TDR uses GraphQL queries, which can either be a read (Query) or a write (Mutation) operation. A GraphQL query is used to read or fetch values; mutations write or post values. Responses are provided in a JSON format.

Fields

Field	Type	Description	Arguments
node	Node		id: ID
investigationSummary	InvestigationSummary	Get summary of investigations (tag and counts for each tag)
investigation	Investigation	Get an investigation by id	investigation_id: ID
investigations	Investigation	Get investigations for the list of ids	investigation_ids: ID
allInvestigations	Investigation	Get all investigations Max perPage Value is 100. If requesting over 100, only the first 100 will be returned. deprecated: Use investigationsSearch for better investigations query experience.	status: String, page: Int, perPage: Int, createdAfter: String, createdBefore: String, updatedAfter: String, updatedBefore: String, orderByField: OrderFieldInput, orderDirection: OrderDirectionInput, isDeleted: Boolean, hideThreatHuntingInvestigations: Boolean
investigationCountOverTime	Count	Get the number of investigations created during a given time frame. Can optionslly pass in a desired 'transition_status' (handoff, acknowledge, resolution)	transition_status: String, after: Time, before: Time
meanTimeSummaryOverPeriod	TimeSummaryForGroup	Get the average times it took to hand off, acknowledge, and resolve all investigations over the course of the period	after: Time, before: Time, includeThreatHuntTypes: Boolean
investigationAssets	InvestigationAssetOutput	Get investigation assets by investigation id	investigation_id: ID, page: Int, perPage: Int
investigationEvents	InvestigationEventOutput	Get investigation events by investigation id	investigation_id: ID, page: Int, perPage: Int
investigationAlerts	InvestigationAlertOutput	Get investigation alerts by investigation id deprecated: Use investigation query or alerts2 search query (paginated) to get alerts by investigation id	investigation_id: ID, page: Int, perPage: Int, filterQuery: String, orderByField: String, orderDirection: OrderDirection
investigationGenesisEvents	Event	Get investigation genesis events by investigation id	investigation_id: ID
investigationGenesisAlerts	Alert	Get investigation genesis alerts by investigation id	investigation_id: ID
investigationAuthCredentials	String	Get investigation auth credentials by investigation id	investigation_id: ID
investigationSearchQueries	SearchQuery	Get investigation search queries by investigation id	investigation_id: ID
investigationsBulkEventsAlerts	InvestigationBulkResponse	Get investigations by quering a string on events/alerts/genesis events/genesis alerts fields	queryStrings: String
investigationsBulkUpdateAlerts	String	Updates Investigation Alerts and Investigation information from Alerts (ie Access Vectors)
investigationStatusSummary	SummaryGroup	Get summary of investigations and status filtered by updated_at	updatedAfter: String, updatedBefore: String
investigationsSearch	InvestigationsOutput	Investigations Search. Query fields accepts a CQL string (non aggregations). Use filterText for free text search. Max perPage Value is 100. If requesting over 100, only the first 100 will be returned.	page: Int, perPage: Int, query: String, filterText: String, orderByField: OrderFieldInput, orderDirection: OrderDirectionInput
investigationsAdvancedSearch	Map	Investigations Advanced Search can perform aggregations/sorting/filtering on investigations using CQL	cql: String
investigationProcessingStatus	InvestigationProcessingResponse	Get investigation processing status by id	investigation_id: ID
getFalsePositives	Map	MDR - false positives widget	after: Time, before: Time
investigationsCount	Int	Get aggregated investigations counts based on CQL query	query: String
investigationsStatusCount	InvestigationStatusCountResponse	Get aggregated investigations status counts
exportInvestigationsSearch	InvestigationsExportOutput	Export investigations Search Raw Content Max perPage Value is 100. If requesting over 100, only the first 100 will be returned.	page: Int, perPage: Int, query: String, filterText: String, orderByField: OrderFieldInput, orderDirection: OrderDirectionInput
investigationFile	InvestigationFile	Get investigation file details	file_id: ID
investigationFiles	InvestigationFile	Get investigation files details	investigation_id: ID
downloadInvestigationFile	String	Presigned URL to Download investigation file	investigation_id: ID, file_id: ID
investigationsBySession	Investigation	Get investigations by multi-tenant session DO NOT USE, this query is unsupported. Use investigationsSearch instead. Max perPage Value is 100. If requesting over 100, only the first 100 will be returned.	session_id: String, page: Int, perPage: Int
getHandoffInvestigations	InvestigationsOutput	Return list of Investigations which are handed off at least once for the the given dates and status Max perPage Value is 100. If requesting over 100, only the first 100 will be returned.	page: Int, perPage: Int, createdAfter: String, createdBefore: String, includeThreatHuntTypesOnly: Boolean, excludeThreatHuntTypes: Boolean
investigationTypes	InvestigationKeyValuePair	Return investigation types list based on user
investigationStatusList	InvestigationKeyValuePair	Return investigation status static list
investigationPriorityList	InvestigationKeyValuePair	Return investigation priority static list
investigationTimeline	InvestigationTimeline	Return investigation timeline	arguments: InvestigationTimelineArguments
investigationEntities	InvestigationEntities	Get an investigation by id	arguments: InvestigationEntitiesArguments

ID

Description: The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

String

Description: The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Int

Description: The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Boolean

Description: The Boolean scalar type represents true or false.

InvestigationTimelineArguments

Fields

Field	Type	Description	Arguments
investigationId	ID
page	Int
perPage	Int
createdAfter	String
createdBefore	String
orderBy	OrderDirectionInput
entityFilters	InvestigationTimelineEntityFilters

InvestigationEntitiesArguments

Fields

Field	Type	Description	Arguments
investigationId	ID

InvestigationEntities

Fields

Field	Type	Description	Arguments
entities	InvestigationEntity

InvestigationEntity

Fields

Field	Type	Description	Arguments
type	String
value	String
rn	RN

InvestigationTimelineEntityFilters

Fields

Field	Type	Description	Arguments
entities	InvestigationTimelineEntityType
entityTypes	String

InvestigationTimeline

Fields

Field	Type	Description	Arguments
entities	InvestigationTimelineEntity
totalEntities	Int

InvestigationTimelineEntity

Fields

Field	Type	Description	Arguments
type	String
id	String
subtype	String
document	Map
creationTimestamp	Time
investigationId	ID
tenantId	String

InvestigationTimelineEntityType

InvestigationKeyValuePair

Fields

Field	Type	Description	Arguments
key	String
value	String
description	String

InvestigationFile

Fields

Field	Type	Description	Arguments
id	ID
investigation_id	ID
tenant_id	String
created_at	Time
updated_at	Time
deleted_at	Time
name	String
path	String
size	Int
status	String
uploaded_by	String
deleted_by	String
additional_metadata	Map

InvestigationStatusCountResponse

Fields

Field	Type	Description	Arguments
open	Int
closed	Int
active	Int
awaiting_action	Int
suspended	Int
total	Int

OrderDirection

InvestigationAlertOutput

Fields

Field	Type	Description	Arguments
alerts	Alert
alerts2	Alert2
totalCount	Int

InvestigationEventOutput

Fields

Field	Type	Description	Arguments
events	Event
totalCount	Int

InvestigationAssetOutput

Fields

Field	Type	Description	Arguments
assets	Asset
totalCount	Int

InvestigationProcessingState

InvestigationProcessingResponse

Fields

Field	Type	Description	Arguments
assets	InvestigationProcessingState
events	InvestigationProcessingState
alerts	InvestigationProcessingState

InvestigationsOutput

Fields

Field	Type	Description	Arguments
investigations	Investigation
totalCount	Int

InvestigationsExportOutput

Fields

Field	Type	Description	Arguments
columnDef	String
rows	String
totalCount	Int

SummaryGroup

Description: Describes the summary of investigations by status filtered by date.

Fields

Field	Type	Description	Arguments
status	String
count	Int
date	String

AccessVector

Fields

Field	Type	Description	Arguments
id	ID
investigation_id	ID
name	String
created_at	Time
updated_at	Time
mitre_info	MitreAttackInfo

Mutation

Description: Mutations in GraphQL enable you to modify data. For the Red Cloak TDR Investigations GraphQL API, mutations allow you to create alerts and input information into alerts. For more information on GraphQL mutations see Mutation and Input Types.

Fields

Field	Type	Description	Arguments
createInvestigation	Investigation	Create new investigation	investigation: InvestigationInput
updateInvestigation	Investigation	Update investigation	investigation_id: ID, investigation: UpdateInvestigationInput
archiveInvestigation	Investigation	Archive investigation	investigation_id: ID
bulkArchiveInvestigations	ID	Bulk Archive Investigations	ids: ID
unArchiveInvestigation	Investigation	UnArchive Investigation	investigation_id: ID
bulkUnArchiveInvestigations	ID	Bulk UnArchive Investigations	ids: ID
createActivityLogForInvestigation	ActivityLog	Create a new activity log for investigation	investigation_id: ID, activityLog: ActivityLogInput
addAssetsToInvestigation	Investigation	Add assets to investigation	investigation_id: ID, assets: String
addEventsToInvestigation	Investigation	Add events to investigation	investigation_id: ID, events: String
addAlertsToInvestigation	Investigation	Add alerts to investigation	investigation_id: ID, alerts: String
addGenesisEventsToInvestigation	Investigation	Add genesis events to investigation	investigation_id: ID, genesis_events: String
addGenesisAlertsToInvestigation	Investigation	Add genesis alerts to investigation	investigation_id: ID, genesis_alerts: String
addAuthCredentialsToInvestigation	Investigation	Add auth credentials to investigation	investigation_id: ID, auth_credentials: String
addSearchQueriesToInvestigation	Investigation	Add search queries to investigation	investigation_id: ID, search_queries: String
addAccessVector	AccessVector	Access Vectors	investigation_id: ID, vectorName: String, created_at: Time, updated_at: Time
removeAccessVector	AccessVector		id: ID
removeAssetsFromInvestigation	Investigation	Remove assets from investigation	investigation_id: ID, assets: String
removeEventsFromInvestigation	Investigation	Remove events from investigation	investigation_id: ID, events: String
removeAlertsFromInvestigation	Investigation	Remove alerts from investigation	investigation_id: ID, alerts: String
removeSearchQueriesFromInvestigation	Investigation	Remove search queries from investigation	investigation_id: ID, search_queries: String
addBulkAlertsToInvestigation	Investigation	Bulk add alerts to an investigation using restdb search query	investigation_id: ID, new_investigation: InvestigationInput, search_query: String
addBulkAlerts2ToInvestigation	Investigation	Bulk add alerts2 to an new investigation using cql query	new_investigation: InvestigationInput, cql: String
addBulkAlerts2ToExistingInvestigation	Investigation	Bulk add alerts2 to an existing investigation using cql query	investigation_id: ID, cql: String
reProcessInvestigationBackgroundJob	InvestigationProcessingResponse	Reprocess investigation background job by id	investigation_id: ID, process_only_events: Boolean
deleteInvestigation	ID	Hard delete of investigation (Supported only in development environments)	investigation_id: ID
acknowledgeInvestigation	ID	Update state_transitions table to acknowledge if current state is handoff, without changing the investigation itself	investigation_id: ID
fileUpload	InvestigationFile	Upload File for an investigation	input: FileUploadInput
deleteFile	Boolean	Delete investigation files from S3 bucket	investigation_id: ID, file_id: ID
initFileUpload	FileUploadResponse	Initialize file upload to get Presigned URL to upload file	input: FileUploadRequest
updateFileStatus	InvestigationFile	Update investigation file status	investigation_id: ID, file_id: ID, status: String

FileUploadResponse

Fields

Field	Type	Description	Arguments
investigationFile	InvestigationFile
presignedUrl	String

FileUploadRequest

Fields

Field	Type	Description	Arguments
investigationId	ID
name	String
size	Int
contentType	String

FileUploadInput

Fields

Field	Type	Description	Arguments
investigationId	ID
file	Upload

InvestigationSummary

Description: Provides a count of investigations per tag.

Fields

Field	Type	Description	Arguments
tag	String
count	Int

Node

Fields

Field	Type	Description	Arguments
id	ID

Event

Description: Resolves the Red Cloak TDR event model.

Fields

Field	Type	Description	Arguments
id	ID

Alert

Description: Used by Nautilus to resolve the Red Cloak TDR alert model.

Fields

Field	Type	Description	Arguments
id	ID

Alert2

Description: Used by Nautilus to resolve the Red Cloak TDR alertv2 model.

Fields

Field	Type	Description	Arguments
id	ID

Asset

Description: Used by Nautilus to resolve the Red Cloak TDR asset model.

Fields

Field	Type	Description	Arguments
id	ID

ParentCount

Description: Represents total and unread comment counts for an investigation.

Fields

Field	Type	Description	Arguments
parent_id	String
parent_type	String
total	Int
unread	Int

TDRUser

Description: Used by Nautilus to resolve the Red Cloak TDR user model.

Fields

Field	Type	Description	Arguments
id	ID

SearchQuery

Description: Represents a saved search query id

Fields

Field	Type	Description	Arguments
id	ID

Investigation

Description: Describes a Red Cloak TDR investigation.

Fields

Field	Type	Description	Arguments
id	ID
tenant_id	String
tags	String
genesis_alerts	Alert
genesis_alerts2	Alert2
genesis_events	Event
alerts	Alert
alerts2	Alert2
events	Event
assets	Asset
search_queries	SearchQuery
auth_credentials	String
key_findings	String
description	String
created_at	Time
updated_at	Time
notified_at	Time
first_notified_at	Time
first_notified_at_scwx	Time
activity_logs	ActivityLog
created_by	String
created_by_user	TDRUser	Retrieves the TDRUser object for the user that created the investigation.
status	String
contributors	String
contributed_users	TDRUser	Retrieves user data for users that have contributed to the investigation.
service_desk_id	String
service_desk_type	String
assignee_id	String
assignee_user	TDRUser	Retrieves the TDRUser object for the user that is assigned to the investigation.
assignee	Assignee	assignee is deprecated use assignee_user
latest_activity	String
access_vectors	AccessVector
transition_state	TransitionState
archived_at	Time
deleted_at	Time
created_by_scwx	Boolean
created_by_partner	Boolean
draft_promoted_at	Time
investigationType	String
processing_status	InvestigationProcessingResponse
priority	Int
type	String
genesis_alerts_count	Int
genesis_events_count	Int
alerts_count	Int
events_count	Int
assets_count	Int
files_count	Int
comments_count	ParentCount
rn	RN
shortId	String	shortId is a shorter, more readable, id. There is no guarantee that it will be sequential or unique but the service will do it's best to achieve this
alertsEvidence	AlertEvidence
assetsEvidence	AssetEvidence
eventsEvidence	EventEvidence
closeReason	String	The reason provided by the user when closing an investigation. This field is only populated for investigations that have reached a 'Closed' status.

Tenant

Fields

Field	Type	Description	Arguments
id	ID
name	String

Assignee

Description: Describes the assignee of an investigation.

Fields

Field	Type	Description	Arguments
id	ID
name	String
roles	String
status	String
user_id	String
email	String
email_verified	Boolean
email_normalized	String
family_name	String
given_name	String
tenants	Tenant

ActivityLog

Description: Stores details of an investigation activity (Create/Update, etc.). DEPRECATED. Use audit logs

Fields

Field	Type	Description	Arguments
id	ID
created_at	Time
updated_at	Time
tenant_id	String
user_id	String
description	String
type	String
comment	String
target	String
investigation_id	ID

TransitionSummary

Description: Used by HandedOff/Acknowledged/ResolvedInvestigations query to represent an investigations most recent transition time and time spent in each state.

Fields

Field	Type	Description	Arguments
transition_time	Time
time_summary	IndividualTimeSummary

TimeSummaryForGroup

Description: Used by MeanTimeSummaryOverPeriod query to represent the average times it took to hand off, acknowledge, and resolve all investigations over the course of the period.

Fields

Field	Type	Description	Arguments
mean_time_to_handoff	Int
mean_time_to_acknowledge	Int
mean_time_to_resolution	Int
time_summaries	IndividualTimeSummary

IndividualTimeSummary

Description: Represents the amounts of time it took before an investigation transitioned into the handoff, acknowledge, and resolution states.

Fields

Field	Type	Description	Arguments
time_to_handoff	Int
time_to_acknowledge	Int
time_to_resolution	Int
is_closed	Boolean
investigation	Investigation

TransitionState

Description: Represent both the initial transitions (if they exist) and the current state (handed off, acknowledged, resolved) of an investigation.

Fields

Field	Type	Description	Arguments
handed_off_at_least_once	Boolean
initial_handoff_time	Time
acknowledged_at_least_once	Boolean
initial_acknowledge_time	Time
resolved_at_least_once	Boolean
initial_resolution_time	Time
handed_off	Boolean
handoff_time	Time
acknowledged	Boolean
acknowledge_time	Time
resolved	Boolean
resolution_time	Time

Count

Description: Represents a int count of a given object.

Fields

Field	Type	Description	Arguments
count	Int

Investigations

Description: An array of InvestigationInfo objects.

Fields

Field	Type	Description	Arguments
investigations	InvestigationInfo

InvestigationInfo

Description: Describes a small subset of investigation information.

Fields

Field	Type	Description	Arguments
id	String
genesis_alerts	String
alerts	String
tenant	String

InvestigationBulkResponse

Description: Used to return an array of investigations for a specific query.

Fields

Field	Type	Description	Arguments
query	String
investigations	Investigation

MitreAttackInfo

Description: Describes fields related to MitreAttack information for an alert.

Fields

Field	Type	Description	Arguments
technique_id	String
technique	String
tactics	String
type	String
description	String
platform	String
system_requirements	String
url	String
data_sources	String
defence_bypassed	String
contributors	String
version	String

InvestigationInput

Description: Describes the fields available for creating a new investigation.

Fields

Field	Type	Description	Arguments
tags	String
genesis_alerts	String
genesis_events	String
alerts	String
events	String
assets	String
auth_credentials	String
search_queries	String
key_findings	String
description	String
notified_at	Time
created_by	String
status	String
contributors	String
service_desk_id	String
service_desk_type	String
assignee_id	String
notes	String
priority	Int
type	String

UpdateInvestigationInput

Description: Describes the fields available for updating an investigation.

Fields

Field	Type	Description	Arguments
tags	String
genesis_alerts	String
genesis_events	String
alerts	String
events	String
assets	String
auth_credentials	String
search_queries	String
key_findings	String
description	String
notified_at	Time
created_by	String
status	String
contributors	String
service_desk_id	String
service_desk_type	String
assignee_id	String
notes	String
acknowledgment	Boolean
priority	Int
type	String
comment_event	Map	For internal use only.

ActivityLogInput

Description: Describes the fields available for creating a new Activity Log.

Fields

Field	Type	Description	Arguments
description	String
type	String
comment	String
target	String

OrderFieldInput

Description: Describes the enums available for the ordering of the AllInvestigations query.

OrderDirectionInput

Description: Describes the order direction available for the order field of the AllInvestigations query.

AlertEvidence

Fields

Field	Type	Description	Arguments
id	ID
investigationId	ID
tenantId	String
createdAt	Time
createdBy	String
alertId	String
isGenesis	Boolean

EventEvidence

Fields

Field	Type	Description	Arguments
id	ID
investigationId	ID
tenantId	String
createdAt	Time
createdBy	String
eventId	String
isGenesis	Boolean

AssetEvidence

Fields

Field	Type	Description	Arguments
id	ID
investigationId	ID
tenantId	String
createdAt	Time
createdBy	String
assetId	String

Time

Description: The default Time implementation for this library.

Map

Description: The default Map implementation for this library

Upload

Description: The default Upload implementation for this library

RN

Description: The default resource name implementation for this library