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).
|
||||
460
docs/cli/admin-reference.md
Normal file
460
docs/cli/admin-reference.md
Normal file
@@ -0,0 +1,460 @@
|
||||
# stella admin - Administrative Operations Reference
|
||||
|
||||
**Sprint:** SPRINT_4100_0006_0005 - Admin Utility Integration
|
||||
|
||||
## Overview
|
||||
|
||||
The `stella admin` command group provides administrative operations for platform management. These commands require elevated authentication and are used for policy management, user administration, feed configuration, and system maintenance.
|
||||
|
||||
## Authentication
|
||||
|
||||
Admin commands require one of the following authentication methods:
|
||||
|
||||
1. **OpTok with admin scopes** (recommended for production):
|
||||
```bash
|
||||
stella auth login
|
||||
# Obtain OpTok with admin.* scopes
|
||||
stella admin policy export
|
||||
```
|
||||
|
||||
2. **Bootstrap API key** (for initial setup before Authority configured):
|
||||
```bash
|
||||
export STELLAOPS_BOOTSTRAP_KEY="bootstrap-key-from-backend-config"
|
||||
stella admin users add admin@example.com --role admin
|
||||
```
|
||||
|
||||
### Required Scopes
|
||||
|
||||
| Command Group | Required Scope | Purpose |
|
||||
|---------------|----------------|---------|
|
||||
| `stella admin policy` | `admin.policy` | Policy management operations |
|
||||
| `stella admin users` | `admin.users` | User administration |
|
||||
| `stella admin feeds` | `admin.feeds` | Feed management |
|
||||
| `stella admin system` | `admin.platform` | System operations |
|
||||
|
||||
## Command Reference
|
||||
|
||||
### stella admin policy
|
||||
|
||||
Policy management commands for exporting, importing, and validating platform policies.
|
||||
|
||||
#### stella admin policy export
|
||||
|
||||
Export the active policy snapshot to a file or stdout.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin policy export [--output <path>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-o, --output <path>` - Output file path (stdout if omitted)
|
||||
- `-v, --verbose` - Enable verbose output
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Export to stdout
|
||||
stella admin policy export
|
||||
|
||||
# Export to file
|
||||
stella admin policy export --output policy-backup.yaml
|
||||
|
||||
# Export with timestamp
|
||||
stella admin policy export --output backup-$(date +%F).yaml
|
||||
```
|
||||
|
||||
#### stella admin policy import
|
||||
|
||||
Import policy from a YAML or JSON file.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin policy import --file <path> [--validate-only] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-f, --file <path>` - Policy file to import (required)
|
||||
- `--validate-only` - Validate without importing
|
||||
- `-v, --verbose` - Enable verbose output
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Validate policy before importing
|
||||
stella admin policy import --file new-policy.yaml --validate-only
|
||||
|
||||
# Import policy
|
||||
stella admin policy import --file new-policy.yaml
|
||||
```
|
||||
|
||||
#### stella admin policy validate
|
||||
|
||||
Validate a policy file without importing.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin policy validate --file <path> [--verbose]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
stella admin policy validate --file policy.yaml
|
||||
```
|
||||
|
||||
#### stella admin policy list
|
||||
|
||||
List all policy revisions.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin policy list [--format <format>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--format <format>` - Output format: `table` (default), `json`
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# List as table
|
||||
stella admin policy list
|
||||
|
||||
# List as JSON
|
||||
stella admin policy list --format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella admin users
|
||||
|
||||
User management commands for adding, removing, and updating users.
|
||||
|
||||
#### stella admin users list
|
||||
|
||||
List platform users.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin users list [--role <role>] [--format <format>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--role <role>` - Filter by role
|
||||
- `--format <format>` - Output format: `table` (default), `json`
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# List all users
|
||||
stella admin users list
|
||||
|
||||
# List all admins
|
||||
stella admin users list --role admin
|
||||
|
||||
# List as JSON
|
||||
stella admin users list --format json
|
||||
```
|
||||
|
||||
#### stella admin users add
|
||||
|
||||
Add a new user to the platform.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin users add <email> --role <role> [--tenant <id>] [--verbose]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `<email>` - User email address
|
||||
|
||||
**Options:**
|
||||
- `-r, --role <role>` - User role (required)
|
||||
- `-t, --tenant <id>` - Tenant ID (default if omitted)
|
||||
|
||||
**Available Roles:**
|
||||
- `admin` - Full platform access
|
||||
- `security-engineer` - Security operations
|
||||
- `developer` - Development access
|
||||
- `viewer` - Read-only access
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Add admin user
|
||||
stella admin users add admin@example.com --role admin
|
||||
|
||||
# Add security engineer for specific tenant
|
||||
stella admin users add alice@example.com --role security-engineer --tenant acme-corp
|
||||
```
|
||||
|
||||
#### stella admin users revoke
|
||||
|
||||
Revoke user access.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin users revoke <email> [--confirm] [--verbose]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `<email>` - User email address
|
||||
|
||||
**Options:**
|
||||
- `--confirm` - Confirm revocation (required for safety)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Revoke user (requires --confirm)
|
||||
stella admin users revoke bob@example.com --confirm
|
||||
```
|
||||
|
||||
**Note:** The `--confirm` flag is required to prevent accidental user removal.
|
||||
|
||||
#### stella admin users update
|
||||
|
||||
Update user role.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin users update <email> --role <role> [--verbose]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `<email>` - User email address
|
||||
|
||||
**Options:**
|
||||
- `-r, --role <role>` - New user role (required)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Promote user to admin
|
||||
stella admin users update alice@example.com --role admin
|
||||
|
||||
# Change to viewer role
|
||||
stella admin users update bob@example.com --role viewer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella admin feeds
|
||||
|
||||
Advisory feed management commands.
|
||||
|
||||
#### stella admin feeds list
|
||||
|
||||
List configured advisory feeds.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin feeds list [--format <format>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--format <format>` - Output format: `table` (default), `json`
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# List feeds as table
|
||||
stella admin feeds list
|
||||
|
||||
# List feeds as JSON
|
||||
stella admin feeds list --format json
|
||||
```
|
||||
|
||||
#### stella admin feeds status
|
||||
|
||||
Show feed synchronization status.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin feeds status [--source <id>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-s, --source <id>` - Filter by source ID (all if omitted)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Show status for all feeds
|
||||
stella admin feeds status
|
||||
|
||||
# Show status for specific feed
|
||||
stella admin feeds status --source nvd
|
||||
```
|
||||
|
||||
#### stella admin feeds refresh
|
||||
|
||||
Trigger feed refresh.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin feeds refresh [--source <id>] [--force] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-s, --source <id>` - Refresh specific source (all if omitted)
|
||||
- `--force` - Force refresh (ignore cache)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Refresh all feeds
|
||||
stella admin feeds refresh
|
||||
|
||||
# Force refresh specific feed
|
||||
stella admin feeds refresh --source nvd --force
|
||||
|
||||
# Refresh OSV feed
|
||||
stella admin feeds refresh --source osv
|
||||
```
|
||||
|
||||
#### stella admin feeds history
|
||||
|
||||
Show feed synchronization history.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin feeds history --source <id> [--limit <n>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-s, --source <id>` - Source ID (required)
|
||||
- `-n, --limit <n>` - Limit number of results (default: 10)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Show last 10 syncs for NVD
|
||||
stella admin feeds history --source nvd
|
||||
|
||||
# Show last 50 syncs for OSV
|
||||
stella admin feeds history --source osv --limit 50
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella admin system
|
||||
|
||||
System management and health commands.
|
||||
|
||||
#### stella admin system status
|
||||
|
||||
Show system health status.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin system status [--format <format>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--format <format>` - Output format: `table` (default), `json`
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Show status as table
|
||||
stella admin system status
|
||||
|
||||
# Show status as JSON
|
||||
stella admin system status --format json
|
||||
```
|
||||
|
||||
#### stella admin system info
|
||||
|
||||
Show system version, build, and configuration information.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin system info [--verbose]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
stella admin system info
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Admin commands can be configured via `appsettings.admin.yaml`:
|
||||
|
||||
```yaml
|
||||
StellaOps:
|
||||
Backend:
|
||||
BaseUrl: "https://api.stellaops.example.com"
|
||||
Auth:
|
||||
OpTok:
|
||||
Enabled: true
|
||||
|
||||
Admin:
|
||||
DefaultTenant: "default"
|
||||
RequireConfirmation: true
|
||||
AuditLog:
|
||||
Enabled: true
|
||||
OutputPath: "~/.stellaops/admin-audit.jsonl"
|
||||
```
|
||||
|
||||
See `etc/appsettings.admin.yaml.example` for full configuration options.
|
||||
|
||||
## Backend API Endpoints
|
||||
|
||||
Admin commands call the following backend APIs:
|
||||
|
||||
| Endpoint | Method | Command |
|
||||
|----------|--------|---------|
|
||||
| `/api/v1/admin/policy/export` | GET | `stella admin policy export` |
|
||||
| `/api/v1/admin/policy/import` | POST | `stella admin policy import` |
|
||||
| `/api/v1/admin/policy/validate` | POST | `stella admin policy validate` |
|
||||
| `/api/v1/admin/policy/revisions` | GET | `stella admin policy list` |
|
||||
| `/api/v1/admin/users` | GET | `stella admin users list` |
|
||||
| `/api/v1/admin/users` | POST | `stella admin users add` |
|
||||
| `/api/v1/admin/users/{email}` | DELETE | `stella admin users revoke` |
|
||||
| `/api/v1/admin/users/{email}` | PATCH | `stella admin users update` |
|
||||
| `/api/v1/admin/feeds` | GET | `stella admin feeds list` |
|
||||
| `/api/v1/admin/feeds/status` | GET | `stella admin feeds status` |
|
||||
| `/api/v1/admin/feeds/{id}/refresh` | POST | `stella admin feeds refresh` |
|
||||
| `/api/v1/admin/feeds/{id}/history` | GET | `stella admin feeds history` |
|
||||
| `/api/v1/admin/system/status` | GET | `stella admin system status` |
|
||||
| `/api/v1/admin/system/info` | GET | `stella admin system info` |
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Authentication Required**: All admin commands require valid OpTok or bootstrap key
|
||||
2. **Scope Validation**: Backend validates admin.* scopes for all operations
|
||||
3. **Audit Logging**: All admin operations are logged to audit trail
|
||||
4. **Confirmation for Destructive Ops**: Commands like `revoke` require `--confirm` flag
|
||||
5. **Bootstrap Mode**: Bootstrap key should only be used for initial setup
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Authentication Errors
|
||||
|
||||
```
|
||||
HTTP 401: Unauthorized
|
||||
```
|
||||
|
||||
**Solution**: Ensure you have a valid OpTok with admin scopes:
|
||||
```bash
|
||||
stella auth login
|
||||
stella admin policy export
|
||||
```
|
||||
|
||||
### Missing Scopes
|
||||
|
||||
```
|
||||
HTTP 403: Forbidden - insufficient scopes
|
||||
```
|
||||
|
||||
**Solution**: Request OpTok with required admin.* scopes from platform administrator.
|
||||
|
||||
### Backend API Not Available
|
||||
|
||||
```
|
||||
HTTP Error: Connection refused
|
||||
```
|
||||
|
||||
**Solution**: Verify backend URL in configuration:
|
||||
```bash
|
||||
export STELLAOPS_BACKEND__BASEURL="https://api.stellaops.example.com"
|
||||
stella admin system status
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [CLI Reference](../09_API_CLI_REFERENCE.md)
|
||||
- [Authority Documentation](../11_AUTHORITY.md)
|
||||
- [Operational Procedures](../operations/administration.md)
|
||||
789
docs/cli/architecture.md
Normal file
789
docs/cli/architecture.md
Normal file
@@ -0,0 +1,789 @@
|
||||
# stella CLI - Plugin Architecture
|
||||
|
||||
**Sprint:** SPRINT_4100_0006_0006 - CLI Documentation Overhaul
|
||||
|
||||
## Overview
|
||||
|
||||
The `stella` CLI is built with a plugin architecture that enables conditional compilation of regional cryptographic providers (GOST, eIDAS, SM) while maintaining a unified command interface. This design supports compliance with export control regulations and cryptographic standards across different jurisdictions.
|
||||
|
||||
**Key Design Goals:**
|
||||
1. **Conditional Compilation**: Include only authorized crypto providers per distribution
|
||||
2. **Plugin Isolation**: Crypto providers as self-contained, testable modules
|
||||
3. **Dependency Injection**: Runtime service resolution for providers
|
||||
4. **Configuration-driven**: Profile-based provider selection
|
||||
5. **Extensibility**: Easy addition of new providers without core CLI changes
|
||||
|
||||
---
|
||||
|
||||
## Architecture Layers
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ stella CLI │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Command Groups │
|
||||
│ ├─ scan, aoc, symbols, crypto, admin, ... │
|
||||
│ └─ System.CommandLine 2.0 routing │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Plugin System │
|
||||
│ ├─ ICryptoProvider interface │
|
||||
│ ├─ Plugin discovery (build-time + runtime) │
|
||||
│ └─ DependencyInjection (Microsoft.Extensions.DI) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Crypto Plugins (Conditional) │
|
||||
│ ├─ Default (.NET Crypto, BouncyCastle) [ALL] │
|
||||
│ ├─ GOST (CryptoPro, OpenSSL-GOST, PKCS#11) [RUSSIA] │
|
||||
│ ├─ eIDAS (TSP Client, Local Signer) [EU] │
|
||||
│ └─ SM (GmSSL, SM Remote CSP) [CHINA] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Backend Integration │
|
||||
│ ├─ Authority (OAuth2 + DPoP) │
|
||||
│ ├─ Scanner, Concelier, Policy, ... │
|
||||
│ └─ HTTP clients with retry policies │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build-time Plugin Selection
|
||||
|
||||
### Conditional Compilation Workflow
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[MSBuild Start] --> B{Check Build Flags}
|
||||
B -->|StellaOpsEnableGOST=true| C[Include GOST Plugin]
|
||||
B -->|StellaOpsEnableEIDAS=true| D[Include eIDAS Plugin]
|
||||
B -->|StellaOpsEnableSM=true| E[Include SM Plugin]
|
||||
B -->|No flags| F[Include Default Only]
|
||||
|
||||
C --> G[Set STELLAOPS_ENABLE_GOST]
|
||||
D --> H[Set STELLAOPS_ENABLE_EIDAS]
|
||||
E --> I[Set STELLAOPS_ENABLE_SM]
|
||||
|
||||
G --> J[Compile with Plugin]
|
||||
H --> J
|
||||
I --> J
|
||||
F --> J
|
||||
|
||||
J --> K[Link Plugin Assembly]
|
||||
K --> L[Final Binary]
|
||||
```
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
src/Cli/
|
||||
├── StellaOps.Cli/
|
||||
│ ├── Program.cs # Entry point, DI setup
|
||||
│ ├── Commands/
|
||||
│ │ ├── CommandFactory.cs # Command routing
|
||||
│ │ ├── Crypto/CryptoCommandGroup.cs # Crypto commands
|
||||
│ │ ├── Admin/AdminCommandGroup.cs # Admin commands
|
||||
│ │ └── ...
|
||||
│ └── StellaOps.Cli.csproj # Conditional <ProjectReference>
|
||||
│
|
||||
├── StellaOps.Cli.Crypto/
|
||||
│ ├── ICryptoProvider.cs # Plugin interface
|
||||
│ ├── ICryptoProviderDiagnostics.cs # Diagnostics interface
|
||||
│ └── Models/ # Shared models
|
||||
│
|
||||
├── StellaOps.Cli.Crypto.Default/ # Always included
|
||||
│ ├── DotNetCryptoProvider.cs # .NET crypto
|
||||
│ ├── BouncyCastleCryptoProvider.cs # BouncyCastle
|
||||
│ └── ServiceCollectionExtensions.cs # DI registration
|
||||
│
|
||||
├── StellaOps.Cli.Crypto.Gost/ # Conditional (Russia)
|
||||
│ ├── GostCryptoProvider.cs # GOST implementation
|
||||
│ ├── CryptoProAdapter.cs # CryptoPro CSP adapter
|
||||
│ ├── OpenSslGostAdapter.cs # OpenSSL-GOST adapter
|
||||
│ └── ServiceCollectionExtensions.cs
|
||||
│
|
||||
├── StellaOps.Cli.Crypto.Eidas/ # Conditional (EU)
|
||||
│ ├── EidasCryptoProvider.cs # eIDAS implementation
|
||||
│ ├── TspClientAdapter.cs # TSP remote signing
|
||||
│ └── ServiceCollectionExtensions.cs
|
||||
│
|
||||
└── StellaOps.Cli.Crypto.Sm/ # Conditional (China)
|
||||
├── SmCryptoProvider.cs # SM implementation
|
||||
├── GmSslAdapter.cs # GmSSL adapter
|
||||
└── ServiceCollectionExtensions.cs
|
||||
```
|
||||
|
||||
### StellaOps.Cli.csproj (Conditional References)
|
||||
|
||||
```xml
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net10.0</TargetFramework>
|
||||
<OutputType>Exe</OutputType>
|
||||
</PropertyGroup>
|
||||
|
||||
<!-- Always include default crypto -->
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\StellaOps.Cli.Crypto\StellaOps.Cli.Crypto.csproj" />
|
||||
<ProjectReference Include="..\StellaOps.Cli.Crypto.Default\StellaOps.Cli.Crypto.Default.csproj" />
|
||||
</ItemGroup>
|
||||
|
||||
<!-- GOST plugin (Russia distribution) -->
|
||||
<ItemGroup Condition="'$(StellaOpsEnableGOST)' == 'true'">
|
||||
<ProjectReference Include="..\StellaOps.Cli.Crypto.Gost\StellaOps.Cli.Crypto.Gost.csproj" />
|
||||
<DefineConstants>$(DefineConstants);STELLAOPS_ENABLE_GOST</DefineConstants>
|
||||
</ItemGroup>
|
||||
|
||||
<!-- eIDAS plugin (EU distribution) -->
|
||||
<ItemGroup Condition="'$(StellaOpsEnableEIDAS)' == 'true'">
|
||||
<ProjectReference Include="..\StellaOps.Cli.Crypto.Eidas\StellaOps.Cli.Crypto.Eidas.csproj" />
|
||||
<DefineConstants>$(DefineConstants);STELLAOPS_ENABLE_EIDAS</DefineConstants>
|
||||
</ItemGroup>
|
||||
|
||||
<!-- SM plugin (China distribution) -->
|
||||
<ItemGroup Condition="'$(StellaOpsEnableSM)' == 'true'">
|
||||
<ProjectReference Include="..\StellaOps.Cli.Crypto.Sm\StellaOps.Cli.Crypto.Sm.csproj" />
|
||||
<DefineConstants>$(DefineConstants);STELLAOPS_ENABLE_SM</DefineConstants>
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
### Build Commands
|
||||
|
||||
```bash
|
||||
# International distribution (default, no flags)
|
||||
dotnet publish src/Cli/StellaOps.Cli --configuration Release --runtime linux-x64
|
||||
|
||||
# Russia distribution (GOST enabled)
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
-p:StellaOpsEnableGOST=true
|
||||
|
||||
# EU distribution (eIDAS enabled)
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
-p:StellaOpsEnableEIDAS=true
|
||||
|
||||
# China distribution (SM enabled)
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
-p:StellaOpsEnableSM=true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Runtime Plugin Discovery
|
||||
|
||||
### Program.cs - DI Registration
|
||||
|
||||
```csharp
|
||||
using Microsoft.Extensions.Configuration;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
using StellaOps.Cli.Crypto;
|
||||
using StellaOps.Cli.Crypto.Default;
|
||||
|
||||
#if STELLAOPS_ENABLE_GOST
|
||||
using StellaOps.Cli.Crypto.Gost;
|
||||
#endif
|
||||
|
||||
#if STELLAOPS_ENABLE_EIDAS
|
||||
using StellaOps.Cli.Crypto.Eidas;
|
||||
#endif
|
||||
|
||||
#if STELLAOPS_ENABLE_SM
|
||||
using StellaOps.Cli.Crypto.Sm;
|
||||
#endif
|
||||
|
||||
namespace StellaOps.Cli;
|
||||
|
||||
public class Program
|
||||
{
|
||||
public static async Task<int> Main(string[] args)
|
||||
{
|
||||
// Build configuration
|
||||
var configuration = new ConfigurationBuilder()
|
||||
.SetBasePath(Directory.GetCurrentDirectory())
|
||||
.AddJsonFile("appsettings.json", optional: true)
|
||||
.AddYamlFile("appsettings.yaml", optional: true)
|
||||
.AddYamlFile(Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), ".stellaops", "config.yaml"), optional: true)
|
||||
.AddEnvironmentVariables("STELLAOPS_")
|
||||
.Build();
|
||||
|
||||
// Setup DI container
|
||||
var services = new ServiceCollection();
|
||||
|
||||
// Register configuration
|
||||
services.AddSingleton<IConfiguration>(configuration);
|
||||
|
||||
// Register HTTP clients
|
||||
services.AddHttpClient("StellaOpsBackend", client =>
|
||||
{
|
||||
var baseUrl = configuration["StellaOps:Backend:BaseUrl"];
|
||||
if (!string.IsNullOrEmpty(baseUrl))
|
||||
client.BaseAddress = new Uri(baseUrl);
|
||||
});
|
||||
|
||||
// Register default crypto providers (always available)
|
||||
services.AddDefaultCryptoProviders(configuration);
|
||||
|
||||
// Register regional crypto providers (conditional compilation)
|
||||
#if STELLAOPS_ENABLE_GOST
|
||||
services.AddGostCryptoProviders(configuration);
|
||||
#endif
|
||||
|
||||
#if STELLAOPS_ENABLE_EIDAS
|
||||
services.AddEidasCryptoProviders(configuration);
|
||||
#endif
|
||||
|
||||
#if STELLAOPS_ENABLE_SM
|
||||
services.AddSmCryptoProviders(configuration);
|
||||
#endif
|
||||
|
||||
// Build service provider
|
||||
var serviceProvider = services.BuildServiceProvider();
|
||||
|
||||
// Create root command and run
|
||||
var rootCommand = CommandFactory.CreateRootCommand(serviceProvider);
|
||||
return await rootCommand.InvokeAsync(args);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Plugin Discovery Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Build as MSBuild
|
||||
participant CLI as stella CLI
|
||||
participant DI as DI Container
|
||||
participant Plugin as Crypto Plugin
|
||||
participant User as User Command
|
||||
|
||||
Build->>Build: Check StellaOpsEnableGOST=true
|
||||
Build->>Build: Include GOST plugin <ProjectReference>
|
||||
Build->>Build: Set DefineConstants=STELLAOPS_ENABLE_GOST
|
||||
Build->>CLI: Compile with GOST plugin
|
||||
|
||||
User->>CLI: stella crypto sign --provider gost
|
||||
CLI->>CLI: Program.cs startup
|
||||
CLI->>CLI: Check #if STELLAOPS_ENABLE_GOST
|
||||
CLI->>DI: services.AddGostCryptoProviders()
|
||||
DI->>Plugin: Register GostCryptoProvider as ICryptoProvider
|
||||
Plugin->>DI: Provider registered
|
||||
|
||||
CLI->>DI: Resolve ICryptoProvider (name="gost")
|
||||
DI->>Plugin: Return GostCryptoProvider instance
|
||||
Plugin->>CLI: Execute sign operation
|
||||
CLI->>User: Signature created
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plugin Interfaces
|
||||
|
||||
### ICryptoProvider
|
||||
|
||||
The core interface all crypto providers must implement:
|
||||
|
||||
```csharp
|
||||
namespace StellaOps.Cli.Crypto;
|
||||
|
||||
public interface ICryptoProvider
|
||||
{
|
||||
/// <summary>
|
||||
/// Unique provider name (e.g., "gost", "eidas", "sm")
|
||||
/// </summary>
|
||||
string Name { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Supported algorithms (e.g., "GOST12-256", "ECDSA-P256")
|
||||
/// </summary>
|
||||
string[] SupportedAlgorithms { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Sign data with specified algorithm and key
|
||||
/// </summary>
|
||||
Task<byte[]> SignAsync(
|
||||
byte[] data,
|
||||
string algorithm,
|
||||
CryptoKeyReference keyRef,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Verify signature
|
||||
/// </summary>
|
||||
Task<bool> VerifyAsync(
|
||||
byte[] data,
|
||||
byte[] signature,
|
||||
string algorithm,
|
||||
CryptoKeyReference keyRef,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// List available keys
|
||||
/// </summary>
|
||||
Task<IReadOnlyList<CryptoKeyInfo>> ListKeysAsync(
|
||||
CancellationToken cancellationToken = default);
|
||||
}
|
||||
```
|
||||
|
||||
### ICryptoProviderDiagnostics
|
||||
|
||||
Optional interface for provider diagnostics:
|
||||
|
||||
```csharp
|
||||
namespace StellaOps.Cli.Crypto;
|
||||
|
||||
public interface ICryptoProviderDiagnostics
|
||||
{
|
||||
/// <summary>
|
||||
/// Run provider self-test
|
||||
/// </summary>
|
||||
Task<ProviderHealthCheck> HealthCheckAsync(CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Get provider version and capabilities
|
||||
/// </summary>
|
||||
ProviderInfo GetInfo();
|
||||
}
|
||||
|
||||
public sealed record ProviderHealthCheck
|
||||
{
|
||||
public required string ProviderName { get; init; }
|
||||
public required bool IsHealthy { get; init; }
|
||||
public required string[] Checks { get; init; }
|
||||
public string? ErrorMessage { get; init; }
|
||||
}
|
||||
|
||||
public sealed record ProviderInfo
|
||||
{
|
||||
public required string Name { get; init; }
|
||||
public required string Version { get; init; }
|
||||
public required string[] Capabilities { get; init; }
|
||||
public required string[] SupportedAlgorithms { get; init; }
|
||||
}
|
||||
```
|
||||
|
||||
### CryptoKeyReference
|
||||
|
||||
Represents a reference to a cryptographic key:
|
||||
|
||||
```csharp
|
||||
namespace StellaOps.Cli.Crypto;
|
||||
|
||||
public sealed record CryptoKeyReference
|
||||
{
|
||||
/// <summary>
|
||||
/// Key identifier (e.g., "prod-key-2024", file path, HSM slot)
|
||||
/// </summary>
|
||||
public required string KeyId { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Key source: "file", "hsm", "kms", "csp"
|
||||
/// </summary>
|
||||
public required string Source { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Additional parameters (e.g., HSM PIN, KMS region)
|
||||
/// </summary>
|
||||
public IReadOnlyDictionary<string, string>? Parameters { get; init; }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Profile-based Provider Selection
|
||||
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
# Default provider (when --provider not specified)
|
||||
DefaultProvider: "default"
|
||||
|
||||
# Crypto profiles for easy switching
|
||||
Profiles:
|
||||
- name: "default-signing"
|
||||
provider: "default"
|
||||
algorithm: "ECDSA-P256"
|
||||
keyId: "default-key"
|
||||
|
||||
- name: "gost-signing"
|
||||
provider: "gost"
|
||||
algorithm: "GOST12-256"
|
||||
keyId: "gost-key-2024"
|
||||
|
||||
- name: "eidas-qes"
|
||||
provider: "eidas"
|
||||
algorithm: "ECDSA-P256-QES"
|
||||
keyId: "eidas-qes-key"
|
||||
|
||||
# Provider-specific configuration
|
||||
Providers:
|
||||
Gost:
|
||||
CryptoProCsp:
|
||||
Enabled: true
|
||||
ContainerName: "StellaOps-GOST-2024"
|
||||
|
||||
OpenSslGost:
|
||||
Enabled: false
|
||||
EnginePath: "/usr/lib/engines/gost.so"
|
||||
|
||||
Eidas:
|
||||
TspClient:
|
||||
Enabled: true
|
||||
TspUrl: "https://tsp.example.eu/api/v1/sign"
|
||||
ApiKey: "${EIDAS_TSP_API_KEY}"
|
||||
|
||||
Sm:
|
||||
GmSsl:
|
||||
Enabled: true
|
||||
LibraryPath: "/usr/lib/libgmssl.so"
|
||||
```
|
||||
|
||||
### Usage with Profiles
|
||||
|
||||
```bash
|
||||
# Use default profile
|
||||
stella crypto sign --file document.pdf
|
||||
|
||||
# Use specific profile
|
||||
stella crypto sign --profile gost-signing --file document.pdf
|
||||
|
||||
# Override provider explicitly
|
||||
stella crypto sign --provider gost --algorithm GOST12-256 --key-id key1 --file document.pdf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Distribution Matrix
|
||||
|
||||
| Distribution | Default | GOST | eIDAS | SM |
|
||||
|--------------|---------|------|-------|-----|
|
||||
| **stella-international** | ✅ | ❌ | ❌ | ❌ |
|
||||
| **stella-russia** | ✅ | ✅ | ❌ | ❌ |
|
||||
| **stella-eu** | ✅ | ❌ | ✅ | ❌ |
|
||||
| **stella-china** | ✅ | ❌ | ❌ | ✅ |
|
||||
|
||||
**Verification:**
|
||||
```bash
|
||||
# Check available providers
|
||||
stella crypto providers
|
||||
|
||||
# Output (International):
|
||||
# Available Crypto Providers:
|
||||
# - default (.NET Crypto, BouncyCastle)
|
||||
|
||||
# Output (Russia):
|
||||
# Available Crypto Providers:
|
||||
# - default (.NET Crypto, BouncyCastle)
|
||||
# - gost (GOST R 34.10-2012, GOST R 34.11-2012)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Creating Custom Plugins
|
||||
|
||||
### 1. Create Plugin Project
|
||||
|
||||
```bash
|
||||
dotnet new classlib -n StellaOps.Cli.Crypto.MyCustom
|
||||
cd StellaOps.Cli.Crypto.MyCustom
|
||||
|
||||
# Add reference to interface project
|
||||
dotnet add reference ../StellaOps.Cli.Crypto/StellaOps.Cli.Crypto.csproj
|
||||
```
|
||||
|
||||
### 2. Implement ICryptoProvider
|
||||
|
||||
```csharp
|
||||
using StellaOps.Cli.Crypto;
|
||||
|
||||
namespace StellaOps.Cli.Crypto.MyCustom;
|
||||
|
||||
public class MyCustomCryptoProvider : ICryptoProvider, ICryptoProviderDiagnostics
|
||||
{
|
||||
private readonly MyCustomCryptoOptions _options;
|
||||
|
||||
public MyCustomCryptoProvider(IOptions<MyCustomCryptoOptions> options)
|
||||
{
|
||||
_options = options.Value;
|
||||
}
|
||||
|
||||
public string Name => "mycustom";
|
||||
|
||||
public string[] SupportedAlgorithms => new[] { "MYCUSTOM-ALG1", "MYCUSTOM-ALG2" };
|
||||
|
||||
public async Task<byte[]> SignAsync(
|
||||
byte[] data,
|
||||
string algorithm,
|
||||
CryptoKeyReference keyRef,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
// Implementation
|
||||
throw new NotImplementedException();
|
||||
}
|
||||
|
||||
public async Task<bool> VerifyAsync(
|
||||
byte[] data,
|
||||
byte[] signature,
|
||||
string algorithm,
|
||||
CryptoKeyReference keyRef,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
// Implementation
|
||||
throw new NotImplementedException();
|
||||
}
|
||||
|
||||
public async Task<IReadOnlyList<CryptoKeyInfo>> ListKeysAsync(
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
// Implementation
|
||||
throw new NotImplementedException();
|
||||
}
|
||||
|
||||
public async Task<ProviderHealthCheck> HealthCheckAsync(
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
return new ProviderHealthCheck
|
||||
{
|
||||
ProviderName = Name,
|
||||
IsHealthy = true,
|
||||
Checks = new[] { "Library loaded", "Keys accessible" }
|
||||
};
|
||||
}
|
||||
|
||||
public ProviderInfo GetInfo()
|
||||
{
|
||||
return new ProviderInfo
|
||||
{
|
||||
Name = Name,
|
||||
Version = "1.0.0",
|
||||
Capabilities = new[] { "sign", "verify" },
|
||||
SupportedAlgorithms = SupportedAlgorithms
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Create DI Extension
|
||||
|
||||
```csharp
|
||||
using Microsoft.Extensions.Configuration;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
|
||||
namespace StellaOps.Cli.Crypto.MyCustom;
|
||||
|
||||
public static class ServiceCollectionExtensions
|
||||
{
|
||||
public static IServiceCollection AddMyCustomCryptoProviders(
|
||||
this IServiceCollection services,
|
||||
IConfiguration configuration)
|
||||
{
|
||||
// Register provider
|
||||
services.AddSingleton<ICryptoProvider, MyCustomCryptoProvider>();
|
||||
|
||||
// Bind configuration
|
||||
services.Configure<MyCustomCryptoOptions>(
|
||||
configuration.GetSection("StellaOps:Crypto:Providers:MyCustom"));
|
||||
|
||||
return services;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Update StellaOps.Cli.csproj
|
||||
|
||||
```xml
|
||||
<!-- MyCustom plugin (custom distribution) -->
|
||||
<ItemGroup Condition="'$(StellaOpsEnableMyCustom)' == 'true'">
|
||||
<ProjectReference Include="..\StellaOps.Cli.Crypto.MyCustom\StellaOps.Cli.Crypto.MyCustom.csproj" />
|
||||
<DefineConstants>$(DefineConstants);STELLAOPS_ENABLE_MYCUSTOM</DefineConstants>
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
### 5. Update Program.cs
|
||||
|
||||
```csharp
|
||||
#if STELLAOPS_ENABLE_MYCUSTOM
|
||||
using StellaOps.Cli.Crypto.MyCustom;
|
||||
#endif
|
||||
|
||||
// In Main():
|
||||
#if STELLAOPS_ENABLE_MYCUSTOM
|
||||
services.AddMyCustomCryptoProviders(configuration);
|
||||
#endif
|
||||
```
|
||||
|
||||
### 6. Build Custom Distribution
|
||||
|
||||
```bash
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
-p:StellaOpsEnableMyCustom=true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Command Routing
|
||||
|
||||
### System.CommandLine 2.0 Integration
|
||||
|
||||
```csharp
|
||||
// CommandFactory.cs
|
||||
using System.CommandLine;
|
||||
|
||||
public static class CommandFactory
|
||||
{
|
||||
public static Command CreateRootCommand(IServiceProvider services)
|
||||
{
|
||||
var root = new Command("stella", "StellaOps unified CLI");
|
||||
|
||||
// Add command groups
|
||||
root.Add(BuildScanCommand(services));
|
||||
root.Add(BuildCryptoCommand(services));
|
||||
root.Add(BuildAdminCommand(services));
|
||||
root.Add(BuildAuthCommand(services));
|
||||
// ... more commands
|
||||
|
||||
return root;
|
||||
}
|
||||
|
||||
private static Command BuildCryptoCommand(IServiceProvider services)
|
||||
{
|
||||
var crypto = new Command("crypto", "Cryptographic operations");
|
||||
|
||||
// crypto providers
|
||||
var providers = new Command("providers", "List available crypto providers");
|
||||
providers.SetAction(async (parseResult, ct) =>
|
||||
{
|
||||
var cryptoProviders = services.GetServices<ICryptoProvider>();
|
||||
foreach (var provider in cryptoProviders)
|
||||
{
|
||||
Console.WriteLine($"- {provider.Name}: {string.Join(", ", provider.SupportedAlgorithms)}");
|
||||
}
|
||||
return 0;
|
||||
});
|
||||
crypto.Add(providers);
|
||||
|
||||
// crypto sign
|
||||
var sign = new Command("sign", "Sign file");
|
||||
// ... add options and handler
|
||||
crypto.Add(sign);
|
||||
|
||||
return crypto;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests
|
||||
|
||||
```csharp
|
||||
using StellaOps.Cli.Crypto;
|
||||
using StellaOps.Cli.Crypto.Gost;
|
||||
using Xunit;
|
||||
|
||||
public class GostCryptoProviderTests
|
||||
{
|
||||
[Fact]
|
||||
public void Name_ReturnsGost()
|
||||
{
|
||||
var provider = new GostCryptoProvider(Options.Create(new GostCryptoOptions()));
|
||||
Assert.Equal("gost", provider.Name);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void SupportedAlgorithms_IncludesGost12_256()
|
||||
{
|
||||
var provider = new GostCryptoProvider(Options.Create(new GostCryptoOptions()));
|
||||
Assert.Contains("GOST12-256", provider.SupportedAlgorithms);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task SignAsync_ProducesSignature()
|
||||
{
|
||||
var provider = new GostCryptoProvider(Options.Create(new GostCryptoOptions()));
|
||||
var data = "test"u8.ToArray();
|
||||
var keyRef = new CryptoKeyReference { KeyId = "test-key", Source = "file" };
|
||||
|
||||
var signature = await provider.SignAsync(data, "GOST12-256", keyRef);
|
||||
|
||||
Assert.NotNull(signature);
|
||||
Assert.NotEmpty(signature);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```csharp
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
using Xunit;
|
||||
|
||||
public class CryptoPluginIntegrationTests
|
||||
{
|
||||
[Fact]
|
||||
public void ServiceProvider_ResolvesAllProviders()
|
||||
{
|
||||
var services = new ServiceCollection();
|
||||
var configuration = new ConfigurationBuilder().Build();
|
||||
|
||||
services.AddDefaultCryptoProviders(configuration);
|
||||
#if STELLAOPS_ENABLE_GOST
|
||||
services.AddGostCryptoProviders(configuration);
|
||||
#endif
|
||||
|
||||
var serviceProvider = services.BuildServiceProvider();
|
||||
var providers = serviceProvider.GetServices<ICryptoProvider>().ToList();
|
||||
|
||||
Assert.NotEmpty(providers);
|
||||
Assert.Contains(providers, p => p.Name == "default");
|
||||
#if STELLAOPS_ENABLE_GOST
|
||||
Assert.Contains(providers, p => p.Name == "gost");
|
||||
#endif
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Packaging
|
||||
|
||||
### NuGet Package Structure
|
||||
|
||||
```
|
||||
StellaOps.Cli (metapackage)
|
||||
├── StellaOps.Cli.Crypto (interfaces)
|
||||
├── StellaOps.Cli.Crypto.Default (always included)
|
||||
├── StellaOps.Cli.Crypto.Gost (optional)
|
||||
├── StellaOps.Cli.Crypto.Eidas (optional)
|
||||
└── StellaOps.Cli.Crypto.Sm (optional)
|
||||
```
|
||||
|
||||
### Distribution Artifacts
|
||||
|
||||
```
|
||||
releases/
|
||||
├── stella-international-linux-x64.tar.gz
|
||||
├── stella-russia-linux-x64.tar.gz
|
||||
├── stella-eu-linux-x64.tar.gz
|
||||
└── stella-china-linux-x64.tar.gz
|
||||
```
|
||||
|
||||
Each artifact contains only the authorized crypto providers for that region.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Command Reference](command-reference.md) - Complete command documentation
|
||||
- [Crypto Plugin Development](crypto-plugins.md) - Detailed plugin development guide
|
||||
- [Compliance Guide](compliance-guide.md) - Regional compliance requirements
|
||||
- [Distribution Matrix](distribution-matrix.md) - Build and distribution guide
|
||||
- [Troubleshooting](troubleshooting.md) - Common plugin issues
|
||||
Reference in New Issue
Block a user