release-train: staging -> main #162
+90
−7
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,9 +1,9 @@ | ||
| --- | ||
| title: "Security & data handling" | ||
| description: "What stays on your infrastructure, what leaves, and how tracebloc enforces it — the page to share with your security team." | ||
| --- | ||
|
|
||
| tracebloc is built so your data never has to leave your network. This page is the summary to hand to your security or compliance team. | ||
|
|
||
| ## What's shared, what isn't | ||
|
|
||
|
|
@@ -17,9 +17,10 @@ | |
| ## How it's enforced | ||
|
|
||
| - **Data locality.** Training runs against your data on your hardware. Raw data never crosses the boundary. | ||
| - **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 @@ | |
|
|
||
| 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-<task>-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. | ||
|
Check warning on line 42 in environment-setup/security.mdx
|
||
|
|
||
| <Steps> | ||
| <Step title="Install cosign"> | ||
| Follow the [cosign installation guide](https://docs.sigstore.dev/cosign/system_config/installation/). Any current release works — check with `cosign version`. | ||
| </Step> | ||
|
|
||
| <Step title="Pull the image and note its digest"> | ||
| 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 | ||
| ``` | ||
|
|
||
| <Warning> | ||
| **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. | ||
| </Warning> | ||
| </Step> | ||
|
|
||
| <Step title="Verify the signature"> | ||
| ```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/.+$' \ | ||
|
There was a problem hiding this comment. Cosign identity omits pre-rename repoHigh Severity The Additional Locations (2)  Triggered by learned rule: cosign verify identity regexp must cover pre-rename repo Reviewed by Cursor Bugbot for commit 2cfe42f. Configure here. |
||
| tracebloc/<image>@sha256:<digest> | ||
| ``` | ||
|
|
||
| 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. | ||
| </Step> | ||
|
|
||
| <Step title="Read the result"> | ||
| 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). | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| ### 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/<image>@sha256:<digest> --format '{{ json .SBOM }}' > sbom.json | ||
| docker buildx imagetools inspect tracebloc/<image>@sha256:<digest> --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. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.