Add initial documentation
This commit is contained in:
204
docs/05_SYSTEM_REQUIREMENTS_SPEC.md
Normal file
204
docs/05_SYSTEM_REQUIREMENTS_SPEC.md
Normal file
@ -0,0 +1,204 @@
|
||||
# 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](02_WHY.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
|
||||
* [08_MODULE_SPECIFICATIONS.md](08_MODULE_SPECIFICATIONS.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.
|
||||
* **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:<br>• `stella/sbom‑builder`<br>• `stella/santech`<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** | 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. |
|
||||
|
||||
---
|
||||
|
||||
## 7 Acceptance Criteria <a id="7-acceptance-criteria"></a>
|
||||
|
||||
1. Issue 333 `/scan` calls; 334th returns **HTTP 429** 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": 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 `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)*
|
||||
Reference in New Issue
Block a user