endor-setup

Endorctl のセットアップとセキュリティスキャン

Endor Labs の操作を行う前に、endorctl がインストールされ、認証され、設定されていることを確認するための前提スキルです。

ワークフローの概要

ユーザーから endorctl のセットアップと基本的なスキャンの実行を依頼された場合は、次の手順に従います。

1. endorctl がインストールされているか確認する（ステップ 1）

   • インストールされていない場合 → ダウンロードしてインストールする（ステップ 2）
   • インストール済みだが認証されていない場合 → 名前空間を尋ねる（ステップ 3）、その後認証する（ステップ 4）
   • インストール済みで認証済みの場合 → 名前空間を尋ねる（ステップ 3）、その後スキャンを実行する

2. 認証の前に必ず名前空間を尋ねる（ステップ 3）— CLI 認証を非対話型環境で機能させるために、これは非常に重要です。対話型のテナント選択プロンプトを回避するため、名前空間を先に取得し、endorctl init --namespace=<namespace> に渡す必要があります。

3. 「command not found」で失敗しない — endorctl が見つからない場合は、必ずインストールします。

4. 重要な原則：積極的に対応してください。endorctl が見つからない場合は、ユーザー自身にインストールを依頼するのではなく、自動的にインストールします。

5. 名前空間の階層：ユーザーは親テナントまたは子名前空間（形式：parent.child）でスキャンできます。ユーザーが指定した名前空間は常に受け入れます。

6. アクセスエラー：ユーザーがテナント／名前空間にアクセスできない場合は、アクセス権がないことを明確に伝え、権限を確認するか、別の名前空間を試すよう提案します。

7. ドキュメントの自動取得：docs.endorlabs.com からスキャンオプションを取得する場合は、自動的に取得します。これは信頼できるドキュメントソースです。

8. 重要 — 非対話型環境：AI コーディングエージェントは、非対話型の 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 の実行を依頼し、endorctl がインストールされていない場合は、エラーを報告するだけにしてはいけません。代わりに、先にインストールするため、次のワークフローに従います。

次の確認をまとめて実行し、ユーザーの状態を判定します。

# 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 を使って、次の 2 つの選択肢を提示します。

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"

インストールの確認

コマンド間でシェルの状態は保持されないため、endorctl を使用する以降の Bash コマンドでは、毎回 export PATH="$HOME/bin:$PATH" を先頭に付ける必要があります（~/bin にインストールした場合）。

endorctl のインストール後、ダウンロードとインストールが成功したことを確認します。

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

このコマンドでバージョン情報が出力されれば、endorctl のダウンロードと検証は正常に完了しています。失敗した場合は、上記のインストール手順を再度実行してください。

Step 3: Namespace を確認する（常に必須）

重要：スキャンを実行する前に、設定ファイルに Namespace がすでに存在する場合でも、必ずユーザーに Endor Labs の Namespace を確認してください。

• 設定に Namespace が存在する場合は候補として提示しますが、必ず確認を求めてください
• 以前のセッションと同じ Namespace を使うと決めつけないでください
• ユーザーは毎回、別の Namespace（親または子）を対象にスキャンしたい場合があります

Namespace の階層構造

Endor Labs は階層型 Namespace（親／子構造）をサポートしています。

• 親テナント：最上位の Namespace（例：parent）
• 子 Namespace：親の下にある Namespace（例：parent.child-project）

ユーザーは次の Namespace に対してスキャンを実行できます。

• 親テナントの Namespace
• 親テナントの下にある任意の子 Namespace（形式：parent.child）

子 Namespace の使用例：

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

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

アクセスエラーの処理

重要：ユーザーがテナントまたは Namespace にアクセスできない場合、endorctl はアクセスエラーを返します。この場合は、次の対応を行います。

1. ユーザーにはっきり伝える：指定されたテナント／Namespace にアクセスできないことを伝えます
2. エラーメッセージを表示する：endorctl から返された実際のエラーを表示します
3. 代替案を提案する：
   • 別の Namespace を意図していたか確認します
   • Endor Labs UI で権限を確認するよう提案します
   • アクセス可能なテナントを一覧表示することを提案します
4. 公式ドキュメントを参照するよう提案する：Namespace とは何かを詳しく知るには、https://docs.endorlabs.com/administration/namespaces/ を参照するよう伝えます。 よくあるアクセスエラーのパターン：

• Invalid permissions to run endorctl - ユーザーに Namespace へのアクセス権がありません
• unauthorized または 403 エラー - 認証には成功しましたが、その Namespace への認可に失敗しました
• tenant not found - Namespace が存在しないか、ユーザーに表示する権限がありません

Namespace の設定

環境変数で設定します。

export ENDOR_NAMESPACE=<user-provided-namespace>

または、スキャンコマンドのフラグとして渡します。

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

Step 4: 認証する

重要：認証を実行する前に、Step 3 で Namespace を必ず確認しておく必要があります。これは、対話型プロンプトを避けるために必要です。

Step 4a: 認証方法を確認する

AskUserQuestion を使用して、次の 2 つの選択肢をユーザーに提示します。

1. CLI 認証（推奨） - ID プロバイダー（Google、GitHub、GitLab、SSO など）を使ってブラウザーからサインインします
2. API キー - 自動化／CI 環境で API キーとシークレットを使用します（ブラウザーは不要です）

Option 1: CLI 認証

ステップ 4b：認証プロバイダーを確認する

ユーザーが CLI 認証を選択した場合は、使用している ID プロバイダーを確認します。AskUserQuestion を使用して、以下の選択肢を提示します。

1. Google - Google でサインイン
2. GitHub - GitHub でサインイン
3. GitLab - GitLab でサインイン
4. Enterprise SSO - 組織の SSO プロバイダー経由でサインイン（テナント名が必要です）
5. Browser (generic) - 汎用ブラウザー経由でサインイン

ユーザーの選択に応じて、対応する --auth-mode の値を使用します。

プロバイダー	--auth-mode の値	追加フラグ
Google	google	なし
GitHub	github	なし
GitLab	gitlab	なし
Enterprise SSO	sso	--auth-tenant <tenant-name>
Browser (generic)	browser-auth	なし

Enterprise SSO の場合のみ：ユーザーが SSO を選択した後、SSO テナント名も確認します。

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

ステップ 4c：認証を実行する（CLI 認証の 2 段階プロセス）

重要 - マルチテナントへの対応：複数のテナントにアクセスできるユーザーには、対話形式でテナントの選択が求められます。Claude Code のような非対話型環境では、これにより 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 コーディングエージェント（Cursor、Claude Code など）のシェルツールでは、実行中のプロセスに対話形式で入力できません。タイムアウトを設定するとコマンドが終了するため、エージェントは出力を解析してステップ 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：テナント番号をパイプで渡して再実行する

取得した出力を解析し、ユーザーが指定した namespace に一致するテナント番号を見つけます。テナント番号は、namespace 名を含む行の : の前にある番号です。

# 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 にパイプで渡します。これは <<< よりもさまざまなシェル環境で移植性が高く、2 回目の実行時に対話形式のプロンプトを完全に回避できます。

認証に失敗する場合（例：指定した namespace へのアクセス権がない場合）：

1. エラーメッセージを明確に表示します
2. 出力に含まれる利用可能なテナント一覧を表示します
3. その namespace へのアクセス権があるか確認するか、一覧から選択するようユーザーに依頼します

オプション 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 回実行したり、概要を表示するかユーザーに尋ねたりしないでください。最初のスキャンコマンドに概要を含めてください。
2. ユーザーが特定のスキャンタイプをリクエストした場合は、適切なフラグを確認するため、必ず最初にドキュメントを取得してください。
3. フラグ名を推測したり、決めつけたりしないでください。必ずドキュメントで確認してください。

セットアップの全自動化

初めて利用するユーザーの場合：

1. 現在の OS 用の 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 を確認してください。これにより、Claude Code のような非対話型環境で、テナント選択の対話形式プロンプトによる EOF エラーを防げます。