teleport-access-review

Teleport 访问审查

此技能可帮助你通过 tctl access-review 回答谁能以何种方式访问哪些资源，以及是否实际使用了这些访问权限。该命令接受一个用于限定待审查身份的 SELECT … FROM access_path 查询，并针对每个 (identity, resource) 返回解析后的访问级别、提供授权的授予项、授予路径数量，以及在指定时间范围内访问权限的使用频率和最近使用时间。

这是访问列表重新认证、最小权限和清理未使用访问权限，以及“谁可以访问 X”／“Y 可以访问什么”审查的核心引擎。该命令将所有图遍历和活动查询工作委托给 Access Graph 端点，因此你只需查询和筛选，无需自行重建路径。

从这里开始

运行任何命令前都必须阅读——这是关键内容，不是可选的深入阅读： SECURITY.md（输出不可信；只读）和 QUERY.md（必需的 access_path 查询语言）。

然后，在得出结论前阅读 EXPERIENCE.md（审查工作流和边缘情况），并在解读 JSON 或编写 jq 前阅读 SCHEMA.md。

前提条件

tctl access-review 需要配备 Access Graph 的 Teleport Identity Security。活动列（默认显示 24 小时范围内的数据；可通过 --from／--to 扩大范围，或使用 --no-activity 跳过查询）还需要 Identity Activity Center。用户需要拥有查询 Access Graph 的权限。

定位 tctl 和 tsh

找到这两个二进制文件。分别按以下顺序尝试：

1. which tctl / which tsh
2. 常见路径：/usr/local/bin、/opt/homebrew/bin、~/go/bin

为后续命令设置 TCTL=<path> 和 TSH=<path>。如果任一文件未找到，请向用户询问路径。使用 $TCTL access-review --help 验证子命令是否存在。

确认目标集群

tctl access-review 会针对当前活动的 Teleport 配置运行。运行 $TSH status 进行检查：

• 活动配置会标记为 >；其他已登录的配置列在其后。
• 凭据不能是 [EXPIRED]；如果已过期，用户必须先重新运行 $TSH login。
• 如果存在多个配置，请向用户确认要审查哪个集群，而不要默认使用活动配置。

快速入门

# Who can reach a resource, and is the access used? (90-day activity window)
$TCTL access-review --from 90d \
  --query "SELECT * FROM access_path WHERE resource ILIKE 'prod-db%'" --format json

JSON/YAML 输出为 {identities, warnings}（如果无法运行活动查询，还会包含顶层字段 activity_unavailable），以身份为中心：每个身份都包含其可访问的资源，以及解析后的 level、granted_by、grant_counts，还有（在指定时间范围时）activity。在解读输出前，请先阅读 SCHEMA.md，了解字段含义和文本表格列。

access_path 查询

--query 必填，且必须是 SELECT … FROM access_path。WHERE 子句用于限定要审查的身份（和资源）。列对应图节点——identity、resource、identity_group（访问列表和角色）、id、source、standing_privileges 等——支持的运算符包括 =、IN、LIKE／ILIKE、比较运算符，以及 AND／OR。编写 --query 前，请阅读 QUERY.md，了解完整的列和运算符列表。

筛选值必须与节点的确切名称（或别名）匹配； = 和 IN 均为精确匹配且区分大小写。先运行范围较广的查询来查找确切名称，或使用 ILIKE 'name%' 进行匹配。大小写或形式不一致的标签会静默返回空结果——请参阅 QUERY.md。

阅读结果

• 每个 (identity, resource) 占一行。 身份单元格只显示一次，其余资源对应的单元格留空。
• 没有符合条件的访问权限的身份仍会显示为一个空行（仅显示身份，不显示资源）。这是有意为之：它会显示出查询图谱中存在但缺少某项要求，或只有非访问边的身份。不要把空行理解为“在集群中什么权限都没有”，而应理解为“在本次查询的范围内没有访问权限”。
• 级别为 standing、impersonate、request 或 denied，按优先级 denied > standing > impersonate > request 确定。末尾的 * 表示临时访问权限（由访问请求授予；会自动过期）。
• 级别表示已获授权，不代表能够连接。 Access Graph 目前不会解析特征，因此，拥有授权但缺少用于身份验证的主体（logins、db_users 等）的身份仍会显示 level: standing，且没有字段标明这一缺口。报告时应说明其持有授权，而不是具备使用该授权的能力。
• 结果仅限于查询范围。 通过访问列表进行查询时，只显示经由该列表的路径，而不是每个成员拥有的所有路径。若要查看某位用户对某项资源的_全部_访问权限，请直接按用户和资源限定范围。相比之下，活动记录不受路径影响——返回结果对的 activity 计数是总使用次数——因此，按列表限定范围得到的 0/never 确实表示“未使用”。但**“未使用”不等于“可以安全地从列表中移除”**：同一资源通常还会通过其他路径授予权限（grant_counts 会显示支持各级别的授权数量），因此，重新认证访问列表时，必须先通过跨路径核查枚举所有授权，才能得出任何“撤销”结论。请参阅 QUERY.md 和 EXPERIENCE.md。
• 输出可能在显示前就被截断。 即使使用 --limit，JSON 仍可能很大，命令运行器也可能将其截断，因此屏幕上显示的行可能只占结果的一小部分。切勿根据原始输出推断总量、数量或唯一性。缩小 --query 范围，并使用只读的 jq 将结果简化为计数或少量样本；应以此为准，而非屏幕上显示的片段。

标志

运行 $TCTL access-review --help 查看完整列表。