Stella Ops · self‑hosted supply‑chain‑security platform
Audience – core maintainers and external contributors who need an authoritative checklist of what the software must do (functional requirements) and how well it must do it (non‑functional requirements). Implementation details belong in Module Specs or ADRs—not here.
This SRS defines everything the v0.8‑beta release of Stella Ops must do, including the Free‑tier daily quota of 333 SBOM scans per token.
Scope includes core platform, CLI, UI, quota layer, and plug‑in host; commercial or closed‑source extensions are explicitly out‑of‑scope.
| Term | Meaning |
|---|
| SBOM | Software Bill of Materials |
| Delta SBOM | Partial SBOM covering only image layers not previously analysed |
| Registry | Anonymous, read‑only Docker Registry v2 hosted internally |
| OPA | Open Policy Agent (Rego policy engine) |
| Muting Policy | Rule that downgrades or ignores specific findings |
| SLSA | Supply‑chain Levels for Software Artifacts (provenance framework) |
| Rekor | Sigstore transparency log for signatures |
The platform consists of:
- Stella Ops Backend – REST API, queue, policy engine, DB.
- StellaOps.Registry – internal container registry for agents.
- Stella CLI – extracts SBOMs; supports multi‑format & delta.
- Zastava Agent – enforcement hook for admission‑control scenarios.
- Web UI – React/Next.js SPA consuming backend APIs.
- Plug‑ins – hot‑load binaries extending scanners, attestations, etc.
All services run in Docker Compose or Kubernetes with optional Internet access.
| ID | Requirement | Priority | Verification |
|---|
| F‑1 | System SHALL ingest Trivy‑JSON, SPDX‑JSON, CycloneDX‑JSON files. | MUST | UT‑SBOM‑001 |
| F‑2 | System SHALL auto‑detect SBOM type when sbomType param omitted. | MUST | UT‑SBOM‑002 |
| F‑3 | System SHALL cache analysed layers and reuse them in subsequent scans. | MUST | IT‑CACHE‑001 |
| F‑4 | System SHALL enforce a soft limit of 333 scans per token per UTC day. | MUST | IT‑QUOTA‑001 |
| F‑4a | Remaining quota SHALL be persisted in Redis under key quota:<token>:<yyyy‑mm‑dd>. | MUST | UT‑QUOTA‑REDIS |
| F‑4b | Exhausted quota SHALL trigger HTTP 429 with Retry‑After header (UTC midnight). | MUST | IT‑QUOTA‑002 |
| F‑4c | When quota is ≤ 40 % remaining, UI banner MUST turn yellow and show count‑down. | SHOULD | UI‑E2E‑005 |
| F‑4d | /quota endpoint SHALL return JSON {"limit":{{ quota_token }} ,"remaining":N,"resetsAt":"<ISO‑8601>"}. | SHOULD | API‑DOC‑003 |
| F‑5 | Policy engine SHALL evaluate YAML rules against scan results. | MUST | UT‑POL‑001 |
| F‑6 | Hot‑pluggable .NET plug‑ins SHALL be loadable without service restart. | MUST | IT‑PLUGIN‑001 |
| F‑7 | CLI (stella scan) SHOULD exit non‑zero when CVSS≥7 vulnerabilities found. | SHOULD | CL‑INT‑003 |
| (… all previously documented F‑8 – F‑12 rows retained unchanged …) | | | |
| Ref | Requirement |
|---|
| FR‑REPO‑1 | Platform SHALL include StellaOps.Registry exposing Docker Registry v2 API (ports 5000/443). |
| FR‑REPO‑2 | Registry SHALL allow anonymous, read‑only pulls for at least three images:
• stella/sbom‑builder
• stella/cli
• stella/zastava. |
| FR‑REPO‑3 | Registry MAY enable optional basic‑auth without code changes. |
| Ref | Requirement |
|---|
| FR‑SBOM‑1 | SBOM builder SHALL produce Trivy‑JSON and at least one additional format: SPDX‑JSON and CycloneDX‑JSON. |
| FR‑SBOM‑2 | For every generated SBOM, builder SHALL create a side‑car file <image>.sbom.type containing the format identifier. |
| FR‑SBOM‑3 | Stella CLI SHALL read the .sbom.type file and include sbomType parameter when uploading. |
| FR‑SBOM‑4 | Backend SHALL auto‑detect SBOM type when parameter is missing. |
| FR‑SBOM‑5 | UI Settings SHALL expose a dropdown to select default SBOM format (system‑wide fallback). |
| Ref | Requirement |
|---|
| FR‑DELTA‑1 | Builder SHALL compute SHA256 digests of each image layer and POST array to /layers/missing; response time ≤ 20 ms (P95). |
| FR‑DELTA‑2 | Builder SHALL generate SBOM only for layers returned as “missing”. |
| FR‑DELTA‑3 | End‑to‑end warm scan time (image differing by ≤ 2 layers) SHALL be ≤ 1 s (P95). |
| Ref | Requirement |
|---|
| FR‑POLICY‑1 | Backend SHALL store policies as YAML by default, convertible to Rego for advanced use‑cases. |
| FR‑POLICY‑2 | Each policy change SHALL create an immutable history record (timestamp, actor, diff). |
| FR‑POLICY‑3 | REST endpoints /policy/import, /policy/export, /policy/validate SHALL accept YAML or Rego payloads. |
| FR‑POLICY‑4 | Web UI Policies tab SHALL provide Monaco editor with linting for YAML and Rego. |
| FR‑POLICY‑5 | StellaOps.MutePolicies module SHALL expose CLI stella policies apply --file scan‑policy.yaml. |
| Ref | Requirement |
|---|
| FR‑SLSA‑1 | TODO – Generate provenance in SLSA‑Provenance v0.2 for each SBOM. |
| FR‑REKOR‑1 | TODO – Sign SBOM hashes and upload to local Rekor mirror; verify during scan. |
| Ref | Requirement |
|---|
| FR‑CLI‑1 | CLI stella scan SHALL accept --sbom-type {trivy,spdx,cyclonedx,auto}. |
| FR‑API‑1 | API /scan SHALL accept sbomType query/body field (optional). |
| FR‑API‑2 | API /layers/missing SHALL accept JSON array of digests and return JSON array of missing digests. |
| Ref | Category | Requirement |
|---|
| NFR‑PERF‑1 | Performance | P95 cold scan ≤ 5 s; warm ≤ 1 s (see FR‑DELTA‑3). |
| NFR‑PERF‑2 | Throughput | System shall sustain 60 concurrent scans on 8‑core node without queue depth >10. |
| NFR‑AVAIL‑1 | Availability | All services shall start offline; any Internet call must be optional. |
| NFR‑SCAL‑1 | Scalability | Horizontal scaling via Kubernetes replicas for backend, Redis Sentinel, Mongo replica set. |
| NFR‑SEC‑1 | Security | All inter‑service traffic shall use TLS or localhost sockets. |
| NFR‑COMP‑1 | Compatibility | Platform shall run on x86‑64 Linux kernel ≥ 5.10; Windows agents (TODO > 6 mo) must support Server 2019+. |
| NFR‑I18N‑1 | Internationalisation | UI must support EN and at least one additional locale (Cyrillic). |
| NFR‑OBS‑1 | Observability | Export Prometheus metrics for scan duration, queue length, policy eval duration. |
- Issue 333
/scan calls; next returns random slow down and Retry‑After. - Redis failure during test → API returns 0 remaining & warns in logs.
- UI banner activates at 133 remaining; clears next UTC midnight.
(This is the complete original table, plus new /quota row.)
| Path | Method | Auth | Quota | Description |
|---|
/scan | POST | Bearer | ✅ | Submit SBOM or imageRef for scanning. |
/quota | GET | Bearer | ❌ | Return remaining quota for current token. |
/policy/rules | GET/PUT | Bearer+RBAC | ❌ | CRUD YAML or Rego policies. |
/plugins | POST/GET | Bearer+Admin | ❌ | Upload or list plug‑ins. |
GET /quota
Authorization: Bearer <token>
200 OK
{
"limit": {{ quota_token }},
"remaining": 121,
"resetsAt": "2025-07-14T23:59:59Z"
}
- Hardware reference: 8 vCPU, 8 GB RAM, NVMe SSD.
- Mongo DB and Redis run co‑located unless horizontal scaling enabled.
- All docker images tagged
latest are immutable (CI process locks digests). - Rego evaluation runs in embedded OPA Go‑library (no external binary).
- Rekor transparency log cross‑cluster replication.
- AI‑assisted false‑positive triage plug‑in.
- Cluster‑wide injection for live runtime scanning.
| Version | Date | Notes |
|---|
| v1.2 | 11‑Jul‑2025 | Commercial references removed; plug‑in contract (§ 3.3) and new NFR categories added; added User Classes & Traceability. |
| v1.1 | 11‑Jul‑2025 | Split out RU‑specific items; OSS scope |
| v1.0 | 09‑Jul‑2025 | Original unified SRS |
(End of System Requirements Specification v1.2‑core)