git.stella-ops.org/docs/cli/unknowns-cli-reference.md

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.

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "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

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

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

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

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

# 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

# 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

# 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
• Reachability CLI Reference
• Unknowns API Reference
• Unknowns Queue Runbook

---

Last Updated: 2025-12-20
Version: 1.0.0
Sprint: 3500.0004.0004