Skip to content

Commit 3b2526a

Browse files
committed
docs(security): clarify self-assessment per TAG-Security review
Address review feedback on the incubation self-assessment: explain the security/usability impact of the tenant Application write surface, state that the CNI/PKI/RBAC/OIDC controls are platform-managed and where tenant responsibility ends, reword the T1-control-plane non-goal as not defending a compromised control plane, and name build-provenance/in-toto attestations as the near-term first step ahead of full reproducible builds. Assisted-by: LLM Signed-off-by: tym83 <[email protected]>
1 parent 8799a4e commit 3b2526a

1 file changed

Lines changed: 4 additions & 4 deletions

File tree

‎docs/security/self-assessment.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,9 @@ Cozystack is an open-source Kubernetes-based platform for building cloud infrast
3232

3333
### Background
3434

35-
Cozystack is delivered as a **management (root) Kubernetes cluster** onto which tenants, managed services, virtual machines, and tenant Kubernetes clusters are layered. The centre of the security model is the aggregated API server **`cozystack-api`**. Tenants never write privileged Kubernetes objects (HelmRelease, Deployment, Secret, RBAC) directly. Instead they write thin, virtual `apps.cozystack.io/*` **Application** custom resources, and `cozystack-api` translates each one into a Flux `HelmRelease` whose chart reference is fixed server-side. The set of Application kinds is registered dynamically from `ApplicationDefinition` custom resources, so the platform's catalogue of managed services is data-driven rather than hard-coded.
35+
Cozystack is delivered as a **management (root) Kubernetes cluster** onto which tenants, managed services, virtual machines, and tenant Kubernetes clusters are layered. The centre of the security model is the aggregated API server **`cozystack-api`**. Tenants never write privileged Kubernetes objects (HelmRelease, Deployment, Secret, RBAC) directly. Instead they write thin, virtual `apps.cozystack.io/*` **Application** custom resources, and `cozystack-api` translates each one into a Flux `HelmRelease` whose chart reference is fixed server-side. The set of Application kinds is registered dynamically from `ApplicationDefinition` custom resources, so the platform's catalogue of managed services is data-driven rather than hard-coded. The security consequence is that a tenant's entire write surface to the platform is a small, server-validated set of Application fields — never a HelmRelease, Deployment, Secret or RBAC object — so a tenant cannot escalate privilege or reach another tenant by crafting a privileged manifest; the usability consequence is that provisioning a database or a cluster is one declarative resource rather than a chart the tenant must assemble and secure themselves.
3636

37-
When OIDC is enabled (opt-in; `authentication.oidc.enabled` is off by default), authentication is centralized through Keycloak/OIDC; in the default OIDC-disabled mode the dashboard is fronted by a token-proxy. Authorization uses Kubernetes RBAC (with roles aggregated per tenant) plus ValidatingAdmissionPolicy. Networking isolation is provided by Cilium. Platform PKI (including the aggregated-API serving certificate) is issued by cert-manager. Tenant Kubernetes clusters run on dedicated Kamaji-hosted control planes with Talos worker nodes running as KubeVirt virtual machines.
37+
When OIDC is enabled (opt-in; `authentication.oidc.enabled` is off by default), authentication is centralized through Keycloak/OIDC; in the default OIDC-disabled mode the dashboard is fronted by a token-proxy. Authorization uses Kubernetes RBAC (with roles aggregated per tenant) plus ValidatingAdmissionPolicy. Networking isolation is provided by Cilium. Platform PKI (including the aggregated-API serving certificate) is issued by cert-manager. Tenant Kubernetes clusters run on dedicated Kamaji-hosted control planes with Talos worker nodes running as KubeVirt virtual machines. All of these controls are configured and operated by the platform, not the tenant: the cluster administrator (T0) installs Cozystack and is trusted to wire Cilium, cert-manager, RBAC and OIDC correctly, and tenants inherit that posture without touching it. A tenant does not — and cannot — configure network isolation, PKI or admission policy; a tenant is responsible only for the values it supplies in its Application resources.
3838

3939
**Usage modes.** Cozystack is deployed in two ways. As a **managed-services backend** (roughly half of deployments), an external provisioning system authenticates with its own ServiceAccount and creates the tenant resources it needs — no OIDC involved. Used **directly**, a human is granted OIDC access to the dashboard and the Cozystack API and operates it, constrained by RBAC to the `apps.cozystack.io` group within their tenant.
4040

@@ -89,7 +89,7 @@ Actors are decomposed by **trust boundary**: two components are distinct actors
8989
### Non-goals
9090

9191
- Defending against a compromised **cluster administrator, node root, or infrastructure administrator** — trusted by design and out of scope (`SECURITY.md`).
92-
- Treating the **T1 platform control plane** (`cozystack-api` ServiceAccount, Flux, system operators) as a sandbox; these hold cluster-admin-equivalent power.
92+
- Isolating the management cluster from a **compromised T1 platform control plane** (`cozystack-api` ServiceAccount, Flux, system operators): these components hold cluster-admin-equivalent power by design and are trusted, so Cozystack does not attempt to sandbox them or defend against one that has been subverted.
9393
- **Upstream-only vulnerabilities** not introduced or worsened by Cozystack packaging or defaults.
9494
- **Ingress-side isolation of tenant pods.** Tenant-pod ingress is open to `world` and `cluster`, so a tenant pod is reachable by any in-cluster peer whose own egress permits it (platform components) or by a workload not governed by Cozystack's tenant egress policies. Cross-tenant isolation is enforced on the *egress* side, not tenant-pod ingress.
9595
- **Blocking cross-tenant reachability through externally-exposed services.** If a tenant publishes a LoadBalancer external IP, another tenant can reach it via `world` egress.
@@ -146,7 +146,7 @@ Cozystack does not currently claim compliance with, or certification against, an
146146
- **Dependency and image CVE scanning (SCA).** An organization-wide pipeline built on Trivy scans every non-fork, non-archived repository in the `cozystack` organization — Go modules, Dockerfile base images, and container images referenced by the packaged charts — against NVD, vendor advisories and the GitHub Advisory Database. CRITICAL findings are scanned every 6 hours, the remaining severities weekly; findings are noise-filtered and tracked as issues under a triage matrix with per-severity targets (CRITICAL 1 business day to triage, 7-day fix target). Two limitations are worth stating: image references assembled at render time by the `cozy-lib.image` helper are invisible to values-file discovery, and per-CVE findings and triage state are currently held in a private repository, so the control is not yet externally verifiable. Aggregate reporting is now published at [`docs/security/reports/`](reports/): monthly reports reduced to counts by severity, plus a backlog reconciliation auditing every tracked finding against what shipped. Publishing the pipeline policy, the triage matrix, the finding status model and the scanning scripts, while keeping per-finding detail embargoed until fixed, is outstanding. The documented triage target is not being met and the role that owns it is unassigned; remediation is happening but the pipeline cannot record it, and the reconciliation sets out both.
147147
- **Dependency updates.** Renovate manages Go modules, Dockerfiles, and GitHub Actions, plus a small set of regex-pinned references, with OpenSSF OSV vulnerability alerts enabled and automerge disabled. The `helm-values` manager is disabled repo-wide, so the curated component images that make up the shipped platform are bumped by maintainers when preparing a release rather than automatically. There is no Dependabot configuration; Renovate is the dependency-update tool.
148148
- **Supply-chain posture.** OpenSSF Scorecard runs weekly with published results. Most GitHub Actions are pinned by commit SHA; a small number of recently added workflows still use floating tags and are being brought into line. Renovate is configured to pin digests; applying digest pins across container base images is in progress.
149-
- **Signed / reproducible builds.** Honestly noted as gaps: release images are **not** signed (no cosign/sigstore), build provenance is currently disabled (`--provenance=false`), SBOM generation is plumbed but off by default, and reproducible builds are not yet established. These are recognized improvement areas for the incubation timeframe.
149+
- **Signed / reproducible builds.** Honestly noted as gaps: release images are **not** signed (no cosign/sigstore), build provenance is currently disabled (`--provenance=false`), SBOM generation is plumbed but off by default, and reproducible builds are not yet established. These are recognized improvement areas for the incubation timeframe; the near-term first step is build-provenance / in-toto attestations (attainable without the full reproducibility work), followed by cosign signing of release images.
150150

151151
### Communication Channels
152152

0 commit comments

Comments
 (0)