grpc_exec: optional execution-environment commitment field in ExecuteResponse for downstream audit consumers

[tomjwxf]

Filing as a tight scope-check question before any PR. Not sandbox-adjacent: this is about the grpc_exec response shape specifically.

Context

Downstream audit systems consuming grpc_exec output (compliance logs, signed-receipt emitters, transparency logs) need to bind a specific execution to the environment it ran in, not just the command and exit code. Today ExecuteResponse returns stdout/stderr/exit status. A consumer that wants to answer the question "which sandbox config and which binary version produced this output?" has to fetch the config separately and trust that nothing changed in between.

One tiny field closes that gap: an optional commitment to the execution environment, computed server-side at the moment of execution.

Proposed shape

Add an optional environment_commitment field to ExecuteResponse (or the appropriate existing message):

message ExecuteResponse {
  // ... existing fields ...

  // Opaque byte string committing to the execution environment that
  // produced this response (sandbox config hash, binary build ID,
  // policy hash, or any composition the server chooses). Stable for a
  // given deployment; a client consuming the commitment verifies
  // against a reference value out-of-band.
  optional bytes environment_commitment = N;
}

Concretely: SHA-256 over a canonical serialization of whatever subset of (sandbox manifest, binary hash, command_filter rule set, runtime version) the grpc_exec server considers authoritative. The field is deliberately opaque to downstream consumers; the semantic is "this server-defined value identifies the execution environment at response time."

What this enables

A downstream audit system can include the commitment in its own signed record, giving a verifier the ability to detect: "the output claims environment X, but the reference environment at time T was Y, so either the server drifted or someone is replaying an old response."

Protocol-layer primitive for auditability. No policy, no governance vocabulary, no opinion on what the commitment covers or how it is verified. The grpc_exec server chooses the composition; downstream consumers choose how to use it.

What this is NOT

• Not a signed-response mechanism. The commitment is unsigned by grpc_exec; downstream systems add their own signatures as they see fit.
• Not a policy engine. grpc_exec does not evaluate the commitment; it only emits it.
• Not a key distribution problem. Verification happens out-of-band.
• Not coupled to any specific audit framework. Any consumer wanting a stable environment identifier can consume it.

Prior art

A similar pattern exists in the TUF spec (target-file hashes in role metadata), in SLSA provenance (builder and build-platform commitments on the Provenance predicate), and in any reproducible-build system that exposes a hash of the build environment. The grpc_exec shape is different enough that those don't directly apply, but the principle is the same: make the execution environment inspectable by consumers without trusting that nothing changed between execution and audit.

Scope-check questions for the maintainers

1. Is execution-environment commitment in scope for grpc_exec, or out of scope (e.g., philosophy is that agent-shell-tools stays minimal and this belongs in a wrapper)?
2. If in scope, does the maintainer have a preferred composition? (My instinct is server-picks, client-treats-as-opaque, but you may have a stricter model in mind.)
3. Is a single optional bytes field the right shape, or would you prefer a structured message (e.g., {digest, algorithm, context_hint}) for future extensibility?

Happy to draft a PR once the scope answer is clear. If this is out of scope for grpc_exec, that is also useful information; the alternative is a wrapper service that sits between grpc_exec and the audit consumer, which I am also willing to build in a separate repo.

Thanks for maintaining agent-shell-tools; the current scope is cleanly composable and this would extend that property by one small additive field.

[afq984]

I think in a single-user, and in the Agent outside the sandbox composition (see //wsb as an example), grpc_execd is allowed to run arbitrary commands, possibly including a command that takes over grpc_execd itself because it is not the security boundary anyway. So anything returned by grpc_execd cannot be trusted. Would such a field still be useful?

Or do you have another shape or composition in mind that a execution-environment commitment returned by grpc_execd would be useful?

[tomjwxf]

That is fair. In the Agent outside the sandbox composition, a value returned by grpc_execd should not be treated as trustworthy evidence. It is only self-reported correlation data.

I tightened the proposal into a supervisor-side shape here: VeritasActa/Acta#2

The narrower composition is: grpc_exec stays minimal, and a separate observer signs a receipt that binds command digest, working-directory digest, environment commitment, response digest, exit code, and observer identity.

The useful distinction is:

1. self-reported: useful for local correlation only.
2. supervisor-attested: useful for local audit when a separate supervisor observes the request and response.
3. third-party-attested: useful for external verification when a separate trust domain signs.

So I would not treat environment_commitment as proof unless the context says who observed it. If that distinction is too easy to misuse inside ExecuteResponse, I agree it belongs in a wrapper/supervisor receipt rather than the core grpc_exec response.

[afq984]

Thinking about it more, it seems like the execution-environment commitment would be better reported by something that actually owns or manages the environment. Maybe //wsb could be that, but it is still in its early stages of experimentation.

[tomjwxf]

That is fair, grpc_execd is probably the wrong trust boundary for this.

Cleanest working split seems to be:

1. grpc_exec returns execution results and stays minimal.
2. The environment owner, for example //wsb or a wrapper that launches/manages //wsb, computes the environment commitment.
3. A separate observer signs a receipt binding the command digest, response digest, exit code, environment commitment, and observer identity.

Tightened example here: VeritasActa/Acta#2

I will not pursue an ExecuteResponse field based on this discussion. If useful later, I can turn the sketch into a small wsb-side example or wrapper that emits a sidecar receipt, but I agree that it should not come from grpc_execd itself.

Happy to close this issue as out of scope for grpc_exec, or leave it open as a marker for a possible future wsb/supervisor-side experiment, whichever you prefer.