# 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)*