Investigate Detections from the CLI

Report an Issue

Is this page helpful?

How can we improve this page?

View as Markdown

Identity Security is available only with Teleport Enterprise.

tctl detections lists and inspects the security detections and anomalies that Teleport Identity Security raises across your infrastructure — the same detections shown in the Web UI under Alerts.

Prerequisites

See Identity Security from the Command Line for the shared prerequisites and how the CLI authenticates to Access Graph. This command requires Access Graph v1.28.0 or later, and Identity Activity Center.

List detections

By default tctl detections ls shows open (in_progress, triaged) detections from the last 30 days:

tctl detections ls

Filter by status, severity, and source, and widen the window:

tctl detections ls --severity=high --severity=critical --status=in_progress --from=7d

Add --detailed for extra columns, or emit JSON/YAML for automation:

tctl detections ls --detailed
tctl detections ls --format=json --limit=25

Flag	Description
--status	Filter by status: in_progress, triaged, resolved, closed. Repeatable. Default: in_progress, triaged.
--severity	Filter by severity: low, medium, high, critical. Repeatable.
--source	Filter by detection source. Repeatable.
--type	Filter by detection type. Repeatable.
--from, --to	Time window. Accepts RFC3339, YYYY-MM-DD, or durations like 24h, 7d. Default: 30d to now.
--detailed	Include extra columns in text output.
--limit	Maximum detections to return. Default: 100.
--format	Output format: text, json, yaml.

Inspect a detection

Once ls surfaces a detection worth investigating, copy its ID from the ID column and pass it to get to see the full detail — description, mitigation steps, related log entries, and status-change history:

tctl detections get 6f6cf1ce-6d1e-4f9e-8f1a-2f7c9b0f1e23

Follow the related log entries into tctl investigate to trace the surrounding activity.

Update a detection's status

Once you have decided what should happen to a detection, record the outcome without leaving the terminal:

tctl detections triage 6f6cf1ce-6d1e-4f9e-8f1a-2f7c9b0f1e23 --reason="Investigating, looks like an extended backup window."

Command	Sets the status to	Use when
tctl detections triage	triaged	You are working on a detection and have not finished.
tctl detections resolve	resolved	The issue was real and has been dealt with.
tctl detections close	closed	No action is needed: false positive or accepted risk.
tctl detections reopen	in_progress	The detection needs to go back to the default state.

Each command takes a detection ID and records a free-text reason. There is no separate resolution category, so the reason carries that context for whoever reads the detection later.

Supply the reason with --reason, or omit the flag to have tctl open your editor on a template. Whole-line # comments are stripped, and an empty reason aborts the change. To record a status change without a reason, pass --allow-empty.

Since tctl detections ls shows only in_progress and triaged detections by default, a detection drops out of the default list once you resolve or close it. Pass --status to see it again:

tctl detections ls --status=resolved --status=closed

Use tctl detections with an AI agent

To let an AI agent drive detection triage with these commands, install the Teleport Detection Triage Agent Skill:

npx skills add https://github.com/gravitational/teleport/tree/master/skills/teleport-detection-triage

Next steps

• tctl detections ls reference
• tctl detections get reference
• tctl detections triage reference
• tctl detections resolve reference
• tctl detections close reference
• tctl detections reopen reference

Troubleshooting

invalid detection id

tctl detections get expects a detection UUID, as shown in the ID column of tctl detections ls. Copy the ID from the list output.

No detections found

Widen --from/--to, relax --status (open detections only by default), or remove severity and source filters. An empty result means nothing matched the filter in the window, not that detections are unavailable.