9e5e958d42
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Added detailed task completion records for KMS interface implementation and CLI support for file-based keys. - Documented security enhancements including Argon2id password hashing, audit event contracts, and rate limiting configurations. - Included scoped service support and integration updates for the Plugin platform, ensuring proper DI handling and testing coverage.
205 lines
10 KiB
Markdown
Executable File
205 lines
10 KiB
Markdown
Executable File
# 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.1.0‑alpha** release of _Stella Ops_ must do, **including the Free‑tier daily quota of {{ quota_token }} 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.
|
||
|
||
---
|
||
|
||
## 2 · References
|
||
|
||
* [overview.md](overview.md) – market gap & problem statement
|
||
* [03_VISION.md](03_VISION.md) – north‑star, KPIs, quarterly themes
|
||
* [07_HIGH_LEVEL_ARCHITECTURE.md](07_HIGH_LEVEL_ARCHITECTURE.md) – context & data flow diagrams
|
||
* [modules/platform/architecture-overview.md](modules/platform/architecture-overview.md) – component APIs & plug‑in contracts
|
||
* [09_API_CLI_REFERENCE.md](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.
|
||
* **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.
|
||
|
||
---
|
||
|
||
## 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 {{ quota_token }} 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 …)* |
|
||
|
||
|
||
### 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:<br>• `stella/sbom‑builder`<br>• `stella/cli`<br>• `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** | 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). |
|
||
|
||
#### 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 EN and at least one additional locale (Cyrillic). |
|
||
| **NFR‑OBS‑1** | Observability | Export Prometheus metrics for scan duration, queue length, policy eval duration. |
|
||
|
||
---
|
||
|
||
## 7 Acceptance Criteria <a id="7-acceptance-criteria"></a>
|
||
|
||
1. Issue {{ quota_token }} `/scan` calls; next returns random slow down and `Retry‑After`.
|
||
2. Redis failure during test → API returns **0 remaining** & warns in logs.
|
||
3. 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. |
|
||
|
||
```bash
|
||
GET /quota
|
||
Authorization: Bearer <token>
|
||
|
||
200 OK
|
||
{
|
||
"limit": {{ quota_token }},
|
||
"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 `latest` are 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)*
|