endor-setup

Endorctl Setup and Security Scan

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

Workflow Overview

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

1. 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

2. 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.

3. Never fail with "command not found" - always install endorctl if missing

4. Key principle: Be proactive. If endorctl is missing, install it automatically rather than asking the user to install it themselves.

5. Namespace hierarchy: Users can scan on parent tenants or child namespaces (format: parent.child). Always accept the namespace the user provides.

6. 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.

7. Auto-fetch documentation: When fetching scan options from docs.endorlabs.com, fetch it automatically. This is a trusted documentation source.

8. 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.

9. 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.

Defaults

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

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

Step 1: Check Installation AND Existing Authentication

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:

# 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.

Step 2: Download endorctl (REQUIRED if NOT_INSTALLED)

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

macOS Installation (ASK USER TO CHOOSE)

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

Present these two options using AskUserQuestion:

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

Option 1: Homebrew Installation (macOS)

brew tap endorlabs/tap
brew install endorctl

Option 2: Direct Download Installation (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 Installation (Automatic)

For Linux and Windows, proceed with direct download automatically:

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

After download completes, move the binary to PATH:

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

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:

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.

Step 3: Ask for Namespace (ALWAYS REQUIRED)

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

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:

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

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

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:

1. Inform the user clearly: Tell them they do not have access to the specified tenant/namespace
2. Show the error message: Display the actual error from endorctl
3. 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
4. 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

Setting the Namespace

Set via environment variable:

export ENDOR_NAMESPACE=<user-provided-namespace>

Or pass as flag in scan command:

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

Step 4: Authenticate

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

Step 4a: Ask Authentication Method

Ask the user using AskUserQuestion with two options:

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

Option 1: CLI Authentication

Step 4b: Ask for Auth Provider

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

1. **Google

---

Content truncated.