# stella vuln - Command Guide

## Overview

The `stella vuln` command group is the operator surface for vulnerability triage workflows:
- Query and inspect vulnerabilities (`list`, `show`)
- Retrieve raw advisory observations for overlay consumers (`observations`)
- Apply workflow actions (assign, comment, accept risk, verify fix, target fix, reopen)
- Simulate policy/VEX changes (`simulate`)
- Export offline evidence bundles and verify them (`export`, `export verify`)

Unless otherwise noted, commands support formatted output by default and `--json` for automation-friendly output.

## Commands

### observations

List raw advisory observations (useful for overlay consumers).

```bash
stella vuln observations \
  --tenant acme \
  --alias CVE-2024-1234 \
  --limit 50 \
  --json
```

Options:

| Flag | Description |
| --- | --- |
| `--tenant` | Tenant identifier (required). |
| `--observation-id` | Filter by observation id (repeatable). |
| `--alias` | Filter by vulnerability alias (repeatable). |
| `--purl` | Filter by Package URL (repeatable). |
| `--cpe` | Filter by CPE value (repeatable). |
| `--limit` | Max items (default 200, max 500). |
| `--cursor` | Opaque cursor token from a previous page. |
| `--json` | Emit raw JSON payload instead of a table. |

### list

List vulnerabilities with filters, grouping, and pagination.

```bash
stella vuln list \
  --severity high \
  --status open \
  --group-by package \
  --limit 50
```

Options:

| Flag | Description |
| --- | --- |
| `--vuln-id` | Filter by vulnerability identifier (e.g., `CVE-2024-1234`). |
| `--severity` | Filter by severity (`critical`, `high`, `medium`, `low`). |
| `--status` | Filter by status (`open`, `triaged`, `accepted`, `fixed`, etc.). |
| `--purl` | Filter by Package URL. |
| `--cpe` | Filter by CPE value. |
| `--sbom-id` | Filter by SBOM identifier. |
| `--policy-id` | Filter by policy identifier. |
| `--policy-version` | Filter by policy version. |
| `--group-by` | Group by (`vuln`, `package`, `severity`, `status`). |
| `--limit` | Max items (default 50, max 500). |
| `--offset` | Offset paging (skip N). |
| `--cursor` | Opaque cursor token from a previous page. |
| `--tenant` | Tenant identifier (overrides profile/environment). |
| `--json` | Emit raw JSON payload instead of a table. |
| `--csv` | Emit CSV instead of a table. |

### show

Show details for a specific vulnerability id.

```bash
stella vuln show CVE-2024-1234 --json
```

Options:

| Flag | Description |
| --- | --- |
| `--tenant` | Tenant identifier (overrides profile/environment). |
| `--json` | Emit raw JSON payload instead of formatted output. |

### Workflow commands

Workflow commands operate on either:
- Explicit selection: repeat `--vuln-id <id>`
- Filtered selection: `--filter-*` options

Shared options:

| Flag | Description |
| --- | --- |
| `--vuln-id` | Vulnerability ids to operate on (repeatable). |
| `--filter-severity` | Filter by severity (`critical`, `high`, `medium`, `low`). |
| `--filter-status` | Filter by current status. |
| `--filter-purl` | Filter by Package URL. |
| `--filter-sbom` | Filter by SBOM id. |
| `--tenant` | Tenant identifier (overrides profile/environment). |
| `--idempotency-key` | Idempotency key for retry-safe operations. |
| `--json` | Emit raw JSON response. |

Commands:

```bash
# Assign selected vulns to an assignee
stella vuln assign alice@example.com --vuln-id CVE-2024-1234

# Add a comment
stella vuln comment "triage started" --vuln-id CVE-2024-1234

# Accept risk with optional due date (ISO-8601)
stella vuln accept-risk "risk accepted for legacy system" \
  --due-date 2026-12-31 \
  --vuln-id CVE-2024-1234

# Mark as fixed and verified
stella vuln verify-fix \
  --fix-version 1.2.3 \
  --comment "patched in release 1.2.3" \
  --vuln-id CVE-2024-1234

# Set a target fix date
stella vuln target-fix 2026-12-31 \
  --comment "scheduled in next maintenance window" \
  --vuln-id CVE-2024-1234

# Reopen a previously closed/accepted vuln
stella vuln reopen --comment "regression observed" --vuln-id CVE-2024-1234
```

### simulate

Simulate policy/VEX changes and show delta summaries.

```bash
stella vuln simulate \
  --policy-id policy://tenant-default/runtime-hardening \
  --policy-version 7 \
  --vex-override "CVE-2024-1234=not_affected" \
  --severity-threshold high \
  --sbom-id sbom-001 \
  --markdown \
  --output ./vuln-sim-report.md
```

Options:

| Flag | Description |
| --- | --- |
| `--policy-id` | Policy id to simulate (uses different version or a new policy). |
| `--policy-version` | Policy version to simulate against. |
| `--vex-override` | VEX status overrides (`vulnId=status`, repeatable). |
| `--severity-threshold` | Threshold (`critical`, `high`, `medium`, `low`). |
| `--sbom-id` | SBOM ids to include (repeatable). |
| `--markdown` | Include Markdown report suitable for CI pipelines. |
| `--changed-only` | Only show items that changed. |
| `--tenant` | Tenant identifier for multi-tenant environments. |
| `--json` | Output JSON for automation. |
| `--output` | Write Markdown report to file instead of stdout. |

### export

Export vulnerability evidence bundles (optionally signed) for offline review and audit workflows.

```bash
stella vuln export \
  --vuln-id CVE-2024-1234 \
  --format ndjson \
  --output ./vuln-export.ndjson
```

Options:

| Flag | Description |
| --- | --- |
| `--vuln-id` | Vulnerability ids to include (repeatable). |
| `--sbom-id` | SBOM ids to include (repeatable). |
| `--policy-id` | Policy id for export filtering. |
| `--format` | `ndjson` (default) or `json`. |
| `--include-evidence` | Include evidence data (default: true). |
| `--include-ledger` | Include workflow ledger (default: true). |
| `--signed` | Request signed export bundle (default: true). |
| `--output` | Output file path for the export bundle (required). |
| `--tenant` | Tenant identifier for multi-tenant environments. |

### export verify

Verify signature and digest of an exported vulnerability bundle.

```bash
stella vuln export verify ./vuln-export.ndjson \
  --expected-digest sha256:deadbeef... \
  --public-key ./authority-public.pem
```

Options:

| Flag | Description |
| --- | --- |
| `--expected-digest` | Expected digest to verify (`sha256:<hex>`). |
| `--public-key` | Public key path for signature verification. |