endor-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Endorctl Setup and Security Scan

Endorctl 安装与安全扫描

Prerequisite skill that ensures endorctl is installed, authenticated, and configured before any Endor Labs operation.

这是一项前置技能，确保在执行任何Endor Labs操作前，endorctl已完成安装、认证和配置。

Workflow Overview

工作流程概述

When the user asks to set up endorctl and run basic scan, follow this sequence:

Check if endorctl is installed (Step 1)
- If NOT installed → Download and install it (Step 2)
- If installed but NOT authenticated → Ask for namespace (Step 3), then Authenticate (Step 4)
- If installed AND authenticated → Ask for namespace (Step 3), then run scan
ALWAYS ask for namespace BEFORE authentication (Step 3) - This is CRITICAL for CLI authentication to work in non-interactive environments. The namespace must be collected first so it can be passed to
```
endorctl init --namespace=<namespace>
```
to avoid interactive tenant selection prompts.
Never fail with "command not found" - always install endorctl if missing
Key principle: Be proactive. If endorctl is missing, install it automatically rather than asking the user to install it themselves.
Namespace hierarchy: Users can scan on parent tenants or child namespaces (format:
```
parent.child
```
). Always accept the namespace the user provides.
Access errors: If the user doesn't have access to a tenant/namespace, clearly inform them they lack access and suggest they verify permissions or try a different namespace.
Auto-fetch documentation: When fetching scan options from
```
docs.endorlabs.com
```
, fetch it automatically. This is a trusted documentation source.
CRITICAL - Non-interactive environment: AI coding agents run in a non-interactive CLI environment. Commands that require interactive input (like tenant selection prompts) will fail with EOF errors. Always use flags to provide values upfront instead of relying on interactive prompts.
Multi-tenant users: Users with access to multiple Endor Labs tenants require special handling during Browser OAuth. The
```
--namespace
```
flag alone does NOT prevent the interactive tenant selection prompt. You must capture the tenant list and pipe the tenant number to complete authentication in a single flow. See Step 4 for details.

当用户要求设置endorctl并执行基础扫描时，请遵循以下步骤：

检查endorctl是否已安装（步骤1）
- 若未安装 → 下载并安装（步骤2）
- 若已安装但未认证 → 询问命名空间（步骤3），然后进行认证（步骤4）
- 若已安装且已认证 → 询问命名空间（步骤3），然后执行扫描
认证前务必询问命名空间（步骤3）- 这对于非交互式环境下的CLI认证正常运行至关重要。必须先收集命名空间，再将其传入
```
endorctl init --namespace=<namespace>
```
，以避免出现交互式租户选择提示。
绝不能因“command not found”报错 - 若缺失endorctl，始终自动安装
核心原则：主动处理。若缺失endorctl，自动为用户安装，而非要求用户自行安装。
命名空间层级：用户可在父租户或子命名空间（格式：
```
parent.child
```
）下执行扫描。始终接受用户提供的命名空间。
访问错误处理：若用户无对应租户/命名空间的访问权限，需清晰告知用户权限不足，并建议其验证权限或尝试其他命名空间。
自动获取文档：从
```
docs.endorlabs.com
```
获取扫描选项时，需自动完成。该来源为官方可信文档。
关键注意事项 - 非交互式环境：AI编码Agent运行于非交互式CLI环境。需要交互式输入的命令（如租户选择提示）会因EOF错误失败。请始终使用参数提前传入所需值，而非依赖交互式提示。
多租户用户：拥有多个Endor Labs租户访问权限的用户在浏览器OAuth认证时需特殊处理。仅使用
```
--namespace
```
参数无法避免交互式租户选择提示。必须捕获租户列表，并传入对应租户编号以完成单流程认证。详情见步骤4。

Defaults

默认配置

Use the API endpoint from the existing config file if present. If no config exists, default to production:

bash

undefined

若存在现有配置文件，则使用其中的API端点；若不存在配置文件，则默认使用生产环境：

bash

undefined

If config exists, use its ENDOR_API value; otherwise default to production

若存在配置文件，使用其ENDOR_API值；否则默认使用生产环境

export ENDOR_API=${ENDOR_API:-https://api.endorlabs.com}

undefined

export ENDOR_API=${ENDOR_API:-https://api.endorlabs.com}

undefined

Step 1: Check Installation AND Existing Authentication

步骤1：检查安装状态与已有的认证信息

IMPORTANT: If the user asks to run endorctl scan and it's not installed, do NOT just report an error. Instead, follow this workflow to install it first.

Run these checks together to determine the user's state:

bash

undefined

重要提示：若用户要求运行endorctl扫描但工具未安装，请勿仅报错。请遵循以下流程先完成安装。

同时执行以下检查以确定当前状态：

bash

undefined

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


**Decision tree based on results:**
- If `NOT_INSTALLED`: Immediately go to Step 2 (Download) - DO NOT ask the user, just proceed with installation
- If `CONFIG_EXISTS`: User is already authenticated → The `ENDOR_API` has been extracted using the grep command above. Go to Step 3 (Ask for Namespace). **Do NOT run `cat` on the config file.**
- If `NOT_AUTHENTICATED`: Go to Step 4 (Authenticate), then Step 3 (Ask for Namespace)

**CRITICAL**: The config file check is ONLY to determine if authentication is already set up. Even if a namespace exists in the config, you MUST still ask the user which namespace they want to use before running the scan. Never assume the namespace from the config file.

if [ -f ~/.endorctl/config.yaml ]; then echo "CONFIG_EXISTS"

从配置文件中提取ENDOR_API（请勿输出完整配置文件内容）


**基于检查结果的决策树**：
- 若返回`NOT_INSTALLED`：立即进入步骤2（下载）- 无需询问用户，直接执行安装
- 若返回`CONFIG_EXISTS`：用户已完成认证 → 已通过grep命令提取`ENDOR_API`。进入步骤3（询问命名空间）。**请勿执行`cat`命令查看配置文件。**
- 若返回`NOT_AUTHENTICATED`：进入步骤4（认证），然后进入步骤3（询问命名空间）

**重要提示**：配置文件检查仅用于判断是否已完成认证。即使配置文件中存在命名空间，执行扫描前仍必须询问用户要使用哪个命名空间。切勿直接使用配置文件中的命名空间。

Step 2: Download endorctl (REQUIRED if NOT_INSTALLED)

步骤2：下载endorctl（未安装时必须执行）

When to execute: Automatically execute this step if Step 1 shows "NOT_INSTALLED".

执行时机：若步骤1返回“NOT_INSTALLED”，自动执行此步骤。

macOS Installation (ASK USER TO CHOOSE)

macOS安装（请让用户选择）

IMPORTANT: On macOS, ALWAYS ask the user which installation method they prefer before proceeding:

Present these two options using AskUserQuestion:

Homebrew (Recommended) - Uses
```
brew tap endorlabs/tap && brew install endorctl
```
. Easier to update later.
Direct Download - Downloads binary directly from api.endorlabs.com. No Homebrew required.

重要提示：在macOS系统上，执行前务必询问用户偏好的安装方式：

通过AskUserQuestion提供以下两个选项：

Homebrew（推荐） - 使用
```
brew tap endorlabs/tap && brew install endorctl
```
。后续更新更便捷。
直接下载 - 从api.endorlabs.com直接下载二进制文件。无需安装Homebrew。

Option 1: Homebrew Installation (macOS)

选项1：Homebrew安装（macOS）

bash

brew tap endorlabs/tap
brew install endorctl

bash

brew tap endorlabs/tap
brew install endorctl

Option 2: Direct Download Installation (macOS)

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

bash

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

bash

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

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

安装至~/bin

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

undefined

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

undefined

Linux/Windows Installation (Automatic)

Linux/Windows安装（自动执行）

For Linux and Windows, proceed with direct download automatically:

bash

#!/bin/bash
set -e

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

对于Linux和Windows系统，自动执行直接下载：

bash

#!/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"

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

构建下载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"

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)

设置可执行权限（.exe文件无需此操作）

if [ "$OS" != "windows" ]; then chmod +x "./$OUTPUT" fi

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


After download completes, move the binary to PATH:
```bash

if [ "$OS" != "windows" ]; then chmod +x "./$OUTPUT" fi

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


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

Install to ~/bin

安装至~/bin

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

undefined

mkdir -p ~/bin mv endorctl ~/bin/ # Windows系统为endorctl.exe export PATH="$HOME/bin:$PATH"

undefined

Verify Installation

验证安装

Since shell state does not persist between commands, you MUST prefix

export PATH="$HOME/bin:$PATH"

in every subsequent Bash command that uses

endorctl

(if it was installed to

~/bin

After installing endorctl, verify that the download and installation succeeded:

bash

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

If this command prints the version information, endorctl has been downloaded and verified successfully. If it fails, retry the installation steps above.

由于Shell状态不会在命令间持久化，若将endorctl安装至

~/bin

，后续所有使用

endorctl

的Bash命令前必须添加

export PATH="$HOME/bin:$PATH"

前缀。

安装完成后，验证下载与安装是否成功：

bash

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

若该命令输出版本信息，则说明endorctl已成功下载并验证。若失败，请重新执行上述安装步骤。

Step 3: Ask for Namespace (ALWAYS REQUIRED)

步骤3：询问命名空间（必须执行）

IMPORTANT: ALWAYS ask the user for their Endor Labs namespace before running a scan, even if a namespace already exists in the config file.

If a namespace exists in the config, offer it as a suggestion but still ask for confirmation
Never assume the user wants to use the same namespace from a previous session
The user may want to scan against a different namespace (parent or child) each time

重要提示：执行扫描前必须询问用户的Endor Labs命名空间，即使配置文件中已存在命名空间。

若配置文件中存在命名空间，可将其作为建议提供，但仍需用户确认
切勿假设用户希望使用上一会话的同名命名空间
用户可能每次需要在不同的命名空间（父或子）下执行扫描

Namespace Hierarchy

命名空间层级

Endor Labs supports hierarchical namespaces (parent/child structure):

Parent tenant: The top-level namespace (e.g.,
```
parent
```
)
Child namespace: A sub-namespace under a parent (e.g.,
```
parent.child-project
```
)

Users can run scans on:

Their parent tenant namespace
Any child namespace under their parent tenant (format:
```
parent.child
```
)

Example child namespace usage:

bash

undefined

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

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

用户可在以下层级执行扫描：

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

子命名空间使用示例：

bash

undefined

Scan using parent namespace

使用父命名空间执行扫描

endorctl scan --namespace=parent

Scan using child namespace

使用子命名空间执行扫描

endorctl scan --namespace=parent.my-project

undefined

endorctl scan --namespace=parent.my-project

undefined

Access Error Handling

访问错误处理

IMPORTANT: If the user does not have access to a tenant or namespace, endorctl will return an access error. When this happens:

Inform the user clearly: Tell them they do not have access to the specified tenant/namespace
Show the error message: Display the actual error from endorctl
Suggest alternatives:
- Ask if they meant a different namespace
- Suggest they check their permissions in the Endor Labs UI
- Offer to list available tenants they have access to
Suggest to visit official documentation: Tell them to visit https://docs.endorlabs.com/administration/namespaces/ to know more details on what is a namespace. Common access error patterns:

```
Invalid permissions to run endorctl
```
- User lacks access to the namespace
```
unauthorized
```
or
```
403
```
errors - Authentication succeeded but authorization failed for that namespace
```
tenant not found
```
- The namespace doesn't exist or user has no visibility to it

重要提示：若用户无对应租户或命名空间的访问权限，endorctl会返回访问错误。此时：

清晰告知用户：告知用户其无对应租户/命名空间的访问权限
显示错误信息：展示endorctl返回的具体错误信息
提供替代建议：
- 询问用户是否输入了错误的命名空间
- 建议用户在Endor Labs UI中检查权限
- 提供列出用户有权访问的租户的选项
建议查看官方文档：告知用户访问https://docs.endorlabs.com/administration/namespaces/以了解命名空间的详细信息。常见访问错误类型：

```
Invalid permissions to run endorctl
```
- 用户无该命名空间的访问权限
```
unauthorized
```
或
```
403
```
错误 - 认证成功但该命名空间授权失败
```
tenant not found
```
- 该命名空间不存在或用户无访问权限

Setting the Namespace

设置命名空间

Set via environment variable:

bash

export ENDOR_NAMESPACE=<user-provided-namespace>

Or pass as flag in scan command:

bash

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

通过环境变量设置：

bash

export ENDOR_NAMESPACE=<user-provided-namespace>

或在扫描命令中通过参数传入：

bash

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

Step 4: Authenticate

步骤4：认证

IMPORTANT: You must have already collected the namespace in Step 3 BEFORE running authentication. This is required to avoid interactive prompts.

重要提示：执行认证前必须已在步骤3中收集到命名空间。这是避免交互式提示的必要条件。

Step 4a: Ask Authentication Method

步骤4a：询问认证方式

Ask the user using AskUserQuestion with two options:

CLI Authentication (Recommended) - Sign in via browser using your identity provider (Google, GitHub, GitLab, SSO, etc.)
API Key - Use API key and secret for automated/CI environments (no browser needed)

通过AskUserQuestion询问用户，提供以下两个选项：

CLI认证（推荐） - 通过浏览器使用身份提供商（Google、GitHub、GitLab、SSO等）登录
API密钥 - 使用API密钥和密钥密文进行自动化/CI环境认证（无需浏览器）

Option 1: CLI Authentication

选项1：CLI认证

Step 4b: Ask for Auth Provider

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

If the user selects CLI Authentication, ask which identity provider they use. Present these options using AskUserQuestion:

Google - Sign in with Google
GitHub - Sign in with GitHub
GitLab - Sign in with GitLab
Enterprise SSO - Sign in via your organization's SSO provider (requires tenant name)
Browser (generic) - Generic browser-based sign-in

Based on the user's selection, use the corresponding

--auth-mode

value:

Provider	`--auth-mode` value	Additional Flags
Google	`google`	None
GitHub	`github`	None
GitLab	`gitlab`	None
Enterprise SSO	`sso`	`--auth-tenant <tenant-name>`
Browser (generic)	`browser-auth`	None

For Enterprise SSO only: After the user selects SSO, also ask them for their SSO tenant name:

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

若用户选择CLI认证，询问其使用的身份提供商。通过AskUserQuestion提供以下选项：

Google - 使用Google登录
GitHub - 使用GitHub登录
GitLab - 使用GitLab登录
企业SSO - 通过组织的SSO提供商登录（需租户名称）
浏览器（通用） - 通用浏览器登录

根据用户选择，使用对应的

--auth-mode

值：

提供商	`--auth-mode` 值	额外参数
Google	`google`	无
GitHub	`github`	无
GitLab	`gitlab`	无
企业SSO	`sso`	`--auth-tenant <tenant-name>`
浏览器（通用）	`browser-auth`	无

仅企业SSO需注意：用户选择SSO后，还需询问其SSO租户名称：

"请输入您的SSO租户名称？（将用于--auth-tenant参数）"

Step 4c: Run Authentication (Two-Step Process for CLI Authentication)

步骤4c：执行认证（CLI认证分两步）

CRITICAL - Multi-Tenant Handling: Users with access to multiple tenants will be prompted to select a tenant interactively. In non-interactive environments (like Claude Code), this causes an EOF error. The

--namespace

flag alone does NOT prevent this prompt. This applies to ALL browser-based auth modes.

Construct the

AUTH_FLAGS

based on the user's provider selection:

bash

undefined

关键注意事项 - 多租户处理：拥有多个租户访问权限的用户会收到交互式租户选择提示。在非交互式环境（如Claude Code）中，这会导致EOF错误。仅使用

--namespace

参数无法避免该提示。此规则适用于所有基于浏览器的认证模式。

根据用户选择的提供商构建

AUTH_FLAGS

：

bash

undefined

Set AUTH_FLAGS based on user's provider selection

根据用户选择的提供商设置AUTH_FLAGS

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>"

企业SSO: AUTH_FLAGS="--auth-mode=sso --auth-tenant=<tenant-name>"

Browser (generic): AUTH_FLAGS="--auth-mode=browser-auth"

浏览器（通用）: AUTH_FLAGS="--auth-mode=browser-auth"


**Step 4c-i: Initiate brower oauth and capture tenant list**

Run init and capture output — this will open the browser for OAuth. After browser auth completes, it will show a tenant list if the user has multiple tenants:
```bash


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

执行init命令并捕获输出 — 这将打开浏览器进行OAuth认证。浏览器认证完成后，若用户拥有多个租户，会显示租户列表：
```bash

Run init and capture output (opens browser for OAuth)

执行init命令并捕获输出（打开浏览器进行OAuth）

endorctl init $AUTH_FLAGS --namespace=<user-provided-namespace> 2>&1 | tee /tmp/endorctl_init_output.txt


If the command fails with EOF error and shows a tenant list like:

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:


**Step 4c-ii: Re-run with tenant number piped in**
Parse the output to find the tenant number matching the user's requested namespace, then:
```bash

endorctl init $AUTH_FLAGS --namespace=<user-provided-namespace> 2>&1 | tee /tmp/endorctl_init_output.txt


若命令因EOF错误失败并显示如下租户列表：


**步骤4c-ii：传入租户编号重新执行**
解析输出以找到与用户请求的命名空间对应的租户编号，然后执行：
```bash

Find the line number for the user's namespace and pipe it

找到用户命名空间对应的行号并传入

Example: if user wants "parent" and it's option 18:

示例：若用户需要"parent"且对应选项为18：

endorctl init $AUTH_FLAGS --namespace=<user-provided-namespace> 2>&1 <<< "<tenant-number>"


**If authentication still fails** (e.g., user doesn't have access to the specified namespace):

1. Show the error message clearly
2. Show the list of available tenants from the output
3. Ask the user to verify they have access to that namespace or choose from the list

endorctl init $AUTH_FLAGS --namespace=<user-provided-namespace> 2>&1 <<< "<tenant-number>"


**若认证仍失败**（例如：用户无该命名空间的访问权限）：

1. 清晰展示错误信息
2. 展示输出中的可用租户列表
3. 询问用户验证其是否拥有该命名空间的访问权限，或从列表中选择其他租户

Option 2: API Key (automated/CI)

选项2：API密钥（自动化/CI环境）

Instruct the user to set these environment variables themselves (never ask them to paste credentials into chat):

bash

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

No init needed - scan will use these credentials directly.

Note: API Key authentication avoids interactive prompts entirely and works best in automated/CLI environments. This is the recommended approach for users who frequently encounter multi-tenant selection issues.

指导用户自行设置以下环境变量（切勿要求用户在聊天中粘贴凭证）：

bash

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

无需执行init命令 — 扫描将直接使用这些凭证。

注意：API密钥认证完全避免了交互式提示，最适合自动化/CLI环境。对于经常遇到多租户选择问题的用户，推荐使用此方式。

Scan Types and Options (ALWAYS FETCH FROM DOCS)

扫描类型与选项（必须从文档获取）

IMPORTANT: When the user requests a specific type of scan (e.g., "quick scan", "secrets scan", "SAST scan", "container scan", etc.), you MUST fetch the current scan options from the documentation before running the scan.

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

How to Handle Scan Type Requests

处理扫描类型请求的流程

User requests a specific scan type (e.g., "run a quick scan", "scan for secrets", "run SAST")
Fetch documentation automatically using WebFetch (do NOT ask for permission - just fetch):
```
URL: https://docs.endorlabs.com/endorctl/commands/scan/
Prompt: "Find the flag/option for [user's requested scan type] scan"
```
Note: Fetching from docs.endorlabs.com should be done automatically without prompting the user for confirmation.
Extract the correct flag from the documentation (e.g.,
```
--quick-scan
```
,
```
--secrets
```
,
```
--sast
```
)
Run the scan with the appropriate flag(s)

用户请求特定扫描类型（例如：“对这个仓库执行快速扫描”、“扫描密钥”、“运行SAST”）
自动获取文档使用WebFetch（无需询问用户许可，直接获取）：
```
URL: https://docs.endorlabs.com/endorctl/commands/scan/
Prompt: "查找[用户请求的扫描类型]对应的参数/选项"
```
注意：从docs.endorlabs.com获取文档时，无需用户确认，自动执行。
从文档中提取正确的参数（例如：
```
--quick-scan
```
、
```
--secrets
```
、
```
--sast
```
）
使用对应参数执行扫描

Example Workflow

示例流程

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

用户：“能对这个仓库执行快速扫描吗？”

步骤1：获取文档
→ WebFetch("https://docs.endorlabs.com/endorctl/commands/scan/", "查找快速扫描对应的参数")

步骤2：从文档中提取参数
→ 找到：--quick-scan

步骤3：使用参数执行扫描
→ endorctl scan --namespace=$ENDOR_NAMESPACE --quick-scan

Why Always Fetch?

为何必须从文档获取？

Scan options and flags may change between endorctl versions
New scan types may be added over time
Documentation is the source of truth for current options
Avoids using outdated or incorrect flags

不同版本的endorctl，扫描选项和参数可能会变化
可能会新增扫描类型
文档是当前选项的权威来源
避免使用过时或错误的参数

Documentation URLs

文档URL

Scan options reference: https://docs.endorlabs.com/endorctl/commands/scan/
Main docs: https://docs.endorlabs.com

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

Step 5: Run Scan

步骤5：执行扫描

bash

undefined

bash

undefined

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>


**IMPORTANT**:

1. Do NOT run the scan twice or ask the user if they want to see a summary - include it in the initial scan command.
2. If user requests a specific scan type, ALWAYS fetch the documentation first to get the correct flag.
3. Do NOT guess or assume flag names - always verify from docs.

endorctl scan --namespace=$ENDOR_NAMESPACE <flags-from-docs>


**重要提示**：

1. 请勿重复执行扫描，也无需询问用户是否需要查看摘要 — 初始扫描命令中已包含相关内容。
2. 若用户请求特定扫描类型，必须先获取文档以确认正确参数。
3. 切勿猜测参数名称 — 始终从文档中验证。

Full Automated Setup

完整自动化设置

For first-time users:

Download endorctl for the current OS (if not installed)
ALWAYS ask user for their ENDOR_NAMESPACE first (this is needed for authentication)
Authenticate: Ask user "CLI Authentication or API Key?"
- CLI Auth: Ask which provider (Google, GitHub, GitLab, Enterprise SSO, Browser), then run
```
endorctl init --auth-mode=<mode> --namespace=<namespace>
```
  (MUST include namespace to avoid interactive prompts). For SSO, also collect
```
--auth-tenant
```
  .
- API Key: Instruct the user to set these environment variables, ENDOR_API_CREDENTIALS_KEY and ENDOR_API_CREDENTIALS_SECRET, then export them
Run
```
endorctl scan --namespace=<namespace>
```

For returning users (already authenticated):

Check installation and authentication status
ALWAYS ask user for their ENDOR_NAMESPACE (always offer existing config value as suggestion)
Run
```
endorctl scan --namespace=<namespace>
```

CRITICAL REMINDER: The namespace MUST be collected BEFORE running

endorctl init

with Browser OAuth. This prevents EOF errors from interactive tenant selection prompts in non-interactive environments like Claude Code.

首次使用用户：

为当前系统下载endorctl（若未安装）
必须先询问用户的ENDOR_NAMESPACE（这是认证的必要条件）
认证：询问用户“CLI认证还是API密钥？”
- CLI认证：询问提供商（Google、GitHub、GitLab、企业SSO、浏览器），然后执行
```
endorctl init --auth-mode=<mode> --namespace=<namespace>
```
  （必须包含命名空间以避免交互式提示）。若为SSO，还需收集
```
--auth-tenant
```
  参数。
- API密钥：指导用户设置ENDOR_API_CREDENTIALS_KEY和ENDOR_API_CREDENTIALS_SECRET环境变量并导出
执行
```
endorctl scan --namespace=<namespace>
```

返回用户（已认证）：

检查安装与认证状态
必须询问用户的ENDOR_NAMESPACE（可将现有配置值作为建议提供）
执行
```
endorctl scan --namespace=<namespace>
```

关键提醒：使用浏览器OAuth执行

endorctl init

前，必须先收集命名空间。这可避免在Claude Code等非交互式环境中因交互式租户选择提示导致的EOF错误。