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
oee keygencreates an Ed25519 key pair:oee.keysigns,oee.pubverifies and is embedded into the supervisor.oee build --sign-keysigns 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.- At every start,
oee-stubchecks theOEE!trailer, recomputes the Merkle root and verifies the signature before the guest starts. oee inspect --verify-key oee.pubperforms 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
strictcap. - No silent downgrade. If a
strictcap or acontainer_fallback: "strict"sandbox primitive cannot be enforced, the binary refuses to start with exit code69, and the selected enforcement tier is printed in the startup audit event. - Authenticated local control.
oee statusandoee stoptalk 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_sha256pins 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.1by 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 case | What could go wrong | What the Executor does |
|---|---|---|
| Multi-worker or double-fork escape | A 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 SIGTERM | The 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 key | An 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 manipulation | A 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 spoofing | The 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 workers | The 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 enforced | The 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 container | A "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 oscillation | Usage 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 collision | The 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-loops | Traffic 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 event | A 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 restrictions | Standard 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.