stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

docs: Archive Sprint 3500 (PoE), Sprint 7100 (Proof Moats), and additional sprints

Browse Source 
Archive completed sprint documentation and deliverables:

## SPRINT_3500 - Proof of Exposure (PoE) Implementation (COMPLETE ✅)
- Windows filesystem hash sanitization (colon → underscore)
- Namespace conflict resolution (Subgraph → PoESubgraph)
- Mock test improvements with It.IsAny<>()
- Direct orchestrator unit tests
- 8/8 PoE tests passing (100% success)
- Archived to: docs/implplan/archived/2025-12-23-sprint-3500-poe/

## SPRINT_7100.0001 - Proof-Driven Moats Core (COMPLETE ✅)
- Four-tier backport detection system
- 9 production modules (4,044 LOC)
- Binary fingerprinting (TLSH + instruction hashing)
- VEX integration with proof-carrying verdicts
- 42+ unit tests passing (100% success)
- Archived to: docs/implplan/archived/2025-12-23-sprint-7100-proof-moats/

## SPRINT_7100.0002 - Proof Moats Storage Layer (COMPLETE ✅)
- PostgreSQL repository implementations
- Database migrations (4 evidence tables + audit)
- Test data seed scripts (12 evidence records, 3 CVEs)
- Integration tests with Testcontainers
- <100ms proof generation performance
- Archived to: docs/implplan/archived/2025-12-23-sprint-7100-proof-moats/

## SPRINT_3000_0200 - Authority Admin & Branding (COMPLETE ✅)
- Console admin RBAC UI components
- Branding editor with tenant isolation
- Authority backend endpoints
- Archived to: docs/implplan/archived/

## Additional Documentation
- CLI command reference and compliance guides
- Module architecture docs (26 modules documented)
- Data schemas and contracts
- Operations runbooks
- Security risk models
- Product roadmap

All archived sprints achieved 100% completion of planned deliverables.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
master
2025-12-23 15:02:38 +02:00
parent fda92af9bc
commit b444284be5
77 changed files with 7673 additions and 556 deletions
Download Patch File Download Diff File Expand all files Collapse all files

820
docs/cli/troubleshooting.md Normal file
View File

@@ -0,0 +1,820 @@
# 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](#authentication-issues)
2. [Crypto Plugin Issues](#crypto-plugin-issues)
3. [Build Issues](#build-issues)
4. [Scanning Issues](#scanning-issues)
5. [Configuration Issues](#configuration-issues)
6. [Network Issues](#network-issues)
7. [Permission Issues](#permission-issues)
8. [Distribution Validation Issues](#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**
```bash
# 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**
```bash
# 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**
```bash
# 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)**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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**
```bash
# 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**
```bash
# 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)**
```yaml
# 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**
```bash
# 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**
```bash
# 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)**
```yaml
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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**
```bash
# Pull image from Docker registry
docker pull nginx:latest
# Then scan
stella scan docker://nginx:latest
```
**Solution 2: Scan local tar archive**
```bash
# Export image to tar
docker save nginx:latest -o nginx.tar
# Scan tar archive
stella scan tar://nginx.tar
```
**Solution 3: Specify registry explicitly**
```bash
# 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)**
```bash
stella admin feeds refresh --source nvd --force
stella admin feeds refresh --source osv --force
```
**Solution 2: Check feed status**
```bash
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**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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**
```yaml
# appsettings.yaml
StellaOps:
Backend:
Http:
TimeoutSeconds: 120 # Increase from 30 to 120
```
**Solution 2: Check network latency**
```bash
# Ping backend
ping api.stellaops.example.com
# Test HTTP latency
time curl -v https://api.stellaops.example.com/health
```
**Solution 3: Use proxy**
```bash
# 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**
```bash
# 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)**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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
```bash
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
```bash
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
```bash
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
```bash
# 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](README.md)
- [CLI Architecture](architecture.md)
- [Command Reference](command-reference.md)
- [Compliance Guide](compliance-guide.md)
2. **Enable Verbose Logging:**
```bash
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:
```bash
# 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:**
```bash
# 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:**
```bash
# 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](README.md) - Installation and quick start
- [CLI Architecture](architecture.md) - Plugin architecture
- [Command Reference](command-reference.md) - Command usage
- [Compliance Guide](compliance-guide.md) - Regional compliance
- [Distribution Matrix](distribution-matrix.md) - Build and distribution
- [Crypto Plugins](crypto-plugins.md) - Plugin development