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

docs consolidation

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-24 12:38:14 +02:00
parent 7503c19b8f
commit 9a08d10b89
215 changed files with 2188 additions and 9623 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/modules/cli/guides/authentication.md
View File

@@ -1,18 +0,0 @@
# CLI Authentication — Draft Skeleton (2025-12-05 UTC)
Status: draft placeholder. Inputs pending: DVDO0110 env vars, token formats, monitoring plan.
## Supported Flows
- Device/code, PAT, workload identity (to confirm).
## Configuration
- Env vars and flags (to be filled once finalized).
## Multi-Tenant Considerations
- Scope selection and defaults.
## Troubleshooting
- Common errors; log paths; retry/backoff guidance.
## Open TODOs
- Insert definitive env var list and examples when available.

94
docs/modules/cli/guides/commands/auth.md
View File

@@ -1,19 +1,85 @@
# stella auth — Command Guide
# stella auth - Command Guide
The `stella auth` command group manages Authority-backed authentication and token operations used by other CLI commands.
## Commands
- `stella auth login --token <token> [--url <baseUrl>]`
- `stella auth status`
- `stella auth logout`
## Flags
- `--url`: API base URL; defaults to config/env.
- `--token`: bearer token or OIDC device code (future); stored in config if allowed.
### auth login
## Behaviour
- Login writes token to config file or keyring (where supported) with deterministic permissions; never echoes secrets.
- Status prints current user/tenant scopes if available; uses exit code 3 when unauthenticated.
- Logout removes stored token and cached session data.
Acquire and cache an access token using the configured Authority credentials.
```bash
stella auth login
stella auth login --force
```
Notes:
- `--force` ignores cached tokens and forces re-authentication.
- Credential sources are configuration-driven (profile/env). This command does not accept raw tokens on the command line.
### auth status / whoami / logout
```bash
stella auth status
stella auth whoami
stella auth logout
```
Behavior:
- `status` reports whether a cached token exists and whether it is still valid.
- `whoami` prints cached token claims (subject, scopes, expiry) for diagnostics.
- `logout` removes cached tokens for the active credentials.
### auth revoke export / verify
Export or verify Authority revocation bundles.
```bash
stella auth revoke export --output ./revocation-export
stella auth revoke verify --bundle ./revocation-bundle.json --signature ./revocation-bundle.json.jws --key ./authority.pub.pem
```
### auth token mint
Mint a service account token (requires appropriate Authority permissions).
```bash
stella auth token mint --service-account concelier-jobs \
--scope concelier.jobs.trigger --scope advisory:ingest --scope advisory:read \
--tenant tenant-default \
--reason "scheduled ingestion" \
--raw
```
Flags:
- `--service-account` / `-s` (required): service account identifier.
- `--scope` (repeatable): scopes to include in the minted token.
- `--expires-in` (optional): expiry in seconds.
- `--tenant` (optional): tenant context.
- `--reason` (optional): audit reason.
- `--raw`: output only the token value (automation-friendly).
### auth token delegate
Delegate your current token to another principal.
```bash
stella auth token delegate --to user@example.org \
--scope advisory:read \
--tenant tenant-default \
--reason "support session" \
--raw
```
Flags:
- `--to` (required): principal identifier to delegate to.
- `--scope` (repeatable): delegated scopes (must be a subset of the current token).
- `--expires-in` (optional): expiry in seconds (defaults to remaining token lifetime).
- `--tenant` (optional): tenant context.
- `--reason` (required): audit reason.
- `--raw`: output only the token value (automation-friendly).
## Offline notes
- `auth login` and token mint/delegate require connectivity to Authority.
- `auth revoke verify`, `status`, `whoami`, and `logout` can operate using local cached state.
## Offline/air-gap notes
- Login requires network; if `--offline` is set, command must fail with exit code 5.
- Status/logout work offline using cached credentials only.

60
docs/modules/cli/guides/commands/db.md Normal file
View File

@@ -0,0 +1,60 @@
# stella db - Command Guide
The `stella db` command group triggers Concelier database operations via backend jobs (connector stages, merge reconciliation, exports).
These commands are operational: they typically require Authority authentication and appropriate Concelier scopes.
## Commands
### db fetch
Trigger a connector stage (`fetch`, `parse`, or `map`) for a given source.
```bash
stella db fetch --source osv --stage fetch
stella db fetch --source osv --stage parse
stella db fetch --source osv --stage map
```
Options:
- `--source` (required): connector identifier (for example `osv`, `redhat`, `ghsa`).
- `--stage` (optional): `fetch`, `parse`, or `map` (defaults to `fetch`).
- `--mode` (optional): connector-specific mode (for example `init`, `resume`, `cursor`).
### db merge
Run canonical merge reconciliation.
```bash
stella db merge
```
### db export
Run Concelier export jobs.
```bash
stella db export --format json
stella db export --format trivy-db --delta
```
Options:
- `--format` (optional): `json` or `trivy-db` (defaults to `json`).
- `--delta` (optional): request a delta export when supported.
- `--publish-full` / `--publish-delta` (optional): override whether exports are published (true/false).
- `--bundle-full` / `--bundle-delta` (optional): override whether offline bundles include full/delta exports (true/false).
## Common setup
Point the CLI at the Concelier base URL:
```bash
export STELLAOPS_BACKEND_URL="https://concelier.example.internal"
```
Authenticate:
```bash
stella auth login
```
See: `docs/10_CONCELIER_CLI_QUICKSTART.md` and `docs/modules/concelier/operations/authority-audit-runbook.md`.

334
docs/modules/cli/guides/commands/reachability.md
View File

@@ -1,265 +1,157 @@
# stella reachability — Command Guide
# stella reachability - Command Guide
## Overview
The `stella reachability` command group provides reachability analysis capabilities for vulnerability exploitability assessment. It supports call graph upload, analysis listing, and detailed reachability explanations.
The `stella reachability` command group uploads call graphs and queries reachability analyses for vulnerability exploitability assessment.
Typical flow:
1. Generate a call graph locally (optional): `stella scan graph ...`
2. Upload the call graph: `stella reachability upload-callgraph ...`
3. List analyses: `stella reachability list ...`
4. Explain reachability: `stella reachability explain ...`
Notes:
- In multi-tenant environments, pass `--tenant` explicitly.
- Outputs are deterministic: stable ordering, UTC timestamps, and cursor-based paging where applicable.
## Generate a call graph (stella scan graph)
`stella scan graph` extracts a call graph from source code using a language-specific extractor:
- Executable name: `stella-callgraph-<lang>`
- Must be available in `PATH`
Examples:
```bash
# .NET solution
stella scan graph \
--lang dotnet \
--target . \
--sln ./MySolution.sln \
--output ./callgraph.json
# Node.js project (writes JSON to stdout)
stella scan graph \
--lang node \
--target ./service \
--format json > ./callgraph.json
```
Supported `stella scan graph` output formats:
- `json` (default; suitable for upload)
- `dot`
- `summary` (prints only a summary; does not emit graph JSON)
If you generate call graphs with other tooling, uploads support `json`, `proto`, and `dot` formats (or `auto` detection).
## Commands
### Upload Call Graph (CLI-SIG-26-001)
### upload-callgraph
Upload a call graph for reachability analysis.
```bash
# Upload a call graph for reachability analysis
stella reachability upload-callgraph \
--path <call-graph-file> \
[--tenant <id>] \
[--scan-id <id>] \
[--asset-id <id>] \
[--format auto|json|proto|dot] \
[--json]
--path ./callgraph.json \
--scan-id scan-12345 \
--tenant acme \
--format auto
```
**Options:**
Options:
| Flag | Description |
|------|-------------|
| `--path` / `-p` | Path to the call graph file (required) |
| `--scan-id` | Scan identifier to associate with the call graph |
| `--asset-id` / `-a` | Asset identifier to associate with the call graph |
| `--format` / `-f` | Call graph format: `auto` (default), `json`, `proto`, `dot` |
| --- | --- |
| `--path`, `-p` | Path to the call graph file (required). |
| `--scan-id` | Scan identifier to associate with the call graph. |
| `--asset-id`, `-a` | Asset identifier to associate with the call graph. |
| `--format`, `-f` | `auto` (default), `json`, `proto`, `dot`. |
| `--tenant`, `-t` | Tenant identifier (recommended in multi-tenant envs). |
| `--json` | Emit raw JSON payload instead of formatted output. |
**Required:** At least one of `--scan-id` or `--asset-id`.
Required: at least one of `--scan-id` or `--asset-id`.
**Supported Call Graph Formats:**
- JSON (native format)
- Protocol Buffers (proto)
- DOT/GraphViz format
### list
### List Reachability Analyses (CLI-SIG-26-001)
List reachability analyses.
```bash
# List reachability analyses
stella reachability list \
[--tenant <id>] \
[--scan-id <id>] \
[--asset-id <id>] \
[--status pending|processing|completed|failed] \
[--limit <num>] \
[--offset <num>] \
[--json]
--scan-id scan-12345 \
--status completed \
--limit 20 \
--json
```
**Options:**
Options:
| Flag | Description |
|------|-------------|
| `--scan-id` | Filter by scan identifier |
| `--asset-id` / `-a` | Filter by asset identifier |
| `--status` | Filter by analysis status |
| `--limit` / `-l` | Maximum number of results (default 100) |
| `--offset` / `-o` | Pagination offset |
| --- | --- |
| `--scan-id` | Filter by scan identifier. |
| `--asset-id`, `-a` | Filter by asset identifier. |
| `--status` | Filter by status (`pending`, `processing`, `completed`, `failed`). |
| `--limit`, `-l` | Maximum number of results (default 100). |
| `--offset`, `-o` | Pagination offset. |
| `--tenant`, `-t` | Tenant identifier. |
| `--json` | Emit raw JSON payload. |
**Output Columns:**
- Analysis ID
- Asset name/ID
- Status (pending, processing, completed, failed)
- Reachable count
- Unreachable count
- Unknown count
- Created timestamp
### explain
### Explain Reachability (CLI-SIG-26-001)
Explain reachability for a vulnerability ID or a package PURL.
```bash
# Explain reachability for a vulnerability or package
stella reachability explain \
--analysis-id <id> \
[--tenant <id>] \
[--vuln-id <cve-id>] \
[--purl <package-url>] \
[--call-paths] \
[--json]
--analysis-id RA-abc123 \
--vuln-id CVE-2024-1234 \
--call-paths
```
**Options:**
Options:
| Flag | Description |
|------|-------------|
| `--analysis-id` / `-i` | Analysis identifier (required) |
| `--vuln-id` / `-v` | Vulnerability identifier to explain |
| `--purl` | Package URL to explain |
| `--call-paths` | Include detailed call paths in the explanation |
| --- | --- |
| `--analysis-id`, `-i` | Analysis identifier (required). |
| `--vuln-id`, `-v` | Vulnerability identifier to explain. |
| `--purl` | Package URL to explain. |
| `--call-paths` | Include detailed call paths in the explanation. |
| `--tenant`, `-t` | Tenant identifier. |
| `--json` | Emit raw JSON payload. |
**Required:** At least one of `--vuln-id` or `--purl`.
Required: at least one of `--vuln-id` or `--purl`.
**Output:**
- Reachability state (reachable, unreachable, unknown)
- Reachability score (0-1)
- Confidence level
- Reasoning explanation
- Affected functions list
- Call paths (when `--call-paths` is used)
## Integration with Policy Simulation (CLI-SIG-26-002)
## Policy simulation integration
Reachability overrides can be applied during policy simulation:
```bash
stella policy simulate P-7 \
--reachability-state "CVE-2024-1234:unreachable" \
--reachability-state "pkg:npm/lodash@4.17.0:reachable" \
--reachability-state "pkg:npm/lodash@4.17.21:reachable" \
--reachability-score "CVE-2024-5678:0.25"
```
**Override Format:**
- State: `<identifier>:<state>` where state is `reachable`, `unreachable`, `unknown`, or `indeterminate`
- Score: `<identifier>:<score>` where score is a decimal between 0 and 1
Override formats:
- State: `<identifier>:<reachable|unreachable|unknown|indeterminate>`
- Score: `<identifier>:<0..1>`
**Identifier Types:**
- Vulnerability ID: `CVE-XXXX-XXXX`, `GHSA-xxxx-xxxx-xxxx`
- Package URL: `pkg:npm/package@version`, `pkg:maven/group/artifact@version`
Identifier types:
- Vulnerability ID: `CVE-...`, `GHSA-...`
- Package URL: `pkg:...`
## Exit Codes
## Reachability states
| State | Meaning |
| --- | --- |
| `reachable` | Vulnerable code is reachable from entry points. |
| `unreachable` | Vulnerable code is not reachable. |
| `unknown` | Insufficient data to decide. |
| `indeterminate` | Inconclusive (dynamic dispatch/reflection/etc). |
## Exit codes
| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error or upload failure |
| 4 | Input validation error |
| 130 | Operation cancelled by user |
## JSON Schema: ReachabilityExplainResult
```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"analysisId": { "type": "string" },
"vulnerabilityId": { "type": "string" },
"packagePurl": { "type": "string" },
"reachabilityState": {
"type": "string",
"enum": ["reachable", "unreachable", "unknown", "indeterminate"]
},
"reachabilityScore": { "type": "number", "minimum": 0, "maximum": 1 },
"confidence": { "type": "string" },
"reasoning": { "type": "string" },
"callPaths": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pathId": { "type": "string" },
"depth": { "type": "integer" },
"entryPoint": { "$ref": "#/$defs/function" },
"frames": { "type": "array", "items": { "$ref": "#/$defs/function" } },
"vulnerableFunction": { "$ref": "#/$defs/function" }
}
}
},
"affectedFunctions": {
"type": "array",
"items": { "$ref": "#/$defs/function" }
}
},
"$defs": {
"function": {
"type": "object",
"properties": {
"name": { "type": "string" },
"signature": { "type": "string" },
"className": { "type": "string" },
"packageName": { "type": "string" },
"filePath": { "type": "string" },
"lineNumber": { "type": "integer" }
}
}
}
}
```
## Examples
### Upload a call graph
```bash
# Upload call graph for a specific scan
stella reachability upload-callgraph \
--path ./callgraph.json \
--scan-id scan-12345 \
--format json
# Upload with auto-detection
stella reachability upload-callgraph \
--path ./app-callgraph.dot \
--asset-id my-application
```
### List recent analyses
```bash
# List all completed analyses for an asset
stella reachability list \
--asset-id my-application \
--status completed \
--json
# List analyses with pagination
stella reachability list \
--limit 20 \
--offset 40
```
### Explain vulnerability reachability
```bash
# Explain with call paths
stella reachability explain \
--analysis-id RA-abc123 \
--vuln-id CVE-2024-1234 \
--call-paths
# Explain package reachability
stella reachability explain \
--analysis-id RA-abc123 \
--purl "pkg:npm/lodash@4.17.21" \
--json
```
### Policy simulation with reachability overrides
```bash
# Mark specific vulnerability as unreachable
stella policy simulate P-7 \
--reachability-state "CVE-2024-1234:unreachable" \
--explain
# Set low reachability score
stella policy simulate P-7 \
--reachability-score "pkg:npm/axios@0.21.0:0.1"
```
## Reachability States
| State | Description |
|-------|-------------|
| `reachable` | Vulnerable code is reachable from application entry points |
| `unreachable` | Vulnerable code cannot be reached during execution |
| `unknown` | Reachability cannot be determined with available information |
| `indeterminate` | Analysis inconclusive due to dynamic dispatch or reflection |
## Call Graph Generation
Call graphs can be generated using various tools:
- **Java:** [WALA](https://github.com/wala/WALA), [Soot](https://github.com/soot-oss/soot)
- **JavaScript/Node.js:** [callgraph](https://www.npmjs.com/package/callgraph)
- **Python:** [pycg](https://github.com/vitsalis/pycg)
- **Go:** `go build -gcflags="-m"` + static analysis
- **C/C++:** [LLVM](https://llvm.org/) call graph pass
## Best Practices
1. **Upload call graphs after each build** to maintain accurate reachability data
2. **Use asset IDs** for long-lived applications to track reachability changes over time
3. **Include call paths** when debugging unexpected reachability results
4. **Apply reachability overrides** in policy simulation to model remediation scenarios
5. **Monitor unreachable counts** as a metric for dependency hygiene
| --- | --- |
| `0` | Success. |
| `1` | Command failed. |
| `4` | Input validation error. |
| `130` | Operation cancelled. |

219
docs/modules/cli/guides/commands/vuln.md
View File

@@ -1,25 +1,206 @@
# stella vuln — Command Guide
# 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
- `stella vuln list --query <filter> [--group-by <field>] [--output json|ndjson|table] [--offline]`
- `stella vuln get --id <vulnId> [--output json|table] [--offline]`
- `stella vuln simulate --from <policyA> --to <policyB> --subjects <path> [--offline]`
## Flags (common)
- `--offline`: read from cached snapshots; fail with exit code 5 if network would be used.
- `--policy <id>`: scope queries to a policy projection.
- `--page-size`, `--page-token`: deterministic pagination.
- `--group-by`: `cve`, `package`, `status`, `advisory` (results stay stably ordered within groups).
### observations
## Inputs/outputs
- Inputs: Vuln Explorer API; optional cached snapshots when offline.
- Outputs: sorted lists or detail documents with provenance pointers (`advisoryId`, `evidenceIds`, `consensusId`).
- Exit codes follow `output-and-exit-codes.md`; 4 for not found, 5 for offline violation.
List raw advisory observations (useful for overlay consumers).
## Determinism rules
- Lists sorted by primary key then timestamp; group-by keeps stable ordering inside each bucket.
- Timestamps UTC ISO-8601; hashes lower-case hex.
```bash
stella vuln observations \
--tenant acme \
--alias CVE-2024-1234 \
--limit 50 \
--json
```
## Offline/air-gap notes
- Use cached snapshots (`--offline`) when remote Explorer is unavailable; commands must not attempt network calls in this mode.
- Simulation must read local policy snapshots and subjects when offline.
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. |

82
docs/modules/cli/guides/graph-and-vuln.md
View File

@@ -1,82 +0,0 @@
# CLI Guide · Graph & Vulnerability
Status: Draft (2025-11-26) — reflects current Graph API surface; Vuln API pending (see docs/api/vuln.md).
## Prereqs
- `stellaops-cli` built from current repo.
- Auth token with scopes: `graph:read`, `graph:query`, `graph:export` (and `vuln:read` when Vuln API lands).
- Tenant header is required for all calls (`--tenant`).
## Commands
### Search graph
```bash
stella graph search \
--tenant acme \
--kinds component \
--query "pkg:npm/" \
--limit 20 \
--format ndjson
```
Outputs NDJSON tiles (`node`, optional `cursor`).
### Query graph with budgets
```bash
stella graph query \
--tenant acme \
--kinds component \
--query widget \
--include-edges \
--budget-tiles 200 \
--budget-nodes 150 \
--budget-edges 100 \
--format ndjson
```
Returns nodes/edges/stats/cursor with cost metadata. If edge budget is exceeded, an `error` tile with `GRAPH_BUDGET_EXCEEDED` is returned.
### Paths
```bash
stella graph paths \
--tenant acme \
--source gn:acme:component:one \
--target gn:acme:component:two \
--max-depth 4 \
--include-edges \
--format ndjson
```
### Diff snapshots
```bash
stella graph diff \
--tenant acme \
--snapshot-a snapA \
--snapshot-b snapB \
--include-edges \
--format ndjson
```
### Export graph
```bash
stella graph export \
--tenant acme \
--format ndjson \
--include-edges \
--kinds component \
--query "pkg:npm/" \
--out graph-export.ndjson
```
Manifest is returned with jobId, sha256, size, and download URL; CLI downloads to `--out`.
### Vuln lookup (placeholder)
Pending Vuln Explorer API; for now use graph search/query to inspect impacted components. See `docs/api/vuln.md`.
## Exit codes
- `0` success
- `2` validation error (missing kinds/tenant/scopes)
- `3` budget exceeded (error tile received)
- `4` network/auth failure
## Tips
- Add `--format table` (when available) for quick summaries; default is NDJSON.
- Use `--cursor` from a previous call to page results.
- To sample overlays, pass `--include-overlays` (budget permitting).