9.7 KiB
9.7 KiB
SYSTEM REQUIREMENTS SPECIFICATION
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.
1 · Purpose & Scope
This SRS defines everything the v0.8‑beta release of Stella Ops must do, including the new Free‑tier quota of 333 SBOM scans per token per UTC day.
Scope includes core platform, CLI, UI, quota layer, and plug‑in host; commercial or closed‑source extensions are explicitly out‑of‑scope.
2 · References
- 02_WHY.md – market gap & problem statement
- 03_VISION.md – north‑star, KPIs, quarterly themes
- 07_HIGH_LEVEL_ARCHITECTURE.md – context & data flow diagrams
- 08_MODULE_SPECIFICATIONS.md – component APIs & plug‑in contracts
- 09_API_CLI_REFERENCE.md – REST & CLI surface
3 · Definitions & Acronyms
| 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 |
4 · Overall System Description
The platform consists of:
- Stella Ops Backend – REST API, queue, policy engine, DB.
- StellaOps.Registry – internal container registry for agents.
- SanTech Agent – 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.
5 · Functional Requirements (FR)
5.1 Core Scanning
| 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 set to midnight UTC. |
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":333,"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 …) |
5.2 Internal Docker Repository
| 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/santech• stella/zastava. |
| FR‑REPO‑3 | Registry MAY enable optional basic‑auth without code changes. |
5.3 SBOM Generation & Handling
| 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 | SanTech Agent 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). |
5.3.1 Delta SBOM (layer reuse)
| 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). |
5.4 Policy as Code (Muting & Expiration)
| 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. |
5.5 SLSA Attestations & Rekor (TODO > 6 mo)
| 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. |
5.6 CLI & API Interface
| 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. |
6 · Non‑Functional Requirements (NFR)
| 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 RU and EN locale toggles. |
| NFR‑OBS‑1 | Observability | Export Prometheus metrics for scan duration, queue length, policy eval duration. |
- Issue 333
/scancalls; 334th returns HTTP 429 andRetry‑After. - Redis failure during test → API returns 0 remaining & warns in logs.
- UI banner activates at 133 remaining; clears next UTC midnight.
8 · System Interfaces
8.1 External APIs
(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": 333,
"remaining": 121,
"resetsAt": "2025-07-14T23:59:59Z"
}
9 · Assumptions & Constraints
- Hardware reference: 8 vCPU, 8 GB RAM, NVMe SSD.
- Mongo DB and Redis run co‑located unless horizontal scaling enabled.
- All docker images tagged
latestare immutable (CI process locks digests). - Rego evaluation runs in embedded OPA Go‑library (no external binary).
10 · Future Work (Beyond 12 Months)
- Rekor transparency log cross‑cluster replication.
- AI‑assisted false‑positive triage plug‑in.
- Cluster‑wide injection for live runtime scanning.
11 · Revision History
| 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)