diff --git a/TERMINOLOGY.md b/TERMINOLOGY.md index 12ab61a..3f477e2 100644 --- a/TERMINOLOGY.md +++ b/TERMINOLOGY.md @@ -37,10 +37,10 @@ | Concept | Preferred | Don't use | Status | Definition | |---|---|---|---|---| -| The software you run on your infra (+ what it gives you) | **secure environment** | workspace, edge device, agent, box, node, cluster, instance, deployment, site | ✅ | **DECIDED 2026-07-12 (Lukas):** the on-prem environment is a **secure environment** everywhere user-facing (matches the marketing hero "Your own secure environment" + the installer/home-screen work). Supersedes the 2026-06-05 "workspace" pick and lifts the old "environment" soft-ban. **`client`** survives as the deep-tech / federated-learning synonym collaborators know (and in **Client ID**), but the default word is *secure environment*. The load-bearing rename. | +| The software you run on your infra (+ what it gives you) | **secure environment** | workspace, edge device, agent, box, node, cluster, instance, deployment, site | ✅ | **DECIDED 2026-07-12 (Lukas):** the on-prem environment is a **secure environment** everywhere user-facing (matches the marketing hero "Your own secure environment" + the installer/home-screen work). Supersedes the 2026-06-05 "workspace" pick and lifts the old "environment" soft-ban. **`client`** survives as the deep-tech / federated-learning synonym peers know (and in **Client ID**), but the default word is *secure environment*. The load-bearing rename. | | The command-line tool | **the tracebloc CLI** (the `tracebloc` / `tb` command) | the client, the binary, the agent | ✅ | What you run to manage your secure environment — ingest data, check status, diagnose. `tb` is the short alias. | | The credential connecting it to the platform | **Client ID** | client key, token, API key | ✅ | Created on the clients page; identifies your secure environment. "client" as a bare noun survives **only** here. | -| The hosted tracebloc service | **the platform** | the cloud, the server, the backend, SaaS | ✅ | The hosted side (ai.tracebloc.io) collaborators connect through. | +| The hosted tracebloc service | **the platform** | the cloud, the server, the backend, SaaS | ✅ | The hosted side (ai.tracebloc.io) peers connect through. | | The web app you log into | **the dashboard** (at ai.tracebloc.io) | portal, console, "the platform" (for the UI), **Hub** | 🔵 **OPEN** | The browser UI. Brand called this the **Hub** — keep "dashboard" or adopt "Hub"? Pair once: dashboard = ai.tracebloc.io, docs = docs.tracebloc.io. | | The user's own servers / laptop | **your infrastructure** (the specific host: **this machine**) | your box, on-prem (as a noun) | ✅ | The **hardware** the secure environment runs on. Distinct from the **secure environment** above (the tracebloc software/runtime it gives you) — don't conflate the two. In CLI/installer copy the specific host is "this machine". | | The user's data | **dataset** | data source, "data set" (two words), "client dataset" | ✅ | Training & test data ingested and staged locally. (It's "your dataset" — never "client data set".) | @@ -53,7 +53,7 @@ | Concept | Preferred | Don't use | Status | Definition | |---|---|---|---|---| -| The people who build & train models on your data | **collaborators** | vendor, contributor, participant, expert, "the user" | ✅ | Invited, whitelisted data scientists who train models and never see the raw data. **(Decided 2026-07-11 — supersedes the seed's "contributor".)** | +| The people who build & train models on your data | **peers** | collaborator, vendor, contributor, participant, expert, "the user" | ✅ | Invited, whitelisted data scientists who train models and never see the raw data. **DECIDED 2026-09-08 (Lukas): peers** — supersedes the 2026-07-11 *collaborators* pick; recorded in RFC-0081 (tracebloc/rfcs#81) and design brief 04 (*Inside a Use Case*): the two researchers on a use case are equals working on one object, and *collaborator* read as a role the owner grants rather than a standing. Code identifiers and existing API field names are not renamed by this row. | | The person who deploys & owns the secure environment | **owner** *(label TBD)* | admin, host, customer, "the user" | 🔵 **OPEN** | Deploys the secure environment, ingests data, creates use cases, controls sharing. Was "workspace owner" — needs a new label now that *workspace* is retired (data owner / admin panel — decide). | ## 3. The ML problem type: **task** @@ -116,7 +116,7 @@ How the user lays out each task's data, and what the label/target column is actu | Concept | Preferred | Don't use | Status | Definition | |---|---|---|---|---| -| A collaborator's attempt within a use case | **experiment** | training run, training job, training plan | ✅ | The unit a collaborator runs against a use case. | +| A peer's attempt within a use case | **experiment** | training run, training job, training plan | ✅ | The unit a peer runs against a use case. | | The act of training a model | **training** (run a training) | — | ✅ | A training happens *inside* an experiment. | | The Kubernetes/infra work object | **job** | — | ✅ | **Infra-internal only — never user-facing.** "job" = the K8s Job; don't use it in product/docs/CLI copy. | @@ -124,9 +124,9 @@ How the user lays out each task's data, and what the label/target column is actu | Concept | Preferred | Don't use | Status | Definition | |---|---|---|---|---| -| The ML model a collaborator trains | **model** | architecture | ✅ | — | +| The ML model a peer trains | **model** | architecture | ✅ | — | | A ready-made starter model/project | **template** | sample, demo | ✅ | model-zoo starters only. | -| The act of a collaborator adding their model | **submit a model** *or* **upload a model** | — | 🔵 **OPEN** | SDK method is `upload_model`. Is the verb "upload", "submit", or "contribute" a model? (Data is never "uploaded" — but a *model* legitimately goes to the platform.) | +| The act of a peer adding their model | **submit a model** *or* **upload a model** | — | 🔵 **OPEN** | SDK method is `upload_model`. Is the verb "upload", "submit", or "contribute" a model? (Data is never "uploaded" — but a *model* legitimately goes to the platform.) | ## 6. Federated learning @@ -183,7 +183,7 @@ Command group is `data` (alias `dataset` one cycle). Keep cluster/namespace/PVC/ - **competition / PrivateCompetition** → **use case** *(frontend ×782, backend `Competition` model + route)* - **workspace** → **secure environment** *(docs, website hero, decks, and the `communication` skill's Terminology Bible)* - **edge / edge device / EdgeDevice** → **secure environment** — *client* only in FL-technical contexts, never in UI copy *(frontend "edge" ×449, backend `EdgeDevice`)* -- **vendor** → **collaborators** *(client README, SDK README, frontend "Vendor Testing Platform" ×54, several docs pages)* +- **vendor** → **peers** *(client README, SDK README, frontend "Vendor Testing Platform" ×54, several docs pages)* - **push / `dataset push`** → **ingest / `data ingest`** *(client README quick-install, docs cli.mdx)* - **`dataset rm`** → **`data delete`** *(cli README)* - **ingester** → **data ingestor** *(exactly one instance org-wide: the `Data ingester` channel row in `cli/docs/rfcs/0003-storage-and-offboard-hygiene.md` §1 — the RFC the definition above restates. Left in place: that RFC is Accepted with a dated decision log, so it is a review target here, not a silent edit there.)* diff --git a/environment-setup/security.mdx b/environment-setup/security.mdx index ba537d4..aa6a44c 100644 --- a/environment-setup/security.mdx +++ b/environment-setup/security.mdx @@ -20,6 +20,7 @@ tracebloc is built so your data never has to leave your network. This page is th - **Isolation.** Each training job runs in its own container with restricted system access; Kubernetes namespaces separate workloads. - **Network policy.** The chart applies a Kubernetes `NetworkPolicy` that denies all inbound to training pods and restricts their outbound traffic — arbitrary pod-to-pod connections and the Kubernetes API are blocked, while the in-cluster MySQL that serves the training data and the in-cluster proxy that reports results and FLOPs stay reachable. Direct outbound HTTPS is still allowed by default today; a stricter lockdown that instead routes it through an in-cluster egress gateway ships with the chart and can be enabled per cluster, and enforcement requires a [CNI that honors NetworkPolicy](/environment-setup/eks-client-deployment-guide). - **Model scanning.** Submitted models are scanned for vulnerabilities (Bandit) before anything executes. +- **Signed images.** Every training image is signed at build time with Sigstore cosign and ships with an SBOM and build provenance, so you can check what you run before you run it — see [Verify a training image](#verify-a-training-image). - **Encryption in transit.** All workspace ↔ platform traffic is TLS, on an **outbound-only** connection. - **Access control.** Only contributors you whitelist by email can join a use case. - **Minimal footprint.** The installer touches only Docker and `~/.tracebloc` — no system-wide changes. @@ -36,3 +37,85 @@ If support asks for diagnostics, `--diagnose` produces a bundle with **credentia Your workspace needs outbound HTTPS to: `*.docker.io`, `ghcr.io`, `raw.githubusercontent.com`, `*.github.io`, `*.tracebloc.io`, and `pypi.org`. Nothing needs to reach *in*. +## Verify a training image + +Every training image tracebloc publishes under `tracebloc/*` on Docker Hub is signed with [Sigstore](https://www.sigstore.dev/) cosign — keyless, with GitHub Actions as the identity provider. There is no private key to leak or rotate: each signature is bound to the GitHub Actions workflow that built the image and recorded in Sigstore's public transparency log. Task images (`tracebloc/client--cpu` and `-gpu`) also carry a software bill of materials (SBOM) and build provenance as attestations; the base images they build on (`tracebloc/base`, `tracebloc/nlp`, `tracebloc/cv`) are signed the same way. You can check all of this yourself, on any machine, without asking us. + + + + Follow the [cosign installation guide](https://docs.sigstore.dev/cosign/system_config/installation/). Any current release works — check with `cosign version`. + + + + Pull the tag you are about to run, then copy the `Digest:` line that `docker pull` prints: + + ```bash + docker pull tracebloc/client-image_classification-cpu:prod + ``` + + ```text + prod: Pulling from tracebloc/client-image_classification-cpu + ... + Digest: sha256:ca315bfac44e627069adbc977151178c57187eae3834e993b32150de61d0b938 + Status: Downloaded newer image for tracebloc/client-image_classification-cpu:prod + ``` + + + **Verify the digest that `docker pull` printed — not one copied from elsewhere.** A `tag@digest` reference resolves by the digest alone and never checks the tag, so verifying a digest you got from somewhere else tells you nothing about the image behind the tag you are running — and `docker image inspect`'s `RepoDigests` can be empty (for example under the containerd image store). The `Digest:` line from your own pull is the only trustworthy source. + + + + + ```bash + cosign verify \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com \ + --certificate-identity-regexp '^https://github\.com/tracebloc/tracebloc-engine/\.github/workflows/docker-build(-base)?\.yml@refs/heads/.+$' \ + tracebloc/@sha256: + ``` + + With the example above filled in: + + ```bash + cosign verify \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com \ + --certificate-identity-regexp '^https://github\.com/tracebloc/tracebloc-engine/\.github/workflows/docker-build(-base)?\.yml@refs/heads/.+$' \ + tracebloc/client-image_classification-cpu@sha256:ca315bfac44e627069adbc977151178c57187eae3834e993b32150de61d0b938 + ``` + + The two flags pin *who* may have signed: the OIDC issuer must be GitHub Actions, and the signing identity must be one of tracebloc's two image-build workflows in the `tracebloc/tracebloc-engine` repository — `docker-build.yml` for task images, `docker-build-base.yml` for base images — on any branch. A signature from anyone else is rejected, however valid it is on its own. + + + + On success cosign exits 0, lists the checks it performed, and prints a JSON array with the signing certificate's `Issuer` and `Subject`: + + ```text + The following checks were performed on each of these signatures: + - The cosign claims were validated + - Existence of the claims in the transparency log was verified offline + - The code-signing certificate was verified using trusted certificate authority certificates + ``` + + ```json + [{"critical": {"image": {"docker-manifest-digest": "sha256:ca315bfac44e627069adbc977151178c57187eae3834e993b32150de61d0b938"}, ...}, + "optional": {"Issuer": "https://token.actions.githubusercontent.com", + "Subject": "https://github.com/tracebloc/tracebloc-engine/.github/workflows/docker-build.yml@refs/heads/master", ...}}] + ``` + + A tampered, unsigned, or differently signed image fails: cosign exits with a non-zero code and an error such as `no matching signatures`. You never need to know how the signature is stored — cosign finds it whichever way it was attached to the registry (the tag-based layout or OCI referrers). + + + +### View the SBOM and provenance + +The SBOM and build provenance live *inside* the image index as BuildKit attestations, so you read them with Docker's own tooling rather than cosign. Use the digest you just verified: + +```bash +docker buildx imagetools inspect tracebloc/@sha256: --format '{{ json .SBOM }}' > sbom.json +docker buildx imagetools inspect tracebloc/@sha256: --format '{{ json .Provenance }}' > provenance.json +``` + +The SBOM is an SPDX 2.3 document per platform (`linux/amd64`, `linux/arm64`) listing every package in the image — tens of megabytes, hence the redirect to a file — and can be fed to whatever SBOM or vulnerability tooling you already use. The provenance is SLSA and records how, and from what, the image was built. + +### Signatures follow the digest, not the tag + +Signatures are attached per digest, so re-tagging an image never breaks verification — the same verified digest stays verified under any tag.