Skip to content

feat(sandboxidentity): verify the identity of Chainloop sandboxes - #3599

Draft
javirln wants to merge 11 commits into
mainfrom
pfm-7678-sandbox-commit-verification
Draft

javirln wants to merge 11 commits into
mainfrom
pfm-7678-sandbox-commit-verification

Conversation

@javirln

@javirln javirln commented Oct 13, 2026 •

Copy link
Copy Markdown
Member

Context: PFM-7678. Design: Spec PFM-7678: Verified identity for Chainloop sandboxes, merged in chainloop-dev/platform#6875. It replaces D-009 of the commit verification spec (chainloop-dev/platform#6821). The platform side is chainloop-dev/platform#6861, which waits for a release with this change.

Today any CLI run can claim to be a Chainloop sandbox. So the platform cannot give a sandbox data that the attestation can trust. With this change, the platform gives each sandbox a signed identity token, and the CLI and the control plane verify it.

  • Identity token (R-001, R-003, D-006, D-013): the new sandboxidentity package defines it. It is a JWT signed with a new key for each sandbox. The x5c header holds a short-lived certificate from the control plane CA. The token names the organization, the project, the workflow, the sandbox run and the Chainloop token of the sandbox. It holds the commit verification of the attested commit. It has no expiry of its own: the control plane accepts it only with the Chainloop token that it names, and that token expires.
  • Only the platform can issue it (R-002, D-004, D-005): it needs the new permission sandbox_identity:create. A caller with this permission gets a certificate with a mark in its subject. No role holds the permission, and only a system API token can hold it. A CA that cannot write the mark gives no certificate.
  • The CLI verifies it (R-004, R-005, D-007, D-011): the CHAINLOOP_SANDBOX runner reads the token from the CHAINLOOP_SANDBOX_IDENTITY environment value. The CLI verifies the token against the trusted root of the control plane, in the same way as the attestation verify command. Only then is the runner authenticated, and only then does git.head record the commit verification. A token that does not verify gives a runner that is not authenticated and has no platform data. The CLI logs the reason.
  • The control plane enforces it (R-006, D-010, D-012): the CLI sends the token with the attestation init request. The control plane verifies it, accepts it only from the Chainloop token that it names, and records it on the workflow run. When the control plane stores an attestation of the sandbox runner, it rejects two cases. One is an authenticated runner without a verified identity. The other is a commit verification that the identity does not hold.

The attestation format does not change, and the other runners do not change.

Notes on the implementation:

  • The CLI does not know the organization ID, so it gives no organization to the expected values. The workflow ID comes from the init response of the control plane. The organization in the leaf certificate must be the organization in the claims. The control plane compares the organization, the project and the workflow. So R-003 holds.
  • The init response gets SandboxIdentityResult, which the spec does not name. The CLI authenticates the runner only when the control plane verified the identity and the verification of the CLI also passes. So the CLI and the control plane cannot disagree about the identity.
  • When the identity holds a signature algorithm, the control plane also compares it with the signature.algorithm of git.head.
  • The EJBCA CA writes the subject from the certificate request, so D-005 does not hold for it. The control plane fails closed. With EJBCA, it gives no certificate with the mark. With any CA, it rejects an issued certificate that has a mark that nobody requested. So an EJBCA deployment issues no identity, and its sandbox runner stays not authenticated, as today. The spec records this difference when the work ships.
  • The control plane logs the arguments of each request. For attestation init, the log replaces the identity token with [REDACTED].

This replaces the unsigned CHAINLOOP_SANDBOX_COMMIT_VERIFICATION value of the first version of this PR. No released CLI reads that value. CommitVerification keeps its JSON tags and status names, because the token carries the commit verification in that format.

AI disclosure: AI assisted with this change.

Assisted-by: Claude Code

View guided diff

@javirln
javirln requested a review from a team October 13, 2026 12:33
@chainloop-platform

chainloop-platform Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

AI Session Checks — ⚠️ no AI session found

Missing AI Coding Sessions

This organization requires every PR to be backed by a Chainloop Trace AI coding session, and none was found for this one.

Please make sure the AI coding session evidence has been sent by the Chainloop CLI, or add the skip-ai-session label to this PR to bypass this check.

Learn more about Chainloop Trace.


Powered by Chainloop and Chainloop Trace

@javirln
javirln marked this pull request as ready for review October 13, 2026 12:40

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 4 files

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

@migmartri migmartri left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am confused about this PR, do you have a task for it?

@javirln

javirln commented Oct 13, 2026

Copy link
Copy Markdown
Member Author

@migmartri Yes, it is PFM-7678: https://linear.app/chainloop/issue/PFM-7678

The built-in PR attestation runs the CLI in the platform sandbox with the CHAINLOOP_SANDBOX runner. The sandbox gets no SCM token, so git.head never records the commit verification. A source-commit policy with check_author_verified fails on every built-in PR attestation.

The approved spec (chainloop-dev/platform#6821) makes the platform verify the commit with the clone credential before it starts the sandbox. Only the result goes into the sandbox, not the token.

This PR is the CLI half: the sandbox runner reads that result and records it only for the attested commit. The platform half is chainloop-dev/platform#6861, which waits for a release with this change. I added these links to the description.

@javirln
javirln marked this pull request as draft October 13, 2026 14:57
@javirln
javirln force-pushed the pfm-7678-sandbox-commit-verification branch from 2ee9aae to f907159 Compare October 16, 2026 13:55
@javirln javirln changed the title feat(runners): record a given commit verification in the sandbox runner feat(sandboxidentity): verify the identity of Chainloop sandboxes Oct 16, 2026
@javirln
javirln force-pushed the pfm-7678-sandbox-commit-verification branch from a26107c to 7257a6e Compare October 19, 2026 07:33

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 17 reviewed files. 35 files intentionally excluded from review.

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

Comment thread app/controlplane/pkg/biz/workflowrun.go Resolved
Comment thread app/controlplane/pkg/biz/apitoken.go Resolved
@javirln
javirln marked this pull request as ready for review October 19, 2026 08:10
@javirln
javirln force-pushed the pfm-7678-sandbox-commit-verification branch from dc48f8f to efb870b Compare October 21, 2026 06:19
@javirln
javirln requested a review from migmartri October 21, 2026 06:21
UseLatestVersion: opts.UseLatestVersion,
RequireExistingVersion: opts.RequireExistingVersion,
MarkAsLatest: opts.MarkAsLatest,
SandboxIdentity: sandboxIdentityToken,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understood from the spec that the sandbox identity token was going to be put into the attestation, and verified from the attestation contents. This way, we could verify past attestations completely, not only on att init.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The implementation follows the merged spec here. The spec keeps the attestation format as it is. The token goes in the attestation init request, and the control plane records the verified identity on the run (R-006, and "Other runners and the attestation format" in the Proposal). At push, the control plane compares the attestation with that record and rejects an authenticated sandbox runner without a verified identity (D-010).

The spec does not keep the raw token after init, so a later check relies on the record of the control plane. If you want to verify past attestations from their content alone, the CLI would record the token in the predicate. That changes the attestation format, so I would add it as a new decision in the spec, in this PR or as a follow-up. Which do you prefer?

@@ -0,0 +1,2 @@
-- Modify "workflow_runs" table
ALTER TABLE "workflow_runs" ADD COLUMN "sandbox_identity" jsonb NULL;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why do we need to store info?

@migmartri
migmartri marked this pull request as draft October 30, 2026 08:54
The CHAINLOOP_SANDBOX runner gets no SCM token, so it cannot ask the
provider whether the attested commit is signed. The platform can verify
the commit before it starts the sandbox. The runner now reads that result
from CHAINLOOP_SANDBOX_COMMIT_VERIFICATION and returns it only when its
commit hash is the attested commit. A malformed value records the
unavailable status.

CommitVerification gets JSON tags, and its status encodes as a name, so
the platform and the CLI share one format.

Assisted-by: Claude Code
Signed-off-by: Javier Rodriguez <javier@chainloop.dev>

Chainloop-Trace-Sessions: 0ebed99f-c817-4242-9a55-3c64202ac7f3
…tatus

A given verification with no status, or with the unspecified status,
carries no result. The runner now records the unavailable status for it,
as it does for a value without a verification. Before, the attestation
recorded the unspecified status.

Assisted-by: Claude Code
Signed-off-by: Javier Rodriguez <javier@chainloop.dev>

Chainloop-Trace-Sessions: 4503bdcc-d428-4e05-ade6-966360bf5543
The platform gives a signed identity token to each Chainloop sandbox that
it spawns. The new sandboxidentity package defines the token and how to
sign and verify it.

The token is a JWT signed with a new key for each sandbox. The key has a
short-lived certificate from the control plane CA, and the certificate
chain is in the x5c header. The CA marks the certificate only for a
caller with the dedicated permission (R-002). The token names the
organization, the project, the workflow, the sandbox run and the
Chainloop token of the sandbox, and it holds the commit verification
with the full commit hash (R-003). It has no expiry of its own (D-013).

Verify checks the chain against the trusted root of the control plane,
the mark, the organization, the project and the workflow, that the time
of signing is inside the certificate lifetime (D-007), and the signature.
The Issuer helper lets the platform issue a token in one call.

The signing request gets the sandbox_identity_issuer flag, and the
attestation init request gets the sandbox_identity token. The verifier
exports ValidateCertificate, so the identity and the attestation use the
same certificate check.

Assisted-by: Claude Code
Signed-off-by: Javier Rodriguez <javier@chainloop.dev>

Chainloop-Trace-Sessions: 4503bdcc-d428-4e05-ade6-966360bf5543
The control plane now issues the certificates that sign a sandbox
identity, and verifies and enforces the identity.

- A new policy, PolicySandboxIdentityIssue, is the dedicated permission.
  No role holds it, and only a system API token can hold it (R-002,
  D-004). The signing service marks the certificate only for a caller
  that holds it. The CA writes the mark in the organizational unit of
  the subject (D-005). A CA that does not write the subject itself gives
  no marked certificate, and a mark that was not requested gives no
  certificate.
- At attestation init, the control plane verifies the identity of a
  CHAINLOOP_SANDBOX run against its own CA, for the attested workflow,
  and only from the Chainloop token that the identity names (R-003,
  D-012). It records the identity on the workflow run, and tells the CLI
  the result. A token that does not verify is the same as no token
  (D-011).
- When it stores an attestation of the sandbox runner, the control
  plane rejects an authenticated runner without a verified identity, and
  a commit verification that the identity does not hold (R-006, D-010).
  Other runners keep their behavior.

Assisted-by: Claude Code
Signed-off-by: Javier Rodriguez <javier@chainloop.dev>

Chainloop-Trace-Sessions: 4503bdcc-d428-4e05-ade6-966360bf5543
…tity

The CHAINLOOP_SANDBOX runner reads the identity token from
CHAINLOOP_SANDBOX_IDENTITY. At attestation init, the CLI sends the token
to the control plane. When the control plane verified it, the CLI also
verifies it against the trusted root of the control plane, in the same
way as attestation verify. Only then is the runner authenticated (R-004),
and only then does it return the commit verification of the identity,
for the full hash of the attested commit (R-005).

A token that does not verify, or a control plane that does not know the
identity, gives a runner that is not authenticated and has no platform
data. The CLI logs the reason (D-011).

This replaces the unsigned hand-off in
CHAINLOOP_SANDBOX_COMMIT_VERIFICATION and its "unavailable" status for an
unreadable value. No released CLI reads that value.

Assisted-by: Claude Code
Signed-off-by: Javier Rodriguez <javier@chainloop.dev>

Chainloop-Trace-Sessions: 4503bdcc-d428-4e05-ade6-966360bf5543
Init loads the state that it wrote, and the load makes a new runner. A new
CHAINLOOP_SANDBOX runner has no verified identity, so the runner info that
init resolves next recorded authenticated=false, while git.head had the
commit verification of the identity (R-004).

Init now keeps its own runner when the runner can carry a verified
identity. The other runners do not change.

Assisted-by: Claude Code
Signed-off-by: Javier Rodriguez <javier@chainloop.dev>

Chainloop-Trace-Sessions: 4503bdcc-d428-4e05-ade6-966360bf5543
…t verification

The git.head subject also records the signature algorithm, and the
renderer takes it from the commit verification first. When the identity
holds a signature algorithm, the control plane now also requires the
attestation to record the same one (R-006). When the identity has no
algorithm, the attestation takes it from the signature of the commit, so
the control plane does not compare it.

Assisted-by: Claude Code
Signed-off-by: Javier Rodriguez <javier@chainloop.dev>

Chainloop-Trace-Sessions: 4503bdcc-d428-4e05-ade6-966360bf5543
The request log of the control plane printed the arguments of
AttestationService/Init, with the sandbox identity token. Redact
replaces the token in the logged request, and keeps the other fields.

Assisted-by: Claude Code
Signed-off-by: Javier Rodriguez <javier@chainloop.dev>

Chainloop-Trace-Sessions: 4503bdcc-d428-4e05-ade6-966360bf5543
…suance

Verify rejects a certificate for another organization than the claims.
The issuer now checks it too, so the error shows up when the platform
issues the identity, and not later in the CLI.

Refs PFM-7678

Signed-off-by: Javier Rodriguez <javier@chainloop.dev>
Assisted-by: Claude Code

Chainloop-Trace-Sessions: 4503bdcc-d428-4e05-ade6-966360bf5543
…eation

Create refuses the permission to issue a sandbox identity for a token
that is not a system token, and accepts it for a system token.

Refs PFM-7678

Signed-off-by: Javier Rodriguez <javier@chainloop.dev>
Assisted-by: Claude Code

Chainloop-Trace-Sessions: 4503bdcc-d428-4e05-ade6-966360bf5543
The loop over dependent attestations declared a new run variable that
shadowed the run of the attestation. Give it its own name, so it is
clear that the later checks use the run of the attestation.

Refs PFM-7678

Signed-off-by: Javier Rodriguez <javier@chainloop.dev>
Assisted-by: Claude Code

Chainloop-Trace-Sessions: 4503bdcc-d428-4e05-ade6-966360bf5543
@javirln
javirln force-pushed the pfm-7678-sandbox-commit-verification branch from efb870b to c8f24ff Compare November 12, 2026 06:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants