git.stella-ops.org/docs/cli

stella CLI - Overview and Quick Start

Sprint: SPRINT_4100_0006_0006 - CLI Documentation Overhaul

Overview

stella is the unified command-line interface for StellaOps, a self-hostable, sovereign container-security platform. It provides vulnerability scanning, SBOM generation, cryptographic signing, policy management, and platform administration capabilities.

Key Features:

• Vulnerability Scanning: Container image scanning with VEX-first decisioning
• SBOM Generation: SPDX 3.0.1 and CycloneDX 1.6 support
• Cryptographic Compliance: Regional crypto support (GOST, eIDAS, SM algorithms)
• Platform Administration: User, policy, and feed management
• Offline-first: Air-gapped operation support
• Multi-tenant: Tenant isolation and RBAC

---

Quick Start

Installation

Option 1: .NET Tool (Recommended)

# Install globally as .NET tool
dotnet tool install --global StellaOps.Cli

# Verify installation
stella --version

Option 2: Binary Download

# Download for your platform
wget https://releases.stella-ops.org/cli/latest/stella-linux-x64.tar.gz
tar -xzf stella-linux-x64.tar.gz
sudo mv stella /usr/local/bin/

# Verify installation
stella --version

Option 3: Package Managers

# Debian/Ubuntu
sudo apt install stellaops-cli

# RHEL/CentOS
sudo yum install stellaops-cli

# macOS (Homebrew)
brew install stella-ops/tap/stella

First-time Setup

1. Configure Backend URL

# Set backend API URL
export STELLAOPS_BACKEND_URL="https://api.stellaops.example.com"

# Or create config file
mkdir -p ~/.stellaops
cat > ~/.stellaops/config.yaml <<EOF
StellaOps:
  Backend:
    BaseUrl: "https://api.stellaops.example.com"
EOF

2. Authenticate

# Interactive login (recommended)
stella auth login

# Or use API key
export STELLAOPS_API_KEY="your-api-key"
stella auth whoami

3. Run Your First Scan

# Scan a container image
stella scan docker://nginx:latest --output scan-result.json

# View SBOM
stella scan docker://nginx:latest --sbom-only --format spdx --output nginx.spdx.json

# Generate attestation
stella scan docker://nginx:latest --attestation --output nginx.att.jsonl

---

Command Categories

Scanning & Analysis

Command	Description
stella scan	Scan container images for vulnerabilities
stella aoc	Generate Attestation of Compliance
stella symbols	Extract and index debug symbols

Example:

# Comprehensive scan with attestation
stella scan docker://myapp:v1.2.3 \
  --sbom-format spdx \
  --attestation \
  --vex-mode strict \
  --output scan-results/

Cryptography & Compliance

Command	Description
stella crypto providers	List available crypto providers
stella crypto sign	Sign files with regional crypto algorithms
stella crypto verify	Verify signatures
stella crypto profiles	Manage crypto profiles

Example (GOST signing in Russia distribution):

# Sign a document with GOST algorithm
stella crypto sign \
  --provider gost \
  --key-id key-gost-2012 \
  --algorithm GOST12-256 \
  --file document.pdf \
  --output document.pdf.sig

# Verify signature
stella crypto verify \
  --provider gost \
  --key-id key-gost-2012 \
  --algorithm GOST12-256 \
  --file document.pdf \
  --signature document.pdf.sig

Administration

Command	Description
stella admin policy	Manage platform policies
stella admin users	User management
stella admin feeds	Advisory feed management
stella admin system	System operations

Example:

# Add a security engineer
stella admin users add alice@example.com --role security-engineer

# Export current policy
stella admin policy export --output policy-backup.yaml

# Refresh vulnerability feeds
stella admin feeds refresh --source nvd --force

Reporting & Export

Command	Description
stella report	Generate compliance reports
stella export	Export scan results in various formats
stella query	Query vulnerability database

Example:

# Generate HTML report
stella report --scan scan-result.json --format html --output report.html

# Export to CSV for spreadsheet analysis
stella export --scan scan-result.json --format csv --output vulnerabilities.csv

---

Configuration

Configuration File Locations

Configuration files are loaded in the following order (later files override earlier):

1. System-wide: /etc/stellaops/config.yaml
2. User-level: ~/.stellaops/config.yaml
3. Project-level: ./stellaops.config.yaml
4. Environment variables: STELLAOPS_*

Configuration Precedence

Environment Variables > Project Config > User Config > System Config > Defaults

Sample Configuration

StellaOps:
  Backend:
    BaseUrl: "https://api.stellaops.example.com"
    Auth:
      OpTok:
        Enabled: true

  Scan:
    DefaultFormat: "spdx"
    IncludeAttestations: true
    VexMode: "strict"

  Crypto:
    DefaultProvider: "default"
    Profiles:
      - name: "prod-signing"
        provider: "default"
        algorithm: "ECDSA-P256"
        keyId: "prod-key-2024"

  Admin:
    RequireConfirmation: true
    AuditLog:
      Enabled: true
      OutputPath: "~/.stellaops/admin-audit.jsonl"

Environment Variables

Variable	Description	Example
STELLAOPS_BACKEND_URL	Backend API URL	https://api.stellaops.example.com
STELLAOPS_API_KEY	API key for authentication	sk_live_...
STELLAOPS_OFFLINE_MODE	Enable offline mode	true
STELLAOPS_CRYPTO_PROVIDER	Default crypto provider	gost, eidas, sm
STELLAOPS_LOG_LEVEL	Log level	Debug, Info, Warning, Error

---

Distribution Variants

StellaOps CLI is available in four regional distributions to comply with export control and cryptographic regulations:

1. International (Default)

Audience: Global users (no export restrictions)

Crypto Providers:

• .NET Crypto (RSA, ECDSA, EdDSA)
• BouncyCastle (additional algorithms)

Download:

wget https://releases.stella-ops.org/cli/latest/stella-international-linux-x64.tar.gz

2. Russia (GOST)

Audience: Russia, CIS states

Crypto Providers:

• Default (.NET Crypto, BouncyCastle)
• GOST R 34.10-2012 (digital signature)
• GOST R 34.11-2012 (hash functions)
• GOST R 34.12-2015 (block cipher)

Providers: CryptoPro CSP, OpenSSL-GOST, PKCS#11

Download:

wget https://releases.stella-ops.org/cli/russia/latest/stella-russia-linux-x64.tar.gz

See: Compliance Guide - GOST

3. EU (eIDAS)

Audience: European Union

Crypto Providers:

• Default (.NET Crypto, BouncyCastle)
• eIDAS Qualified Electronic Signatures (QES)
• eIDAS Advanced Electronic Signatures (AES)
• eIDAS AdES signatures

Standards: ETSI EN 319 412 (certificates), ETSI EN 319 102 (policies)

Download:

wget https://releases.stella-ops.org/cli/eu/latest/stella-eu-linux-x64.tar.gz

See: Compliance Guide - eIDAS

4. China (SM)

Audience: China

Crypto Providers:

• Default (.NET Crypto, BouncyCastle)
• SM2 (elliptic curve signature, GM/T 0003-2012)
• SM3 (hash function, GM/T 0004-2012)
• SM4 (block cipher, GM/T 0002-2012)

Providers: GmSSL, Commercial CSPs (OSCCA-certified)

Download:

wget https://releases.stella-ops.org/cli/china/latest/stella-china-linux-x64.tar.gz

See: Compliance Guide - SM

Which Distribution Should I Use?

Your Location	Distribution	Reason
USA, Canada, Australia, etc.	International	No export restrictions
Russia, Kazakhstan, Belarus	Russia	GOST compliance required for government/regulated sectors
EU member states	EU	eIDAS compliance for qualified signatures
China	China	SM algorithms required for government/regulated sectors

---

Profile Management

Profiles allow switching between environments (dev, staging, production) easily.

Create a Profile

# Create dev profile
stella config profile create dev \
  --backend-url https://dev.stellaops.example.com \
  --crypto-provider default

# Create production profile with GOST
stella config profile create prod \
  --backend-url https://api.stellaops.example.com \
  --crypto-provider gost

Switch Profiles

# Switch to production profile
stella config profile use prod

# List profiles
stella config profile list

# Show active profile
stella config profile current

---

Getting Help

Built-in Help

# General help
stella --help

# Command-specific help
stella scan --help
stella crypto sign --help
stella admin users --help

# Show version and build info
stella --version
stella admin system info

Documentation

• CLI Architecture: docs/cli/architecture.md
• Command Reference: docs/cli/command-reference.md
• Crypto Plugin Development: docs/cli/crypto-plugins.md
• Compliance Guide: docs/cli/compliance-guide.md
• Distribution Matrix: docs/cli/distribution-matrix.md
• Admin Guide: admin-reference.md
• Troubleshooting: docs/cli/troubleshooting.md

Community Resources

• GitHub Discussions: https://github.com/stellaops/stellaops/discussions
• Issue Tracker: https://git.stella-ops.org/stella-ops.org/git.stella-ops.org/issues
• Documentation: https://docs.stella-ops.org

---

Common Workflows

1. Daily Vulnerability Scan

#!/bin/bash
# daily-scan.sh - Run daily vulnerability scan

IMAGE="myapp:latest"
OUTPUT_DIR="scan-results/$(date +%Y-%m-%d)"

mkdir -p "$OUTPUT_DIR"

stella scan "docker://$IMAGE" \
  --sbom-format spdx \
  --attestation \
  --vex-mode strict \
  --output "$OUTPUT_DIR/scan-result.json"

# Generate HTML report
stella report \
  --scan "$OUTPUT_DIR/scan-result.json" \
  --format html \
  --output "$OUTPUT_DIR/report.html"

echo "Scan complete: $OUTPUT_DIR"

2. Compliance Attestation Workflow

#!/bin/bash
# compliance-workflow.sh - Generate compliance attestation

IMAGE="myapp:v1.2.3"

# 1. Scan image
stella scan "docker://$IMAGE" --output scan.json

# 2. Generate SBOM
stella scan "docker://$IMAGE" --sbom-only --format spdx --output sbom.spdx.json

# 3. Generate attestation
stella aoc --scan scan.json --sbom sbom.spdx.json --output attestation.jsonl

# 4. Sign attestation (GOST example for Russia)
stella crypto sign \
  --provider gost \
  --key-id compliance-key \
  --algorithm GOST12-256 \
  --file attestation.jsonl \
  --output attestation.jsonl.sig

# 5. Bundle everything
tar -czf myapp-v1.2.3-compliance.tar.gz \
  scan.json \
  sbom.spdx.json \
  attestation.jsonl \
  attestation.jsonl.sig

echo "Compliance bundle: myapp-v1.2.3-compliance.tar.gz"

3. Policy-based CI/CD Gate

#!/bin/bash
# ci-gate.sh - Fail CI build if policy violations found

IMAGE="$1"

stella scan "docker://$IMAGE" --output scan.json

# Check exit code
if [ $? -ne 0 ]; then
  echo "❌ Scan failed"
  exit 1
fi

# Check for policy violations
VIOLATIONS=$(jq '.policyViolations | length' scan.json)

if [ "$VIOLATIONS" -gt 0 ]; then
  echo "❌ Policy violations found: $VIOLATIONS"
  jq '.policyViolations' scan.json
  exit 1
fi

echo "✅ Image compliant with policy"
exit 0

---

Next Steps

1. Install the CLI - Choose your distribution and install
2. Configure authentication - stella auth login
3. Run your first scan - stella scan docker://your-image
4. Explore commands - stella --help
5. Read detailed docs - See links above

For detailed architecture and plugin development, see CLI Architecture.

For complete command reference, see Command Reference.

For troubleshooting, see Troubleshooting Guide.