git.stella-ops.org/docs/cli/troubleshooting.md

stella CLI - Troubleshooting Guide

Sprint: SPRINT_4100_0006_0006 - CLI Documentation Overhaul

Overview

This guide covers common issues encountered when using the stella CLI and their solutions. Issues are categorized by functional area for easy navigation.

---

Table of Contents

1. Authentication Issues
2. Crypto Plugin Issues
3. Build Issues
4. Scanning Issues
5. Configuration Issues
6. Network Issues
7. Permission Issues
8. Distribution Validation Issues

---

Authentication Issues

Problem: stella auth login fails with "Authority unreachable"

Symptoms:

$ stella auth login
❌ Error: Failed to connect to Authority
Authority URL: https://auth.stellaops.example.com
Error: Connection refused

Possible Causes:

1. Authority service is down
2. Network connectivity issues
3. Incorrect Authority URL in configuration
4. Firewall blocking connection

Solutions:

Solution 1: Verify Authority URL

# Check current Authority URL
stella config get Backend.BaseUrl

# If incorrect, set correct URL
stella config set Backend.BaseUrl https://api.stellaops.example.com

# Or set via environment variable
export STELLAOPS_BACKEND_URL="https://api.stellaops.example.com"

Solution 2: Test network connectivity

# Test if Authority is reachable
curl -v https://auth.stellaops.example.com/health

# Check DNS resolution
nslookup auth.stellaops.example.com

Solution 3: Enable offline cache fallback

# Allow offline cache fallback (uses cached tokens)
export STELLAOPS_AUTHORITY_ALLOW_OFFLINE_CACHE_FALLBACK=true
export STELLAOPS_AUTHORITY_OFFLINE_CACHE_TOLERANCE=00:30:00

stella auth login

Solution 4: Use API key authentication (bypass Authority)

# Use API key instead of interactive login
export STELLAOPS_API_KEY="sk_live_your_api_key"

stella auth whoami
# Output: Authenticated via API key

---

Problem: stella auth whoami shows "Token expired"

Symptoms:

$ stella auth whoami
❌ Error: Token expired
Expiration: 2025-12-22T10:00:00Z
Please re-authenticate with 'stella auth login'

Solution:

# Re-authenticate
stella auth login

# Or refresh token (if supported by Authority)
stella auth refresh

# Verify authentication
stella auth whoami

---

Problem: HTTP 403 "Insufficient scopes" when running admin commands

Symptoms:

$ stella admin policy export
❌ HTTP 403: Forbidden
Error: Insufficient scopes. Required: admin.policy
Your scopes: scan.read, scan.write

Solution:

# Re-authenticate to obtain admin scopes
stella auth logout
stella auth login

# Verify you have admin scopes
stella auth whoami
# Output should include: admin.policy, admin.users, admin.feeds, admin.platform

# If still missing scopes, contact your platform administrator
# to grant admin role to your account

---

Crypto Plugin Issues

Problem: stella crypto sign --provider gost fails with "Provider 'gost' not available"

Symptoms:

$ stella crypto sign --provider gost --file document.pdf
❌ Error: Crypto provider 'gost' not available
Available providers: default

Cause: You are using the International distribution which does not include GOST plugin.

Solution:

# Check which distribution you have
stella --version
# Output: stella CLI version 2.1.0
# Distribution: stella-international  <-- Problem!

# Download correct distribution for Russia/CIS
wget https://releases.stella-ops.org/cli/russia/latest/stella-russia-linux-x64.tar.gz
tar -xzf stella-russia-linux-x64.tar.gz
sudo cp stella /usr/local/bin/

# Verify GOST provider is available
stella crypto providers
# Output:
# - default (.NET Crypto, BouncyCastle)
# - gost (GOST R 34.10-2012)  <-- Now available

---

Problem: GOST signing fails with "CryptoPro CSP not initialized"

Symptoms:

$ stella crypto sign --provider gost --algorithm GOST12-256 --file document.pdf
❌ Error: CryptoPro CSP not initialized
Container: StellaOps-GOST-2024 not found

Causes:

1. CryptoPro CSP not installed
2. Container not created
3. Invalid provider configuration

Solutions:

Solution 1: Verify CryptoPro CSP installation

# Check if CryptoPro CSP is installed
/opt/cprocsp/bin/amd64/csptestf -absorb -alg GR3411_2012_256

# If not installed, install CryptoPro CSP
sudo ./install.sh  # From CryptoPro CSP distribution

Solution 2: Create GOST container

# Create new container
/opt/cprocsp/bin/amd64/csptest -keyset -newkeyset -container "StellaOps-GOST-2024"

# List containers
/opt/cprocsp/bin/amd64/csptest -keyset -enum_cont -verifycontext

# Update configuration to use correct container name
stella config set Crypto.Providers.Gost.CryptoProCsp.ContainerName "StellaOps-GOST-2024"

Solution 3: Use OpenSSL-GOST instead (development only)

# appsettings.yaml
StellaOps:
  Crypto:
    Providers:
      Gost:
        CryptoProCsp:
          Enabled: false  # Disable CryptoPro CSP
        OpenSslGost:
          Enabled: true   # Use OpenSSL-GOST

Warning: OpenSSL-GOST is NOT FSTEC-certified and should only be used for development/testing.

---

Problem: eIDAS signing fails with "TSP unreachable"

Symptoms:

$ stella crypto sign --provider eidas --algorithm ECDSA-P256-QES --file contract.pdf
❌ Error: Trust Service Provider unreachable
TSP URL: https://tsp.example.eu/api/v1/sign
HTTP Error: Connection refused

Solutions:

Solution 1: Verify TSP URL

# Test TSP connectivity
curl -v https://tsp.example.eu/api/v1/sign

# Update TSP URL if incorrect
stella config set Crypto.Providers.Eidas.TspClient.TspUrl "https://correct-tsp.eu/api/v1/sign"

Solution 2: Check API key

# Verify API key is set
echo $EIDAS_TSP_API_KEY

# If not set, export it
export EIDAS_TSP_API_KEY="your_api_key_here"

# Or set in configuration
stella config set Crypto.Providers.Eidas.TspClient.ApiKey "your_api_key_here"

Solution 3: Use local signer for AES (not QES)

# For Advanced Electronic Signatures (not qualified)
StellaOps:
  Crypto:
    Providers:
      Eidas:
        TspClient:
          Enabled: false
        LocalSigner:
          Enabled: true

---

Build Issues

Problem: Build fails with "DefineConstants 'STELLAOPS_ENABLE_GOST' not defined"

Symptoms:

$ dotnet build -p:StellaOpsEnableGOST=true
error CS0103: The name 'STELLAOPS_ENABLE_GOST' does not exist in the current context

Cause: Missing -p:DefineConstants flag.

Solution:

# Correct build command (includes both flags)
dotnet build \
  -p:StellaOpsEnableGOST=true \
  -p:DefineConstants="STELLAOPS_ENABLE_GOST"

# Or for publish:
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  -p:StellaOpsEnableGOST=true \
  -p:DefineConstants="STELLAOPS_ENABLE_GOST"

---

Problem: Build succeeds but crypto plugin not available at runtime

Symptoms:

# Build appears successful
$ dotnet build -p:StellaOpsEnableGOST=true -p:DefineConstants="STELLAOPS_ENABLE_GOST"
Build succeeded.

# But plugin not available
$ ./stella crypto providers
Available providers:
- default

# GOST plugin missing!

Cause: Plugin DLL not copied to output directory.

Solution:

# Use dotnet publish instead of dotnet build
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  -p:StellaOpsEnableGOST=true \
  -p:DefineConstants="STELLAOPS_ENABLE_GOST" \
  --output dist/stella-russia-linux-x64

# Verify GOST plugin DLL is present
ls dist/stella-russia-linux-x64/*.dll | grep Gost
# Expected: StellaOps.Cli.Crypto.Gost.dll

---

Problem: "GLIBC version not found" when running CLI on older Linux

Symptoms:

$ ./stella --version
./stella: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by ./stella)

Cause: CLI built with newer .NET runtime requiring newer GLIBC.

Solution:

# Check your GLIBC version
ldd --version
# If < 2.34, upgrade to a newer Linux distribution

# Or build with older .NET runtime (if possible)
# Or use containerized version:
docker run -it stellaops/cli:latest stella --version

---

Scanning Issues

Problem: stella scan fails with "Image not found"

Symptoms:

$ stella scan docker://nginx:latest
❌ Error: Image not found
Image: docker://nginx:latest

Solutions:

Solution 1: Pull image first

# Pull image from Docker registry
docker pull nginx:latest

# Then scan
stella scan docker://nginx:latest

Solution 2: Scan local tar archive

# Export image to tar
docker save nginx:latest -o nginx.tar

# Scan tar archive
stella scan tar://nginx.tar

Solution 3: Specify registry explicitly

# Use fully-qualified image reference
stella scan docker://docker.io/library/nginx:latest

---

Problem: Scan succeeds but no vulnerabilities found (expected some)

Symptoms:

$ stella scan docker://vulnerable-app:latest
Scan complete: 0 vulnerabilities found

Possible Causes:

1. Advisory feeds not synchronized
2. Offline mode with stale data
3. VEX mode filtering vulnerabilities

Solutions:

Solution 1: Refresh advisory feeds (admin)

stella admin feeds refresh --source nvd --force
stella admin feeds refresh --source osv --force

Solution 2: Check feed status

stella admin feeds status
# Output:
# Feed         Last Sync           Status
# ────────────────────────────────────────
# NVD          2025-12-23 10:00    ✅ UP
# OSV          2025-12-23 09:45    ⚠️  STALE (12 hours old)

Solution 3: Disable VEX filtering

# Scan with VEX mode disabled
stella scan docker://vulnerable-app:latest --vex-mode disabled

---

Configuration Issues

Problem: "Configuration file not found"

Symptoms:

$ stella config show
⚠️  Warning: No configuration file found
Using default configuration

Solution:

# Create user configuration directory
mkdir -p ~/.stellaops

# Create configuration file
cat > ~/.stellaops/config.yaml <<EOF
StellaOps:
  Backend:
    BaseUrl: "https://api.stellaops.example.com"
EOF

# Verify configuration is loaded
stella config show

---

Problem: Environment variables not overriding configuration

Symptoms:

$ export STELLAOPS_BACKEND_URL="https://test.example.com"
$ stella config get Backend.BaseUrl
https://api.stellaops.example.com  # Still shows old value!

Cause: Incorrect environment variable format.

Solution:

# Correct environment variable format (double underscore for nested properties)
export STELLAOPS_BACKEND__BASEURL="https://test.example.com"
#                        ^^ Note: double underscore

# Verify
stella config get Backend.BaseUrl
# Output: https://test.example.com  # Now correct

Environment Variable Format Rules:

• Prefix: STELLAOPS_
• Nested properties: Double underscore __
• Array index: Double underscore + index __0, __1, etc.

Examples:

# Simple property
export STELLAOPS_BACKEND__BASEURL="https://api.example.com"

# Nested property
export STELLAOPS_CRYPTO__DEFAULTPROVIDER="gost"

# Array element
export STELLAOPS_CRYPTO__PROVIDERS__GOST__KEYS__0__KEYID="key1"

---

Network Issues

Problem: Timeouts when connecting to backend

Symptoms:

$ stella scan docker://nginx:latest
❌ Error: Request timeout
Backend: https://api.stellaops.example.com/api/v1/scan
Timeout: 30s

Solutions:

Solution 1: Increase timeout

# appsettings.yaml
StellaOps:
  Backend:
    Http:
      TimeoutSeconds: 120  # Increase from 30 to 120

Solution 2: Check network latency

# Ping backend
ping api.stellaops.example.com

# Test HTTP latency
time curl -v https://api.stellaops.example.com/health

Solution 3: Use proxy

# Set HTTP proxy
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"

stella scan docker://nginx:latest

---

Problem: SSL certificate verification fails

Symptoms:

$ stella scan docker://nginx:latest
❌ Error: SSL certificate verification failed
Certificate: CN=api.stellaops.example.com
Error: The SSL certificate is invalid

Solutions:

Solution 1: Add CA certificate

# Add custom CA certificate (Linux)
sudo cp custom-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# Add custom CA certificate (macOS)
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain custom-ca.crt

Solution 2: Disable SSL verification (INSECURE - development only)

# WARNING: This disables SSL verification. Use only for testing!
export STELLAOPS_BACKEND__HTTP__DISABLESSLVERIFICATION=true

stella scan docker://nginx:latest

---

Permission Issues

Problem: "Permission denied" when running stella

Symptoms:

$ stella --version
bash: /usr/local/bin/stella: Permission denied

Solution:

# Make binary executable
chmod +x /usr/local/bin/stella

# Verify
stella --version

---

Problem: "Access denied" when accessing keys

Symptoms:

$ stella crypto sign --provider gost --file doc.pdf
❌ Error: Access denied to key file
File: /etc/stellaops/keys/gost-key.pem

Solution:

# Fix key file permissions
sudo chmod 600 /etc/stellaops/keys/gost-key.pem
sudo chown $(whoami):$(whoami) /etc/stellaops/keys/gost-key.pem

# Or run as root (not recommended)
sudo stella crypto sign --provider gost --file doc.pdf

---

Distribution Validation Issues

Problem: Validation script reports "wrong plugins included"

Symptoms:

$ ./validate-distribution.sh international dist/stella-international-linux-x64/stella
❌ FAIL: International distribution contains restricted plugins
Found: GostCryptoProvider

Cause: Built with wrong flags or flags not working.

Solution:

# Clean and rebuild without regional flags
dotnet clean
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  --output dist/stella-international-linux-x64

# Verify no build flags were set
echo "No StellaOpsEnableGOST, StellaOpsEnableEIDAS, or StellaOpsEnableSM flags"

# Re-validate
./validate-distribution.sh international dist/stella-international-linux-x64/stella
# Expected: ✅ PASS

---

Diagnostic Commands

Check CLI Version and Distribution

stella --version
# Output:
# stella CLI version 2.1.0
# Build: 2025-12-23T10:00:00Z
# Commit: dfaa207
# Distribution: stella-russia
# Platform: linux-x64
# .NET Runtime: 10.0.0

System Diagnostics

stella system diagnostics
# Output:
# System Diagnostics:
# ✅ CLI version: 2.1.0
# ✅ .NET Runtime: 10.0.0
# ✅ Backend reachable: https://api.stellaops.example.com
# ✅ Authentication: Valid (expires 2025-12-24)
# ✅ Crypto providers: default, gost
# ⚠️  PostgreSQL: Not configured (offline mode)

Check Available Crypto Providers

stella crypto providers --verbose
# Output:
# Available Crypto Providers:
#
# Provider: default
#   Description: .NET Crypto, BouncyCastle
#   Algorithms: ECDSA-P256, ECDSA-P384, EdDSA, RSA-2048, RSA-4096
#   Status: ✅ Healthy
#
# Provider: gost
#   Description: GOST R 34.10-2012, GOST R 34.11-2012
#   Algorithms: GOST12-256, GOST12-512, GOST2001
#   Status: ⚠️  CryptoPro CSP not initialized

Verbose Mode

# Enable verbose logging for all commands
stella --verbose <command>

# Example:
stella --verbose auth login
stella --verbose scan docker://nginx:latest
stella --verbose crypto sign --provider gost --file doc.pdf

---

Getting Help

If you're still experiencing issues after trying these solutions:

1. Check Documentation:

   • CLI Overview
   • CLI Architecture
   • Command Reference
   • Compliance Guide

2. Enable Verbose Logging:

   stella --verbose <command>
   

3. Check GitHub Issues:

   • https://git.stella-ops.org/stella-ops.org/git.stella-ops.org/issues

4. Community Support:

   • GitHub Discussions: https://github.com/stellaops/stellaops/discussions

5. Commercial Support:

   • Contact: support@stella-ops.org

---

Common Error Codes

Exit Code	Meaning	Typical Cause
0	Success	-
1	General error	Check error message
2	Policy violations	Scan found policy violations (with --fail-on-policy-violations)
3	Authentication error	Token expired or invalid credentials
4	Configuration error	Invalid configuration or missing required fields
5	Network error	Backend unreachable or timeout
10	Invalid arguments	Incorrect command usage or missing required arguments

---

Frequently Asked Questions (FAQ)

Q: How do I switch between crypto providers?

A: Use the --provider flag or create a crypto profile:

# Method 1: Use --provider flag
stella crypto sign --provider gost --file doc.pdf

# Method 2: Create and use profile
stella crypto profiles create my-gost --provider gost --algorithm GOST12-256
stella crypto profiles use my-gost
stella crypto sign --file doc.pdf  # Uses my-gost profile

Q: Can I use multiple regional plugins in one distribution?

A: No. Each distribution includes only one regional plugin (GOST, eIDAS, or SM) to comply with export control laws.

Q: How do I update the CLI?

A:

# If installed via .NET tool
dotnet tool update --global StellaOps.Cli

# If installed via binary download
wget https://releases.stella-ops.org/cli/latest/stella-<distribution>-<platform>.tar.gz
tar -xzf stella-<distribution>-<platform>.tar.gz
sudo cp stella /usr/local/bin/

Q: How do I enable offline mode?

A:

# Set offline mode
export STELLAOPS_OFFLINE_MODE=true

# Create offline package (admin)
stella offline sync --output stellaops-offline-$(date +%F).tar.gz

# Load offline package in air-gapped environment
stella offline load --package stellaops-offline-2025-12-23.tar.gz

---

See Also

• CLI Overview - Installation and quick start
• CLI Architecture - Plugin architecture
• Command Reference - Command usage
• Compliance Guide - Regional compliance
• Distribution Matrix - Build and distribution
• Crypto Plugins - Plugin development