Skip to content

Reference

Trust boundary and state provenance

See what a value from a cloned repository can decide and what each machine has to confirm.

What comes from the clone does not decide execution

Running Orkastery in a third-party repository does not execute code just because of that. A value that comes from the clone does not become a process option, an executable or a path outside the root; the only commands run by design are the declared ones.

The trust boundary is the audit of every process call and every path the core builds with data from the clone, with the class of each one and no exploitation recipe. The full matrix, module by module, is in the source.

In version 0.6.10, the audit fixes and the state provenance rules ship, the latter as a security patch, by the owner’s decision.

What the core trusts

The command line belongs to whoever is at the keyboard: it is trusted, but validated when it goes to git, as with --remoto, --para, --de and thread ids. The environment and the account folders (~/.orkastery, ~/.claude and ~/.codex) are trusted too.

Not trusted: the versioned manifest and setup (orkastery.yaml and orkastery.setup.json), state versioned in the clone (.orkastery and the .ork-ci/<thread>.json bundles), the state branches (ork/roadmap-reservas, the factory’s and the ork/* ones) and whatever comes from another machine in the network (snapshots, reservations and the roadmap frontmatter). Tool output (git, runtime) is data, never code.

Every process call and every path in the matrix gets one of these classes. Every process call in the core uses an argument vector, without a shell; a shell exists only in the declared commands and in the MCP sandbox probe.

  • Declared: a command that the manifest or a claim declares to run. It is the product (re-running what is claimed), and SECURITY.md documents it.
  • Inert: constants only, or trusted data.
  • Defended: external data, but validated, placed after --end-of-options, with a qualified ref or a checked sha.
  • Fixed: it was option injection, an executable chosen by the clone or a path outside the root.
  • Fixed by owner decision: it closes a pending item by changing behavior, and the owner chose to merge it as a security patch.
  • Pending with the owner: closing it means changing behavior that is documented or accepted today, and the decision belongs to the owner.

Declared commands

They are the only ones the core runs by design, and SECURITY.md lists them all. The documentation promises no runtime warning: treat the orkastery.yaml and the state of a third-party repository like a Makefile.

ork doctor, ork board, ork thread list, ork init, ork thread new and ork retry plan do not run declared commands.

  • verify.build, verify.test, verify.typecheck and verify.preparo, in the worktree, through ork verify, ork fix open, ork fix reverify, ork retry run (in the corrigir-dirigido action), the baseline of ork phase run and the gate of ork ship.
  • ci.command and the .ork-ci/<thread>.json bundle, in ork ci run on the CI runner.
  • Claims (claims.jsonl and --verificar) and the doneWhen in thread.json, in the same commands as verify; ork claims add runs them only with the manifest policy.
  • GO-FIX corrections and the claims of audit findings (board.jsonl), in ork fix reverify and in the check of an audit round.
  • The runtime binary (claude and codex), through the adapters, in ork phase run and ork retry run.
ork verify <thread>
ork fix reverify <thread>
ork audit verify <rodada>
ork ci run --branch <branch>

The five provenance rules

In version 0.6.10, five rules (P1 to P5) close the items the audit left pending with the owner. The idea is the same in all of them: what comes with the repository does not decide the executable, a path outside the root or what this machine publishes; when the use is legitimate, the machine confirms outside git, and the refusal is typed and names the command.

  • Sandbox posture (P1): a runtime.sandbox that gives the agent full access (danger-full-access) only dispatches through Codex after ork setup sandbox confirmar <postura>, stored in .orkastery/private/postura-local.json (0600, outside git, for this checkout only). Without it, ork phase run and ork retry run refuse with runtime.sandbox-nao-confirmado, and ork doctor reports it.
  • Tracked state (P2): versioned .orkastery state does not choose the cwd, the worktree or the executable (estado.rastreado). A cwd that comes from thread.json, the ledger or the queue, for the agent or for git, only counts at the project root or in a worktree the repository has registered (estado.worktree-nao-registrada). This covers dispatch, resume, verify, claims, GO-FIX, the GO proof, handoff, liveness, ork ci prepare, ork worktree audit and ork worktree release.
  • Pulse and digest transport (P2): only the local pulse-host.json and master-host.json count, regular files not tracked by git (transporte.rastreado).
  • Recall and handoff pointers (P2): ork recall, ork handoff recall and ork handoff export only read a file that, by its real path, sits at the project root or in the thread’s registered worktree. Recall refuses with ponteiro.fora-da-raiz, and export no longer points outside.
  • Worktree folder (P3): a worktree.dir that leads outside the root by its real path (absolute path, parent directory, a link in the path or .git) only creates a worktree after ork setup worktree confirmar, stored in .orkastery/private/worktree-local.json (0600, outside git, for this checkout and this folder only). Without it, creation refuses with worktree.dir-fora-da-raiz, and ork doctor reports it. Existing worktrees keep working, and the MCP still refuses a worktree outside the root.
  • Eval (P4): ork eval only runs the catalog (behavior scenarios, hooks and core/dist) of the package that is running. A directory with skills, references and eval folders found from the cwd that is not the package’s own refuses with eval.catalogo-alheio, and the message says how to run that checkout’s eval on purpose. The kit’s CI, with node core/dist/index.js eval at the root, does not change.
  • Shared factory (P5): fabrica.compartilhada: true in the manifest no longer turns on publishing this machine’s snapshot (threads, name and host) to the clone’s remote, nor reading the other machines. Only the machine’s own membership does: ork fabrica entrar, in ~/.orkastery/maquina.json, or ORK_FABRICA_COMPARTILHADA=1. With the request in the manifest and no membership, ork doctor and ork fabrica warn with fabrica.nao-confirmada.
ork setup sandbox confirmar danger-full-access
ork setup worktree confirmar
ork fabrica entrar
ork doctor
git rm -r --cached .orkastery

What the audit fixed

In version 0.6.10, the audit fixes these cases without changing accepted behavior:

  • The mergeSha and the target branch of a ship_done in the ledger only reach the git log of the revert detection as a hexadecimal sha and a branch name, after --end-of-options; before, a ledger versioned in the clone passed an option to git, in ork master and ork ship.
  • ork docs sincronizar no longer falls back to the raw manifest base when it does not resolve, and, from the ledger sha and the frontmatter commit, only a hexadecimal sha reaches git.
  • The manifest refuses a worktree.base_branch that is not a valid branch name for git (it starts with a hyphen or contains ..).
  • The manifest refuses a relative memory.cli: it accepts a name looked up in PATH, like orkmind, or an absolute path. The OrkMind probe, including the one in ork doctor, ignores relative PATH entries and a shebang with a relative interpreter, and ork brain runs the executable with its cwd in $HOME, not at the clone root.
  • .orkastery, .orkastery/threads and a thread folder as a symbolic link refuse with estado.link, and appends to the ledger, claims and board use O_NOFOLLOW; before, a versioned link sent the write outside the root.
  • The id of an audit round read from run.json must be a simple name (audit.rodada-invalida).
  • SECURITY.md now lists every declared command, including verify.preparo, ci.command, the .ork-ci/<thread>.json bundles and doneWhen.

Private data barrier and DSN outside the environment

In version 0.6.10, the private data barrier is a core command: ork privado varrer looks for home paths, email outside the allowed list, hostnames in machine format and the terms of the local list, which stays outside git. Exceptions in orkastery.privado.json require an exact pattern and value, without wildcards, with the path only as a filter and a required reason. The report states file, line, column and pattern, never the value, and masks the name of a file with a finding.

With the dado_privado policy in the manifest, ork verify scans the thread diff and fails with policy.violation in block, and ork ci prepare refuses to write the bundle when there is a finding. In the core CI, the scan is a step of the documentacao job. The local list is only read as a regular file of the current user, without a link and with 0600 permissions; when absent, as in CI, only the generic patterns run, and the output says so.

The memory DSN gains a source outside the agents’ environment: memory.database_url_file points to ~/.orkastery/segredos/<nome>, and the manifest cannot choose a file outside that folder. The two sources are exclusive, so ork never falls back from one to the other. Before opening, it checks with lstat every folder between the home and the secrets folder, opens with O_NOFOLLOW and requires a regular file of the user running ork, with exact 0600 or 0400 permissions, up to 4 KiB and a single line with the DSN.

A child process response that repeats the DSN or its password is refused whole, with memory.transport.secret, brain.transport.secret or brain.migration.secret, without the value. The limit is stated honestly: the agent runs as the owner’s user and can read a 0600 file of theirs. The gain is the password out of env, the transcript and the model context; strong isolation needs another user or an intermediary.

ork privado varrer
ork privado varrer --base origin/main
ork memory status

What remains with the owner

The audit left six items pending with the owner, because closing them changed accepted or documented behavior. The first five, P1 to P5, got the provenance rules on this page, merged by the owner’s decision. P6 remains pending.

On the same list, these remain recorded, with low risk:

  • ork retry run --dry-run, in the corrigir-dirigido action, re-runs claims and verify: they are declared commands, but this goes against the meaning of --dry-run.
  • The runtime profile recorded in the ledger chooses the CLAUDE_CONFIG_DIR and the CODEX_HOME of query commands.
  • P6: the manifest’s memory.cli can be any name on PATH or an absolute path, including inside the clone, and memory.database_url_env names any environment variable. The value reaches the Brain executable on every query, and the file source memory.database_url_file only accepts ork’s secrets folder, so the class does not widen.
  • ci.external_repositories accepts a parent-directory segment in the path of a read through the GitHub API.
  • ork adapter install still finds the catalog from the project, as ork eval used to, but only copies the adapter into the project itself and prefers the executable on PATH when there is one.

For core contributors

Rules for code in core/src:

  • A value from the clone on its way to git: validate it before the call with remotoValido or exigirRemoto, branchValida or shaValido (core/src/branch-de-estado.ts), and put --end-of-options before it.
  • A branch ref goes fully qualified, and a merge goes by the checked sha, never by name.
  • An executable never comes from the manifest through a relative path, and the cwd of an executable chosen by configuration is not the clone root.
  • A path with an id read from a file has a single segment, checked by regex, and the state directory is not a link.
  • Appends to state use O_NOFOLLOW; a whole-file write goes through a temporary file created with wx and then renamed.
  • A path read from a pointer stored in state is checked by its real path with exigirCaminhoContido (core/src/procedencia.ts). A decision the manifest cannot take alone becomes a local confirmation in .orkastery/private, with lerArquivoPrivado and gravarArquivoPrivado (core/src/postura-local.ts).
  • The fix’s test fails the previous code; the reference tests are core/test/fronteira-de-confianca.test.ts, core/test/procedencia-e-postura.test.ts and core/test/fronteira-pendentes.test.ts.