stella-ops.org/git.stella-ops.org

Fork 0

Files

master 145e67a544 Harden live-backed unified search weighting and indexing

2026-03-08 02:23:43 +02:00

13 KiB

Raw Blame History

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.7 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 0: Source Checkout (local development)

If you are working from this repository checkout, do not assume stella is already installed on PATH. Build or run the CLI from source first.

Quick references:

docs/API_CLI_REFERENCE.md
src/AdvisoryAI/__Tests/INFRASTRUCTURE.md

# Run directly from source
dotnet run --project "src/Cli/StellaOps.Cli/StellaOps.Cli.csproj" -- --help

# Publish a reusable local binary
dotnet publish "src/Cli/StellaOps.Cli/StellaOps.Cli.csproj" -c Release -o ".artifacts/stella-cli"

# Windows
.artifacts/stella-cli/StellaOps.Cli.exe --help

# Linux/macOS
./.artifacts/stella-cli/StellaOps.Cli --help

For local AdvisoryAI live-search verification from a source checkout:

use stella advisoryai sources prepare from the local CLI build or dotnet run
then use the authenticated HTTP rebuild steps in src/AdvisoryAI/__Tests/INFRASTRUCTURE.md

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

System-wide: /etc/stellaops/config.yaml
User-level: ~/.stellaops/config.yaml
Project-level: ./stellaops.config.yaml
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: architecture.md
Command Reference: commands/reference.md
Crypto Plugin Development: crypto/crypto-plugins.md
Compliance Guide: compliance.md
Distribution Matrix: distribution-matrix.md
Admin Guide: admin/admin-reference.md
Troubleshooting: 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

Install the CLI - Choose your distribution and install
Configure authentication - stella auth login
Run your first scan - stella scan docker://your-image
Explore commands - stella --help
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.

13 KiB Raw Blame History

stella CLI - Overview and Quick Start

Overview

Quick Start

Installation

Option 0: Source Checkout (local development)

Option 1: .NET Tool (Recommended)

Option 2: Binary Download

Option 3: Package Managers

First-time Setup

1. Configure Backend URL

2. Authenticate

3. Run Your First Scan

Command Categories

Scanning & Analysis

Cryptography & Compliance

Administration

Reporting & Export

Configuration

Configuration File Locations

Configuration Precedence

Sample Configuration

Environment Variables

Distribution Variants

1. International (Default)

2. Russia (GOST)

3. EU (eIDAS)

4. China (SM)

Which Distribution Should I Use?

Profile Management

Create a Profile

Switch Profiles

Getting Help

Built-in Help

Documentation

Community Resources

Common Workflows

1. Daily Vulnerability Scan

2. Compliance Attestation Workflow

3. Policy-based CI/CD Gate

Next Steps

13 KiB

Raw Blame History