9.2 KiB
Chapter 9 — Security and trust (developer mindset)
Bare OS is research software. It is not a hardened multi-tenant OS. Still, developers should understand what is trusted and what full ctx power implies.
System drive trust model
The system Hyperdrive is the OS image. You normally obtain it by replicating from peers that share the project’s discovery topology (see handbook protocol chapters). The codebase assumes you trust that image the same way you would trust an installer ISO from a vendor you chose.
/bin and /boot bytes are executed as JavaScript. A malicious seeder could ship hostile /bin scripts. Mitigation is social and operational: use keys and peers you trust, verify releases, run your own seeder for development.
Boot snippet tightening: with BARE_OS_BOOT_ALLOWLIST=1, the stock kernel only runs lines from trusted rc, rc.d, rc.local, kernel.d, and onboot whose first shell token appears in /etc/bare-os/boot.allow (plus builtins such as export, cd, :). Pair with **BARE_OS_BOOT_STRICT=1** to exit the session on the first disallowed or failing line.
Boot manifest integrity: BARE_OS_BOOT_MANIFEST=1 makes the stock kernel compare /etc/bare-os/boot.manifest.json to an expected digest (ctx.bareOsBootFileSha256Hex). **BARE_OS_BOOT_MANIFEST_SIGN=1** adds Ed25519 verification of the raw manifest bytes against /etc/bare-os/boot.manifest.sig, using ctx.bareOsVerifyBootManifestSignature and BARE_OS_BOOT_MANIFEST_PUBKEY_HEX (64 hex chars). Rotation is operational: ship a new public key in host env and a matching signature file on the system image. This does not replace image trust—you still choose peers and seed sources carefully.
Seed capability attestation (optional): the seeder may answer bare_os.capability_attestation with JSON from host env BARE_OS_SEED_CAPABILITY_ATTESTATION_JSON (for example a distro or hyper-multisig bundle). The guest does not verify signatures; operators verify on the host or out-of-band. BARE_OS_BIN_WORKER_OFFLOAD is a reserved gate for future isolated /bin execution—stock paths remain in-process unless a host integration supplies a worker bridge.
Audit: BARE_OS_AUDIT=1 logs execLine activity to /var/log/bare-os/audit.log. BARE_OS_AUDIT_JSON=1 uses JSON lines with auditSchemaVersion: 2 on execLine, delegate, and httpFetch records; BARE_OS_AUDIT_REDACT=1 (or true) masks common secret-like **VAR=value** patterns; **BARE_OS_AUDIT_REDACT=TOKEN,PASSWORD** masks named keys.
Delegated HTTP: when the booter sets ctx.httpFetch from the host fetch, BARE_OS_HTTP_ALLOWLIST and BARE_OS_HTTP_DENYLIST restrict **http/https** URLs for **curl/wget** (host-pattern globs). Failed checks throw before the request; with audit on, allow/deny outcomes can be logged.
Host CLI delegates: git, curl, wget, and systemctl-family commands can be restricted with BARE_OS_DELEGATE_ALLOW (comma list; empty = all). Optional per-minute caps use BARE_OS_DELEGATE_MAX_PER_MIN and per-kind BARE_OS_DELEGATE_*_MAX_PER_MIN. With **BARE_OS_AUDIT=1**, **BARE_OS_DELEGATE_AUDIT_ONLY=1** logs delegate invocations and skips the host run (exit 0) for audit-only environments.
DNS allowlist: BARE_OS_DNS_ALLOWLIST optionally constrains http(s) hostnames for **curl/wget** before fetch (suffix wildcard ***.example.com** supported).
DNSSEC: the stock guest does not validate DNSSEC; resolvers and TLS stacks on the host own DNSSEC, DANE, and related policy. Do not infer DNS security properties from Bare OS delegate behavior alone.
IPC JSON-RPC: when BARE_OS_IPC_RPC_TOKEN is set, pushJson payloads must include matching bareOsIpcToken or the push throws. Line size is capped (BARE_OS_IPC_JSON_MAX_BYTES, default 256 KiB).
Sandboxed scripts: ctx.bareOsSandboxRunScript(source, argv?, opts?) runs in-image JS with a restricted ctx: writes are limited to the personal namespace (same routing rules as isPersonalRoute), and identity / vault / virtual-file registration hooks are disabled. Disable entirely with BARE_OS_SANDBOX_SCRIPT=0. BARE_OS_SANDBOX_WORKER=1 prefers bare-worker when the host provides it, else defers on a fresh microtask; neither path is a hardware isolate. For documented stronger separation, operators may compose Holepunch cross-worker / bare-bundle-evaluate patterns (see comments in packages/bare-os-booter/lib/bare-os-sandbox.js). This remains not a guaranteed security boundary—treat sandboxing as a trust reducer.
WebAssembly and native FFI (policy): a future guest WASM runtime must map imports to capability-gated ctx.vfs / IPC surfaces only—never raw host syscalls. **Native bare-addon** loading belongs on the Pear host with explicit allowlists; the replicated system image should not ship unsigned addons. Pair WASM/FFI plans with boot.policy.json denyKernelSyscalls / allowedCtxMethods and treat both as experimental until a dedicated ADR lands.
Provenance: /proc/bare_os_provenance (and /proc/bare_os/provenance) combines boot manifest digest, optional signing flags, and Pear channel hints for operators (see kernel extensions).
Pear trust summary (operator): /proc/bare_os/pear_trust.json reflects optional host JSON from BARE_OS_PEAR_TRUST_JSON (e.g. multisig-link style metadata). The guest does not verify multisig or Pear channel signatures—operators validate on the host or out-of-band.
Pear IPC allowlist: when boot.policy.json sets allowedPearIpcChannels, the stock kernel copies it to BARE_OS_BOOT_POLICY_PEAR_IPC_CHANNELS so ctx.bareOsPearIpcEmit only forwards listed channels.
Documented bare-subprocess bridge: feature bit BARE_OS_FEATURE2_BARE_SUBPROCESS_BRIDGE names an optional, default-off host integration pattern using Holepunch bare-subprocess for long-running delegated commands with a message bridge back to ctx. Stock images do not enable it unless a distributor wires env + allowlists explicitly. Capability word 5 adds bareOsReadSubprocessBridgeSnapshot with optional cgroupRootHint / signal lists from BARE_OS_SUBPROCESS_BRIDGE_META_JSON — these are host-supplied hints only; the guest must not treat them as a Linux security boundary.
Personal drive and user scripts
Anything you can write to $HOME can be executed if you run it—and you are the typical author. If you download a script from the network into your home directory and execLine it, you have effectively eval’d untrusted code with access to:
ctx.vfs(read/write personal tree),- identity hooks (if exposed through crafted shell lines),
runBinCommand(invoke all bundled utilities).
The stock shell does not sandbox run. Treat drive-resident JS like shell scripts with superpowers.
Why “add dynamic import from the internet” is dangerous
Loading modules from Hyperdrive or HTTP sounds convenient but creates:
- Supply chain exposure (mutable remote code),
- Ambiguous versioning (no lockfile on device),
- Larger attack surface in the booter.
The project’s conservative stance: bundle on the host or ship utilities in the system image after review.
Guest vs unlocked identity
Default guest sessions have predictable HOME=/home/guest and no Ed25519 identity. Login unlocks /.bare/account and changes ctx.vfs.env (user, home, keys). Applications that handle secrets should never log passphrases or raw keys; use existing login / logout flows.
pear.multisig.json metadata (signer list + quorum) is validated by the same shape predicate in bare-os-protocol (seeder hint) and the bundled guest helper bareOsPearMultisigShapeOk in kernel/lib/boot/00-pear-multisig-shape.js; keep those files aligned when changing rules.
BARE_OS_RC_PROPOSAL_MULTISIG_STRICT ties /etc/bare-os/rc.proposals/enabled/*.json to that policy before rc.d: each proposal lists approved signer public keys in signaturesFrom; the guest checks membership and quorum only (host tooling should verify signatures over proposal payloads before writing enabled/).
Reporting issues
Security vulnerabilities in this repo should be reported through the project’s normal channels (maintainer contact / GitHub security advisories if enabled). Do not open public issues with exploit details until coordinated disclosure.