git.stella-ops.org/docs/modules/cli/guides/vuln-explorer-cli.md

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

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:

stella vuln list --severity critical

Group by status for reporting:

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

Export CSV for compliance audit:

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

---

3. stella vuln show

3.1 Synopsis

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

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.

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:

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

4.2 stella vuln comment

Add a comment to vulnerabilities.

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

4.3 stella vuln accept-risk

Accept risk for vulnerabilities with documented justification.

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.

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.

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.

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:

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

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

# 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

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

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

---

7. stella vuln export verify

7.1 Synopsis

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

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

# 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

# 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

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

9.4 Evidence Bundle for Audit

# 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

- 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

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

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:

   stella vuln export --output vuln-bundle.ndjson --signed
   

2. Transfer bundle to air-gapped system.

3. Verify bundle integrity:

   stella vuln export verify vuln-bundle.ndjson \
     --expected-digest sha256:...
   

For full offline kit support, see the Offline Kit documentation.

---

12. Related Documentation

• VEX Consensus CLI - VEX status management
• Policy Simulation - Policy testing
• Authentication Guide - Token management
• API Reference - Full API documentation