taegis-sdk-python 1.6.16__tar.gz → 1.6.18__tar.gz

{taegis_sdk_python-1.6.16 → taegis_sdk_python-1.6.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taegis-sdk-python
-Version: 1.6.16
+Version: 1.6.18
 Summary: Taegis Python SDK
 Project-URL: Homepage, https://github.com/secureworks/taegis-sdk-python
 Project-URL: Bug Reports, https://github.com/secureworks/taegis-sdk-python/issues

{taegis_sdk_python-1.6.16 → taegis_sdk_python-1.6.18}/taegis_sdk_python/_version.py

@@ -1,3 +1,3 @@
 """Version idenitier."""
 
-__version__ = "1.6.16"
+__version__ = "1.6.18"

taegis_sdk_python-1.6.18/taegis_sdk_python/commons/__init__.py

@@ -0,0 +1,33 @@
+"""Taegis Commons - Imports."""
+
+from taegis_sdk_python.commons._introspection import (
+    introspection_mutation,
+    introspection_query,
+    introspection_subscription,
+)
+from taegis_sdk_python.commons.alerts.search import alerts_search
+from taegis_sdk_python.commons.cases.search import cases_search
+from taegis_sdk_python.commons.events.search import events_search
+from taegis_sdk_python.commons.investigations.search import investigations_search
+from taegis_sdk_python.commons.sharelinks.create import (
+    create_alerts_query_sharelink,
+    create_cases_sharelink,
+    create_events_query_sharelink,
+    create_investigations_sharelink,
+    create_sharelink,
+)
+
+__all__ = [
+    "introspection_query",
+    "introspection_mutation",
+    "introspection_subscription",
+    "alerts_search",
+    "cases_search",
+    "events_search",
+    "investigations_search",
+    "create_sharelink",
+    "create_alerts_query_sharelink",
+    "create_events_query_sharelink",
+    "create_investigations_sharelink",
+    "create_cases_sharelink",
+]

taegis_sdk_python-1.6.18/taegis_sdk_python/commons/_introspection.py

@@ -0,0 +1,122 @@
+"""Taegis Commons - Introspection GraphQL operations."""
+
+from typing import Any, Optional
+
+from graphql import GraphQLSchema
+
+from taegis_sdk_python import (
+    GraphQLService,
+    build_output_string_from_introspection,
+    prepare_input,
+)
+
+
+def introspection_query(
+    service: GraphQLService,
+    endpoint: str,
+    schema: Optional[GraphQLSchema] = None,
+    **kwargs
+) -> Any:
+    """Generate a GraphQL Query operation with output based on server-side introspection.
+
+    Parameters
+    ----------
+    service : GraphQLService
+    endpoint : str
+    schema : Optional[GraphQLSchema], optional
+        If not provided, the latest schema will be retrieved from the GQL endpoint. By default, None.
+        Useful when the schmea is not on the core service, but is on a child service (e.g. EventService) that shares the same GQL endpoint.
+    Returns
+    -------
+    Any
+        Usually a dict or list of dicts, depending on the query.
+    """
+    # retreive the latest schema from the GQL endpoint
+    if schema is None:
+        schema = service.core.schema
+    # parse the correct output fields for the desired query from the schema
+    field = schema.query_type.fields.get(endpoint)
+
+    output = build_output_string_from_introspection(field)
+
+    results = service.core.execute_query(
+        endpoint=endpoint,
+        variables={key: prepare_input(value) for key, value in kwargs.items()},
+        output=output,
+    )
+
+    return results.get(endpoint)
+
+
+def introspection_mutation(
+    service: GraphQLService,
+    endpoint: str,
+    schema: Optional[GraphQLSchema] = None,
+    **kwargs
+) -> Any:
+    """Generate a GraphQL Mutation operation with output based on server-side introspection.
+
+    Parameters
+    ----------
+    service : GraphQLService
+    endpoint : str
+    schema : Optional[GraphQLSchema], optional
+        If not provided, the latest schema will be retrieved from the GQL endpoint. By default, None.
+        Useful when the schmea is not on the core service, but is on a child service (e.g. EventService) that shares the same GQL endpoint.
+    Returns
+    -------
+    Any
+        Usually a dict or list of dicts, depending on the query.
+    """
+    # retreive the latest schema from the GQL endpoint
+    if schema is None:
+        schema = service.core.schema
+    # parse the correct output fields for the desired query from the schema
+    field = schema.mutation_type.fields.get(endpoint)
+
+    output = build_output_string_from_introspection(field)
+
+    results = service.core.execute_query(
+        endpoint=endpoint,
+        variables={key: prepare_input(value) for key, value in kwargs.items()},
+        output=output,
+    )
+
+    return results.get(endpoint)
+
+
+def introspection_subscription(
+    service: GraphQLService,
+    endpoint: str,
+    schema: Optional[GraphQLSchema] = None,
+    **kwargs
+) -> Any:
+    """Generate a GraphQL Subscription operation with output based on server-side introspection.
+
+    Parameters
+    ----------
+    service : GraphQLService
+    endpoint : str
+    schema : Optional[GraphQLSchema], optional
+        If not provided, the latest schema will be retrieved from the GQL endpoint. By default, None.
+        Useful when the schmea is not on the core service, but is on a child service (e.g. EventService) that shares the same GQL endpoint.
+    Returns
+    -------
+    Any
+        Usually a dict or list of dicts, depending on the query.
+    """
+    # retreive the latest schema from the GQL endpoint
+    if schema is None:
+        schema = service.core.schema
+    # parse the correct output fields for the desired query from the schema
+    field = schema.subscription_type.fields.get(endpoint)
+
+    output = build_output_string_from_introspection(field)
+
+    results = service.core.execute_query(
+        endpoint=endpoint,
+        variables={key: prepare_input(value) for key, value in kwargs.items()},
+        output=output,
+    )
+
+    return results.get(endpoint)

{taegis_sdk_python-1.6.16 → taegis_sdk_python-1.6.18}/taegis_sdk_python/services/__init__.py

@@ -53,6 +53,7 @@ from taegis_sdk_python.services.events import EventsService
 from taegis_sdk_python.services.exports import ExportsService
 from taegis_sdk_python.services.fast_ioc import FastIocService
 from taegis_sdk_python.services.file_info import FileInfoService
+from taegis_sdk_python.services.health import HealthService
 from taegis_sdk_python.services.ingest_stats import IngestStatsService
 from taegis_sdk_python.services.investigations import InvestigationsService
 from taegis_sdk_python.services.investigations2 import Investigations2Service
@@ -220,6 +221,7 @@ class GraphQLService:
         self._events = None
         self._exports = None
         self._fast_ioc = None
+        self._health = None
         self._file_info = None
         self._ingest_stats = None
         self._investigations = None
@@ -686,6 +688,13 @@ class GraphQLService:
             self._fast_ioc = FastIocService(self)
         return self._fast_ioc
 
+    @property
+    def health(self):
+        """Health Service Endpoint."""
+        if not self._health:
+            self._health = HealthService(self)
+        return self._health
+
     @property
     def file_info(self):
         """FileInfo Service Endpoint."""

{taegis_sdk_python-1.6.16 → taegis_sdk_python-1.6.18}/taegis_sdk_python/services/alerts/types.py

@@ -35,6 +35,8 @@ class ResolutionStatus(str, Enum):
     NOT_ACTIONABLE = "NOT_ACTIONABLE"
     OTHER = "OTHER"
     SUPPRESSED = "SUPPRESSED"
+    AUTO_CLOSE = "AUTO_CLOSE"
+    DISMISSED = "DISMISSED"
 
 
 class Origin(str, Enum):

{taegis_sdk_python-1.6.16 → taegis_sdk_python-1.6.18}/taegis_sdk_python/services/assets2/types.py

@@ -405,8 +405,26 @@ class TagV2:
         default=None, metadata=config(field_name="updatedAt")
     )
     tag: Optional[str] = field(default=None, metadata=config(field_name="tag"))
-    key: Optional[str] = field(default=None, metadata=config(field_name="key"))
-    value: Optional[str] = field(default=None, metadata=config(field_name="value"))
+    key: Optional[str] = field(
+        default=None,
+        metadata=config(
+            metadata={
+                "deprecated": True,
+                "deprecation_reason": "Use the tag field instead. Key/value separation is inconsistent across endpoint types.",
+            },
+            field_name="key",
+        ),
+    )
+    value: Optional[str] = field(
+        default=None,
+        metadata=config(
+            metadata={
+                "deprecated": True,
+                "deprecation_reason": "Use the tag field instead. Key/value separation is inconsistent across endpoint types.",
+            },
+            field_name="value",
+        ),
+    )
     is_vendor_tag: Optional[bool] = field(
         default=None, metadata=config(field_name="isVendorTag")
     )

{taegis_sdk_python-1.6.16 → taegis_sdk_python-1.6.18}/taegis_sdk_python/services/context_summarizer/__init__.py

@@ -1,8 +1,12 @@
 """ContextSummarizer Service."""
 
 from taegis_sdk_python.service_core import ServiceCore
-from taegis_sdk_python.services.context_summarizer.mutations import TaegisSDKContextSummarizerMutation
-from taegis_sdk_python.services.context_summarizer.queries import TaegisSDKContextSummarizerQuery
+from taegis_sdk_python.services.context_summarizer.mutations import (
+    TaegisSDKContextSummarizerMutation,
+)
+from taegis_sdk_python.services.context_summarizer.queries import (
+    TaegisSDKContextSummarizerQuery,
+)
 from taegis_sdk_python.services.context_summarizer.subscriptions import (
     TaegisSDKContextSummarizerSubscription,
 )

{taegis_sdk_python-1.6.16 → taegis_sdk_python-1.6.18}/taegis_sdk_python/services/contracted_endpoint/queries.py

@@ -56,6 +56,10 @@ class TaegisSDKContractedEndpointQuery:
         """No developer notes."""
         endpoint = "projectIRHoursForTenantID"
 
+        log.warning(
+            f"GraphQL Query `{endpoint}` is deprecated: 'Use endpointCountForTenantID instead. Planned removal: 2026-09-01'"
+        )
+
         result = self.service.execute_query(endpoint=endpoint, variables={}, output="")
         if result.get(endpoint) is not None:
             return result.get(endpoint)

{taegis_sdk_python-1.6.16 → taegis_sdk_python-1.6.18}/taegis_sdk_python/services/event_stats/queries.py

@@ -36,6 +36,10 @@ class TaegisSDKEventStatsQuery:
         """Get effective agents count for the given tenant and time range."""
         endpoint = "effectiveAgents"
 
+        log.warning(
+            f"GraphQL Query `{endpoint}` is deprecated: 'Use `eventStatsQuery` instead'"
+        )
+
         result = self.service.execute_query(
             endpoint=endpoint,
             variables={

{taegis_sdk_python-1.6.16 → taegis_sdk_python-1.6.18}/taegis_sdk_python/services/events/types.py

@@ -172,6 +172,9 @@ class EventFetchOptions:
     normalize_event_keys: Optional[bool] = field(
         default=None, metadata=config(field_name="normalizeEventKeys")
     )
+    metadata: Optional[dict] = field(
+        default=None, metadata=config(field_name="metadata")
+    )
     backend_strategy: Optional[BackendStrategy] = field(
         default=None, metadata=config(field_name="backendStrategy")
     )

taegis_sdk_python-1.6.18/taegis_sdk_python/services/health/__init__.py

@@ -0,0 +1,35 @@
+"""Health Service."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from taegis_sdk_python.service_core import ServiceCore
+from taegis_sdk_python.services.health.mutations import TaegisSDKHealthMutation
+from taegis_sdk_python.services.health.queries import TaegisSDKHealthQuery
+from taegis_sdk_python.services.health.subscriptions import TaegisSDKHealthSubscription
+
+if TYPE_CHECKING:  # pragma: no cover
+    from taegis_sdk_python.services import GraphQLService
+
+
+class HealthService(ServiceCore):
+    """Taegis Health Service."""
+
+    @property
+    def query(self):
+        if not self._queries:
+            self._queries = TaegisSDKHealthQuery(self)
+        return self._queries
+
+    @property
+    def mutation(self):
+        if not self._mutations:
+            self._mutations = TaegisSDKHealthMutation(self)
+        return self._mutations
+
+    @property
+    def subscription(self):
+        if not self._subscriptions:
+            self._subscriptions = TaegisSDKHealthSubscription(self)
+        return self._subscriptions

taegis_sdk_python-1.6.18/taegis_sdk_python/services/health/mutations.py

@@ -0,0 +1,54 @@
+"""Health Mutation."""
+
+# pylint: disable=no-member, unused-argument, too-many-locals, duplicate-code, wildcard-import, unused-wildcard-import, cyclic-import
+
+
+# Autogenerated
+# DO NOT MODIFY
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
+
+from taegis_sdk_python import GraphQLNoRowsInResultSetError
+from taegis_sdk_python._consts import TaegisEnum
+from taegis_sdk_python.services.health.types import *
+from taegis_sdk_python.utils import (
+    build_output_string,
+    parse_union_result,
+    prepare_input,
+)
+
+if TYPE_CHECKING:  # pragma: no cover
+    from taegis_sdk_python.services.health import HealthService
+
+log = logging.getLogger(__name__)
+
+
+class TaegisSDKHealthMutation:
+    """Taegis Health Mutation operations."""
+
+    def __init__(self, service: HealthService):
+        self.service = service
+
+    def ndr_health_clear_health_status(
+        self, device_name: str, alert_name: str
+    ) -> NDRHealthStatus:
+        """Clear Health Alert."""
+        endpoint = "ndrHealthClearHealthStatus"
+
+        result = self.service.execute_mutation(
+            endpoint=endpoint,
+            variables={
+                "deviceName": prepare_input(device_name),
+                "alertName": prepare_input(alert_name),
+            },
+            output=build_output_string(
+                NDRHealthStatus,
+                exclude_deprecated_output=self.service.exclude_deprecated_output,
+            ),
+        )
+        if result.get(endpoint) is not None:
+            return NDRHealthStatus.from_dict(result.get(endpoint))
+        raise GraphQLNoRowsInResultSetError("for mutation ndrHealthClearHealthStatus")

taegis_sdk_python-1.6.18/taegis_sdk_python/services/health/queries.py

@@ -0,0 +1,111 @@
+"""Health Query."""
+
+# pylint: disable=no-member, unused-argument, too-many-locals, duplicate-code, wildcard-import, unused-wildcard-import, cyclic-import
+
+
+# Autogenerated
+# DO NOT MODIFY
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
+
+from taegis_sdk_python import GraphQLNoRowsInResultSetError
+from taegis_sdk_python._consts import TaegisEnum
+from taegis_sdk_python.services.health.types import *
+from taegis_sdk_python.utils import (
+    build_output_string,
+    parse_union_result,
+    prepare_input,
+)
+
+if TYPE_CHECKING:  # pragma: no cover
+    from taegis_sdk_python.services.health import HealthService
+
+log = logging.getLogger(__name__)
+
+
+class TaegisSDKHealthQuery:
+    """Taegis Health Query operations."""
+
+    def __init__(self, service: HealthService):
+        self.service = service
+
+    def ndr_health_last_event(self, device_name: str) -> NDRHealthLastEvents:
+        """Query to get event timestamps."""
+        endpoint = "ndrHealthLastEvent"
+
+        result = self.service.execute_query(
+            endpoint=endpoint,
+            variables={
+                "deviceName": prepare_input(device_name),
+            },
+            output=build_output_string(
+                NDRHealthLastEvents,
+                exclude_deprecated_output=self.service.exclude_deprecated_output,
+            ),
+        )
+        if result.get(endpoint) is not None:
+            return NDRHealthLastEvents.from_dict(result.get(endpoint))
+        raise GraphQLNoRowsInResultSetError("for query ndrHealthLastEvent")
+
+    def ndr_health_status(self, device_name: str) -> List[NDRHealthStatus]:
+        """Query to get health status of a device."""
+        endpoint = "ndrHealthStatus"
+
+        result = self.service.execute_query(
+            endpoint=endpoint,
+            variables={
+                "deviceName": prepare_input(device_name),
+            },
+            output=build_output_string(
+                NDRHealthStatus,
+                exclude_deprecated_output=self.service.exclude_deprecated_output,
+            ),
+        )
+        if result.get(endpoint) is not None:
+            return NDRHealthStatus.schema().load(
+                [r or {} for r in result.get(endpoint)], many=True
+            )
+        raise GraphQLNoRowsInResultSetError("for query ndrHealthStatus")
+
+    def ndr_health_statuses(self) -> List[NDRHealthStatuses]:
+        """Query to get list of devices with health status of each device."""
+        endpoint = "ndrHealthStatuses"
+
+        result = self.service.execute_query(
+            endpoint=endpoint,
+            variables={},
+            output=build_output_string(
+                NDRHealthStatuses,
+                exclude_deprecated_output=self.service.exclude_deprecated_output,
+            ),
+        )
+        if result.get(endpoint) is not None:
+            return NDRHealthStatuses.schema().load(
+                [r or {} for r in result.get(endpoint)], many=True
+            )
+        raise GraphQLNoRowsInResultSetError("for query ndrHealthStatuses")
+
+    def ndr_health_metrics(
+        self, ndr_health_metrics_query: NDRHealthMetricsQuery
+    ) -> List[NDRHealthMetricsResponse]:
+        """Query to get health metrics of a device for the requested type."""
+        endpoint = "ndrHealthMetrics"
+
+        result = self.service.execute_query(
+            endpoint=endpoint,
+            variables={
+                "ndrHealthMetricsQuery": prepare_input(ndr_health_metrics_query),
+            },
+            output=build_output_string(
+                NDRHealthMetricsResponse,
+                exclude_deprecated_output=self.service.exclude_deprecated_output,
+            ),
+        )
+        if result.get(endpoint) is not None:
+            return NDRHealthMetricsResponse.schema().load(
+                [r or {} for r in result.get(endpoint)], many=True
+            )
+        raise GraphQLNoRowsInResultSetError("for query ndrHealthMetrics")

taegis_sdk_python-1.6.18/taegis_sdk_python/services/health/subscriptions.py

@@ -0,0 +1,33 @@
+"""Health Subscription."""
+
+# pylint: disable=no-member, unused-argument, too-many-locals, duplicate-code, wildcard-import, unused-wildcard-import, cyclic-import
+
+
+# Autogenerated
+# DO NOT MODIFY
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
+
+from taegis_sdk_python import GraphQLNoRowsInResultSetError
+from taegis_sdk_python._consts import TaegisEnum
+from taegis_sdk_python.services.health.types import *
+from taegis_sdk_python.utils import (
+    build_output_string,
+    parse_union_result,
+    prepare_input,
+)
+
+if TYPE_CHECKING:  # pragma: no cover
+    from taegis_sdk_python.services.health import HealthService
+
+log = logging.getLogger(__name__)
+
+
+class TaegisSDKHealthSubscription:
+    """Taegis Health Subscription operations."""
+
+    def __init__(self, service: HealthService):
+        self.service = service