opensource/teleport
3
0
Fork 0
mirror of https://github.com/gravitational/teleport.git synced 2026-09-21 05:55:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

sessionsearch[27]: add session recording search documentation (#66412)

Browse Source 
* sessionsearch[27]: add session recording search documentation

Add Identity Security docs for Session Recording Search

Also update Access Graph docs, the feature matrix, and the tctl CLI reference.

Signed-off-by: Tiago Silva <tiago.silva@goteleport.com>

* handle review feedback

* fix linter

* fix linter

* handle code review comments

* fix linter

---------

Signed-off-by: Tiago Silva <tiago.silva@goteleport.com>
This commit is contained in:
Tiago Silva
2026-05-07 20:16:55 +00:00
committed by GitHub
parent 25f2d6c0b4
commit c8810854ac
8 changed files with 470 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cspell.json
+2
View File
@@ -197,6 +197,8 @@
"Passcode",
"Passwordless",
"Pbbd",
"pg_trgm",
"pgvector",
"Pluggable",
"Println",
"Pulumi",
docs/pages/feature-matrix.mdx
+1 -2
View File
@@ -151,7 +151,7 @@ and non-human identities.
| Analyze shadow access and drift of security posture | ✔ | ✔ | ✖ |
| Investigate identity vulnerabilities and potential exposures | ✔ | ✔ | ✖ |
| Monitor critical assets with [Crown Jewel](identity-security/usage/crown-jewels.mdx) Alerting | ✔ | ✔ | ✖ |
| [Session Recording Summaries](identity-security/session-summaries.mdx) | ✔ | ✔ | ✖ |
| [Session Recording Summaries and Session Recording Search](identity-security/session-summaries/session-search.mdx) | ✔ | ✔ | ✖ |
| Identity Activity Center | ✖ | ✔ | ✖ |
## Platform integrations, management, licensing, and deployment
@@ -181,4 +181,3 @@ and non-human identities.
| Self-hosted deployment| ✖ | ✔ | ✔ |
| Multi-Region High Availability | ✔ (Teleport service) | ✔ (Customer-implemented, via a [supported blueprint](installation/self-hosted/deployments/multi-region-blueprint.mdx)) | ✖ |
| FIPS-compliant binaries available for FedRAMP, including Low, Moderate & High | ✖ | ✔ | ✖ |
docs/pages/identity-security/access-graph/self-hosted-helm.mdx
+4
View File
@@ -47,6 +47,10 @@ chart.
The user that Access Graph connects to the database with needs to be the owner of this database, or have similar broad permissions:
at least the `CREATE TABLE` privilege on the `public` schema, and the `CREATE SCHEMA` privilege.
- Amazon RDS for PostgreSQL is supported.
- [Session Recording Search](../session-summaries/session-search.mdx) requires Access Graph
v1.30.0 or later and a PostgreSQL instance where the `pg_trgm` and
`pgvector` extensions are available. Access Graph enables them
automatically.
- A TLS certificate for the Access Graph service
- The TLS certificate must be issued for "server authentication" key usage,
and must contain an X.509 v3 `subjectAltName` extension with the Kubernetes service name for Access Graph
docs/pages/identity-security/access-graph/self-hosted.mdx
+4
View File
@@ -33,6 +33,10 @@ configuration file and Teleport credentials.
The user that Access Graph connects to the database with needs to be the owner of this database, or have similar broad permissions:
at least the `CREATE TABLE` privilege on the `public` schema, and the `CREATE SCHEMA` privilege.
- Amazon RDS for PostgreSQL is supported.
- [Session Recording Search](../session-summaries/session-search.mdx) requires Access Graph
v1.30.0 or later and a PostgreSQL instance where the `pg_trgm` and
`pgvector` extensions are available. Access Graph enables them
automatically.
- A TLS certificate for the Access Graph service
- The TLS certificate must be issued for "server authentication" key usage,
and must list the IP or DNS name of the Access Graph service in an X.509 v3 `subjectAltName` extension.
docs/pages/identity-security/session-summaries/session-search.mdx
+325
View File
@@ -0,0 +1,325 @@
---
title: Session Recording Search
sidebar_label: Session Recording Search
description: Configure and use Teleport Identity Security Session Recording Search to find summarized session recordings.
tags:
- session-recording
- how-to
- conceptual
- identity-security
- ai
enterprise: Identity Security
---
Session Recording Search lets you find relevant session recordings by searching their
summaries and session metadata. You can search with a natural
language description, exact keywords, or filters such as user, role, resource,
label, session kind, time range, and severity.
Session Recording Search searches session summaries, not raw recording data. A
recording appears in search results only after Teleport has generated a
successful [session recording summary](./session-summaries.mdx) for that
session.
## How it works
When a session summary is generated, Teleport indexes the summary and related
session metadata in Identity Security. Teleport also generates vector embeddings for
summary chunks using the configured `retrieval_model` resource. When a user
runs a search, Teleport Auth Service embeds the search query, queries Identity Security
for matching summaries, applies Teleport RBAC checks, and returns only the
sessions the user is allowed to view.
The default search mode is hybrid search, which combines keyword search and
vector similarity search. You can also run keyword-only or embeddings-only
searches.
<Admonition type="note" title="AI and embeddings">
Session Recording Search sends session summary text and user search queries to
the embeddings provider configured in the `retrieval_model` resource. Review
the same data handling and provider considerations that apply to
[Session Recording Summaries](./session-summaries.mdx).
</Admonition>
## Prerequisites
- A Teleport Enterprise cluster v18.8.0 or later with Identity Security enabled.
- [Session Recording Summaries](./session-summaries.mdx) enabled and generating
successful summaries.
- For self-hosted deployments, Access Graph v1.30.0 or later.
- For self-hosted deployments, a PostgreSQL v14 or later database for Access
Graph where these extensions are available:
- `pg_trgm`, required for keyword search.
- `pgvector`, required for vector similarity search. Its PostgreSQL extension
name is `vector`.
- Permission to read the session recordings you want to search. Search results
are filtered with the same `session` RBAC rules used for session recordings
and summaries.
- At least one SSH node, Kubernetes cluster, or PostgreSQL database connected to
Teleport to generate session recordings.
Teleport Enterprise Cloud manages Access Graph and its backing database. For
self-hosted clusters, follow the [Docker](../access-graph/self-hosted.mdx) or
[Helm](../access-graph/self-hosted-helm.mdx) Access Graph deployment guide and
run Access Graph v1.30.0 or later.
Access Graph enables and manages the required PostgreSQL extensions automatically;
you do not need to run `CREATE EXTENSION` manually.
## Step 1/3. Configure the retrieval model
The `retrieval_model` resource is a cluster-wide singleton named
`retrieval-model`. It tells Teleport which embeddings provider to use for
Session Recording Search and which inference model to use to convert natural
language search queries into API requests and generate prose from session
summaries.
The preset `editor` role can manage `retrieval_model` resources. If you use a
custom administration role, grant `read`, `list`, `create`, `update`, and
`delete` on `retrieval_model`.
For example, create a `session-search-admin.yaml` file with the following
content:
```yaml
kind: role
metadata:
name: session-search-admin
spec:
allow:
rules:
- resources: [retrieval_model]
verbs: [read, list, create, update, delete]
version: v7
```
Session Recording Search needs both an embeddings provider and an inference
model. The embeddings provider converts session summaries and search queries
into vectors for semantic matching. The `inference_model_name` field points to
an existing `inference_model` resource that Teleport uses to convert natural
language search queries into API requests and generate prose from session
summaries. In most deployments, this can be the same inference model you
already configured for Session Recording Summaries.
Choose the tab that matches the embeddings provider you want to use:
<Tabs>
<TabItem label="OpenAI">
You can reuse an existing `inference_secret` that contains your OpenAI or
OpenAI-compatible API key. The following example uses the `openai-key` secret
from the Session Recording Summaries setup and the `shell-summary-model`
inference model.
Session Recording Search supports the `text-embedding-3-large` and
`text-embedding-3-small` OpenAI embedding models:
```yaml
kind: retrieval_model
version: v1
metadata:
name: retrieval-model
spec:
openai:
openai_model_id: text-embedding-3-large
api_key_secret_ref: openai-key
inference_model_name: shell-summary-model
```
</TabItem>
<TabItem label="Amazon Bedrock">
The following example uses Amazon Titan Text Embeddings. Replace the region
with a region available in your AWS account. Session Recording Search supports
only the `amazon.titan-embed-text-v2:0` Bedrock embedding model.
```yaml
kind: retrieval_model
version: v1
metadata:
name: retrieval-model
spec:
bedrock:
region: us-east-1
bedrock_model_id: amazon.titan-embed-text-v2:0
inference_model_name: shell-summary-model
```
</TabItem>
</Tabs>
Save the configuration as `retrieval-model.yaml`, then apply it:
```code
$ tctl create -f retrieval-model.yaml
```
For infrastructure-as-code workflows, see the
[`teleport_retrieval_model` Terraform resource](../../reference/infrastructure-as-code/terraform-provider/resources/retrieval_model.mdx)
or the
[`TeleportRetrievalModelV1` Kubernetes operator resource](../../reference/infrastructure-as-code/operator-resources/resources-teleport-dev-retrievalmodelsv1.mdx).
## Step 2/3. Generate searchable summaries
Conduct a new SSH, Kubernetes, or database session that matches one of your
session summary inference policies. After the session ends, wait for Teleport
to generate its summary. New successful summaries are indexed for Session
Recording Search.
Select a resource type for instructions on connecting to the resource with
`tsh`:
<Tabs>
<TabItem label="Servers">
Run the `tsh ssh` command to connect to a server, specifying the login to assume
on the server you are connecting to. The following command connects to the
server `mynode` as user `root`:
```code
$ tsh ssh root@mynode
```
You can also connect to servers using the Teleport Web UI by navigating to the
**Resources** tab and selecting an SSH server.
</TabItem>
<TabItem label="Kubernetes clusters">
To access a Teleport-connected Kubernetes cluster, run the following command to
update your kubeconfig with a certificate signed by Teleport. The following
command logs in to the cluster mycluster:
```code
$ tsh kube login mycluster
```
Once you have logged into the cluster, run `tsh kubectl` to execute `kubectl`
commands. Teleport can allow or deny access to specific Kubernetes cluster
resources. `tsh kubectl` detects whether the command has failed due to
insufficient permissions and, if so, submits an Access Request for the target
Kubernetes resource.
For example, the following creates an interactive session using the `sh` command
in pod `my-pod`:
```code
$ kubectl exec -it my-pod -- sh
```
You can also connect to Kubernetes resources using the Teleport Web UI by
navigating to the **Resources** tab and selecting a Kubernetes cluster.
</TabItem>
<TabItem label="PostgreSQL database">
To connect to a PostgreSQL database and generate a session recording, use the
Teleport Web UI. Navigate to the **Resources** tab, select a PostgreSQL
database, and start an interactive session.
</TabItem>
</Tabs>
## Step 3/3. Search recordings
Use `tctl recordings search` to search summarized recordings. By default, the
command searches the last 24 hours and opens an interactive terminal UI.
```code
$ tctl recordings search "SSH sessions downloading archives from production"
```
Search with filters:
```code
$ tctl recordings search \
--from=2026-05-01 \
--to=2026-05-04 \
--kind=ssh \
--username=alice \
--label=env=prod \
--severity=high \
"external endpoint"
```
Use JSON or YAML output for automation:
```code
$ tctl recordings search --format=json --limit=25 "DROP TABLE"
```
Choose a search mode:
```code
$ tctl recordings search --search-mode=keyword "rm -rf"
$ tctl recordings search --search-mode=embeddings "credential harvesting"
```
Supported search modes are:
| Mode | Description |
| --- | --- |
| `hybrid` | Default. Combines keyword search and vector similarity search. |
| `keyword` | Uses keyword matching only. |
| `embeddings` | Uses vector similarity search only. |
Common filters include:
| Flag | Description |
| --- | --- |
| `--from`, `--to` | Search time range in `YYYY-MM-DD` format. |
| `--kind` | Session kind, such as `ssh`, `k8s`, or `db`. Can be repeated. |
| `--username` | Teleport user who initiated the session. |
| `--role` | Role held by the user during the session. Can be repeated. |
| `--access-request` | Access Request ID associated with the session. Can be repeated. |
| `--resource-kind` | Teleport resource kind, such as `node`, `kube_cluster`, or `db`. |
| `--resource-name` | Name of the accessed resource. |
| `--label` | Resource labels in `key=value` form. |
| `--severity` | Minimum summary severity: `low`, `medium`, `high`, or `critical`. |
## Next steps
- [tctl recordings search reference](../../reference/cli/tctl.mdx#tctl-recordings-search)
## Troubleshooting
### Session Recording Search requires Access Graph to be enabled with session recording support
Make sure your cluster is connected to Access Graph and that self-hosted
deployments run Access Graph v1.30.0 or later.
### Check PostgreSQL extension availability
Connect to the PostgreSQL database used by Access Graph and query
`pg_available_extensions`:
```sql
SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name IN ('pg_trgm', 'vector')
ORDER BY name;
```
`pg_trgm` should appear as `pg_trgm`. `pgvector` should appear as `vector`,
which is the PostgreSQL extension name. If a row is missing, that extension is
not available in the PostgreSQL instance. If `installed_version` is empty, the
extension is available but is not enabled in the current database yet; Access
Graph enables required extensions automatically when it initializes the
database.
### Session Recording Search requires the pg_trgm PostgreSQL extension
Use a PostgreSQL instance where `pg_trgm` is available to the Access Graph
database. Access Graph enables the extension automatically.
### Session Recording Search requires the pgvector PostgreSQL extension
Use a PostgreSQL instance where `pgvector` is available to the Access Graph
database. Access Graph enables the `vector` extension automatically.
### No sessions found
Check that the search time range includes the session, that the session has a
successful summary, and that your Teleport roles allow you to read the
recording. Session Recording Search does not return recordings that have not
been summarized.
docs/pages/identity-security/session-summaries.mdx → docs/pages/identity-security/session-summaries/session-summaries.mdx
+22 -15
View File
@@ -87,7 +87,7 @@ Session Recording Summary Player and Timeline
<Tabs>
<TabItem label="Teleport Enterprise Cloud">
- A Teleport Enterprise Cloud tenant running v18.2.0 or later with Identity
Security enabled. v18.7.1 required to use Teleport managed profiles.
Security enabled. v18.7.1 required to use Teleport managed profiles.
- Optionally, access to your own LLM API (OpenAI, Amazon Bedrock, or an
OpenAI-compatible gateway). If you don't bring your own, you can use the
Teleport-managed model included with your Cloud tenant.
@@ -169,7 +169,7 @@ underlying API-specific model name
Teleport Enterprise Cloud tenants come with a pre-provisioned inference model
called `teleport-cloud-default`, powered by Amazon Bedrock. Teleport manages the
underlying model and infrastructure.
underlying model and infrastructure.
No additional configuration is needed for this step. Skip to
[Step 3](#step-35-set-up-an-inference-policy) and reference
@@ -324,7 +324,7 @@ The exact procedure for attaching this policy is different depending on the
details of your infrastructure; for example, if you are running Teleport on an
EC2 instance, you should navigate to that instance in the AWS Console, and
modify the role specified in the **IAM Role** section of the instance summary.
(If there's no IAM role set, use **Actions -> Security -> Modify IAM role**.)
(If there's no IAM role set, use **Actions -> Security -> Modify IAM role**.)
### Create an `inference_model` resource
@@ -346,7 +346,7 @@ modify the role specified in the **IAM Role** section of the instance summary.
# If unset, defaults to 200kB. See the Limitations section for more details.
max_session_length_bytes: 190000
```
Replace <Var name="bedrock-model-or-inference-profile-arn"/> with an ARN of
the Amazon Bedrock foundation model or an inference profile. A Bedrock model
ID can also be used.
@@ -357,7 +357,7 @@ modify the role specified in the **IAM Role** section of the instance summary.
model support by AWS
region](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html)
from the official AWS documentation.
If `bedrock_model_id` refers to an inference profile, <Var name="region"/>
needs to point to a region specified in the inference profile ARN.
@@ -455,16 +455,16 @@ summarize (Kubernetes, Database, SSH), give the policy a name, and click
</Tabs>
For full description of the inference configuration resources, see appropriate
sections of [Teleport Resources Reference](../reference/infrastructure-as-code/teleport-resources/teleport-resources.mdx):
sections of [Teleport Resources Reference](../../reference/infrastructure-as-code/teleport-resources/teleport-resources.mdx):
- [`inference_model`](../reference/infrastructure-as-code/teleport-resources/inference-model.mdx)
- [`inference_secret`](../reference/infrastructure-as-code/teleport-resources/inference-secret.mdx) (only for OpenAI and compatible APIs)
- [`inference_policy`](../reference/infrastructure-as-code/teleport-resources/inference-policy.mdx)
- [`inference_model`](../../reference/infrastructure-as-code/teleport-resources/inference-model.mdx)
- [`inference_secret`](../../reference/infrastructure-as-code/teleport-resources/inference-secret.mdx) (only for OpenAI and compatible APIs)
- [`inference_policy`](../../reference/infrastructure-as-code/teleport-resources/inference-policy.mdx)
## Step 4/5: Configure access to session summaries
Every user who has access to
[given session recording](../reference/access-controls/roles.mdx#rbac-for-session-recordings)
[given session recording](../../reference/access-controls/roles.mdx#rbac-for-session-recordings)
also has access to its summary through a `session` resource kind. The preset
`access` role allows users to only view their sessions; in order to allow a
user to view all recordings and summaries, it's easiest to use the preset
@@ -507,7 +507,7 @@ session, and go to **Audit -> Session Recordings**. You should see the
corresponding recording tile with a summary button. Clicking the summary button
will show the summary.
### Session Recording Summary Dashboard
### Session Recording Summary Dashboard
![Session recording list screen with a summary visible](https://website.goteleport.com/_uploads/session_summary_list_3fe0cae7ac.png)
@@ -518,10 +518,17 @@ factors, including session size, model, and its temperature. Usually it should
appear up to a minute after the session is uploaded to the Auth service.
</Admonition>
## Session Recording Search
After summaries are enabled, you can configure
[Session Recording Search](./session-search.mdx) to find summarized recordings
by natural language query, keyword search, session metadata, resource labels,
Access Request IDs, and severity.
## Audit Events for Session Summaries
After a session is summarized, an audit event is generated. This allows you to
forward events to a SIEM to alert the high severity sessions.
forward events to a SIEM to alert the high severity sessions.
```json
// Example Session Summarization with a critical risk level.
@@ -672,7 +679,7 @@ session, and user.
| resource.metadata.labels | Resource labels | `equals(resource.metadata.labels["env"], "prod")` |
| resource.metadata.name | Resource name. In case of SSH servers, it's the server ID. | `resource.metadata.name == "production-cluster"` |
| resource.spec.addr | Server address (SSH sessions only) | `resource.spec.addr == "123.123.123.123:3022"` |
| resource.spec.db_protocol | Database protocol (database sessions only). See [DB resource reference](../reference/infrastructure-as-code/teleport-resources/database-v3.mdx) for supported values. | `resource.spec.db_protocol == "postgres"` |
| resource.spec.db_protocol | Database protocol (database sessions only). See [DB resource reference](../../reference/infrastructure-as-code/teleport-resources/database-v3.mdx) for supported values. | `resource.spec.db_protocol == "postgres"` |
| resource.spec.hostname | Server hostname (SSH sessions only) | `resource.spec.hostname == "dummy-host"` |
| resource.spec.uri | Database URI (database sessions only) | `has_prefix(resource.spec.uri, "db-host")` |
| session | The session that is being matched. This object supports all the fields of `session.end` and `db.session.end` events, so we only name the most useful ones here. | |
@@ -741,7 +748,7 @@ Teleport exposes a couple of useful Prometheus metrics that can be used to
monitor the session summarizer. Metrics are labeled by inference model name,
and in case of OpenAI errors — additionally with the OpenAI API error code. See
the [Teleport Metrics
reference](../reference/deployment/monitoring/metrics.mdx#session-recording-summarizer)
reference](../../reference/deployment/monitoring/metrics.mdx#session-recording-summarizer)
for details.
## Troubleshooting
@@ -758,7 +765,7 @@ the `inference_model` resource.
### Amazon Bedrock model identifier is invalid
**Problem:** Summarization fails with "ValidationException: The provided model
identifier is invalid."
identifier is invalid."
**Solution:** One possible reason is a mismatch between the `region` declared
in the `inference_model` resource and available regions for the given model or
docs/pages/reference/architecture/session-recording.mdx
+1 -1
View File
@@ -351,4 +351,4 @@ viewed using the Teleport web app.
- [SSH recording modes](../deployment/monitoring/audit.mdx)
- [Session recording for desktops](../../enroll-resources/desktop-access/reference/sessions.mdx)
- [Encrypted Session Recordings](../../enroll-resources/server-access/guides/encrypted-session-recordings/encrypted-session-recordings.mdx)
- [Session recording summaries](../../identity-security/session-summaries.mdx)
- [Session recording summaries](../../identity-security/session-summaries/session-summaries.mdx)
docs/pages/reference/cli/tctl.mdx
+111 -9
View File
@@ -34,8 +34,8 @@ Global flags:
|`-c`, `--config`|none|Path to a configuration file \[/etc/teleport.yaml\] for an Auth Service instance. Can also be set via the TELEPORT_CONFIG_FILE environment variable. Ignored if the auth_service is disabled.|
|`-d`, `--[no-]debug`|`false`|Enable verbose logging to stderr|
|`-i`, `--identity`|none|Path to an identity file. Must be provided to make remote connections to auth. An identity file can be exported with 'tctl auth sign'|
|`--[no-]insecure`|`false`|When specifying a proxy address in --auth-server, do not verify its TLS certificate. Danger: any data you send can be intercepted or modified by an attacker.|
|`--mfa-mode`|`auto`|Preferred mode for MFA assertions (auto, cross-platform, platform, sso, browser).|
|`--[no-]insecure`|`false`|When specifying a proxy address in --auth-server, do not verify its TLS certificate. Danger: any data you send can be intercepted or modified by an attacker.|
Global environment variables:
@@ -129,6 +129,30 @@ Arguments:
|---|---|---|
|access-list-name|none (required)|The access list name to fetch review history for.|
## tctl acl summary
Show summary information for access lists, including their members and last
review.
Usage:
```code
$ tctl acl summary [<flags>] [<access-list-name>]
```
Flags:
|Flag|Default|Description|
|---|---|---|
|`--format`|`yaml`|Output format 'yaml' or 'json'|
|`--[no-]review-only`|`true`|Show only access lists that are due for review within the next 2 weeks or past due. Defaults to true.|
Arguments:
|Argument|Default|Description|
|---|---|---|
|access-list-name|none (optional)|The access list name to show summary for. If not provided, shows summary for all access lists.|
## tctl acl users add
Add a user to an Access List.
@@ -496,7 +520,7 @@ Flags:
|`--integration`|none|Name of the integration. Only applies to "github" CAs.|
|`--[no-]keys`|`false`|if set, will print private keys|
|`--out`|none|If set writes exported authorities to files with the given path prefix|
|`--type`|none|export certificate type (user, host, tls-host, tls-user, tls-user-der, tls-spiffe, windows, db, db-der, db-client, db-client-der, openssh, saml-idp, github, awsra)|
|`--type`|none|export certificate type (user, host, tls-host, tls-user, tls-user-der, tls-spiffe, windows, db, db-der, db-client, db-client-der, openssh, saml-idp, github, awsra, app-client)|
## tctl auth ls
@@ -533,7 +557,7 @@ Flags:
|`--[no-]interactive`|`false`|Enable interactive mode|
|`--[no-]manual`|`false`|Activate manual rotation, set rotation phases manually|
|`--phase`|none|Target rotation phase to set, used in manual rotation, one of: init, standby, update_clients, update_servers, rollback|
|`--type`|none|Certificate authority to rotate, one of: host, windows, user, db, db_client, openssh, jwt, saml_idp, oidc_idp, spiffe, okta, awsra, bound_keypair|
|`--type`|none|Certificate authority to rotate, one of: host, windows, user, db, db_client, openssh, jwt, saml_idp, oidc_idp, spiffe, okta, awsra, bound_keypair, app_client|
## tctl auth sign
@@ -1048,6 +1072,26 @@ Flags:
|`--device-id`|none|Device identifier|
|`--[no-]current-device`|`false`|Removes the current device. Overrides --device-id and --asset-tag.|
## tctl discovery nodes
Report discovered server instances and their enrollment status using Teleport
audit log and cluster state.
Usage:
```code
$ tctl discovery nodes [<flags>]
```
Flags:
|Flag|Default|Description|
|---|---|---|
|`--cloud`|``|Comma-separated list of cloud providers to include (allowed: aws, azure). Empty (default) returns all.|
|`--format`|`text`|Output format.|
|`--last`|`1h`|Time window to look back for failures in Teleport audit log (e.g. 1h, 24h, 30m).|
|`--[no-]failures-only`|`false`|Only show instances with enrollment failures.|
## tctl edit
Edit a Teleport resource.
@@ -1237,6 +1281,7 @@ Flags:
|`--device`|none|UUID of a trusted device to disable.|
|`--expires`|none|Time point (RFC3339) when the lock expires.|
|`--join-token`|none|Bot join token name to disable|
|`--linux-desktop`|none|Name of a Linux desktop to disable.|
|`--login`|none|Name of a local UNIX user to disable.|
|`--message`|none|Message to display to locked-out users.|
|`--mfa-device`|none|UUID of a user MFA device to disable.|
@@ -1702,6 +1747,45 @@ Flags:
|`--limit`|`50`|Maximum number of recordings to show. Default 50.|
|`--to-utc`|none|End of time range in which recordings are listed. Format 2006-01-02. Defaults to current time.|
## tctl recordings search
Search session recordings using semantic and keyword queries.
Usage:
```code
$ tctl recordings search [<flags>] [<query>...]
```
Flags:
|Flag|Default|Description|
|---|---|---|
|`--access-request`|none|Filter by access request ID. Can be specified multiple times.|
|`--database-name`|none|Filter database sessions by database name.|
|`--format`|`text`|Format output (text, json, yaml).. Defaults to 'text'.|
|`--from`|none|Start of time range. Format 2006-01-02. Defaults to 24 hours ago.|
|`--kind`|none|Filter by session kind (ssh, db, k8s, desktop). Can be specified multiple times.|
|`--label`|none|Filter by resource labels (key=value pairs), e.g. env/prod=true,db/type=postgres.|
|`--limit`|`50`|Maximum number of results to return.|
|`--pod-name`|none|Filter Kubernetes sessions by pod name.|
|`--pod-namespace`|none|Filter Kubernetes sessions by pod namespace.|
|`--resource-kind`|none|Filter by Teleport resource type (node, kube_cluster, db).|
|`--resource-name`|none|Filter by resource name.|
|`--role`|none|Filter by role held during the session. Can be specified multiple times.|
|`--search-mode`|`hybrid`|Search strategy to use when search queries are provided.|
|`--server-addr`|none|Filter SSH sessions by server address.|
|`--server-hostname`|none|Filter SSH sessions by server hostname.|
|`--severity`|none|Minimum severity level to include (low, medium, high, critical).|
|`--to`|none|End of time range. Format 2006-01-02. Defaults to current time.|
|`--username`|none|Filter by the Teleport username that initiated the session.|
Arguments:
|Argument|Default|Description|
|---|---|---|
|query|none (optional)|Natural language description of the sessions to find (e.g. "SSH sessions exfiltrating data to external endpoints").|
## tctl requests approve
Approve pending Access Request.
@@ -1717,7 +1801,7 @@ Flags:
|Flag|Default|Description|
|---|---|---|
|`--annotations`|none|Resolution attributes \<key\>=\<val\>\[,...\]|
|`--assume-start-time`|none|Sets time roles can be assumed by requestor (RFC3339 e.g. 2023-12-12T23:20:50.52Z)|
|`--assume-start-time`|none|Sets time roles can be assumed by requestor (RFC3339 e.g 2023-12-12T23:20:50.52Z)|
|`--delegator`|none|Optional delegating identity|
|`--reason`|none|Optional reason message|
|`--roles`|none|Override requested roles \<role\>\[,...\]|
@@ -1894,6 +1978,24 @@ Arguments:
|---|---|---|
|connector_name|none (required)|name of the SAML connector to export the key from|
## tctl scoped assignments list
List scoped role assignments
Usage:
```code
$ tctl scoped assignments list [<flags>]
```
Flags:
|Flag|Default|Description|
|---|---|---|
|`-f`, `--format`|`text`|Format output (text, json, yaml).|
|`--role`|none|Filter by assigned role.|
|`--user`|none|Filter by user.|
## tctl scoped status
Show the status of scoped resources.
@@ -1919,7 +2021,7 @@ Flags:
|Flag|Default|Description|
|---|---|---|
|`--assign-scope`|none|Scope that should be applied to resources provisioned by this token|
|`--format`|none|Output format, 'text', 'json', or 'yaml'|
|`--format`|none|Format output (text, json, yaml).|
|`--labels`|none|Set token labels, e.g. env=prod,region=us-west|
|`--mode`|none|Usage mode of a token (default: unlimited, single_use)|
|`--name`|none|Override the default, randomly generated token name with a specified name|
@@ -1942,7 +2044,7 @@ Flags:
|Flag|Default|Description|
|---|---|---|
|`--format`|none|Output format, 'text', 'json' or 'yaml'|
|`-f`, `--format`|none|Format output (text, json, yaml).|
|`--[no-]with-secrets`|`false`|Do not redact join tokens|
## tctl scoped tokens rm
@@ -2103,7 +2205,7 @@ $ tctl status
## tctl terraform env
Obtain certificates and load them into environments variables. This creates a
Obtain certificates and load them into environment variables. This creates a
temporary MachineID bot.
Usage:
@@ -2165,7 +2267,7 @@ Flags:
|`--context`|none|Kubernetes context to use. When not set, defaults to the active context.|
|`-f`, `--[no-]force`|`false`|Force the token creation, even if the token already exists|
|`-j`, `--join-with`|`auto`|Kubernetes joining type, possible values are 'oidc', 'jwks', and 'auto'. See https://goteleport.com/docs/reference/join-methods/#kubernetes-kubernetes for more details.|
|`-n`, `--namespace`|`teleport`|Namespace of the Kubernetes Service Account using the token. For 'teleport-kube-agent' and 'tbot' Helm charts, this is release namespace.|
|`-n`, `--namespace`|`teleport`|Namespace of the Kubernetes Service Account using the token. For 'teleport-kube-agent' and 'tbot' Helm charts, this is the release namespace.|
|`-o`, `--out`|`./values.yaml`|Path of the output file.|
|`-s`, `--service-account`|none|Name of the Kubernetes Service Account using the token. For 'teleport-kube-agent' and 'tbot' Helm charts, this is the release name.|
|`--token-name`|none|Optional name of the created join token. When not set, default to '\<CLUSTER_NAME\>(-\<BOT_NAME\>)'|
@@ -2406,7 +2508,7 @@ Flags:
|Flag|Default|Description|
|---|---|---|
|`--expires-at`|none|Time that the revocation should expire, usually this should match the expiry time of the credential. This should be specified using RFC3339 e.g. '2024-02-05T15:04:00Z'. If unspecified, the time 1 week from now is used.|
|`--expires-at`|none|Time that the revocation should expire, usually this should match the expiry time of the credential. This should be specified using RFC3339 e.g '2024-02-05T15:04:00Z'. If unspecified, the time 1 week from now is used.|
|`--reason`|none|Reason for revocation.|
|`--serial`|none|Serial number of the certificate to revoke.|
|`--type`|none|Type of credential to revoke (x509)|