endor-setup

Endorctl 设置与安全扫描

前置技能，确保在执行任何 Endor Labs 操作前已安装、完成身份验证并配置好 endorctl。

工作流概览

当用户要求设置 endorctl 并运行基本扫描时，请按以下顺序操作：

1. 检查是否已安装 endorctl（步骤 1）

   • 如果未安装 → 下载并安装（步骤 2）
   • 如果已安装但未完成身份验证 → 询问命名空间（步骤 3），然后完成身份验证（步骤 4）
   • 如果已安装且已完成身份验证 → 询问命名空间（步骤 3），然后运行扫描

2. 务必在身份验证前询问命名空间（步骤 3）——这对于在非交互式环境中成功完成 CLI 身份验证至关重要。必须先收集命名空间，以便将其传递给 endorctl init --namespace=<namespace>，从而避免出现交互式租户选择提示。

3. 绝不能因“找不到命令”而失败——如果缺少 endorctl，务必安装。

4. 关键原则：主动处理。如果缺少 endorctl，请自动安装，而不是让用户自行安装。

5. 命名空间层级：用户可以在父级租户或子级命名空间上进行扫描（格式：parent.child）。始终接受用户提供的命名空间。

6. 访问错误：如果用户无权访问某个租户/命名空间，请明确告知他们缺少访问权限，并建议他们确认权限或尝试其他命名空间。

7. 自动获取文档：从 docs.endorlabs.com 获取扫描选项时，请自动获取。这是可信的文档来源。

8. 关键——非交互式环境：AI 编码 Agent 运行于非交互式 CLI 环境中。需要交互式输入的命令（例如租户选择提示）会因 EOF 错误而失败。务必使用标志预先提供值，而不要依赖交互式提示。

9. 多租户用户：有权访问多个 Endor Labs 租户的用户，在使用浏览器 OAuth 时需要特殊处理。仅使用 --namespace 标志无法避免交互式租户选择提示。必须捕获租户列表并将租户编号通过管道传入，以在单个流程中完成身份验证。详情请参阅步骤 4。

默认值

如果现有配置文件中包含 API 端点，则使用该端点。如果没有配置文件，则默认使用生产环境：

# If config exists, use its ENDOR_API value; otherwise default to production
export ENDOR_API=${ENDOR_API:-https://api.endorlabs.com}

步骤 1：检查安装情况和现有身份验证状态

重要：如果用户要求运行 endorctl scan，但尚未安装，不要只报告错误。请先按照此工作流安装。

同时运行以下检查，以确定用户的状态：

# Check if installed
if ! command -v endorctl &> /dev/null; then
  echo "NOT_INSTALLED"
else
  endorctl --version
fi

# Check if already authenticated (config file exists with credentials)
if [ -f ~/.endorctl/config.yaml ]; then
  echo "CONFIG_EXISTS"
  # Extract ENDOR_API from config (do NOT cat the full file)
  ENDOR_API=$(grep 'api:' ~/.endorctl/config.yaml | awk '{print $2}')
  export ENDOR_API=${ENDOR_API:-https://api.endorlabs.com}
  echo "ENDOR_API=$ENDOR_API"
else
  echo "NOT_AUTHENTICATED"
  export ENDOR_API=https://api.endorlabs.com
fi

根据结果判断：

• 如果为 NOT_INSTALLED：立即转到步骤 2（下载）——不要询问用户，直接开始安装
• 如果为 CONFIG_EXISTS：用户已完成身份验证 → 上方的 grep 命令已提取 ENDOR_API。转到步骤 3（询问命名空间）。不要对配置文件运行 cat。
• 如果为 NOT_AUTHENTICATED：转到步骤 4（身份验证），然后转到步骤 3（询问命名空间）

关键：检查配置文件仅用于确定是否已设置身份验证。即使配置文件中存在命名空间，运行扫描前仍必须询问用户想使用哪个命名空间。绝不要默认使用配置文件中的命名空间。

步骤 2：下载 endorctl（如果为 NOT_INSTALLED，则必须执行）

执行时机：如果步骤 1 显示“NOT_INSTALLED”，则自动执行此步骤。

macOS 安装（询问用户选择）

重要：在 macOS 上，继续操作前务必询问用户偏好的安装方式：

使用 AskUserQuestion 呈现以下两个选项：

1. Homebrew（推荐）——使用 brew tap endorlabs/tap && brew install endorctl。之后更易于更新。
2. 直接下载——直接从 api.endorlabs.com 下载二进制文件。无需 Homebrew。

选项 1：Homebrew 安装（macOS）

brew tap endorlabs/tap
brew install endorctl

选项 2：直接下载安装（macOS）

ARCH=$(uname -m)
case "$ARCH" in
  x86_64|amd64) ARCH="amd64" ;;
  arm64|aarch64) ARCH="arm64" ;;
esac

BINARY="endorctl_macos_${ARCH}"
echo "Downloading $BINARY..."
curl -L "https://api.endorlabs.com/download/latest/$BINARY" -o endorctl

# Verify checksum
EXPECTED_SHA=$(curl -s "https://api.endorlabs.com/sha/latest/$BINARY")
echo "$EXPECTED_SHA  endorctl" | shasum -a 256 -c

chmod +x ./endorctl

# Install to ~/bin
mkdir -p ~/bin
mv endorctl ~/bin/
export PATH="$HOME/bin:$PATH"

Linux/Windows 安装（自动）

对于 Linux 和 Windows，请直接自动下载：

#!/bin/bash
set -e

OS=$(uname -s)
ARCH=$(uname -m)

# Normalize OS names
case "$OS" in
  Linux*)
    OS="linux"
    ;;
  MINGW*|MSYS*|CYGWIN*)
    OS="windows"
    ;;
  *)
    echo "Unsupported operating system: $OS"
    exit 1
    ;;
esac

# Normalize architecture names
case "$ARCH" in
  x86_64|amd64)
    ARCH="amd64"
    ;;
  arm64|aarch64)
    ARCH="arm64"
    ;;
  *)
    echo "Unsupported architecture: $ARCH"
    exit 1
    ;;
esac

echo "Detected platform: $OS $ARCH"

# Build download URL
if [ "$OS" = "windows" ]; then
  BINARY="endorctl_windows_${ARCH}.exe"
  OUTPUT="endorctl.exe"
else
  BINARY="endorctl_${OS}_${ARCH}"
  OUTPUT="endorctl"
fi

echo "Downloading $BINARY..."
curl -L "https://api.endorlabs.com/download/latest/$BINARY" -o "$OUTPUT"

# Verify checksum
echo "Verifying checksum..."
EXPECTED_SHA=$(curl -s "https://api.endorlabs.com/sha/latest/$BINARY")
echo "$EXPECTED_SHA  $OUTPUT" | sha256sum -c

# Make executable (not needed for .exe)
if [ "$OS" != "windows" ]; then
  chmod +x "./$OUTPUT"
fi

echo "Installation complete!"
echo "Binary location: $(pwd)/$OUTPUT"

下载完成后，将二进制文件移至 PATH：

# Install to ~/bin
mkdir -p ~/bin
mv endorctl ~/bin/  # or endorctl.exe on Windows
export PATH="$HOME/bin:$PATH"

验证安装

由于 Shell 状态不会在命令之间持久保留，之后每次在 Bash 命令中使用 endorctl 时，都必须在命令前加上 export PATH="$HOME/bin:$PATH"（如果它安装在 ~/bin 中）。

安装 endorctl 后，验证下载和安装是否成功：

export PATH="$HOME/bin:$PATH"
endorctl --version

如果此命令输出版本信息，则表示 endorctl 已成功下载并通过验证。如果失败，请重试上述安装步骤。

第 3 步：询问命名空间（始终必需）

重要：运行扫描前，始终询问用户的 Endor Labs 命名空间，即使配置文件中已存在命名空间也不例外。

• 如果配置中存在命名空间，可将其作为建议，但仍须征求确认
• 切勿假定用户想使用上次会话中的同一命名空间
• 用户每次可能想使用不同的命名空间（父级或子级）进行扫描

命名空间层级结构

Endor Labs 支持分层命名空间（父级/子级结构）：

• 父级租户：顶级命名空间（例如，parent）
• 子级命名空间：父级下的子命名空间（例如，parent.child-project）

用户可以在以下命名空间中运行扫描：

• 其父级租户命名空间
• 其父级租户下的任意子级命名空间（格式：parent.child）

子级命名空间用法示例：

# Scan using parent namespace
endorctl scan --namespace=parent

# Scan using child namespace
endorctl scan --namespace=parent.my-project

访问错误处理

重要：如果用户无权访问某个租户或命名空间，endorctl 将返回访问错误。出现这种情况时：

1. 清楚地告知用户：告诉他们无权访问指定的租户/命名空间
2. 显示错误消息：显示 endorctl 返回的实际错误
3. 提供替代方案：
   • 询问他们是否指的是其他命名空间
   • 建议他们在 Endor Labs UI 中检查权限
   • 提供列出他们有权访问的租户的选项
4. 建议访问官方文档：告诉他们访问 https://docs.endorlabs.com/administration/namespaces/，以了解有关命名空间的更多详情。 常见访问错误模式：

• Invalid permissions to run endorctl - 用户无权访问该命名空间
• unauthorized 或 403 错误 - 身份验证成功，但未获准访问该命名空间
• tenant not found - 命名空间不存在，或用户无权查看该命名空间

设置命名空间

通过环境变量设置：

export ENDOR_NAMESPACE=<user-provided-namespace>

或在扫描命令中作为标志传入：

endorctl scan --namespace=<user-provided-namespace>

第 4 步：身份验证

重要：运行身份验证前，必须已在第 3 步收集命名空间信息。这是避免出现交互式提示的必要条件。

第 4a 步：询问身份验证方式

使用 AskUserQuestion 向用户询问，并提供两个选项：

1. CLI 身份验证（推荐） - 通过浏览器使用身份提供商（Google、GitHub、GitLab、SSO 等）登录
2. API Key - 在自动化/CI 环境中使用 API key 和密钥（无需浏览器）

选项 1：CLI 身份验证

步骤 4b：询问身份提供方

如果用户选择 CLI 身份验证，请询问他们使用哪个身份提供方。使用 AskUserQuestion 提供以下选项：

1. Google - 使用 Google 登录
2. GitHub - 使用 GitHub 登录
3. GitLab - 使用 GitLab 登录
4. 企业 SSO - 通过组织的 SSO 提供方登录（需要租户名称）
5. 浏览器（通用） - 通用的基于浏览器的登录

根据用户的选择，使用相应的 --auth-mode 值：

提供方	--auth-mode 值	附加标志
Google	google	无
GitHub	github	无
GitLab	gitlab	无
企业 SSO	sso	--auth-tenant <tenant-name>
浏览器（通用）	browser-auth	无

仅限企业 SSO：用户选择 SSO 后，还要询问其 SSO 租户名称：

"What is your SSO tenant name? (This is used with --auth-tenant)"

步骤 4c：运行身份验证（CLI 身份验证的两步流程）

关键 - 多租户处理：拥有多个租户访问权限的用户会收到交互式租户选择提示。在非交互式 Agent 环境中，这会导致 EOF 错误。仅使用 --namespace 标志并不能阻止此提示。这适用于所有基于浏览器的身份验证模式。

根据用户选择的提供方构造 AUTH_FLAGS：

# Set AUTH_FLAGS based on user's provider selection
# Google:           AUTH_FLAGS="--auth-mode=google"
# GitHub:           AUTH_FLAGS="--auth-mode=github"
# GitLab:           AUTH_FLAGS="--auth-mode=gitlab"
# Enterprise SSO:   AUTH_FLAGS="--auth-mode=sso --auth-tenant=<tenant-name>"
# Browser (generic): AUTH_FLAGS="--auth-mode=browser-auth"

步骤 4c-i：启动浏览器 OAuth 并捕获租户列表

运行 init 并捕获输出——这会打开浏览器进行 OAuth 身份验证。浏览器身份验证完成后，如果用户有多个租户，系统会显示租户列表。

重要：使用超时，防止命令在交互式租户选择提示处无限期阻塞。AI 编码 Agent 中的 Shell 工具通常无法向正在运行的进程提供交互式输入。超时可确保命令退出，以便 Agent 解析输出并继续执行步骤 4c-ii。

# Run init with a timeout (60s allows time for browser OAuth, but won't hang forever at the tenant prompt)
# The timeout will kill the process after 60 seconds if it's still waiting for input
timeout 60 bash -c 'endorctl init $AUTH_FLAGS --namespace=<user-provided-namespace> 2>&1' | tee /tmp/endorctl_init_output.txt || true

此命令完成后（成功完成或因超时／EOF 退出），检查捕获的输出：

# Check if tenant selection was required
if grep -q "Please select the tenant" /tmp/endorctl_init_output.txt; then
  echo "MULTI_TENANT_DETECTED"
  cat /tmp/endorctl_init_output.txt
fi

如果输出显示类似以下内容的租户列表：

Your account has access to multiple tenants. Please select the tenant you would like to initialize:
0 : tenant-a [SYSTEM_ROLE_ADMIN]
1 : tenant-b [SYSTEM_ROLE_READ_ONLY]
2 : my-namespace [SYSTEM_ROLE_ADMIN]
Enter tenant number:

然后立即继续执行步骤 4c-ii。

步骤 4c-ii：通过管道传入租户编号并重新运行

解析捕获的输出，找到与用户请求的命名空间对应的租户编号。租户编号是包含命名空间名称的行中 : 之前的数字。

# Parse the tenant number from the captured output
# Example: for namespace "qa-test", find the line "15 : qa-test [SYSTEM_ROLE_ADMIN]" and extract "15"
TENANT_NUM=$(grep -E "^\s*[0-9]+ : <user-provided-namespace> " /tmp/endorctl_init_output.txt | awk '{print $1}')
echo "Found tenant number: $TENANT_NUM"

# Re-run with tenant number piped via stdin (no tee needed this time)
echo "$TENANT_NUM" | endorctl init $AUTH_FLAGS --namespace=<user-provided-namespace>

重要：echo "$TENANT_NUM" | 语法会将租户编号通过管道传入 stdin，与 <<< 相比，它在不同 Shell 环境中的兼容性更好。这样第二次运行时就完全避免了交互式提示。

如果身份验证仍然失败（例如，用户无权访问指定的命名空间）：

1. 清楚地显示错误消息
2. 显示输出中的可用租户列表
3. 请用户确认他们有权访问该命名空间，或从列表中选择一个

选项 2：API 密钥（自动化／CI）

指示用户自行设置这些环境变量（绝不要要求他们在聊天中粘贴凭据）：

export ENDOR_API_CREDENTIALS_KEY=<your-api-key>
export ENDOR_API_CREDENTIALS_SECRET=<your-api-secret>

无需运行 init——扫描会直接使用这些凭据。

注意：API 密钥身份验证可完全避免交互式提示，在自动化／CLI 环境中效果最佳。对于经常遇到多租户选择问题的用户，推荐使用此方法。

扫描类型和选项（始终从文档获取）

重要：当用户请求特定类型的扫描（例如“快速扫描”“密钥扫描”“SAST 扫描”“容器扫描”等）时，运行扫描前必须从文档中获取当前扫描选项。

如何处理扫描类型请求

1. 用户请求特定的扫描类型（例如，“运行快速扫描”“扫描机密信息”“运行 SAST”）

2. 自动获取文档，使用 WebFetch（不要征求许可——直接获取）：

   URL: https://docs.endorlabs.com/endorctl/commands/scan/
   Prompt: "Find the flag/option for [user's requested scan type] scan"
   

   注意：从 docs.endorlabs.com 获取内容时，应自动进行，无需提示用户确认。

3. 从文档中提取正确的标志（例如，--quick-scan、--secrets、--sast）

4. 使用相应的标志运行扫描

工作流示例

User: "Can you run a quick scan on this repo?"

Step 1: Fetch docs
→ WebFetch("https://docs.endorlabs.com/endorctl/commands/scan/", "Find the flag for quick scan")

Step 2: Extract flag from docs
→ Found: --quick-scan

Step 3: Run scan with flag
→ endorctl scan --namespace=$ENDOR_NAMESPACE --quick-scan

为什么始终要获取文档？

• 扫描选项和标志可能会随 endorctl 版本变化
• 可能会随着时间推移添加新的扫描类型
• 文档是当前选项的权威来源
• 避免使用过时或错误的标志

文档 URL

• 扫描选项参考：https://docs.endorlabs.com/endorctl/commands/scan/
• 主文档：https://docs.endorlabs.com

第 5 步：运行扫描

# Default scan (no specific type requested)
endorctl scan --namespace=$ENDOR_NAMESPACE

# With specific scan type (fetch flag from docs first!)
endorctl scan --namespace=$ENDOR_NAMESPACE <flags-from-docs>

重要提示：

1. 不要运行两次扫描，也不要询问用户是否要查看摘要——请在首次扫描命令中包含摘要。
2. 如果用户请求特定的扫描类型，务必先获取文档以找到正确的标志。
3. 不要猜测或假定标志名称——务必从文档中确认。

完整自动化设置

对于首次使用的用户：

1. 下载适用于当前操作系统的 endorctl（如果尚未安装）
2. 务必先询问用户的 ENDOR_NAMESPACE（身份验证需要此信息）
3. 进行身份验证：询问用户“CLI 身份验证还是 API 密钥？”
   • CLI 身份验证：询问使用哪种提供方（Google、GitHub、GitLab、Enterprise SSO、Browser），然后运行 endorctl init --auth-mode=<mode> --namespace=<namespace>（必须包含 namespace，以避免出现交互式提示）。对于 SSO，还要收集 --auth-tenant。
   • API 密钥：指导用户设置 ENDOR_API_CREDENTIALS_KEY 和 ENDOR_API_CREDENTIALS_SECRET 这些环境变量，然后导出它们
4. 运行 endorctl scan --namespace=<namespace>

对于回访用户（已完成身份验证）：

1. 检查安装和身份验证状态
2. 务必询问用户的 ENDOR_NAMESPACE（始终提供现有配置值作为建议）
3. 运行 endorctl scan --namespace=<namespace>

关键提醒：使用 Browser OAuth 运行 endorctl init 之前，必须先获取 namespace。这可以防止非交互式 Agent 环境中，在交互式租户选择提示处发生 EOF 错误。