XDR Python SDK のはじめ方🔗

注意

テナントのリージョンに応じて、以下のリージョンまたは環境識別子を使用してください。

US1 または charlie または production： https://ctpx.secureworks.com/
US2 または delta： https://delta.taegis.secureworks.com/
US3 または foxtrot： https://foxtrot.taegis.secureworks.com/
EU または echo： https://echo.taegis.secureworks.com/

Python SDK のインストール🔗

Python 3.8 以上がすでにインストールされていることを前提に、Python SDK をインストールします。

python -m pip install taegis-sdk-python

認証🔗

インストール時に Secureworks® Taegis™ XDR アカウントでの認証が求められます。これはパスワードとMFAトークンが必要ですが、組織がSSO認証を登録している場合は不要です。SSOが有効な場合、デバイスコード認証リンクが表示されます。

詳細は Taegis™ XDR Python SDK での認証を参照してください。

使用例🔗

from taegis_sdk_python import GraphQLService

from pprint import pprint as pp

service = GraphQLService()

results = service.users.query.current_tdruser()

pp(results)

SDK の探索🔗

標準の Python help は XDR の Python SDK に組み込まれています。GraphQLService オブジェクト構造内の任意のオブジェクトで使用し、利用可能な内容や呼び出し方法を確認できます。

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.alerts.types import SearchRequestInput

service = GraphQLService()

# Find available services (Service Endpoints)

help(service)
# Find available service queries (or mutations or subscriptions)

help(service.alerts.query)
help(service.alerts.mutation)
help(service.alerts.subscription)
# Reference documentation on specific endpoint

help(service.alerts.query.alerts_service_search)
# Help on an Input variable

help(SearchRequestInput)

# service

class GraphQLService(builtins.object)
 |  GraphQLService(*, environment: Optional[str] = None, tenant_id: Optional[str] = None, environments: Optional[Dict[str, str]] = None, gateway: Optional[str] = None)
...
 |  agent
 |      Events Service Endpoint.
 |
 |  alerts
 |      Alerts2 Service Endpoint.
 |
 |  assets
 |      Assets
...
# Alerts Query

class TaegisSDKAlertsQuery(builtins.object)
 |  TaegisS
...
 |  alerts_service_aggregate_alerts_by_severity(self, in_: 'Optional[AggregateAlertsBySeverityInputInput]' = None) -> 'AlertsAggregateResponse'
 |      Pull alert severity aggregates based on `group_by` parameters: domain, watchlist, hostname, detector, user..
 |
 |  alerts_service_alerts_dashboard_triage(self, in_: 'Optional[TriageDashboardInputInput]' = None) -> 'TriageDashboardOutput'
 |      None.
 |
 |  alerts_service_poll(self, in_: 'Optional[PollRequestInput]' = None) -> 'AlertsResponse'
 |      Poll for results for a specific `search
...
# SearchRequestInput

class SearchRequestInput(builtins.object)
 |  SearchRequestInput(cql_query: Optional[str] = None, offset: Optional[int] = None, limit: Optional[int] = None) -> None
...

コンテキストマネージャ🔗

サービスオブジェクトはコンテキストマネージャとしても利用でき、APIコール時にデフォルト値を一時的に上書きできます。これには environment、tenant_id、output、access_token などのフィールドが含まれます。

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.alerts.types import SearchRequestInput

service = GraphQLService()

with service(
    environment="delta",
    tenant_id="00000",
    output="""
        reason
        alerts {
            total_results
            list {
                id
                tenant_id
                metadata {
                    title
                    severity
                }
                status
            }
        }
    """,
):
    result = service.alerts.query.alerts_service_search(SearchRequestInput(
        offset=0,
        limit=10,
        cql_query="""
        FROM alert
        WHERE
            severity >= 0.6
        EARLIEST=-1d
        """
    ))

GraphQL 出力の絞り込み🔗

XDR Python SDK は、デフォルトで GraphQL API から返されるすべての利用可能なフィールドを提供します。これは探索に役立ちますが、返したいフィールドを定義することも可能です。

必要な内容を決めるために、build_output_string ユーティリティを使用できます。これは、返却型のすべての可能なフィールドを含む出力オブジェクトの文字列表現を返します。これを参考にして独自の出力を作成し、不要なフィールドを削除できます。

from taegis_sdk_python import build_output_string
from taegis_sdk_python.services.alerts.types import AlertsResponse

print(build_output_string(AlertsResponse))

reason search_id status alerts { previous_offset total_parts list { reference_details { reference {
description url type } } parent_tenant_id entities { entities relationships { relationship to_entity
from_entity type } } sensor_types suppression_rules { id version } resolution_history { timestamp {
nanos seconds } user_id status num_alerts_affected id reason } enrichment_details {
business_email_compromise { user_name source_address_geo_summary { country { confidence iso_code
geoname_id code } city { confidence locale_names { record { value key } } geoname_id name } location {
timezone latitude longitude us_metro_code radius metro_code gmt_offset } asn { autonomous_system_no
autonomous_system_org } continent { code geoname_id } } source_address }
...

サービスオブジェクトはコンテキストマネージャとして呼び出され、output に新しい GraphQL 出力フィールドが割り当てられます。同じオブジェクトが返され、未定義のフィールドには None が割り当てられます。

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.alerts.types import SearchRequestInput

from pprint import pprint as pp

service = GraphQLService()
with service(output="search_id alerts { list { id status metadata { title severity confidence } } }")
    results = service.alerts.query.alerts_service_search(
        SearchRequestInput(
            offset=0,
            limit=10,
            cql_query="""
            FROM alert
            WHERE
                severity >= 0.6
            EARLIEST=-1d
            """,
        )
    )
pp(results)

任意のクエリ🔗

クエリ、ミューテーション、サブスクリプション用に独自のAPIコールを作成できます。特定のサービスが異なる設定になっている場合があるため、利用したいサービスエンドポイントを使用することを推奨します。

execute_query
execute_mutation
execute_subscription

from taegis_sdk_python import GraphQLService

from pprint import pprint as pp

service = GraphQLService()

results = service.alerts.execute_query(
    endpoint="alertsServiceSearch",
    variables={
        "in": {
            "limit": 3,
            "offset": 0,
            "cql_query": """
            FROM alert
            WHERE
                severity >= 0.6
            EARLIEST=-1d
            """
        }
    },
    output="""
        search_id
        alerts {
            list {
                id
                tenant_id
                metadata {
                    title
                    severity
                }
                status
            }
        }
    """
)
pp(results)

生クエリ🔗

独自の生の GraphQL 文字列も実行できます。これにより最大限の柔軟性が得られますが、ガードレールは最小限となります。

execute
subscribe

from taegis_sdk_python import GraphQLService

from pprint import pprint as pp

service = GraphQLService()

results = service.investigations.execute("""
    query investigationsStatusCount
    {
        investigationsStatusCount
        {
            open closed active awaiting_action suspended total
        }
    }
""")
pp(results)

ヘルパー🔗

`build_output_string` ユーティリティ🔗

build_output_string ユーティリティは、返却型のすべての可能なフィールドを含む出力オブジェクトの文字列表現を返します。

from taegis_sdk_python import build_output_string
from taegis_sdk_python.services.alerts.types import AlertsResponse

print(build_output_string(AlertsResponse))

`_build_output_query` ユーティリティ🔗

_build_output_query サービスエンドポイントは、完全な GraphQL クエリ文字列の作成を支援します。スキーマからクエリを構築するため、正しいサービスエンドポイントからスキーマを取得していることを確認してください。

from taegis_sdk_python import GraphQLService, build_output_string
from taegis_sdk_python.services.investigations.types import InvestigationStatusCountResponse

service = GraphQLService()
schema = service.alerts.get_sync_schema()

print(service.alerts._build_output_query(
    operation_type="query",
    endpoint="investigationsStatusCount",
    graphql_field=schema.query_type.fields.get("investigationsStatusCount"),
    output=build_output_string(InvestigationStatusCountResponse)
))