docs consolidation and others
This commit is contained in:
master
460
docs/modules/cli/guides/admin/admin-reference.md
Normal file
460
docs/modules/cli/guides/admin/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](../API_CLI_REFERENCE.md)
|
||||
- [Authority Documentation](../AUTHORITY.md)
|
||||
- [Operational Procedures](../operations/administration.md)
|
||||
@@ -60,4 +60,4 @@ Offline/air-gapped usage patterns for the Stella CLI.
|
||||
## Tips
|
||||
- Keep bundles on read-only media to avoid hash drift.
|
||||
- Use `--dry-run` to validate without writing to registries.
|
||||
- Pair with `docs/airgap/overview.md` and `docs/airgap/sealing-and-egress.md` for policy context.
|
||||
- Pair with `docs/modules/airgap/guides/overview.md` and `docs/modules/airgap/guides/sealing-and-egress.md` for policy context.
|
||||
|
||||
215
docs/modules/cli/guides/commands/audit-pack.md
Normal file
215
docs/modules/cli/guides/commands/audit-pack.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# Audit Pack CLI Commands
|
||||
|
||||
## Overview
|
||||
|
||||
The `stella audit-pack` command provides functionality for exporting, importing, verifying, and replaying audit packs for compliance and verification workflows.
|
||||
|
||||
## Commands
|
||||
|
||||
### Export
|
||||
|
||||
Export an audit pack from a scan result.
|
||||
|
||||
```bash
|
||||
stella audit-pack export --scan-id <id> --output audit-pack.tar.gz
|
||||
|
||||
# With signing
|
||||
stella audit-pack export --scan-id <id> --sign --key signing-key.pem --output audit-pack.tar.gz
|
||||
|
||||
# Minimize size
|
||||
stella audit-pack export --scan-id <id> --minimize --output audit-pack.tar.gz
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--scan-id <id>` - Scan ID to export
|
||||
- `--output <path>` - Output file path (tar.gz)
|
||||
- `--sign` - Sign the audit pack
|
||||
- `--key <path>` - Signing key path (required if --sign)
|
||||
- `--minimize` - Minimize bundle size (only required feeds/policies)
|
||||
- `--name <name>` - Custom pack name
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
stella audit-pack export \
|
||||
--scan-id abc123 \
|
||||
--sign \
|
||||
--key ~/.stella/keys/signing-key.pem \
|
||||
--output compliance-pack-2025-12.tar.gz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Verify
|
||||
|
||||
Verify audit pack integrity and signatures.
|
||||
|
||||
```bash
|
||||
stella audit-pack verify audit-pack.tar.gz
|
||||
|
||||
# Skip signature verification
|
||||
stella audit-pack verify --no-verify-signatures audit-pack.tar.gz
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--no-verify-signatures` - Skip signature verification
|
||||
- `--json` - Output results as JSON
|
||||
|
||||
**Output:**
|
||||
```
|
||||
✅ Audit Pack Verification
|
||||
Pack ID: abc-123-def-456
|
||||
Created: 2025-12-22T00:00:00Z
|
||||
Files: 42 (all digests valid)
|
||||
Signature: Valid (verified with trust root 'prod-ca')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Info
|
||||
|
||||
Display information about an audit pack.
|
||||
|
||||
```bash
|
||||
stella audit-pack info audit-pack.tar.gz
|
||||
|
||||
# JSON output
|
||||
stella audit-pack info --json audit-pack.tar.gz
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
Audit Pack Information
|
||||
Pack ID: abc-123-def-456
|
||||
Name: compliance-pack-2025-12
|
||||
Created: 2025-12-22T00:00:00Z
|
||||
Schema: 1.0.0
|
||||
|
||||
Contents:
|
||||
Run Manifest: included
|
||||
Verdict: included
|
||||
Evidence: included
|
||||
SBOMs: 2 (CycloneDX, SPDX)
|
||||
Attestations: 3
|
||||
VEX Docs: 1
|
||||
Trust Roots: 2
|
||||
|
||||
Bundle:
|
||||
Feeds: 4 (NVD, GHSA, Debian, Alpine)
|
||||
Policies: 2 (default, strict)
|
||||
Size: 42.5 MB
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Replay
|
||||
|
||||
Replay scan from audit pack and compare results.
|
||||
|
||||
```bash
|
||||
stella audit-pack replay audit-pack.tar.gz --output replay-result.json
|
||||
|
||||
# Show differences
|
||||
stella audit-pack replay audit-pack.tar.gz --show-diff
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--output <path>` - Write replay results to file
|
||||
- `--show-diff` - Display verdict differences
|
||||
- `--json` - JSON output format
|
||||
|
||||
**Output:**
|
||||
```
|
||||
✅ Replay Complete
|
||||
Original Verdict Digest: abc123...
|
||||
Replayed Verdict Digest: abc123...
|
||||
Match: Identical
|
||||
Duration: 1.2s
|
||||
|
||||
Verdict Comparison:
|
||||
✅ All findings match
|
||||
✅ All severities match
|
||||
✅ VEX statements identical
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Verify and Replay (Combined)
|
||||
|
||||
Verify integrity and replay in one command.
|
||||
|
||||
```bash
|
||||
stella audit-pack verify-and-replay audit-pack.tar.gz
|
||||
```
|
||||
|
||||
This combines `verify` and `replay` for a complete verification workflow.
|
||||
|
||||
**Output:**
|
||||
```
|
||||
Step 1/2: Verifying audit pack...
|
||||
✅ Integrity verified
|
||||
✅ Signatures valid
|
||||
|
||||
Step 2/2: Replaying scan...
|
||||
✅ Replay complete
|
||||
✅ Verdicts match
|
||||
|
||||
Overall Status: PASSED
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Success |
|
||||
| 1 | Verification failed |
|
||||
| 2 | Replay failed |
|
||||
| 3 | Verdicts don't match |
|
||||
| 10 | Invalid arguments |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
- `STELLAOPS_AUDIT_PACK_VERIFY_SIGS` - Default signature verification (true/false)
|
||||
- `STELLAOPS_AUDIT_PACK_TRUST_ROOTS` - Directory containing trust roots
|
||||
- `STELLAOPS_OFFLINE_BUNDLE` - Offline bundle path for replay
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Full Compliance Workflow
|
||||
|
||||
```bash
|
||||
# 1. Export audit pack from scan
|
||||
stella audit-pack export \
|
||||
--scan-id prod-scan-2025-12-22 \
|
||||
--sign \
|
||||
--key production-signing-key.pem \
|
||||
--output compliance-pack.tar.gz
|
||||
|
||||
# 2. Transfer to auditor environment (air-gapped)
|
||||
scp compliance-pack.tar.gz auditor@secure-env:/audit/
|
||||
|
||||
# 3. Auditor verifies and replays
|
||||
ssh auditor@secure-env
|
||||
stella audit-pack verify-and-replay /audit/compliance-pack.tar.gz
|
||||
|
||||
# Output:
|
||||
# ✅ Verification PASSED
|
||||
# ✅ Replay PASSED - Verdicts identical
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
CLI commands are implemented in:
|
||||
- `src/Cli/StellaOps.Cli/Commands/AuditPackCommands.cs`
|
||||
|
||||
Backend services:
|
||||
- `StellaOps.AuditPack.Services.AuditPackBuilder`
|
||||
- `StellaOps.AuditPack.Services.AuditPackImporter`
|
||||
- `StellaOps.AuditPack.Services.AuditPackReplayer`
|
||||
@@ -56,5 +56,5 @@ Authenticate:
|
||||
stella auth login
|
||||
```
|
||||
|
||||
See: `docs/10_CONCELIER_CLI_QUICKSTART.md` and `docs/modules/concelier/operations/authority-audit-runbook.md`.
|
||||
See: `docs/CONCELIER_CLI_QUICKSTART.md` and `docs/modules/concelier/operations/authority-audit-runbook.md`.
|
||||
|
||||
|
||||
263
docs/modules/cli/guides/commands/drift.md
Normal file
263
docs/modules/cli/guides/commands/drift.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# Drift CLI Reference
|
||||
|
||||
**Sprint:** SPRINT_3600_0004_0001
|
||||
**Task:** UI-024 - Update CLI documentation for drift commands
|
||||
|
||||
## Overview
|
||||
|
||||
The Drift CLI provides commands for detecting and analyzing reachability drift between scan results. Reachability drift occurs when the call paths to vulnerable code change between builds, potentially altering the risk profile of an application.
|
||||
|
||||
## Commands
|
||||
|
||||
### stellaops drift
|
||||
|
||||
Parent command for reachability drift operations.
|
||||
|
||||
```bash
|
||||
stellaops drift <SUBCOMMAND> [OPTIONS]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stellaops drift compare
|
||||
|
||||
Compare reachability between two scans or graph snapshots.
|
||||
|
||||
```bash
|
||||
stellaops drift compare [OPTIONS]
|
||||
```
|
||||
|
||||
#### Required Options
|
||||
|
||||
| Option | Alias | Description |
|
||||
|--------|-------|-------------|
|
||||
| `--base <ID>` | `-b` | Base scan/graph ID or commit SHA for comparison |
|
||||
|
||||
#### Optional Options
|
||||
|
||||
| Option | Alias | Description | Default |
|
||||
|--------|-------|-------------|---------|
|
||||
| `--head <ID>` | `-h` | Head scan/graph ID or commit SHA | latest |
|
||||
| `--image <REF>` | `-i` | Container image reference (digest or tag) | - |
|
||||
| `--repo <REPO>` | `-r` | Repository reference (owner/repo) | - |
|
||||
| `--output <FMT>` | `-o` | Output format: `table`, `json`, `sarif` | `table` |
|
||||
| `--min-severity <SEV>` | | Minimum severity: `critical`, `high`, `medium`, `low`, `info` | `medium` |
|
||||
| `--only-increases` | | Only show sinks with increased reachability | `false` |
|
||||
| `--verbose` | | Enable verbose output | `false` |
|
||||
|
||||
#### Examples
|
||||
|
||||
##### Compare by scan IDs
|
||||
|
||||
```bash
|
||||
stellaops drift compare --base abc123 --head def456
|
||||
```
|
||||
|
||||
##### Compare by commit SHAs
|
||||
|
||||
```bash
|
||||
stellaops drift compare --base HEAD~1 --head HEAD --repo myorg/myapp
|
||||
```
|
||||
|
||||
##### Filter to risk increases only
|
||||
|
||||
```bash
|
||||
stellaops drift compare --base abc123 --only-increases --min-severity high
|
||||
```
|
||||
|
||||
##### Output as JSON
|
||||
|
||||
```bash
|
||||
stellaops drift compare --base abc123 --output json > drift.json
|
||||
```
|
||||
|
||||
##### Output as SARIF for CI integration
|
||||
|
||||
```bash
|
||||
stellaops drift compare --base abc123 --output sarif > drift.sarif
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stellaops drift show
|
||||
|
||||
Display details of a previously computed drift result.
|
||||
|
||||
```bash
|
||||
stellaops drift show [OPTIONS]
|
||||
```
|
||||
|
||||
#### Required Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--id <ID>` | Drift result ID to display |
|
||||
|
||||
#### Optional Options
|
||||
|
||||
| Option | Alias | Description | Default |
|
||||
|--------|-------|-------------|---------|
|
||||
| `--output <FMT>` | `-o` | Output format: `table`, `json`, `sarif` | `table` |
|
||||
| `--expand-paths` | | Show full call paths instead of compressed view | `false` |
|
||||
| `--verbose` | | Enable verbose output | `false` |
|
||||
|
||||
#### Examples
|
||||
|
||||
##### Show drift result
|
||||
|
||||
```bash
|
||||
stellaops drift show --id drift-abc123
|
||||
```
|
||||
|
||||
##### Show with expanded paths
|
||||
|
||||
```bash
|
||||
stellaops drift show --id drift-abc123 --expand-paths
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Formats
|
||||
|
||||
### Table Format (Default)
|
||||
|
||||
Human-readable table output using Spectre.Console:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Reachability Drift (abc123) │
|
||||
├───────────────────────────────┬─────────────────────────────┤
|
||||
│ Metric │ Value │
|
||||
├───────────────────────────────┼─────────────────────────────┤
|
||||
│ Trend │ ↑ Increasing │
|
||||
│ Net Risk Delta │ +3 │
|
||||
│ Increased │ 4 │
|
||||
│ Decreased │ 1 │
|
||||
│ New Sinks │ 2 │
|
||||
│ Removed Sinks │ 0 │
|
||||
└───────────────────────────────┴─────────────────────────────┘
|
||||
|
||||
┌──────────────┬──────────────────────┬───────────────┬─────────────────────────┬───────┐
|
||||
│ Severity │ Sink │ CVE │ Bucket Change │ Delta │
|
||||
├──────────────┼──────────────────────┼───────────────┼─────────────────────────┼───────┤
|
||||
│ CRITICAL │ SqlConnection.Open │ CVE-2024-1234 │ Runtime → Entrypoint │ +2 │
|
||||
│ HIGH │ XmlParser.Parse │ CVE-2024-5678 │ Unknown → Direct │ +1 │
|
||||
└──────────────┴──────────────────────┴───────────────┴─────────────────────────┴───────┘
|
||||
```
|
||||
|
||||
### JSON Format
|
||||
|
||||
Structured JSON for programmatic processing:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "abc123",
|
||||
"comparedAt": "2025-12-18T10:30:00Z",
|
||||
"baseGraphId": "base-graph-id",
|
||||
"headGraphId": "head-graph-id",
|
||||
"summary": {
|
||||
"totalSinks": 42,
|
||||
"increasedReachability": 4,
|
||||
"decreasedReachability": 1,
|
||||
"unchangedReachability": 35,
|
||||
"newSinks": 2,
|
||||
"removedSinks": 0,
|
||||
"riskTrend": "increasing",
|
||||
"netRiskDelta": 3
|
||||
},
|
||||
"driftedSinks": [
|
||||
{
|
||||
"sinkSymbol": "SqlConnection.Open",
|
||||
"cveId": "CVE-2024-1234",
|
||||
"severity": "critical",
|
||||
"previousBucket": "runtime",
|
||||
"currentBucket": "entrypoint",
|
||||
"isRiskIncrease": true,
|
||||
"riskDelta": 2
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### SARIF Format
|
||||
|
||||
SARIF 2.1.0 output for CI/CD integration:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "2.1.0",
|
||||
"$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
|
||||
"runs": [
|
||||
{
|
||||
"tool": {
|
||||
"driver": {
|
||||
"name": "StellaOps Drift",
|
||||
"version": "1.0.0",
|
||||
"informationUri": "https://stellaops.io/docs/drift"
|
||||
}
|
||||
},
|
||||
"results": [
|
||||
{
|
||||
"ruleId": "CVE-2024-1234",
|
||||
"level": "error",
|
||||
"message": {
|
||||
"text": "Reachability changed: runtime → entrypoint"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| `0` | Success (no risk increases or within threshold) |
|
||||
| `1` | Error during execution |
|
||||
| `2` | Risk increases detected |
|
||||
| `3` | Critical risk increases detected |
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
- name: Check Reachability Drift
|
||||
run: |
|
||||
stellaops drift compare \
|
||||
--base ${{ github.event.pull_request.base.sha }} \
|
||||
--head ${{ github.sha }} \
|
||||
--repo ${{ github.repository }} \
|
||||
--output sarif > drift.sarif
|
||||
continue-on-error: true
|
||||
|
||||
- name: Upload SARIF
|
||||
uses: github/codeql-action/upload-sarif@v2
|
||||
with:
|
||||
sarif_file: drift.sarif
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
drift-check:
|
||||
script:
|
||||
- stellaops drift compare --base $CI_MERGE_REQUEST_DIFF_BASE_SHA --head $CI_COMMIT_SHA --output sarif > drift.sarif
|
||||
artifacts:
|
||||
reports:
|
||||
sast: drift.sarif
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Reachability Analysis](../reachability/README.md)
|
||||
- [Smart-Diff CLI](./smart-diff-cli.md)
|
||||
- [VEX Decisioning](../vex/decisioning.md)
|
||||
558
docs/modules/cli/guides/commands/reachability-reference.md
Normal file
558
docs/modules/cli/guides/commands/reachability-reference.md
Normal file
@@ -0,0 +1,558 @@
|
||||
# Reachability CLI Reference
|
||||
|
||||
**Sprint:** SPRINT_3500_0004_0004
|
||||
**Version:** 1.0.0
|
||||
|
||||
## Overview
|
||||
|
||||
The Reachability CLI commands enable call graph management, reachability computation, and explain queries. All commands support air-gapped operation.
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
### stella reachability
|
||||
|
||||
Manage reachability analysis.
|
||||
|
||||
```bash
|
||||
stella reachability <SUBCOMMAND> [OPTIONS]
|
||||
```
|
||||
|
||||
#### Subcommands
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `compute` | Trigger reachability computation |
|
||||
| `findings` | List reachability findings |
|
||||
| `explain` | Explain reachability verdict |
|
||||
| `explain-all` | Export all explanations |
|
||||
| `summary` | Show reachability summary |
|
||||
| `job-status` | Check computation job status |
|
||||
| `job-logs` | View job logs |
|
||||
| `job-cancel` | Cancel running job |
|
||||
|
||||
---
|
||||
|
||||
### stella reachability compute
|
||||
|
||||
Trigger reachability computation for a scan.
|
||||
|
||||
```bash
|
||||
stella reachability compute [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
| `--max-depth <N>` | Maximum path length to explore | 10 |
|
||||
| `--indirect-resolution <MODE>` | Handle indirect calls: `conservative`, `aggressive`, `skip` | `conservative` |
|
||||
| `--timeout <DURATION>` | Maximum computation time | 300s |
|
||||
| `--parallel` | Enable parallel BFS | `true` |
|
||||
| `--include-runtime` | Merge runtime evidence | `true` |
|
||||
| `--offline` | Run in offline mode | `false` |
|
||||
| `--symbol-db <PATH>` | Symbol resolution database | System default |
|
||||
| `--deterministic` | Enable deterministic mode | `true` |
|
||||
| `--seed <BASE64>` | Random seed for determinism | Auto |
|
||||
| `--graph-digest <HASH>` | Use specific call graph version | Latest |
|
||||
| `--partition-by <KEY>` | Partition analysis: `artifact`, `entrypoint` | — |
|
||||
| `--force` | Force recomputation | `false` |
|
||||
| `--wait` | Wait for completion | `false` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Basic computation
|
||||
stella reachability compute --scan-id $SCAN_ID
|
||||
|
||||
# With custom options
|
||||
stella reachability compute --scan-id $SCAN_ID \
|
||||
--max-depth 20 \
|
||||
--timeout 600s \
|
||||
--indirect-resolution conservative
|
||||
|
||||
# Wait for completion
|
||||
stella reachability compute --scan-id $SCAN_ID --wait
|
||||
|
||||
# Offline computation
|
||||
stella reachability compute --scan-id $SCAN_ID --offline
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella reachability findings
|
||||
|
||||
List reachability findings for a scan.
|
||||
|
||||
```bash
|
||||
stella reachability findings [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
| `--status <STATUS>` | Filter by status (comma-separated) | All |
|
||||
| `--cve <ID>` | Filter by CVE ID | — |
|
||||
| `--purl <PURL>` | Filter by package URL | — |
|
||||
| `--min-confidence <N>` | Minimum confidence (0-1) | 0 |
|
||||
| `--output <PATH>` | Output file path | stdout |
|
||||
| `--output-format <FMT>` | Format: `json`, `yaml`, `table`, `sarif` | `table` |
|
||||
|
||||
#### Status Values
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `UNREACHABLE` | No path found |
|
||||
| `POSSIBLY_REACHABLE` | Path with heuristic edges |
|
||||
| `REACHABLE_STATIC` | Statically proven path |
|
||||
| `REACHABLE_PROVEN` | Runtime confirmed |
|
||||
| `UNKNOWN` | Insufficient data |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# List all findings
|
||||
stella reachability findings --scan-id $SCAN_ID
|
||||
|
||||
# Filter by status
|
||||
stella reachability findings --scan-id $SCAN_ID \
|
||||
--status REACHABLE_STATIC,REACHABLE_PROVEN
|
||||
|
||||
# Export as SARIF for CI
|
||||
stella reachability findings --scan-id $SCAN_ID \
|
||||
--status REACHABLE_STATIC,REACHABLE_PROVEN \
|
||||
--output-format sarif \
|
||||
--output findings.sarif
|
||||
|
||||
# JSON output
|
||||
stella reachability findings --scan-id $SCAN_ID --output-format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella reachability explain
|
||||
|
||||
Explain a reachability verdict.
|
||||
|
||||
```bash
|
||||
stella reachability explain [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
| `--cve <ID>` | CVE ID | Required |
|
||||
| `--purl <PURL>` | Package URL | Required |
|
||||
| `--all-paths` | Show all paths, not just shortest | `false` |
|
||||
| `--max-paths <N>` | Maximum paths to show | 5 |
|
||||
| `--verbose` | Show detailed explanation | `false` |
|
||||
| `--offline` | Run in offline mode | `false` |
|
||||
| `--output <PATH>` | Output file path | stdout |
|
||||
| `--output-format <FMT>` | Format: `json`, `yaml`, `text` | `text` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Explain single finding
|
||||
stella reachability explain --scan-id $SCAN_ID \
|
||||
--cve CVE-2024-1234 \
|
||||
--purl "pkg:npm/lodash@4.17.20"
|
||||
|
||||
# Show all paths
|
||||
stella reachability explain --scan-id $SCAN_ID \
|
||||
--cve CVE-2024-1234 \
|
||||
--purl "pkg:npm/lodash@4.17.20" \
|
||||
--all-paths
|
||||
|
||||
# JSON output
|
||||
stella reachability explain --scan-id $SCAN_ID \
|
||||
--cve CVE-2024-1234 \
|
||||
--purl "pkg:npm/lodash@4.17.20" \
|
||||
--output-format json
|
||||
```
|
||||
|
||||
#### Output Example
|
||||
|
||||
```
|
||||
Status: REACHABLE_STATIC
|
||||
Confidence: 0.70
|
||||
|
||||
Shortest Path (depth=3):
|
||||
[0] MyApp.Controllers.OrdersController::Get(Guid)
|
||||
Entrypoint: HTTP GET /api/orders/{id}
|
||||
[1] MyApp.Services.OrderService::Process(Order)
|
||||
Edge: static (direct_call)
|
||||
[2] Lodash.merge(Object, Object) [VULNERABLE]
|
||||
Edge: static (direct_call)
|
||||
|
||||
Why Reachable:
|
||||
- Static call path exists from HTTP entrypoint /api/orders/{id}
|
||||
- All edges are statically proven (no heuristics)
|
||||
- Vulnerable function Lodash.merge() is directly invoked
|
||||
|
||||
Confidence Factors:
|
||||
staticPathExists: +0.50
|
||||
noHeuristicEdges: +0.20
|
||||
runtimeConfirmed: +0.00
|
||||
|
||||
Alternative Paths: 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella reachability explain-all
|
||||
|
||||
Export all reachability explanations.
|
||||
|
||||
```bash
|
||||
stella reachability explain-all [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
| `--status <STATUS>` | Filter by status | All |
|
||||
| `--output <PATH>` | Output file path | Required |
|
||||
| `--offline` | Run in offline mode | `false` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Export all explanations
|
||||
stella reachability explain-all --scan-id $SCAN_ID --output explanations.json
|
||||
|
||||
# Export only reachable findings
|
||||
stella reachability explain-all --scan-id $SCAN_ID \
|
||||
--status REACHABLE_STATIC,REACHABLE_PROVEN \
|
||||
--output reachable-explanations.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella reachability summary
|
||||
|
||||
Show reachability summary for a scan.
|
||||
|
||||
```bash
|
||||
stella reachability summary [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Show summary
|
||||
stella reachability summary --scan-id $SCAN_ID
|
||||
|
||||
# Output:
|
||||
# Total vulnerabilities: 45
|
||||
# Unreachable: 38 (84%)
|
||||
# Possibly reachable: 4 (9%)
|
||||
# Reachable (static): 2 (4%)
|
||||
# Reachable (proven): 1 (2%)
|
||||
# Unknown: 0 (0%)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella reachability job-status
|
||||
|
||||
Check computation job status.
|
||||
|
||||
```bash
|
||||
stella reachability job-status [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--job-id <ID>` | Job ID | Required |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
stella reachability job-status --job-id reachability-job-001
|
||||
|
||||
# Output:
|
||||
# Status: running
|
||||
# Progress: 67% (8,234 / 12,345 nodes visited)
|
||||
# Started: 2025-12-20T10:00:00Z
|
||||
# Estimated completion: 2025-12-20T10:02:30Z
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Call Graph Commands
|
||||
|
||||
### stella scan graph
|
||||
|
||||
Manage call graphs.
|
||||
|
||||
```bash
|
||||
stella scan graph <SUBCOMMAND> [OPTIONS]
|
||||
```
|
||||
|
||||
#### Subcommands
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `upload` | Upload call graph |
|
||||
| `summary` | Show call graph summary |
|
||||
| `entrypoints` | List entrypoints |
|
||||
| `export` | Export call graph |
|
||||
| `validate` | Validate call graph |
|
||||
| `visualize` | Generate visualization |
|
||||
| `convert` | Convert graph format |
|
||||
| `partition` | Partition large graph |
|
||||
| `merge` | Merge multiple graphs |
|
||||
|
||||
---
|
||||
|
||||
### stella scan graph upload
|
||||
|
||||
Upload a call graph to a scan.
|
||||
|
||||
```bash
|
||||
stella scan graph upload [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
| `--file <PATH>` | Call graph file | Required |
|
||||
| `--format <FMT>` | Format: `json`, `ndjson` | Auto-detect |
|
||||
| `--streaming` | Use streaming upload | `false` |
|
||||
| `--framework <NAME>` | Framework hint | Auto-detect |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Basic upload
|
||||
stella scan graph upload --scan-id $SCAN_ID --file callgraph.json
|
||||
|
||||
# Streaming upload (large graphs)
|
||||
stella scan graph upload --scan-id $SCAN_ID \
|
||||
--file callgraph.ndjson \
|
||||
--format ndjson \
|
||||
--streaming
|
||||
|
||||
# With framework hint
|
||||
stella scan graph upload --scan-id $SCAN_ID \
|
||||
--file callgraph.json \
|
||||
--framework aspnetcore
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella scan graph summary
|
||||
|
||||
Show call graph summary.
|
||||
|
||||
```bash
|
||||
stella scan graph summary [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
stella scan graph summary --scan-id $SCAN_ID
|
||||
|
||||
# Output:
|
||||
# Nodes: 12,345
|
||||
# Edges: 56,789
|
||||
# Entrypoints: 42
|
||||
# Languages: [dotnet, java]
|
||||
# Size: 15.2 MB
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella scan graph entrypoints
|
||||
|
||||
List detected entrypoints.
|
||||
|
||||
```bash
|
||||
stella scan graph entrypoints [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
| `--verbose` | Show detailed info | `false` |
|
||||
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# List entrypoints
|
||||
stella scan graph entrypoints --scan-id $SCAN_ID
|
||||
|
||||
# Output:
|
||||
# Kind | Route | Framework | Node
|
||||
# ─────────┼─────────────────────┼─────────────┼────────────────
|
||||
# http | GET /api/orders | aspnetcore | OrdersController::Get
|
||||
# http | POST /api/orders | aspnetcore | OrdersController::Create
|
||||
# grpc | OrderService.Get | grpc-dotnet | OrderService::GetOrder
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella scan graph validate
|
||||
|
||||
Validate call graph structure.
|
||||
|
||||
```bash
|
||||
stella scan graph validate [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Validate uploaded graph | — |
|
||||
| `--file <PATH>` | Validate local file | — |
|
||||
| `--strict` | Enable strict validation | `false` |
|
||||
|
||||
#### Validation Checks
|
||||
|
||||
- All edge targets exist as nodes
|
||||
- Entrypoints reference valid nodes
|
||||
- No orphan nodes
|
||||
- No cycles in entrypoint definitions
|
||||
- Schema compliance
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Validate uploaded graph
|
||||
stella scan graph validate --scan-id $SCAN_ID
|
||||
|
||||
# Validate before upload
|
||||
stella scan graph validate --file callgraph.json --strict
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella scan graph visualize
|
||||
|
||||
Generate call graph visualization.
|
||||
|
||||
```bash
|
||||
stella scan graph visualize [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
| `--node <ID>` | Center on specific node | — |
|
||||
| `--depth <N>` | Visualization depth | 3 |
|
||||
| `--output <PATH>` | Output file (SVG/PNG/DOT) | Required |
|
||||
| `--format <FMT>` | Format: `svg`, `png`, `dot` | `svg` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Visualize subgraph
|
||||
stella scan graph visualize --scan-id $SCAN_ID \
|
||||
--node sha256:node123... \
|
||||
--depth 3 \
|
||||
--output subgraph.svg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Options
|
||||
|
||||
### Authentication
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--token <TOKEN>` | OAuth bearer token |
|
||||
| `--token-file <PATH>` | File containing token |
|
||||
| `--profile <NAME>` | Use named profile |
|
||||
|
||||
### Output
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--quiet` | Suppress non-error output |
|
||||
| `--verbose` | Enable verbose output |
|
||||
| `--debug` | Enable debug logging |
|
||||
| `--no-color` | Disable colored output |
|
||||
|
||||
### Connection
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--endpoint <URL>` | Scanner API endpoint |
|
||||
| `--timeout <DURATION>` | Request timeout |
|
||||
| `--insecure` | Skip TLS verification |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `STELLA_TOKEN` | OAuth token |
|
||||
| `STELLA_ENDPOINT` | API endpoint |
|
||||
| `STELLA_PROFILE` | Profile name |
|
||||
| `STELLA_OFFLINE` | Offline mode |
|
||||
| `STELLA_SYMBOL_DB` | Symbol database path |
|
||||
|
||||
---
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Success |
|
||||
| 1 | General error |
|
||||
| 2 | Invalid arguments |
|
||||
| 3 | Authentication failed |
|
||||
| 4 | Resource not found |
|
||||
| 5 | Computation failed |
|
||||
| 6 | Network error |
|
||||
| 10 | Timeout |
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Score Proofs CLI Reference](./score-proofs-cli-reference.md)
|
||||
- [Unknowns CLI Reference](./unknowns-cli-reference.md)
|
||||
- [Reachability API Reference](../api/score-proofs-reachability-api-reference.md)
|
||||
- [Reachability Runbook](../operations/reachability-runbook.md)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-20
|
||||
**Version**: 1.0.0
|
||||
**Sprint**: 3500.0004.0004
|
||||
1061
docs/modules/cli/guides/commands/reference.md
Normal file
1061
docs/modules/cli/guides/commands/reference.md
Normal file
File diff suppressed because it is too large
Load Diff
40
docs/modules/cli/guides/commands/sbomer.md
Normal file
40
docs/modules/cli/guides/commands/sbomer.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# stella sbomer (DOCS-CLI-DET-01)
|
||||
|
||||
Offline-first usage of `stella sbomer` verbs with deterministic outputs.
|
||||
|
||||
## Prerequisites
|
||||
- Install CLI from offline bundle; ensure `local-nugets/` is available.
|
||||
- Export images/charts locally; no network access required during commands.
|
||||
|
||||
## Commands
|
||||
- `stella sbomer layer <image>`
|
||||
- Emits deterministic SBOM per layer; options: `--format cyclonedx|spdx`, `--output <path>`, `--deterministic` (default true).
|
||||
- `stella sbomer compose <manifest>`
|
||||
- Merges layer SBOMs with stable ordering; rejects missing hashes.
|
||||
- `stella sbomer drift <baseline> <current>`
|
||||
- Computes drift; returns machine-readable diff with stable ordering.
|
||||
- `stella sbomer verify <sbom> --hash <sha256>`
|
||||
- Validates hash/signature if provided; offline only.
|
||||
|
||||
## Determinism rules
|
||||
- Use fixed sort keys (component name, version, purl) when composing.
|
||||
- All timestamps forced to `1970-01-01T00:00:00Z` unless `--timestamp` supplied.
|
||||
- GUID/UUID generation disabled; use content hashes as IDs.
|
||||
- Outputs written in UTF-8 with LF line endings; no BOM.
|
||||
|
||||
## Examples
|
||||
```bash
|
||||
# generate layer SBOM
|
||||
stella sbomer layer ghcr.io/acme/app:1.2.3 --format cyclonedx --output app.cdx.json
|
||||
|
||||
# compose
|
||||
stella sbomer compose app.cdx.json lib.cdx.json --output combined.cdx.json
|
||||
|
||||
# drift
|
||||
stella sbomer drift baseline.cdx.json combined.cdx.json --output drift.json
|
||||
```
|
||||
|
||||
## Offline tips
|
||||
- Preload registries; set `STELLA_SBOMER_OFFLINE=true` to prevent remote pulls.
|
||||
- Configure cache dir via `STELLA_CACHE_DIR` for reproducible paths.
|
||||
- For air-gapped logs, use `--log-format json` and capture to file for later analysis.
|
||||
450
docs/modules/cli/guides/commands/score-proofs-reference.md
Normal file
450
docs/modules/cli/guides/commands/score-proofs-reference.md
Normal file
@@ -0,0 +1,450 @@
|
||||
# Score Proofs CLI Reference
|
||||
|
||||
**Sprint:** SPRINT_3500_0004_0004
|
||||
**Version:** 1.0.0
|
||||
|
||||
## Overview
|
||||
|
||||
The Score Proofs CLI commands enable score computation, replay, proof verification, and proof bundle management. All commands support air-gapped operation.
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
### stella score
|
||||
|
||||
Compute or replay vulnerability scores.
|
||||
|
||||
```bash
|
||||
stella score <SUBCOMMAND> [OPTIONS]
|
||||
```
|
||||
|
||||
#### Subcommands
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `compute` | Compute scores for a scan |
|
||||
| `replay` | Replay score computation with different inputs |
|
||||
| `show` | Display score details for a scan |
|
||||
| `diff` | Compare scores between runs |
|
||||
| `manifest` | View/export scan manifest |
|
||||
| `inputs` | List scoring inputs |
|
||||
|
||||
---
|
||||
|
||||
### stella score compute
|
||||
|
||||
Compute vulnerability scores for a scan.
|
||||
|
||||
```bash
|
||||
stella score compute [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID to compute scores for | Required |
|
||||
| `--deterministic` | Enable deterministic mode | `true` |
|
||||
| `--seed <BASE64>` | Random seed for determinism | Auto-generated |
|
||||
| `--output <PATH>` | Output file path | stdout |
|
||||
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
|
||||
| `--include-proof` | Include proof ledger in output | `false` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Compute scores
|
||||
stella score compute --scan-id $SCAN_ID
|
||||
|
||||
# Compute with proof output
|
||||
stella score compute --scan-id $SCAN_ID --include-proof --output-format json
|
||||
|
||||
# Compute in deterministic mode with fixed seed
|
||||
stella score compute --scan-id $SCAN_ID --deterministic --seed "AQIDBA=="
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella score replay
|
||||
|
||||
Replay score computation with updated feeds or policies.
|
||||
|
||||
```bash
|
||||
stella score replay [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID to replay | Required |
|
||||
| `--feed-snapshot <HASH>` | Override feed snapshot hash | Current |
|
||||
| `--vex-snapshot <HASH>` | Override VEX snapshot hash | Current |
|
||||
| `--policy-snapshot <HASH>` | Override policy hash | Current |
|
||||
| `--use-original-snapshots` | Use exact original snapshots | `false` |
|
||||
| `--diff` | Show diff from original | `false` |
|
||||
| `--skip-unchanged` | Skip if no input changes | `false` |
|
||||
| `--offline` | Run in offline mode | `false` |
|
||||
| `--bundle <PATH>` | Use offline bundle for replay | — |
|
||||
| `--output <PATH>` | Output file path | stdout |
|
||||
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Replay with current feeds
|
||||
stella score replay --scan-id $SCAN_ID
|
||||
|
||||
# Replay with specific feed snapshot
|
||||
stella score replay --scan-id $SCAN_ID --feed-snapshot sha256:newfeed...
|
||||
|
||||
# Replay and compare with original
|
||||
stella score replay --scan-id $SCAN_ID --diff
|
||||
|
||||
# Replay with original snapshots (exact reproduction)
|
||||
stella score replay --scan-id $SCAN_ID --use-original-snapshots
|
||||
|
||||
# Offline replay
|
||||
stella score replay --scan-id $SCAN_ID --offline --bundle /path/to/bundle.zip
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella score show
|
||||
|
||||
Display score details for a scan.
|
||||
|
||||
```bash
|
||||
stella score show [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
| `--verbose` | Show detailed breakdown | `false` |
|
||||
| `--include-evidence` | Include evidence references | `false` |
|
||||
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Show score summary
|
||||
stella score show --scan-id $SCAN_ID
|
||||
|
||||
# Show detailed breakdown
|
||||
stella score show --scan-id $SCAN_ID --verbose
|
||||
|
||||
# JSON output
|
||||
stella score show --scan-id $SCAN_ID --output-format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella score diff
|
||||
|
||||
Compare scores between two runs.
|
||||
|
||||
```bash
|
||||
stella score diff [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID to compare | Required |
|
||||
| `--original` | Compare with original score | `false` |
|
||||
| `--replayed` | Compare with most recent replay | `false` |
|
||||
| `--base <RUN_ID>` | Base run ID for comparison | — |
|
||||
| `--target <RUN_ID>` | Target run ID for comparison | — |
|
||||
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Compare original vs replayed
|
||||
stella score diff --scan-id $SCAN_ID --original --replayed
|
||||
|
||||
# Compare two specific runs
|
||||
stella score diff --scan-id $SCAN_ID --base run-001 --target run-002
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella score manifest
|
||||
|
||||
View or export scan manifest.
|
||||
|
||||
```bash
|
||||
stella score manifest [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
| `--output <PATH>` | Output file path | stdout |
|
||||
| `--include-dsse` | Include DSSE envelope | `false` |
|
||||
| `--verify` | Verify DSSE signature | `false` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# View manifest
|
||||
stella score manifest --scan-id $SCAN_ID
|
||||
|
||||
# Export with DSSE
|
||||
stella score manifest --scan-id $SCAN_ID --include-dsse --output manifest.json
|
||||
|
||||
# Verify manifest signature
|
||||
stella score manifest --scan-id $SCAN_ID --verify
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Proof Commands
|
||||
|
||||
### stella proof
|
||||
|
||||
Manage proof bundles.
|
||||
|
||||
```bash
|
||||
stella proof <SUBCOMMAND> [OPTIONS]
|
||||
```
|
||||
|
||||
#### Subcommands
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `verify` | Verify a proof bundle |
|
||||
| `download` | Download proof bundle |
|
||||
| `export` | Export proof bundle |
|
||||
| `inspect` | Inspect proof bundle contents |
|
||||
| `status` | Check proof status |
|
||||
| `list` | List proofs for a scan |
|
||||
| `retrieve` | Retrieve from cold storage |
|
||||
|
||||
---
|
||||
|
||||
### stella proof verify
|
||||
|
||||
Verify a proof bundle.
|
||||
|
||||
```bash
|
||||
stella proof verify [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--bundle-id <HASH>` | Proof bundle ID (sha256:...) | — |
|
||||
| `--bundle <PATH>` | Local proof bundle file | — |
|
||||
| `--offline` | Skip Rekor verification | `false` |
|
||||
| `--skip-rekor` | Alias for --offline | `false` |
|
||||
| `--check-rekor` | Force Rekor verification | `false` |
|
||||
| `--trust-anchor <PATH>` | Trust anchor file | System default |
|
||||
| `--public-key <PATH>` | Public key file | — |
|
||||
| `--self-contained` | Use embedded trust anchors | `false` |
|
||||
| `--verbose` | Show detailed verification | `false` |
|
||||
| `--check <CHECK>` | Verify specific check only | All |
|
||||
|
||||
#### Verification Checks
|
||||
|
||||
| Check | Description |
|
||||
|-------|-------------|
|
||||
| `signatureValid` | DSSE signature verification |
|
||||
| `idRecomputed` | Content-addressed ID match |
|
||||
| `merklePathValid` | Merkle tree construction |
|
||||
| `rekorInclusion` | Transparency log entry |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Verify online
|
||||
stella proof verify --bundle-id sha256:proof123...
|
||||
|
||||
# Verify offline
|
||||
stella proof verify --bundle proof.zip --offline
|
||||
|
||||
# Verify with specific trust anchor
|
||||
stella proof verify --bundle proof.zip --offline --trust-anchor anchors.json
|
||||
|
||||
# Verify specific check
|
||||
stella proof verify --bundle-id sha256:proof123... --check signatureValid
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella proof download
|
||||
|
||||
Download proof bundle.
|
||||
|
||||
```bash
|
||||
stella proof download [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
| `--root-hash <HASH>` | Specific proof root hash | Latest |
|
||||
| `--output <PATH>` | Output file path | `proof-{scanId}.zip` |
|
||||
| `--all` | Download all proofs for scan | `false` |
|
||||
| `--output-dir <PATH>` | Output directory (with --all) | `.` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Download latest proof
|
||||
stella proof download --scan-id $SCAN_ID --output proof.zip
|
||||
|
||||
# Download specific proof
|
||||
stella proof download --scan-id $SCAN_ID --root-hash sha256:proof123... --output proof.zip
|
||||
|
||||
# Download all proofs
|
||||
stella proof download --scan-id $SCAN_ID --all --output-dir ./proofs/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella proof export
|
||||
|
||||
Export proof bundle with additional data.
|
||||
|
||||
```bash
|
||||
stella proof export [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan ID | Required |
|
||||
| `--portable` | Create self-contained portable bundle | `false` |
|
||||
| `--include-manifest` | Include scan manifest | `true` |
|
||||
| `--include-chain` | Include full proof chain | `false` |
|
||||
| `--include-trust-anchors` | Include trust anchor keys | `false` |
|
||||
| `--output <PATH>` | Output file path | Required |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Export standard bundle
|
||||
stella proof export --scan-id $SCAN_ID --output proof-bundle.zip
|
||||
|
||||
# Export portable bundle (for offline verification)
|
||||
stella proof export --scan-id $SCAN_ID --portable --include-trust-anchors --output portable.zip
|
||||
|
||||
# Export with full chain
|
||||
stella proof export --scan-id $SCAN_ID --include-chain --output full-bundle.zip
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella proof inspect
|
||||
|
||||
Inspect proof bundle contents.
|
||||
|
||||
```bash
|
||||
stella proof inspect [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--bundle <PATH>` | Proof bundle file | Required |
|
||||
| `--output-dir <PATH>` | Extract to directory | — |
|
||||
| `--show-manifest` | Display manifest | `false` |
|
||||
| `--show-proof` | Display proof nodes | `false` |
|
||||
| `--show-meta` | Display metadata | `false` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# List bundle contents
|
||||
stella proof inspect --bundle proof.zip
|
||||
|
||||
# Extract and inspect
|
||||
stella proof inspect --bundle proof.zip --output-dir ./inspection/
|
||||
|
||||
# Show manifest
|
||||
stella proof inspect --bundle proof.zip --show-manifest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Options
|
||||
|
||||
### Authentication
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--token <TOKEN>` | OAuth bearer token |
|
||||
| `--token-file <PATH>` | File containing token |
|
||||
| `--profile <NAME>` | Use named profile |
|
||||
|
||||
### Output
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--quiet` | Suppress non-error output |
|
||||
| `--verbose` | Enable verbose output |
|
||||
| `--debug` | Enable debug logging |
|
||||
| `--no-color` | Disable colored output |
|
||||
|
||||
### Connection
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--endpoint <URL>` | Scanner API endpoint |
|
||||
| `--timeout <DURATION>` | Request timeout (e.g., 30s, 5m) |
|
||||
| `--insecure` | Skip TLS verification (dev only) |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description | Equivalent Option |
|
||||
|----------|-------------|-------------------|
|
||||
| `STELLA_TOKEN` | OAuth token | `--token` |
|
||||
| `STELLA_ENDPOINT` | API endpoint | `--endpoint` |
|
||||
| `STELLA_PROFILE` | Profile name | `--profile` |
|
||||
| `STELLA_OFFLINE` | Offline mode | `--offline` |
|
||||
| `STELLA_TRUST_ANCHOR` | Trust anchor path | `--trust-anchor` |
|
||||
|
||||
---
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Success |
|
||||
| 1 | General error |
|
||||
| 2 | Invalid arguments |
|
||||
| 3 | Authentication failed |
|
||||
| 4 | Resource not found |
|
||||
| 5 | Verification failed |
|
||||
| 6 | Network error |
|
||||
| 10 | Timeout |
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Reachability CLI Reference](./reachability-cli-reference.md)
|
||||
- [Unknowns CLI Reference](./unknowns-cli-reference.md)
|
||||
- [Score Proofs API Reference](../api/score-proofs-reachability-api-reference.md)
|
||||
- [Score Proofs Runbook](../operations/score-proofs-runbook.md)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-20
|
||||
**Version**: 1.0.0
|
||||
**Sprint**: 3500.0004.0004
|
||||
284
docs/modules/cli/guides/commands/smart-diff.md
Normal file
284
docs/modules/cli/guides/commands/smart-diff.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# Smart-Diff CLI Reference
|
||||
|
||||
**Sprint:** SPRINT_3500_0001_0001
|
||||
**Task:** SDIFF-MASTER-0008 - Update CLI documentation with smart-diff commands
|
||||
|
||||
## Overview
|
||||
|
||||
Smart-Diff analyzes changes between container image versions to identify material risk changes. It detects reachability shifts, VEX status changes, binary hardening regressions, and intelligence signal updates.
|
||||
|
||||
## Commands
|
||||
|
||||
### stellaops smart-diff
|
||||
|
||||
Compare two artifacts and report material risk changes.
|
||||
|
||||
```bash
|
||||
stellaops smart-diff [OPTIONS]
|
||||
```
|
||||
|
||||
#### Required Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--base <ARTIFACT>` | Base artifact (image digest, SBOM path, or purl) |
|
||||
| `--target <ARTIFACT>` | Target artifact to compare against base |
|
||||
|
||||
#### Output Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--output <PATH>` | Output file path | stdout |
|
||||
| `--output-format <FMT>` | Output format: `json`, `yaml`, `table`, `sarif` | `table` |
|
||||
| `--output-dir <DIR>` | Output directory for bundle format | - |
|
||||
| `--include-proofs` | Include proof ledger in output | `false` |
|
||||
| `--include-evidence` | Include raw evidence data | `false` |
|
||||
| `--pretty` | Pretty-print JSON/YAML output | `false` |
|
||||
|
||||
#### Analysis Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--rules <PATH>` | Custom detection rules file | built-in |
|
||||
| `--config <PATH>` | Scoring configuration file | default config |
|
||||
| `--tier <TIER>` | Filter by evidence tier: `imported`, `executed`, `tainted_sink` | all |
|
||||
| `--min-priority <N>` | Minimum priority score (0-1) | 0.0 |
|
||||
| `--include-unchanged` | Include unchanged findings | `false` |
|
||||
|
||||
#### Feed Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--feed-snapshot <HASH>` | Use specific feed snapshot | latest |
|
||||
| `--offline` | Run in offline mode | `false` |
|
||||
| `--feed-dir <PATH>` | Local feed directory | - |
|
||||
|
||||
### Examples
|
||||
|
||||
#### Basic Comparison
|
||||
|
||||
```bash
|
||||
# Compare two image versions
|
||||
stellaops smart-diff \
|
||||
--base registry.example.com/app:v1.0.0 \
|
||||
--target registry.example.com/app:v1.1.0
|
||||
|
||||
# Output:
|
||||
# Smart-Diff Report: app:v1.0.0 → app:v1.1.0
|
||||
# ═══════════════════════════════════════════
|
||||
#
|
||||
# Summary:
|
||||
# Total Changes: 5
|
||||
# Risk Increased: 2
|
||||
# Risk Decreased: 3
|
||||
# Hardening Regressions: 1
|
||||
#
|
||||
# Material Changes:
|
||||
# ┌─────────────────┬──────────────────┬──────────┬──────────┐
|
||||
# │ Vulnerability │ Component │ Change │ Priority │
|
||||
# ├─────────────────┼──────────────────┼──────────┼──────────┤
|
||||
# │ CVE-2024-1234 │ lodash@4.17.20 │ +reach │ 0.85 │
|
||||
# │ CVE-2024-5678 │ requests@2.28.0 │ +kev │ 0.95 │
|
||||
# │ CVE-2024-9999 │ urllib3@1.26.0 │ -reach │ 0.60 │
|
||||
# └─────────────────┴──────────────────┴──────────┴──────────┘
|
||||
```
|
||||
|
||||
#### SARIF Output for CI/CD
|
||||
|
||||
```bash
|
||||
# Generate SARIF for GitHub Actions
|
||||
stellaops smart-diff \
|
||||
--base app:v1.0.0 \
|
||||
--target app:v1.1.0 \
|
||||
--output-format sarif \
|
||||
--output results.sarif
|
||||
```
|
||||
|
||||
#### Filtered Analysis
|
||||
|
||||
```bash
|
||||
# Only show high-priority changes
|
||||
stellaops smart-diff \
|
||||
--base app:v1 \
|
||||
--target app:v2 \
|
||||
--min-priority 0.7 \
|
||||
--output-format json
|
||||
|
||||
# Only tainted_sink tier findings
|
||||
stellaops smart-diff \
|
||||
--base app:v1 \
|
||||
--target app:v2 \
|
||||
--tier tainted_sink
|
||||
```
|
||||
|
||||
#### Export with Proofs
|
||||
|
||||
```bash
|
||||
# Full export with proof bundle
|
||||
stellaops smart-diff \
|
||||
--base app:v1 \
|
||||
--target app:v2 \
|
||||
--output-dir ./smart-diff-export \
|
||||
--include-proofs \
|
||||
--include-evidence
|
||||
|
||||
# Creates:
|
||||
# ./smart-diff-export/
|
||||
# ├── manifest.json
|
||||
# ├── diff-results.json
|
||||
# ├── proofs/
|
||||
# └── evidence/
|
||||
```
|
||||
|
||||
#### Offline Mode
|
||||
|
||||
```bash
|
||||
# Use local feeds only
|
||||
STELLAOPS_OFFLINE=true stellaops smart-diff \
|
||||
--base sbom-v1.json \
|
||||
--target sbom-v2.json \
|
||||
--feed-dir /opt/stellaops/feeds
|
||||
```
|
||||
|
||||
### stellaops smart-diff show
|
||||
|
||||
Display results from a saved smart-diff report.
|
||||
|
||||
```bash
|
||||
stellaops smart-diff show [OPTIONS] <INPUT>
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--format <FMT>` | Output format: `table`, `json`, `yaml` | `table` |
|
||||
| `--filter <EXPR>` | Filter expression (e.g., `priority>=0.8`) | - |
|
||||
| `--sort <FIELD>` | Sort field: `priority`, `vuln`, `component` | `priority` |
|
||||
| `--limit <N>` | Maximum results to show | all |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Show top 5 highest priority changes
|
||||
stellaops smart-diff show \
|
||||
--sort priority \
|
||||
--limit 5 \
|
||||
smart-diff-report.json
|
||||
```
|
||||
|
||||
### stellaops smart-diff verify
|
||||
|
||||
Verify a smart-diff report's proof bundle.
|
||||
|
||||
```bash
|
||||
stellaops smart-diff verify [OPTIONS] <INPUT>
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--proof-bundle <PATH>` | Proof bundle path | inferred |
|
||||
| `--public-key <PATH>` | Public key for signature verification | - |
|
||||
| `--strict` | Fail on any warning | `false` |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Verify report integrity
|
||||
stellaops smart-diff verify \
|
||||
--proof-bundle ./proofs \
|
||||
--public-key /path/to/key.pub \
|
||||
smart-diff-report.json
|
||||
|
||||
# Output:
|
||||
# ✓ Manifest hash verified: sha256:abc123...
|
||||
# ✓ Proof ledger valid (45 nodes)
|
||||
# ✓ Root hash matches
|
||||
# ✓ Signature valid (key: CN=scanner.stellaops.io)
|
||||
```
|
||||
|
||||
### stellaops smart-diff replay
|
||||
|
||||
Re-run smart-diff with different feed or config.
|
||||
|
||||
```bash
|
||||
stellaops smart-diff replay [OPTIONS] <SCAN-ID>
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--feed-snapshot <HASH>` | Use specific feed snapshot | latest |
|
||||
| `--config <PATH>` | Different scoring config | original |
|
||||
| `--dry-run` | Preview without saving | `false` |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Replay with new feed
|
||||
stellaops smart-diff replay \
|
||||
--feed-snapshot sha256:abc123... \
|
||||
scan-12345678
|
||||
|
||||
# Preview impact of config change
|
||||
stellaops smart-diff replay \
|
||||
--config strict-scoring.json \
|
||||
--dry-run \
|
||||
scan-12345678
|
||||
```
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Success, no material changes |
|
||||
| 1 | Success, material changes found |
|
||||
| 2 | Success, hardening regressions found |
|
||||
| 3 | Success, KEV additions found |
|
||||
| 10 | Invalid arguments |
|
||||
| 11 | Artifact not found |
|
||||
| 12 | Feed not available |
|
||||
| 20 | Verification failed |
|
||||
| 99 | Internal error |
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `STELLAOPS_OFFLINE` | Run in offline mode |
|
||||
| `STELLAOPS_FEED_DIR` | Local feed directory |
|
||||
| `STELLAOPS_CONFIG` | Default config file |
|
||||
| `STELLAOPS_OUTPUT_FORMAT` | Default output format |
|
||||
|
||||
## Configuration File
|
||||
|
||||
```yaml
|
||||
# ~/.stellaops/smart-diff.yaml
|
||||
defaults:
|
||||
output_format: json
|
||||
include_proofs: true
|
||||
min_priority: 0.3
|
||||
|
||||
scoring:
|
||||
reachability_flip_up_weight: 1.0
|
||||
kev_added_weight: 1.5
|
||||
hardening_regression_weight: 0.8
|
||||
|
||||
rules:
|
||||
custom_path: /path/to/custom-rules.json
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `stellaops scan` - Full vulnerability scan
|
||||
- `stellaops score replay` - Score replay
|
||||
- `stellaops verify-bundle` - Verify proof bundles
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Smart-Diff Air-Gap Workflows](../airgap/smart-diff-airgap-workflows.md)
|
||||
- [SARIF Integration](../ci/sarif-integration.md)
|
||||
- [Scoring Configuration](../ci/scoring-configuration.md)
|
||||
323
docs/modules/cli/guides/commands/triage.md
Normal file
323
docs/modules/cli/guides/commands/triage.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# Triage CLI Reference
|
||||
|
||||
**Sprint:** SPRINT_3600_0001_0001
|
||||
**Task:** TRI-MASTER-0008 - Update CLI documentation with offline commands
|
||||
|
||||
## Overview
|
||||
|
||||
The Triage CLI provides commands for vulnerability triage, decision management, and offline workflows. It supports evidence-based decision making and audit-ready replay tokens.
|
||||
|
||||
## Commands
|
||||
|
||||
### stellaops triage list
|
||||
|
||||
List findings for triage.
|
||||
|
||||
```bash
|
||||
stellaops triage list [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Filter by scan ID | - |
|
||||
| `--status <STATUS>` | Filter: `untriaged`, `affected`, `not_affected`, `wont_fix`, `false_positive` | all |
|
||||
| `--priority-min <N>` | Minimum priority (0-1) | 0 |
|
||||
| `--priority-max <N>` | Maximum priority (0-1) | 1 |
|
||||
| `--sort <FIELD>` | Sort: `priority`, `vuln`, `component`, `created` | `priority` |
|
||||
| `--format <FMT>` | Output: `table`, `json`, `csv` | `table` |
|
||||
| `--limit <N>` | Max results | 50 |
|
||||
| `--workspace <PATH>` | Offline workspace | - |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# List untriaged high-priority findings
|
||||
stellaops triage list \
|
||||
--scan-id scan-12345678 \
|
||||
--status untriaged \
|
||||
--priority-min 0.7
|
||||
|
||||
# Export for review
|
||||
stellaops triage list \
|
||||
--scan-id scan-12345678 \
|
||||
--format json > findings.json
|
||||
```
|
||||
|
||||
### stellaops triage show
|
||||
|
||||
Show finding details with evidence.
|
||||
|
||||
```bash
|
||||
stellaops triage show <FINDING-ID> [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--show-evidence` | Include full evidence | `false` |
|
||||
| `--evidence-first` | Lead with evidence summary | `false` |
|
||||
| `--show-history` | Show decision history | `false` |
|
||||
| `--format <FMT>` | Output: `text`, `json`, `yaml` | `text` |
|
||||
| `--workspace <PATH>` | Offline workspace | - |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Show with evidence
|
||||
stellaops triage show CVE-2024-1234 \
|
||||
--show-evidence \
|
||||
--evidence-first
|
||||
|
||||
# Output:
|
||||
# ═══════════════════════════════════════════
|
||||
# CVE-2024-1234 · pkg:npm/lodash@4.17.20
|
||||
# ═══════════════════════════════════════════
|
||||
#
|
||||
# EVIDENCE
|
||||
# ────────
|
||||
# Reachability: TAINTED_SINK (tier 3/3)
|
||||
# └─ api.js:42 → utils.js:15 → lodash/merge
|
||||
#
|
||||
# Call Stack:
|
||||
# 1. api.js:42 handleUserInput()
|
||||
# 2. utils.js:15 processData()
|
||||
# 3. lodash:merge <vulnerable sink>
|
||||
#
|
||||
# VEX: No statement
|
||||
# EPSS: 0.67 (High)
|
||||
# KEV: No
|
||||
#
|
||||
# VULNERABILITY
|
||||
# ─────────────
|
||||
# CVE-2024-1234: Prototype Pollution in lodash
|
||||
# CVSS: 7.5 (High)
|
||||
# CWE: CWE-1321
|
||||
#
|
||||
# STATUS: untriaged
|
||||
```
|
||||
|
||||
### stellaops triage decide
|
||||
|
||||
Record a triage decision.
|
||||
|
||||
```bash
|
||||
stellaops triage decide <FINDING-ID> [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--status <STATUS>` | Required: `affected`, `not_affected`, `wont_fix`, `false_positive` | - |
|
||||
| `--justification <TEXT>` | Decision justification | - |
|
||||
| `--reviewer <NAME>` | Reviewer identifier | current user |
|
||||
| `--vex-emit` | Emit VEX statement | `false` |
|
||||
| `--workspace <PATH>` | Offline workspace | - |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Mark as not affected
|
||||
stellaops triage decide CVE-2024-1234 \
|
||||
--status not_affected \
|
||||
--justification "Feature gated, unreachable in production"
|
||||
|
||||
# Mark affected and emit VEX
|
||||
stellaops triage decide CVE-2024-5678 \
|
||||
--status affected \
|
||||
--justification "In use, remediation planned" \
|
||||
--vex-emit
|
||||
```
|
||||
|
||||
### stellaops triage batch
|
||||
|
||||
Interactive batch triage mode.
|
||||
|
||||
```bash
|
||||
stellaops triage batch [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan to triage | - |
|
||||
| `--query <EXPR>` | Filter expression | - |
|
||||
| `--input <PATH>` | Offline bundle | - |
|
||||
| `--workspace <PATH>` | Offline workspace | - |
|
||||
|
||||
#### Keyboard Shortcuts
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `j` / `↓` | Next finding |
|
||||
| `k` / `↑` | Previous finding |
|
||||
| `a` | Mark affected |
|
||||
| `n` | Mark not affected |
|
||||
| `w` | Mark won't fix |
|
||||
| `f` | Mark false positive |
|
||||
| `e` | Show full evidence |
|
||||
| `g` | Show graph context |
|
||||
| `u` | Undo last decision |
|
||||
| `/` | Search findings |
|
||||
| `?` | Show help |
|
||||
| `q` | Save and quit |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Interactive triage
|
||||
stellaops triage batch \
|
||||
--scan-id scan-12345678 \
|
||||
--query "priority>=0.5"
|
||||
```
|
||||
|
||||
### stellaops triage export
|
||||
|
||||
Export findings for offline triage.
|
||||
|
||||
```bash
|
||||
stellaops triage export [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Scan to export | required |
|
||||
| `--findings <IDS>` | Specific finding IDs (comma-separated) | - |
|
||||
| `--all-findings` | Export all findings | `false` |
|
||||
| `--include-evidence` | Include evidence data | `true` |
|
||||
| `--include-graph` | Include dependency graph | `true` |
|
||||
| `--output <PATH>` | Output path (.stella.bundle.tgz) | required |
|
||||
| `--sign` | Sign the bundle | `true` |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Export specific findings
|
||||
stellaops triage export \
|
||||
--scan-id scan-12345678 \
|
||||
--findings CVE-2024-1234,CVE-2024-5678 \
|
||||
--output triage-bundle.stella.bundle.tgz
|
||||
```
|
||||
|
||||
### stellaops triage import
|
||||
|
||||
Import offline bundle for triage.
|
||||
|
||||
```bash
|
||||
stellaops triage import [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--input <PATH>` | Bundle path | required |
|
||||
| `--workspace <PATH>` | Target workspace | `~/.stellaops/triage` |
|
||||
| `--verify` | Verify signature | `true` |
|
||||
| `--public-key <PATH>` | Public key for verification | - |
|
||||
|
||||
### stellaops triage export-decisions
|
||||
|
||||
Export decisions for sync.
|
||||
|
||||
```bash
|
||||
stellaops triage export-decisions [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--workspace <PATH>` | Workspace path | required |
|
||||
| `--output <PATH>` | Output path | required |
|
||||
| `--format <FMT>` | Format: `json`, `ndjson` | `json` |
|
||||
| `--sign` | Sign output | `true` |
|
||||
|
||||
### stellaops triage import-decisions
|
||||
|
||||
Import and apply decisions.
|
||||
|
||||
```bash
|
||||
stellaops triage import-decisions [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--input <PATH>` | Decisions file | required |
|
||||
| `--verify` | Verify signatures | `true` |
|
||||
| `--apply` | Apply to server | `false` |
|
||||
| `--dry-run` | Preview only | `false` |
|
||||
| `--conflict-mode <MODE>` | Conflict handling: `keep-local`, `keep-server`, `newest`, `review` | `review` |
|
||||
|
||||
### stellaops triage verify-bundle
|
||||
|
||||
Verify bundle integrity.
|
||||
|
||||
```bash
|
||||
stellaops triage verify-bundle [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--input <PATH>` | Bundle path | required |
|
||||
| `--public-key <PATH>` | Public key | required |
|
||||
| `--strict` | Fail on warnings | `false` |
|
||||
|
||||
### stellaops triage show-token
|
||||
|
||||
Display replay token details.
|
||||
|
||||
```bash
|
||||
stellaops triage show-token <TOKEN>
|
||||
```
|
||||
|
||||
### stellaops triage verify-token
|
||||
|
||||
Verify replay token.
|
||||
|
||||
```bash
|
||||
stellaops triage verify-token <TOKEN> [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--public-key <PATH>` | Public key | required |
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Success |
|
||||
| 1 | Findings require attention |
|
||||
| 10 | Invalid arguments |
|
||||
| 11 | Resource not found |
|
||||
| 20 | Verification failed |
|
||||
| 21 | Signature invalid |
|
||||
| 30 | Conflict detected |
|
||||
| 99 | Internal error |
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `STELLAOPS_OFFLINE` | Enable offline mode |
|
||||
| `STELLAOPS_TRIAGE_WORKSPACE` | Default workspace |
|
||||
| `STELLAOPS_REVIEWER` | Default reviewer name |
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Triage Air-Gap Workflows](../airgap/triage-airgap-workflows.md)
|
||||
- [Keyboard Shortcuts](./keyboard-shortcuts.md)
|
||||
- [Triage API Reference](../api/triage-api.md)
|
||||
532
docs/modules/cli/guides/commands/unknowns-reference.md
Normal file
532
docs/modules/cli/guides/commands/unknowns-reference.md
Normal file
@@ -0,0 +1,532 @@
|
||||
# Unknowns CLI Reference
|
||||
|
||||
**Sprint:** SPRINT_3500_0004_0004
|
||||
**Version:** 1.0.0
|
||||
|
||||
## Overview
|
||||
|
||||
The Unknowns CLI commands manage components that cannot be analyzed due to missing data, unrecognized formats, or resolution failures. These commands support triage workflows, escalation, and resolution tracking.
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
### stella unknowns
|
||||
|
||||
Manage unknowns registry.
|
||||
|
||||
```bash
|
||||
stella unknowns <SUBCOMMAND> [OPTIONS]
|
||||
```
|
||||
|
||||
#### Subcommands
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `list` | List unknowns |
|
||||
| `show` | Show unknown details |
|
||||
| `summary` | Show unknowns summary |
|
||||
| `escalate` | Escalate unknown |
|
||||
| `resolve` | Mark unknown resolved |
|
||||
| `suppress` | Suppress unknown |
|
||||
| `bulk-triage` | Bulk triage unknowns |
|
||||
| `export` | Export unknowns |
|
||||
| `import` | Import unknown resolutions |
|
||||
|
||||
---
|
||||
|
||||
### stella unknowns list
|
||||
|
||||
List unknowns for a scan or workspace.
|
||||
|
||||
```bash
|
||||
stella unknowns list [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Filter by scan ID | — |
|
||||
| `--workspace-id <ID>` | Filter by workspace ID | — |
|
||||
| `--status <STATUS>` | Filter by status | All |
|
||||
| `--category <CAT>` | Filter by category | All |
|
||||
| `--priority <PRI>` | Filter by priority (1-10) | All |
|
||||
| `--min-score <N>` | Minimum 2-factor score | 0 |
|
||||
| `--max-age <DURATION>` | Maximum age | — |
|
||||
| `--purl <PATTERN>` | Filter by PURL pattern | — |
|
||||
| `--output <PATH>` | Output file path | stdout |
|
||||
| `--output-format <FMT>` | Format: `json`, `yaml`, `table`, `csv` | `table` |
|
||||
| `--limit <N>` | Maximum results | 100 |
|
||||
| `--offset <N>` | Pagination offset | 0 |
|
||||
| `--sort <FIELD>` | Sort field | `priority` |
|
||||
| `--order <DIR>` | Sort direction: `asc`, `desc` | `desc` |
|
||||
|
||||
#### Status Values
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `pending` | Awaiting triage |
|
||||
| `escalated` | Escalated for manual review |
|
||||
| `suppressed` | Suppressed (accepted risk) |
|
||||
| `resolved` | Resolved |
|
||||
|
||||
#### Category Values
|
||||
|
||||
| Category | Description |
|
||||
|----------|-------------|
|
||||
| `unmapped_purl` | No CPE/OVAL mapping |
|
||||
| `checksum_miss` | Binary checksum not in DB |
|
||||
| `language_gap` | Unsupported language |
|
||||
| `parsing_failure` | Manifest parsing failed |
|
||||
| `network_timeout` | Feed unavailable |
|
||||
| `unrecognized_format` | Unknown format |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# List all pending unknowns
|
||||
stella unknowns list --status pending
|
||||
|
||||
# List high-priority unknowns
|
||||
stella unknowns list --min-score 7
|
||||
|
||||
# List by category
|
||||
stella unknowns list --category unmapped_purl
|
||||
|
||||
# Export to CSV
|
||||
stella unknowns list --scan-id $SCAN_ID --output-format csv --output unknowns.csv
|
||||
|
||||
# Filter by PURL pattern
|
||||
stella unknowns list --purl "pkg:npm/*"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella unknowns show
|
||||
|
||||
Show details of a specific unknown.
|
||||
|
||||
```bash
|
||||
stella unknowns show [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--id <ID>` | Unknown ID | Required |
|
||||
| `--verbose` | Show extended details | `false` |
|
||||
| `--output-format <FMT>` | Format: `json`, `yaml`, `text` | `text` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Show unknown details
|
||||
stella unknowns show --id unknown-001
|
||||
|
||||
# Output:
|
||||
# ID: unknown-001
|
||||
# PURL: pkg:npm/left-pad@1.3.0
|
||||
# Category: unmapped_purl
|
||||
# Status: pending
|
||||
# Priority: 6
|
||||
# Score: 7.2 (vuln: 3, impact: 4.2)
|
||||
# Created: 2025-12-20T10:00:00Z
|
||||
# Scans Affected: 5
|
||||
# Reason: No CVE/advisory mapping exists for this package
|
||||
|
||||
# Verbose output
|
||||
stella unknowns show --id unknown-001 --verbose
|
||||
|
||||
# JSON output
|
||||
stella unknowns show --id unknown-001 --output-format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella unknowns summary
|
||||
|
||||
Show unknowns summary statistics.
|
||||
|
||||
```bash
|
||||
stella unknowns summary [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Filter by scan ID | — |
|
||||
| `--workspace-id <ID>` | Filter by workspace ID | — |
|
||||
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Summary for workspace
|
||||
stella unknowns summary --workspace-id $WS_ID
|
||||
|
||||
# Output:
|
||||
# Total unknowns: 127
|
||||
#
|
||||
# By Status:
|
||||
# pending: 89
|
||||
# escalated: 15
|
||||
# suppressed: 12
|
||||
# resolved: 11
|
||||
#
|
||||
# By Category:
|
||||
# unmapped_purl: 67
|
||||
# checksum_miss: 34
|
||||
# language_gap: 18
|
||||
# parsing_failure: 8
|
||||
#
|
||||
# Priority Distribution:
|
||||
# High (8-10): 12
|
||||
# Medium (5-7): 45
|
||||
# Low (1-4): 70
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella unknowns escalate
|
||||
|
||||
Escalate an unknown for manual review.
|
||||
|
||||
```bash
|
||||
stella unknowns escalate [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--id <ID>` | Unknown ID | Required |
|
||||
| `--reason <TEXT>` | Escalation reason | — |
|
||||
| `--assignee <USER>` | Assign to user/team | — |
|
||||
| `--severity <LEVEL>` | Severity: `low`, `medium`, `high`, `critical` | `medium` |
|
||||
| `--due-date <DATE>` | Due date (ISO 8601) | — |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Basic escalation
|
||||
stella unknowns escalate --id unknown-001 --reason "Potential supply chain risk"
|
||||
|
||||
# Escalate with assignment
|
||||
stella unknowns escalate --id unknown-001 \
|
||||
--reason "Missing mapping for critical dependency" \
|
||||
--assignee security-team \
|
||||
--severity high \
|
||||
--due-date 2025-12-27
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella unknowns resolve
|
||||
|
||||
Mark an unknown as resolved.
|
||||
|
||||
```bash
|
||||
stella unknowns resolve [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--id <ID>` | Unknown ID | Required |
|
||||
| `--resolution <TYPE>` | Resolution type | Required |
|
||||
| `--comment <TEXT>` | Resolution comment | — |
|
||||
| `--mapping <JSON>` | Custom mapping data | — |
|
||||
| `--evidence <PATH>` | Evidence file | — |
|
||||
|
||||
#### Resolution Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `mapped` | Package/CVE mapping added |
|
||||
| `not_applicable` | Not applicable to context |
|
||||
| `false_positive` | Detection was incorrect |
|
||||
| `accepted_risk` | Risk accepted |
|
||||
| `replaced` | Component replaced |
|
||||
| `removed` | Component removed |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Resolve with mapping
|
||||
stella unknowns resolve --id unknown-001 \
|
||||
--resolution mapped \
|
||||
--comment "Added CPE mapping to internal DB"
|
||||
|
||||
# Resolve as accepted risk
|
||||
stella unknowns resolve --id unknown-001 \
|
||||
--resolution accepted_risk \
|
||||
--comment "Internal component, no external exposure"
|
||||
|
||||
# Resolve with evidence
|
||||
stella unknowns resolve --id unknown-001 \
|
||||
--resolution not_applicable \
|
||||
--evidence ./analysis-report.pdf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella unknowns suppress
|
||||
|
||||
Suppress an unknown (accept risk).
|
||||
|
||||
```bash
|
||||
stella unknowns suppress [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--id <ID>` | Unknown ID | Required |
|
||||
| `--reason <TEXT>` | Suppression reason | Required |
|
||||
| `--expires <DATE>` | Expiration date | — |
|
||||
| `--scope <SCOPE>` | Scope: `scan`, `workspace`, `global` | `scan` |
|
||||
| `--approver <USER>` | Approver name/email | — |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Suppress with expiration
|
||||
stella unknowns suppress --id unknown-001 \
|
||||
--reason "Internal tooling, no risk exposure" \
|
||||
--expires 2026-01-01
|
||||
|
||||
# Workspace-wide suppression
|
||||
stella unknowns suppress --id unknown-001 \
|
||||
--reason "Deprecated component, scheduled for removal" \
|
||||
--scope workspace \
|
||||
--approver security@example.com
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella unknowns bulk-triage
|
||||
|
||||
Bulk triage multiple unknowns.
|
||||
|
||||
```bash
|
||||
stella unknowns bulk-triage [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--file <PATH>` | Triage decisions file (JSON/YAML) | Required |
|
||||
| `--dry-run` | Preview changes | `false` |
|
||||
| `--continue-on-error` | Continue on individual failures | `false` |
|
||||
|
||||
#### Input File Format
|
||||
|
||||
```json
|
||||
{
|
||||
"decisions": [
|
||||
{
|
||||
"id": "unknown-001",
|
||||
"action": "resolve",
|
||||
"resolution": "mapped",
|
||||
"comment": "Added mapping"
|
||||
},
|
||||
{
|
||||
"id": "unknown-002",
|
||||
"action": "suppress",
|
||||
"reason": "Accepted risk",
|
||||
"expires": "2026-01-01"
|
||||
},
|
||||
{
|
||||
"id": "unknown-003",
|
||||
"action": "escalate",
|
||||
"reason": "Needs security review",
|
||||
"assignee": "security-team"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Bulk triage with preview
|
||||
stella unknowns bulk-triage --file triage-decisions.json --dry-run
|
||||
|
||||
# Apply bulk triage
|
||||
stella unknowns bulk-triage --file triage-decisions.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella unknowns export
|
||||
|
||||
Export unknowns data.
|
||||
|
||||
```bash
|
||||
stella unknowns export [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--scan-id <ID>` | Filter by scan ID | — |
|
||||
| `--workspace-id <ID>` | Filter by workspace ID | — |
|
||||
| `--status <STATUS>` | Filter by status | All |
|
||||
| `--output <PATH>` | Output file path | Required |
|
||||
| `--format <FMT>` | Format: `json`, `yaml`, `csv`, `ndjson` | `json` |
|
||||
| `--include-history` | Include resolution history | `false` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Export all unknowns
|
||||
stella unknowns export --workspace-id $WS_ID --output unknowns.json
|
||||
|
||||
# Export pending as CSV
|
||||
stella unknowns export --status pending --output pending.csv --format csv
|
||||
|
||||
# Export with history
|
||||
stella unknowns export --scan-id $SCAN_ID \
|
||||
--output unknowns-history.json \
|
||||
--include-history
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella unknowns import
|
||||
|
||||
Import unknown resolutions.
|
||||
|
||||
```bash
|
||||
stella unknowns import [OPTIONS]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--file <PATH>` | Resolutions file | Required |
|
||||
| `--format <FMT>` | Format: `json`, `yaml`, `csv` | Auto-detect |
|
||||
| `--dry-run` | Preview import | `false` |
|
||||
| `--conflict <MODE>` | Conflict handling: `skip`, `update`, `error` | `skip` |
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Import resolutions
|
||||
stella unknowns import --file resolutions.json
|
||||
|
||||
# Preview import
|
||||
stella unknowns import --file resolutions.json --dry-run
|
||||
|
||||
# Update existing
|
||||
stella unknowns import --file resolutions.json --conflict update
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Options
|
||||
|
||||
### Authentication
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--token <TOKEN>` | OAuth bearer token |
|
||||
| `--token-file <PATH>` | File containing token |
|
||||
| `--profile <NAME>` | Use named profile |
|
||||
|
||||
### Output
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--quiet` | Suppress non-error output |
|
||||
| `--verbose` | Enable verbose output |
|
||||
| `--debug` | Enable debug logging |
|
||||
| `--no-color` | Disable colored output |
|
||||
|
||||
### Connection
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--endpoint <URL>` | Scanner API endpoint |
|
||||
| `--timeout <DURATION>` | Request timeout |
|
||||
| `--insecure` | Skip TLS verification |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `STELLA_TOKEN` | OAuth token |
|
||||
| `STELLA_ENDPOINT` | API endpoint |
|
||||
| `STELLA_PROFILE` | Profile name |
|
||||
| `STELLA_WORKSPACE` | Default workspace ID |
|
||||
|
||||
---
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Success |
|
||||
| 1 | General error |
|
||||
| 2 | Invalid arguments |
|
||||
| 3 | Authentication failed |
|
||||
| 4 | Resource not found |
|
||||
| 5 | Operation failed |
|
||||
| 6 | Network error |
|
||||
|
||||
---
|
||||
|
||||
## Workflows
|
||||
|
||||
### Daily Triage Workflow
|
||||
|
||||
```bash
|
||||
# 1. Check summary
|
||||
stella unknowns summary --workspace-id $WS_ID
|
||||
|
||||
# 2. List high-priority pending
|
||||
stella unknowns list --status pending --min-score 7
|
||||
|
||||
# 3. Review and escalate critical items
|
||||
stella unknowns escalate --id unknown-001 \
|
||||
--reason "Security review needed" \
|
||||
--severity high
|
||||
|
||||
# 4. Bulk resolve known patterns
|
||||
stella unknowns bulk-triage --file daily-resolutions.json
|
||||
```
|
||||
|
||||
### Weekly Report Export
|
||||
|
||||
```bash
|
||||
# Export all unknowns with history
|
||||
stella unknowns export \
|
||||
--workspace-id $WS_ID \
|
||||
--include-history \
|
||||
--output weekly-unknowns-$(date +%Y%m%d).json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Score Proofs CLI Reference](./score-proofs-cli-reference.md)
|
||||
- [Reachability CLI Reference](./reachability-cli-reference.md)
|
||||
- [Unknowns API Reference](../api/score-proofs-reachability-api-reference.md)
|
||||
- [Unknowns Queue Runbook](../operations/unknowns-queue-runbook.md)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-20
|
||||
**Version**: 1.0.0
|
||||
**Sprint**: 3500.0004.0004
|
||||
656
docs/modules/cli/guides/compliance.md
Normal file
656
docs/modules/cli/guides/compliance.md
Normal file
@@ -0,0 +1,656 @@
|
||||
# stella CLI - Regional Cryptographic Compliance Guide
|
||||
|
||||
**Sprint:** SPRINT_4100_0006_0006 - CLI Documentation Overhaul
|
||||
|
||||
## Overview
|
||||
|
||||
StellaOps CLI supports regional cryptographic algorithms to comply with national and international cryptographic standards and regulations. This guide covers compliance requirements for:
|
||||
|
||||
- **GOST** (Russia and CIS states)
|
||||
- **eIDAS** (European Union)
|
||||
- **SM** (China)
|
||||
|
||||
**Important:** Use the distribution appropriate for your jurisdiction. Unauthorized export or use of regional cryptographic implementations may violate export control laws.
|
||||
|
||||
---
|
||||
|
||||
## GOST (Russia and CIS States)
|
||||
|
||||
### Overview
|
||||
|
||||
**GOST** (Государственный стандарт, State Standard) refers to the family of Russian cryptographic standards mandated for government and regulated sectors in Russia and CIS states.
|
||||
|
||||
**Applicable Jurisdictions:** Russia, Belarus, Kazakhstan, Armenia, Kyrgyzstan
|
||||
|
||||
**Legal Basis:**
|
||||
- Federal Law No. 63-FZ "On Electronic Signature" (2011)
|
||||
- FSTEC (Federal Service for Technical and Export Control) regulations
|
||||
- GOST standards published by Rosstandart
|
||||
|
||||
---
|
||||
|
||||
### GOST Standards
|
||||
|
||||
| Standard | Name | Purpose |
|
||||
|----------|------|---------|
|
||||
| **GOST R 34.10-2012** | Digital Signature Algorithm | Elliptic curve digital signatures (256-bit and 512-bit) |
|
||||
| **GOST R 34.11-2012** (Streebog) | Hash Function | Cryptographic hash (256-bit and 512-bit) |
|
||||
| **GOST R 34.12-2015** (Kuznyechik) | Block Cipher | Symmetric encryption (256-bit key) |
|
||||
| **GOST R 34.12-2015** (Magma) | Block Cipher | Legacy symmetric encryption (256-bit key, formerly GOST 28147-89) |
|
||||
| **GOST R 34.13-2015** | Cipher Modes | Modes of operation for block ciphers |
|
||||
|
||||
---
|
||||
|
||||
### Crypto Providers
|
||||
|
||||
The `stella-russia` distribution includes three GOST providers:
|
||||
|
||||
#### 1. CryptoPro CSP (Recommended for Production)
|
||||
|
||||
**Provider:** Commercial CSP from CryptoPro
|
||||
**Certification:** FSTEC-certified
|
||||
**License:** Commercial (required for production use)
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
# Install CryptoPro CSP (requires license)
|
||||
sudo ./install.sh
|
||||
|
||||
# Verify installation
|
||||
/opt/cprocsp/bin/amd64/csptestf -absorb -alg GR3411_2012_256
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Gost:
|
||||
CryptoProCsp:
|
||||
Enabled: true
|
||||
ContainerName: "StellaOps-GOST-2024"
|
||||
ProviderType: 80 # PROV_GOST_2012_256
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella crypto sign \
|
||||
--provider gost \
|
||||
--algorithm GOST12-256 \
|
||||
--key-id gost-prod-key \
|
||||
--file document.pdf \
|
||||
--output document.pdf.sig
|
||||
```
|
||||
|
||||
#### 2. OpenSSL-GOST (Open Source, Non-certified)
|
||||
|
||||
**Provider:** OpenSSL with GOST engine
|
||||
**Certification:** Not FSTEC-certified (development/testing only)
|
||||
**License:** Open source
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
# Install OpenSSL with GOST engine
|
||||
sudo apt install openssl gost-engine
|
||||
|
||||
# Verify installation
|
||||
openssl engine gost
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Gost:
|
||||
OpenSslGost:
|
||||
Enabled: true
|
||||
EnginePath: "/usr/lib/x86_64-linux-gnu/engines-1.1/gost.so"
|
||||
```
|
||||
|
||||
#### 3. PKCS#11 (HSM Support)
|
||||
|
||||
**Provider:** PKCS#11 interface to hardware security modules
|
||||
**Certification:** Depends on HSM (e.g., Rutoken, JaCarta)
|
||||
**License:** Depends on HSM vendor
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Gost:
|
||||
Pkcs11:
|
||||
Enabled: true
|
||||
LibraryPath: "/usr/lib/librtpkcs11ecp.so"
|
||||
SlotId: 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Algorithms
|
||||
|
||||
| Algorithm | Description | GOST Standard | Key Size | Recommended |
|
||||
|-----------|-------------|---------------|----------|-------------|
|
||||
| `GOST12-256` | GOST R 34.10-2012 (256-bit) | GOST R 34.10-2012 | 256-bit | ✅ Yes |
|
||||
| `GOST12-512` | GOST R 34.10-2012 (512-bit) | GOST R 34.10-2012 | 512-bit | ✅ Yes |
|
||||
| `GOST2001` | GOST R 34.10-2001 (legacy) | GOST R 34.10-2001 | 256-bit | ⚠️ Legacy |
|
||||
|
||||
**Recommendation:** Use `GOST12-256` or `GOST12-512` for new implementations. `GOST2001` is supported for backward compatibility only.
|
||||
|
||||
---
|
||||
|
||||
### Configuration Example
|
||||
|
||||
```yaml
|
||||
# appsettings.gost.yaml
|
||||
|
||||
StellaOps:
|
||||
Backend:
|
||||
BaseUrl: "https://api.stellaops.ru"
|
||||
|
||||
Crypto:
|
||||
DefaultProvider: "gost"
|
||||
|
||||
Profiles:
|
||||
- name: "gost-prod-signing"
|
||||
provider: "gost"
|
||||
algorithm: "GOST12-256"
|
||||
keyId: "gost-prod-key-2024"
|
||||
|
||||
- name: "gost-qualified-signature"
|
||||
provider: "gost"
|
||||
algorithm: "GOST12-512"
|
||||
keyId: "gost-qes-key"
|
||||
|
||||
Providers:
|
||||
Gost:
|
||||
CryptoProCsp:
|
||||
Enabled: true
|
||||
ContainerName: "StellaOps-GOST"
|
||||
ProviderType: 80
|
||||
|
||||
Keys:
|
||||
- KeyId: "gost-prod-key-2024"
|
||||
Algorithm: "GOST12-256"
|
||||
Source: "csp"
|
||||
FriendlyName: "Production GOST Signing Key 2024"
|
||||
|
||||
- KeyId: "gost-qes-key"
|
||||
Algorithm: "GOST12-512"
|
||||
Source: "csp"
|
||||
FriendlyName: "Qualified Electronic Signature Key"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Test Vectors (FSTEC Compliance)
|
||||
|
||||
Verify your GOST implementation with official test vectors:
|
||||
|
||||
```bash
|
||||
# Test vector from GOST R 34.11-2012 (Streebog hash)
|
||||
echo -n "012345678901234567890123456789012345678901234567890123456789012" | \
|
||||
openssl dgst -engine gost -streebog256
|
||||
|
||||
# Expected output:
|
||||
# 9d151eefd8590b89daa6ba6cb74af9275dd051026bb149a452fd84e5e57b5500
|
||||
```
|
||||
|
||||
**Official Test Vectors:**
|
||||
- GOST R 34.10-2012: [TC26 GitHub](https://github.com/tc26/gost-crypto/blob/master/test_vectors/)
|
||||
- GOST R 34.11-2012: [RFC 6986 Appendix A](https://datatracker.ietf.org/doc/html/rfc6986#appendix-A)
|
||||
|
||||
---
|
||||
|
||||
### Compliance Checklist
|
||||
|
||||
- [ ] Use FSTEC-certified cryptographic provider (CryptoPro CSP or certified HSM)
|
||||
- [ ] Use GOST R 34.10-2012 (not legacy GOST 2001) for new signatures
|
||||
- [ ] Use GOST R 34.11-2012 (Streebog) for hashing
|
||||
- [ ] Store private keys in certified HSM for qualified signatures
|
||||
- [ ] Maintain key management records per FSTEC requirements
|
||||
- [ ] Obtain certificate from accredited Russian CA for qualified signatures
|
||||
- [ ] Verify signatures against FSTEC test vectors
|
||||
|
||||
---
|
||||
|
||||
### Legal Considerations
|
||||
|
||||
**Export Control:**
|
||||
- GOST implementations are subject to Russian export control laws
|
||||
- Distribution outside Russia/CIS may require special permissions
|
||||
- StellaOps `stella-russia` distribution is authorized for Russia/CIS only
|
||||
|
||||
**Qualified Electronic Signatures:**
|
||||
- Qualified signatures require accredited CA certificate
|
||||
- Accredited CAs: [Ministry of Digital Development list](https://digital.gov.ru/en/)
|
||||
- Private keys must be stored in FSTEC-certified HSM
|
||||
|
||||
---
|
||||
|
||||
## eIDAS (European Union)
|
||||
|
||||
### Overview
|
||||
|
||||
**eIDAS** (electronic IDentification, Authentication and trust Services) is the EU regulation (No 910/2014) governing electronic signatures, seals, and trust services across EU member states.
|
||||
|
||||
**Applicable Jurisdictions:** All 27 EU member states + EEA (Norway, Iceland, Liechtenstein)
|
||||
|
||||
**Legal Basis:**
|
||||
- Regulation (EU) No 910/2014 (eIDAS Regulation)
|
||||
- ETSI standards for implementation
|
||||
- National laws implementing eIDAS
|
||||
|
||||
---
|
||||
|
||||
### Signature Levels
|
||||
|
||||
| Level | Name | Description | Recommended Use |
|
||||
|-------|------|-------------|-----------------|
|
||||
| **QES** | Qualified Electronic Signature | Equivalent to handwritten signature | Contracts, legal documents |
|
||||
| **AES** | Advanced Electronic Signature | High assurance, not qualified | Internal approvals, workflows |
|
||||
| **AdES** | Advanced Electronic Signature | Basic electronic signature | General document signing |
|
||||
|
||||
---
|
||||
|
||||
### Crypto Providers
|
||||
|
||||
The `stella-eu` distribution includes eIDAS-compliant providers:
|
||||
|
||||
#### 1. TSP Client (Remote Qualified Signature)
|
||||
|
||||
**Provider:** Trust Service Provider remote signing client
|
||||
**Certification:** Depends on TSP (must be EU-qualified)
|
||||
**License:** Subscription-based (per TSP)
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Eidas:
|
||||
TspClient:
|
||||
Enabled: true
|
||||
TspUrl: "https://tsp.example.eu/api/v1/sign"
|
||||
ApiKey: "${EIDAS_TSP_API_KEY}"
|
||||
CertificateId: "qes-cert-2024"
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Sign with QES (Qualified Electronic Signature)
|
||||
stella crypto sign \
|
||||
--provider eidas \
|
||||
--algorithm ECDSA-P256-QES \
|
||||
--key-id qes-cert-2024 \
|
||||
--file contract.pdf \
|
||||
--output contract.pdf.sig
|
||||
```
|
||||
|
||||
#### 2. Local Signer (Advanced Signature)
|
||||
|
||||
**Provider:** Local signing with software keys
|
||||
**Certification:** Not qualified (AES/AdES only)
|
||||
**License:** Open source
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Eidas:
|
||||
LocalSigner:
|
||||
Enabled: true
|
||||
KeyStorePath: "/etc/stellaops/eidas-keys"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Standards
|
||||
|
||||
| Standard | Name | Purpose |
|
||||
|----------|------|---------|
|
||||
| **ETSI EN 319 412** | Certificate Profiles | Requirements for certificates (QES, AES) |
|
||||
| **ETSI EN 319 102** | Signature Policies | Signature policy requirements |
|
||||
| **ETSI EN 319 142** | PAdES (PDF Signatures) | PDF Advanced Electronic Signatures |
|
||||
| **ETSI TS 119 432** | Remote Signing | Remote signature creation protocols |
|
||||
| **ETSI EN 319 401** | Trust Service Providers | TSP requirements and policies |
|
||||
|
||||
---
|
||||
|
||||
### Algorithms
|
||||
|
||||
| Algorithm | Description | Signature Level | Recommended |
|
||||
|-----------|-------------|-----------------|-------------|
|
||||
| `ECDSA-P256-QES` | ECDSA with P-256 curve (QES) | QES | ✅ Yes |
|
||||
| `ECDSA-P384-QES` | ECDSA with P-384 curve (QES) | QES | ✅ Yes |
|
||||
| `RSA-2048-QES` | RSA 2048-bit (QES) | QES | ⚠️ Use ECDSA |
|
||||
| `ECDSA-P256-AES` | ECDSA with P-256 curve (AES) | AES | ✅ Yes |
|
||||
|
||||
**Recommendation:** Use ECDSA P-256 or P-384 for new implementations. RSA is supported but ECDSA is preferred.
|
||||
|
||||
---
|
||||
|
||||
### Configuration Example
|
||||
|
||||
```yaml
|
||||
# appsettings.eidas.yaml
|
||||
|
||||
StellaOps:
|
||||
Backend:
|
||||
BaseUrl: "https://api.stellaops.eu"
|
||||
|
||||
Crypto:
|
||||
DefaultProvider: "eidas"
|
||||
|
||||
Profiles:
|
||||
- name: "eidas-qes"
|
||||
provider: "eidas"
|
||||
algorithm: "ECDSA-P256-QES"
|
||||
keyId: "qes-cert-2024"
|
||||
|
||||
- name: "eidas-aes"
|
||||
provider: "eidas"
|
||||
algorithm: "ECDSA-P256-AES"
|
||||
keyId: "aes-cert-2024"
|
||||
|
||||
Providers:
|
||||
Eidas:
|
||||
TspClient:
|
||||
Enabled: true
|
||||
TspUrl: "https://tsp.example.eu/api/v1/sign"
|
||||
ApiKey: "${EIDAS_TSP_API_KEY}"
|
||||
|
||||
# Qualified Trust Service Provider
|
||||
TspProfile:
|
||||
Name: "Example Trust Services Provider"
|
||||
QualifiedStatus: true
|
||||
Country: "DE"
|
||||
TrustedListUrl: "https://tsp.example.eu/tsl.xml"
|
||||
|
||||
Keys:
|
||||
- KeyId: "qes-cert-2024"
|
||||
Algorithm: "ECDSA-P256-QES"
|
||||
Source: "tsp"
|
||||
SignatureLevel: "QES"
|
||||
FriendlyName: "Qualified Electronic Signature 2024"
|
||||
|
||||
- KeyId: "aes-cert-2024"
|
||||
Algorithm: "ECDSA-P256-AES"
|
||||
Source: "local"
|
||||
SignatureLevel: "AES"
|
||||
FriendlyName: "Advanced Electronic Signature 2024"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### EU Trusted List Validation
|
||||
|
||||
Verify TSP is on the EU Trusted List:
|
||||
|
||||
```bash
|
||||
# Download EU Trusted List
|
||||
wget https://ec.europa.eu/tools/lotl/eu-lotl.xml
|
||||
|
||||
# Validate TSP certificate against trusted list
|
||||
stella crypto verify-tsp \
|
||||
--tsp-cert tsp-certificate.pem \
|
||||
--trusted-list eu-lotl.xml
|
||||
```
|
||||
|
||||
**Official EU Trusted List:**
|
||||
- https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/EU+Trusted+Lists
|
||||
|
||||
---
|
||||
|
||||
### Compliance Checklist
|
||||
|
||||
#### For QES (Qualified Electronic Signature):
|
||||
|
||||
- [ ] Use EU-qualified Trust Service Provider (on EU Trusted List)
|
||||
- [ ] Verify TSP certificate is qualified according to ETSI EN 319 412-2
|
||||
- [ ] Use signature policy compliant with ETSI EN 319 102-1
|
||||
- [ ] Include qualified certificate in signature
|
||||
- [ ] Use qualified signature creation device (QSCD) for key storage
|
||||
- [ ] Validate against EU Trusted List before accepting signatures
|
||||
- [ ] Maintain signature validation for 30+ years (long-term validation)
|
||||
|
||||
#### For AES (Advanced Electronic Signature):
|
||||
|
||||
- [ ] Uniquely linked to signatory
|
||||
- [ ] Capable of identifying signatory
|
||||
- [ ] Created using secure signature creation data
|
||||
- [ ] Linked to signed data to detect alterations
|
||||
|
||||
---
|
||||
|
||||
### Legal Considerations
|
||||
|
||||
**Cross-border Recognition:**
|
||||
- QES has same legal effect as handwritten signature in all EU member states
|
||||
- AES/AdES may have varying legal recognition across member states
|
||||
|
||||
**Long-term Validation:**
|
||||
- QES must remain verifiable for decades
|
||||
- Use AdES with long-term validation (LTV) attributes
|
||||
- Timestamp signatures to prove time of signing
|
||||
|
||||
**Data Protection (GDPR):**
|
||||
- eIDAS signatures may contain personal data
|
||||
- Comply with GDPR when processing signature certificates
|
||||
- Obtain consent for processing qualified certificate data
|
||||
|
||||
---
|
||||
|
||||
## SM (China)
|
||||
|
||||
### Overview
|
||||
|
||||
**SM** (ShāngMì, 商密, Commercial Cipher) refers to China's national cryptographic algorithms mandated by OSCCA (Office of State Commercial Cryptography Administration).
|
||||
|
||||
**Applicable Jurisdiction:** People's Republic of China
|
||||
|
||||
**Legal Basis:**
|
||||
- Cryptography Law of PRC (2020)
|
||||
- GM/T standards published by OSCCA
|
||||
- MLPS 2.0 (Multi-Level Protection Scheme 2.0)
|
||||
|
||||
---
|
||||
|
||||
### SM Standards
|
||||
|
||||
| Standard | Name | Purpose |
|
||||
|----------|------|---------|
|
||||
| **GM/T 0003-2012** (SM2) | Public Key Cryptographic Algorithm | Elliptic curve signatures and encryption (256-bit) |
|
||||
| **GM/T 0004-2012** (SM3) | Cryptographic Hash Algorithm | Hash function (256-bit output) |
|
||||
| **GM/T 0002-2012** (SM4) | Block Cipher Algorithm | Symmetric encryption (128-bit key) |
|
||||
| **GM/T 0009-2012** (SM9) | Identity-Based Cryptography | Identity-based encryption and signatures |
|
||||
|
||||
---
|
||||
|
||||
### Crypto Providers
|
||||
|
||||
The `stella-china` distribution includes SM providers:
|
||||
|
||||
#### 1. GmSSL (Open Source)
|
||||
|
||||
**Provider:** GmSSL library
|
||||
**Certification:** Not OSCCA-certified (development/testing only)
|
||||
**License:** Apache 2.0
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
# Install GmSSL
|
||||
sudo apt install gmssl
|
||||
|
||||
# Verify installation
|
||||
gmssl version
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Sm:
|
||||
GmSsl:
|
||||
Enabled: true
|
||||
LibraryPath: "/usr/lib/libgmssl.so"
|
||||
```
|
||||
|
||||
#### 2. Commercial CSP (OSCCA-certified)
|
||||
|
||||
**Provider:** OSCCA-certified commercial CSP
|
||||
**Certification:** OSCCA-certified (required for production)
|
||||
**License:** Commercial (vendor-specific)
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Sm:
|
||||
CommercialCsp:
|
||||
Enabled: true
|
||||
VendorId: "vendor-name"
|
||||
DeviceId: "device-serial"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Algorithms
|
||||
|
||||
| Algorithm | Description | GM Standard | Key Size | Recommended |
|
||||
|-----------|-------------|-------------|----------|-------------|
|
||||
| `SM2` | Elliptic curve signature and encryption | GM/T 0003-2012 | 256-bit | ✅ Yes |
|
||||
| `SM3` | Cryptographic hash | GM/T 0004-2012 | 256-bit output | ✅ Yes |
|
||||
| `SM4` | Block cipher | GM/T 0002-2012 | 128-bit key | ✅ Yes |
|
||||
| `SM9` | Identity-based crypto | GM/T 0009-2012 | 256-bit | ⚠️ Specialized |
|
||||
|
||||
---
|
||||
|
||||
### Configuration Example
|
||||
|
||||
```yaml
|
||||
# appsettings.sm.yaml
|
||||
|
||||
StellaOps:
|
||||
Backend:
|
||||
BaseUrl: "https://api.stellaops.cn"
|
||||
|
||||
Crypto:
|
||||
DefaultProvider: "sm"
|
||||
|
||||
Profiles:
|
||||
- name: "sm-prod-signing"
|
||||
provider: "sm"
|
||||
algorithm: "SM2"
|
||||
keyId: "sm-prod-key-2024"
|
||||
|
||||
Providers:
|
||||
Sm:
|
||||
GmSsl:
|
||||
Enabled: true
|
||||
LibraryPath: "/usr/lib/libgmssl.so"
|
||||
|
||||
Keys:
|
||||
- KeyId: "sm-prod-key-2024"
|
||||
Algorithm: "SM2"
|
||||
Source: "file"
|
||||
FilePath: "/etc/stellaops/keys/sm-key.pem"
|
||||
FriendlyName: "Production SM2 Signing Key 2024"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Usage Example
|
||||
|
||||
```bash
|
||||
# Sign with SM2
|
||||
stella crypto sign \
|
||||
--provider sm \
|
||||
--algorithm SM2 \
|
||||
--key-id sm-prod-key-2024 \
|
||||
--file document.pdf \
|
||||
--output document.pdf.sig
|
||||
|
||||
# Verify SM2 signature
|
||||
stella crypto verify \
|
||||
--provider sm \
|
||||
--algorithm SM2 \
|
||||
--key-id sm-prod-key-2024 \
|
||||
--file document.pdf \
|
||||
--signature document.pdf.sig
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Test Vectors (OSCCA Compliance)
|
||||
|
||||
Verify your SM implementation with official test vectors:
|
||||
|
||||
```bash
|
||||
# Test vector from GM/T 0004-2012 (SM3 hash)
|
||||
echo -n "abc" | gmssl sm3
|
||||
|
||||
# Expected output:
|
||||
# 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0
|
||||
```
|
||||
|
||||
**Official Test Vectors:**
|
||||
- SM2: [GM/T 0003-2012 Appendix A](http://www.gmbz.org.cn/main/viewfile/20180108023812835219.html)
|
||||
- SM3: [GM/T 0004-2012 Appendix A](http://www.gmbz.org.cn/main/viewfile/20180108023528214322.html)
|
||||
|
||||
---
|
||||
|
||||
### Compliance Checklist
|
||||
|
||||
- [ ] Use OSCCA-certified cryptographic product for production
|
||||
- [ ] Use SM2 for digital signatures (not RSA/ECDSA)
|
||||
- [ ] Use SM3 for hashing (not SHA-256)
|
||||
- [ ] Use SM4 for symmetric encryption (not AES)
|
||||
- [ ] Obtain commercial cipher product model certificate
|
||||
- [ ] Register commercial cipher use with local authorities (MLPS 2.0)
|
||||
- [ ] Store keys in OSCCA-certified hardware for sensitive applications
|
||||
|
||||
---
|
||||
|
||||
### Legal Considerations
|
||||
|
||||
**Export Control:**
|
||||
- SM implementations are subject to Chinese export control laws
|
||||
- Distribution outside China may require special permissions
|
||||
- StellaOps `stella-china` distribution is authorized for China only
|
||||
|
||||
**MLPS 2.0 Requirements:**
|
||||
- Level 2+: SM algorithms recommended
|
||||
- Level 3+: SM algorithms mandatory
|
||||
- Level 4+: SM algorithms + OSCCA-certified hardware mandatory
|
||||
|
||||
**Commercial Cipher Regulations:**
|
||||
- Commercial use requires OSCCA product certification
|
||||
- Open-source implementations (GmSSL) for development/testing only
|
||||
- Production systems must use OSCCA-certified CSPs
|
||||
|
||||
---
|
||||
|
||||
## Distribution Selection
|
||||
|
||||
| Your Location | Required Compliance | Distribution |
|
||||
|---------------|---------------------|--------------|
|
||||
| Russia, CIS | GOST R 34.10-2012 (government/regulated) | `stella-russia` |
|
||||
| EU Member State | eIDAS QES (legal documents) | `stella-eu` |
|
||||
| China | SM2/SM3/SM4 (MLPS 2.0 Level 3+) | `stella-china` |
|
||||
| Other | None (international standards) | `stella-international` |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [CLI Overview](README.md) - Installation and quick start
|
||||
- [CLI Architecture](architecture.md) - Plugin architecture
|
||||
- [Command Reference](command-reference.md) - Crypto command usage
|
||||
- [Crypto Plugin Development](crypto-plugins.md) - Develop custom plugins
|
||||
- [Distribution Matrix](distribution-matrix.md) - Build and distribution guide
|
||||
- [Troubleshooting](troubleshooting.md) - Common compliance issues
|
||||
304
docs/modules/cli/guides/crypto/crypto-commands.md
Normal file
304
docs/modules/cli/guides/crypto/crypto-commands.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# Crypto Commands
|
||||
|
||||
**Sprint**: SPRINT_4100_0006_0001
|
||||
**Status**: Implemented
|
||||
**Distribution Support**: International, Russia (GOST), EU (eIDAS), China (SM)
|
||||
|
||||
## Overview
|
||||
|
||||
The `stella crypto` command group provides cryptographic operations with regional compliance support. The available crypto providers depend on your distribution build.
|
||||
|
||||
## Distribution Matrix
|
||||
|
||||
| Distribution | Build Flag | Crypto Standards | Providers |
|
||||
|--------------|------------|------------------|-----------|
|
||||
| **International** | (default) | NIST/FIPS | BouncyCastle (ECDSA, RSA, EdDSA) |
|
||||
| **Russia** | `StellaOpsEnableGOST=true` | GOST R 34.10-2012<br>GOST R 34.11-2012<br>GOST R 34.12-2015 | CryptoPro CSP<br>OpenSSL GOST<br>PKCS#11 GOST |
|
||||
| **EU** | `StellaOpsEnableEIDAS=true` | eIDAS Regulation 910/2014<br>ETSI EN 319 412 | Remote TSP (QES)<br>Local PKCS#12 (AdES) |
|
||||
| **China** | `StellaOpsEnableSM=true` | GM/T 0003-2012 (SM2)<br>GM/T 0004-2012 (SM3)<br>GM/T 0002-2012 (SM4) | Remote CSP<br>GmSSL |
|
||||
|
||||
## Commands
|
||||
|
||||
### `stella crypto sign`
|
||||
|
||||
Sign artifacts using configured crypto provider.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella crypto sign --input <file> [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--input <path>` - Path to file to sign (required)
|
||||
- `--output <path>` - Output path for signature (default: `<input>.sig`)
|
||||
- `--provider <name>` - Override crypto provider (e.g., `gost-cryptopro`, `eidas-tsp`, `sm-remote`)
|
||||
- `--key-id <id>` - Key identifier for signing
|
||||
- `--format <format>` - Signature format: `dsse`, `jws`, `raw` (default: `dsse`)
|
||||
- `--detached` - Create detached signature (default: true)
|
||||
- `--verbose` - Show detailed output
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Sign with default provider
|
||||
stella crypto sign --input artifact.tar.gz
|
||||
|
||||
# Sign with specific GOST provider
|
||||
stella crypto sign --input artifact.tar.gz --provider gost-cryptopro --key-id prod-signing-2025
|
||||
|
||||
# Sign with eIDAS QES
|
||||
stella crypto sign --input contract.pdf --provider eidas-tsp --format jws
|
||||
```
|
||||
|
||||
### `stella crypto verify`
|
||||
|
||||
Verify signatures using configured crypto provider.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella crypto verify --input <file> [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--input <path>` - Path to file to verify (required)
|
||||
- `--signature <path>` - Path to signature file (default: `<input>.sig`)
|
||||
- `--provider <name>` - Override crypto provider
|
||||
- `--trust-policy <path>` - Path to trust policy YAML file
|
||||
- `--format <format>` - Signature format: `dsse`, `jws`, `raw` (auto-detect if omitted)
|
||||
- `--verbose` - Show detailed output
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Verify with auto-detected signature
|
||||
stella crypto verify --input artifact.tar.gz
|
||||
|
||||
# Verify with trust policy
|
||||
stella crypto verify --input artifact.tar.gz --trust-policy ./policies/production-trust.yaml
|
||||
|
||||
# Verify specific provider signature
|
||||
stella crypto verify --input contract.pdf --provider eidas-tsp --signature contract.jws
|
||||
```
|
||||
|
||||
### `stella crypto profiles`
|
||||
|
||||
List available crypto providers and their capabilities.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella crypto profiles [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--details` - Show detailed provider capabilities
|
||||
- `--provider <name>` - Filter by provider name
|
||||
- `--test` - Run provider diagnostics and connectivity tests
|
||||
- `--verbose` - Show detailed output
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# List all providers
|
||||
stella crypto profiles
|
||||
|
||||
# Show detailed capabilities
|
||||
stella crypto profiles --details
|
||||
|
||||
# Test GOST provider connectivity
|
||||
stella crypto profiles --provider gost --test
|
||||
```
|
||||
|
||||
**Output Distribution Info:**
|
||||
|
||||
The `profiles` command shows which regional crypto plugins are enabled:
|
||||
|
||||
```
|
||||
Distribution Information:
|
||||
┌──────────────────┬─────────┐
|
||||
│ Feature │ Status │
|
||||
├──────────────────┼─────────┤
|
||||
│ GOST (Russia) │ Enabled │
|
||||
│ eIDAS (EU) │ Disabled│
|
||||
│ SM (China) │ Disabled│
|
||||
│ BouncyCastle │ Enabled │
|
||||
└──────────────────┴─────────┘
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Quick Start
|
||||
|
||||
1. Copy example configuration:
|
||||
```bash
|
||||
cp src/Cli/StellaOps.Cli/appsettings.crypto.yaml.example appsettings.crypto.yaml
|
||||
```
|
||||
|
||||
2. Set active profile:
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Registry:
|
||||
ActiveProfile: "russia-prod" # or "eu-prod", "china-prod", "international"
|
||||
```
|
||||
|
||||
3. Configure provider credentials:
|
||||
```bash
|
||||
export STELLAOPS_CRYPTO_KEYSTORE_PASSWORD="your-password"
|
||||
export STELLAOPS_GOST_CONTAINER_NAME="your-container" # For GOST
|
||||
export STELLAOPS_EIDAS_TSP_API_KEY="your-api-key" # For eIDAS
|
||||
export STELLAOPS_SM_CSP_API_KEY="your-api-key" # For SM
|
||||
```
|
||||
|
||||
### Profile Configuration
|
||||
|
||||
See `appsettings.crypto.yaml.example` for detailed configuration examples for each distribution.
|
||||
|
||||
**Key sections:**
|
||||
- `Profiles.<profile>.PreferredProviders` - Provider precedence order
|
||||
- `Profiles.<profile>.Providers.<name>.Configuration` - Provider-specific settings
|
||||
- `Validation` - Startup validation rules
|
||||
- `Attestation.Dsse` - DSSE envelope settings
|
||||
- `Kms` - Key Management Service integration
|
||||
|
||||
## Build Instructions
|
||||
|
||||
### International Distribution (Default)
|
||||
|
||||
```bash
|
||||
dotnet build src/Cli/StellaOps.Cli/StellaOps.Cli.csproj
|
||||
```
|
||||
|
||||
### Russia Distribution (GOST)
|
||||
|
||||
```bash
|
||||
dotnet build src/Cli/StellaOps.Cli/StellaOps.Cli.csproj \
|
||||
-p:StellaOpsEnableGOST=true
|
||||
```
|
||||
|
||||
### EU Distribution (eIDAS)
|
||||
|
||||
```bash
|
||||
dotnet build src/Cli/StellaOps.Cli/StellaOps.Cli.csproj \
|
||||
-p:StellaOpsEnableEIDAS=true
|
||||
```
|
||||
|
||||
### China Distribution (SM)
|
||||
|
||||
```bash
|
||||
dotnet build src/Cli/StellaOps.Cli/StellaOps.Cli.csproj \
|
||||
-p:StellaOpsEnableSM=true
|
||||
```
|
||||
|
||||
### Multi-Region Distribution
|
||||
|
||||
```bash
|
||||
dotnet build src/Cli/StellaOps.Cli/StellaOps.Cli.csproj \
|
||||
-p:StellaOpsEnableGOST=true \
|
||||
-p:StellaOpsEnableEIDAS=true \
|
||||
-p:StellaOpsEnableSM=true
|
||||
```
|
||||
|
||||
**Note:** Multi-region builds include all crypto plugins but only activate those configured in the active profile.
|
||||
|
||||
## Compliance Notes
|
||||
|
||||
### GOST (Russia)
|
||||
|
||||
- **Algorithms**: GOST R 34.10-2012 (256/512-bit), GOST R 34.11-2012, GOST R 34.12-2015
|
||||
- **CSP Support**: CryptoPro CSP, OpenSSL GOST engine, PKCS#11 tokens
|
||||
- **Certification**: Certified by FSB (Federal Security Service of Russia)
|
||||
- **Use Cases**: Government contracts, regulated industries in Russia
|
||||
|
||||
### eIDAS (EU)
|
||||
|
||||
- **Regulation**: (EU) No 910/2014
|
||||
- **Signature Levels**:
|
||||
- QES (Qualified Electronic Signature) - Legal equivalence to handwritten
|
||||
- AES (Advanced Electronic Signature)
|
||||
- AdES (Advanced Electronic Signature with validation data)
|
||||
- **Trust Anchors**: EU Trusted List (EUTL)
|
||||
- **Use Cases**: Legal contracts, public procurement, cross-border transactions
|
||||
|
||||
### SM/ShangMi (China)
|
||||
|
||||
- **Standards**: GM/T 0003-2012 (SM2), GM/T 0004-2012 (SM3), GM/T 0002-2012 (SM4)
|
||||
- **Authority**: OSCCA (Office of State Commercial Cryptography Administration)
|
||||
- **Algorithms**: SM2 (elliptic curve), SM3 (hash), SM4 (block cipher)
|
||||
- **Use Cases**: Government systems, financial services, critical infrastructure in China
|
||||
|
||||
## Migration from `cryptoru` CLI
|
||||
|
||||
The standalone `cryptoru` CLI is deprecated. Functionality has been integrated into `stella crypto`:
|
||||
|
||||
| Old Command | New Command |
|
||||
|-------------|-------------|
|
||||
| `cryptoru providers` | `stella crypto profiles` or `stella crypto providers` |
|
||||
| `cryptoru sign` | `stella crypto sign` |
|
||||
|
||||
**Migration Steps:**
|
||||
|
||||
1. Update scripts to use `stella crypto` instead of `cryptoru`
|
||||
2. Update configuration from `cryptoru.yaml` to `appsettings.crypto.yaml`
|
||||
3. The `cryptoru` tool will be removed in StellaOps 2.0 (sunset date: 2025-07-01)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No crypto providers available"
|
||||
|
||||
**Cause**: CLI built without regional crypto flags, or providers not registered.
|
||||
|
||||
**Solution**:
|
||||
1. Check build flags: `stella crypto profiles` shows distribution info
|
||||
2. Rebuild with appropriate flag (e.g., `-p:StellaOpsEnableGOST=true`)
|
||||
3. Verify `appsettings.crypto.yaml` configuration
|
||||
|
||||
### "Provider not found"
|
||||
|
||||
**Cause**: Active profile references unavailable provider.
|
||||
|
||||
**Solution**:
|
||||
1. List available providers: `stella crypto profiles`
|
||||
2. Update active profile in configuration
|
||||
3. Or override with `--provider` flag
|
||||
|
||||
### GOST Provider Initialization Failed
|
||||
|
||||
**Cause**: CryptoPro CSP not installed or configured.
|
||||
|
||||
**Solution**:
|
||||
1. Install CryptoPro CSP 5.0+
|
||||
2. Configure container: `csptest -keyset -enum_cont -fqcn -verifyc`
|
||||
3. Set environment: `export STELLAOPS_GOST_CONTAINER_NAME="your-container"`
|
||||
|
||||
### eIDAS TSP Connection Error
|
||||
|
||||
**Cause**: TSP endpoint unreachable or invalid API key.
|
||||
|
||||
**Solution**:
|
||||
1. Verify TSP endpoint: `curl -I https://tsp.example.eu/api/v1`
|
||||
2. Check API key: `export STELLAOPS_EIDAS_TSP_API_KEY="valid-key"`
|
||||
3. Review TSP logs for authentication errors
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Cryptography Architecture](../architecture/cryptography.md)
|
||||
- [Compliance Matrix](../compliance/crypto-standards.md)
|
||||
- [Configuration Reference](../configuration/crypto.md)
|
||||
- [Air-Gap Operation](../operations/airgap.md#crypto-bundles)
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Key Protection**: Never commit private keys or credentials to version control
|
||||
2. **Environment Variables**: Use secure secret management (Vault, AWS Secrets Manager)
|
||||
3. **Trust Policies**: Validate certificate chains and revocation status
|
||||
4. **Audit Trail**: Enable crypto operation logging for compliance
|
||||
5. **Key Rotation**: Implement periodic key rotation policies
|
||||
6. **Disaster Recovery**: Backup key material securely
|
||||
|
||||
## Support
|
||||
|
||||
For regional crypto compliance questions:
|
||||
- **GOST**: Contact your CryptoPro representative
|
||||
- **eIDAS**: Consult qualified Trust Service Provider (TSP)
|
||||
- **SM**: Contact OSCCA-certified crypto service provider
|
||||
- **General**: StellaOps support team (support@stella-ops.org)
|
||||
1017
docs/modules/cli/guides/crypto/crypto-plugins.md
Normal file
1017
docs/modules/cli/guides/crypto/crypto-plugins.md
Normal file
File diff suppressed because it is too large
Load Diff
694
docs/modules/cli/guides/distribution-matrix.md
Normal file
694
docs/modules/cli/guides/distribution-matrix.md
Normal file
@@ -0,0 +1,694 @@
|
||||
# stella CLI - Build and Distribution Matrix
|
||||
|
||||
**Sprint:** SPRINT_4100_0006_0006 - CLI Documentation Overhaul
|
||||
|
||||
## Overview
|
||||
|
||||
StellaOps CLI is distributed in **four regional variants** to comply with export control regulations and cryptographic standards. Each distribution includes different cryptographic plugins based on regional requirements.
|
||||
|
||||
**Key Principles:**
|
||||
1. **Build-time Selection**: Crypto plugins are conditionally compiled based on build flags
|
||||
2. **Export Compliance**: Each distribution complies with export control laws
|
||||
3. **Deterministic Builds**: Same source + flags = same binary (reproducible builds)
|
||||
4. **Validation**: Automated validation ensures correct plugin inclusion
|
||||
|
||||
---
|
||||
|
||||
## Distribution Matrix
|
||||
|
||||
| Distribution | Crypto Plugins | Build Flag | Target Audience | Export Restrictions |
|
||||
|--------------|----------------|------------|-----------------|---------------------|
|
||||
| **stella-international** | Default (.NET, BouncyCastle) | None | Global (unrestricted) | ✅ No restrictions |
|
||||
| **stella-russia** | Default + GOST | `StellaOpsEnableGOST=true` | Russia, CIS states | ⚠️ Russia/CIS only |
|
||||
| **stella-eu** | Default + eIDAS | `StellaOpsEnableEIDAS=true` | European Union | ⚠️ EU/EEA only |
|
||||
| **stella-china** | Default + SM | `StellaOpsEnableSM=true` | China | ⚠️ China only |
|
||||
|
||||
---
|
||||
|
||||
## Crypto Provider Matrix
|
||||
|
||||
| Provider | International | Russia | EU | China |
|
||||
|----------|---------------|--------|-----|-------|
|
||||
| **.NET Crypto** (RSA, ECDSA, EdDSA) | ✅ | ✅ | ✅ | ✅ |
|
||||
| **BouncyCastle** (Extended algorithms) | ✅ | ✅ | ✅ | ✅ |
|
||||
| **GOST** (R 34.10-2012, R 34.11-2012) | ❌ | ✅ | ❌ | ❌ |
|
||||
| **eIDAS** (QES, AES, AdES) | ❌ | ❌ | ✅ | ❌ |
|
||||
| **SM** (SM2, SM3, SM4) | ❌ | ❌ | ❌ | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## Build Instructions
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- .NET 10 SDK
|
||||
- Git
|
||||
- Docker (for Linux builds on Windows/macOS)
|
||||
|
||||
### Build Environment Setup
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://git.stella-ops.org/stella-ops.org/git.stella-ops.org
|
||||
cd git.stella-ops.org
|
||||
|
||||
# Verify .NET SDK
|
||||
dotnet --version
|
||||
# Expected: 10.0.0 or later
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Building Regional Distributions
|
||||
|
||||
### 1. International Distribution (Default)
|
||||
|
||||
**Includes:** Default crypto providers only (no regional algorithms)
|
||||
|
||||
**Build Command:**
|
||||
```bash
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-linux-x64
|
||||
```
|
||||
|
||||
**Supported Platforms:**
|
||||
- `linux-x64` - Linux x86_64
|
||||
- `linux-arm64` - Linux ARM64
|
||||
- `osx-x64` - macOS Intel
|
||||
- `osx-arm64` - macOS Apple Silicon
|
||||
- `win-x64` - Windows x64
|
||||
|
||||
**Example (all platforms):**
|
||||
```bash
|
||||
# Linux x64
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-linux-x64
|
||||
|
||||
# Linux ARM64
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-arm64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-linux-arm64
|
||||
|
||||
# macOS Intel
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime osx-x64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-osx-x64
|
||||
|
||||
# macOS Apple Silicon
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime osx-arm64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-osx-arm64
|
||||
|
||||
# Windows x64
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime win-x64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-win-x64
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Russia Distribution (GOST)
|
||||
|
||||
**Includes:** Default + GOST crypto providers
|
||||
|
||||
**Build Command:**
|
||||
```bash
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableGOST=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_GOST" \
|
||||
--output dist/stella-russia-linux-x64
|
||||
```
|
||||
|
||||
**Important:** The build flag `StellaOpsEnableGOST=true` conditionally includes GOST plugin projects, and `DefineConstants` enables `#if STELLAOPS_ENABLE_GOST` preprocessor directives.
|
||||
|
||||
**Multi-platform Example:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# build-russia.sh - Build all Russia distributions
|
||||
|
||||
set -e
|
||||
|
||||
RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")
|
||||
|
||||
for runtime in "${RUNTIMES[@]}"; do
|
||||
echo "Building stella-russia for $runtime..."
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime "$runtime" \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableGOST=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_GOST" \
|
||||
--output "dist/stella-russia-$runtime"
|
||||
done
|
||||
|
||||
echo "All Russia distributions built successfully"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. EU Distribution (eIDAS)
|
||||
|
||||
**Includes:** Default + eIDAS crypto providers
|
||||
|
||||
**Build Command:**
|
||||
```bash
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableEIDAS=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_EIDAS" \
|
||||
--output dist/stella-eu-linux-x64
|
||||
```
|
||||
|
||||
**Multi-platform Example:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# build-eu.sh - Build all EU distributions
|
||||
|
||||
set -e
|
||||
|
||||
RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")
|
||||
|
||||
for runtime in "${RUNTIMES[@]}"; do
|
||||
echo "Building stella-eu for $runtime..."
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime "$runtime" \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableEIDAS=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_EIDAS" \
|
||||
--output "dist/stella-eu-$runtime"
|
||||
done
|
||||
|
||||
echo "All EU distributions built successfully"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. China Distribution (SM)
|
||||
|
||||
**Includes:** Default + SM crypto providers
|
||||
|
||||
**Build Command:**
|
||||
```bash
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableSM=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_SM" \
|
||||
--output dist/stella-china-linux-x64
|
||||
```
|
||||
|
||||
**Multi-platform Example:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# build-china.sh - Build all China distributions
|
||||
|
||||
set -e
|
||||
|
||||
RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")
|
||||
|
||||
for runtime in "${RUNTIMES[@]}"; do
|
||||
echo "Building stella-china for $runtime..."
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime "$runtime" \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableSM=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_SM" \
|
||||
--output "dist/stella-china-$runtime"
|
||||
done
|
||||
|
||||
echo "All China distributions built successfully"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build All Distributions
|
||||
|
||||
**Automated build script:**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# build-all.sh - Build all distributions for all platforms
|
||||
|
||||
set -e
|
||||
|
||||
DISTRIBUTIONS=("international" "russia" "eu" "china")
|
||||
RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")
|
||||
|
||||
build_distribution() {
|
||||
local dist=$1
|
||||
local runtime=$2
|
||||
local flags=""
|
||||
|
||||
case $dist in
|
||||
"russia")
|
||||
flags="-p:StellaOpsEnableGOST=true -p:DefineConstants=STELLAOPS_ENABLE_GOST"
|
||||
;;
|
||||
"eu")
|
||||
flags="-p:StellaOpsEnableEIDAS=true -p:DefineConstants=STELLAOPS_ENABLE_EIDAS"
|
||||
;;
|
||||
"china")
|
||||
flags="-p:StellaOpsEnableSM=true -p:DefineConstants=STELLAOPS_ENABLE_SM"
|
||||
;;
|
||||
esac
|
||||
|
||||
echo "Building stella-$dist for $runtime..."
|
||||
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime "$runtime" \
|
||||
--self-contained true \
|
||||
$flags \
|
||||
--output "dist/stella-$dist-$runtime"
|
||||
|
||||
# Create tarball (except Windows)
|
||||
if [[ ! $runtime =~ ^win ]]; then
|
||||
tar -czf "dist/stella-$dist-$runtime.tar.gz" -C "dist/stella-$dist-$runtime" .
|
||||
echo "✅ Created dist/stella-$dist-$runtime.tar.gz"
|
||||
else
|
||||
# Create zip for Windows
|
||||
(cd "dist/stella-$dist-$runtime" && zip -r "../stella-$dist-$runtime.zip" .)
|
||||
echo "✅ Created dist/stella-$dist-$runtime.zip"
|
||||
fi
|
||||
}
|
||||
|
||||
for dist in "${DISTRIBUTIONS[@]}"; do
|
||||
for runtime in "${RUNTIMES[@]}"; do
|
||||
build_distribution "$dist" "$runtime"
|
||||
done
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "🎉 All distributions built successfully!"
|
||||
echo "See dist/ directory for artifacts"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Distribution Validation
|
||||
|
||||
### Automated Validation Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# validate-distribution.sh - Validate distribution has correct plugins
|
||||
|
||||
set -e
|
||||
|
||||
DISTRIBUTION=$1 # international, russia, eu, china
|
||||
BINARY_PATH=$2
|
||||
|
||||
if [ -z "$DISTRIBUTION" ] || [ -z "$BINARY_PATH" ]; then
|
||||
echo "Usage: $0 <distribution> <binary-path>"
|
||||
echo "Example: $0 russia dist/stella-russia-linux-x64/stella"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Validating $DISTRIBUTION distribution: $BINARY_PATH"
|
||||
echo ""
|
||||
|
||||
# Function to check for symbol in binary
|
||||
has_symbol() {
|
||||
local symbol=$1
|
||||
if command -v objdump &> /dev/null; then
|
||||
objdump -p "$BINARY_PATH" 2>/dev/null | grep -q "$symbol"
|
||||
elif command -v nm &> /dev/null; then
|
||||
nm "$BINARY_PATH" 2>/dev/null | grep -q "$symbol"
|
||||
else
|
||||
# Fallback: check if binary contains string
|
||||
strings "$BINARY_PATH" 2>/dev/null | grep -q "$symbol"
|
||||
fi
|
||||
}
|
||||
|
||||
# Validation rules
|
||||
validate_international() {
|
||||
echo "Checking International distribution..."
|
||||
|
||||
# Should NOT contain regional plugins
|
||||
if has_symbol "GostCryptoProvider" || \
|
||||
has_symbol "EidasCryptoProvider" || \
|
||||
has_symbol "SmCryptoProvider"; then
|
||||
echo "❌ FAIL: International distribution contains restricted plugins"
|
||||
return 1
|
||||
fi
|
||||
|
||||
echo "✅ PASS: International distribution valid (no restricted plugins)"
|
||||
return 0
|
||||
}
|
||||
|
||||
validate_russia() {
|
||||
echo "Checking Russia distribution..."
|
||||
|
||||
# Should contain GOST
|
||||
if ! has_symbol "GostCryptoProvider"; then
|
||||
echo "❌ FAIL: Russia distribution missing GOST plugin"
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Should NOT contain eIDAS or SM
|
||||
if has_symbol "EidasCryptoProvider" || has_symbol "SmCryptoProvider"; then
|
||||
echo "❌ FAIL: Russia distribution contains non-GOST regional plugins"
|
||||
return 1
|
||||
fi
|
||||
|
||||
echo "✅ PASS: Russia distribution valid (GOST included, no other regional plugins)"
|
||||
return 0
|
||||
}
|
||||
|
||||
validate_eu() {
|
||||
echo "Checking EU distribution..."
|
||||
|
||||
# Should contain eIDAS
|
||||
if ! has_symbol "EidasCryptoProvider"; then
|
||||
echo "❌ FAIL: EU distribution missing eIDAS plugin"
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Should NOT contain GOST or SM
|
||||
if has_symbol "GostCryptoProvider" || has_symbol "SmCryptoProvider"; then
|
||||
echo "❌ FAIL: EU distribution contains non-eIDAS regional plugins"
|
||||
return 1
|
||||
fi
|
||||
|
||||
echo "✅ PASS: EU distribution valid (eIDAS included, no other regional plugins)"
|
||||
return 0
|
||||
}
|
||||
|
||||
validate_china() {
|
||||
echo "Checking China distribution..."
|
||||
|
||||
# Should contain SM
|
||||
if ! has_symbol "SmCryptoProvider"; then
|
||||
echo "❌ FAIL: China distribution missing SM plugin"
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Should NOT contain GOST or eIDAS
|
||||
if has_symbol "GostCryptoProvider" || has_symbol "EidasCryptoProvider"; then
|
||||
echo "❌ FAIL: China distribution contains non-SM regional plugins"
|
||||
return 1
|
||||
fi
|
||||
|
||||
echo "✅ PASS: China distribution valid (SM included, no other regional plugins)"
|
||||
return 0
|
||||
}
|
||||
|
||||
# Run validation
|
||||
case $DISTRIBUTION in
|
||||
"international")
|
||||
validate_international
|
||||
;;
|
||||
"russia")
|
||||
validate_russia
|
||||
;;
|
||||
"eu")
|
||||
validate_eu
|
||||
;;
|
||||
"china")
|
||||
validate_china
|
||||
;;
|
||||
*)
|
||||
echo "❌ ERROR: Unknown distribution '$DISTRIBUTION'"
|
||||
echo "Valid distributions: international, russia, eu, china"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
exit $?
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Validate Russia distribution
|
||||
./validate-distribution.sh russia dist/stella-russia-linux-x64/stella
|
||||
|
||||
# Output:
|
||||
# Validating russia distribution: dist/stella-russia-linux-x64/stella
|
||||
#
|
||||
# Checking Russia distribution...
|
||||
# ✅ PASS: Russia distribution valid (GOST included, no other regional plugins)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Runtime Validation
|
||||
|
||||
Verify correct plugins are available at runtime:
|
||||
|
||||
```bash
|
||||
# International distribution
|
||||
./stella crypto providers
|
||||
# Expected output:
|
||||
# Available Crypto Providers:
|
||||
# - default (.NET Crypto, BouncyCastle)
|
||||
|
||||
# Russia distribution
|
||||
./stella crypto providers
|
||||
# Expected output:
|
||||
# Available Crypto Providers:
|
||||
# - default (.NET Crypto, BouncyCastle)
|
||||
# - gost (GOST R 34.10-2012, GOST R 34.11-2012)
|
||||
|
||||
# EU distribution
|
||||
./stella crypto providers
|
||||
# Expected output:
|
||||
# Available Crypto Providers:
|
||||
# - default (.NET Crypto, BouncyCastle)
|
||||
# - eidas (QES, AES, AdES)
|
||||
|
||||
# China distribution
|
||||
./stella crypto providers
|
||||
# Expected output:
|
||||
# Available Crypto Providers:
|
||||
# - default (.NET Crypto, BouncyCastle)
|
||||
# - sm (SM2, SM3, SM4)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Packaging
|
||||
|
||||
### Tarball Creation
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# package.sh - Create distribution tarballs
|
||||
|
||||
DIST=$1 # stella-russia-linux-x64
|
||||
OUTPUT_DIR="dist"
|
||||
|
||||
cd "$OUTPUT_DIR/$DIST"
|
||||
|
||||
# Create tarball
|
||||
tar -czf "../$DIST.tar.gz" .
|
||||
|
||||
echo "✅ Created $OUTPUT_DIR/$DIST.tar.gz"
|
||||
```
|
||||
|
||||
### Checksums
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# checksums.sh - Generate checksums for all distributions
|
||||
|
||||
cd dist
|
||||
|
||||
for tarball in *.tar.gz *.zip; do
|
||||
if [ -f "$tarball" ]; then
|
||||
sha256sum "$tarball" >> checksums.txt
|
||||
fi
|
||||
done
|
||||
|
||||
echo "✅ Checksums written to dist/checksums.txt"
|
||||
cat dist/checksums.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions / Gitea Actions
|
||||
|
||||
```yaml
|
||||
name: Build and Release CLI
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'v*'
|
||||
|
||||
jobs:
|
||||
build-matrix:
|
||||
strategy:
|
||||
matrix:
|
||||
distribution: [international, russia, eu, china]
|
||||
runtime: [linux-x64, linux-arm64, osx-x64, osx-arm64, win-x64]
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup .NET
|
||||
uses: actions/setup-dotnet@v4
|
||||
with:
|
||||
dotnet-version: '10.0.x'
|
||||
|
||||
- name: Build Distribution
|
||||
run: |
|
||||
FLAGS=""
|
||||
case "${{ matrix.distribution }}" in
|
||||
"russia")
|
||||
FLAGS="-p:StellaOpsEnableGOST=true -p:DefineConstants=STELLAOPS_ENABLE_GOST"
|
||||
;;
|
||||
"eu")
|
||||
FLAGS="-p:StellaOpsEnableEIDAS=true -p:DefineConstants=STELLAOPS_ENABLE_EIDAS"
|
||||
;;
|
||||
"china")
|
||||
FLAGS="-p:StellaOpsEnableSM=true -p:DefineConstants=STELLAOPS_ENABLE_SM"
|
||||
;;
|
||||
esac
|
||||
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime ${{ matrix.runtime }} \
|
||||
--self-contained true \
|
||||
$FLAGS \
|
||||
--output dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}
|
||||
|
||||
- name: Validate Distribution
|
||||
run: |
|
||||
chmod +x scripts/validate-distribution.sh
|
||||
./scripts/validate-distribution.sh \
|
||||
${{ matrix.distribution }} \
|
||||
dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}/stella
|
||||
|
||||
- name: Create Tarball
|
||||
if: ${{ !contains(matrix.runtime, 'win') }}
|
||||
run: |
|
||||
cd dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}
|
||||
tar -czf ../stella-${{ matrix.distribution }}-${{ matrix.runtime }}.tar.gz .
|
||||
|
||||
- name: Upload Artifact
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: stella-${{ matrix.distribution }}-${{ matrix.runtime }}
|
||||
path: dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}.tar.gz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Distribution Deployment
|
||||
|
||||
### Release Structure
|
||||
|
||||
```
|
||||
releases/
|
||||
├── v2.1.0/
|
||||
│ ├── stella-international-linux-x64.tar.gz
|
||||
│ ├── stella-international-linux-arm64.tar.gz
|
||||
│ ├── stella-international-osx-x64.tar.gz
|
||||
│ ├── stella-international-osx-arm64.tar.gz
|
||||
│ ├── stella-international-win-x64.zip
|
||||
│ ├── stella-russia-linux-x64.tar.gz
|
||||
│ ├── stella-russia-linux-arm64.tar.gz
|
||||
│ ├── stella-russia-osx-x64.tar.gz
|
||||
│ ├── stella-russia-osx-arm64.tar.gz
|
||||
│ ├── stella-russia-win-x64.zip
|
||||
│ ├── stella-eu-linux-x64.tar.gz
|
||||
│ ├── stella-eu-linux-arm64.tar.gz
|
||||
│ ├── stella-eu-osx-x64.tar.gz
|
||||
│ ├── stella-eu-osx-arm64.tar.gz
|
||||
│ ├── stella-eu-win-x64.zip
|
||||
│ ├── stella-china-linux-x64.tar.gz
|
||||
│ ├── stella-china-linux-arm64.tar.gz
|
||||
│ ├── stella-china-osx-x64.tar.gz
|
||||
│ ├── stella-china-osx-arm64.tar.gz
|
||||
│ ├── stella-china-win-x64.zip
|
||||
│ ├── checksums.txt
|
||||
│ └── RELEASE_NOTES.md
|
||||
└── latest -> v2.1.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Download Links
|
||||
|
||||
**Public Release Server:**
|
||||
```
|
||||
https://releases.stella-ops.org/cli/
|
||||
├── latest/
|
||||
│ ├── stella-international-linux-x64.tar.gz
|
||||
│ ├── stella-russia-linux-x64.tar.gz
|
||||
│ ├── stella-eu-linux-x64.tar.gz
|
||||
│ └── stella-china-linux-x64.tar.gz
|
||||
├── v2.1.0/
|
||||
├── v2.0.0/
|
||||
└── checksums.txt
|
||||
```
|
||||
|
||||
**User Installation:**
|
||||
```bash
|
||||
# International (unrestricted)
|
||||
wget https://releases.stella-ops.org/cli/latest/stella-international-linux-x64.tar.gz
|
||||
|
||||
# Russia (GOST)
|
||||
wget https://releases.stella-ops.org/cli/russia/latest/stella-russia-linux-x64.tar.gz
|
||||
|
||||
# EU (eIDAS)
|
||||
wget https://releases.stella-ops.org/cli/eu/latest/stella-eu-linux-x64.tar.gz
|
||||
|
||||
# China (SM)
|
||||
wget https://releases.stella-ops.org/cli/china/latest/stella-china-linux-x64.tar.gz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Legal & Export Control
|
||||
|
||||
### Export Control Statement
|
||||
|
||||
> StellaOps CLI regional distributions contain cryptographic software subject to export control laws.
|
||||
>
|
||||
> - **stella-international**: No export restrictions (standard commercial crypto)
|
||||
> - **stella-russia**: Authorized for Russia and CIS states only
|
||||
> - **stella-eu**: Authorized for EU/EEA member states only
|
||||
> - **stella-china**: Authorized for China only
|
||||
>
|
||||
> Unauthorized export, re-export, or transfer may violate applicable laws. Users are responsible for compliance with export control regulations in their jurisdiction.
|
||||
|
||||
### License Compliance
|
||||
|
||||
All distributions are licensed under **AGPL-3.0-or-later**, with regional plugins subject to additional vendor licenses (e.g., CryptoPro CSP requires commercial license).
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [CLI Overview](README.md) - Installation and quick start
|
||||
- [CLI Architecture](architecture.md) - Plugin architecture
|
||||
- [Command Reference](command-reference.md) - Command usage
|
||||
- [Compliance Guide](compliance-guide.md) - Regional compliance requirements
|
||||
- [Crypto Plugins](crypto-plugins.md) - Plugin development
|
||||
- [Troubleshooting](troubleshooting.md) - Build and validation issues
|
||||
233
docs/modules/cli/guides/keyboard-shortcuts.md
Normal file
233
docs/modules/cli/guides/keyboard-shortcuts.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# Keyboard Shortcuts Reference
|
||||
|
||||
**Sprint:** SPRINT_3600_0001_0001
|
||||
**Task:** TRI-MASTER-0010 - Document keyboard shortcuts in user guide
|
||||
|
||||
## Overview
|
||||
|
||||
StellaOps supports keyboard shortcuts for efficient triage and navigation. Shortcuts are available in the Web UI and CLI interactive modes.
|
||||
|
||||
## Triage View Shortcuts
|
||||
|
||||
### Navigation
|
||||
|
||||
| Key | Action | Context |
|
||||
|-----|--------|---------|
|
||||
| `j` / `↓` | Next finding | Finding list |
|
||||
| `k` / `↑` | Previous finding | Finding list |
|
||||
| `g g` | Go to first finding | Finding list |
|
||||
| `G` | Go to last finding | Finding list |
|
||||
| `Enter` | Open finding details | Finding list |
|
||||
| `Esc` | Close panel / Cancel | Any |
|
||||
|
||||
### Decision Actions
|
||||
|
||||
| Key | Action | Context |
|
||||
|-----|--------|---------|
|
||||
| `a` | Mark as Affected | Finding selected |
|
||||
| `n` | Mark as Not Affected | Finding selected |
|
||||
| `w` | Mark as Won't Fix | Finding selected |
|
||||
| `f` | Mark as False Positive | Finding selected |
|
||||
| `u` | Undo last decision | Any |
|
||||
| `Ctrl+z` | Undo | Any |
|
||||
|
||||
### Evidence & Context
|
||||
|
||||
| Key | Action | Context |
|
||||
|-----|--------|---------|
|
||||
| `e` | Toggle evidence panel | Finding selected |
|
||||
| `g` | Toggle graph view | Finding selected |
|
||||
| `c` | Show call stack | Finding selected |
|
||||
| `v` | Show VEX status | Finding selected |
|
||||
| `p` | Show provenance | Finding selected |
|
||||
| `d` | Show diff | Finding selected |
|
||||
|
||||
### Search & Filter
|
||||
|
||||
| Key | Action | Context |
|
||||
|-----|--------|---------|
|
||||
| `/` | Open search | Global |
|
||||
| `Ctrl+f` | Find in page | Global |
|
||||
| `Ctrl+k` | Quick filter | Global |
|
||||
| `x` | Clear filters | Filter active |
|
||||
|
||||
### View Controls
|
||||
|
||||
| Key | Action | Context |
|
||||
|-----|--------|---------|
|
||||
| `1` | Show all findings | View |
|
||||
| `2` | Show untriaged only | View |
|
||||
| `3` | Show affected only | View |
|
||||
| `4` | Show not affected | View |
|
||||
| `[` | Collapse all | List view |
|
||||
| `]` | Expand all | List view |
|
||||
| `Tab` | Next panel | Multi-panel |
|
||||
| `Shift+Tab` | Previous panel | Multi-panel |
|
||||
|
||||
### Bulk Actions
|
||||
|
||||
| Key | Action | Context |
|
||||
|-----|--------|---------|
|
||||
| `Space` | Toggle selection | Finding |
|
||||
| `Shift+j` | Select next | Selection mode |
|
||||
| `Shift+k` | Select previous | Selection mode |
|
||||
| `Ctrl+a` | Select all visible | Finding list |
|
||||
| `Shift+a` | Bulk: Affected | Selection |
|
||||
| `Shift+n` | Bulk: Not Affected | Selection |
|
||||
|
||||
## CLI Batch Mode Shortcuts
|
||||
|
||||
### Navigation
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `j` / `↓` | Next finding |
|
||||
| `k` / `↑` | Previous finding |
|
||||
| `Page Down` | Skip 10 forward |
|
||||
| `Page Up` | Skip 10 back |
|
||||
| `Home` | First finding |
|
||||
| `End` | Last finding |
|
||||
|
||||
### Decisions
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `a` | Affected |
|
||||
| `n` | Not affected |
|
||||
| `w` | Won't fix |
|
||||
| `f` | False positive |
|
||||
| `s` | Skip (no decision) |
|
||||
| `u` | Undo last |
|
||||
|
||||
### Information
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `e` | Show evidence |
|
||||
| `i` | Show full info |
|
||||
| `?` | Show help |
|
||||
|
||||
### Control
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `q` | Save and quit |
|
||||
| `Q` | Quit without saving |
|
||||
| `Ctrl+c` | Abort |
|
||||
|
||||
## Graph View Shortcuts
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `+` / `=` | Zoom in |
|
||||
| `-` | Zoom out |
|
||||
| `0` | Reset zoom |
|
||||
| `Arrow keys` | Pan view |
|
||||
| `f` | Fit to screen |
|
||||
| `h` | Highlight path to root |
|
||||
| `l` | Highlight dependents |
|
||||
| `Enter` | Select node |
|
||||
| `Esc` | Deselect |
|
||||
|
||||
## Dashboard Shortcuts
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `r` | Refresh data |
|
||||
| `t` | Toggle sidebar |
|
||||
| `m` | Open menu |
|
||||
| `s` | Open settings |
|
||||
| `?` | Show shortcuts |
|
||||
|
||||
## Scan View Shortcuts
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `j` / `k` | Navigate scans |
|
||||
| `Enter` | Open scan details |
|
||||
| `d` | Download report |
|
||||
| `c` | Compare scans |
|
||||
| `r` | Rescan |
|
||||
|
||||
## Configuration
|
||||
|
||||
### Enable/Disable Shortcuts
|
||||
|
||||
```yaml
|
||||
# ~/.stellaops/ui.yaml
|
||||
keyboard:
|
||||
enabled: true
|
||||
vim_mode: true # Use vim-style navigation
|
||||
|
||||
# Customize keys
|
||||
custom:
|
||||
next_finding: "j"
|
||||
prev_finding: "k"
|
||||
affected: "a"
|
||||
not_affected: "n"
|
||||
```
|
||||
|
||||
### CLI Configuration
|
||||
|
||||
```yaml
|
||||
# ~/.stellaops/cli.yaml
|
||||
interactive:
|
||||
keyboard_enabled: true
|
||||
confirm_quit: true
|
||||
auto_save: true
|
||||
```
|
||||
|
||||
### Web UI Settings
|
||||
|
||||
Access via **Settings → Keyboard Shortcuts**:
|
||||
|
||||
- Enable/disable shortcuts
|
||||
- Customize key bindings
|
||||
- Import/export configurations
|
||||
|
||||
## Accessibility
|
||||
|
||||
### Screen Reader Support
|
||||
|
||||
All keyboard shortcuts have equivalent menu actions:
|
||||
- Use `Alt` to access menu bar
|
||||
- Tab navigation for all controls
|
||||
- ARIA labels for all actions
|
||||
|
||||
### Motion Preferences
|
||||
|
||||
When `prefers-reduced-motion` is set:
|
||||
- Instant transitions replace animations
|
||||
- Focus indicators remain visible longer
|
||||
|
||||
## Quick Reference Card
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────┐
|
||||
│ STELLAOPS KEYBOARD SHORTCUTS │
|
||||
├────────────────────────────────────────────┤
|
||||
│ NAVIGATION │ DECISIONS │
|
||||
│ j/k Next/Prev │ a Affected │
|
||||
│ g g First │ n Not Affected │
|
||||
│ G Last │ w Won't Fix │
|
||||
│ Enter Open │ f False Positive │
|
||||
│ Esc Close │ u Undo │
|
||||
├─────────────────────┼──────────────────────┤
|
||||
│ EVIDENCE │ VIEW │
|
||||
│ e Evidence panel │ 1 All findings │
|
||||
│ g Graph view │ 2 Untriaged │
|
||||
│ c Call stack │ 3 Affected │
|
||||
│ v VEX status │ / Search │
|
||||
├─────────────────────┼──────────────────────┤
|
||||
│ BULK │ CONTROL │
|
||||
│ Space Select │ q Save & quit │
|
||||
│ Ctrl+a Select all │ ? Help │
|
||||
│ Shift+a Bulk affect │ Ctrl+z Undo │
|
||||
└─────────────────────┴──────────────────────┘
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Triage CLI Reference](./triage-cli.md)
|
||||
- [Web UI Guide](../UI_GUIDE.md)
|
||||
- [Accessibility Guide](../accessibility.md)
|
||||
219
docs/modules/cli/guides/migration.md
Normal file
219
docs/modules/cli/guides/migration.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# CLI Consolidation Migration Guide
|
||||
|
||||
**Sprint:** SPRINT_5100_0001_0001
|
||||
**Status:** In Progress
|
||||
**Effective Date:** 2025-01-01 (deprecation begins)
|
||||
**Sunset Date:** 2025-07-01 (old CLIs removed)
|
||||
|
||||
## Overview
|
||||
|
||||
StellaOps is consolidating multiple standalone CLI tools into a single unified `stella` command with plugin-based subcommands. This improves developer experience, simplifies distribution, and ensures consistent behavior across all CLI operations.
|
||||
|
||||
## Migration Summary
|
||||
|
||||
| Old CLI | New Command | Status |
|
||||
|---------|-------------|--------|
|
||||
| `stella-aoc verify` | `stella aoc verify` | Available |
|
||||
| `stella-symbols ingest` | `stella symbols ingest` | Available |
|
||||
| `stella-symbols upload` | `stella symbols upload` | Available |
|
||||
| `stella-symbols verify` | `stella symbols verify` | Available |
|
||||
| `stella-symbols health` | `stella symbols health` | Available |
|
||||
| `cryptoru` | `cryptoru` (unchanged) | Separate |
|
||||
|
||||
**Note:** `cryptoru` CLI remains separate due to regional compliance requirements.
|
||||
|
||||
## Migration Steps
|
||||
|
||||
### 1. AOC CLI Migration
|
||||
|
||||
**Before (deprecated):**
|
||||
```bash
|
||||
stella-aoc verify --since 2025-01-01 --postgres "Host=localhost;..."
|
||||
```
|
||||
|
||||
**After:**
|
||||
```bash
|
||||
stella aoc verify --since 2025-01-01 --postgres "Host=localhost;..."
|
||||
```
|
||||
|
||||
**Command Options (unchanged):**
|
||||
- `--since, -s` - Git commit SHA or ISO timestamp to verify from (required)
|
||||
- `--postgres, -p` - PostgreSQL connection string (required)
|
||||
- `--output, -o` - Path for JSON output report
|
||||
- `--ndjson, -n` - Path for NDJSON output (one violation per line)
|
||||
- `--tenant, -t` - Filter by tenant ID
|
||||
- `--dry-run` - Validate configuration without querying database
|
||||
- `--verbose, -v` - Enable verbose output
|
||||
|
||||
### 2. Symbols CLI Migration
|
||||
|
||||
#### Ingest Command
|
||||
|
||||
**Before (deprecated):**
|
||||
```bash
|
||||
stella-symbols ingest --binary ./myapp --debug ./myapp.pdb --server https://symbols.example.com
|
||||
```
|
||||
|
||||
**After:**
|
||||
```bash
|
||||
stella symbols ingest --binary ./myapp --debug ./myapp.pdb --server https://symbols.example.com
|
||||
```
|
||||
|
||||
#### Upload Command
|
||||
|
||||
**Before (deprecated):**
|
||||
```bash
|
||||
stella-symbols upload --manifest ./manifest.json --server https://symbols.example.com
|
||||
```
|
||||
|
||||
**After:**
|
||||
```bash
|
||||
stella symbols upload --manifest ./manifest.json --server https://symbols.example.com
|
||||
```
|
||||
|
||||
#### Verify Command
|
||||
|
||||
**Before (deprecated):**
|
||||
```bash
|
||||
stella-symbols verify --path ./manifest.json
|
||||
```
|
||||
|
||||
**After:**
|
||||
```bash
|
||||
stella symbols verify --path ./manifest.json
|
||||
```
|
||||
|
||||
#### Health Command
|
||||
|
||||
**Before (deprecated):**
|
||||
```bash
|
||||
stella-symbols health --server https://symbols.example.com
|
||||
```
|
||||
|
||||
**After:**
|
||||
```bash
|
||||
stella symbols health --server https://symbols.example.com
|
||||
```
|
||||
|
||||
## CI/CD Updates
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
**Before:**
|
||||
```yaml
|
||||
- name: Verify AOC compliance
|
||||
run: stella-aoc verify --since ${{ github.event.before }} --postgres "$POSTGRES_CONN"
|
||||
```
|
||||
|
||||
**After:**
|
||||
```yaml
|
||||
- name: Verify AOC compliance
|
||||
run: stella aoc verify --since ${{ github.event.before }} --postgres "$POSTGRES_CONN"
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
**Before:**
|
||||
```yaml
|
||||
aoc-verify:
|
||||
script:
|
||||
- stella-aoc verify --since $CI_COMMIT_BEFORE_SHA --postgres "$POSTGRES_CONN"
|
||||
```
|
||||
|
||||
**After:**
|
||||
```yaml
|
||||
aoc-verify:
|
||||
script:
|
||||
- stella aoc verify --since $CI_COMMIT_BEFORE_SHA --postgres "$POSTGRES_CONN"
|
||||
```
|
||||
|
||||
### Shell Scripts
|
||||
|
||||
Update any shell scripts that invoke the old CLIs:
|
||||
|
||||
```bash
|
||||
# Find and replace patterns
|
||||
sed -i 's/stella-aoc /stella aoc /g' scripts/*.sh
|
||||
sed -i 's/stella-symbols /stella symbols /g' scripts/*.sh
|
||||
```
|
||||
|
||||
## Deprecation Timeline
|
||||
|
||||
| Date | Action |
|
||||
|------|--------|
|
||||
| 2025-01-01 | Deprecation warnings added to old CLIs |
|
||||
| 2025-03-01 | Warning frequency increased (every invocation) |
|
||||
| 2025-05-01 | Old CLIs emit error + warning, still functional |
|
||||
| 2025-07-01 | Old CLIs removed from distribution |
|
||||
|
||||
## Deprecation Warnings
|
||||
|
||||
When using deprecated CLIs, you will see warnings like:
|
||||
|
||||
```
|
||||
[DEPRECATED] stella-aoc is deprecated and will be removed on 2025-07-01.
|
||||
Please migrate to: stella aoc verify ...
|
||||
See: https://docs.stellaops.io/cli/migration
|
||||
```
|
||||
|
||||
## Plugin Architecture
|
||||
|
||||
The new `stella` CLI uses a plugin architecture. Plugins are automatically discovered from:
|
||||
- `<stella-install-dir>/plugins/cli/`
|
||||
- Custom directories via `STELLAOPS_CLI_PLUGINS_DIR`
|
||||
|
||||
Each plugin provides:
|
||||
- A manifest file (`*.manifest.json`)
|
||||
- A .NET assembly implementing `ICliCommandModule`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Plugin Not Found
|
||||
|
||||
If a subcommand is not available:
|
||||
|
||||
1. Check plugin directory exists:
|
||||
```bash
|
||||
ls $(dirname $(which stella))/plugins/cli/
|
||||
```
|
||||
|
||||
2. Verify manifest file:
|
||||
```bash
|
||||
cat $(dirname $(which stella))/plugins/cli/StellaOps.Cli.Plugins.Aoc/stellaops.cli.plugins.aoc.manifest.json
|
||||
```
|
||||
|
||||
3. Enable verbose logging:
|
||||
```bash
|
||||
stella --verbose aoc verify ...
|
||||
```
|
||||
|
||||
### Version Compatibility
|
||||
|
||||
Ensure all components are from the same release:
|
||||
```bash
|
||||
stella --version
|
||||
# StellaOps CLI v1.0.0
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
The unified CLI respects all existing environment variables:
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `STELLAOPS_BACKEND_URL` | Backend API URL |
|
||||
| `STELLAOPS_CLI_PLUGINS_DIR` | Custom plugins directory |
|
||||
| `STELLAOPS_AUTHORITY_URL` | Authority service URL |
|
||||
| `STELLAOPS_LOG_LEVEL` | Logging verbosity |
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Documentation: https://docs.stellaops.io/cli
|
||||
- Issues: https://github.com/stellaops/stellaops/issues
|
||||
- Migration support: support@stellaops.io
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [CLI Reference](../API_CLI_REFERENCE.md)
|
||||
- [Audit Pack Commands](./audit-pack-commands.md)
|
||||
- [Unknowns CLI Reference](./unknowns-cli-reference.md)
|
||||
508
docs/modules/cli/guides/quickstart.md
Normal file
508
docs/modules/cli/guides/quickstart.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.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 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**: [architecture.md](../architecture.md)
|
||||
- **Command Reference**: [commands/reference.md](commands/reference.md)
|
||||
- **Crypto Plugin Development**: [crypto/crypto-plugins.md](crypto/crypto-plugins.md)
|
||||
- **Compliance Guide**: [compliance.md](compliance.md)
|
||||
- **Distribution Matrix**: [distribution-matrix.md](distribution-matrix.md)
|
||||
- **Admin Guide**: [admin/admin-reference.md](admin/admin-reference.md)
|
||||
- **Troubleshooting**: [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).
|
||||
820
docs/modules/cli/guides/troubleshooting.md
Normal file
820
docs/modules/cli/guides/troubleshooting.md
Normal file
@@ -0,0 +1,820 @@
|
||||
# stella CLI - Troubleshooting Guide
|
||||
|
||||
**Sprint:** SPRINT_4100_0006_0006 - CLI Documentation Overhaul
|
||||
|
||||
## Overview
|
||||
|
||||
This guide covers common issues encountered when using the `stella` CLI and their solutions. Issues are categorized by functional area for easy navigation.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Authentication Issues](#authentication-issues)
|
||||
2. [Crypto Plugin Issues](#crypto-plugin-issues)
|
||||
3. [Build Issues](#build-issues)
|
||||
4. [Scanning Issues](#scanning-issues)
|
||||
5. [Configuration Issues](#configuration-issues)
|
||||
6. [Network Issues](#network-issues)
|
||||
7. [Permission Issues](#permission-issues)
|
||||
8. [Distribution Validation Issues](#distribution-validation-issues)
|
||||
|
||||
---
|
||||
|
||||
## Authentication Issues
|
||||
|
||||
### Problem: `stella auth login` fails with "Authority unreachable"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella auth login
|
||||
❌ Error: Failed to connect to Authority
|
||||
Authority URL: https://auth.stellaops.example.com
|
||||
Error: Connection refused
|
||||
```
|
||||
|
||||
**Possible Causes:**
|
||||
1. Authority service is down
|
||||
2. Network connectivity issues
|
||||
3. Incorrect Authority URL in configuration
|
||||
4. Firewall blocking connection
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Verify Authority URL**
|
||||
```bash
|
||||
# Check current Authority URL
|
||||
stella config get Backend.BaseUrl
|
||||
|
||||
# If incorrect, set correct URL
|
||||
stella config set Backend.BaseUrl https://api.stellaops.example.com
|
||||
|
||||
# Or set via environment variable
|
||||
export STELLAOPS_BACKEND_URL="https://api.stellaops.example.com"
|
||||
```
|
||||
|
||||
**Solution 2: Test network connectivity**
|
||||
```bash
|
||||
# Test if Authority is reachable
|
||||
curl -v https://auth.stellaops.example.com/health
|
||||
|
||||
# Check DNS resolution
|
||||
nslookup auth.stellaops.example.com
|
||||
```
|
||||
|
||||
**Solution 3: Enable offline cache fallback**
|
||||
```bash
|
||||
# Allow offline cache fallback (uses cached tokens)
|
||||
export STELLAOPS_AUTHORITY_ALLOW_OFFLINE_CACHE_FALLBACK=true
|
||||
export STELLAOPS_AUTHORITY_OFFLINE_CACHE_TOLERANCE=00:30:00
|
||||
|
||||
stella auth login
|
||||
```
|
||||
|
||||
**Solution 4: Use API key authentication (bypass Authority)**
|
||||
```bash
|
||||
# Use API key instead of interactive login
|
||||
export STELLAOPS_API_KEY="sk_live_your_api_key"
|
||||
|
||||
stella auth whoami
|
||||
# Output: Authenticated via API key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: `stella auth whoami` shows "Token expired"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella auth whoami
|
||||
❌ Error: Token expired
|
||||
Expiration: 2025-12-22T10:00:00Z
|
||||
Please re-authenticate with 'stella auth login'
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Re-authenticate
|
||||
stella auth login
|
||||
|
||||
# Or refresh token (if supported by Authority)
|
||||
stella auth refresh
|
||||
|
||||
# Verify authentication
|
||||
stella auth whoami
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: HTTP 403 "Insufficient scopes" when running admin commands
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella admin policy export
|
||||
❌ HTTP 403: Forbidden
|
||||
Error: Insufficient scopes. Required: admin.policy
|
||||
Your scopes: scan.read, scan.write
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Re-authenticate to obtain admin scopes
|
||||
stella auth logout
|
||||
stella auth login
|
||||
|
||||
# Verify you have admin scopes
|
||||
stella auth whoami
|
||||
# Output should include: admin.policy, admin.users, admin.feeds, admin.platform
|
||||
|
||||
# If still missing scopes, contact your platform administrator
|
||||
# to grant admin role to your account
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Crypto Plugin Issues
|
||||
|
||||
### Problem: `stella crypto sign --provider gost` fails with "Provider 'gost' not available"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella crypto sign --provider gost --file document.pdf
|
||||
❌ Error: Crypto provider 'gost' not available
|
||||
Available providers: default
|
||||
```
|
||||
|
||||
**Cause:**
|
||||
You are using the **International distribution** which does not include GOST plugin.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check which distribution you have
|
||||
stella --version
|
||||
# Output: stella CLI version 2.1.0
|
||||
# Distribution: stella-international <-- Problem!
|
||||
|
||||
# Download correct distribution for Russia/CIS
|
||||
wget https://releases.stella-ops.org/cli/russia/latest/stella-russia-linux-x64.tar.gz
|
||||
tar -xzf stella-russia-linux-x64.tar.gz
|
||||
sudo cp stella /usr/local/bin/
|
||||
|
||||
# Verify GOST provider is available
|
||||
stella crypto providers
|
||||
# Output:
|
||||
# - default (.NET Crypto, BouncyCastle)
|
||||
# - gost (GOST R 34.10-2012) <-- Now available
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: GOST signing fails with "CryptoPro CSP not initialized"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella crypto sign --provider gost --algorithm GOST12-256 --file document.pdf
|
||||
❌ Error: CryptoPro CSP not initialized
|
||||
Container: StellaOps-GOST-2024 not found
|
||||
```
|
||||
|
||||
**Causes:**
|
||||
1. CryptoPro CSP not installed
|
||||
2. Container not created
|
||||
3. Invalid provider configuration
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Verify CryptoPro CSP installation**
|
||||
```bash
|
||||
# Check if CryptoPro CSP is installed
|
||||
/opt/cprocsp/bin/amd64/csptestf -absorb -alg GR3411_2012_256
|
||||
|
||||
# If not installed, install CryptoPro CSP
|
||||
sudo ./install.sh # From CryptoPro CSP distribution
|
||||
```
|
||||
|
||||
**Solution 2: Create GOST container**
|
||||
```bash
|
||||
# Create new container
|
||||
/opt/cprocsp/bin/amd64/csptest -keyset -newkeyset -container "StellaOps-GOST-2024"
|
||||
|
||||
# List containers
|
||||
/opt/cprocsp/bin/amd64/csptest -keyset -enum_cont -verifycontext
|
||||
|
||||
# Update configuration to use correct container name
|
||||
stella config set Crypto.Providers.Gost.CryptoProCsp.ContainerName "StellaOps-GOST-2024"
|
||||
```
|
||||
|
||||
**Solution 3: Use OpenSSL-GOST instead (development only)**
|
||||
```yaml
|
||||
# appsettings.yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Gost:
|
||||
CryptoProCsp:
|
||||
Enabled: false # Disable CryptoPro CSP
|
||||
OpenSslGost:
|
||||
Enabled: true # Use OpenSSL-GOST
|
||||
```
|
||||
|
||||
**Warning:** OpenSSL-GOST is NOT FSTEC-certified and should only be used for development/testing.
|
||||
|
||||
---
|
||||
|
||||
### Problem: eIDAS signing fails with "TSP unreachable"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella crypto sign --provider eidas --algorithm ECDSA-P256-QES --file contract.pdf
|
||||
❌ Error: Trust Service Provider unreachable
|
||||
TSP URL: https://tsp.example.eu/api/v1/sign
|
||||
HTTP Error: Connection refused
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Verify TSP URL**
|
||||
```bash
|
||||
# Test TSP connectivity
|
||||
curl -v https://tsp.example.eu/api/v1/sign
|
||||
|
||||
# Update TSP URL if incorrect
|
||||
stella config set Crypto.Providers.Eidas.TspClient.TspUrl "https://correct-tsp.eu/api/v1/sign"
|
||||
```
|
||||
|
||||
**Solution 2: Check API key**
|
||||
```bash
|
||||
# Verify API key is set
|
||||
echo $EIDAS_TSP_API_KEY
|
||||
|
||||
# If not set, export it
|
||||
export EIDAS_TSP_API_KEY="your_api_key_here"
|
||||
|
||||
# Or set in configuration
|
||||
stella config set Crypto.Providers.Eidas.TspClient.ApiKey "your_api_key_here"
|
||||
```
|
||||
|
||||
**Solution 3: Use local signer for AES (not QES)**
|
||||
```yaml
|
||||
# For Advanced Electronic Signatures (not qualified)
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Eidas:
|
||||
TspClient:
|
||||
Enabled: false
|
||||
LocalSigner:
|
||||
Enabled: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Issues
|
||||
|
||||
### Problem: Build fails with "DefineConstants 'STELLAOPS_ENABLE_GOST' not defined"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ dotnet build -p:StellaOpsEnableGOST=true
|
||||
error CS0103: The name 'STELLAOPS_ENABLE_GOST' does not exist in the current context
|
||||
```
|
||||
|
||||
**Cause:**
|
||||
Missing `-p:DefineConstants` flag.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Correct build command (includes both flags)
|
||||
dotnet build \
|
||||
-p:StellaOpsEnableGOST=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_GOST"
|
||||
|
||||
# Or for publish:
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
-p:StellaOpsEnableGOST=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_GOST"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: Build succeeds but crypto plugin not available at runtime
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
# Build appears successful
|
||||
$ dotnet build -p:StellaOpsEnableGOST=true -p:DefineConstants="STELLAOPS_ENABLE_GOST"
|
||||
Build succeeded.
|
||||
|
||||
# But plugin not available
|
||||
$ ./stella crypto providers
|
||||
Available providers:
|
||||
- default
|
||||
|
||||
# GOST plugin missing!
|
||||
```
|
||||
|
||||
**Cause:**
|
||||
Plugin DLL not copied to output directory.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Use dotnet publish instead of dotnet build
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableGOST=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_GOST" \
|
||||
--output dist/stella-russia-linux-x64
|
||||
|
||||
# Verify GOST plugin DLL is present
|
||||
ls dist/stella-russia-linux-x64/*.dll | grep Gost
|
||||
# Expected: StellaOps.Cli.Crypto.Gost.dll
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: "GLIBC version not found" when running CLI on older Linux
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ ./stella --version
|
||||
./stella: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by ./stella)
|
||||
```
|
||||
|
||||
**Cause:**
|
||||
CLI built with newer .NET runtime requiring newer GLIBC.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check your GLIBC version
|
||||
ldd --version
|
||||
# If < 2.34, upgrade to a newer Linux distribution
|
||||
|
||||
# Or build with older .NET runtime (if possible)
|
||||
# Or use containerized version:
|
||||
docker run -it stellaops/cli:latest stella --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scanning Issues
|
||||
|
||||
### Problem: `stella scan` fails with "Image not found"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella scan docker://nginx:latest
|
||||
❌ Error: Image not found
|
||||
Image: docker://nginx:latest
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Pull image first**
|
||||
```bash
|
||||
# Pull image from Docker registry
|
||||
docker pull nginx:latest
|
||||
|
||||
# Then scan
|
||||
stella scan docker://nginx:latest
|
||||
```
|
||||
|
||||
**Solution 2: Scan local tar archive**
|
||||
```bash
|
||||
# Export image to tar
|
||||
docker save nginx:latest -o nginx.tar
|
||||
|
||||
# Scan tar archive
|
||||
stella scan tar://nginx.tar
|
||||
```
|
||||
|
||||
**Solution 3: Specify registry explicitly**
|
||||
```bash
|
||||
# Use fully-qualified image reference
|
||||
stella scan docker://docker.io/library/nginx:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: Scan succeeds but no vulnerabilities found (expected some)
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella scan docker://vulnerable-app:latest
|
||||
Scan complete: 0 vulnerabilities found
|
||||
```
|
||||
|
||||
**Possible Causes:**
|
||||
1. Advisory feeds not synchronized
|
||||
2. Offline mode with stale data
|
||||
3. VEX mode filtering vulnerabilities
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Refresh advisory feeds (admin)**
|
||||
```bash
|
||||
stella admin feeds refresh --source nvd --force
|
||||
stella admin feeds refresh --source osv --force
|
||||
```
|
||||
|
||||
**Solution 2: Check feed status**
|
||||
```bash
|
||||
stella admin feeds status
|
||||
# Output:
|
||||
# Feed Last Sync Status
|
||||
# ────────────────────────────────────────
|
||||
# NVD 2025-12-23 10:00 ✅ UP
|
||||
# OSV 2025-12-23 09:45 ⚠️ STALE (12 hours old)
|
||||
```
|
||||
|
||||
**Solution 3: Disable VEX filtering**
|
||||
```bash
|
||||
# Scan with VEX mode disabled
|
||||
stella scan docker://vulnerable-app:latest --vex-mode disabled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Issues
|
||||
|
||||
### Problem: "Configuration file not found"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella config show
|
||||
⚠️ Warning: No configuration file found
|
||||
Using default configuration
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Create user configuration directory
|
||||
mkdir -p ~/.stellaops
|
||||
|
||||
# Create configuration file
|
||||
cat > ~/.stellaops/config.yaml <<EOF
|
||||
StellaOps:
|
||||
Backend:
|
||||
BaseUrl: "https://api.stellaops.example.com"
|
||||
EOF
|
||||
|
||||
# Verify configuration is loaded
|
||||
stella config show
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: Environment variables not overriding configuration
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ export STELLAOPS_BACKEND_URL="https://test.example.com"
|
||||
$ stella config get Backend.BaseUrl
|
||||
https://api.stellaops.example.com # Still shows old value!
|
||||
```
|
||||
|
||||
**Cause:**
|
||||
Incorrect environment variable format.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Correct environment variable format (double underscore for nested properties)
|
||||
export STELLAOPS_BACKEND__BASEURL="https://test.example.com"
|
||||
# ^^ Note: double underscore
|
||||
|
||||
# Verify
|
||||
stella config get Backend.BaseUrl
|
||||
# Output: https://test.example.com # Now correct
|
||||
```
|
||||
|
||||
**Environment Variable Format Rules:**
|
||||
- Prefix: `STELLAOPS_`
|
||||
- Nested properties: Double underscore `__`
|
||||
- Array index: Double underscore + index `__0`, `__1`, etc.
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Simple property
|
||||
export STELLAOPS_BACKEND__BASEURL="https://api.example.com"
|
||||
|
||||
# Nested property
|
||||
export STELLAOPS_CRYPTO__DEFAULTPROVIDER="gost"
|
||||
|
||||
# Array element
|
||||
export STELLAOPS_CRYPTO__PROVIDERS__GOST__KEYS__0__KEYID="key1"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Network Issues
|
||||
|
||||
### Problem: Timeouts when connecting to backend
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella scan docker://nginx:latest
|
||||
❌ Error: Request timeout
|
||||
Backend: https://api.stellaops.example.com/api/v1/scan
|
||||
Timeout: 30s
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Increase timeout**
|
||||
```yaml
|
||||
# appsettings.yaml
|
||||
StellaOps:
|
||||
Backend:
|
||||
Http:
|
||||
TimeoutSeconds: 120 # Increase from 30 to 120
|
||||
```
|
||||
|
||||
**Solution 2: Check network latency**
|
||||
```bash
|
||||
# Ping backend
|
||||
ping api.stellaops.example.com
|
||||
|
||||
# Test HTTP latency
|
||||
time curl -v https://api.stellaops.example.com/health
|
||||
```
|
||||
|
||||
**Solution 3: Use proxy**
|
||||
```bash
|
||||
# Set HTTP proxy
|
||||
export HTTP_PROXY="http://proxy.example.com:8080"
|
||||
export HTTPS_PROXY="http://proxy.example.com:8080"
|
||||
|
||||
stella scan docker://nginx:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: SSL certificate verification fails
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella scan docker://nginx:latest
|
||||
❌ Error: SSL certificate verification failed
|
||||
Certificate: CN=api.stellaops.example.com
|
||||
Error: The SSL certificate is invalid
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Add CA certificate**
|
||||
```bash
|
||||
# Add custom CA certificate (Linux)
|
||||
sudo cp custom-ca.crt /usr/local/share/ca-certificates/
|
||||
sudo update-ca-certificates
|
||||
|
||||
# Add custom CA certificate (macOS)
|
||||
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain custom-ca.crt
|
||||
```
|
||||
|
||||
**Solution 2: Disable SSL verification (INSECURE - development only)**
|
||||
```bash
|
||||
# WARNING: This disables SSL verification. Use only for testing!
|
||||
export STELLAOPS_BACKEND__HTTP__DISABLESSLVERIFICATION=true
|
||||
|
||||
stella scan docker://nginx:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Permission Issues
|
||||
|
||||
### Problem: "Permission denied" when running `stella`
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella --version
|
||||
bash: /usr/local/bin/stella: Permission denied
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Make binary executable
|
||||
chmod +x /usr/local/bin/stella
|
||||
|
||||
# Verify
|
||||
stella --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: "Access denied" when accessing keys
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella crypto sign --provider gost --file doc.pdf
|
||||
❌ Error: Access denied to key file
|
||||
File: /etc/stellaops/keys/gost-key.pem
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Fix key file permissions
|
||||
sudo chmod 600 /etc/stellaops/keys/gost-key.pem
|
||||
sudo chown $(whoami):$(whoami) /etc/stellaops/keys/gost-key.pem
|
||||
|
||||
# Or run as root (not recommended)
|
||||
sudo stella crypto sign --provider gost --file doc.pdf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Distribution Validation Issues
|
||||
|
||||
### Problem: Validation script reports "wrong plugins included"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ ./validate-distribution.sh international dist/stella-international-linux-x64/stella
|
||||
❌ FAIL: International distribution contains restricted plugins
|
||||
Found: GostCryptoProvider
|
||||
```
|
||||
|
||||
**Cause:**
|
||||
Built with wrong flags or flags not working.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Clean and rebuild without regional flags
|
||||
dotnet clean
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-linux-x64
|
||||
|
||||
# Verify no build flags were set
|
||||
echo "No StellaOpsEnableGOST, StellaOpsEnableEIDAS, or StellaOpsEnableSM flags"
|
||||
|
||||
# Re-validate
|
||||
./validate-distribution.sh international dist/stella-international-linux-x64/stella
|
||||
# Expected: ✅ PASS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Diagnostic Commands
|
||||
|
||||
### Check CLI Version and Distribution
|
||||
|
||||
```bash
|
||||
stella --version
|
||||
# Output:
|
||||
# stella CLI version 2.1.0
|
||||
# Build: 2025-12-23T10:00:00Z
|
||||
# Commit: dfaa207
|
||||
# Distribution: stella-russia
|
||||
# Platform: linux-x64
|
||||
# .NET Runtime: 10.0.0
|
||||
```
|
||||
|
||||
### System Diagnostics
|
||||
|
||||
```bash
|
||||
stella system diagnostics
|
||||
# Output:
|
||||
# System Diagnostics:
|
||||
# ✅ CLI version: 2.1.0
|
||||
# ✅ .NET Runtime: 10.0.0
|
||||
# ✅ Backend reachable: https://api.stellaops.example.com
|
||||
# ✅ Authentication: Valid (expires 2025-12-24)
|
||||
# ✅ Crypto providers: default, gost
|
||||
# ⚠️ PostgreSQL: Not configured (offline mode)
|
||||
```
|
||||
|
||||
### Check Available Crypto Providers
|
||||
|
||||
```bash
|
||||
stella crypto providers --verbose
|
||||
# Output:
|
||||
# Available Crypto Providers:
|
||||
#
|
||||
# Provider: default
|
||||
# Description: .NET Crypto, BouncyCastle
|
||||
# Algorithms: ECDSA-P256, ECDSA-P384, EdDSA, RSA-2048, RSA-4096
|
||||
# Status: ✅ Healthy
|
||||
#
|
||||
# Provider: gost
|
||||
# Description: GOST R 34.10-2012, GOST R 34.11-2012
|
||||
# Algorithms: GOST12-256, GOST12-512, GOST2001
|
||||
# Status: ⚠️ CryptoPro CSP not initialized
|
||||
```
|
||||
|
||||
### Verbose Mode
|
||||
|
||||
```bash
|
||||
# Enable verbose logging for all commands
|
||||
stella --verbose <command>
|
||||
|
||||
# Example:
|
||||
stella --verbose auth login
|
||||
stella --verbose scan docker://nginx:latest
|
||||
stella --verbose crypto sign --provider gost --file doc.pdf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you're still experiencing issues after trying these solutions:
|
||||
|
||||
1. **Check Documentation:**
|
||||
- [CLI Overview](README.md)
|
||||
- [CLI Architecture](architecture.md)
|
||||
- [Command Reference](command-reference.md)
|
||||
- [Compliance Guide](compliance-guide.md)
|
||||
|
||||
2. **Enable Verbose Logging:**
|
||||
```bash
|
||||
stella --verbose <command>
|
||||
```
|
||||
|
||||
3. **Check GitHub Issues:**
|
||||
- https://git.stella-ops.org/stella-ops.org/git.stella-ops.org/issues
|
||||
|
||||
4. **Community Support:**
|
||||
- GitHub Discussions: https://github.com/stellaops/stellaops/discussions
|
||||
|
||||
5. **Commercial Support:**
|
||||
- Contact: support@stella-ops.org
|
||||
|
||||
---
|
||||
|
||||
## Common Error Codes
|
||||
|
||||
| Exit Code | Meaning | Typical Cause |
|
||||
|-----------|---------|---------------|
|
||||
| `0` | Success | - |
|
||||
| `1` | General error | Check error message |
|
||||
| `2` | Policy violations | Scan found policy violations (with `--fail-on-policy-violations`) |
|
||||
| `3` | Authentication error | Token expired or invalid credentials |
|
||||
| `4` | Configuration error | Invalid configuration or missing required fields |
|
||||
| `5` | Network error | Backend unreachable or timeout |
|
||||
| `10` | Invalid arguments | Incorrect command usage or missing required arguments |
|
||||
|
||||
---
|
||||
|
||||
## Frequently Asked Questions (FAQ)
|
||||
|
||||
### Q: How do I switch between crypto providers?
|
||||
|
||||
**A:** Use the `--provider` flag or create a crypto profile:
|
||||
|
||||
```bash
|
||||
# Method 1: Use --provider flag
|
||||
stella crypto sign --provider gost --file doc.pdf
|
||||
|
||||
# Method 2: Create and use profile
|
||||
stella crypto profiles create my-gost --provider gost --algorithm GOST12-256
|
||||
stella crypto profiles use my-gost
|
||||
stella crypto sign --file doc.pdf # Uses my-gost profile
|
||||
```
|
||||
|
||||
### Q: Can I use multiple regional plugins in one distribution?
|
||||
|
||||
**A:** No. Each distribution includes only one regional plugin (GOST, eIDAS, or SM) to comply with export control laws.
|
||||
|
||||
### Q: How do I update the CLI?
|
||||
|
||||
**A:**
|
||||
```bash
|
||||
# If installed via .NET tool
|
||||
dotnet tool update --global StellaOps.Cli
|
||||
|
||||
# If installed via binary download
|
||||
wget https://releases.stella-ops.org/cli/latest/stella-<distribution>-<platform>.tar.gz
|
||||
tar -xzf stella-<distribution>-<platform>.tar.gz
|
||||
sudo cp stella /usr/local/bin/
|
||||
```
|
||||
|
||||
### Q: How do I enable offline mode?
|
||||
|
||||
**A:**
|
||||
```bash
|
||||
# Set offline mode
|
||||
export STELLAOPS_OFFLINE_MODE=true
|
||||
|
||||
# Create offline package (admin)
|
||||
stella offline sync --output stellaops-offline-$(date +%F).tar.gz
|
||||
|
||||
# Load offline package in air-gapped environment
|
||||
stella offline load --package stellaops-offline-2025-12-23.tar.gz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [CLI Overview](README.md) - Installation and quick start
|
||||
- [CLI Architecture](architecture.md) - Plugin architecture
|
||||
- [Command Reference](command-reference.md) - Command usage
|
||||
- [Compliance Guide](compliance-guide.md) - Regional compliance
|
||||
- [Distribution Matrix](distribution-matrix.md) - Build and distribution
|
||||
- [Crypto Plugins](crypto-plugins.md) - Plugin development
|
||||
Reference in New Issue
Block a user