up
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
This commit is contained in:
master
248
docs/modules/cli/guides/commands/risk.md
Normal file
248
docs/modules/cli/guides/commands/risk.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user