Docs · reference
Sandbox configuration reference — base images, knobs, compliance mapping.
Five supported base images, six per-step resource limits the runtime enforces, five secret-mount patterns with custody story, the network-isolation toggle set, PR-test command templates per language, and the compliance-control mapping a staff-plus engineer reads end to end.
Base images
Five runtimes, all hermetic
node:22 · python:3.12 · golang:1.23 · temurin:21 · rust:1.82 — pin one, ship the lockfile, the hermetic-build hash stays stable across reruns.
Resource limits
Six knobs, with ceilings
One knob per resource the runtime enforces — CPU, memory, disk, timeout, parallel tests, cache mode. Each row carries the default value, the hard ceiling, the sandbox step it applies to, and the compliance control it maps to.
Compliance mapping
One table, every control
SOC 2 CC6.1 / CC6.6 / CC7.2, FedRAMP AC-4 / AU-2, ISO 27001 A.8.24 — each control lists the sandbox knob(s) that implement it. A staff-plus engineer reads end-to-end; the audit log does not lie.
base images · resource limits · secret mounts · network isolation · PR-test commands · compliance mapping
Base images
Five runtimes — pin one, ship the lockfile, hermetic from day one.
The platform team picks one base image per tenant. Each image runs hermetic by default — the sandbox cannot reach any host that is not on the language-registry allow-list shipped with the image. Lock the image tag, commit the lockfile, and the hermetic-build hash stays byte-stable across reruns.
Starter values.yaml a platform team copies
The block below is the canonical starter for a Driftlock sandbox deployment — every knob below is one row in the resource-limits table that follows. Copy, set your tenant + registry hosts, commit it to your chart repo, hand the diff to the compliance reviewer alongside the row the knob controls.
# Driftlock sandbox starter — values.yaml fragment a platform team copies
# into their chart. Every knob below is documented on /docs/sandbox-config;
# copy this block, set your tenant + registry hosts, commit to your chart repo,
# hand the diff to the compliance reviewer alongside the row the knob controls.
sandbox:
cpu: "2" # default 2 vCPU, max 8
memory: "4Gi" # default 4 GiB, max 32 GiB
disk: "20Gi" # default 20 GiB, max 200 GiB
timeoutSec: 1800 # default 30m, max 7200 (2h)
parallelTests: 4 # default 4, max 32
cacheMode: layered # layered | strict | off
baseImage: node:22-bookworm # pick Node/Python/Go/JVM/Rust — see /docs/sandbox-config#base-images
egress:
allowed: [] # default-deny — add registry + KMS CIDRs as you integrate
blockedCidrs: [] # layer on top of allowed for known-bad ranges
dns:
policy: cluster # cluster | strict; reject dns.policy: open in code review
resolvers: [] # only set when policy is strict
Base image
Node
- image tag
- node:22-bookworm
- system packages
- gitca-certificateslibssl-devbuild-essential
- language registries
- registry.npmjs.orgregistry.yarnpkg.com
SOC 2 CC6.1 · FedRAMP AC-4
Base image
Python
- image tag
- python:3.12-bookworm
- system packages
- gitca-certificateslibffi-devbuild-essential
- language registries
- pypi.orgfiles.pythonhosted.org
SOC 2 CC6.1 · ISO 27001 A.8.24
Base image
Go
- image tag
- golang:1.23-bookworm
- system packages
- gitca-certificatesbuild-essential
- language registries
- proxy.golang.orgsum.golang.org
SOC 2 CC6.6 · FedRAMP CM-7
Base image
JVM
- image tag
- eclipse-temurin:21-jdk-bookworm
- system packages
- gitca-certificatesunzipbuild-essential
- language registries
- repo.maven.apache.orgplugins.gradle.org
SOC 2 CC6.6 · ISO 27001 A.8.24
Base image
Rust
- image tag
- rust:1.82-bookworm
- system packages
- gitca-certificatesbuild-essentialpkg-configlibssl-dev
- language registries
- crates.iostatic.crates.io
SOC 2 CC6.6 · FedRAMP CM-7
node:22 · python:3.12 · golang:1.23 · temurin:21 · rust:1.82 · hermetic by default
Resource limits
Six knobs — every sandbox step bounded, every knob ceilinged.
The platform team owns one values.yaml. Each row below is a knob key the platform team sets, the default value the runtime applies when they omit it, the hard ceiling the runtime enforces, and the sandbox step(s) the knob applies to. The same knob name appears on the parent /docs sandbox table — vocabulary shared with the audit-trail row and the SBOM emission.
Knob · step
Default · ceiling · compliance / control
sandbox.cpu
applies to · run · replay · scan
CPU budget the runtime pins per concurrent sandbox step. Set above the default only when a per-PR test profile averages more than 90% CPU time over a 24-hour window.
- default
- 2 vCPU
- ceiling
- 8 vCPU
- compliance / control
- SOC 2 CC6.1 · ISO 27001 A.8.24
sandbox.memory
applies to · run · replay
Working-set ceiling the runtime enforces per sandbox. Above the ceiling the OOMKilled exit code feeds the same retry budget as a failing test — not a sandbox budget overspend.
- default
- 4 GiB
- ceiling
- 32 GiB
- compliance / control
- SOC 2 CC6.1 · ISO 27001 A.8.24
sandbox.disk
applies to · run · replay · scan
Ephemeral disk the runtime hands the sandbox. Larger values extend the cache lifetime but do not extend the per-step timeout — keep the two knobs distinct.
- default
- 20 GiB
- ceiling
- 200 GiB
- compliance / control
- SOC 2 CC7.2 · FedRAMP AU-2
sandbox.timeoutSec
applies to · run · replay
Hard ceiling the runtime enforces on a single sandbox step. Steps that exceed this are surfaced as `data.failure.kind: timeout` on the webhook — never as a silent truncation.
- default
- 1800s (30m)
- ceiling
- 7200s (2h)
- compliance / control
- SOC 2 CC7.2 · ISO 27001 A.8.24
sandbox.parallelTests
applies to · run
Number of sandbox steps the runner fans out concurrently. Above the ceiling the runner queues — it does not silently drop tests.
- default
- 4
- ceiling
- 32
- compliance / control
- SOC 2 CC6.1 · ISO 27001 A.8.24
sandbox.cacheMode
applies to · run · replay
Cache strategy for the hermetic-build hash input. `strict` re-builds from a deterministic tarball; `layered` reuses cached layers keyed by locking-file hash; `off` forces a fresh build every run.
- default
- layered
- ceiling
- layered | strict | off
- compliance / control
- SOC 2 CC7.2 · FedRAMP AU-2
sandbox.cpu · sandbox.memory · sandbox.disk · sandbox.timeoutSec · sandbox.parallelTests · sandbox.cacheMode
Secret mounting
Five mount patterns — every credential a sandbox reads, with a custody story.
Each pattern below is a different way the runtime injects a secret into the sandbox step. The platform team picks one (or stacks several); what changes between them is the custody story — who holds the secret, who rotates it, and what audit-trail row the read leaves behind.
Secret-mount pattern
envFile
The default mount for non-cloud secrets a sandbox reads once at start — GitHub App private keys, cosign signing keys, verifier KMS credentials.
- mount path
- /etc/driftlock/secrets.env
- env shape
- KEY=VALUE
- custody
- Mounted at sandbox start; never persisted past sandbox exit; sourced from a per-tenant sealed-secret CRD the platform team owns.
- allowed values
- Var name `^[A-Z][A-Z0-9_]{1,63}$`, value `<4096 bytes`, opaque-string (no special parsing).
SOC 2 CC6.1 · FedRAMP AC-4
Secret-mount pattern
fileMount
Use for binary credentials a runtime cannot read via env — PKCS#11 blobs for HSM-backed verifier keys, cosign.key.pem for KMS-resident signers.
- mount path
- /run/secrets/<name>
- env shape
- binary
- custody
- Tmpfs volume the runtime hands the sandbox with `noexec,nosuid,nodev` set; wiped on sandbox exit; sourced from the same sealed-secret CRD.
- allowed values
- Single file, `<= 1 MiB`, user `driftlock` (uid 10001), `0640` perms, read-only after mount.
SOC 2 CC6.1 · FedRAMP AC-4 · ISO 27001 A.8.24
Secret-mount pattern
oidcToken
The default mount for cross-cluster authentication — Rekor transparency-log inclusion, cosign OIDC flow, dependency-feed registry pulls.
- mount path
- /var/run/driftlock/oidc/token
- env shape
- jwt
- custody
- Mint-on-start OIDC token issued by the in-cluster issuer; rotated at sandbox-step boundary; subject claim pinned to the sandbox run id.
- allowed values
- JWT, RS256 signed, 15-minute TTL, audience `driftlock-sandbox`, subject `run-<id>`-pinned.
SOC 2 CC6.6 · FedRAMP IA-2
Secret-mount pattern
k8sSecret
Use only when the platform team delegates custody to the cluster operator — same wire shape as `fileMount`, different custody story.
- mount path
- /run/secrets/k8s/<secret-ref>
- env shape
- object<string, base64>
- custody
- Native Kubernetes Secret injected as a tmpfs volume; backed by etcd encryption at rest (`encryption-at-rest: aescbc`); platform team owns the RBAC.
- allowed values
- Object key `^[a-z][a-z0-9-]{0,62}$`, value `<= 1 MiB` per key, `<= 32 keys` per Secret.
SOC 2 CC6.1 · FedRAMP AC-4
Secret-mount pattern
hsmToken
The Enterprise tier mount — for sandboxes that sign commits or read signer keys the platform team holds in an HSM partition.
- mount path
- /var/run/driftlock/hsm/handle
- env shape
- pkcs11-handle
- custody
- PKCS#11 handle the HSM client opens at sandbox start; key never leaves the hardware; rotation driven by the HSM-resident policy.
- allowed values
- Single handle per sandbox step; `--login-flags=protected-authentication-path` required; CKA_EXTRACTABLE never set.
SOC 2 CC6.1 · FedRAMP SC-12 · ISO 27001 A.8.24
envFile · fileMount · oidcToken · k8sSecret · hsmToken
Network isolation
Five toggles — default-deny egress, observable, TLS-pinned.
The runtime applies each toggle to every sandbox step. The platform team picks one of two states per knob; the compliance reviewer reads the diff and either confirms the default (safe) posture or records an exception the runbook cites by control row.
Network-isolation toggle
egress.allowed
The single most important toggle — `[]` is the safe default; the platform team adds ranges as the integration needs them.
- on
- Allow-list of CIDR ranges the sandbox can reach — registry hosts, KMS endpoints, sigstore services, Rekor inclusion servers.
- off
- Default-deny — every outbound packet is dropped at the network policy layer; the sandbox can still reach the in-cluster services the runner phone-homes through.
SOC 2 CC6.6 · FedRAMP AC-4
Network-isolation toggle
egress.blockedCidrs
Layered control — keep it short, as a standing block-list, and prefer proactive allow-listing via `egress.allowed`.
- on
- Block-list of CIDR ranges the sandbox cannot reach even when they fall under `egress.allowed` — last-mile guard for known-bad registries.
- off
- No block filter; the platform team relies on `egress.allowed` alone for egress control.
SOC 2 CC6.6 · FedRAMP AC-4
Network-isolation toggle
dns.policy
The DNS posture the runtime enforces on every step — pick `cluster` or `strict`; reject `open` requests in code review.
- on
- `cluster` — DNS lookups flow through the cluster CoreDNS; `strict` — lookups resolve only against the explicit resolver set under `dns.resolvers`.
- off
- `open` — the sandbox reaches the upstream resolvers with no policy layer in the middle. EXPOSED — a tightening reviewer should mark this as a finding.
SOC 2 CC6.6 · ISO 27001 A.8.24
Network-isolation toggle
network.observability
The audit-trail depth the platform team opts into — `metadata-only` is the floor; `payload-sampled` is the option a compliance reviewer asks for.
- on
- `metadata-only` — the runtime records `<src, dst, port, proto, decision>` per packet; `payload-sampled` — additionally samples 1-in-1024 payload bytes for the audit log.
- off
- `off` — no network observability; the audit trail records only egress-block decisions, not allowed traffic.
SOC 2 CC7.2 · FedRAMP AU-2 · ISO 27001 A.8.15
Network-isolation toggle
tls.pinningRequired
The TLS posture the runtime enforces on every outbound connection — keep `true`; treat `false` as a deliberate exception the runbook records.
- on
- Runtime validates the SPKI pin against the static pin-set the platform team commits; a mismatch aborts the connection and surfaces as a `deny-policy` failure.
- off
- Runtime falls back to the system trust store — vulnerable to mitm with a compromised CA; the compliance reviewer will flag this as a finding.
SOC 2 CC6.7 · FedRAMP SC-8 · ISO 27001 A.8.20
egress.allowed · egress.blockedCidrs · dns.policy · network.observability · tls.pinningRequired
PR-test command templates
Five runners — one per language, all under the hermetic-build hash.
The platform team picks one template per language in the base-images matrix above. Each template writes its result report to a stable path under /tmp/driftlock/ that the runner reads back into the audit-trail row. The DRIFTLOCK_HERMETIC=1 prefix forces the runner to operate under the hermetic build, bypassing any local cache that would break byte-stable replay.
PR-test command · Node
Node
Runs the project test suite under the hermetic build hash; writes a JSON report the runner reads back into the audit-trail row.
DRIFTLOCK_HERMETIC=1 npm test -- --runInBand --reporter=json --outputFile=/tmp/driftlock/test-results.json- expected exit codes
- 0
- compliance / control
- SOC 2 CC7.2 · FedRAMP AU-2
PR-test command · Python
Python
Runs the project pytest collection, writes a JUnit XML the runner normalizes into the test-results column. Exit 5 is `no tests collected` — a valid skip.
DRIFTLOCK_HERMETIC=1 python -m pytest -p no:cacheprovider --junitxml=/tmp/driftlock/junit.xml -ra- expected exit codes
- 05
- compliance / control
- SOC 2 CC7.2 · FedRAMP AU-2
PR-test command · Go
Go
Runs the project test suite with `-count=1` to bypass the test cache the hermetic build does not write; emits JSON output the runner reads.
DRIFTLOCK_HERMETIC=1 go test -count=1 -json ./... | tee /tmp/driftlock/go-test.json- expected exit codes
- 0
- compliance / control
- SOC 2 CC7.2 · FedRAMP AU-2
PR-test command · JVM
JVM
Runs the project Gradle task graph with `--rerun-tasks` to force a fresh execution under the hermetic build hash; `init.gradle` pins the test-output listener.
DRIFTLOCK_HERMETIC=1 ./gradlew test --no-daemon --no-build-cache --rerun-tasks -I /etc/driftlock/init.gradle- expected exit codes
- 0
- compliance / control
- SOC 2 CC7.2 · FedRAMP AU-2
PR-test command · Rust
Rust
Runs the project test suite under the locked-lockfile constraint the hermetic build hash pins; emits the JSON message format the runner normalizes.
DRIFTLOCK_HERMETIC=1 cargo test --locked --no-default-features --message-format=json | tee /tmp/driftlock/cargo-test.json- expected exit codes
- 0
- compliance / control
- SOC 2 CC7.2 · FedRAMP AU-2
npm test · pytest · go test · ./gradlew test · cargo test · /tmp/driftlock/* reports
Compliance mapping
One table — every control the audit cites, and the knob(s) that implement it.
The platform team hands this table to the compliance reviewer alongside the values.yaml diff. Each row names a control (SOC 2 / FedRAMP / ISO 27001), the framework it belongs to, the obligation it encodes, and the sandbox knob(s) the runtime uses to satisfy it. A staff-plus engineer reads both direction: knob-to-control (this table) and control-to-knob (when responding to an audit finding).
Control · framework
Obligation · sandbox knobs
SOC 2 CC6.1
SOC 2 Trust Services Criteria
Logical access controls — restrict access to information assets based on authorized, validated need.
SOC 2 CC6.6
SOC 2 Trust Services Criteria
Logical access controls at the network boundary — restrict external connections based on a defined allow-list and deny-by-default posture.
SOC 2 CC6.7
SOC 2 Trust Services Criteria
Restriction of data transmission to authorized parties over encrypted, integrity-verified channels.
SOC 2 CC7.2
SOC 2 Trust Services Criteria
System monitoring — detect, log, and respond to anomalies and deviations from the established baseline.
FedRAMP AC-4
FedRAMP Rev. 5 — Access Control
Information flow enforcement — restrict the flow of information to authorized destinations based on policy.
FedRAMP AU-2
FedRAMP Rev. 5 — Audit and Accountability
Audit events — record the occurrences and characteristics of events that affect the system.
ISO 27001 A.8.24
ISO/IEC 27001:2022
Use of cryptography — controls the effective use of cryptography to protect information confidentiality, integrity, and authenticity.
What a tightening reviewer should check
- Every knob the team enables appears as a key in the audit-trail row — sandbox.cpu maps to audit.sandbox.cpu, which maps to SOC 2 CC6.1.
- Every secret the team mounts appears in the runtime's secret-mounts column with a custody row matching FedRAMP AC-4 or the matching SOC 2 / ISO 27001 row above.
- Network-isolation toggles stay at their safe defaults — egress.allowed: [], dns.policy: cluster, tls.pinningRequired: true — and any exception appears in the runbook with the control it relaxes.
SOC 2 · FedRAMP · ISO 27001 · knob-to-control · control-to-knob
Back to the runbook
The parent /docs page covers the audit-trail row + SBOM emission per configuration — this page covers the knobs platform teams actually set.
The nine-knob sandbox table on /docs → Sandbox config maps each key to its audit column and SBOM output. This deep-dive covers the five supported base images, six per-step resource limits with ceilings, five secret-mount patterns with custody story, the network-isolation toggle set, PR-test command templates per language, and the full compliance-control mapping.
Request a deeper-docs walkthrough
We'll reply with a calendar link and the air-gap or key-handling runbook relevant to your scope.