| type | Concept | ||
|---|---|---|---|
| title | Cloud and server deployment profile | ||
| okf_status | active | ||
| tags |
|
||
| freshness | 2026-09-30 | ||
| resource | https://github.com/alphazede/bran | ||
| public_boundary | public |
This is the stage-1 contract for issue #28: the smallest safe way to run BRAN on a cloud VM or container host without giving up its local-first, bounded-root, read-only defaults.
BRAN ships a staged profile. Only stage 1 exists.
| Stage | Shape | Status |
|---|---|---|
| 1 | Remote CLI. Operators run the existing headless commands over SSH, a job runner, or an orchestrator. BRAN opens no listening port. | Implemented here |
| 2 | Single-tenant service. An opt-in daemon with a versioned job API. | Not built |
| 3 | Multi-tenant service. | Deferred |
Why remote CLI first:
check,query, andpacketare already deterministic, bounded, read-only, and emit versioned JSON with typed exit codes. A runner that invokes them over SSH gets the same evidence a local user gets.- No listener means no new attack surface. Authentication, transport security, scheduling, retries, and job records stay with systems built for them (SSH, the job runner, systemd, the container runtime).
- Stage 1 persists no BRAN state. Nothing needs backup, migration, or crash recovery beyond the repository mounts BRAN already treats as read-only.
A service is justified only by a workload that needs durable asynchronous jobs or controlled API access that a runner cannot provide. No such use case is stated today, so stage 2 is not built. Its entry conditions are listed in Stage 2 entry conditions. Multi-tenancy stays unavailable until namespace, authorization, storage, and side-channel isolation have their own approved security design.
The default bran binary is unchanged: no listener, no network call, no
new required configuration.
Stage 1 adds one opt-in control. When the environment variable
BRAN_REGISTERED_ROOTS is set, the CLI runs in registered-root mode.
The variable is deployment configuration, set by the operator in the image,
unit, or runner — never by a request.
The value is a list of repository roots separated like PATH (: on
Unix). Each entry must be an absolute path to an existing directory, spelled
exactly as its canonical path: no symlink component, no . or .., no
trailing slash. If any entry fails, every command fails with
registered_roots_invalid (exit 3), including help, --version, and
smoke. An empty value is invalid, so an image can default to empty and fail
closed until the operator registers a root.
In registered-root mode:
- Only
check,query, andpacketrun. Every other command fails withunavailable_in_registered_root_mode(exit 2). That includeshelp,--version,smoke,maintain,evidence,-p,get,tui,agents,doctor, andbody-preserved. query --recordandcheck --policy-stdinfail the same way. The first writes into the repository. The second lets a request replace repository policy.- Every root argument, including each
query --add-dirroot, must equal a registered entry byte for byte. Anything else fails withroot_not_registered(exit 2) before BRAN touches that path. This rejects unregistered roots,..traversal, alternative spellings, and symlink aliases. - Request text for
queryandpacketis limited to 8192 UTF-8 bytes (request_oversized, exit 2). It must also pass BRAN's DLP screen (is_public_dlp_safe), or it fails withrequest_dlp_rejected(exit 2). The screen is substring matching, not a DLP product. It rejects credential assignments such astoken=orpassword:, bearer and prefixed tokens, private keys, and home-directory paths. A legitimate question that contains one of those markers is rejected too. That is the fail-closed trade-off. - Rejections never echo the rejected root or request text.
The scanner already refuses to follow symlinks inside a root, so a link in a registered repository that points outside it contributes nothing.
In registered-root mode, every check, query, and packet envelope for an
admitted root adds provenance.source_revisions, including operation-error
envelopes such as a scanner quota overflow and policy-load errors. It holds
one entry per requested root, in request order: the primary root, then each
--add-dir root. Rejected requests carry no revision.
{"root":"/repos/example","kind":"git-head","status":"attested",
"ref":"refs/heads/main","value":"<full commit id>","reason":null}BRAN reads the commit that the root's git HEAD names from git metadata
directly. It never runs git, so no hook, config, or filter executes. It reads
only these files:
.gitin the root: a directory, or agitdir:file for a linked worktree or submoduleHEADandcommondirin that git directory- for per-worktree refs (
refs/worktree/,refs/bisect/,refs/rewritten/), the loose ref in that git directory; these refs are never packed - for every other ref, the loose ref, then
packed-refs, in the common directory
Every file BRAN reads must resolve, through any symlinks, to a regular file
inside its directory: the root for .git, the git directory for HEAD,
commondir, and per-worktree refs, and the common directory for shared refs
and packed-refs. BRAN resolves the path before opening it and never reads
a file outside that directory. It opens without following a final symlink
and without blocking, and rejects FIFOs, sockets, and devices. Each read is
bounded: 4 KiB per file and 64 MiB for packed-refs. BRAN follows at most
five symbolic refs, counting HEAD, and only names under refs/ without
empty, ., or .. components. value is a full lowercase SHA-1 or SHA-256
object id. ref is null for a detached HEAD.
When BRAN cannot resolve the commit, status is unavailable, value is
null, and reason says why. BRAN never guesses.
reason |
Meaning |
|---|---|
not_a_git_checkout |
The root has no .git |
git_metadata_invalid |
.git is a symlink, not a file or directory, or a malformed gitdir: file; the git or common directory is missing; or commondir is malformed |
git_metadata_unsafe |
HEAD or commondir resolves outside the git directory or is not a regular file (for example a FIFO) |
reftable_unsupported |
The repository uses the reftable ref store |
head_unreadable |
HEAD is missing or cannot be read |
head_corrupt |
HEAD is neither ref: refs/... nor a full object id |
ref_unsafe |
HEAD or a symbolic ref names something outside refs/, or a loose ref or packed-refs resolves outside its directory or is not a regular file |
ref_unresolved |
The branch has no loose or packed ref, for example before the first commit |
ref_corrupt |
A loose ref or its packed-refs line holds no full object id |
ref_unreadable |
A ref file or packed-refs cannot be read |
ref_cycle |
Symbolic refs go deeper than five |
The revision is the commit HEAD named when the request ran. It does not
attest that the files match that commit: uncommitted edits, untracked files,
and concurrent updates are not reflected. BRAN does not open the commit
object, so it does not prove that the object exists. A linked worktree's git
directory lies outside its root. Mount that directory read-only too;
otherwise the revision is unavailable with git_metadata_invalid.
Default mode never reads git metadata and never emits source_revisions.
Apart from that field, a registered-root result is byte-identical to the
default-mode result, and registered-root mode changes no ranking, packet, or
validation result.
| Requirement | Stage-1 mechanism |
|---|---|
| Non-root user, read-only executable | Image user 65532:65532, binary mode 0555; container runs with --read-only; systemd unit uses DynamicUser=yes and ProtectSystem=strict |
| Repositories at explicitly registered roots | Read-only bind mount per repository plus BRAN_REGISTERED_ROOTS |
| Bounded writable volume for BRAN state | Not needed. check, query, and packet write nothing, and registered-root mode refuses every command that writes. Stage 1 mounts no writable volume. |
| Network egress disabled | --network none; PrivateNetwork=yes, IPAddressDeny=any, RestrictAddressFamilies=none |
| Explicit capability configuration for connected agents and adapters | Connected agents (-p) are unavailable in registered-root mode. No database, object-storage, or other network adapter exists. |
| Item, byte, TTL, timeout, cancellation, concurrency limits | Existing scanner limits (10,000 files, 1 MiB per file, 256 MiB total), packet limits, and the request limit above. Timeout, cancellation, and concurrency belong to the runner (TimeoutStartSec=, timeout, job-runner concurrency). |
| No mutation of repositories, Git state, hooks, or host configuration | Read-only mounts, mutating commands refused, ProtectSystem=strict; git metadata is parsed for the source revision, and git is never run |
| No credentials in arguments, bodies, logs, metrics, receipts, or job metadata | Request DLP screen, no echo on rejection, no credential-bearing environment in the image |
deploy/oci/build_image.py builds an OCI
image layout from:
- the exact release archive (
bran-vX.Y.Z-<linux target>.tar.gz), checked against the SHA-256 in the signed release manifest. The release must be bran 0.2.0 or later, the first release with registered-root mode, and its binary must carry the guard's strings (BRAN_REGISTERED_ROOTSandunavailable_in_registered_root_mode). An older binary ignores the registry, sobuildrefuses it andverifyrejects an image holding it. - a base image layout pinned by manifest digest (a glibc runtime base,
because release binaries link glibc dynamically; for example a distroless
ccimage with no shell) - a dependency-license inventory read from
cargo metadata --locked --offlineat the release commit
It adds one uncompressed layer with only /usr/local/bin/bran (mode 0555),
the two licence texts, and the inventory. It writes canonical JSON with
fixed timestamps. The same inputs produce the same image digest on any
host. The image config sets user 65532:65532, entrypoint
/usr/local/bin/bran, no default command, and working directory /. It sets
the environment to only PATH and an empty BRAN_REGISTERED_ROOTS, so the
image fails closed. It declares no exposed ports and no volumes. Labels bind
the BRAN version, source commit, lockfile digest, release-archive digest,
binary digest, and base manifest digest.
build_image.py verify <layout> checks the image deterministically:
- every blob digest and size;
diff_idsagainst the layer bytes - user, entrypoint, working directory, and environment; no default command, exposed ports, or volumes
- the BRAN layer: exact entries, owners, modes, and fixed timestamps, and the binary digest against its label
- the release: version label 0.2.0 or later and the registered-root guard strings in the binary
- every layer: no setuid or setgid bit, no file-capability xattr, no device
node, no world-writable path except sticky directories, and no absolute or
..member name - the licence inventory: every dependency licence expression must be
satisfiable with MIT or Apache-2.0, matching
deny.toml
Base-image licences (for example glibc) belong to the pinned base. The verifier records the base digest and does not claim to have checked them.
Build and run:
python3 deploy/oci/build_image.py build \
--release-archive dist/bran-v0.2.0-x86_64-unknown-linux-gnu.tar.gz \
--release-manifest dist/bran-release-manifest.json \
--base-layout base-oci/ \
--base-manifest-digest sha256:<pinned base manifest digest> \
--out bran-oci/
python3 deploy/oci/build_image.py verify bran-oci/
docker run --rm --read-only --network none --user 65532:65532 \
--cap-drop ALL --security-opt no-new-privileges \
--pids-limit 64 --memory 1g \
--mount type=bind,source=/srv/bran/repos/example,target=/repos/example,readonly \
--env BRAN_REGISTERED_ROOTS=/repos/example \
<image@sha256:digest> packet /repos/example "where is ledger rotation handled"Reference the image by digest, never by tag.
This repository's checks do not build an image on a real base. The base must be pulled over the network by digest, and the gate runs offline. The contract check therefore builds only on a synthetic base. An operator with registry access runs these commands; they were not run here:
skopeo copy --override-os linux --override-arch amd64 \
docker://gcr.io/distroless/cc-debian12@sha256:<pinned digest> oci:base-oci
python3 -c 'import json; print(json.load(open("base-oci/index.json"))["manifests"][0]["digest"])'
python3 deploy/oci/build_image.py build \
--release-archive dist/bran-v0.2.0-x86_64-unknown-linux-gnu.tar.gz \
--release-manifest dist/bran-release-manifest.json \
--base-layout base-oci/ \
--base-manifest-digest <digest printed above> \
--out bran-oci/
python3 deploy/oci/build_image.py verify bran-oci/
skopeo copy oci:bran-oci docker-daemon:bran:0.2.0Pin the platform manifest digest that index.json lists, not a
multi-platform index digest. build rejects any other digest. Review the
base image's licence notices before first use.
deploy/systemd/bran-check@.service
is a hardened oneshot template. systemctl start bran-check@example runs
bran check /srv/bran/repos/example bran-strict with a dynamic user,
network isolation, an empty capability set, and a read-only view in which
/srv/bran/repos shows only the one instance repository. Instance names are
repository directory names ([a-z0-9-]+).
To check the unit offline before installing it, replace the binary path with
a stand-in that exists, because systemd-analyze verify checks that
ExecStart is executable, and verify it under an instance name:
work=$(mktemp -d)
sed 's#/usr/local/bin/bran#/usr/bin/true#' deploy/systemd/bran-check@.service \
> "$work/bran-check@.service"
systemd-analyze verify "$work/bran-check@example.service"
systemd-analyze security --offline=yes "$work/bran-check@example.service"
rm -r "$work"Ad-hoc query and packet runs use the same properties through
systemd-run:
systemd-run --pipe --wait --collect \
-p DynamicUser=yes -p PrivateNetwork=yes -p IPAddressDeny=any \
-p RestrictAddressFamilies=none -p CapabilityBoundingSet= \
-p NoNewPrivileges=yes -p ProtectSystem=strict -p ProtectHome=yes \
-p TemporaryFileSystem=/srv/bran/repos:ro \
-p BindReadOnlyPaths=/srv/bran/repos/example \
-p Environment=BRAN_REGISTERED_ROOTS=/srv/bran/repos/example \
-p RuntimeMaxSec=300 \
/usr/local/bin/bran query /srv/bran/repos/example "ledger rotation"-
Liveness does not apply. Stage 1 runs no long-lived process, and registered-root mode refuses
smoke,help, and--version. -
Readiness: run
bran query <registered root> readinessfor each registered root, with the sameBRAN_REGISTERED_ROOTSas real requests. The exit code alone is not enough: a root without native policy exits 0 with statusunavailable, and a skipped oversized file exits 0 with a warning. The root is ready only when all of these hold:- the exit code is 0
- the envelope
statusisok, which means native policy loaded failuresis empty- every warning is either
unmatched_query_terms: readinessor a skipped in-repository symlink (Symlink { ... }). AnOversizedInput,Unreadable, or any other warning means BRAN could not see the whole repository.
A repository over the file or byte quota fails with exit 3 and
LimitExceeded. For example, withjq:bran query "$root" readiness > ready.json 2>&1; code=$? [ "$code" -eq 0 ] && jq -e '.status == "ok" and .failures == [] and all(.warnings[]; startswith("unmatched_query_terms:") or startswith("Symlink {"))' \ ready.json > /dev/null
-
Validation:
bran check <registered root> <profile>, as in the systemd unit. Exit 1 means the repository fails validation.checkreads only knowledge documents, so it does not prove the whole repository fits the scanner quotas. -
There is no state store or network adapter in stage 1, so neither can be unavailable.
A stage-1 invocation is one process. It prints its envelope only after the
command completes. On SIGTERM or SIGKILL, it exits by signal and leaves
nothing behind, because it writes nothing. The runner must treat only exit
status 0 or 1 plus a complete JSON envelope as a result. Any other outcome,
including a truncated stdout, is a failed run. There is no in-flight job
store to cancel or recover.
Stage 1 owns no persistent state. Back up the repositories and the
deployment configuration: the image digest, the unit or runner definition,
and the registered-root list. Restore is redeploying those. Do not back up
.bran/cache or .bran/results from a stage-1 host, because stage 1 never
writes them.
Record this tuple for every deployment:
| Field | Source |
|---|---|
| Image digest | sha256: digest of the manifest build_image.py prints |
| BRAN version and source commit | org.opencontainers.image.version and .revision labels; on a VM, bran --version run without BRAN_REGISTERED_ROOTS |
| Release-archive and binary digests | Image labels; release manifest |
| Envelope schema version | schema_version in every envelope, for example the readiness query |
| Repository policy schema | schema_version in each repository's .bran/policy.yaml |
| Stored-state schema | None in stage 1 |
Upgrade: build and verify the new image, run readiness against each registered root, then switch the runner to the new digest. Roll back by switching back to the recorded previous digest. Stage 1 has no stored state to migrate or downgrade. A future stage that stores state must version it and refuse to start on an unknown stored-state version. Rolling back across a stored-state migration then requires restoring the pre-upgrade backup.
| Asset | Threat | Control |
|---|---|---|
| Host filesystem | A request names a path outside the approved repositories | Registered-root exact match before any file access; container and unit see only mounted repositories |
| Repository contents | A request mutates a repository, Git state, or hooks | Read-only mounts; mutating commands refused in registered-root mode |
| Repository contents | A symlink inside a repository points at host files | The scanner does not follow symlinks |
| Repository metadata | Reading the source revision runs a repository's git hooks, config, or filters, reads host files through symlinks, or hangs on a FIFO | BRAN parses HEAD, commondir, and refs itself and never runs git. It reads only regular files that resolve inside their git directory, without blocking, with bounded reads. It emits only full object ids, safe refs/ names, and fixed reason codes |
| Credentials | A credential passed in a request is echoed into output or logs | DLP screen rejects the request without echo; the image holds no credentials; errors never echo roots or request text |
| Network | BRAN is used for exfiltration or as a pivot | No listener or socket API in the workspace sources, no network crate in Cargo.lock, --network none or PrivateNetwork=yes |
| Host resources | A large repository or request exhausts memory or time | Scanner and packet limits, request limit, runner timeouts, and container or unit memory and task limits |
| Image supply chain | A tampered binary or base | Release manifest digest check, pinned base digest, deterministic build, verify |
| Privilege | Escalation inside the container | Non-root user, --cap-drop ALL, no-new-privileges, no setuid, setgid, or file-capability files |
Out of scope in stage 1: authentication and transport security (SSH or the runner owns them), tenant isolation beyond one registry per process, and side channels between co-located containers.
- Image referenced by digest;
build_image.py verifypassed on it. - Base image pinned by manifest digest, with a reviewed licence notice.
- Each repository mounted read-only at its own path and listed in
BRAN_REGISTERED_ROOTSwith its exact canonical spelling. - Nothing else from the host is mounted. No writable volume is mounted.
- Container:
--read-only --network none --user 65532:65532 --cap-drop ALL --security-opt no-new-privilegesplus memory and PID limits. Unit:deploy/systemd/bran-check@.serviceproperties. - No credentials in the image, unit, environment, or arguments.
- Runner enforces a timeout and treats only exit 0 or 1 with a complete envelope as a result.
- Readiness rule passes for each root after every upgrade.
- Deployment tuple recorded for rollback.
- Authentication. Delegated. SSH, the job runner, or the orchestrator authenticates the operator. BRAN implements none in stage 1.
- Network egress. None. No stage-1 command needs it.
- Repository registration and tenant ownership. Registration is
deployment configuration (
BRAN_REGISTERED_ROOTSplus mounts). One process or container serves one tenant. Separate tenants use separate containers or units. - Retention and encryption. Stage 1 retains nothing. Results go to the runner, which owns retention and encryption.
- Audit evidence. The runner records the deployment tuple, the
invocation (command, registered root, exit status), and the SHA-256 of the
envelope. The request text may be recorded only under the runner's own
data policy. BRAN envelopes carry controls, limits, selected locators,
derivation (
why_selected, rankings), DLP status, and in registered-root mode the source revision of each root. BRAN does not log. - Resource limits. BRAN enforces scanner, packet, and request limits. CPU, memory, PIDs, and wall time are container or unit limits. BRAN has no decompression or model workloads in stage 1.
Build a single-tenant service only after an owner-approved use case needs
durable asynchronous jobs or API access a runner cannot give. It must then
meet the issue's service boundary: loopback or private bind, TLS at the
service or a trusted ingress, short-lived identities or credential
references, per-operation authorization against the registry, versioned
schemas, idempotency keys, cancellable and quota-bounded jobs, opaque
identifiers, separate liveness and readiness, content-free metrics, and an
audit receipt. Job and result state starts on BRAN's bounded local result
store (.bran/results: 16 entries, 4 MiB total, 1 MiB per item, 24-hour
TTL, staged writes whose leftovers are discarded on the next open). Any
database-backed state follows the EvidenceSource/StateStore separation in
issue #27. Kubernetes, Helm,
autoscaling, and a hosted control plane wait for a stable single-node
contract. Provider-specific infrastructure stays outside bran-core, which
keeps zero dependencies.
| Criterion | Status | Evidence |
|---|---|---|
| Design document chooses a shape and explains why | Done | Decision |
| Default binary opens no listener and makes no network call | Done | tools/ci/deployment_contract_check.py (no socket API in crates/, no network crate in Cargo.lock); p8_deployment_profile traces check, query, and packet for socket calls when strace is installed |
| Smoke test runs check, query, and packet against a mounted synthetic repository | Done for stage 1 | p8_deployment_profile: registered, read-only synthetic repository, cleared environment, read-only working directory, repository digest unchanged |
| Negative tests | Partial | p8_deployment_profile covers unregistered roots, path traversal, symlink escape (root alias, registry entry, in-repository link), cross-namespace access (a root registered to another process), oversized requests, quota overflow (a repository over the 10,000-file scanner quota fails with exit 3), and secret reflection. registered_mode_admits_only_check_query_packet checks that an empty or invalid registry refuses every command, including help, --version, and smoke. readiness_rule_rejects_policy_and_quota_gaps checks that the readiness rule rejects a root without native policy, an oversized file, and a quota overflow. Not done: expired authentication, because stage 1 has no BRAN authentication (SSH or the runner authenticates). Cancellation races are also not done for stage 1: it has no BRAN cancellation interface, and the runner ends the process. The connected cancel-versus-publish race is covered by the existing p3_headless_cli_and_maintain_lifecycle. |
| Restart recovery never reports a partial job as successful | Partial | Stage 1 has no BRAN job state, and exit status is authoritative. The bounded result store discards staged writes on the next open and keeps prior results when publication fails (existing p3_headless_cli_and_maintain_lifecycle). Job records are stage 2. |
| Results retain source revision, packet, DLP, derivation, and storage provenance | Done for stage 1 | Source revision, added in registered-root mode by owner decision of 2026-09-30. p8_source_revision covers a loose-ref checkout, detached HEAD (SHA-1 and SHA-256), packed ref, linked worktree (absolute and relative gitdir:), non-git root, and corrupt, unsafe, unresolved, cyclic, and reftable metadata. It also cross-checks loose, packed, worktree, and detached results against real git. git_metadata_symlinks_stay_confined, git_metadata_fifos_never_block, and worktree_local_refs_resolve_in_worktree_git_dir cover outside symlinks, FIFOs, and per-worktree refs, with a real-git cross-check. registered_revision_is_confined_and_never_blocks and error_envelopes_keep_source_revisions cover the same through the CLI. p8_deployment_profile checks an attested revision through the CLI for a real git checkout and unavailable for a non-git root. It also checks packet, DLP, and derivation fields, and that the output is byte-identical to default mode apart from source_revisions. Storage provenance does not apply: stage 1 stores nothing. |
| OCI image contents, user, entrypoint, ports, writable paths, capabilities, and licences verified deterministically | Partial | deployment_contract_check.py builds twice from a synthetic base and archive, compares digests, and checks that verify rejects each contract violation. It also checks that build refuses, and verify rejects, a release before 0.2.0 or a binary without the registered-root guard. Not done: no image on a real base has been built or verified. That needs a network pull of a digest-pinned base image, and this repository's checks run offline. By owner decision of 2026-09-30 this stays not done. The operator commands are in Building on a real base. |
| Server can use the bounded local state store first; database state follows #27 | Done by design | Stage 1 stores nothing; Stage 2 entry conditions |
| Upgrade and rollback path binds image digest, version, schema versions, and state migration | Done | Upgrade and rollback; image labels |
| Hosted-provider infrastructure optional and outside the portable core | Done | deployment_contract_check.py checks that bran-core has no dependencies; nothing provider-specific ships |