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 段階プロセス）

重要 — マルチテナントの処理：複数のテナントにアクセスできるユーザーには、テナントを対話形式で選択するよう求められます。非対話型のエージェント環境では、これによって 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 コーディングエージェントのシェルツールでは、実行中のプロセスに対話形式で入力できないのが一般的です。タイムアウトを設定するとコマンドが終了し、エージェントが出力を解析してステップ 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 にパイプで渡します。これは <<< よりもシェル環境間の互換性が高く、2 回目の実行で対話形式のプロンプトを完全に回避できます。

認証が引き続き失敗する場合（例：ユーザーが指定された名前空間にアクセスできない場合）：

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回実行したり、概要を表示するかユーザーに尋ねたりしないでください。最初のスキャンコマンドに概要を含めます。
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を取得してください。これにより、非対話型のエージェント環境でテナント選択の対話型プロンプトによってEOFエラーが発生するのを防げます。