Anomaly Detection

Overview

The anomalies client provides automated anomaly detection for your authorization system. It identifies unusual patterns such as rate spikes, high failure rates, new principals, and off-hours activity. Access the anomalies client via client.anomalies.

Detect

Run anomaly detection across all agents and return any detected anomalies:

from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    result = client.anomalies.detect()

    print(f"Detected at: {result.detected_at}")
    print(f"Total anomalies: {result.total}")
    for anomaly in result.anomalies:
        print(f"  [{anomaly.severity}] {anomaly.type}: {anomaly.description}")

DetectAnomaliesResponse

Field	Type	Description
`detected_at`	`str`	ISO 8601 timestamp of the detection run.
`total`	`int`	Number of anomalies detected.
`anomalies`	`tuple[Anomaly, ...]`	The detected anomalies.

List

List stored anomalies. Optionally filter to show only unacknowledged anomalies:

from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    # List all anomalies
    result = client.anomalies.list()
    print(f"Total: {result.total}")

    # List only unacknowledged anomalies
    result = client.anomalies.list(unacknowledged=True)
    for anomaly in result.anomalies:
        print(f"  {anomaly.id}: [{anomaly.severity}] {anomaly.type}")
        print(f"    {anomaly.description}")
        print(f"    Detected: {anomaly.detected_at}")

Parameters

Parameter	Type	Required	Default	Description
`unacknowledged`	`bool`	No	`False`	If `True`, only return unacknowledged anomalies.

The parameter is keyword-only.

ListAnomaliesResponse

Field	Type	Description
`anomalies`	`tuple[Anomaly, ...]`	The list of anomalies.
`total`	`int`	Total number of anomalies.

Acknowledge

Acknowledge an anomaly to mark it as reviewed:

from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    anomaly = client.anomalies.acknowledge("anom_abc123")

    print(f"Acknowledged at: {anomaly.acknowledged_at}")

Returns the updated Anomaly with the acknowledged_at timestamp set.

Anomaly Type

The Anomaly frozen dataclass has the following fields:

Field	Type	Description
`id`	`str`	Unique anomaly identifier.
`type`	`str`	The anomaly type (see table below).
`severity`	`str`	`"low"`, `"medium"`, or `"high"`.
`agent_id`	`str \| None`	The agent involved (if applicable).
`principal_id`	`str \| None`	The principal involved (if applicable).
`description`	`str`	Human-readable description of the anomaly.
`metadata`	`dict[str, Any]`	Additional data about the anomaly.
`detected_at`	`str`	ISO 8601 timestamp when the anomaly was detected.
`acknowledged_at`	`str \| None`	ISO 8601 timestamp when the anomaly was acknowledged (or `None`).

Anomaly Types

Type	Description
`rate_spike`	Unusual spike in authorization or token requests.
`high_failure_rate`	Abnormally high rate of failed actions.
`new_principal`	A previously unseen principal is being used.
`off_hours_activity`	Authorization activity outside normal hours.

Example: Monitor and Acknowledge

from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    # Run detection
    detection = client.anomalies.detect()

    if detection.total > 0:
        print(f"Found {detection.total} anomalies!")

        for anomaly in detection.anomalies:
            print(f"\n[{anomaly.severity.upper()}] {anomaly.type}")
            print(f"  {anomaly.description}")

            if anomaly.agent_id:
                print(f"  Agent: {anomaly.agent_id}")
            if anomaly.principal_id:
                print(f"  Principal: {anomaly.principal_id}")

            # Acknowledge after review
            client.anomalies.acknowledge(anomaly.id)
            print(f"  -> Acknowledged")
    else:
        print("No anomalies detected")

​Overview

​Detect

​DetectAnomaliesResponse

​List

​Parameters

​ListAnomaliesResponse

​Acknowledge

​Anomaly Type

​Anomaly Types

​Example: Monitor and Acknowledge