Browse the documentation

Early preview

Security and integrity

Every Executor binary verifies itself before your application runs, carries a policy that nothing at run time can weaken, and keeps the supervisor's secrets away from the code it supervises.

A memory-safe core

Both the oee CLI and the oee-stub supervisor are written entirely in Rust and compile to static executables with no C or OpenSSL libraries. The security-sensitive parts rely on audited Rust crates: rustls for TLS 1.3 and certificate pinning, seccompiler for seccomp-BPF filters compiled in pure Rust, landlock for Linux filesystem access control, rustix for type-safe POSIX and Linux system calls, and windows-sys for Win32 Job Objects, AppContainer and the Windows Filtering Platform.

Signing and verification

  1. oee keygen creates an Ed25519 key pair: oee.key signs, oee.pub verifies and is embedded into the supervisor.
  2. oee build --sign-key signs the policy and writes the binary's footer: the BLAKE3 Merkle root across segments 1 to 4 (supervisor, policy, runtime, application) and a 64-byte Ed25519 detached signature.
  3. At every start, oee-stub checks the OEE! trailer, recomputes the Merkle root and verifies the signature before the guest starts.
  4. oee inspect --verify-key oee.pub performs the same verification on demand.

Any byte modification to the supervisor, the embedded oee.yaml policy or the bundled runtime archive fails BLAKE3 and Ed25519 verification before guest execution begins. See Single-binary layout.

A policy nothing at run time can weaken

  • Sealed caps. CPU and memory caps travel inside the signed binary. No environment variable, CLI flag, control-socket command or remote API response can raise or disable a strict cap.
  • No silent downgrade. If a strict cap or a container_fallback: "strict" sandbox primitive cannot be enforced, the binary refuses to start with exit code 69, and the selected enforcement tier is printed in the startup audit event.
  • Authenticated local control. oee status and oee stop talk to the supervisor over authenticated, user-scoped control sockets. Checkpoints use a random per-run token, OEE_IPC_TOKEN.

Secret scrubbing

Exit-event credentials can come from an environment variable (from_env), a mounted secret file (from_file) or a token you explicitly seal into the signed manifest. With scrub_from_guest_env: true, the default, oee-stub reads the variable into supervisor memory at startup and strips it from the environment passed to the guest runtime. An untrusted guest script that inspects its environment never sees the exit-event key. The guided configuration never writes a secret into oee.yaml unless you choose a sealed static token.

Network trust

  • TLS 1.3 with SPKI pinning. pinned_spki_sha256 pins the control API's public keys, so a local proxy or a modified host CA store cannot spoof a "keep running" response.
  • Signed responses. Optionally, an Ed25519 signature over the response body and the request nonce (X-OEE-Response-Sig) prevents replayed responses.
  • Separate control plane. The supervisor's HTTP client is set up before the guest is placed in its own network context, so an air-gapped guest cannot reach the network while the supervisor keeps polling its exit event.
  • Webhook on loopback. The inbound webhook listens on 127.0.0.1 by default, supports bearer and HMAC authorization with timestamp replay protection, and is never reachable through the guest sandbox.

Edge cases and how the Executor handles them

Threat or edge caseWhat could go wrongWhat the Executor does
Multi-worker or double-fork escapeA uvicorn worker or a shell script forks background workers (setsid) that outlive the main process when it stops.On Linux, PR_SET_CHILD_SUBREAPER, a PID namespace and cgroup.kill track and stop every descendant atomically; on Windows, the Job Object enforces kill-on-close with breakaway disabled.
Guest ignores SIGTERMThe application traps SIGTERM and refuses to exit during a graceful stop.The drain stage enforces a strict monotonic grace_period_ms deadline and escalates to the uncatchable SIGKILL or TerminateJobObject.
Guest reads the exit-event keyAn untrusted script inspects its environment to steal OEE_AUTH_TOKEN and query or flood the exit-event API.With scrub_from_guest_env: true (default), the supervisor reads the variable at startup and removes it from the child's environment.
System clock manipulationA host user sets the clock back (date -s "-2 hours") to escape a one-hour limit.Durations run on hardware monotonic counters (CLOCK_MONOTONIC_RAW, CLOCK_BOOTTIME, QueryPerformanceCounter), unaffected by wall-clock changes.
Local DNS or proxy spoofingThe host redirects the exit-event domain in /etc/hosts to a local server answering {"ep_flag": "OK"}.TLS 1.3 SPKI pinning and optional Ed25519 response signatures reject unauthenticated responses immediately.
Cap evasion by forked workersThe guest spawns extra workers or detached daemons to get more CPU or memory.Caps apply to the cgroup or Job Object holding the whole tree, so every descendant shares one budget.
Strict cap cannot be enforcedThe host has no delegated cgroup or no kernel hard limit, so a strict cap would silently become advisory.The binary refuses to start with exit code 69 unless the manifest opts into the governor tier; the enforcement tier is always printed in the startup audit event.
Percentage cap inside a containerA "10%" cap resolves against the host's 64 cores although the container is limited to 4.The capacity base is the smaller of host capacity and the container limit read from the container's cgroup.
Scaling oscillationUsage hovers near a threshold and replicas start and stop repeatedly.Separate lower and upper thresholds, sustained-breach windows, a cooldown after each action, and one replica per decision.
Replica port collisionThe port chosen for a new replica is taken between selection and bind.The start is retried on the next free port, the load balancer adds a backend only after readiness passes, and a configured range is honored.
Replica fails readiness or crash-loopsTraffic is sent to a dead backend.Traffic is gated on readiness, failed backends are ejected by health checks, and restarts use exponential backoff with a limit that stops the instance.
Spoofed stop eventA local user posts to the webhook, edits the watched file or produces a Kafka message to stop the service.The webhook listens on loopback by default with bearer or HMAC authorization and replay protection; Kafka supports TLS and SASL; for file-watch rules, the watched path's permissions are the trust boundary.
Unprivileged container restrictionsStandard Docker or Kubernetes blocks CLONE_NEWUSER or mount with EPERM.The Executor detects the container's capabilities and applies Landlock, seccomp-BPF and subreaper containment without privileged container flags.

Reporting a vulnerability

Security reports go to hello@openeng.ai, the address in this site's security.txt.