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 brings Stella Ops vulnerability management to the command line: listing and inspecting vulnerabilities, running workflow operations, simulating policy changes, and exporting evidence bundles. All commands support multi-tenant environments and integrate with Stella Ops 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

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

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

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

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 Commands — VEX status management
• Policy Runs & Simulation — Policy testing and simulate mode
• Authentication Commands — Token management
• API & CLI Reference — Full API documentation