git.stella-ops.org/docs/modules/cli/guides/commands/risk.md

stella risk — Command Guide

Overview

The stella risk command group provides risk profile management, risk scoring simulation, and risk bundle verification capabilities.

Commands

Risk Profile Management (CLI-RISK-66-001)

# List risk profiles
stella risk profile list \
  [--tenant <id>] \
  [--include-disabled] \
  [--category <category>] \
  [--limit <num>] \
  [--offset <num>] \
  [--json]

Options:

Flag	Description
--include-disabled	Include disabled profiles in listing
--category	Filter by profile category
--limit	Maximum number of results (default 100)
--offset	Pagination offset

Output Columns:

• Profile ID
• Name
• Category
• Version
• Rules count
• Enabled status
• Built-in indicator

Risk Simulation (CLI-RISK-66-002)

# Simulate risk scoring
stella risk simulate \
  [--tenant <id>] \
  [--profile-id <id>] \
  [--sbom-id <id>] \
  [--sbom-path <path>] \
  [--asset-id <id>] \
  [--diff] \
  [--baseline-profile-id <id>] \
  [--json] \
  [--csv] \
  [--output <path>]

Options:

Flag	Description
--profile-id	Risk profile to use for simulation
--sbom-id	SBOM identifier for risk evaluation
--sbom-path	Local path to SBOM file
--asset-id	Asset identifier for risk evaluation
--diff	Enable diff mode to compare with baseline
--baseline-profile-id	Baseline profile for diff comparison

Required: At least one of --sbom-id, --sbom-path, or --asset-id.

Output:

• Overall score and grade (A+ to F)
• Findings summary by severity (critical, high, medium, low, info)
• Component-level scores
• Diff information when --diff is enabled

Risk Results (CLI-RISK-67-001)

# Get risk evaluation results
stella risk results \
  [--tenant <id>] \
  [--asset-id <id>] \
  [--sbom-id <id>] \
  [--profile-id <id>] \
  [--min-severity <severity>] \
  [--max-score <score>] \
  [--explain] \
  [--limit <num>] \
  [--offset <num>] \
  [--json] \
  [--csv]

Options:

Flag	Description
--min-severity	Minimum severity threshold (critical, high, medium, low, info)
--max-score	Maximum score threshold (0-100)
--explain	Include explainability information

Output:

• Summary statistics (average, min, max score, asset count)
• Results table with score, grade, severity, finding count
• Explanation factors and recommendations when --explain is used

Risk Bundle Verification (CLI-RISK-68-001)

# Verify a risk bundle
stella risk bundle verify \
  [--tenant <id>] \
  --bundle-path <path> \
  [--signature-path <path>] \
  [--check-rekor] \
  [--json]

Options:

Flag	Description
--bundle-path	Path to the risk bundle file (required)
--signature-path	Path to detached signature file
--check-rekor	Verify transparency log entry in Sigstore Rekor

Output:

• Bundle validation status (VALID/INVALID)
• Bundle information (ID, version, profile count, rule count)
• Signature verification status
• Rekor transparency log verification status

Exit Codes

Code	Meaning
0	Success (for verify: bundle is valid)
1	Error or invalid bundle
4	Input validation error
130	Operation cancelled by user

JSON Schema: RiskSimulateResult

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "success": { "type": "boolean" },
    "profileId": { "type": "string" },
    "profileName": { "type": "string" },
    "overallScore": { "type": "number" },
    "grade": { "type": "string" },
    "findings": {
      "type": "object",
      "properties": {
        "critical": { "type": "integer" },
        "high": { "type": "integer" },
        "medium": { "type": "integer" },
        "low": { "type": "integer" },
        "info": { "type": "integer" },
        "total": { "type": "integer" }
      }
    },
    "componentScores": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "componentId": { "type": "string" },
          "componentName": { "type": "string" },
          "score": { "type": "number" },
          "grade": { "type": "string" },
          "findingCount": { "type": "integer" }
        }
      }
    },
    "diff": {
      "type": "object",
      "properties": {
        "baselineScore": { "type": "number" },
        "candidateScore": { "type": "number" },
        "delta": { "type": "number" },
        "improved": { "type": "boolean" },
        "findingsAdded": { "type": "integer" },
        "findingsRemoved": { "type": "integer" }
      }
    },
    "simulatedAt": { "type": "string", "format": "date-time" },
    "errors": { "type": "array", "items": { "type": "string" } }
  }
}

Examples

List all enabled risk profiles

stella risk profile list --json

Simulate risk for a local SBOM

stella risk simulate \
  --sbom-path ./my-sbom.json \
  --profile-id RP-security-baseline \
  --json

Compare risk between profiles

stella risk simulate \
  --asset-id my-app \
  --profile-id RP-strict \
  --diff \
  --baseline-profile-id RP-permissive

Get high-severity results with explanations

stella risk results \
  --asset-id my-app \
  --min-severity high \
  --explain

Verify a signed risk bundle

stella risk bundle verify \
  --bundle-path ./risk-bundle.tar.gz \
  --signature-path ./risk-bundle.sig \
  --check-rekor

Risk Grading Scale

Grade	Score Range	Description
A+	95-100	Excellent
A	90-94	Very Good
B+	85-89	Good
B	80-84	Above Average
C+	75-79	Average
C	70-74	Below Average
D+	65-69	Poor
D	60-64	Very Poor
F	0-59	Failing