endor-setup

What this skill does

# 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:
```bash
# 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:
```bash
# 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)
```bash
brew tap endorlabs/tap
brew install endorctl
```

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

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

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

# 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:
```bash
# 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:
```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.

## 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:
```bash
# Scan using parent namespace
endor