privatae-bastion/docs/ops.md

Ops and action ops

Ops: programs your host wrote, run in a sandbox first

A host can ship an op, a small program (op.yaml plus run) it wrote and tested, identified by the sha256 of its contents. It runs here only under terms the host signed and you approved: once, with these parameters, or as a standing grant with parameter bounds, an expiry and a use count (never as root). Every run is a dry run first, in a throwaway sandbox with no network, an overlay over this machine's disks, and this bastion's own records masked; it reports what the op would create, change and remove. An op sees only the system's programs and libraries, a few /etc files that hold no secret, and the paths its manifest declares (its effects and its reads). Every other file and folder is covered with an empty one. A link is left in place, so an op can read where a link points, but not what is there. The op can also see the names of the folders it was denied, in its own mount table. A declared path that reaches a credential store is refused, as written and as it resolves, and checked again at every run. The stores are /root, /etc/ssh, /etc/shadow, /etc/wireguard, /etc/systemd, docker's and k3s's keys and more, plus any path you list in this machine's sensitive_paths. Covers are put on paths, so a bind mount or a hard link that you make yourself, putting a credential file inside a declared path, is seen through it. List such a path in sensitive_paths. Anything outside the op's declared file effects refuses the run. Applying is the same run again, then a check in a fresh sandbox. A one-time apply is bound to the change list the dry run showed you, and lands nothing else. A run under a standing grant is bound to the grant's parameter bounds and the op's declared effects instead: you approved the grant, not each run's change list. Linux only, and file effects only; other platforms refuse every op and say so. privatae-bastion ops lists what is held, and ops drop <grant> takes a standing grant back.

Action ops: ship steps, run the same way

A ship step acts rather than edits: it builds and pushes an image, moves a source tree to a new commit, restarts a service, rolls a workload. An op with kind: action does this in two parts, and approving it works the same way: a dry run first, then an apply bound to the change list the dry run showed.

• The op's program runs unprivileged. Each run gets a uid no earlier run had, in its own systemd transient unit, with no capabilities and no new privileges. This machine's files are read-only to it: it writes only to a private work folder at /tmp and its own throwaway /run and /var/tmp. It sees only what a files op sees (above).

• Its network, in an apply, reaches only the destinations it declares (host:port):

  • the unit's address allowlist holds it to the addresses those names resolved to when the run began;
  • Landlock holds its TCP connections to the declared ports, and blocks abstract unix sockets and signals outside the sandbox;
  • UDP is held to the declared addresses but not to their ports, and a port declared for one address is open on every declared address;
  • a destination on this machine, a link-local address, or a cloud's metadata service is refused, as written and as resolved.

  A dry run has no network at all, because nobody approved it.

• Memory: no ceiling, and the op goes first. A run may use whatever memory the machine has to spare. It is the first thing stopped when the machine runs short:

  • the kernel, if it must kill, kills the op before anything else;
  • the bastion stops the op when free memory falls to a floor. The floor is the largest of 1 GiB, 5% of memory, and, on a Kubernetes node, the kubelet's own eviction line (hard or soft) plus 512 MiB, so the op goes before any pod is evicted. A kubelet setting it cannot read raises the floor, never lowers it;
  • the bastion also stops the op when the machine's services, pods or users start waiting on memory: 7 points more of the time than the least they had during the run. The op's own waits don't count, and neither does a group that was already waiting, such as a pod at its own limit;
  • a machine already under the floor starts no op;
  • a run counts as stopped only if the kill landed.

  The refusal says what happened and how much the op had used.

• Credentials: it is handed the credentials it declares, sealed by the host to this machine's encryption key and bound to that run, in its environment only. A credential a verb names goes to the verb, never to the program. They are scrubbed from its output and gone when the run ends. A dry run is handed none.

• The builder: an op that declares builder reaches this machine's builder socket in an apply, never in a dry run, and never through a privileged group.

• Root work is done by this bastion, as named verbs the manifest declares with their arguments written in:

  • tree.checkout moves an existing git tree forward to an exact commit from its own origin. It runs only in a tree root owns, whose .git no one else can write, and never writes into a folder another user controls. It never runs the tree's hooks, never overwrites an ignored file the machine keeps, and refuses a tree with local changes or a git config that could run a program.
  • unit.reload and unit.restart act on one systemd service, never the bastion's own.
  • k8s.set_image sets one container's image to a digest, only forward:
    • the digest needs a receipt this machine signed for an image one of its op runs reported, built from the repository the manifest names;
    • its commit must descend from the one behind the live image;
    • the live image's commit counts only if this machine rolled it. An image it did not roll is refused, and the refusal says so.
  • logs.check returns a verdict and one line, read after the apply.

  Only a commit and a digest may come from the run's parameters. The program cannot ask for a verb. An op with verbs is root, so it is never a standing grant.

What a program pushed becomes a receipt, signed by this machine. The heartbeat says whether this machine can run action ops (action_ops) and carries its encryption key, signed by the machine's own key. A run that this bastion's restart cut short leaves nothing: the next start unmounts its files and stops its unit.