diff --git a/docs/cspell.json b/docs/cspell.json index 3e4d7556f45..cc36c4a8fe1 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -197,6 +197,8 @@ "Passcode", "Passwordless", "Pbbd", + "pg_trgm", + "pgvector", "Pluggable", "Println", "Pulumi", diff --git a/docs/pages/feature-matrix.mdx b/docs/pages/feature-matrix.mdx index a5bcf78eeb9..57b5f5ee225 100644 --- a/docs/pages/feature-matrix.mdx +++ b/docs/pages/feature-matrix.mdx @@ -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 | ✖ | ✔ | ✖ | - diff --git a/docs/pages/identity-security/access-graph/self-hosted-helm.mdx b/docs/pages/identity-security/access-graph/self-hosted-helm.mdx index a92dfcd7aff..c29d0a15ec4 100644 --- a/docs/pages/identity-security/access-graph/self-hosted-helm.mdx +++ b/docs/pages/identity-security/access-graph/self-hosted-helm.mdx @@ -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 diff --git a/docs/pages/identity-security/access-graph/self-hosted.mdx b/docs/pages/identity-security/access-graph/self-hosted.mdx index 0707853ca9e..e149a904db0 100644 --- a/docs/pages/identity-security/access-graph/self-hosted.mdx +++ b/docs/pages/identity-security/access-graph/self-hosted.mdx @@ -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. diff --git a/docs/pages/identity-security/session-summaries/session-search.mdx b/docs/pages/identity-security/session-summaries/session-search.mdx new file mode 100644 index 00000000000..3190e2fdf67 --- /dev/null +++ b/docs/pages/identity-security/session-summaries/session-search.mdx @@ -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. + + +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). + + +## 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: + + + + +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 +``` + + + + +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 +``` + + + + +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`: + + + + +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. + + + + +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. + + + + +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. + + + + +## 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. diff --git a/docs/pages/identity-security/session-summaries.mdx b/docs/pages/identity-security/session-summaries/session-summaries.mdx similarity index 96% rename from docs/pages/identity-security/session-summaries.mdx rename to docs/pages/identity-security/session-summaries/session-summaries.mdx index 3047c9dddb7..37954476278 100644 --- a/docs/pages/identity-security/session-summaries.mdx +++ b/docs/pages/identity-security/session-summaries/session-summaries.mdx @@ -87,7 +87,7 @@ Session Recording Summary Player and Timeline - 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 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, 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 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. +## 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 diff --git a/docs/pages/reference/architecture/session-recording.mdx b/docs/pages/reference/architecture/session-recording.mdx index 559bd421811..afa05ee4743 100644 --- a/docs/pages/reference/architecture/session-recording.mdx +++ b/docs/pages/reference/architecture/session-recording.mdx @@ -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) diff --git a/docs/pages/reference/cli/tctl.mdx b/docs/pages/reference/cli/tctl.mdx index 96fb019519c..a6d5b4984f6 100644 --- a/docs/pages/reference/cli/tctl.mdx +++ b/docs/pages/reference/cli/tctl.mdx @@ -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: + +|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: + +|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: + +|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 \=\\[,...\]| -|`--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 \\[,...\]| @@ -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: + +|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 '\(-\)'| @@ -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)|