Taegis SDK for Python 使用例🔗

検出🔗

検出の検索🔗

以下の例は、クエリ言語を使用して検出の検索を実行し、関心のある一般的なフィールドを返します。このクエリ例は、最も早い/最新の期間内に作成され、まだフィードバックが受け取られていない高/重大な検出を返します。

注意

この例で使用されているすべてのタイムスタンプはUTCです。

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

service = GraphQLService()
results = service.alerts.query.alerts_service_search(SearchRequestInput(
    cql_query="FROM alert WHERE severity >= 0.6 AND status = 'OPEN' EARLIEST=-1d",
    limit=10,
    offset=0,
))
print(results)

IDによる検出の取得🔗

以下のクエリを使用して、IDで検出を取得できます。

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

service = GraphQLService()
results = service.alerts.query.alerts_service_retrieve_alerts_by_id(GetByIDRequestInput(i_ds=[
    "alert://priv:stolen-user-credentials:11063:1630602244467:79015c9a-8d22-5c4e-a199-58afc0599aa5"
]))
print(results)

IDによる検出の解決🔗

以下を使用して、IDのリストによって検出を解決します。これは、1つ以上の検出ID、解決理由、および検出にラベル付けする解決ステータスを受け付けます。

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.alerts.types import UpdateResolutionRequestInput, ResolutionStatus, CallerInformation

service = GraphQLService()
results = service.alerts.mutation.alerts_service_update_resolution_info(UpdateResolutionRequestInput(
    alert_ids=[
        "alert://priv:event-filter:11063:1645647767642:d9ea3f17-5b8b-4edc-93e1-29539b7c6b26",
        "alert://priv:event-filter:11063:1645647041875:37ee1876-8458-4897-8965-f0c7b9afc85e"
    ],
    reason="This is why I am resolving.",
    resolution_status=ResolutionStatus.FALSE_POSITIVE,
    caller=CallerInformation.ALERTS_V2,
))
print(results)

検出データの集計🔗

以下のクエリを使用して、重大度ごとの検出集計数を取得します。

注意

これは非推奨となった alertsBySeverity クエリと類似しています。

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

service = GraphQLService()
with service(output="status reason alerts { group_by { key value } total_results }"):
    results = service.alerts.query.alerts_service_search(SearchRequestInput(
        cql_query="FROM alert WHERE severity >= 0.6 AND status = 'OPEN' EARLIEST=-1d | aggregate count by severity | head 10",
        limit=1,
        offset=0,
    ))
print(results)

検出のページネーション🔗

ページネーションには主に2つの方法があります。1つ目は最大10,000件の検出を取得する方法です。もう1つは最大1,000,000件の検出を取得する方法です。

10,000件未満の検出🔗

limit および offset フィールドを使用して検索リクエストをページネートします。

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

service = GraphQLService()
results_page_1 = service.alerts.query.alerts_service_search(SearchRequestInput(
    cql_query="FROM alert EARLIEST=-24h",
    limit=500,
    offset=0,
))
print(results_page_1)

results_page_2 = service.alerts.query.alerts_service_search(SearchRequestInput(
    cql_query="FROM alert EARLIEST=-24h",
    limit=500,
    offset=500,
))
print(results_page_2)

10,000件を超える検出🔗

もう1つのページネーション方法は、検索リクエストで返される search_id を使用することです。これにより、10,000件を超える結果を取得できます。

まず、取得したい合計結果数を limit に設定して検索リクエストを送信します。以下の例では、合計50,000件の結果をリクエストしています。

検索結果が10,000件を超える場合、最初の10,000件の結果とともに、後続ページの取得に使用できる search_id が返されます。後続ページを取得するには、同じ検索リクエストを送信しますが、search_id パラメータを追加し、limitおよびoffsetパラメータを削除します。search_id が返されなくなった時点で、結果セットの末尾に到達したことになります。

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

service = GraphQLService()
query = "FROM alert WHERE severity >= 0.6 AND status = 'OPEN' EARLIEST=-3d"
results = service.alerts.query.alerts_service_search(SearchRequestInput(
    cql_query=query,
    limit=50000,
))

responses = [results]
search_id = results.search_id
total_parts = results.alerts.total_parts

while search_id:
    results = None
    try:
        results = service.alerts.query.alerts_service_search(
            SearchRequestInput(
                search_id=search_id,
                cql_query=query,
            )
        )
        search_id = None
    except Exception as exc:
        if "not found" in str(exc):
            break
        raise exc

    if (
        isinstance(results, AlertsResponse)
        and results.alerts is not None
    ):
        responses.append(results)

print(sum(
    len(response.alerts.list)
    for response in poll_responses
))

その他🔗

利用可能な検出GraphQLオブジェクトの一覧については、Alerts GraphQL API ドキュメントを参照してください。

資産🔗

すべての資産を表示🔗

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.assets.types import AssetsOrderByInput, AssetStateFilter

service = GraphQLService()
results = service.assets.query.all_assets(
    offset=0,
    limit=3,
    order_by=AssetsOrderByInput.HOSTNAME,
    filter_asset_state=AssetStateFilter.ALL
)
print(results)

ページネーション🔗

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.assets.types import AssetsOrderByInput, AssetStateFilter

service = GraphQLService()

offset = 0
limit = 500

results = service.assets.query.all_assets(
    offset=offset,
    limit=limit,
    order_by=AssetsOrderByInput.HOSTNAME,
    filter_asset_state=AssetStateFilter.ALL
)

assets = results.assets

while len(results.assets) != limit:
    offset += limit
    results = service.assets.query.all_assets(
        offset=offset,
        limit=limit,
        order_by=AssetsOrderByInput.HOSTNAME,
        filter_asset_state=AssetStateFilter.ALL
    )
    assets.extend(results.assets)

資産の削除🔗

from taegis_sdk_python import GraphQLService

service = GraphQLService()
results = service.assets.mutation.delete_assets([
    "asset-uuid-here"
])
print(results)

資産数の取得🔗

from taegis_sdk_python import GraphQLService

service = GraphQLService()
results = service.assets.query.asset_count_group_by_endpoint_type()
print(results)

ホストIDによるクエリ🔗

from taegis_sdk_python import GraphQLService

service = GraphQLService()
results = service.assets.query.assets_by_host_ids([
    "host/sensor-id-here"
])
print(results)

監査🔗

監査のクエリ🔗

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.audits.types import AllAuditsInput

service = GraphQLService()
results = service.audits.query.all_audits(AllAuditsInput(
    offset=0,
    limit=1,
))
print(results)

監査の検索🔗

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.audits.types import AuditSearchInput

service = GraphQLService()
results = service.audits.query.search_audits(AuditSearchInput(
    offset=0,
    limit=1,
    email="name@your-domain.com",
    application="alerts"
))
print(results)

コレクター🔗

コレクターの作成🔗

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.collector.types import ClusterInput, NetworkInput

service = GraphQLService()
results = service.collector.mutation.create_cluster(ClusterInput(
    name="sample-collector",
    description="a collector created from a script!",
    network: NetworkInput(dhcp=True, hostname="sample-collector-host")
))
print(results)

コレクターのクエリ🔗

from taegis_sdk_python import GraphQLService, build_output_string
from taegis_sdk_python.services.collector.types import Cluster

service = GraphQLService()

with service(
    # not all users have permission to endpoint credentials
    # we remove the field using the function so that updates
    # to the schema don't interfere
    output=build_output_string(Cluster).replace(" credentials ", " ")
):
    results = service.collector.query.get_all_clusters(role="collector")
print(results)

注意

一部のユーザーは、endpoints セクションから credentials を削除する必要がある場合があります。

ケース🔗

ケースのクエリ🔗

from taegis_sdk_python import GraphQLService

service = GraphQLService()
results = service.investigations.query.investigations_search(
    page=1,
    per_page=3,
    query="""
    type in ('Security Investigation')
    """
)
print(results)

ケースの作成🔗

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.investigations.types import InvestigationInput

service = GraphQLService()
results = service.investigations.mutation.create_investigation(InvestigationInput(
    description="Testing",
    status="Open",
    contributors=[],
    keyfindings="Test Keyfindings",
    tags=[],
    genesis_alerts=[],
    genesis_events=[],
    alerts=[],
    events=[],
    auth_credentials=[],
))
print(results)

脅威インテリジェンス🔗

利用可能な脅威インテリジェンスインジケーターリストのダウンロード🔗

以下のリクエストを使用して、ダウンロード可能な脅威インテリジェンスインジケーターリストの一覧を取得します。このリストには、各リストへのリンクが含まれており、認証はURLに組み込まれているため、直接利用できます。

from taegis_sdk_python import GraphQLService
import requests
from pathlib import Path
from pprint import pprint as pp

service = GraphQLService()

response = requests.get(
    f"{service.core.sync_url}/intel-requester/ti-list/latest",
    headers=service.headers,
)
data = response.json()
len(data)

for ti in data:
    with requests.get(
        ti.get("link"),
        allow_redirects=True
    ) as r:
        file_path = Path(ti.get("name"))
        file_path.parent.mkdir(parents=True, exist_ok=True)
        with file_path.open("wb") as f:
            for chunk in r.iter_content(chunk_size=8192):
                f.write(chunk)

タイプ別Watchlistインジケーターのダウンロード🔗

以下のCTU脅威インテリジェンスインジケーターフィードは高信頼度リストとして特定されており、threat watchlist TI APIエンドポイントを使用して取得できます。

CTU Botnet Indicators IP List - MSS
CTU Threat Group Indicators IP List - MSS
Third Party Threat Group Indicators IP List - MSS
CTU Botnet Indicators Domain List - MSS
CTU Threat Group Indicators Domain List - MSS
Third Party Threat Group Indicators Domain List - MSS

MSSリストは、自動ブロックや検出に適した高精度インジケーターを含む脅威アクティビティに関連しています。以下のスクリプトを実行してドメインWatchlistを取得してください。

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.threat.types import ThreatParentType

service = GraphQLService()
results = service.threat.query.threat_watchlist(ThreatParentType.DOMAIN)
print(results)

インジケーターによる脅威インテリジェンス🔗

脅威インテリジェンスAPIを使用して、CTU脅威インテリジェンスレポート、脅威グループ、または関連するマルウェアファミリーを、それぞれのインジケーターに対して取得することが可能です（インジケーターがデータセット内の前述の脅威オブジェクトと関係している場合）。

from taegis_sdk_python import GraphQLService

service = GraphQLService()
results = service.threat.query.threat_indicator_intelligence("vitl.tk")
print(results)

ユーザー🔗

テナントへのユーザー招待🔗

パート1: 招待要件🔗

テナントにユーザーを招待するには、主に4つの値が必要です。

access_token: API認証の手順に従って取得した XDR アクセストークン。

tenant_id: このユーザーを招待するテナントのID。

注意

招待リクエストに使用する access_token には、対象テナント（tenant_id）内でユーザーを招待する権限が必要です。

email_address: テナントに招待したいユーザーのメールアドレス。

role_id: 招待するユーザーに割り当てたいロールのID。例：テナント管理者（ba0fdcbd-e87d-4bdd-ae7d-ca6118b25068）またはテナントアナリスト（a4903f9f-465b-478f-a24e-82fa2e129d2e）。

パート2: 招待リクエスト🔗

ロールID:

テナントアナリスト—a4903f9f-465b-478f-a24e-82fa2e129d2e
テナント管理者—ba0fdcbd-e87d-4bdd-ae7d-ca6118b25068
テナント監査役—ace1cae4-59fd-4fd1-9500-40077dc529a7
テナント対応者—a72dace7-4536-4dbc-947d-015a8eb65f4d

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.users.types import TDRUserInviteInput

service = GraphQLService()
results = service.users.mutation.invite_tdruser(TDRUserInviteInput(
    email="invitee_email_address",
    role_id="invitee_role_id"
))
print(results)

ユーザーの取得🔗

パート1: 取得要件🔗

ユーザーの詳細を取得するには、以下の3つの値が必要です。

access_token: API認証の手順に従って取得した XDR アクセストークン。

user_id 取得したいユーザーの一意のID。

tenant_id: 対象ユーザーが所属するテナントのID。

注意

取得リクエストに使用する access_token には、対象テナント（tenant_id）内でユーザーを読み取る権限が必要です。

パート2: 取得リクエスト🔗

既存ユーザーの詳細取得は、users APIの tdruser クエリを呼び出すgraphqlリクエストで行います。

from taegis_sdk_python import GraphQLService

service = GraphQLService()
results = service.users.query.tdruser('user_id')
print(results)

ユーザーの更新🔗

パート1: ユーザー更新要件🔗

ユーザーの詳細を更新するには、以下の3つの値が必要です。

access_token: API認証の手順に従って取得した XDR アクセストークン。

user_id 更新したい（対象）ユーザーの一意のID。

tenant_id: 対象ユーザーが所属するテナントのID。

パート2: ユーザー更新リクエスト🔗

ユーザーの更新は、users APIの updateTDRUser ミューテーションを呼び出し、対象ユーザーの更新したいフィールドの patch を含めたgraphqlリクエストで行います。

注意

更新リクエストに使用する access_token には、対象テナント（tenant_id）内でユーザーを更新する権限が必要です。

ユーザーの詳細を更新するために patch 内で設定可能な変数がいくつかあります。現在パッチ可能なフィールドは以下の通りです。

given_name
family_name
phone_number
secondary_phone_number

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.users.types import TDRUserUpdateInput

service = GraphQLService()
results = service.users.mutation.update_tdruser('user_id', TDRUserUpdateInput(
    phone_number="+10000000000",
    secondary_phone_number="+000000000000"
))
print(results)

ユーザーのアクセス権の取り消し🔗

パート1: 取り消し要件🔗

ユーザーのアクセス権の取り消しは、ユーザーのロール割り当てを削除することで実施します。ユーザーがテナント内でロール割り当てが0になると、そのテナントへのアクセス権がなくなります。すべての テナントでロール割り当てがない場合、そのアカウントは deactivated とマークされ、ユーザーは XDR へのログインができなくなります。

ユーザーのロール割り当てを取り消すには、以下の値が必要です。

access_token: API認証の手順に従って取得した XDR アクセストークン。

user_id: ロール割り当てを取り消したい（対象）ユーザーの一意のID。

tenant_id: 対象ユーザーが所属し、ロールを取り消すテナントのID。

role_id: 取り消すロールのID。

パート2: ロール割り当て削除リクエスト🔗

ロール割り当ての削除は、users APIの removeTDRUserRoles ミューテーションを呼び出すgraphqlリクエストで行います。

注意

ロール削除リクエストに使用する access_token には、対象テナント（tenant_id）内でユーザーを更新する権限が必要です。

ロールID:

テナントアナリスト—a4903f9f-465b-478f-a24e-82fa2e129d2e
テナント管理者—ba0fdcbd-e87d-4bdd-ae7d-ca6118b25068
テナント監査役—ace1cae4-59fd-4fd1-9500-40077dc529a7
テナント対応者—a72dace7-4536-4dbc-947d-015a8eb65f4d

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.users.types import TDRUserUpdateInput

service = GraphQLService()
results = service.users.mutation.remove_tdruser_roles('user_id', roles=["role_id"])
print(results)

ユーザーの検索🔗

パート1: 検索要件🔗

ユーザーを検索するには、以下の2つの値が必要です。

access_token: API認証の手順に従って取得した XDR アクセストークン。

tenant_id: ユーザーを検索するテナントのID。

注意

取得リクエストに使用する access_token には、対象テナント（tenant_id）内でユーザーを読み取る権限が必要です。

パート2: 検索リクエスト🔗

ユーザー検索は、users APIの tdrUsersSearch クエリを呼び出すgraphqlリクエストで行います。

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.users.types import TDRUserUpdateInput

service = GraphQLService()
results = service.users.query.tdr_users_search(TDRUsersSearchInput(
    tenant_status="!Deactivated"
))
print(results)

事前認証済みユーザーの登録🔗

新しいUsers APIが追加され、パートナーが標準の招待プロセスや登録用メール通知を経ずに、自分のテナントに新しいユーザーを追加できるようになりました。

パート1: ユーザー登録要件🔗

ユーザーが割り当てられるパートナーまたは子テナントで有効なSSO接続が必要です。
ユーザーのメールドメインはSSO接続と一致している必要があります。
パートナーおよびそのテナントでのみ利用可能で、Taegis テナントでは利用できません。
新しいテナント管理者ユーザーは標準の招待プロセスを経る必要があり、このAPIでは動作しません。

テナントにユーザーを登録するには、主に4つの値が必要です。

access_token: API認証の手順に従って取得した XDR アクセストークン。

tenant_id: このユーザーを登録するテナントのID。

注意

登録リクエストに使用する access_token には、対象テナント（tenant_id）内で createPreRegisteredUser ユーザーを作成する権限が必要です。TenantAdminロールにはこの権限があります。

email_address: テナントに登録したいユーザーのメールアドレス。

role_id: 登録するユーザーに割り当てたいロールのID。例：テナント監査役（ace1cae4-59fd-4fd1-9500-40077dc529a7）またはテナントアナリスト（a4903f9f-465b-478f-a24e-82fa2e129d2e）。

パート2: ユーザー登録リクエスト🔗

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.users.types import PartnerRegistrationInput

service = GraphQLService()
results = service.users.mutation.register_partner_user(PartnerRegistrationInput(
    email="user_email_address",
    role_id="role_id",
    role_expires_at="role_expiration_time",
    language="user_preferred_language",
    given_name="user_first_name",
    family_name="user_last_name",
    phone_number="user_phone_number",
    timezone="user_timezone",
))
print(results)

テナント🔗

テナントの取得🔗

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import TenantsQuery

service = GraphQLService()
results = service.tenants.query.tenants(TenantsQuery(
    max_results=10
))
print(results)

テナントのページネーション🔗

ページ番号🔗

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import TenantsQuery

service = GraphQLService()
results = service.tenants.query.tenants(TenantsQuery(
    max_results=10
))
tenants = results.results

for page in range(2, 4 + 1):
    results = service.tenants.query.tenants(TenantsQuery(
        max_results=10,
        page_num=page
    ))
    tenants.extend(results.results)

print(len(tenants))

カーソル🔗

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import TenantsQuery

service = GraphQLService()
results = service.tenants.query.tenants(TenantsQuery(
    max_results=10
))
tenants = results.results

for _ in range(3):
    results = service.tenants.query.tenants(TenantsQuery(
        max_results=10,
        cursor_pos=results.cursor_pos
    ))
    tenants.extend(results.results)

print(len(tenants))

テナントのフィルタ🔗

フィルターは組み合わせて使用できます。以下のいずれか（またはすべて）のフィルターを使用できます。

name
ids
forHierarchies
environmentFilter
labelFilter
withService
withServices
withPartnerSubscription
withPartnerSubscriptions
partnership
createdTimeFilter
modifiedTimeFilter
isPartner
withSupport

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import (
    TenantsQuery,
    EnvironmentFilter,
    LabelFilter,
    TimeFilter,
)

service = GraphQLService()
results = service.tenants.query.tenants(
    TenantsQuery(
        max_results=10,
        ids=["xxxxx"],
        name="%my name%",
        for_hierachies=["id"],
        environment_filter=EnvironmentFilter(name="EU", enabled=True),
        label_filter=LabelFilter(label_name="testing"),
        with_partner_subscription="%",
        with_partner_subscriptions=["%"],
        created_time_filter=TimeFilter(
            start_time="2019-07-04T15:00:22", end_time="2019-07-06T15:00:22Z"
        ),
    )
)

print(results)

テナントのソート🔗

結果は以下のいずれかでソートできます。

Id
Name
CreatedAt
UpdatedAt

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import (
    TenantsQuery,
    TenantOrderField,
    OrderDir,
)

service = GraphQLService()
results = service.tenants.query.tenants(
    TenantsQuery(
        max_results=10,
        created_time_filter=TimeFilter(
            start_time="2019-07-04T15:00:22", end_time="2019-07-06T15:00:22Z"
        ),
        order_by=TenantOrderField.CREATED_AT,
        order_dir=OrderDir.DESC,
    )
)

print(results)

テナントの作成🔗

mutation createTenant(TenantCreateInput!) は、いくつかの制限付きでパートナー上にテナントを作成します。

アクセス権のないパートナー（親テナント）上に子テナントを作成することはできません。
新しいパートナーテナントを作成することはできません（Taegis ユーザーで適切なロールを持っている場合を除く）。

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import TenantCreateInput, InputTenantLabel, TenantEnvironment

service = GraphQLService()
results = service.tenants.mutation.create_tenant(TenantCreateInput(
    name="New Tenant Name",
    partner_tenant_id="xxxxx",
    labels=[
        InputTenantLabel(
            name="partner_only_label_name",
            value="label_value",
            owner_partner_tenant_id="xxxxx"
        ),
    ],
    environments=[
        TenantEnvironment.EU,
        TenantEnvironment.PILOT,
    ]
))
print(results)

注意事項🔗

partnerTenantID は親のパートナーテナントIDです。名前の通り、そのテナント（TenantAdmin として）へのアクセス権が必要です。
labels の対象を owner_parent_tenant_id で制限できます。上記の例では、partner_only_label_name はテナント xxxxx にアクセスできるトークンにのみ表示されます。現時点ではラベルの所有権は親テナントのみに設定できます。
environments を使用して、この子テナントを有効化したい環境のリストを設定できます。この例では新しいテナントは EU および pilot で有効化されています。

テナント名の変更🔗

テナント名を変更するには、mutation updateTenant(TenantUpdateInput) を使用します。

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import TenantUpdateInput

service = GraphQLService()
results = service.tenants.mutation.update_tenant(
    tenant_id="xxxxx",
    update_input=TenantUpdateInput(
        name="Updated Tenant Name",
    ),
)
print(results)

テナント環境の管理🔗

テナント作成時には、少なくとも1つの環境で有効化されます。環境を変更するには、mutation updateTenant(TenantUpdateInput) を使用します。

ヒント

1回のリクエストで複数の環境を有効化/無効化できます。テナントは1つ以上の環境で有効化されていればアクティブとみなされます。

テナントの無効化🔗

テナントを無効化するには、すべての環境で無効化するか、単に "disable" : true フィールドを設定します。どちらの方法でも同じ結果となります。

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import TenantUpdateInput, TenantEnvironmentUpdateInput

service = GraphQLService()
results = service.tenants.mutation.update_tenant(
    tenant_id="xxxxx",
    update_input=TenantUpdateInput(
        disable=True
    ),
)
print(results)

テナント有効期限の管理🔗

有効期限が設定されたテナントは、60日後に自動的に無効化されます。有効期限は mutation updateTenant(TenantUpdateInput) で変更できます。

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import TenantUpdateInput, TenantEnvironmentUpdateInput

service = GraphQLService()
results = service.tenants.mutation.update_tenant(
    tenant_id="xxxxx",
    update_input=TenantUpdateInput(
        expires_at="2023-12-31T00:00:00Z"
    ),
)
print(results)

有効期限のクリア🔗

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import TenantUpdateInput, TenantEnvironmentUpdateInput

service = GraphQLService()
results = service.tenants.mutation.update_tenant(
    tenant_id="xxxxx",
    update_input=TenantUpdateInput(
        clear_expiration=True,
    ),
)
print(results)

テナントラベルの管理🔗

以下のミューテーションを使用して、テナント内でラベルの作成、更新、削除が可能です。

createTenantLabel(label_id ID!, label_input ID!: InputTenantLabel!): TenantLabel!、InputTenantLabel.owner_parent_tenant_id でラベルの対象を設定できます。
updateTenantLabel(label_id ID!, tenant_id ID!, label_input: InputTenantLabel!): TenantLabel!
deleteTenantLabel(label_id: ID!, tenant_id: ID!): TenantLabel!

注意

一部のラベルは制限されており、変更や削除ができません。Tenants APIは、制限付きラベルの変更を試みた場合に通知します。

テナントラベルの作成🔗

所有するテナントに新しいラベルを作成するには：

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import InputTenantLabel

service = GraphQLService()
results = service.tenants.mutation.create_tenant_label(
    tenant_id="xxxxx",
    label_input=InputTenantLabel(
        name="test",
        value="value",
    ),
)
print(results)

パートナーサブスクリプションの管理🔗

以下のミューテーションを使用して、利用可能なパートナーサブスクリプションおよび子テナントへのサブスクリプション割り当ての両方を管理できます。

createSubscription(input: NewSubscription!): Service! 子テナントに割り当て可能なサブスクリプションを作成します。
updateSubscription(input: SubscriptionUpdate!): Service! アクセス権のあるサブスクリプションの名前を変更します。
deleteSubscription(id: ID!): Service! 割り当てられていないサブスクリプションを削除します。すでに割り当てられている場合はエラーが返されます。
assignSubscription(tenant_id: ID!, subscription_id: ID!): Tenant! パートナー子テナントにサブスクリプションを設定します。
unassignSubscription(tenant_id: ID!, subscription_id: ID!): Tenant! パートナー子テナントからサブスクリプションを削除します。

from taegis_sdk_python import GraphQLService

service = GraphQLService()
results = service.tenants.mutation.assign_subscription(
    tenant_id="xxxxx",
    subscription_id="1cb04358-0e00-4ffb-abc8-14ccbc7b42b0"
)
print(results)

注意事項🔗

subscription_id はサブスクリプション作成時に返されます。返された id 値はサブスクリプション割り当てIDであり、サブスクリプションの割り当て解除に使用できます。

サポートの許可🔗

tenants-api を使用して、以下のミューテーションでパートナー子テナントのサポートを有効化または無効化できます。

enableTenantSupport(tenantID: ID!): Tenant!
disableTenantSupport(tenantID: ID!): Tenant!

from taegis_sdk_python import GraphQLService

service = GraphQLService()
results = service.tenants.mutation.enable_tenant_support(
    tenant_id="xxxxx",
)
print(results)

シングルサインオン接続🔗

Taegis プラットフォームへの認証のためのサードパーティIDプロバイダーの構成は、Tenants APIで行います。サポートされているのはSAMLプロバイダーのみであり、このガイドではプロバイダーの構成に必要な手順を説明します。このSAML通信のシナリオでは、Taegis プラットフォームがサービスプロバイダーとなります。

SSO接続の作成🔗

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import NewSSOConnectionInput, SSOConnectionType

service = GraphQLService()
results = service.tenants.mutation.create_sso_connection(
    NewSSOConnectionInput(
        name="Connection Name",
        type=SSOConnectionType.SAML,
        domains=["email_domain"],
        testers=["tester@email_domain"]
    )
)
print(results)

注意事項🔗

入力
- name — 作成するSSO接続の名前。必須
- type — 接続タイプ、saml でなければなりません。必須
- domains — この接続で認証を行うメールドメインのリスト。必須
- testers — この接続のアーリーアダプターとなるテスターのリスト。任意
出力
- id — 接続の内部ID。
- type — 作成された接続のタイプ。saml である必要があります。
- createdAt — 接続が作成された時刻。
- updatedAt — 最終更新時刻。
- externalName — 接続の外部名。自動生成されます。
- externalID — 接続の外部ID。自動生成されます。
- domains — この接続で認証を行う設定済みメールドメインのリスト。
- testers — この接続をテストしているユーザーのリスト。
- status — この接続のステータス。この段階では Draft である必要があります。他の可能な値は Testing、Enabled、Disabled です。
- ssoConnectionParameters
  - postBackURL — IDプロバイダーの構成に使用します。これはIDプロバイダーからSAMLアサーションを受け取るコールバックであり、assertion consumer service とも呼ばれます。
  - entityID — IDプロバイダーに対して Taegis 接続を識別します。

postBackURL および entityID は、次のステップに進む前に通常SAML IDプロバイダー側で構成されます。

SSO構成の取得🔗

getSSOConnectionConfig クエリは、SAMLサービスプロバイダー（Taegis）に必要な情報を取得します。このステップは通常、設定内容が正しいことを事前確認するために行います。

from taegis_sdk_python import GraphQLService

service = GraphQLService()
results = service.tenants.query.get_sso_connection_config(
    metadata_url="metadata_url",
)
print(results)

注意事項🔗

入力🔗

metadataURL はIDプロバイダーのメタデータURLを指定します。これは任意であり、cert とは排他的です。
cert はIDプロバイダーの署名証明書です。他のデータが利用可能なため必須ではなく、利便性のために提供されています。これは任意であり、metadataURL とは排他的です。

出力🔗

expiresAt — 署名証明書の有効期限。
notBefore — 署名証明書の有効開始日。
issuer — 署名証明書の発行者。
subject — 署名証明書の発行対象。
ssoConnectionConfiguration
- samlConnectionConfiguration は metadataURL が指定された場合に返されます。
  - signInEndpoint は、Taegis がSSOユーザーを認証するために呼び出すエンドポイントです。
  - signingCert は、メタデータURLから抽出されたIDプロバイダーの署名証明書です。

初期SSO接続構成の完了🔗

初期接続構成を完了するには、IDプロバイダーのメタデータURL、または署名証明書とサインインエンドポイントの組み合わせが必要です。正常に完了すると、接続は Testing ステータスに移行します。

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import UpdateSSOConnectionInput, ConnectionConfiguration, SAMLSSOConfiguration

service = GraphQLService()
results = service.tenants.mutation.update_sso_connection(
    UpdateSSOConnectionInput(
        id="connection_id",
        connection_configuration=ConnectionConfiguration(
            saml_configuration=SAMLSSOConfiguration(
                metadata_url="metadata_url",
                # or #
                signing_cert_name="certificate_name",
                signing_cert="certificate",
                sign_in_endpoint="sign_in_endpoint"
            )
        )
    )
)
print(results)

注意事項🔗

入力🔗

id — 接続の内部ID。必須
samlConfiguration
- metadataURL — IDプロバイダーの構成をダウンロードできるURL。任意。指定した場合、signingCert 入力は無視されます。
- signingCert — IDプロバイダーの署名証明書。任意。指定し、metadataURL がない場合は signInEndpoint も指定する必要があります。
- signInEndpoint — SSOユーザーの認証に使用するURL。任意ですが、signingCert を使用する場合は必須です。
- signingCertName — 署名証明書のファイル名。過去に使用した証明書を識別するために使用されますが、ユーザーのローカルファイルシステムから証明書を取得するためには使用されません。任意

出力🔗

id — 接続の内部ID。
name — 接続名。
externalName — Taegis がSSO認証を処理するために使用する外部名。
externalID — Taegis がSSO認証を処理するために使用する外部ID。
createdAt — 接続が作成された時刻。
updatedAt — 最終更新時刻。
type — SSO接続のタイプ。現在サポートされているのはSAMLのみです。
status — 接続ステータス。リクエストが正常に完了すると Testing に移行します。
domains — この接続で認証を行うメールドメイン。
testers — テスターのリスト。
cerName — 更新リクエストで指定された場合、証明書ファイル名。
notBefore — 署名証明書の有効開始時刻。
expiresAt — 署名証明書の有効期限。
issuer — 署名証明書の発行者。
subject — 署名証明書の発行対象。
ssoConnectionParameters — サービスプロバイダー（Taegis）のSAML属性。
- postBackURL — IDプロバイダーからSAMLアサーションレスポンスを受け取るエンドポイント。
- entityID — Taegis SAMLエンティティの識別子。
- metadataURL — IDプロバイダーが将来的にTaegisのSAML構成をダウンロードするために使用できるURL（更新が必要な場合）。
ssoConnectionIDPConfig — IDプロバイダーの構成。
- samlConnectionConfiguration
  - signInEndpoint — Taegis がSSOユーザーを認証するために使用するエンドポイント。
  - signingCert — IDプロバイダーの署名証明書。

SSO接続の更新🔗

テストが完了したら、SSO接続を Enabled ステータスにして、登録済みメールドメインで利用できるようにする必要があります。他の属性も調整が必要な場合があります。たとえば、設定済み証明書の有効期限が近づいた場合は新しい署名証明書が必要です。

from taegis_sdk_python import GraphQLService
from taegis_sdk_python.services.tenants.types import UpdateSSOConnectionInput, SSOConnectionStatus

service = GraphQLService()
results = service.tenants.mutation.update_sso_connection(
    UpdateSSOConnectionInput(
        id="connection_id",
        status=SSOConnectionStatus.ENABLED
    )
)
print(results)

注意事項🔗

入力🔗

id — 接続の内部ID。必須
status — 接続のステータスを更新します。有効な値は Enabled、Disabled、Testing です。任意
addTesters — 新たに追加するテスターの文字列配列。任意
removeTesters — 削除するテスターの文字列配列。任意
addDomains — 追加するメールドメインの文字列配列。任意
removeDomains — 削除するメールドメインの文字列配列。任意
samlConfiguration
- metadataURL — IDプロバイダーの構成をダウンロードできるURL。指定した場合、signingCert 入力は無視されます。任意
- signingCert — IDプロバイダーの署名証明書。指定し、metadataURL がない場合は signInEndpoint も指定する必要があります。任意
- signInEndpoint — SSOユーザーの認証に使用するURL。任意ですが、signingCert を使用する場合は必須です。
- signingCertName — 署名証明書のファイル名。過去に使用した証明書を識別するために使用され、ユーザーのローカルファイルシステムから証明書を取得するためには使用されません。任意

出力🔗

id — 接続の内部ID。
name — 接続名。
externalName — Taegis がSSO認証を処理するために使用する外部名。
externalID — Taegis がSSO認証を処理するために使用する外部ID。
createdAt — 接続が作成された時刻。
updatedAt — 最終更新時刻。
type — SSO接続のタイプ。現在サポートされているのはSAMLのみです。
status — 接続ステータス。このリクエストが正常に完了すると Testing に移行します。
domains — この接続で認証を行うメールドメイン。
testers — テスターのリスト。
cerName — 更新リクエストで指定された場合、証明書ファイル名。
notBefore — 署名証明書の有効開始時刻。
expiresAt — 署名証明書の有効期限。
issuer — 署名証明書の発行者。
subject — 署名証明書の発行対象。
ssoConnectionParameters — サービスプロバイダー（Taegis）のSAML属性。
- postBackURL — IDプロバイダーからSAMLアサーションレスポンスを受け取るエンドポイント。
- entityID — Taegis SAMLエンティティの識別子。
- metadataURL — IDプロバイダーが将来的にTaegisのSAML構成をダウンロードするために使用できるURL（更新が必要な場合）。
ssoConnectionIDPConfig — IDプロバイダーの構成。
- samlConnectionConfiguration
  - signInEndpoint — Taegis がSSOユーザーを認証するために使用するエンドポイント。
  - signingCert — IDプロバイダーの署名証明書。

SSO接続の削除🔗

from taegis_sdk_python import GraphQLService

service = GraphQLService()
results = service.tenants.mutation.delete_sso_connection(
    connection_id="connection_id"
)
print(results)

注意事項🔗

入力🔗

connectionID — 接続の内部ID。必須

出力🔗

id — 接続の内部ID。
name — 接続名。
type — SSO接続のタイプ。現在サポートされているのはSAMLのみです。
status — 接続ステータス。リクエストが正常に完了すると Testing に移行します。
externalName — Taegis がSSO認証を処理するために使用する外部名。
externalID — Taegis がSSO認証を処理するために使用する外部ID。
domains — この接続で認証を行うメールドメイン。
testers — テスターのリスト。

対策🔗

以下のエンドポイントは、XDR Countermeasures API を使用してCTU情報を取得するためにアクセスできます。

/ — ルールセットを返します。例: https://api.ctpx.secureworks.com/intel-requester/
/ti-list — CTUによってリリースされたすべての脅威インジケーターリストのバージョンを返します。例: https://api.ctpx.secureworks.com/intel-requester/ti-list
/ti-list/latest — CTUによってリリースされた最新バージョンの脅威インジケーターリストのみを返します。例: https://api.ctpx.secureworks.com/intel-requester/ti-list/latest

デフォルトでは、これらのエンドポイントからの結果はURLエスケープされません。結果をWebページに表示する必要がある場合は、クエリパラメータ ?html=true を使用してください。

脅威インジケーターリストエンドポイントは、デフォルトでフィルタ済みリスト（MSS）を返します。すべてのリストまたは生リストのみが必要な場合は、フィルタクエリパラメータを使用してください。*

?filter=all => すべてのリスト
?filter=raw => 生リスト

*クエリパラメータを省略するか、?filter=mss でmssリストを取得します。

対策リストの取得🔗

from taegis_sdk_python import GraphQLService
import requests
import tarfile

service = GraphQLService()

response = requests.get(
    f"{service.core.sync_url}/intel-requester/",
    headers=service.headers,
)

data = response.json()
print(data)

for cm in data:
    name = cm.get("name").split("/")[1]
    with requests.get(
        cm.get("link"),
        allow_redirects=True
    ) as r:
        with open(name, "wb") as f:
            for chunk in r.iter_content(chunk_size=8192):
                f.write(chunk)

Taegis SDK for Python 使用例🔗

検出🔗

検出の検索🔗

IDによる検出の取得🔗

IDによる検出の解決🔗

検出データの集計🔗

検出のページネーション🔗

10,000件未満の検出🔗

10,000件を超える検出🔗

その他🔗

資産🔗

すべての資産を表示🔗

ページネーション🔗

資産の削除🔗

資産数の取得🔗

ホストIDによるクエリ🔗

監査🔗

監査のクエリ🔗

監査の検索🔗

コレクター🔗

コレクターの作成🔗

コレクターのクエリ🔗

ケース🔗

ケースのクエリ🔗

ケースの作成🔗

脅威インテリジェンス🔗

利用可能な脅威インテリジェンスインジケーターリストのダウンロード🔗

タイプ別Watchlistインジケーターのダウンロード🔗

最新の脅威インテリジェンス公開情報のダウンロード🔗

インジケーターによる脅威インテリジェンス🔗

ユーザー🔗

テナントへのユーザー招待🔗

パート1: 招待要件🔗

パート2: 招待リクエスト🔗

ユーザーの取得🔗

パート1: 取得要件🔗

パート2: 取得リクエスト🔗

ユーザーの更新🔗

パート1: ユーザー更新要件🔗

パート2: ユーザー更新リクエスト🔗

ユーザーのアクセス権の取り消し🔗

パート1: 取り消し要件🔗

パート2: ロール割り当て削除リクエスト🔗

ユーザーの検索🔗

パート1: 検索要件🔗

パート2: 検索リクエスト🔗

事前認証済みユーザーの登録🔗

パート1: ユーザー登録要件🔗

パート2: ユーザー登録リクエスト🔗

テナント🔗

テナントの取得🔗

テナントのページネーション🔗

ページ番号🔗

カーソル🔗

テナントのフィルタ🔗

テナントのソート🔗

テナントの作成🔗

注意事項🔗

テナント名の変更🔗

テナント環境の管理🔗

テナントの無効化🔗

テナント有効期限の管理🔗

有効期限のクリア🔗

テナントラベルの管理🔗

テナントラベルの作成🔗

パートナーサブスクリプションの管理🔗

注意事項🔗

サポートの許可🔗

シングルサインオン接続🔗

SSO接続の作成🔗

注意事項🔗

SSO構成の取得🔗

注意事項🔗

入力🔗

出力🔗

初期SSO接続構成の完了🔗

注意事項🔗

入力🔗

出力🔗

SSO接続の更新🔗