94 lines
9.2 KiB
Markdown
94 lines
9.2 KiB
Markdown
# 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](../docs/reference/kernel-extensions.md)).
|
||
|
||
**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`](https://github.com/holepunchto/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.
|
||
|
||
---
|
||
|
||
## See also
|
||
|
||
- [Blind relay / P2P hardening (proc defaults)](../docs/security/blind-relay-p2p-hardening.md)
|
||
- [Handbook — Blueprints / trust](../handbook/02-blueprints.md)
|
||
- [Chapter 5 — Modules](05-modules-and-imports.md)
|
||
|
||
---
|
||
|
||
[← Testing](08-testing-and-debugging.md) · [Glossary →](10-glossary-and-faq.md)
|