# CLI Vulnerability Explorer Commands Reference

> **Audience:** DevEx engineers, security operators, and CI authors managing vulnerabilities through the `stella` CLI.
> **Scope:** Command synopsis, options, exit codes, and CI integration patterns for `stella vuln` commands as introduced in Sprint 205.

The Vulnerability Explorer CLI enables comprehensive vulnerability management including listing, inspection, workflow operations, policy simulation, and export. All commands support multi-tenant environments and integrate with StellaOps Authority for authentication.

---

## 1. Prerequisites

- CLI version: `stella` >= 0.21.0 (Vulnerability Explorer feature gate enabled).
- Required scopes (DPoP-bound):
  - `vuln:view` for listing and viewing vulnerabilities.
  - `vuln:workflow` for workflow operations (assign, comment, accept-risk, etc.).
  - `vuln:simulate` for policy simulation.
  - `vuln:export` for exporting evidence bundles.
  - `tenant:select` if using tenant switching.
- Connectivity: direct access to Backend APIs or configured backend URL.
- Environment: set `STELLAOPS_BACKEND_URL`, `STELLA_TENANT`, and authenticate via `stella auth login`.

---

## 2. `stella vuln list`

### 2.1 Synopsis

```bash
stella vuln list \
  [--vuln-id <id>] \
  [--severity critical|high|medium|low] \
  [--status open|triaged|accepted|fixed|risk_accepted] \
  [--purl <package-url>] \
  [--cpe <cpe>] \
  [--sbom-id <sbom-id>] \
  [--policy-id <policy-id>] \
  [--policy-version <version>] \
  [--group-by severity|status|sbom|policy] \
  [--limit <n>] [--offset <n>] [--cursor <token>] \
  [--tenant <tenant-id>] \
  [--json] [--csv] [--verbose]
```

### 2.2 Description

Lists vulnerabilities matching the specified filters with pagination support. Supports grouped summaries for reporting and machine-readable output for automation.

### 2.3 Options

| Option | Description |
|--------|-------------|
| `--vuln-id <id>` | Filter by vulnerability ID (e.g., CVE-2024-1234). |
| `--severity <level>` | Filter by severity (critical, high, medium, low). |
| `--status <status>` | Filter by workflow status. |
| `--purl <package-url>` | Filter by Package URL pattern. |
| `--cpe <cpe>` | Filter by CPE pattern. |
| `--sbom-id <sbom-id>` | Filter by SBOM identifier. |
| `--policy-id <policy-id>` | Filter by policy ID. |
| `--policy-version <version>` | Filter by policy version. |
| `--group-by <field>` | Group results by field (shows summary counts). |
| `--limit <n>` | Maximum results to return (default 50). |
| `--offset <n>` | Number of results to skip. |
| `--cursor <token>` | Pagination cursor from previous response. |
| `--tenant <tenant-id>` | Override tenant for multi-tenant deployments. |
| `--json` | Output as JSON for automation. |
| `--csv` | Output as CSV for spreadsheet import. |
| `--verbose` | Enable debug logging. |

### 2.4 Examples

List critical vulnerabilities:

```bash
stella vuln list --severity critical
```

Group by status for reporting:

```bash
stella vuln list --group-by status --json > status-summary.json
```

Export CSV for compliance audit:

```bash
stella vuln list --severity critical --severity high --csv > critical-vulns.csv
```

---

## 3. `stella vuln show`

### 3.1 Synopsis

```bash
stella vuln show <vulnerability-id> \
  [--tenant <tenant-id>] \
  [--json] [--verbose]
```

### 3.2 Description

Displays detailed information about a specific vulnerability including severity, affected packages, policy rationale, evidence, dependency paths, and workflow history.

### 3.3 Output Sections

- **Header:** Vulnerability ID, status, severity, VEX status, aliases, assignee, dates.
- **Description:** Full vulnerability description.
- **Affected Packages:** Table of affected packages with versions and fix status.
- **Policy Rationale:** Active policy rules and their evaluation results.
- **Evidence:** Timeline of evidence collected.
- **Dependency Paths:** Transitive dependency chains leading to vulnerability.
- **Workflow History:** Audit ledger of all workflow actions.
- **References:** Links to advisories, patches, and documentation.

### 3.4 Example

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

---

## 4. Workflow Commands

All workflow commands support bulk operations via `--vuln-id` (repeatable) or filter options.

### 4.1 `stella vuln assign`

Assign vulnerabilities to a team member.

```bash
stella vuln assign <assignee> \
  [--vuln-id <id>]... \
  [--filter-severity <level>] \
  [--filter-status <status>] \
  [--filter-purl <pattern>] \
  [--filter-sbom <sbom-id>] \
  [--tenant <tenant-id>] \
  [--idempotency-key <key>] \
  [--json] [--verbose]
```

Example:

```bash
stella vuln assign security-team \
  --filter-severity critical \
  --filter-status open
```

### 4.2 `stella vuln comment`

Add a comment to vulnerabilities.

```bash
stella vuln comment "<text>" \
  --vuln-id CVE-2024-1234 \
  [--json]
```

### 4.3 `stella vuln accept-risk`

Accept risk for vulnerabilities with documented justification.

```bash
stella vuln accept-risk "<justification>" \
  --vuln-id CVE-2024-1234 \
  [--due-date 2025-12-31] \
  [--json]
```

### 4.4 `stella vuln verify-fix`

Mark vulnerabilities as fixed and verified.

```bash
stella vuln verify-fix <fix-version> \
  --vuln-id CVE-2024-1234 \
  [--json]
```

### 4.5 `stella vuln target-fix`

Set target fix version and due date.

```bash
stella vuln target-fix <version> \
  --vuln-id CVE-2024-1234 \
  [--due-date 2025-06-30] \
  [--json]
```

### 4.6 `stella vuln reopen`

Reopen previously closed vulnerabilities.

```bash
stella vuln reopen "<reason>" \
  --vuln-id CVE-2024-1234 \
  [--json]
```

### 4.7 Idempotency

All workflow commands support `--idempotency-key` for safe retries in CI pipelines:

```bash
stella vuln assign security-team \
  --vuln-id CVE-2024-1234 \
  --idempotency-key "assign-cve-2024-1234-$(date +%Y%m%d)"
```

---

## 5. `stella vuln simulate`

### 5.1 Synopsis

```bash
stella vuln simulate \
  [--policy-id <id>] \
  [--policy-version <version>] \
  [--vex-override <vulnId>=<status>]... \
  [--severity-threshold <level>] \
  [--sbom-id <id>]... \
  [--markdown] \
  [--changed-only] \
  [--output <file>] \
  [--tenant <tenant-id>] \
  [--json] [--verbose]
```

### 5.2 Description

Simulates the impact of policy or VEX changes without modifying data. Produces delta summaries showing which vulnerabilities would change status, useful for policy review and CI gates.

### 5.3 Options

| Option | Description |
|--------|-------------|
| `--policy-id <id>` | Policy ID to simulate. |
| `--policy-version <version>` | Policy version to simulate against. |
| `--vex-override <vulnId>=<status>` | Override VEX status for simulation (repeatable). |
| `--severity-threshold <level>` | Minimum severity to include. |
| `--sbom-id <id>` | Limit simulation to specific SBOMs (repeatable). |
| `--markdown` | Include Markdown report for CI. |
| `--changed-only` | Only show items that would change. |
| `--output <file>` | Write Markdown report to file. |
| `--json` | Output full simulation results as JSON. |

### 5.4 Output

The command displays:
- **Summary Panel:** Total evaluated, changed, upgrades, downgrades.
- **Delta Table:** Before/after status comparison with UPGRADE/DOWNGRADE indicators.
- **Markdown Report:** Optional CI-friendly report.

### 5.5 CI Integration Example

```bash
# Run simulation and fail if any downgrades
stella vuln simulate \
  --policy-id prod-policy \
  --changed-only \
  --markdown \
  --output simulation-report.md

# Check exit code
if [ $? -ne 0 ]; then
  echo "Simulation found issues - see simulation-report.md"
  exit 1
fi
```

---

## 6. `stella vuln export`

### 6.1 Synopsis

```bash
stella vuln export \
  --output <file> \
  [--vuln-id <id>]... \
  [--sbom-id <id>]... \
  [--policy-id <id>] \
  [--format ndjson|json] \
  [--include-evidence] \
  [--include-ledger] \
  [--signed] \
  [--tenant <tenant-id>] \
  [--verbose]
```

### 6.2 Description

Exports vulnerability evidence bundles for compliance documentation, audits, or offline analysis. Bundles can be cryptographically signed for integrity verification.

### 6.3 Options

| Option | Description |
|--------|-------------|
| `--output <file>` | Output file path (required). |
| `--vuln-id <id>` | Vulnerability IDs to include (repeatable). |
| `--sbom-id <id>` | SBOM IDs to scope export (repeatable). |
| `--policy-id <id>` | Policy ID for filtering. |
| `--format <fmt>` | Output format: `ndjson` (default) or `json`. |
| `--include-evidence` | Include evidence data (default: true). |
| `--include-ledger` | Include workflow ledger (default: true). |
| `--signed` | Request signed bundle (default: true). |

### 6.4 Example

```bash
stella vuln export \
  --output compliance-bundle.ndjson \
  --sbom-id prod-app-sbom \
  --signed
```

---

## 7. `stella vuln export verify`

### 7.1 Synopsis

```bash
stella vuln export verify <file> \
  [--expected-digest <sha256:hex>] \
  [--public-key <key-file>] \
  [--verbose]
```

### 7.2 Description

Verifies the integrity and optional signature of an exported vulnerability bundle. Use this to validate bundles received from external sources or stored archives.

### 7.3 Example

```bash
stella vuln export verify compliance-bundle.ndjson \
  --expected-digest sha256:abc123... \
  --public-key /path/to/public.pem
```

---

## 8. Exit Codes

| Exit Code | Meaning |
|-----------|---------|
| `0` | Command completed successfully. |
| `1` | General error (see error message). |
| `130` | Operation cancelled by user (Ctrl+C). |

---

## 9. Compliance Checklist

Use these commands to demonstrate vulnerability management compliance:

### 9.1 Vulnerability Inventory

```bash
# Generate complete vulnerability inventory
stella vuln list --json > inventory.json

# Summary by severity
stella vuln list --group-by severity --json > severity-summary.json
```

### 9.2 SLA Compliance

```bash
# Find critical vulns older than 30 days
stella vuln list \
  --severity critical \
  --status open \
  --json | jq '.items[] | select(.updatedAt < (now - 2592000 | todate))'
```

### 9.3 Risk Acceptance Audit

```bash
# Export all risk-accepted vulnerabilities with justifications
stella vuln list --status risk_accepted --json > risk-accepted.json
```

### 9.4 Evidence Bundle for Audit

```bash
# Export signed evidence bundle
stella vuln export \
  --output audit-$(date +%Y%m%d).ndjson \
  --signed

# Verify bundle integrity
stella vuln export verify audit-$(date +%Y%m%d).ndjson
```

---

## 10. CI Pipeline Snippets

### 10.1 GitHub Actions

```yaml
- name: Check Critical Vulnerabilities
  run: |
    count=$(stella vuln list --severity critical --status open --json | jq '.total')
    if [ "$count" -gt 0 ]; then
      echo "::error::Found $count critical open vulnerabilities"
      stella vuln list --severity critical --status open
      exit 1
    fi

- name: Policy Simulation Gate
  run: |
    stella vuln simulate \
      --policy-id ${{ env.POLICY_ID }} \
      --changed-only \
      --markdown \
      --output ${{ github.workspace }}/simulation.md

    cat ${{ github.workspace }}/simulation.md >> $GITHUB_STEP_SUMMARY
```

### 10.2 GitLab CI

```yaml
vuln-check:
  script:
    - stella auth login --token $STELLA_TOKEN
    - |
      if stella vuln list --severity critical --status open --json | jq -e '.total > 0'; then
        echo "Critical vulnerabilities found!"
        stella vuln list --severity critical --status open
        exit 1
      fi
  artifacts:
    reports:
      dotenv: vuln-status.env
```

### 10.3 Jenkins Pipeline

```groovy
stage('Vulnerability Check') {
    steps {
        sh '''
            stella vuln list \
              --severity critical \
              --severity high \
              --status open \
              --csv > vulns.csv
        '''
        archiveArtifacts artifacts: 'vulns.csv'

        script {
            def count = sh(
                script: "stella vuln list --severity critical --status open --json | jq '.total'",
                returnStdout: true
            ).trim().toInteger()

            if (count > 0) {
                error("Found ${count} critical vulnerabilities")
            }
        }
    }
}
```

---

## 11. Offline Operation

When operating in air-gapped environments:

1. Export vulnerability data before going offline:
   ```bash
   stella vuln export --output vuln-bundle.ndjson --signed
   ```

2. Transfer bundle to air-gapped system.

3. Verify bundle integrity:
   ```bash
   stella vuln export verify vuln-bundle.ndjson \
     --expected-digest sha256:...
   ```

For full offline kit support, see the [Offline Kit documentation](../../../24_OFFLINE_KIT.md).

---

## 12. Related Documentation

- [VEX Consensus CLI](./vex-cli.md) - VEX status management
- [Policy Simulation](../../policy/guides/simulation.md) - Policy testing
- [Authentication Guide](./auth-cli.md) - Token management
- [API Reference](../../../09_API_CLI_REFERENCE.md) - Full API documentation