Repository navigation
Expand file tree
/
Copy pathsandbox_protocol.proto
More file actions
437 lines (428 loc) · 14.5 KB
/
Copy pathsandbox_protocol.proto
File metadata and controls
437 lines (428 loc) · 14.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
syntax = "proto3";
package openshell.sandbox.protocol.v1;
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "options.proto";
// EXPERIMENTAL: This protocol is under active development. Its API and wire
// format may change incompatibly before stabilization.
//
// Authenticated Sandbox Protocol for per-boundary and shared backends. Each
// client stream starts with the OpenBoundary handle, checked against the
// authenticated sandbox and generation. Subsequent frames are typed protocol
// messages, with no nested JSON envelopes or application framing.
// Exchange handles one request/response and its associated process or relay I/O.
// Mediate handles OpenMediation followed by correlated DNS queries/responses.
// DiscoverPolicy is allowed before Attach on its own authenticated stream.
// Admission is Attach -> Confirm -> StartAgent; no untrusted instruction may
// execute before StartAgent. Exec and forwarding require Running.
service SandboxProtocol {
rpc Exchange(stream ExchangeFrame) returns (stream ExchangeFrame);
rpc Mediate(stream MediateFrame) returns (stream MediateFrame);
}
// The first client frame contains boundary_id, never repeated on that stream.
// Control messages are bounded to 1 MiB; each I/O payload is at most 64 KiB.
// Process stdin closes explicitly; ending a gRPC request stream does not end
// the independent response stream. Exit follows all retained process output.
message ExchangeFrame {
oneof payload {
string boundary_id = 1;
RequestEnvelope request = 3;
ResponseEnvelope response = 4;
bytes stdin = 5;
bytes stdout = 6;
bytes stderr = 7;
ExitStatus exit = 8;
StdinClosed stdin_closed = 9;
TcpOpenDecision tcp_open_decision = 10;
bytes relay_data = 11;
}
}
// DNS mediation has its own stream, with no process I/O or TCP relay frames.
// The first frame binds the boundary; OpenMediation request/response follows,
// then correlated DNS messages. Other control operations are rejected.
message MediateFrame {
oneof payload {
string boundary_id = 1;
RequestEnvelope request = 3;
ResponseEnvelope response = 4;
DnsQuery dns_query = 12;
DnsResponse dns_response = 13;
}
}
message StdinClosed {}
// A random UUID scoped to the boundary generation. Retried mutations reuse the
// same ID and typed request, including the exec deadline. Replays return the
// original result; conflicting reuse is rejected. Compare decoded known fields
// (map order is immaterial), not serialized protobuf bytes. Unknown fields do
// not authorize behavior: send behavior-affecting additions only after
// negotiating the receiver's supporting capability. No client digest required.
// Replayable mutations: Attach, Confirm, StartAgent, UpdateProviderEnvironment,
// Exec, Signal, Terminate, TerminateBoundary, and Resize. Exec outcomes remain
// retained through the deadline even after process exit.
message RequestEnvelope {
string request_id = 1;
oneof request {
DiscoverPolicy discover_policy = 10;
Attach attach = 11;
Confirm confirm = 12;
StartAgent start_agent = 14;
UpdateProviderEnvironment update_provider_environment = 15;
AttachProcess attach_process = 16;
Wait wait = 17;
Signal signal = 18;
Terminate terminate = 19;
TerminateBoundary terminate_boundary = 20;
Exec exec = 21;
Resize resize = 23;
LoopbackConnect loopback_connect = 24;
OpenMediation open_mediation = 25;
AcceptNetwork accept_network = 26;
}
}
message ResponseEnvelope {
string request_id = 1;
oneof response {
ImagePolicy image_policy = 10;
Attached attached = 11;
Confirmed confirmed = 12;
Started started = 14;
ProviderEnvironmentUpdated provider_environment_updated = 15;
ProcessAttached process_attached = 16;
Exited exited = 17;
Signaled signaled = 18;
Terminated terminated = 19;
BoundaryTerminated boundary_terminated = 20;
ExecStarted exec_started = 21;
Resized resized = 22;
LoopbackConnected loopback_connected = 23;
MediationReady mediation_ready = 24;
NetworkConnected network_connected = 25;
Error error = 26;
}
}
// Read-only image-policy discovery, permitted before attachment.
message DiscoverPolicy {}
message Attach {
string supervisor_instance_id = 1;
SandboxPolicy policy = 2;
// Gateway-signed supervisor takeover grant. Present only when this
// supervisor process replaces the current owner of the generation at a
// higher credential epoch; send it only to a runtime advertising
// openshell.sandbox.supervisor-takeover. The runtime stages the replacement
// and promotes it at Confirm, fencing every older connection and epoch.
optional string supervisor_takeover = 3 [(openshell.options.v1.secret) = true];
// How long the runtime should keep the workload frozen after losing this
// connection's supervision, offered by the supervisor in whole seconds. The
// runtime refuses an offer outside 10 to 300 seconds and applies its
// default (30 seconds) without one.
google.protobuf.Duration supervisor_recovery_timeout = 4;
}
// Success asserts that the backend can enforce the attached policy and trusted
// workload identity. Unsupported requirements fail before StartAgent, which
// installs all launch-time controls as required by the admission sequence.
// Supervisor or transport loss must never relax enforcement or open an
// unmediated egress path; supervisor-dependent operations fail closed.
// A backend may terminate, pause, or keep a disconnected workload contained.
message Confirm {}
// Begin workload execution with the policy admitted by Attach and Confirm.
// For a prepared restore, complete restoration here and return the restored
// main process rather than starting a duplicate. Restoration may immediately
// execute workload instructions, so all launch-time controls must be installed
// before invoking it. A deferred restore failure fails this call, without
// silently changing the launch path selected when the boundary was opened.
// Unsupported provider files must be rejected before workload execution.
message StartAgent {
string sandbox_id = 1;
AgentSpec spec = 2;
optional string ca_cert = 4;
optional string ca_bundle = 5;
uint64 provider_env_revision = 6;
map<string, string> provider_env = 7 [(openshell.options.v1.secret) = true];
map<string, string> provider_files = 8 [(openshell.options.v1.secret) = true];
}
// Validate support and the complete snapshot before applying an update.
message UpdateProviderEnvironment {
uint64 generation = 1;
uint64 revision = 2;
map<string, string> provider_env = 3 [(openshell.options.v1.secret) = true];
map<string, string> provider_files = 4 [(openshell.options.v1.secret) = true];
}
message AttachProcess {
string process_id = 1;
}
message Wait {
string process_id = 1;
}
// Signal either a main or exec process using its generation-scoped ID.
message Signal {
string process_id = 1;
BoundarySignal signal = 2;
}
message Terminate {
string process_id = 1;
}
message TerminateBoundary {}
message Exec {
ExecSpec spec = 1;
// Required absolute admission/retry deadline, not a process runtime limit.
// Remains unchanged on retries and participates in replay comparison.
google.protobuf.Timestamp exec_admission_deadline = 2;
}
message Resize {
string process_id = 1;
uint32 cols = 2;
uint32 rows = 3;
}
message LoopbackConnect {
// Numeric IPv4/IPv6 address inside the boundary. Loopback only.
string host = 1;
uint32 port = 2;
}
message OpenMediation {}
message AcceptNetwork {}
// No image policy is yaml absent with invalid=false. invalid=true reports an
// unreadable or invalid image policy; it must not be treated as missing.
message ImagePolicy {
optional string yaml = 1;
bool invalid = 2;
}
message Attached {
SessionSnapshot snapshot = 1;
}
message Confirmed {
BoundaryConfirmation confirmation = 1;
}
message Started {
string process_id = 1;
uint64 provider_env_revision = 2;
uint64 provider_env_generation = 3;
}
message ProviderEnvironmentUpdated {
uint64 revision = 1;
uint64 generation = 2;
bool applied = 3;
}
message ProcessAttached {
bool terminal = 1;
}
message Exited {
ExitStatus status = 1;
}
message Signaled {}
message Terminated {}
message BoundaryTerminated {}
message ExecStarted {
string process_id = 1;
bool pty = 2;
}
message Resized {}
message LoopbackConnected {}
message MediationReady {}
message NetworkConnected {
BinaryIdentity identity = 1;
// Numeric destination captured before mediation; never a workload-provided
// claim of executable identity. No upstream bytes flow before RelayReady.
string destination = 2;
NetworkSocketMetadata socket = 3;
uint64 policy_generation = 4;
// Omitted timing means unmeasured (zero).
MediationTiming timing = 5;
}
message Error {
BoundaryErrorKind kind = 1;
string message = 2;
}
enum BoundaryErrorKind {
BOUNDARY_ERROR_KIND_UNSPECIFIED = 0;
BOUNDARY_ERROR_KIND_INVALID = 1;
BOUNDARY_ERROR_KIND_DENIED = 2;
BOUNDARY_ERROR_KIND_UNAVAILABLE = 3;
BOUNDARY_ERROR_KIND_TERMINATED = 4;
BOUNDARY_ERROR_KIND_PROCESS = 5;
BOUNDARY_ERROR_KIND_UNSUPPORTED = 6;
}
enum BoundarySignal {
BOUNDARY_SIGNAL_UNSPECIFIED = 0;
BOUNDARY_SIGNAL_TERM = 1;
BOUNDARY_SIGNAL_KILL = 2;
BOUNDARY_SIGNAL_INT = 3;
BOUNDARY_SIGNAL_HUP = 4;
}
message ExitStatus {
oneof status {
int32 exited = 1;
int32 signaled = 2;
}
}
message AgentSpec {
string program = 1;
repeated string args = 2;
optional string workdir = 3;
// Omitted or zero means no timeout; otherwise whole nonnegative seconds.
google.protobuf.Duration timeout = 4;
bool interactive = 5;
// True while the supervisor relays agent OTLP traces, so the runtime may
// point workload SDKs at the relay by default. False keeps the workload
// environment unchanged.
bool otlp_relay_active = 6;
}
message ExecSpec {
string program = 1;
repeated string args = 2;
ShellSpec shell = 3;
optional RuntimeHelper runtime_helper = 4;
// Ordered entries preserve duplicate-variable semantics of the existing API.
repeated EnvironmentEntry env = 5 [(openshell.options.v1.secret) = true];
optional string workdir = 6;
bool pty = 7;
}
message EnvironmentEntry {
string name = 1;
string value = 2;
}
message ShellSpec {
optional string command = 1;
bool login = 2;
}
enum RuntimeHelper {
RUNTIME_HELPER_UNSPECIFIED = 0;
RUNTIME_HELPER_SFTP = 1;
}
// Boundary launch controls, distinct from the authored gateway SandboxPolicy.
message SandboxPolicy {
uint32 version = 1;
repeated string read_only = 2;
repeated string read_write = 3;
bool include_workdir = 4;
NetworkMode network = 5;
optional string proxy_addr = 6;
LandlockCompatibility landlock = 7;
optional string run_as_user = 8;
optional string run_as_group = 9;
}
enum NetworkMode {
NETWORK_MODE_UNSPECIFIED = 0;
NETWORK_MODE_BLOCK = 1;
NETWORK_MODE_PROXY = 2;
NETWORK_MODE_ALLOW = 3;
}
enum LandlockCompatibility {
LANDLOCK_COMPATIBILITY_UNSPECIFIED = 0;
LANDLOCK_COMPATIBILITY_BEST_EFFORT = 1;
LANDLOCK_COMPATIBILITY_HARD_REQUIREMENT = 2;
}
message ResolvedWorkloadIdentity {
uint32 uid = 1;
uint32 gid = 2;
repeated uint32 supplementary_gids = 3;
string source = 4;
string resource_digest = 5;
}
// Successful confirmation binds policy enforcement to the admitted launch.
// Enforcement mechanisms are backend-specific, not a portable flag checklist.
message BoundaryConfirmation {
string generation = 1;
ResolvedWorkloadIdentity identity = 2;
string session_id = 5;
// Derived from backend-owned provisioned state, not supervisor-supplied claims.
map<string, string> resource_claims = 8;
// Optional backend-owned audit document encoded as a UTF-8 JSON value. Empty
// bytes mean absent. Native clients may validate its schema; external backends
// need not provide Linux mechanism evidence.
bytes backend_audit = 9;
// Required SHA-256 commitment to the driver's validated provisioning evidence
// and this generation. Must match trusted launch metadata. A matching digest
// binds provisioning; it is not independent proof of policy enforcement.
string provisioning_evidence_digest = 10;
}
message SessionSnapshot {
string generation = 1;
repeated ProcessSnapshot processes = 2;
// Launch controls the runtime bound at its first attach. A replacement
// supervisor reattaches with exactly these; they never change for a
// running generation.
SandboxPolicy bound_policy = 3;
}
message ProcessSnapshot {
string process_id = 1;
ProcessKind kind = 2;
bool terminal = 3;
ExitStatus status = 4;
OutputWindow retained_output = 5;
}
enum ProcessKind {
PROCESS_KIND_UNSPECIFIED = 0;
PROCESS_KIND_MAIN = 1;
PROCESS_KIND_EXEC = 2;
}
message OutputWindow {
uint64 first_sequence = 1;
uint64 next_sequence = 2;
bool truncated = 3;
}
message ExecutableIdentity {
string path = 1;
optional string digest = 2;
}
message ResolvedBinaryIdentity {
ExecutableIdentity executable = 1;
repeated ExecutableIdentity ancestors = 2;
repeated string cmdline_paths = 3;
}
message BinaryIdentity {
oneof result {
ResolvedBinaryIdentity resolved = 1;
string failed = 2;
}
}
// Optional native socket evidence. Guests without kernel sockets omit it and
// supply their authoritative executable identity; never fabricate host PIDs.
message NetworkSocketMetadata {
uint64 socket_cookie = 1;
bool nonblocking = 2;
uint64 process_generation = 3;
}
message MediationTiming {
// Diagnostic backend-monotonic measurements; zero if unmeasured.
google.protobuf.Duration notification_to_queue = 1;
google.protobuf.Duration queue_wait = 2;
}
message TcpOpenDecision {
oneof decision {
TcpOpenDenial denied = 1;
RelayReady relay_ready = 2;
}
}
message RelayReady {}
enum TcpOpenDenial {
TCP_OPEN_DENIAL_UNSPECIFIED = 0;
TCP_OPEN_DENIAL_POLICY_DENIED = 1;
TCP_OPEN_DENIAL_IDENTITY_UNAVAILABLE = 2;
TCP_OPEN_DENIAL_INVALID_DESTINATION = 3;
TCP_OPEN_DENIAL_RESOURCE_EXHAUSTED = 4;
TCP_OPEN_DENIAL_MEDIATION_UNAVAILABLE = 5;
}
message DnsQuery {
uint64 stream_id = 1;
// One DNS wire message, without DNS-over-TCP framing.
bytes request = 2;
DnsTransport transport = 3;
BinaryIdentity identity = 4;
// Omitted timing means unmeasured (zero).
MediationTiming timing = 5;
}
enum DnsTransport {
DNS_TRANSPORT_UNSPECIFIED = 0;
DNS_TRANSPORT_UDP = 1;
DNS_TRANSPORT_TCP = 2;
}
// Reply on the same authenticated mediation stream with the query stream_id.
message DnsResponse {
uint64 stream_id = 1;
oneof result {
bytes response = 2;
string error = 3;
}
}