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

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

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

# Verify installation
stella --version
```

#### Option 2: Binary Download

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

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

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

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

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

```yaml
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:**
```bash
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:**
```bash
wget https://releases.stella-ops.org/cli/russia/latest/stella-russia-linux-x64.tar.gz
```

**See:** [Compliance Guide - GOST](compliance-guide.md#gost-russia)

### 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:**
```bash
wget https://releases.stella-ops.org/cli/eu/latest/stella-eu-linux-x64.tar.gz
```

**See:** [Compliance Guide - eIDAS](compliance-guide.md#eidas-eu)

### 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:**
```bash
wget https://releases.stella-ops.org/cli/china/latest/stella-china-linux-x64.tar.gz
```

**See:** [Compliance Guide - SM](compliance-guide.md#sm-china)

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

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

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

```bash
# 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](architecture.md)
- **Command Reference**: [docs/cli/command-reference.md](command-reference.md)
- **Crypto Plugin Development**: [docs/cli/crypto-plugins.md](crypto-plugins.md)
- **Compliance Guide**: [docs/cli/compliance-guide.md](compliance-guide.md)
- **Distribution Matrix**: [docs/cli/distribution-matrix.md](distribution-matrix.md)
- **Admin Guide**: [admin-reference.md](admin-reference.md)
- **Troubleshooting**: [docs/cli/troubleshooting.md](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

```bash
#!/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

```bash
#!/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

```bash
#!/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](architecture.md).

For complete command reference, see [Command Reference](command-reference.md).

For troubleshooting, see [Troubleshooting Guide](troubleshooting.md).