stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 12 Releases Wiki Activity

up
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details

Browse Source
This commit is contained in:
StellaOps Bot
2025-11-28 09:40:40 +02:00
parent 1c6730a1d2
commit 05da719048
206 changed files with 34741 additions and 1751 deletions
Download Patch File Download Diff File Expand all files Collapse all files

502
docs/modules/cli/guides/vuln-explorer-cli.md Normal file
View File

@@ -0,0 +1,502 @@
# 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