content_dist

How it works

content_dist moves files onto and off an endpoint without a shell. stage downloads a file into the agent’s own staging directory (<agent.data_dir>/staged, owner-only on POSIX) over a socket the agent opens itself, hashes it, and keeps it only if the SHA-256 equals the sha256 the caller supplied; a match also records that hash in the agent’s key-value store under staged_hash:<filename>. execute_staged takes a file name, optional args and an optional expected_hash drift check, and no hash for authorisation: it reads the recorded hash back, hashes the file again, refuses on any difference, then runs the file directly (no shell) with a fixed 30-minute deadline and reports its exit code and combined output. list_staged and cleanup are plain directory walks of the staging directory; cleanup deletes files older than hours (default 24) and drops their recorded hash. upload_file is a separate path: it sends one local file to the Yuzu server’s upload endpoint in chunks, using a one-time grant minted by an operator, and reports the size and SHA-256 the server confirmed.

Deliberately not: a shell, because no action invokes /bin/sh, cmd.exe or an interpreter, and downloads and uploads are direct socket clients. Not a general file manager either: stage, execute_staged, list_staged and cleanup only touch the staging directory. upload_file is the exception, because it reads the local path you give it (anywhere the agent can read, unless base_dir restricts it) and talks only to the agent’s own configured server address, never an address supplied in the call.

flowchart LR
  OP["Operator, workflow or the /auto Deploy engine"] --> SRV["Server: authz per action - SoftwareDeployment, Execution or FileRetrieval"]
  SRV -->|"gRPC mTLS"| HOST["Agent plugin host"] --> EX["content_dist.execute"]
  EX --> WIN["Windows leg: httplib_tls, subprocess_runner:staged_payload, std_filesystem"]
  EX --> MAC["macOS leg: httplib_tls, subprocess_runner:staged_payload, std_filesystem"]
  EX --> LIN["Linux leg: httplib_tls, subprocess_runner:staged_payload (native only), std_filesystem"]
  WIN & MAC & LIN --> ROWS["pipe rows, typed result status on execute_staged only"]
  ROWS -->|"CommandResponse"| RS[("ResponseStore")]
  RS --> API["REST /api/responses and the /auto Deploy engine"]

What you can decide with it

Per OS: all five actions work on Windows, macOS and Linux. On Windows, stage and upload_file need the agent to have been built with OpenSSL; without it HTTPS fails with an error row. On Linux, execute_staged refuses files that start with #!, so stage a native executable. Nothing here returns a permission-denied status: a filesystem or network failure is an error|... row.

A successful stage proves the bytes match the hash the caller gave, which is only as good as that hash. It says nothing about who built the file, because no code signature is checked.

The trust chain for execute_staged

1. The hash you pass to stage is the root of trust. The URL, the network path and a plain http:// source are not trusted; the hash is the only integrity check on the download.
2. stage keeps the file only if its SHA-256 equals that hash, then stores the hash in the agent’s key-value store, a separate database outside the staging directory.
3. execute_staged ignores any hash in the call for authorisation. It reads the recorded hash from the key-value store, hashes the file on disk again, and refuses if there is no record or the two differ. A file dropped into the staging directory by anything other than stage has no record and does not run.
4. The optional expected_hash parameter is only a drift check: it must equal the recorded hash or the call fails, and it can never authorise anything the record does not.
5. On Linux the file is then run from the descriptor the runner opened, pinned to its verified size. A small window between the hash check and that open remains (Caveat 3).
6. What is not covered: anyone who can act as the agent account can rewrite both the file and the stored hash, and the plugin does not verify a vendor signature.

Diagrams

stage, then execute_staged

sequenceDiagram
  participant Op as Operator or Deploy engine
  participant Ag as content_dist
  participant Src as Download server
  participant KV as Agent key-value store
  participant Dir as Staging directory
  Op->>Ag: stage with url, filename, sha256
  Ag->>Src: GET url
  Src-->>Ag: file bytes
  Ag->>Dir: write the file
  Note over Ag: hash the file on disk
  alt hash differs
    Ag->>Dir: delete the file
    Ag-->>Op: error, hash mismatch
  else hash matches
    Ag->>KV: store staged_hash for the filename
    Ag-->>Op: status ok and staged_path
  end
  Op->>Ag: execute_staged with filename and args
  Ag->>KV: read staged_hash
  Ag->>Dir: hash the file again
  Note over Ag: refuse if no record or the hash differs
  Note over Ag: Linux rejects shebang files, args are checked, POSIX sets mode 0700
  Ag->>Ag: run the file directly, 30 minute deadline
  Ag-->>Op: status, exit_code, output

The download is only trusted after its hash matches the one you supplied, and the run is only allowed against the hash recorded at that moment. The run uses the agent’s own identity and environment, with loader variables such as LD_* and DYLD_* removed on POSIX.

upload_file

sequenceDiagram
  participant Op as Operator
  participant Ag as content_dist
  participant Srv as Yuzu server upload endpoint
  Op->>Ag: upload_file with path, grant_id, grant_secret
  Note over Ag: check path, base_dir and size limit locally
  Ag->>Srv: POST /api/v1/uploads with the grant
  Srv-->>Ag: 201 with upload_id, session secret, chunk size, offset
  loop each chunk
    Ag->>Srv: PUT chunk with Content-Range
    Srv-->>Ag: 200 with the acknowledged offset
    Note over Ag: hash the bytes just acknowledged
  end
  Ag->>Srv: POST commit with the computed sha256
  Srv-->>Ag: 200 with actual size and sha256
  Note over Ag: size and hash must equal what was sent
  Ag-->>Op: status ok, sha256, size, upload_id
  Note over Ag,Srv: most failures after the session opens send a DELETE to cancel

The grant is minted beforehand by an operator through the upload-grants API and is single use. The agent checks the file locally (regular file, resolved path inside base_dir if given, not larger than max_size_mb, default 100, at most 1000), retries transient failures with backoff, resumes from the server’s acknowledged offset, and hashes the exact bytes the server acknowledged, so a file that changes mid-upload yields the hash of what was sent. The connection is TLS only, with certificate verification, to agent.server_web_url.

OS capability

Declared limits per leg (descriptor fallback text, verbatim):

• execute_staged / Linux — shebang-interpreted (#!) staged payloads are rejected — B6 fd-exec (execveat O_CLOEXEC) is incompatible with the kernel’s binfmt_script re-open; native executables only
• stage / Windows — requires OpenSSL to be found at build time; HTTPS unavailable if absent
• upload_file / Windows — requires OpenSSL to be found at build time; HTTPS unavailable if absent

Privileges and prerequisites

Binaries, subprocesses and network: stage and upload_file open raw TCP/TLS sockets through cpp-httplib (no subprocess). execute_staged spawns exactly one process, the staged file itself, through yuzu::agent::run_bounded_subprocess (no shell, no other binary), and that child inherits the agent’s environment. list_staged and cleanup touch no network and spawn nothing.

Data contract

Inputs

Outputs

Every action writes independent key|value lines via ctx.write_output — not a fixed-width pipe row like a collector’s table. A validation or transport failure typically replaces the whole declared line set with a single unstructured error|<message> line rather than filling the declared columns with a placeholder value; there is no --for-unknown convention in this plugin. execute_staged on POSIX can also emit a warn|failed to set execute permission on staged file: ... line before the run when the 0700 chmod fails; the run then proceeds and fails with its own error.

agent.content_dist.cleanup — status|files_removed

agent.content_dist.execute_staged — status|exit_code|output

agent.content_dist.list_staged — file|size|sha256

agent.content_dist.stage — status|staged_path

agent.content_dist.upload_file — status|sha256|size|upload_id

Result status

execute_staged’s ordinary exit (rc 0 or nonzero) sets no typed status at all, because the runner’s failure classifier (classify_runner_failure) reports nothing for a normal exit by design; the status and exit_code lines carry the outcome. stage, list_staged, cleanup and upload_file never call set_result_status, so the agent records UNDECLARED for them. The samples below only exercise parameter validation and an empty staging directory, so none shows a typed status.

Where the data goes

• Instruction result, and the /auto Deploy engine. Rows travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore. stage and execute_staged are also dispatched by the /auto Deploy engine (server/core/src/deployment_engine.cpp), which parses this wire contract through server/core/src/deployment_parse.hpp to drive its own per-device state machine, so that surface needed no extra agent code.
• upload_file’s grant_id and grant_secret are redacted before any persisted audit or history copy (server/core/src/sensitive_instruction_params.hpp); the server keeps only a hash of the grant secret in the upload store.
• Not consumed by daily-sync inventory, the Echo warehouse, DEX or metrics.
• Sensitivity. execute_staged’s output line is the combined stdout and stderr of whatever program was staged and run, so it can carry anything that process prints, including usernames, hostnames or credentials. The plugin’s own declared columns (staged_path, file, sha256, upload_id) carry only caller-chosen filenames and content hashes. upload_file moves the whole content of the named file off the device, so the sensitivity of that data is the file’s own.
• Siblings: none in this catalogue. execute_staged is the only “run a verified binary” action here; compare script_exec.exec for ad hoc admin commands and scripts.
• MCP / REST. Discover: discover_plugins (summary) then yuzu://plugin-docs (this page as data) then discover_instructions / get_definition("agent.content_dist.execute_staged"). Run: execute_instruction {definition_id, parameters}. Read: /api/responses/{id}; stage and execute_staged results are also polled by the /auto Deploy engine’s deployment_run_store.

Sample output

Windows — captured: windows Microsoft Windows NT 10.0.26200.0 x64 · bare-metal · 2026-09-07 · SYSTEM · leg-hash 590399d7174c

== action=stage
error|missing required parameters: url, filename, sha256
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=execute_staged
error|missing required parameter: filename
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=list_staged
count|0
[result_status] UNDECLARED / UNKNOWN

== action=cleanup
[not captured] Destructive/Irreversible: not executed on a live host

== action=upload_file
error|missing required parameters: path, grant_id, grant_secret
[result_status] UNDECLARED / UNKNOWN
[rc] 1

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-09-07 · euid 501 (jsmith) · leg-hash 590399d7174c

== action=stage
error|missing required parameters: url, filename, sha256
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=execute_staged
error|missing required parameter: filename
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=list_staged
count|0
[result_status] UNDECLARED / UNKNOWN

== action=cleanup
[not captured] Destructive/Irreversible: not executed on a live host

== action=upload_file
error|missing required parameters: path, grant_id, grant_secret
[result_status] UNDECLARED / UNKNOWN
[rc] 1

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-09-06 · euid 0 · leg-hash 590399d7174c

== action=stage
error|missing required parameters: url, filename, sha256
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=execute_staged
error|missing required parameter: filename
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=list_staged
count|0
[result_status] UNDECLARED / UNKNOWN

== action=cleanup
[not captured] Destructive/Irreversible: not executed on a live host

== action=upload_file
error|missing required parameters: path, grant_id, grant_secret
[result_status] UNDECLARED / UNKNOWN
[rc] 1

Caveats and known gaps

1. cleanup ignores filename, and its declared columns do not match its output. do_cleanup reads only hours and sweeps the whole staging directory by age (default 24; 0 or less removes everything), so removing a single file is not possible. The declared status column is never emitted, an unparseable hours silently falls back to 24, and the declared files_removed is actually written as removed|<n>.
2. execute_staged rejects Linux shebang scripts by design; do not “fix” this. The Linux runner executes the already-opened, verified file descriptor (the Linux execveat system call with an empty path), which gives the kernel no path to build an interpreter command line from, so a #! file is refused up front instead of failing opaquely. Stage a native executable instead.
3. A small window between the hash check and the exec is accepted, not closed. The key-value hash check and the runner’s own open of the file target the same path but not the same descriptor, and closing it needs the runner to accept a caller-supplied digest. The staging directory is owner-only, so exploiting the window already requires the agent’s own identity, and the runner pins the executed descriptor to the verified size.
4. Termination grace differs by OS. On Linux and macOS a deadline or cancel sends SIGTERM to the process group and waits 30 seconds before the hard kill. On Windows the child has no console (CREATE_NO_WINDOW), so a soft stop cannot reach it and the grace is zeroed: a deadline or cancel is an immediate hard kill, which can interrupt an installer mid-transaction.
5. The hash you supply is the only integrity control on a download. stage accepts plain http:// sources, does not follow redirects, applies no size cap to the download, and does not check a code signature, so a wrong or attacker-chosen hash makes a wrong file trusted. Samples exercise only parameter validation, so stage, execute_staged and upload_file have no successful capture, and cleanup is not captured although it only touches the plugin’s own staging directory.

Source and tests

• Plugin: agents/plugins/content_dist/src/content_dist_exec_parsers.hpp · agents/plugins/content_dist/src/content_dist_exec_seam.hpp · agents/plugins/content_dist/src/content_dist_plugin.cpp · agents/plugins/content_dist/src/content_dist_upload_parsers.hpp
• Definitions: content/definitions/content_dist.yaml · content/definitions/t2_capabilities.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_content_dist.hpp
• Tests: tests/unit/test_content_dist_actions.cpp · tests/unit/test_content_dist_exec_parsers.cpp · tests/unit/test_content_dist_exec_seam.cpp · tests/unit/test_content_dist_exec_seam_win.cpp · tests/unit/test_content_dist_upload_parsers.cpp
• Privilege row: docs/agent-privilege-model.md