This procedure is useful when an application Maintainer needs a small, reviewed transformation but shouldn't control the environment that runs it. The Maintainer can propose the harmless input. A trusted operator reviews those bytes and controls the runtime, image, task program, Docker context, host paths, records, and cleanup.
The procedure constrains one task on one local Docker context. It doesn't constrain the application Maintainer's GitLab pipelines, isolate arbitrary hostile code, deliver a production secret, select a production runner, or prove full CI isolation. Containers share the host kernel; treat Docker daemon or socket access as trusted host authority.
Prepare the reviewed task and input
Use the example-file setup to establish GSS_GUIDE_CHECKOUT, then work from that root with the reviewed task.py. The task has no dependencies outside Python's standard library. It reads one immutable JSON input, returns a sorted unique list with its count and sum, and checks the local boundaries described below.
First prepare the Python runtime. That setup downloads and inspects the exact Linux ARM64 image on Docker Desktop's desktop-linux context. The task uses the cached image and doesn't install dependencies while running.
set -euo pipefail
umask 077
cd "$GSS_GUIDE_CHECKOUT"
export GSS_IMAGE='python@sha256:f77ac9e44ae96ef2c90b8053ea08c31f8be030f824196b0ae4db6d462c84e51f'
export GSS_CONTEXT='desktop-linux'
export GSS_TASK="$GSS_GUIDE_CHECKOUT/examples/isolated-task/task.py"
export GSS_RUN_ID="$(python3 -c 'import secrets; print(secrets.token_hex(8))')"
export GSS_NAME="gss-isolated-${GSS_RUN_ID}"
export GSS_LABEL="gss.isolated.task=${GSS_RUN_ID}"
export GSS_RECORD_DIR="$PWD/isolated-task-${GSS_RUN_ID}"
install -d -m 700 "$GSS_RECORD_DIR/input"
cat > "$GSS_RECORD_DIR/input/request.json" <<'JSON'
{"schema":"gss-isolated-task-input-v1","values":[9,2,9,-3]}
JSON
chmod 0444 "$GSS_RECORD_DIR/input/request.json"
export GSS_TASK_SHA256="$(python3 -c 'import hashlib,sys; print(hashlib.sha256(open(sys.argv[1],"rb").read()).hexdigest())' "$GSS_TASK")"
export GSS_INPUT_SHA256="$(python3 -c 'import hashlib,json,sys; value=json.load(open(sys.argv[1])); raw=json.dumps(value,sort_keys=True,separators=(",", ":")).encode(); print(hashlib.sha256(raw).hexdigest())' "$GSS_RECORD_DIR/input/request.json")"
printf '%s %s\n' "$GSS_TASK_SHA256" "$GSS_TASK" > "$GSS_RECORD_DIR/source-hashes.txt"
printf '%s %s\n' "$GSS_INPUT_SHA256" "$GSS_RECORD_DIR/input/request.json" >> "$GSS_RECORD_DIR/source-hashes.txt"
The input must contain only schema and values, with 1–32 JSON integers in the range -1,000,000 through 1,000,000. Booleans are rejected. When the application Maintainer supplies the input, the trusted operator reviews these exact bytes before continuing. That keeps the approved input tied to the hash used later in the run.
Confirm Docker points to the intended daemon and the pinned image is already present. Record its immutable ID, platform, repository digest, and built-in environment. The later container comparison requires that Docker add no environment entry beyond the pinned image; the task process itself starts under env -i with three explicit non-secret values.
docker --context "$GSS_CONTEXT" context inspect > "$GSS_RECORD_DIR/context.json"
docker --context "$GSS_CONTEXT" image inspect "$GSS_IMAGE" > "$GSS_RECORD_DIR/image.json"
jq -e --arg image "$GSS_IMAGE" '
length == 1 and .[0].Os == "linux" and .[0].Architecture == "arm64" and
(.[0].RepoDigests | index($image)) != null and
(.[0].Id | test("^sha256:[0-9a-f]{64}$"))
' "$GSS_RECORD_DIR/image.json"
export GSS_IMAGE_ID="$(jq -er '.[0].Id' "$GSS_RECORD_DIR/image.json")"
Confirm the exact name is unused
Check that the exact name is free before creating anything. Only Docker's missing-object response establishes absence; a daemon, context, or transport failure leaves the name unresolved.
require_absent() {
name="$1"; output="$GSS_RECORD_DIR/absence-${name}.out"; error="$GSS_RECORD_DIR/absence-${name}.err"
set +e
docker --context "$GSS_CONTEXT" container inspect "$name" >"$output" 2>"$error"
status=$?
set -e
test "$status" -eq 1
grep -Eiq 'no such (object|container)' "$error"
}
require_absent "$GSS_NAME"
Create, inspect, then start once
Create the container in a stopped state and leave out --rm so you can inspect the exact object before any task code runs. Its only host mounts are the reviewed program and input, both read-only. /workspace is a one-MiB tmpfs owned by UID/GID 65532. The container has a read-only root, no network namespace attachment, published port, added capability, device, Docker socket, credential, home directory, repository, writable host mount, or host environment pass-through.
export GSS_TASK_REAL="$(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$GSS_TASK")"
export GSS_INPUT_REAL="$(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$GSS_RECORD_DIR/input/request.json")"
printf '%s\n' "intent create $GSS_NAME $GSS_LABEL" > "$GSS_RECORD_DIR/create-intent.txt"
export GSS_CONTAINER_ID="$(docker --context "$GSS_CONTEXT" create \
--pull=never --name "$GSS_NAME" --label "$GSS_LABEL" \
--platform linux/arm64 --network none --read-only \
--user 65532:65532 --cap-drop ALL \
--security-opt no-new-privileges \
--memory 64m --cpus 0.5 --pids-limit 32 \
--mount "type=bind,src=${GSS_TASK_REAL},dst=/program/task.py,readonly" \
--mount "type=bind,src=${GSS_INPUT_REAL},dst=/input/request.json,readonly" \
--tmpfs '/workspace:rw,nosuid,nodev,noexec,size=1m,uid=65532,gid=65532,mode=0700' \
"$GSS_IMAGE" \
/usr/bin/env -i \
'PATH=/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' \
'LANG=C.UTF-8' 'GSS_TASK_MODE=isolated' \
/usr/local/bin/python /program/task.py)"
[[ "$GSS_CONTAINER_ID" =~ ^[0-9a-f]{64}$ ]]
printf '%s\n' "$GSS_CONTAINER_ID" > "$GSS_RECORD_DIR/container-id.txt"
docker --context "$GSS_CONTEXT" container inspect "$GSS_CONTAINER_ID" \
> "$GSS_RECORD_DIR/container-created.json"
If creation is interrupted or doesn't return an exact 64-character ID, stop and reconcile the name and ownership label before deciding what to do next. Don't repeat docker create while the first request's outcome is uncertain.
Before running any task code, compare the stopped container with the reviewed command:
jq -e \
--arg id "$GSS_CONTAINER_ID" --arg name "/$GSS_NAME" \
--arg label "$GSS_RUN_ID" --arg image_id "$GSS_IMAGE_ID" \
--arg task "$GSS_TASK_REAL" --arg input "$GSS_INPUT_REAL" \
--argjson image_env "$(jq '.[0].Config.Env' "$GSS_RECORD_DIR/image.json")" '
.[0] as $c |
$c.Id == $id and $c.Name == $name and $c.Image == $image_id and
$c.State.Status == "created" and $c.Config.User == "65532:65532" and
$c.Config.Labels["gss.isolated.task"] == $label and
$c.Config.Env == $image_env and
$c.Config.Cmd == ["/usr/bin/env","-i",
"PATH=/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
"LANG=C.UTF-8","GSS_TASK_MODE=isolated","/usr/local/bin/python","/program/task.py"] and
$c.HostConfig.NetworkMode == "none" and $c.HostConfig.ReadonlyRootfs == true and
$c.HostConfig.Privileged == false and $c.HostConfig.CapDrop == ["ALL"] and
($c.HostConfig.SecurityOpt | index("no-new-privileges")) != null and
$c.HostConfig.Memory == 67108864 and $c.HostConfig.NanoCpus == 500000000 and
$c.HostConfig.PidsLimit == 32 and
($c.HostConfig.PortBindings == null or $c.HostConfig.PortBindings == {}) and
(($c.HostConfig.Devices // []) | length) == 0 and
(($c.HostConfig.DeviceRequests // []) | length) == 0 and
($c.HostConfig.Tmpfs["/workspace"] | split(",") |
(index("rw") != null and index("nosuid") != null and index("nodev") != null and
index("noexec") != null and index("size=1m") != null and
index("uid=65532") != null and index("gid=65532") != null and
index("mode=0700") != null)) and
($c.Mounts | length) == 2 and
any($c.Mounts[]; .Source == $task and .Destination == "/program/task.py" and .RW == false) and
any($c.Mounts[]; .Source == $input and .Destination == "/input/request.json" and .RW == false)
' "$GSS_RECORD_DIR/container-created.json"
This inspection confirms how the cgroup limits are configured. It doesn't exercise CPU, memory, or PID exhaustion.
Start the exact stopped container once and capture its output. If the start is interrupted, inspect that same container before deciding what to do next; a retry could run the task twice.
printf '%s\n' "intent start $GSS_CONTAINER_ID" > "$GSS_RECORD_DIR/start-intent.txt"
docker --context "$GSS_CONTEXT" start --attach "$GSS_CONTAINER_ID" \
> "$GSS_RECORD_DIR/task.stdout" 2> "$GSS_RECORD_DIR/task.stderr"
test ! -s "$GSS_RECORD_DIR/task.stderr"
docker --context "$GSS_CONTEXT" logs "$GSS_CONTAINER_ID" \
> "$GSS_RECORD_DIR/docker.stdout" 2> "$GSS_RECORD_DIR/docker.stderr"
test ! -s "$GSS_RECORD_DIR/docker.stderr"
cmp "$GSS_RECORD_DIR/task.stdout" "$GSS_RECORD_DIR/docker.stdout"
test "$(wc -l < "$GSS_RECORD_DIR/task.stdout" | tr -d ' ')" -eq 1
docker --context "$GSS_CONTEXT" container inspect "$GSS_CONTAINER_ID" \
> "$GSS_RECORD_DIR/container-finished.json"
jq -e --arg id "$GSS_CONTAINER_ID" '
.[0].Id == $id and .[0].State.Running == false and
.[0].State.ExitCode == 0 and .[0].State.OOMKilled == false
' "$GSS_RECORD_DIR/container-finished.json"
Check the result
The output is useful only when the task demonstrates each of these properties:
- UID and GID 65532;
- an exact three-key process environment created by
env -i; - write denial with only
EACCESorEROFSaccepted when appending to the program or input and creating a root-level file; Docker inspection independently requires a read-only root and both bind mounts withRW=false; - a successful TCP exchange with an in-process helper on
127.0.0.1; - exact
ENETUNREACHfor one TCP connection to documentation address198.51.100.1; ENOSPCwhile filling the one-MiB workspace, followed by removal of the fill file; and- the fixed-format JSON transformation.
A timeout or another off-host errno leaves the network result uncertain. It doesn't establish the expected no-egress behavior. Check the single stdout object independently:
jq -e --arg input_sha "$GSS_INPUT_SHA256" '
keys == ["count","gid","input_sha256","loopback","off_host_errno","schema",
"sum","uid","values","workspace_enospc"] and
.schema == "gss-isolated-task-result-v1" and
.input_sha256 == $input_sha and .values == [-3,2,9] and
.count == 3 and .sum == 8 and .uid == 65532 and .gid == 65532 and
.loopback == "loopback-ok" and .off_host_errno == 101 and
.workspace_enospc == true
' "$GSS_RECORD_DIR/task.stdout"
python3 -c 'import hashlib,sys; print(hashlib.sha256(open(sys.argv[1],"rb").read()).hexdigest())' \
"$GSS_RECORD_DIR/task.stdout" | tee "$GSS_RECORD_DIR/result-sha256.txt"
Remove only the recorded container
Before removal, compare the ID, exact name, and run label with the recorded values. Then remove that stopped ID once and check that Docker reports the exact name as missing:
docker --context "$GSS_CONTEXT" container inspect "$GSS_CONTAINER_ID" \
| jq -e --arg id "$GSS_CONTAINER_ID" --arg name "/$GSS_NAME" --arg run "$GSS_RUN_ID" '
.[0].Id == $id and .[0].Name == $name and
.[0].Config.Labels["gss.isolated.task"] == $run'
printf '%s\n' "intent remove $GSS_CONTAINER_ID" > "$GSS_RECORD_DIR/remove-intent.txt"
test "$(docker --context "$GSS_CONTEXT" container rm "$GSS_CONTAINER_ID")" = "$GSS_CONTAINER_ID"
require_absent "$GSS_NAME"
Keep the task and input hashes, context and image inspection, create/start/remove intents, exact container ID, pre-start and terminal inspections, stdout, Docker logs, result hash, and absence readback for as long as your retention policy requires. Apply that policy before removing the input or these records.
When all checks pass, you've run one reviewed, credential-free local task under these exact controls. The trusted Docker operator can still control the host and runtime. Before moving an application-controlled task, secret, or network exception into CI, choose a runner and executor administered outside application-Maintainer authority. In that environment, define and test the image and dependency policy, writable paths, secret broker, and destination-level egress policy.
Product references
Docker documents the relevant flags and boundaries in Running containers, docker container create, resource constraints, tmpfs mounts, and Docker Engine security. For the unresolved CI selection, review GitLab's hosted-runner properties and security guidance for self-managed runners before choosing an executor for application-controlled code, secrets, or network access.