stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity
Files
4b3db9ca8535e02cbfd2a0114e749023ab7b921b
git.stella-ops.org/docs/cli/unknowns-cli-reference.md
StellaOps Bot 4b3db9ca85 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).
2025-12-20 22:30:02 +02:00

533 lines
12 KiB
Markdown
Raw Blame History

# 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 View Git Blame Copy Permalink