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

```bash
# 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)

```bash
# 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)

```bash
# 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)

```bash
# 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

```json
{
  "$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

```bash
stella risk profile list --json
```

### Simulate risk for a local SBOM

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

### Compare risk between profiles

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

### Get high-severity results with explanations

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

### Verify a signed risk bundle

```bash
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 |