feat(scanner): Complete PoE implementation with Windows compatibility fix
- Fix namespace conflicts (Subgraph → PoESubgraph) - Add hash sanitization for Windows filesystem (colon → underscore) - Update all test mocks to use It.IsAny<>() - Add direct orchestrator unit tests - All 8 PoE tests now passing (100% success rate) - Complete SPRINT_3500_0001_0001 documentation Fixes compilation errors and Windows filesystem compatibility issues. Tests: 8/8 passing Files: 8 modified, 1 new test, 1 completion report 🤖 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
508
docs/cli/README.md
Normal file
508
docs/cli/README.md
Normal file
@@ -0,0 +1,508 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user