Sandbox workload identity

Sandbox workload identity lets repository processes exchange short-lived Inspect-issued OIDC tokens for access to AWS, Vault, cloud workload federation, or another service. Inspect projects tokens into session sandboxes and repository image builds without storing long-lived credentials in Inspect.

An organization administrator manages up to 16 workload identities under Organization → Security → Workload identity. The setting is disabled when no identities are configured.

Prefer the AWS MCP connectorCopy Anchor Link

Use the AWS MCP connector by default when Inspect needs to inspect or change AWS resources. The connector exchanges OIDC tokens outside the sandbox and exposes controlled AWS tools, so credentials never become available to repository code, setup scripts, dependencies, or shell commands.

Use sandbox workload identity only when a process inside the sandbox or repository image build must authenticate directly—for example, when running the AWS CLI, Terraform, an AWS SDK integration test, Vault, or a provider-specific development tool. In that model, every process that can affect the sandbox or build must be trusted with the resulting identity. If a connector can perform the task, prefer the connector.

Configure workload identitiesCopy Anchor Link

Each workload identity has:

• a name, such as aws or vault, which determines its token file path
• an audience, such as sts.amazonaws.com or https://vault.example.com, which becomes the token's exact aud claim

Names must begin with a lowercase letter or number and may contain lowercase letters, numbers, underscores, and hyphens. Names are unique and can contain up to 64 characters. Choose stable names because repository processes and provider configuration depend on the resulting file paths. Audiences can contain up to 256 non-space printable ASCII characters.

Settings apply across the organization. An empty identity list disables token issuance.

Issuer and discoveryCopy Anchor Link

The token's issuer (iss) is:

https://<your-inspect-host>/api/oidc

Inspect publishes standard OIDC discovery and signing keys at:

https://<your-inspect-host>/api/oidc/.well-known/openid-configuration
https://<your-inspect-host>/api/oidc/jwks

Subject and claimsCopy Anchor Link

The latest subject (sub) format identifies the Inspect organization, canonical source-control repository, and lifecycle:

cell:<organization>:repository:<source-control-host-key>:<repository-owner>/<repository-name>:lifecycle:<runtime|build>

For GitHub.com repositories, the source-control host key is github. For example, github.com/acme/payments in the example Inspect organization has these subjects:

Runtime: cell:example:repository:github:acme/payments:lifecycle:runtime
Build:   cell:example:repository:github:acme/payments:lifecycle:build

The cell: prefix is a fixed part of the token format; keep it unchanged in trust policies. Inspect percent-encodes organization and repository values when necessary. Workspace aliases resolve to the canonical source-control repository before Inspect builds the subject. Repository renames and transfers change the subject.

Tokens contain the standard iss, sub, aud, iat, exp, and jti claims plus a numeric ver claim. Repository and lifecycle scope live in sub; relying parties can inspect ver before interpreting versioned claims.

Claims formatsCopy Anchor Link

• Version 1: ver=1; repository-scoped subject without a lifecycle segment.
• Version 2: ver=2; adds lifecycle:runtime or lifecycle:build to the subject.

New organizations use the latest claims format. An organization on an older format can upgrade under Organization → Security → Workload identity after its relying-party trust policies accept the new subjects. Upgrades are permanent.

Projected token filesCopy Anchor Link

Inspect installs a token refresher before repository setup and writes files with mode 0600 under:

/run/inspect/oidc-tokens/<name>

For example, a workload identity named aws is available at /run/inspect/oidc-tokens/aws. Repository processes should read that file directly. The configured token paths are the only supported customer interface; other files under /run/inspect are implementation details.

Tokens live for one hour and are atomically replaced after roughly 40–50 minutes, leaving at least ten minutes for retries. The refresher polls the current administrator configuration every five minutes, so it adds newly configured identities and removes renamed or deleted identity files without replacing the sandbox. Inspect reinstalls the refresher after a sandbox is restored or replaced.

Repository image builds install the same projection before pre-clone and repository setup scripts. Inspect stops the refresher and removes projected tokens and AWS CLI credential caches before persisting any build snapshot. Build scripts must also remove downstream credentials, such as CodeArtifact tokens in package-manager configuration, before the snapshot is created.

Inspect authenticates each token request and binds it to the active repository sandbox or image build. Repository processes can request only configured identity names, and each identity's audience comes from organization settings. Failed refreshes preserve an existing token file and retry; an unavailable identity removes its file.

Any process in the sandbox or image build can read its projected tokens: that environment is the workload principal.

Connect a sandbox or image build to AWSCopy Anchor Link

AWS is one example of a service that can trust Inspect workload identity. The same feature also works with Vault, other cloud providers, and internal services that accept OIDC tokens; use the audience and setup instructions from that service instead.

Ask an Inspect organization administrator to add a workload identity named aws with the audience sts.amazonaws.com.

1. Add Inspect as an AWS identity providerCopy Anchor Link

Follow AWS's IAM OIDC provider setup guide. In the AWS console, go to IAM → Identity providers → Add provider and select OpenID Connect.

• For Provider URL, enter the issuer documented above.
• For Audience, enter sts.amazonaws.com.

If this AWS account already uses the Inspect AWS MCP connector, the provider already exists. You can use the existing provider instead of creating another one. The same provider works for both features, but sandbox workload identity and connector tokens use different subjects and credential boundaries.

2. Create a role for the repositoryCopy Anchor Link

In IAM → Roles, create a role with Web identity as the trusted entity. Select the Inspect identity provider and the sts.amazonaws.com audience. AWS documents the underlying exchange in AssumeRoleWithWebIdentity.

Use an exact subject when runtime sandboxes and image builds should assume different roles. For example, this condition trusts only runtime sandboxes for one repository:

{
  "StringEquals": {
    "<issuer-without-https>:aud": "sts.amazonaws.com",
    "<issuer-without-https>:sub": "cell:example:repository:github:acme/payments:lifecycle:runtime"
  }
}

In condition keys, replace <issuer-without-https> with the complete issuer minus its https:// prefix, including the /api/oidc path. Replace the Inspect organization, owner, and repository with your values.

When one role intentionally serves both lifecycles, use StringLike to wildcard only the final lifecycle segment while keeping the organization and repository exact:

{
  "StringEquals": {
    "<issuer-without-https>:aud": "sts.amazonaws.com"
  },
  "StringLike": {
    "<issuer-without-https>:sub": "cell:example:repository:github:acme/payments:lifecycle:*"
  }
}

When one role intentionally serves multiple repositories, the repository segment can also use a wildcard:

{
  "StringEquals": {
    "<issuer-without-https>:aud": "sts.amazonaws.com"
  },
  "StringLike": {
    "<issuer-without-https>:sub": "cell:example:repository:github:acme/*:lifecycle:*"
  }
}

Keep the Inspect organization, source-control host key, and owner exact. Prefer the narrowest repository prefix—or an array of explicit repository subjects—that covers every repository meant to receive the role's permissions. Attach a permissions policy that grants only the AWS actions and resources those repositories need. Do not reuse the AWS MCP connector's role because connector tokens have a different subject.

3. Configure repository environment variablesCopy Anchor Link

Configure the standard AWS web-identity environment variables in the repository's Environment variables settings:

AWS_ROLE_ARN=arn:aws:iam::123456789012:role/inspect
AWS_WEB_IDENTITY_TOKEN_FILE=/run/inspect/oidc-tokens/aws
AWS_ROLE_SESSION_NAME=inspect
AWS_REGION=us-east-1

Select the Build scope for image setup, Runtime for live sandboxes, or both when they share a role. These values identify the role and token path; they are not AWS credentials. Inspect never places AWS credentials in the sandbox or image snapshot.

AWS SDKs and the AWS CLI reread the projected file when credentials need refreshing. Verify the setup from a new sandbox or build with the AWS operation your repository requires. For a sandbox with permission to call STS, you can run:

aws sts get-caller-identity

The returned ARN should contain the role you created.

Security and revocationCopy Anchor Link

Configuring an identity gives every process in an eligible repository sandbox or image build access to a bearer token for that relying party. The agent, tools, setup scripts, dependencies, and repository code can read, copy, or exchange the token. Treat the sandbox or build as the workload principal, not as a trusted credential store.

Use dedicated, least-privilege roles and policies. Trust an exact audience and the narrowest practical subject. Do not wildcard Inspect organization, repository owner, or repository identifiers unless every matching sandbox and build should receive the same access. Continue enforcing authorization at the destination service. OIDC federation removes long-lived static secrets from Inspect, but it does not make an over-permissioned role safe.

Removing an identity blocks new minting and removes its projected file on the next configuration poll. Existing JWT copies remain valid for up to one hour, and downstream credentials remain valid until their own expiration. For immediate AWS invalidation, use Revoke active sessions on the IAM role.

Public or collaborative sessions can be influenced by users other than the session owner. Configure only roles whose permissions are appropriate for every user and process that can affect the sandbox. Review untrusted prompts, repository changes, setup scripts, and dependencies before granting access to sensitive systems.