taegis-sdk-python is Secureworks Taegis XDR Python SDK. It provides an easy to use API that enables Python developers to configure and manage Taegis XDR.
- Python 3.8 or higher.
- Set
CLIENT_IDandCLIENT_SECRETenvironment variables as described in the Taegis XDR Documenation. Credentials used to create these variables MUST haveAdmin Privilegesotherwise you wont have enough permissions to issue calls.
-
Install git secrets
brew install gitleaks -
Install pre-commit
brew install pre-commit&pre-commit install -
Check for secrets
make secretsor commit and the pre-commit hook will install -
Open a terminal
-
Change to your favorite local directory (i.e.
cd /opt) -
Clone the repository
git clone git@github.com:secureworks/tdr-sdk-python.git
-
Create a Virtual Environment
python -m venv venv
-
Activate Virtual Environment
source ./venv/bin/activate -
Install the SDK
pip install "/path/to/local/sdk" For example: pip install /opt/taegis-sdk-python
To use the SDK, you must first import the GraphQLService
from taegis_sdk_python.services import GraphQLService
# Instantiate GraphQL Service
service = GraphQLService()Now that you have the GraphQLService, you can make requests and process responses for Taegis XDR Services. The following example uses the Investigations Service to send a query to get all available investigations
# Get all Investigations
raw_data, all_investigations = service.investigations.query.get_all_investigations(page=1, per_page=20)
# Print list of Investigations as a dictionary
for data in raw_data:
print(str(data))
# Print list of Investigation dataclasses
for investigation in all_investigations:
print(investigation)The SDK enables users to override the output property of a query to retrieve specific response fields. For example, the following code will ONLY return the ids of all Closed Investigations. This query runs inside the Service Context.
from taegis_sdk_python.services import GraphQLService
from taegis_sdk_python.services.investigations.enums import InvestigationStatusEnum
service = GraphQLService()
# specify the output fields, and start the service context
with service.core(output="{ id }"):
raw_data, all_investigations = service.investigations.query.get_all_investigations(
status=InvestigationStatusEnum.closed(),
page=1,
per_page=20
)
for inv in all_investigations:
print(inv.id)Advanced users can leverage the power of the SDK to execute custom queries. If an invalid query is passed the system will respond with GraphQLSyntaxError -> Syntax Error, otherwise the query will be executed and results will be returned as a dictionary of data.
from taegis_sdk_python.services import GraphQLService
gql_query = """
query investigationsStatusCount {
investigationsStatusCount {
open
closed
active
awaiting_action
suspended
total
}
}
"""
result = service.core.execute_gql_string(gql_query)The GraphQLService supports an execution history log. This feature is currently NOT supported for Custom Queries.
for history_item in service.core.history:
print(history_item.as_json())