git.stella-ops.org/docs/09_API_CLI_REFERENCE.md

# API & CLI Reference

Purpose – give operators and integrators a single, authoritative spec for REST/GRPC calls and first‑party CLI tools (stella-cli, zastava, stella).
Everything here is source‑of‑truth for generated Swagger/OpenAPI and the --help screens in the CLIs.

---

## 0 Quick Glance

Area	Call / Flag	Notes
Scan entry	POST /scan	Accepts SBOM or image; sub‑5 s target
Delta check	POST /layers/missing	<20 ms reply; powers delta SBOM feature
Rate‑limit / quota	—	Headers X‑Stella‑Quota‑Remaining, X‑Stella‑Reset on every response
Policy I/O	GET /policy/export, POST /policy/import	YAML now; Rego coming
Policy lint	POST /policy/validate	Returns 200 OK if ruleset passes
Auth	POST /connect/token (OpenIddict)	Client‑credentials preferred
Health	GET /healthz	Simple liveness probe
Attestation *	POST /attest (TODO Q1‑2026)	SLSA provenance + Rekor log
CLI flags	--sbom-type --delta --policy-file	Added to stella

* Marked TODO → delivered after sixth month (kept on Feature Matrix “To Do” list).

---

## 1 Authentication

Stella Ops uses OAuth 2.0 / OIDC (token endpoint mounted via OpenIddict).

POST /connect/token
Content‑Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=ci‑bot&
client_secret=REDACTED&
scope=stella.api

Successful response:

{
  "access_token": "eyJraWQi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Tip

 – pass the token via Authorization: Bearer <token> on every call.

---

## 2 REST API

### 2.0 Obtain / Refresh Offline‑Token

POST /token/offline
Authorization: Bearer <admin‑token>

Body field	Required	Example	Notes
expiresDays	no	30	Max 90 days

{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "expires": "2025‑08‑17T00:00:00Z"
}

Token is signed with the backend’s private key and already contains "maxScansPerDay": {{ quota_token }}.

### 2.1 Scan – Upload SBOM or Image

POST /scan

Param / Header	In	Required	Description
X‑Stella‑Sbom‑Type	header	no	trivy-json-v2, spdx-json, cyclonedx-json; omitted ➞ auto‑detect
?threshold	query	no	low, medium, high, critical; default critical
body	body	yes	Either SBOM JSON or Docker image tarball/upload URL

Every successful /scan response now includes:

Header	Example
X‑Stella‑Quota‑Remaining	129
X‑Stella‑Reset	2025‑07‑18T23:59:59Z
X‑Stella‑Token‑Expires	2025‑08‑17T00:00:00Z

Response 200 (scan completed):

{
  "digest": "sha256:…",
  "summary": {
    "Critical": 0,
    "High": 3,
    "Medium": 12,
    "Low": 41
  },
  "policyStatus": "pass",
  "quota": {
    "remaining": 131,
    "reset": "2025-07-18T00:00:00Z"
  }
}

Response 202 – queued; polling URL in Location header.

---

### 2.2 Delta SBOM – Layer Cache Check

POST /layers/missing
Content‑Type: application/json
Authorization: Bearer <token>

{
  "layers": [
    "sha256:d38b...",
    "sha256:af45..."
  ]
}

Response 200 — <20 ms target:

{
  "missing": [
    "sha256:af45..."
  ]
}

Client then generates SBOM only for the missing layers and re‑posts /scan.

---

### 2.3 Policy Endpoints

Method	Path	Purpose
GET	/policy/export	Download live YAML ruleset
POST	/policy/import	Upload YAML or Rego; replaces active
POST	/policy/validate	Lint only; returns 400 on error
GET	/policy/history	Paginated change log (audit trail)

# Example import payload (YAML)
version: "1.0"
rules:
  - name: Ignore Low dev
    severity: [Low, None]
    environments: [dev, staging]
    action: ignore

Validation errors come back as:

{
  "errors": [
    {
      "path": "$.rules[0].severity",
      "msg": "Invalid level 'None'"
    }
  ]
}

---

### 2.4 Attestation (Planned – Q1‑2026)

POST /attest

Param	Purpose
body (JSON)	SLSA v1.0 provenance doc
	Signed + stored in local Rekor mirror

Returns 202 Accepted and Location: /attest/{id} for async verify.

---

### 2.5 Misc Endpoints

Path	Method	Description
/healthz	GET	Liveness; returns "ok"
/metrics	GET	Prometheus exposition (OTel)
/version	GET	Git SHA + build date

---

## 3 First‑Party CLI Tools

### 3.1 stella

Package SBOM + Scan + Exit code – designed for CI.

Usage: stella [OPTIONS] IMAGE_OR_SBOM

Flag / Option	Default	Description
--server	http://localhost:8080	API root
--token	env STELLA_TOKEN	Bearer token
--sbom-type	auto	Force trivy-json-v2/spdx-json/cyclonedx-json
--delta	false	Enable delta layer optimisation
--policy-file	none	Override server rules with local YAML/Rego
--threshold	critical	Fail build if ≥ level found
--output-json	none	Write raw scan result to file
--wait-quota	true	If 429 received, automatically wait Retry‑After and retry once.

Exit codes

Code	Meaning
0	Scan OK, policy passed
1	Vulnerabilities ≥ threshold OR policy block
2	Internal error (network etc.)

---

### 3.2 stella‑zastava

Daemon / K8s DaemonSet – watch container runtime, push SBOMs.

Core flags (excerpt):

Flag	Purpose
--mode	listen (default) / enforce
--filter-image	Regex; ignore infra/busybox images
--threads	Worker pool size

---

### 3.3 stellopsctl

Admin utility – policy snapshots, feed status, user CRUD.

Examples:

stellopsctl policy export > policies/backup-2025-07-14.yaml
stellopsctl feed refresh  # force OSV merge
stellopsctl user add dev-team --role developer

---

## 4 Error Model

Uniform problem‑details object (RFC 7807):

{
  "type": "https://stella-ops.org/probs/validation",
  "title": "Invalid request",
  "status": 400,
  "detail": "Layer digest malformed",
  "traceId": "00-7c39..."
}

---

## 5 Rate Limits

Default 40 requests / second / token.
429 responses include Retry-After seconds header.

---

## 6 FAQ & Tips

• Skip SBOM generation in CI – supply a pre‑built SBOM and add ?sbom-only=true to /scan for <1 s path.
• Air‑gapped? – point --server to http://oukgw:8080 inside the Offline Update Kit.
• YAML vs Rego – YAML simpler; Rego unlocks time‑based logic (see samples).
• Cosign verify plug‑ins – enable SCANNER_VERIFY_SIG=true env to refuse unsigned plug‑ins.

---

## 7 Planned Changes (Beyond 6 Months)

These stay in Feature Matrix → To Do until design is frozen.

Epic / Feature	API Impact Sketch
SLSA L1‑L3 attestation	/attest (see §2.4)
Rekor transparency log	/rekor/log/{id} (GET)
Plug‑in Marketplace metadata	/plugins/market (catalog)
Horizontal scaling controls	POST /cluster/node (add/remove)
Windows agent support	Update LSAPI to PDE, no API change

---

## 8 References

• OpenAPI YAML → /openapi/v1.yaml (served by backend)
• OAuth2 spec: https://datatracker.ietf.org/doc/html/rfc6749
• SLSA spec: https://slsa.dev/spec/v1.0

---

## 9 Changelog (truncated)

• 2025‑07‑14 – added delta SBOM, policy import/export, CLI --sbom-type.
• 2025‑07‑12 – initial public reference.

---