Unknowns CLI Reference

Audience: Security analysts and DevOps engineers who triage components Stella Ops could not fully analyze. Scope: The stella unknowns command group — listing, triaging, escalating, resolving, and exporting “unknown” components that lack the data needed for a confident verdict.

Overview

The stella unknowns command group manages components that Stella Ops cannot analyze because of missing data, unrecognized formats, or resolution failures. These commands support the full triage lifecycle: review, escalation, resolution, suppression, and bulk import/export for offline workflows.

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