Documentation
¶
Overview ¶
Package sandbox defines bounded evaluation jobs without importing a runtime.
Index ¶
Constants ¶
const ArtifactProducer = "cortex/sandbox"
ArtifactProducer identifies worker-captured bytes, not a grading verdict.
const NetworkDenied = "denied"
NetworkDenied is the only network profile supported by schema one.
const PrefixJob id.Prefix = "sjob"
PrefixJob identifies a sandbox evaluation job.
const ProfileDenyAll = "runsc-deny-all-v1"
ProfileDenyAll requires read-only root and inputs, empty capabilities, isolated PID/mount/network namespaces, non-root identity and enforced resource limits.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Capabilities ¶
type Capabilities struct {
SchemaVersion int `json:"schema_version"`
Runtime string `json:"runtime"`
RuntimeDigest string `json:"runtime_digest"`
Profile string `json:"profile"`
Qualification string `json:"qualification"`
QualifiedUntil time.Time `json:"qualified_until"`
Limits Limits `json:"limits"`
}
Capabilities is a trusted deployment attestation. The adapter must only publish Qualification after the pinned worker passes its live isolation probes. These values cannot establish their own authenticity.
func (Capabilities) Supports ¶
func (c Capabilities) Supports(j Job) error
Supports fails closed for missing or expired qualification and excess limits.
func (Capabilities) Validate ¶
func (c Capabilities) Validate() error
Validate checks capability shape and qualification expiry. It does not prove the attestation's origin or establish that live isolation probes passed.
type Input ¶
Input mounts one immutable artifact under /inputs, read-only. Path never identifies a host path. Directories and links are not inputs.
type Job ¶
type Job struct {
SchemaVersion int `json:"schema_version"`
ID id.ID `json:"id"`
Key string `json:"key"`
Scope cortex.Scope `json:"scope"`
Principal string `json:"principal"`
Image string `json:"image"`
Argv []string `json:"argv"`
Inputs []Input `json:"inputs,omitempty"`
Outputs []Output `json:"outputs,omitempty"`
Env map[string]string `json:"env,omitempty"`
Network string `json:"network"`
Limits Limits `json:"limits"`
Digest string `json:"digest"`
}
Job carries no host mount, capability, credential or shell-interpolation fields. The host authenticates Principal and Scope independently of this payload.
func (Job) OutputSource ¶
OutputSource identifies the guest path in this job. It is an opaque provenance reference, never a host path or a URL to fetch. Callers must validate the job and require output to be one of its signed declarations.
func (Job) ValidateArtifacts ¶
ValidateArtifacts binds captured references to the signed declarations. Set complete for an exited job; failed attempts may retain a verified subset. This checks metadata only. It grants no access and proves no task correctness.
type JobStatus ¶
type JobStatus struct {
Receipt Receipt `json:"receipt"`
State State `json:"state"`
Revision uint64 `json:"revision"`
UpdatedAt time.Time `json:"updated_at"`
}
JobStatus is a durable broker observation. Revision is a monotonic CAS token.
type Limits ¶
type Limits struct {
CPUMillis int64 `json:"cpu_millis"`
MemoryBytes int64 `json:"memory_bytes"`
Processes int64 `json:"processes"`
ScratchBytes int64 `json:"scratch_bytes"`
WallTime time.Duration `json:"wall_time_ns"`
OutputBytes int64 `json:"output_bytes"`
ArtifactBytes int64 `json:"artifact_bytes,omitempty"`
}
Limits are hard ceilings. OutputBytes bounds combined stdout and stderr; ArtifactBytes separately bounds captured files and defaults to no capture.
type Output ¶
type Output struct {
ID id.ID `json:"id"`
Path string `json:"path"`
MediaType string `json:"media_type"`
MaxBytes int64 `json:"max_bytes"`
}
Output declares a required regular file under the guest's scratch directory. The host allocates ID before sealing the job so an uncertain upload can be reconciled by identity. MediaType is a declaration, not content validation. Captured files are restricted evidence. No destination or release grant is carried here. Archives remain opaque bytes and are never expanded.
type Receipt ¶
type Receipt struct {
SchemaVersion int `json:"schema_version"`
Job Job `json:"job"`
Capabilities Capabilities `json:"capabilities"`
Broker string `json:"broker"`
AcceptedAt time.Time `json:"accepted_at"`
Signature []byte `json:"signature"`
}
Receipt binds accepted execution controls to an authenticated broker identity. Transport authentication is mandatory; Signature signs canonical JSON with this field empty using the broker's Ed25519 key.
type Result ¶
type Result struct {
JobDigest string `json:"job_digest"`
State State `json:"state"`
ExitCode int `json:"exit_code"`
Reason string `json:"reason"`
Stdout []byte `json:"stdout,omitempty"`
Stderr []byte `json:"stderr,omitempty"`
Artifacts []evidence.Ref `json:"artifacts,omitempty"`
Signature []byte `json:"signature,omitempty"`
}
Result is bounded output from an authenticated runner. The candidate's stdout never supplies a trusted verdict; protected grading evaluates it separately.
type Runner ¶
type Runner interface {
Capabilities(context.Context) (Capabilities, error)
Submit(context.Context, Job) (Receipt, error)
Inspect(context.Context, id.ID) (JobStatus, error)
Cancel(context.Context, id.ID) error
Collect(context.Context, id.ID) (Result, error)
}
Runner submits and reconciles jobs by immutable identity. An ambiguous Submit must be inspected or retried with the same key, never replaced with a host run.
Source Files