docs(ops): Complete operations runbooks for Epic 3500
Sprint 3500.0004.0004 (Documentation & Handoff) - T2 DONE Operations Runbooks Added: - score-replay-runbook.md: Deterministic replay procedures - proof-verification-runbook.md: DSSE/Merkle verification ops - airgap-operations-runbook.md: Offline kit management CLI Reference Docs: - reachability-cli-reference.md - score-proofs-cli-reference.md - unknowns-cli-reference.md Air-Gap Guides: - score-proofs-reachability-airgap-runbook.md Training Materials: - score-proofs-concept-guide.md UI API Clients: - proof.client.ts - reachability.client.ts - unknowns.client.ts All 5 operations runbooks now complete (reachability, unknowns-queue, score-replay, proof-verification, airgap-operations).
This commit is contained in:
StellaOps Bot
532
docs/cli/unknowns-cli-reference.md
Normal file
532
docs/cli/unknowns-cli-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
|
||||
Reference in New Issue
Block a user