# Customer isolation 0.3.1 — independent review candidate ## Threat model and three mandatory paths Untrusted Python runs in a **credentialless, network-none Linux Docker worker**. It can monkeypatch the SDK, use native sockets, fork, call setsid, or forge local requests, but those operations do not grant direct external connectivity or provider credentials within a correctly configured container boundary. A host-side broker, outside the worker, executes only registered typed operations: 1. **Network/action gate:** no worker internet, DNS, metadata, providers or hosted gateway access. Only one read-only Unix socket mount. Broker validates typed arguments, asks the real Encased gateway, waits for matching approval and performs the exact frozen operation itself. Never hand an allow permit back to the worker to execute an arbitrary effect. 2. **Process gate:** host-owned CPU, memory, PID limits and independent elapsed deadline; removal kills the whole container cgroup, including setsid children. Broker also limits total/repeated actions and serialises dispatch. It cannot infer semantic intent or detect all prompt injection. Subprocesses inside the container are allowed within PID/resource limits, not individually approved. 3. **Token gate:** only the broker has the provider key. The fixed-model handler reserves tokens/USD in a host-private SQLite ledger BEFORE provider dispatch. The ledger is shared across local broker processes and survives restarts. Full reservations are never refunded, even with known lower usage; uncertainty cannot reopen budget. Limits are immutable per ledger. No caller-controlled model, endpoint, prices, output cap, system role, tool, image or retry policy. The kernel, Docker daemon, default seccomp profile, reviewed images, broker, trusted configuration and customer administrator remain trusted. A container is not a VM or a guarantee against kernel/container escapes. Use an independently reviewed microVM/runtime where the threat model requires it. Allowed text inputs can still leak data to an approved provider or induce harmful allowed behaviour. ## Setup on a dedicated customer Linux Docker host Do not run this in the Encased website server. Install the 0.3.1 source package on a customer host. Review the image/dependencies and pin both base and final worker images by real SHA-256 digests. No mutable-image fallback is provided. ```sh curl -fL https://encased.ai/sdk/encased-0.3.1.tgz -o encased-0.3.1.tgz tar xzf encased-0.3.1.tgz cd encased-0.3.1 python3 -m venv .venv . .venv/bin/activate pip install . # From the extracted source root; replace with your independently reviewed digest: docker build --build-arg BASE="$REVIEWED_PYTHON_BASE_DIGEST" \ -f deployment/isolation-worker.Dockerfile -t encased-worker . mkdir -m 700 /var/lib/encased-test export ENCASED_STATE_DIR=/var/lib/encased-test export ENCASED_URL=https://encased.ai/api/public/v1 export ENCASED_FIXED_READ_URL=https://YOUR_REVIEWED_HOST/fixed-synthetic-document # Explicit, independently approved global addresses/CIDRs for that exact host: export ENCASED_READ_APPROVED_IPS="$REVIEWED_READ_IPS" # Set ENCASED_KEY securely in the HOST process only, never worker/image/CLI args. # Push your reviewed build to your own registry and pull its actual manifest # digest. A local image config ID is NOT a repository manifest digest. # Final image must already be available locally by repository@sha256:digest. python -m encased.isolation_runner --image "$REVIEWED_WORKER_DIGEST" \ --config examples/isolation_host.py ``` Set the optional host-only ENCASED_MODEL, ENCASED_TOKEN_LIMIT, ENCASED_SPEND_LIMIT_USD, ENCASED_INPUT_PRICE_PER_MILLION, ENCASED_OUTPUT_PRICE_PER_MILLION and OPENAI_API_KEY to enable llm.chat. Prices are customer-reviewed current provider prices, not invented defaults. The byte-plus-framing input bound is conservative for the supported text-only adapter but requires model/tokenizer qualification; usage overshoot stops the ledger after the fact and cannot undo billable work. Streaming is deliberately not supported in this isolation release. ### Approved domain AND IP controls The fixed read and optional model transport now require explicit approved global IP addresses or CIDRs as well as their exact HTTPS domain. Set ENCASED_READ_APPROVED_IPS (comma-separated addresses/CIDRs), and, when enabling the fixed api.openai.com model client, ENCASED_PROVIDER_APPROVED_IPS. There are no default approved ranges: missing configuration refuses startup. Review ranges with the destination owner; do not automatically approve fresh DNS answers. All DNS answers must match the allowlist and be global. Connections use the validated address directly, with TLS certificate/hostname checks and SNI for the approved domain. DNS changes to unapproved addresses fail closed. Redirects are refused, proxy environment is ignored, and provider requests are limited to the fixed non-streaming chat endpoint. Address rotation requires operator review. These controls cover the supplied fixed-read and provider effect transports; the existing Encased telemetry/control client remains a separate trusted channel. Arbitrary customer-added broker tools require their own approved transport and review. This is not a host-wide firewall. The worker still has NO direct internet, even to approved destinations. Local mocked transport tests are not proof of actual Linux isolation, a cloud-VM run, or independent containment assurance. The worker image has no secrets in any image layer, inherited environment, service tokens, extra volumes or runtime sockets. The runner refuses a credential/proxy environment or an isolation inspection mismatch, never falls back to an ordinary Python process, and does not attach worker stdout to the host terminal. Host broker permissions and socket paths must remain inaccessible to other untrusted host users. The mounted socket is per run, not multi-tenant. The runner explicitly disables Docker logging to prevent worker output exhausting host disk. Collect only bounded broker evidence; opt-in test probes temporarily use the rotating local log driver to read short synthetic results. ## Exactly what is and is not durable actions.sqlite claims each worker request ID before proposal. Claimed IDs cannot be dispatched again, even after a broker restart. State distinguishes claimed, dispatching, admitted, completed and stopped/uncertain. No prompts, secrets, results or full memory are stored in this journal, only request hashes, IDs and state. Intent telemetry must be acknowledged before effects. If completion telemetry fails, the result is uncertain to the caller and the broker stops; never retry blindly. A new ID is a new proposed operation, not deduplication of a business transaction. Add downstream transaction idempotency before financial/destructive tools; this release intentionally registers neither. Crash recovery requires human reconciliation, not automatic replay. SQLite is single-host shared storage, not a distributed ledger, and deleting state as administrator resets protection. Action/repetition counters are per broker run and reset on reconstruction; budgets and consumed request IDs do not. Trusted administrators control starting new runs. Stop and dispatch admission are linearised, but an already admitted operation can still finish after stop; external side effects are not reversible. Worker termination cannot cancel an already dispatched provider/remote effect. Pending review may continue in the broker after container removal, but the stop flag prevents later dispatch. A local operator stop/deadline is not a remote dashboard kill channel. Encased key revocation stops the next gateway request, not the check-to-dispatch interval or already billable remote work. ## Qualification and acceptance ```sh python -m unittest discover -s tests -v # Full Linux qualification (builds the worker image, runs every container probe, # prints a PASS/FAIL verdict). Run on the reviewed Linux customer host: ENCASED_DOCKER_TEST_IMAGE="$REVIEWED_WORKER_DIGEST" \ ./deployment/run-linux-isolation-tests.sh python:3.13-slim@sha256: # Or run the container suites directly against a pinned worker image: ENCASED_DOCKER_TEST_IMAGE="$REVIEWED_WORKER_DIGEST" \ python -m unittest tests.test_linux_isolation tests.test_isolation_docker -v ``` The qualification suite (tests/test_linux_isolation.py) verifies: all network paths blocked (TCP/UDP/IPv6/DNS/cloud metadata), detached child processes cannot escape the network boundary, no credential-like environment variables or Docker socket in the worker, unprivileged uid, read-only root filesystem, noexec /tmp, pids and memory cgroup limits, the runner's own container verification, and externally forced removal killing escaped children. The script requires a reviewed base digest and a real pulled worker manifest digest matching the source build. It refuses mutable bases or fabricated tag-plus-image-ID digests. Push the build to your registry before qualification. Local tests exercise real Unix-socket dispatch with synthetic gateway decisions, exact frozen arguments, duplicate/restart rejection, denial, telemetry failure, budget persistence/concurrent reservations and Docker configuration refusal. The opt-in Docker suite probes raw sockets, IPv6/UDP, subprocess/setsid, credential absence, blocked host mounts and externally forced termination. Those Docker tests are **not passed merely because they were skipped**. This builder environment has no Docker engine; actual container enforcement and billable provider calls remain unverified here. Lucas must run the container suite, inspect host traffic/cgroups, run a real disposable-workspace allow/review/deny/revoke journey, measure deadline/overshoot and independently review broker/sandbox code. No production containment assurance, certification, global exactly-once effect, shared hosted policy delivery, remote emergency stop or universal bypass-proof claim is made. Publish/deploy only after reviewing the actual host configuration.