TaegisXDRv2

Details

ID	`TaegisXDRv2`
Provider	Sophos
Category	Data Enrichment & Threat Intelligence
From Version	6.2.0
Docker Image	`demisto/python3:3.12.13.10116658`
Supported Modules	Agentix XSIAM

README

Configure Taegis XDR in Cortex

Parameter	Description	Required
Taegis Environment	The environment to utilize	True
Client ID	Client ID as described in the Taegis Documentation	True
Client Secret	Client Secret as described in the Taegis Documentation	True
Use system proxy settings	Defines whether the system proxy is used or not	False
Fetch Incident Type	The type of incident to fetch from Taegis (Alerts or Investigations)	True
Include Assets in Fetch	When using the Investigations fetch type, should assets be included? This can cause API failures or latency and should only be enabled if necessary	False

Commands

You can execute these commands from the CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

taegis-add-evidence-to-investigation

Base Command

!taegis-add-evidence-to-investigation

Inputs

Argument Name	Description	Required
id	The investigation id to update	True
alerts	A list of alert IDs to add to an investigation	False
events	A list of event IDs to add to an investigation	False
alert_query	A Taegis CQL query for alerts to add to the investigation	False

At least one of the inputs alerts, events, or alert_query MUST be defined

Command Example

`!taegis-add-evidence-to-investigation` id=c207ca4c-8a78-4408-a056-49f05d6eb77d alerts="alert://priv:crowdstrike:11772:1677742145475:07e2d9cc-0a04-55ec-890a-97f39d63698e"

Context Example

{
    "TaegisXDR": {
        "InvestigationEvidenceUpdate": {
            "investigationId": "c207ca4c-8a78-4408-a056-49f05d6eb77d"
        }
    }
}

taegis-archive-investigation

Base Command

!taegis-archive-investigation

Inputs

Argument Name	Description	Required
id	The investigation id to archive	True

Command Example

!taegis-archive-investigation id=c207ca4c-8a78-4408-a056-49f05d6eb77d

Context Example

{
    "TaegisXDR": {
        "ArchivedInvestigation": {
            "id": "c207ca4c-8a78-4408-a056-49f05d6eb77d"
        }
    }
}

taegis-create-comment

Base Command

!taegis-create-comment

Inputs

Argument Name	Description	Required
comment	The comment string to add to the investigation	True
id	The investigation ID to add the comment to	True

Command Example

!taegis-create-comment comment="This is a test comment" id="219da0ee-8642-4363-827c-8a6fbd479082"

Context Example

{
    "TaegisXDR": {
        "CommentCreate": {
            "id": "593fa115-abad-4a52-9fc4-2ec403a8a1e4"
        }
    }
}

taegis-create-investigation

Base Command

!taegis-create-investigation

Inputs

Argument Name	Description	Required
title	The subject or description of the investigation	True
priority	The priority for the investigiation [Default: 3]	False
status	The status for the investigation [Default: OPEN]	False
alerts	A list of alert IDs to add to the investigation [Default: []]	False
keyFindings	The Key Findings for the investigation	False
type	The investigation type [Default: SECURITY_INVESTIGATION]	False
assigneeId	The assignee for the investigation [Default: @secureworks]	False
serviceDeskId	A 3rd party ticket number for tracking purposes	False
serviceDeskType	The type of 3rd party ticket number	False
tags	A list of tags to add to the investigation [Default: []]	False

Command Example

!taegis-create-investigation priority=1 title="XSOAR Created Investigation"

Context Example

{
    "TaegisXDR": {
        "Investigation": {
            "id": "593fa115-abad-4a52-9fc4-2ec403a8a1e4"
        }
    }
}

taegis-create-sharelink

Base Command

!taegis-create-sharelink

Inputs

Argument Name	Description	Required
id	The ID of the Taegis element to create a sharelink to	True
type	The type of Taegis element to create a sharelink with	True

Command Example

!taegis-create-sharelink type=investigationId id=219da0ee-8642-4363-827c-8a6fbd479082

Context Example

{
    "TaegisXDR": {
        "ShareLink": {
            "id": "593fa115-abad-4a52-9fc4-2ec403a8a1e4",
            "url": "https://ctpx.secureworks.com/share/593fa115-abad-4a52-9fc4-2ec403a8a1e4"
        }
    }
}

taegis-execute-playbook

Base Command

!taegis-execute-playbook

Inputs

Argument Name	Description	Required
id	Playbook instance ID to execute	True
inputs	JSON object of inputs to pass into the playbook execution	False

Command Example

!taegis-execute-playbook id=UGxheWJvb2tJbnN0YW5jZTphZDNmNzBlZi1mN2U0LTQ0OWYtODJiMi1hYWQwMjQzZTA2NTg=
!taegis-execute-playbook id=UGxheWJvb2tJbnN0YW5jZTphZDNmNzBlZi1mN2U0LTQ0OWYtODJiMi1hYWQwMjQzZTA2NTg= inputs=`{'myvar': 'myval'}`

Context Example

{
    "id": "UGxheWJvb2tFeGVjdXRpb246NGYwZDZiNGQtNWNiZS00NDkxLTg3YzYtMDZkNjkxYzMwMTg4"
}

taegis-fetch-alerts

Base Command

!taegis-fetch-alerts

Input

Argument Name	Description	Default	Required
ids	A list of alerts by IDs	`936c1cc1-db8f-430c-837c-1c914fcca35a`	False
limit	Number of results to when `ids` is not defined	`10`	False
offset	The result to start from when `ids` is not defined	`0`	False
cql_query	The query to utilize when searching for Alerts	`from alert severity >= 0.6 and status='OPEN'`	False

Command Examples

!taegis-fetch-alerts ids=`["6594e97f-a898-5b28-82b2-ea03293cdaa1"]`

Context Example

{
    "TaegisXDR": {
        "Alerts": [
            {
                "id": "c4f33b53-eaba-47ac-8272-199af0f7935b",
                "metadata": {
                    "title": "Test Alert",
                    "description": "This is a test alert",
                    "severity": 0.5,
                },
                "url": "https://ctpx.secureworks.com/alerts/c4f33b53-eaba-47ac-8272-199af0f7935b"
            }
        ]
    }
}

taegis-fetch-assets

Base Command

!taegis-fetch-assets

Input

Argument Name	Description	Default	Required
page		`0`	False
page_size		`10`	False
endpoint_type			False
host_id	ID of the asset to fetch	`e43b545a-580a-4047-b489-4338c1cc4ba1`	False
hostname			False
investigation_id			False
ip_address			False
mac_address			False
os_family			False
os_version			False
sensor_version			False
username			False

Command Examples

!taegis-fetch-assets
!taegis-fetch-assets page=1 page_size=5
!taegis-fetch-assets hostname=MyHostname01
!taegis-fetch-assets host_id=e43b545a-580a-4047-b489-4338c1cc4ba1

Context Example

{
    "TaegisXDR": {
        "Assets": [
            {
              "id": "",
              "ingestTime": "",
              "createdAt": "",
              "updatedAt": "",
              "deletedAt": "",
              "biosSerial": "",
              "firstDiskSerial": "",
              "systemVolumeSerial": "",
              "sensorVersion": "",
              "endpointPlatform": "",
              "hostnames": [{"id": ", "hostname": ""],
              "architecture": "",
              "osFamily": "",
              "osVersion": "",
              "osDistributor": "",
              "osRelease": "",
              "systemType": "",
              "osCodename": "",
              "kernelRelease": "",
              "kernelVersion": "",
              "tags": [ "key": "", "tag": ""],
              "endpointType": "",
              "hostId": "",
              "sensorId": "",
            }
        ]
    }
}

taegis-fetch-comment

Base Command

!taegis-fetch-comment

Inputs

Argument Name	Description	Required
id	The ID of the comment to fetch	True

Command Example

!taegis-fetch-comment id=ff9ca818-4749-4ccb-883a-2ccc6f6c9e0f

Context Example

{
    "TaegisXDR": {
        "Comment": {
            "author_user": {
                "email_normalized": "myuser@email.com",
                "given_name": "John",
                "family_name": "Smith",
                "id": "auth0|000000000000000000000001",
            },
            "id": "ff9ca818-4749-4ccb-883a-2ccc6f6c9e0f",
            "comment": "This is a comment in an investigation",
            "created_at": "2022-01-01T13:04:57.17234Z",
            "deleted_at": None,
            "modified_at": None,
            "parent_id": "c2e09554-833e-41a1-bc9d-8160aec0d70d",
            "parent_type": "investigation",
        }
    }
}

taegis-fetch-comments

Base Command

!taegis-create-comments

Inputs

Argument Name	Description	Required
id	The investigation ID to fetch comments for	True
page	Search page number [Default: 0]	False
page_size	Number of results per page [Default: 10]	False
order_direction	The order direction [Default: DESCENDING]	False

Command Example

!taegis-fetch-comments id=c2e09554-833e-41a1-bc9d-8160aec0d70d

Context Example

{
    "TaegisXDR": {
        "Comments": [
            {
                "author_user": {
                    "email_normalized": "myuser@email.com",
                    "given_name": "John",
                    "family_name": "Smith",
                    "id": "auth0|000000000000000000000001",
                },
                "id": "ff9ca818-4749-4ccb-883a-2ccc6f6c9e0f",
                "comment": "This is a comment in an investigation",
                "created_at": "2022-01-01T13:04:57.17234Z",
                "deleted_at": None,
                "modified_at": None,
                "parent_id": "c2e09554-833e-41a1-bc9d-8160aec0d70d",
                "parent_type": "investigation",
            },
            {
                "author_user": {
                    "email_normalized": "myuser@email.com",
                    "given_name": "John",
                    "family_name": "Smith",
                    "id": "auth0|000000000000000000000001",
                },
                "id": "ff9ca818-4749-4ccb-883a-2ccc6f6c1234",
                "comment": "This is another comment",
                "created_at": "2022-01-02T13:04:57.17234Z",
                "deleted_at": None,
                "modified_at": None,
                "parent_id": "c2e09554-833e-41a1-bc9d-8160aec0d70d",
                "parent_type": "investigation",
            }
        ]
    }
}

taegis-fetch-endpoint

Base Command

!taegis-fetch-endpoint

Inputs

Argument Name	Description	Required
id	Endpoint ID to fetch	True

Command Example

!taegis-fetch-endpoint id=ff9ca818-4749-4ccb-883a-2ccc6f6c9e0f

Context Example

{
    "TaegisXDR": {
        "assetEndpointInfo": {
            "hostId": "",
            "hostName": "",
            "actualIsolationStatus": "",
            "allowedDomain": "",
            "desiredIsolationStatus": "",
            "firstConnectTime": "",
            "moduleHealth": {
                "enabled": ""
                "lastRunningTime": "",
                "moduleDisplayName": "",
            }
            "lastConnectAddress": "",
            "lastConnectTime": "",
            "sensorVersion": ""
        }
    }
}

taegis-fetch-investigation

Base Command

!taegis-fetch-investigation

Inputs

Argument Name	Description	Required
id	Investigation ID to lookup	False
query	If not using ID, the query to utilize when searching investigations [Default: deleted_at is null]	False
page	Search page number [Default: 0]	False
page_size	Number of results per page [Default: 10]	False
order_by	The field to order results by [Default: created_at]	False
order_direction	The order direction [Default: DESCENDING]	False

Command Example

!taegis-fetch-investigation id=936c1cc1-db8f-430c-837c-1c914fcca35a

Context Example

{
    "TaegisXDR": {
        "Investigations": [
            {
                "archived_at": None,
                "created_at": "2022-02-02T13:53:35Z",
                "description": "Test Investigation",
                "id": "c2e09554-833e-41a1-bc9d-8160aec0d70d",
                "key_findings": "",
                "priority": 2,
                "service_desk_id": "",
                "service_desk_type": "",
                "status": "Open",
                "alerts2": [],
                "url": "https://ctpx.secureworks.com/investigations/c2e09554-833e-41a1-bc9d-8160aec0d70d",
            }
        ]
    }
}

taegis-fetch-investigation-alerts

Base Command

!taegis-fetch-investigation-alerts

Inputs

Argument Name	Description	Required
id	Investigation ID to lookup	True
page	Search page number [Default: 0]	False
page_size	Number of results per page [Default: 10]	False

Command Example

!taegis-fetch-investigation-alerts id=936c1cc1-db8f-430c-837c-1c914fcca35a

Context Example

{
    "TaegisXDR": {
        "InvestigationAlerts": [
            {
                "id": "c4f33b53-eaba-47ac-8272-199af0f7935b",
                "description": "Test Alert",
                "message": "This is a test alert",
                "severity": 0.5,
            }
        ]
    }
}

taegis-fetch-playbook-execution

Base Command

!taegis-fetch-playbook-execution

Inputs

Argument Name	Description	Required
id	Playbook execution ID to fetch	True

Command Example

!taegis-fetch-playbook-execution id=UGxheWJvb2tFeGVjdXRpb246NGYwZDZiNGQtNWNiZS00NDkxLTg3YzYtMDZkNjkxYzMwMTg4

Context Example

{
    "TaegisXDR": {
        "PlaybookExecution": {
            "createdAt": "2022-01-01T13:51:24Z",
            "executionTime": 1442,
            "id": "UGxheWJvb2tFeGVjdXRpb246NGYwZDZiNGQtNWNiZS00NDkxLTg3YzYtMDZkNjkxYzMwMTg4",
            "inputs": {
                "alert": {
                    "message": "Test Alert",
                }
            },
            "instance": {
                "name": "Test Alert Instance",
                "playbook": {
                    "name": "Taegis.PagerDutyAlertEvent"
                }
            },
            "outputs": "d6b65662-c1da-4109-8553-c5664918c952",
            "state": "Completed",
            "updatedAt": "2022-01-01T13:51:31Z"
        }
    }
}

taegis-fetch-users

Base Command

!taegis-fetch-users

Inputs

Argument Name	Description	Required
id	The id of the user, in `auth0` format	False
email	The email of the user	False
status	The users to find based on status	False
page		False
page_size		False

Command Example

!taegis-fetch-users id="auth0|123456"

Context Example

{
    "TaegisXDR": {
        "Users": [
            {
                "email": "myuser@email.com",
                "family_name": "Smith",
                "given_name": "John",
                "status": "Registered",
                "user_id": "auth0|123456"
            }
        ]
    }
}

taegis-isolate-asset

Base Command

!taegis-isolate-asset

Input

Argument Name	Description	Default	Required
id	ID of the asset to isolate	`e43b545a-580a-4047-b489-4338c1cc4ba1`	True
reason	The reason for the isolation	`See ticket 12345`	True

Command Examples

!taegis-isolate-asset id="e43b545a-580a-4047-b489-4338c1cc4ba1" reason="See ticket 12345"

Context Example

{
    "TaegisXDR": {
        "AssetIsolation": {
            "id": "e43b545a-580a-4047-b489-4338c1cc4ba1"
        }
    }
}

taegis-fetch-events

Beta Command: This is a beta command, which lets you implement and test pre-release software. Since the command is beta, it might contain bugs. Updates to the command during the beta phase might include non-backward compatible features. We appreciate your feedback on the quality and usability of the command to help us identify issues, fix them, and continually improve.

Base Command

taegis-fetch-events

Input

Argument Name	Description	Required
ids	A comma-separated list of event IDs to return.	False
cql_query	The Taegis CQL query string to use for searching events (e.g. `FROM process EARLIEST=-1d \\| head 10`). If not defined, defaults to `FROM * EARLIEST=-1m \\| head 50`.	False
limit	The maximum number of events to return. For standard CQL searches, the limit is passed as a GraphQL variable. For user-provided queries, embed the limit directly in the CQL string (e.g., `\\| head 100`). Default is 50.	False
offset	The number of events to skip before returning results. Default is 0.	False
next	The pagination cursor token returned from a previous `taegis-fetch-events` call. Use this to retrieve the next page of results.	False
fields	The fields to return from the query.	False
tenant_id	The tenant to run against if using an MSP. If no tenant is provided, the tenant of the generated credentials is used.	False

CQL Query Time Field Reference

Scenario	Use This Field	Why?
Incident Reconstruction	event_time	You need to see the exact sequence of the attacker’s steps.
Real-time Monitoring	EARLIEST=-1m	You want to see everything that hits the platform in the last 60 seconds.
Compliance/Audit	ingest_time	You need to prove when Secureworks actually received the record.
Offline Host Sync	ingest_time	You want to find data from a laptop that was just turned back on after a weekend.

Command example

!taegis-fetch-events
!taegis-fetch-events cql_query="FROM process EARLIEST=-1d | head 10"
!taegis-fetch-events cql_query="FROM dnsquery WHERE query_name MATCHES ('*.xyz', '*.top') EARLIEST=-24h" limit=100
!taegis-fetch-events ids="event-12345-67890,event-12345-67891"
!taegis-fetch-events next="eyJvZmZzZXQiOiAxMH0="

Context Example

[
    {
        "TaegisXDR": {
            "Events": [
                {
                    "id": "event-12345-67890",
                    "metadata": {
                        "event_type": "process",
                        "event_time": "2024-05-20T14:30:05.123Z",
                        "tenant_id": "999-000-111",
                        "sensor_id": "win-endpoint-01"
                    },
                    "parent_process_id": "456",
                    "image_path": "C:\\Windows\\System32\\cmd.exe",
                    "commandline": "cmd.exe /c \"whoami\"",
                    "username": "admin_user",
                    "next": "CursorToken_Batch01_Seq99"
                },
                {
                    "id": "event-12345-67891",
                    "metadata": {
                        "event_type": "netflow",
                        "event_time": "2024-05-20T14:30:10.456Z",
                        "tenant_id": "999-000-111",
                        "sensor_id": "fw-edge-02"
                    },
                    "source_ip": "1.1.1.1",
                    "destination_ip": "8.8.8.8",
                    "destination_port": 53,
                    "protocol": "UDP",
                    "next": "CursorToken_Batch01_Seq99"
                }
            ]
        }
    }
]

Context Output

Path	Type	Description
TaegisXDR.Events.id	String	The unique identifier of the event.
TaegisXDR.Events.metadata.event_type	String	The type of event (e.g., process, netflow, dnsquery).
TaegisXDR.Events.metadata.event_time	String	The timestamp when the event occurred.
TaegisXDR.Events.metadata.tenant_id	String	The tenant ID associated with the event.
TaegisXDR.Events.metadata.sensor_id	String	The sensor ID that generated the event.
TaegisXDR.Events.parent_process_id	String	The parent process ID (process events).
TaegisXDR.Events.image_path	String	The image/executable path (process events).
TaegisXDR.Events.commandline	String	The command line string (process events).
TaegisXDR.Events.username	String	The username associated with the event.
TaegisXDR.Events.source_ip	String	The source IP address (netflow events).
TaegisXDR.Events.destination_ip	String	The destination IP address (netflow events).
TaegisXDR.Events.destination_port	Number	The destination port number (netflow events).
TaegisXDR.Events.protocol	String	The network protocol (netflow events).
TaegisXDR.Events.next	String	Pagination cursor token for retrieving the next page of results.

taegis-update-alert-status

Base Command

!taegis-update-alert-status

Input

Argument Name	Description	Default	Required
ids	A comma-separated list of alerts by IDs	`alert://priv:crowdstrike:11772:1666269058114:59284e28-4ec8-542b-a4a1-452c3688bc1a`	True
status	The status to update the alert(s) with	`FALSE_POSITIVE`	True
reason	A comment/reason for the alert status update	`See ticket 13245`	False

Permitted Status Values

FALSE_POSITIVE
NOT_ACTIONABLE
OPEN
TRUE_POSITIVE_BENIGN
TRUE_POSITIVE_MALICIOUS
OTHER

Command Examples

!taegis-update-alert-status ids="alert://priv:crowdstrike:11772:1677742145475:07e2d9cc-0a04-55ec-890a-97f39d63698e" status=NOT_ACTIONABLE reason="Test Reason"

Context Example

{
    "TaegisXDR": {
        "AlertStatusUpdate": {
            "reason": "feedback updates successfully applied",
            "resolution_status": "SUCCESS"
        }
    }
}

taegis-update-comment

Base Command

!taegis-update-comment

Inputs

Argument Name	Description	Required
comment	The comment string to add to the investigation	True
id	The comment ID to update	True

Command Example

!taegis-update-comment id="ff9ca818-4749-4ccb-883a-2ccc6f6c9e0f" comment="Newly updated comment"

Context Example

{
    "TaegisXDR": {
        "CommentUpdate": {
            "id": "593fa115-abad-4a52-9fc4-2ec403a8a1e4"
        }
    }
}

taegis-update-investigation

Base Command

!taegis-update-investigation

Inputs

Argument Name	Description	Required
id	Investigation ID to update	True
title	The title of the investigation	False
keyFindings	The investigation Key Findings	False
prioirity	The priority of the Investigation (1-5)	False
status	The current status of the Investigation	False
assigneeId	The id of a user to assign, in `auth0\|12345` format	False
serviceDeskId	A 3rd party ticket number for tracking purposes	False
serviceDeskType	The type of 3rd party ticket number	False
tags	A list of tags to add to the investigation [Default: []]	False

Note: At least 1 of the above inputs (in addition to id) must be defined

Permitted Status Values

Active
Awaiting Action
Closed: Authorized Activity
Closed: Confirmed Security Incident
Closed: False Positive Alert
Closed: Inconclusive
Closed: Informational
Closed: Not Vulnerable
Closed: Threat Mitigated
Open
Suspended

Command Example

!taegis-update-investigation id="936c1cc1-db8f-430c-837c-1c914fcca35a" priority=3 status="OPEN"

Context Example

{
    "TaegisXDR": {
        "InvestigationUpdate": {
            "id": "c2e09554-833e-41a1-bc9d-8160aec0d70d"
        }
    }
}

taegis-unarchive-investigation

Base Command

!taegis-unarchive-investigation

Inputs

Argument Name	Description	Required
id	The investigation id to unarchive	True

Command Example

!taegis-unarchive-investigation id=c207ca4c-8a78-4408-a056-49f05d6eb77d

Context Example

{
    "TaegisXDR": {
        "UnarchivedInvestigation": {
            "id": "c207ca4c-8a78-4408-a056-49f05d6eb77d"
        }
    }
}

Configuration parameters

environment — Taegis Environment (required)
insecure — Trust any certificate (not secure)
proxy — Use system proxy settings
client_id — Client ID (required)
client_secret — Client Secret (required)
isFetch — Fetch incidents
max_fetch — Maximum number of incidents per fetch
incidentFetchInterval — Incidents Fetch Interval
first_fetch — First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)
incidentType — Incident type
include_assets — Include Assets in Fetch
fetch_type — Fetch Incident Type

Commands (21)

taegis-add-evidence-to-investigation
Add alerts and events to an existing investigation.
taegis-archive-investigation
Archive an investigation.
taegis-create-comment
Create a comment on an investigation.
taegis-create-investigation
Create an Investigation within Taegis.
taegis-create-sharelink
Creates a ShareLink to a Taegis element, such as an alert or investigation.
taegis-execute-playbook
Executes a Taegis playbook instance.
taegis-fetch-alerts
List Taegis alerts by ID.
taegis-fetch-assets
Fetch assets based on search criteria.
taegis-fetch-comment
Fetch comment by comment ID.
taegis-fetch-comments
Fetch comments by Investigation ID.
taegis-fetch-endpoint
Fetch endpoint information.
taegis-fetch-events
This is a beta command, which lets you implement and test pre-release software. Since the command is beta, it might contain bugs. Updates to the command during the beta phase might include non-backward compatible features. We appreciate your feedback on the quality and usability of the command to help us identify issues, fix them, and continually improve. Fetches Taegis events using a CQL query string or a list of event IDs. Supports pagination via the next cursor token returned in results. If no cql_query is provided, defaults to "FROM * EARLIEST=-1m | head 50".
taegis-fetch-investigation
Fetch all investigations or a specific investigation.
taegis-fetch-investigation-alerts
Fetch Alert IDs related to a specific investigation.
taegis-fetch-playbook-execution
Fetch the results of a Taegis playbook instance execution.
taegis-fetch-users
Fetch a user by ID or email address.
taegis-isolate-asset
Isolate a specific asset.
taegis-unarchive-investigation
Unarchive an investigation.
taegis-update-alert-status
Update the status of an alert.
taegis-update-comment
Update an existing comment.
taegis-update-investigation
Update an existing investigation.

Source

TaegisXDRv2.py TaegisXDRv2_test.py TaegisXDRv2.yml TaegisXDRv2_description.md command_examples.txt

Download History Raw

sectionorder:
- Connect
- Collect
commonfields:
  id: TaegisXDRv2
  version: -1
name: TaegisXDRv2
display: TaegisXDR v2
category: Data Enrichment & Threat Intelligence
provider: Sophos
description: For integration with the Secureworks Taegis XDR platform.
configuration:
- display: Taegis Environment
  name: environment
  type: 15
  required: true
  options:
  - US1 (Charlie)
  - US2 (Delta)
  - US3 (Foxtrot)
  - EU (Echo)
  additionalinfo: Used to determine the URL and API endpoint to utilize for your tenant
  section: Connect
- display: Trust any certificate (not secure)
  name: insecure
  defaultvalue: "false"
  type: 8
  required: false
  section: Connect
- display: Use system proxy settings
  name: proxy
  type: 8
  required: false
  section: Connect
- display: Client ID
  name: client_id
  type: 4
  required: true
  section: Connect
- display: Client Secret
  name: client_secret
  type: 4
  required: true
  section: Connect
- display: Fetch incidents
  name: isFetch
  type: 8
  required: false
  section: Collect
- display: Maximum number of incidents per fetch
  name: max_fetch
  defaultvalue: "15"
  type: 0
  required: false
  additionalinfo: The maximum limit is 200.
  section: Collect
- display: Incidents Fetch Interval
  name: incidentFetchInterval
  defaultvalue: "1"
  type: 19
  required: false
  section: Collect
- defaultvalue: 1 day
  display: First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)
  name: first_fetch
  required: false
  type: 0
  section: Collect
- display: Incident type
  name: incidentType
  type: 13
  required: false
  section: Collect
- display: Include Assets in Fetch
  name: include_assets
  defaultvalue: "false"
  type: 8
  required: false
  additionalinfo: An error can occur when the API is slow or there are a large numbers of assets being added to a new incident/investigation. Disabling this will fetch incidents without including asset information, allowing time for the investigation creation to be completed.
  section: Collect
- display: Fetch Incident Type
  name: fetch_type
  type: 15
  required: false
  options:
  - alerts
  - investigations
  additionalinfo: The type of Taegis asset to fetch when using fetch-incidents
  section: Collect
script:
  script: ''
  type: python
  commands:
  - name: taegis-fetch-alerts
    arguments:
    - name: ids
      description: A list of alert IDs or string of comma-separated alert IDs to return.
      isArray: true
    - name: cql_query
      description: The Taegis CQL query to for searching Alerts.
    - name: limit
      default: true
      description: Number of results to return per page.
      defaultValue: "10"
    - name: offset
      description: The results to start with.
      defaultValue: "0"
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.Alerts
      description: List of Taegis alerts.
    description: List Taegis alerts by ID.
  - name: taegis-fetch-investigation
    arguments:
    - name: id
      description: The investigation ID to lookup.
    - name: page
      description: The page number for fetching investigations.
      defaultValue: "0"
    - name: page_size
      description: Number of investigations to return.
      defaultValue: "10"
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: query
      description: The Taegis query string to utilize for searching investigations.
      defaultValue: deleted_at is null
    - name: order_by
      description: The field to order by when performing a search.
      defaultValue: created_at
    - name: order_direction
      description: The order direction when performing a search.
      defaultValue: desc
    - name: fields
      description: The fields to return in the results.
    outputs:
    - contextPath: TaegisXDR.Investigations
      description: Dictionary of the located Taegis investigation.
    description: Fetch all investigations or a specific investigation.
  - name: taegis-create-investigation
    arguments:
    - name: title
      required: true
      description: The title of the investigation.
    - name: priority
      required: true
      default: true
      auto: PREDEFINED
      predefined:
      - "1"
      - "2"
      - "3"
      - "4"
      description: The priority of the investigation.
      defaultValue: "2"
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    - name: alerts
      description: A list of alert IDs or string of comma-separated alert IDs to add to the investigation during creation.
      isArray: true
    - name: keyFindings
      description: The key findings to utilize within the Investigation.
    - name: type
      auto: PREDEFINED
      predefined:
      - SECURITY_INVESTIGATION
      - INCIDENT_RESPONSE
      - THREAT_HUNT
      - MANAGED_XDR_THREAT_HUNT
      - CTU_THREAT_HUNT
      - MANAGED_XDR_ELITE_THREAT_HUNT
      - SECUREWORKS_INCIDENT_RESPONSE
      description: The investigation type to create.
      defaultValue: SECURITY_INVESTIGATION
    - name: assigneeId
      description: The assignee for the investigation.
      defaultValue: '@secureworks'
    - name: status
      auto: PREDEFINED
      predefined:
      - OPEN
      - ACTIVE
      - AWAITING_ACTION
      - SUSPENDED
      - CLOSED_AUTHORIZED_ACTIVITY
      - CLOSED_CONFIRMED_SECURITY_INCIDENT
      - CLOSED_FALSE_POSITIVE_ALERT
      - CLOSED_INCONCLUSIVE
      - CLOSED_INFORMATIONAL
      - CLOSED_NOT_VULNERABLE
      - CLOSED_THREAT_MITIGATED
      description: The investigation status.
      defaultValue: OPEN
    - name: tags
      description: A list of tags or string of comma-separated tags to add to the investigation.
      isArray: true
    outputs:
    - contextPath: TaegisXDR.Investigation
      description: The investigation ID that was created.
    description: Create an Investigation within Taegis.
  - name: taegis-update-investigation
    arguments:
    - name: id
      required: true
      description: The investigation ID to update.
    - name: priority
      auto: PREDEFINED
      predefined:
      - "1"
      - "2"
      - "3"
      - "4"
      description: The priority of the investigation.
    - name: keyFindings
      description: The Key Findings field of the investigation.
    - name: status
      auto: PREDEFINED
      predefined:
      - OPEN
      - ACTIVE
      - AWAITING_ACTION
      - SUSPENDED
      - CLOSED_AUTHORIZED_ACTIVITY
      - CLOSED_CONFIRMED_SECURITY_INCIDENT
      - CLOSED_FALSE_POSITIVE_ALERT
      - CLOSED_INCONCLUSIVE
      - CLOSED_INFORMATIONAL
      - CLOSED_NOT_VULNERABLE
      - CLOSED_THREAT_MITIGATED
      description: New status for the investigation.
    - name: assigneeId
      description: The auth0 ID of a user, in 'auth0|12345' format.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    - name: type
      auto: PREDEFINED
      predefined:
      - SECURITY_INVESTIGATION
      - INCIDENT_RESPONSE
      - THREAT_HUNT
      - MANAGED_XDR_THREAT_HUNT
      - CTU_THREAT_HUNT
      - MANAGED_XDR_ELITE_THREAT_HUNT
      - SECUREWORKS_INCIDENT_RESPONSE
      description: The type of investigation.
    - name: title
      description: The title of the investigation.
    - name: serviceDeskId
      description: A 3rd party ticket to associate with the Taegis Investigation (usually the XSOAR incident).
    - name: serviceDeskType
      description: The type of 3rd party ticket to associate with the Taegis Investigation (e.g. XSOAR).
    - name: tags
      description: A list of tags or string of comma-separated tags to add to the investigation.
      isArray: true
    outputs:
    - contextPath: TaegisXDR.InvestigationUpdate
      description: ID of the updated Taegis investigation.
    description: Update an existing investigation.
  - name: taegis-fetch-investigation-alerts
    arguments:
    - name: id
      required: true
      description: The investigation ID related to the alerts.
    - name: page
      description: Page number of the investigation alerts.
      defaultValue: "0"
    - name: page_size
      description: Number of alerts per investigation query.
      defaultValue: "10"
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.InvestigationAlerts
      description: List of alerts related to a Taegis investigation.
    description: Fetch Alert IDs related to a specific investigation.
  - name: taegis-execute-playbook
    arguments:
    - name: id
      required: true
      description: The ID of the playbook instance to execute.
    - name: inputs
      description: JSON Object of optional playbook inputs.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.Execution
      description: The playbook execution ID.
      type: string
    description: Executes a Taegis playbook instance.
    execution: true
  - name: taegis-fetch-playbook-execution
    arguments:
    - name: id
      required: true
      description: Playbook execution ID.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.PlaybookExecution
      description: Returns related execution information.
    description: Fetch the results of a Taegis playbook instance execution.
  - name: taegis-fetch-comment
    arguments:
    - name: id
      required: true
      description: The ID of the comment to fetch.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.Comment
      description: Return the comment.
    description: Fetch comment by comment ID.
  - name: taegis-fetch-comments
    arguments:
    - name: id
      required: true
      description: The ID of the investigation related to the comments.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: page
      description: The page number for fetching comments.
      defaultValue: "0"
    - name: page_size
      description: Number of comments to return.
      defaultValue: "10"
    - name: order_direction
      auto: PREDEFINED
      predefined:
      - ASCENDING
      - DESCENDING
      description: The order direction when performing a search.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.Comments
      description: A list of comments to return.
    description: Fetch comments by Investigation ID.
  - name: taegis-create-comment
    arguments:
    - name: comment
      required: true
      description: The comment string to add to the parent.
    - name: id
      required: true
      description: The investigation that the comment is being added to.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.CommentCreate
      description: The created comment information.
    description: Create a comment on an investigation.
  - name: taegis-update-comment
    arguments:
    - name: id
      required: true
      description: The ID of the comment to update.
    - name: comment
      required: true
      description: String to update/replace the comment with.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.CommentUpdate
      description: The comment update results.
    description: Update an existing comment.
  - name: taegis-fetch-users
    arguments:
    - name: id
      description: The auth0 ID, in 'auth0|12345' format.
    - name: email
      description: The email address to search for.
    - name: status
      description: Search by user status.
    - name: page
      description: Page for results.
      defaultValue: "0"
    - name: page_size
      description: Results to return per page.
      defaultValue: "10"
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.Users
      description: The located user(s).
    description: Fetch a user by ID or email address.
  - name: taegis-archive-investigation
    arguments:
    - name: id
      required: true
      description: ID of investigation to update.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.ArchivedInvestigation
      description: The results from archiving an investigation.
    description: Archive an investigation.
  - name: taegis-unarchive-investigation
    arguments:
    - name: id
      required: true
      description: ID of investigation to update.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.UnarchivedInvestigation
      description: The results from unarchiving an investigation.
    description: Unarchive an investigation.
  - name: taegis-update-alert-status
    arguments:
    - name: ids
      required: true
      description: A list of alert IDs or string of comma-separated alert IDs to return.
      isArray: true
    - name: status
      required: true
      auto: PREDEFINED
      predefined:
      - FALSE_POSITIVE
      - NOT_ACTIONABLE
      - OPEN
      - TRUE_POSITIVE_BENIGN
      - TRUE_POSITIVE_MALICIOUS
      description: The status to update the alert with.
    - name: reason
      description: A simple comment/reason for the status change.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.AlertStatusUpdate
      description: The result of the alert status update.
    description: Update the status of an alert.
  - name: taegis-fetch-assets
    arguments:
    - name: page
      description: Search results page number.
      defaultValue: "0"
    - name: page_size
      description: The number of results per-page.
      defaultValue: "10"
    - name: endpoint_type
      description: Filter assets by asset type.
    - name: host_id
      description: Filter assets by host ID.
    - name: hostname
      description: Filter assets by hostname.
    - name: investigation_id
      description: Filter assets by related investigation ID.
    - name: ip_address
      description: Filter assets by IP address.
    - name: mac_address
      description: Filter assets by MAC address.
    - name: os_family
      description: Filter assets by OS family.
    - name: os_version
      description: Filter assets by OS version.
    - name: sensor_version
      description: Filter assets by sensor version.
    - name: username
      description: Filter assets by username.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.Assets
      description: A list of located assets.
    description: Fetch assets based on search criteria.
  - name: taegis-isolate-asset
    arguments:
    - name: id
      required: true
      description: Asset ID to isolate.
    - name: reason
      required: true
      description: A reason for the isolation.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.AssetIsolation
      description: Results from the asset isolation.
    description: Isolate a specific asset.
  - name: taegis-fetch-endpoint
    arguments:
    - name: id
      required: true
      description: The endpoint ID to fetch.
    - name: tenant_id
      description: The tenant to run against if an MSP. If no tenant  provided, the tenant of the generated credentials is used.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.Endpoint
      description: Results from fetching the endpoint information.
    description: Fetch endpoint information.
  - name: taegis-create-sharelink
    arguments:
    - name: id
      required: true
      description: The ID of the alert, investigation, etc.
    - name: type
      required: true
      auto: PREDEFINED
      predefined:
      - alertId
      - investigationId
      - queryId
      - endpointDetails
      - playbookTemplateId
      - playbookInstanceId
      - playbookExecutionId
      - connectorId
      - connectionId
      - eventId
      description: The type of Taegis element to create the ShareLink against.
    - name: fields
      description: The fields to return from the query.
    outputs:
    - contextPath: TaegisXDR.ShareLink
      description: Results from creating the ShareLink.
    description: Creates a ShareLink to a Taegis element, such as an alert or investigation.
  - name: taegis-fetch-events
    arguments:
    - name: ids
      description: A comma-separated list of event IDs to return.
      isArray: true
    - name: cql_query
      description: The Taegis CQL query string to use for searching events (e.g. "FROM process EARLIEST=-1d | head 10"). If not defined, defaults to "FROM * EARLIEST=-1m | head 50".
    - name: limit
      description: The maximum number of events to return. For standard CQL searches, the limit is passed as a GraphQL variable. For user-provided queries, embed the limit directly in the CQL string (e.g., "| head 100").
      defaultValue: "50"
    - name: offset
      description: The number of events to skip before returning results.
      defaultValue: "0"
    - name: next
      description: The pagination cursor token returned from a previous taegis-fetch-events call. Use this to retrieve the next page of results.
    - name: fields
      description: The fields to return from the query.
    - name: tenant_id
      description: The tenant to run against if using an MSP. If no tenant is provided, the tenant of the generated credentials is used.
    outputs:
    - contextPath: TaegisXDR.Events.id
      description: The unique identifier of the event.
      type: String
    - contextPath: TaegisXDR.Events.metadata.event_type
      description: The type of event (e.g., process, netflow, dnsquery).
      type: String
    - contextPath: TaegisXDR.Events.metadata.event_time
      description: The timestamp when the event occurred.
      type: String
    - contextPath: TaegisXDR.Events.metadata.tenant_id
      description: The tenant ID associated with the event.
      type: String
    - contextPath: TaegisXDR.Events.metadata.sensor_id
      description: The sensor ID that generated the event.
      type: String
    - contextPath: TaegisXDR.Events.parent_process_id
      description: The parent process ID associated with the event (process events).
      type: String
    - contextPath: TaegisXDR.Events.image_path
      description: The image/executable path associated with the event (process events).
      type: String
    - contextPath: TaegisXDR.Events.commandline
      description: The command line string associated with the event (process events).
      type: String
    - contextPath: TaegisXDR.Events.username
      description: The username associated with the event.
      type: String
    - contextPath: TaegisXDR.Events.source_ip
      description: The source IP address (netflow events).
      type: String
    - contextPath: TaegisXDR.Events.destination_ip
      description: The destination IP address (netflow events).
      type: String
    - contextPath: TaegisXDR.Events.destination_port
      description: The destination port number (netflow events).
      type: Number
    - contextPath: TaegisXDR.Events.protocol
      description: The network protocol (netflow events).
      type: String
    - contextPath: TaegisXDR.Events.next
      description: The pagination cursor token for retrieving the next page of results.
      type: String
    description: 'This is a beta command, which lets you implement and test pre-release software. Since the command is beta, it might contain bugs. Updates to the command during the beta phase might include non-backward compatible features. We appreciate your feedback on the quality and usability of the command to help us identify issues, fix them, and continually improve. Fetches Taegis events using a CQL query string or a list of event IDs. Supports pagination via the next cursor token returned in results. If no cql_query is provided, defaults to "FROM * EARLIEST=-1m | head 50".'
  - name: taegis-add-evidence-to-investigation
    arguments:
    - name: id
      required: true
      description: The investigation ID to update.
    - name: alerts
      description: A list of alert IDs or string of comma-separated alert IDs to add.
      isArray: true
    - name: events
      description: A list of alert IDs or string of comma-separated event IDs to add.
    - name: alert_query
      description: A CQL query to find alerts to add to the investigation.
    outputs:
    - contextPath: TaegisXDR.InvestigationEvidenceUpdate
      description: The investigation that received the update.
    description: Add alerts and events to an existing investigation.
  dockerimage: demisto/python3:3.12.13.10116658
  isfetch: true
  runonce: false
  subtype: python3
  isFetchSamples: true
fromversion: 6.2.0
tests:
- No tests (auto formatted)