171 lines
6.4 KiB
Markdown
Executable File
171 lines
6.4 KiB
Markdown
Executable File
# API and CLI Reference
|
|
|
|
This is the single entry point for operators and integrators who need:
|
|
- API contracts (OpenAPI, schemas, samples)
|
|
- CLI command guides and automation-friendly outputs
|
|
- Cross-cutting conventions (auth, tenancy, errors, determinism, offline posture)
|
|
|
|
Detailed references live under `docs/api/` and `docs/modules/cli/`.
|
|
|
|
## Quick links
|
|
|
|
| Goal | Open this |
|
|
| --- | --- |
|
|
| API conventions (headers, pagination, errors) | `docs/api/overview.md` |
|
|
| API versioning policy | `docs/api/versioning.md` |
|
|
| Gateway tenancy header policy | `docs/api/gateway/tenant-auth.md` |
|
|
| Gateway header hardening rules | `docs/modules/gateway/identity-header-policy.md` |
|
|
| Console workspaces (findings/VEX views) | `docs/api/console/workspaces.md` |
|
|
| Console search and downloads | `docs/api/console/search-downloads.md` |
|
|
| Exceptions API entry point | `docs/api/exceptions.md` |
|
|
| Download aggregated OpenAPI via CLI | `docs/modules/cli/guides/commands/api.md` |
|
|
| CLI command reference (by command group) | `docs/modules/cli/guides/commands/` |
|
|
| CLI authentication and tokens | `docs/modules/cli/guides/commands/auth.md` |
|
|
| CLI Concelier job triggers (`db`) | `docs/modules/cli/guides/commands/db.md`, `docs/CONCELIER_CLI_QUICKSTART.md` |
|
|
| CLI offline/air-gap workflows | `docs/modules/cli/guides/commands/offline.md`, `docs/OFFLINE_KIT.md` |
|
|
| CLI reachability workflow | `docs/modules/cli/guides/commands/reachability.md` |
|
|
| CLI vulnerability workflow | `docs/modules/cli/guides/commands/vuln.md` |
|
|
| Vuln Explorer OpenAPI (v1) | `docs/modules/vuln-explorer/openapi/vuln-explorer.v1.yaml` |
|
|
| Graph Gateway API (draft) | `docs/api/graph.md`, `docs/api/graph-gateway-spec-draft.yaml` |
|
|
|
|
## Where the API contracts live
|
|
|
|
StellaOps treats the OpenAPI documents and JSON schemas as the source of truth for HTTP shapes.
|
|
|
|
- Aggregation/discovery: `docs/api/openapi-discovery.md`
|
|
- Gateway-proxied reference docs + samples: `docs/api/gateway/`
|
|
- Service-specific OpenAPI (selected):
|
|
- `docs/modules/vuln-explorer/openapi/vuln-explorer.v1.yaml`
|
|
- `docs/api/notify-openapi.yaml`
|
|
- `docs/api/taskrunner-openapi.yaml`
|
|
- `docs/api/proofs-openapi.yaml`
|
|
- `docs/api/vexlens-openapi.yaml`
|
|
- API samples and fixtures (deterministic): `docs/api/**/samples/`
|
|
|
|
If you are building an SDK or want a single document for tooling, prefer the CLI OpenAPI download flow:
|
|
- `stella api spec list`
|
|
- `stella api spec download --output ./openapi.yaml --format openapi-yaml`
|
|
|
|
See: `docs/modules/cli/guides/commands/api.md`.
|
|
|
|
## Where the CLI docs live
|
|
|
|
The `stella` CLI is documented as:
|
|
- High-level module docs: `docs/modules/cli/README.md`, `docs/modules/cli/architecture.md`
|
|
- Command guides: `docs/modules/cli/guides/commands/` (one file per command group)
|
|
|
|
CLI docs are written to match repo reality; avoid copying raw endpoint paths into the CLI guides unless they are backed by OpenAPI and tests.
|
|
|
|
## Cross-cutting conventions (high-level)
|
|
|
|
For the detailed contract, see `docs/api/overview.md`. The stable rules to keep in mind:
|
|
|
|
- Auth: bearer tokens are the baseline; sender-constrained modes (DPoP/mTLS) are deployment-profile dependent.
|
|
- Tenancy: every tenant-scoped request must carry an explicit tenant context (see `docs/api/gateway/tenant-auth.md`).
|
|
- Determinism: stable ordering, stable ids, UTC ISO-8601 timestamps, and canonical hashing where applicable.
|
|
- Streaming: some endpoints use NDJSON (`application/x-ndjson`) for deterministic, resumable tile/record streams.
|
|
- Offline-first: workflows must remain runnable in air-gapped mode using Offline Kit bundles and locally verifiable signatures.
|
|
|
|
## stella scan diff
|
|
|
|
Compare ELF binaries between two container images using section hashes.
|
|
|
|
### Synopsis
|
|
|
|
```bash
|
|
stella scan diff --base <image-ref> --target <image-ref> [options]
|
|
```
|
|
|
|
### Options
|
|
|
|
| Option | Description |
|
|
| --- | --- |
|
|
| `--base`, `-b` | Base image reference (tag or digest). |
|
|
| `--target`, `-t` | Target image reference (tag or digest). |
|
|
| `--mode`, `-m` | Analysis mode: `elf`, `pe`, `auto` (default: `auto`, currently uses ELF). |
|
|
| `--emit-dsse`, `-d` | Directory for DSSE attestation output. |
|
|
| `--signing-key` | Path to ECDSA private key (PEM) for DSSE signing. |
|
|
| `--format`, `-f` | Output format: `table`, `json`, `summary` (default: `table`). |
|
|
| `--platform`, `-p` | Platform filter (e.g., `linux/amd64`). |
|
|
| `--include-unchanged` | Include unchanged binaries in output. |
|
|
| `--sections` | Sections to analyze (comma-separated or repeatable). |
|
|
| `--registry-auth` | Path to Docker config for registry authentication. |
|
|
| `--timeout` | Timeout in seconds (default: 300). |
|
|
| `--verbose`, `-v` | Enable verbose output. |
|
|
|
|
Note: `--emit-dsse` requires `--signing-key` to sign the DSSE envelope.
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Basic comparison
|
|
stella scan diff --base myapp:1.0.0 --target myapp:1.0.1
|
|
|
|
# DSSE output with signing key
|
|
stella scan diff --base myapp:1.0.0 --target myapp:1.0.1 \
|
|
--mode=elf --emit-dsse=./attestations --signing-key=./keys/binarydiff.pem
|
|
|
|
# JSON output for automation
|
|
stella scan diff --base myapp:1.0.0 --target myapp:1.0.1 --format=json > diff.json
|
|
|
|
# Specific platform
|
|
stella scan diff --base myapp:1.0.0 --target myapp:1.0.1 --platform=linux/amd64
|
|
```
|
|
|
|
### Output
|
|
|
|
DSSE output produces two files per platform:
|
|
|
|
```
|
|
attestations/
|
|
linux-amd64-binarydiff.dsse.json
|
|
linux-amd64-binarydiff.payload.json
|
|
```
|
|
|
|
See also: `docs/modules/scanner/binary-diff-attestation.md`.
|
|
|
|
## stella image inspect
|
|
|
|
Inspect OCI image manifests and layers.
|
|
|
|
### Synopsis
|
|
|
|
```bash
|
|
stella image inspect <reference> [options]
|
|
```
|
|
|
|
### Options
|
|
|
|
| Option | Description |
|
|
| --- | --- |
|
|
| `--resolve-index`, `-r` | Resolve multi-arch index to platform manifests (default: true). |
|
|
| `--print-layers`, `-l` | Include layer details in output (default: true). |
|
|
| `--platform`, `-p` | Platform filter (e.g., `linux/amd64`). |
|
|
| `--output`, `-o` | Output format: `table`, `json` (default: `table`). |
|
|
| `--timeout` | Timeout in seconds (default: 60). |
|
|
| `--verbose`, `-v` | Enable verbose output. |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Basic inspection
|
|
stella image inspect nginx:latest
|
|
|
|
# JSON output
|
|
stella image inspect nginx:latest --output json
|
|
|
|
# Filter to a single platform
|
|
stella image inspect nginx:latest --platform linux/amd64
|
|
|
|
# Local registry over HTTP
|
|
stella image inspect http://localhost:5000/myapp:1.0.0
|
|
```
|
|
|
|
### Exit codes
|
|
|
|
| Code | Meaning |
|
|
| --- | --- |
|
|
| `0` | Success |
|
|
| `1` | Image not found |
|
|
| `2` | Error (auth, network, invalid input, timeout) |
|