Documentation
¶
Overview ¶
Package igbackend owns strict execution-policy gadgets. The public service uses the persistent full backend; the explicit legacy API remains separate. Unsupported semantics are errors, never silently weakened rules.
Index ¶
- Constants
- Variables
- func ApplySharedNodeHealth(status *api.NodeStatus, h SharedNodeHealth, observedGeneration int64, ...)
- func Compile(binding sandboxpolicy.Binding, plan sandboxpolicy.Plan, generation uint64) (execruntime.Config, error)
- func CompileFull(binding sandboxpolicy.Binding, plan sandboxpolicy.Plan, generation uint64, ...) (*fullpolicy.KernelProgram, error)
- func DecodeVerdict(binding sandboxpolicy.Binding, plan sandboxpolicy.Plan, generation uint64, ...) (sandboxpolicy.Verdict, error)
- func LoadSharedProfile(path string) (fullruntime.SharedProfile, error)
- func VerifySharedImage(ctx context.Context, store oras.ReadOnlyTarget, image, expected, arch string) error
- type Backend
- func (b *Backend) Close(ctx context.Context) error
- func (b *Backend) Replace(ctx context.Context, binding sandboxpolicy.Binding, plan sandboxpolicy.Plan) (result sandboxpolicy.ReplaceResult, resultErr error)
- func (b *Backend) Withdraw(ctx context.Context, binding sandboxpolicy.Binding) (result sandboxpolicy.WithdrawResult, resultErr error)
- type ContainerdFullSource
- type Engine
- type FullBackend
- func (b *FullBackend) Attest(ctx context.Context, binding sandboxpolicy.Binding, revision string) error
- func (b *FullBackend) Close(ctx context.Context) error
- func (b *FullBackend) KernelEventStats(ctx context.Context) (KernelEventStats, error)
- func (b *FullBackend) Replace(ctx context.Context, binding sandboxpolicy.Binding, plan sandboxpolicy.Plan) (result sandboxpolicy.ReplaceResult, resultErr error)
- func (b *FullBackend) Withdraw(ctx context.Context, binding sandboxpolicy.Binding) (sandboxpolicy.WithdrawResult, error)
- type FullBindingLease
- type FullBindingSource
- type FullEngine
- type FullEngineCloser
- type FullInstance
- type FullKernelCounterSource
- type FullPendingAborter
- type FullPlanUpdater
- type FullStartConfig
- type FullVerdictCatalog
- func (c *FullVerdictCatalog) Abort(generation uint64) error
- func (c *FullVerdictCatalog) Commit(generation uint64) error
- func (c *FullVerdictCatalog) Decode(raw RawFullVerdict) (sandboxpolicy.Verdict, error)
- func (c *FullVerdictCatalog) Stage(generation uint64, plan sandboxpolicy.Plan, program *fullpolicy.KernelProgram) error
- type FullVerdictDecoder
- type ImageIndexLimits
- type ImageInode
- type Instance
- type KernelEventStats
- type KernelEventTotals
- type Lease
- type LinuxValidator
- type RawFullVerdict
- type RawVerdict
- type SharedEngine
- type SharedEngineConfig
- type SharedNodeHealth
- type SharedProductConfig
- type SharedProductImage
- type Validator
Constants ¶
const ( )
Defaults: the host procfs and root as mounted into the node-agent pod (hostPID is required for the host PID namespace).
const FullBackendMaxBindings = 1024
FullBackendMaxBindings includes owners awaiting cleanup.
const FullOperationTimeout = 5 * time.Second
Bound whole-exec drain/re-attestation even when the service lifetime context has no deadline. First admission may need a longer bounded image walk/load.
const FullStartupTimeout = 2 * time.Minute
const FullVerdictCatalogCapacity = 16
FullVerdictCatalogCapacity bounds provenance retained per persistent owner, including its active generation and at most one pending publication. Late events for evicted generations are dropped, never decoded with newer rules.
SharedEngineAPIVersion is the IG shared-node API version this engine is written against; the engine constructors refuse any other.
SharedPublishAttempts bounds Compile/PublishCompiled retries when a compilation goes stale (fullruntime.ErrSharedCompiledStale).
Variables ¶
var ErrKernelNotQualified = errors.New("running kernel is not a qualified kernel build")
ErrKernelNotQualified: the running kernel is not one of the agent's compiled-in qualified kernel builds (its architecture, BTF sha256, release or GNU build-id differs). Health reports it with reason KernelNotQualified.
ErrSharedManifestMismatch: the trusted store resolves the selected image to a manifest other than the configured one.
var ErrVerdictDecode = errors.New("sandbox verdict decode failed")
ErrVerdictDecode wraps every verdict event dropped because it could not be read from the datasource or decoded against its generation's catalogue. It reaches the onError callback only; enforcement is unaffected.
Functions ¶
func ApplySharedNodeHealth ¶
func ApplySharedNodeHealth(status *api.NodeStatus, h SharedNodeHealth, observedGeneration int64, now metav1.Time)
ApplySharedNodeHealth maps h into status's Ready and Degraded conditions.
Ready: an engine refused at agent start is False (KernelNotQualified when the running kernel is not a qualified build, otherwise SharedEngineUnavailable, with the typed reason), a node start still retrying a native attach capacity refusal is False (SharedNodeAttachCapacity, with the refusal), a node whose start failed is False (SharedNodeStartFailed, with the error), a node not started is False (SharedNodeNotStarted) and a node whose Ready fails, or whose fail-closed witness is NotReady or unknown, is False (SharedNodeNotReady). A qualification node is otherwise False (QualificationOnly). A Ready product node never raises Ready: the controller's Ready condition (True only when every binding's Check passed) is kept, and absent one Ready is False (ReadyUnreported).
Degraded (D2: never NotReady on its own) is merged into an existing Degraded condition: an existing True one keeps its reason and message and gains ours. Ours reports a fail-closed Degraded window, verdict event loss, the image ledger fault, any other Degraded condition of a product node (SharedNodeDegraded), a binding's latched protocol fault (BindingProtocolFault) and unavailable witnesses.
func Compile ¶
func Compile(binding sandboxpolicy.Binding, plan sandboxpolicy.Plan, generation uint64) (execruntime.Config, error)
Compile is an explicit interim legacy converter, not the full exec backend.
func CompileFull ¶
func CompileFull(binding sandboxpolicy.Binding, plan sandboxpolicy.Plan, generation uint64, activatedRoleEpochs map[string]uint64) (*fullpolicy.KernelProgram, error)
CompileFull preserves the complete resolved exec vocabulary and policy-local identities. It prepares immutable data only: it neither attests kernel facts nor authorizes role bootstrap, image evidence or native publication. The interim path-only Compile/Backend remains unchanged until its persistent owner is available. activatedRoleEpochs is the persistent owner's SUCCESSFUL UID activation catalogue; nil is appropriate only for a fresh owner, not reload. The matching expanded IG module is required to build this bridge.
func DecodeVerdict ¶
func DecodeVerdict(binding sandboxpolicy.Binding, plan sandboxpolicy.Plan, generation uint64, r RawVerdict) (sandboxpolicy.Verdict, error)
DecodeVerdict leaves argv, UID, image origin and actor paths absent when the legacy event cannot supply them. Time is receipt time, not kernel time.
func LoadSharedProfile ¶
func LoadSharedProfile(path string) (fullruntime.SharedProfile, error)
LoadSharedProfile reads the exact geometry the shared image was built with (a JSON fullruntime.SharedProfile; unknown fields are refused).
func VerifySharedImage ¶
func VerifySharedImage(ctx context.Context, store oras.ReadOnlyTarget, image, expected, arch string) error
VerifySharedImage is the build-time check of a product image in the agent's tracers.tar: the agent's start check for arch (the kernel entry's architecture, not the builder's), then every blob the manifest references (its config and layers) is fetched digest- and size-verified, so the archive cannot ship content other than the pinned image's.
Types ¶
type Backend ¶
type Backend struct {
// contains filtered or unexported fields
}
func New ¶
func New(engine Engine, validator Validator, receiver sandboxpolicy.VerdictReceiver, onError func(error)) (*Backend, error)
func NewNative ¶
func NewNative(rt runtime.Runtime, kube operators.DataOperator, store oras.ReadOnlyTarget, image string, receiver sandboxpolicy.VerdictReceiver, onError func(error)) (*Backend, error)
NewNative uses an already initialized runtime. Its caller retains ownership of that runtime and must call Backend.Close before runtime.Close.
func (*Backend) Close ¶
Close removes this backend's exact bindings and finishes their cleanup. Call again after an error; it does not stop unrelated instances on the runtime.
func (*Backend) Replace ¶
func (b *Backend) Replace(ctx context.Context, binding sandboxpolicy.Binding, plan sandboxpolicy.Plan) (result sandboxpolicy.ReplaceResult, resultErr error)
func (*Backend) Withdraw ¶
func (b *Backend) Withdraw(ctx context.Context, binding sandboxpolicy.Binding) (result sandboxpolicy.WithdrawResult, resultErr error)
type ContainerdFullSource ¶
type ContainerdFullSource struct {
// contains filtered or unexported fields
}
ContainerdFullSource owns one trusted containerd connection. Close must follow all native owners' confirmed detach and lease release; it refuses outstanding preparations/leases. A failed Close seals admission, and can be retried.
The administrator must provide a protected host root, host proc/cgroup mounts and containerd socket/parent directory from the same host. These privileged inputs are not authenticated by policy metadata or by merely naming a path. The host-proc check additionally requires Linux's initial PID namespace and pins PID1's current mount namespace; unsupported/container-local proc fails.
func NewContainerdFullSource ¶
func NewContainerdFullSource(socket, hostRoot, procRoot, cgroupRoot string, limits ImageIndexLimits) (*ContainerdFullSource, error)
func (*ContainerdFullSource) Close ¶
func (s *ContainerdFullSource) Close() error
func (*ContainerdFullSource) Prepare ¶
func (s *ContainerdFullSource) Prepare(ctx context.Context, binding sandboxpolicy.Binding) (FullBindingLease, error)
type Engine ¶
type Engine interface {
Start(context.Context, string, execruntime.Config, func(RawVerdict)) (Instance, error)
}
Engine.Start returns only after native readiness, or after failed-candidate cleanup. Every call owns independent maps and links.
type FullBackend ¶
type FullBackend struct {
// contains filtered or unexported fields
}
FullBackend publishes into one persistent native owner per exact binding. Native engine and trusted lease source are explicit: there is no legacy fallback.
func NewFull ¶
func NewFull(engine FullEngine, source FullBindingSource, receiver sandboxpolicy.VerdictReceiver, onError func(error)) (*FullBackend, error)
func (*FullBackend) Attest ¶
func (b *FullBackend) Attest(ctx context.Context, binding sandboxpolicy.Binding, revision string) error
Attest observes only the exact committed owner; it never resumes a pending publication, including an uncommitted candidate from a previously failed reload.
func (*FullBackend) KernelEventStats ¶
func (b *FullBackend) KernelEventStats(ctx context.Context) (KernelEventStats, error)
KernelEventStats reads telemetry only; it does not check/repair enforcement. Errors describe incomplete totals, never successful zero-loss observations.
func (*FullBackend) Replace ¶
func (b *FullBackend) Replace(ctx context.Context, binding sandboxpolicy.Binding, plan sandboxpolicy.Plan) (result sandboxpolicy.ReplaceResult, resultErr error)
func (*FullBackend) Withdraw ¶
func (b *FullBackend) Withdraw(ctx context.Context, binding sandboxpolicy.Binding) (sandboxpolicy.WithdrawResult, error)
type FullBindingLease ¶
type FullBindingLease interface {
fullruntime.BindingLease
ImageOrigins() *execruntime.ImageOriginSnapshot
}
FullBindingLease is authenticated runtime evidence, never policy input. Origins must describe the same pinned image root for the entire owner lifetime. Close consumes all owned resources even on OS close errors; repeated Close is harmless. This matches the native Owner.ReleaseAfterDetach contract.
type FullBindingSource ¶
type FullBindingSource interface {
Prepare(context.Context, sandboxpolicy.Binding) (FullBindingLease, error)
}
FullBindingSource transfers an owned lease, including any nonnil lease returned alongside an error. The backend retains it until cleanup is confirmed. Prepare may run concurrently for distinct bindings.
type FullEngine ¶
type FullEngine interface {
Start(context.Context, string, FullStartConfig, func(RawFullVerdict)) (FullInstance, error)
}
FullEngine prepares one persistent owner without activating its first policy. Install event provenance BEFORE Start and Activate. A non-nil instance returned with an error still owns resources: retain it and retry Stop until successful. Start may run concurrently for distinct bindings. Instance operations are serialized per binding; Close runs only after all Start/instance work joins. Event callbacks must not reenter lifecycle methods or block on their locks.
func NewNativeFullEngine ¶
func NewNativeFullEngine(rt runtime.Runtime, kube operators.DataOperator, store oras.ReadOnlyTarget, image, controlRoot string, budget *fullruntime.Budget, onError func(error)) (FullEngine, error)
NewNativeFullEngine borrows the initialized runtime and trusted OCI archive. The caller must stop every instance before closing the runtime. The one shared budget must cover all engines that could target the same cgroup. No fallback to immutable/path-only enforcement occurs when the persistent image is unsupported.
type FullEngineCloser ¶
FullEngineCloser optionally owns node-wide resources shared by instances. The backend calls Close only after every instance and untransferred lease has drained. An error retains ownership for retry; success is called only once. Close must not release the borrowed runtime or binding source: their caller closes those only after backend Close succeeds. Legacy engines need no Close.
type FullInstance ¶
type FullInstance interface {
Activate(context.Context) (fullruntime.PublicationResult, error)
Update(context.Context, *fullpolicy.KernelProgram) (fullruntime.PublicationResult, error)
Resume(context.Context) (fullruntime.PublicationResult, error)
Generation() uint64
PendingGeneration() uint64
Epochs() map[string]uint64
Check(context.Context) error
// Detached confirms manager teardown, even if releasing pins still fails.
Detached() bool
Stop(context.Context) error
}
FullInstance reloads the same kernel owner; it never replaces the gadget. A publication error may have Committed=true. Resume the same pending generation rather than creating another owner or rolling back successful role epochs.
type FullKernelCounterSource ¶
type FullKernelCounterSource interface {
KernelEventCounters() (fullruntime.KernelEventCounters, error)
}
FullKernelCounterSource is optional telemetry, independent of readiness. Successful Stop must retain a Final snapshot or an explicit unavailable error.
type FullPendingAborter ¶
FullPendingAborter optionally discards an uncommitted candidate without changing the last committed policy. A committed candidate must not abort.
type FullPlanUpdater ¶
type FullPlanUpdater interface {
UpdatePlan(context.Context, sandboxpolicy.Plan, *fullpolicy.KernelProgram) (fullruntime.PublicationResult, error)
}
FullPlanUpdater optionally receives the resolved plan with each reload. The backend calls UpdatePlan instead of Update when an instance implements it; program is the backend's compilation of plan at its pending generation and keeps the Update contract (result generation, pending/commit semantics).
type FullStartConfig ¶
type FullStartConfig struct {
Binding sandboxpolicy.Binding
Program *fullpolicy.KernelProgram
Acquire func(context.Context) (fullruntime.BindingLease, error)
ImageOrigins *execruntime.ImageOriginSnapshot
// Plan is the resolved plan Program was compiled from. Engines that compile
// in-kernel publications themselves (the shared node engine) need it;
// per-binding owners ignore it.
Plan sandboxpolicy.Plan
}
FullStartConfig supplies trusted runtime evidence, never policy annotations. Acquire transfers ownership of its lease (including partial error results) to the instance. ImageOrigins must remain pinned by that lease until Stop succeeds.
type FullVerdictCatalog ¶
type FullVerdictCatalog struct {
// contains filtered or unexported fields
}
FullVerdictCatalog is local provenance, not proof of kernel publication or health. It must not be copied after first use. One catalogue belongs to one exact binding and must outlive that owner's event subscription.
func NewFullVerdictCatalog ¶
func NewFullVerdictCatalog(binding sandboxpolicy.Binding) *FullVerdictCatalog
func (*FullVerdictCatalog) Abort ¶
func (c *FullVerdictCatalog) Abort(generation uint64) error
Abort removes only an uncommitted pending attempt after the kernel publisher confirms it did not commit. The attempt number is never reusable.
func (*FullVerdictCatalog) Commit ¶
func (c *FullVerdictCatalog) Commit(generation uint64) error
Commit records an irreversible kernel commit, even if publication finalization failed. It is idempotent for the active generation. Never Abort a committed publication: retain its provenance while resuming the same kernel generation.
func (*FullVerdictCatalog) Decode ¶
func (c *FullVerdictCatalog) Decode(raw RawFullVerdict) (sandboxpolicy.Verdict, error)
func (*FullVerdictCatalog) Stage ¶
func (c *FullVerdictCatalog) Stage(generation uint64, plan sandboxpolicy.Plan, program *fullpolicy.KernelProgram) error
Stage validates and snapshots provenance BEFORE calling the kernel publisher. Once admitted (no pending publication), an attempt number is consumed even if validation fails. Resumption uses the existing staged generation, not Stage. Staged events can be decoded because kernel commit may precede its Go receipt.
type FullVerdictDecoder ¶
type FullVerdictDecoder struct {
// contains filtered or unexported fields
}
FullVerdictDecoder snapshots bounded immutable provenance. It does not attach programs or attest that the kernel supplied complete or trustworthy facts.
func NewFullVerdictDecoder ¶
func NewFullVerdictDecoder(binding sandboxpolicy.Binding, plan sandboxpolicy.Plan, program *fullpolicy.KernelProgram) (*FullVerdictDecoder, error)
func (*FullVerdictDecoder) Decode ¶
func (d *FullVerdictDecoder) Decode(r RawFullVerdict) (sandboxpolicy.Verdict, error)
type ImageIndexLimits ¶
type ImageIndexLimits struct{ Roots, Files, Entries, Depth, PathBytes int }
ImageIndexLimits may tighten, never enlarge, the finite indexing budget. Zero selects the hard maximum for that dimension.
type ImageInode ¶
type Instance ¶
type Instance interface {
Ready() error
Unbind(context.Context, execruntime.ContainerIdentity) error
Stop(context.Context) error
}
type KernelEventStats ¶
type KernelEventStats struct {
Owned, Retired KernelEventTotals
}
KernelEventStats covers this backend's lifetime (not process restarts). Owned includes partial-startup and retiring instances. Retired retains final snapshots after instance removal. Unavailable counts MUST be checked before interpreting zero loss. Live snapshots are not atomic across CPUs/instances.
type KernelEventTotals ¶
type KernelEventTotals struct {
Submitted, Lost, ObservationErrors uint64
}
KernelEventTotals contains successfully read kernel counter contributions. On read failure, the last successful sample is retained as a lower bound. These counters exclude early native owner refusals; Lost measures failed ring reservations, not userspace queue loss or complete denied-exec event coverage.
type LinuxValidator ¶
type LinuxValidator struct{ ProcRoot, CgroupRoot string }
LinuxValidator uses host-visible procfs and the unified cgroup mount. Runtime and container ID must originate from the authoritative runtime cache; neither is inferred from cgroup names. Nonempty roots support node-agent host mounts.
Binding cgroup paths are host-absolute (IG reads them in PID 1's cgroup namespace and CgroupRoot is the host cgroup2 mount), but the kernel renders /proc/<pid>/cgroup relative to the reader's cgroup namespace. A pod-confined agent (containerd on cgroup v2 gives every non-host container a private cgroupns) would read "0::/../<path>", so membership is re-read only from the pinned initial cgroup namespace of ProcRoot's PID 1.
func (LinuxValidator) Acquire ¶
func (v LinuxValidator) Acquire(ctx context.Context, b sandboxpolicy.Binding) (Lease, error)
type RawFullVerdict ¶
type RawFullVerdict struct {
RawVerdict
MatchedRules [4]uint64
Error uint32
// Shared reports that the event carried the additive shared-engine fields
// (event ABI 1: exec_class, scope, exec_id, pass, uncertain,
// facts_unknown, load_epoch); they are zero otherwise. task_cookie is
// optional within that ABI: HasTaskCookie reports its presence.
ExecClass, Pass, Uncertain, FactsUnknown uint32
Scope, ExecID, LoadEpoch uint64
HasTaskCookie bool
TaskCookie uint64
}
func ReadFullVerdict ¶
func ReadFullVerdict(ds datasource.DataSource, data datasource.Data) (RawFullVerdict, error)
ReadFullVerdict checks schema presence before invoking typed accessors. Bitmap words use the producer's byte order, not the host's or the IR encoding order.
type RawVerdict ¶
type SharedEngine ¶
type SharedEngine struct {
// contains filtered or unexported fields
}
SharedEngine implements FullEngine and FullEngineCloser over one lazily started node. Events demultiplex by the bound cgroup and must carry the binding's route scope once it is known.
func NewSharedProductEngine ¶
func NewSharedProductEngine(ctx context.Context, rt runtime.Runtime, c SharedProductConfig, onError func(error)) (*SharedEngine, error)
NewSharedProductEngine selects the running kernel build's image now, at agent start (fullruntime.SelectSharedProductImage), loads its profile and binds its manifest digest. Any refusal leaves an engine that never starts: every Start fails and Health reports the reason (wrapping fullruntime.ErrSharedNativeUnavailable); nothing falls back to another image or engine. Otherwise the node starts on the first Start, through a manager of the borrowed runtime, after binding the manifest again.
func NewUnavailableSharedEngine ¶
func NewUnavailableSharedEngine(reason error, onError func(error)) *SharedEngine
NewUnavailableSharedEngine returns a product engine refused at agent start for reason (for example ErrKernelNotQualified): it never starts, every Start fails and Health reports the reason, wrapping fullruntime.ErrSharedNativeUnavailable. The reason is reported once.
func (*SharedEngine) Close ¶
func (e *SharedEngine) Close(ctx context.Context) error
Close stops the node after every instance was stopped. An error retains the node for a retried Close; no binding is admitted after Close found none (a Start that reserved its cgroup first makes Close refuse).
func (*SharedEngine) Health ¶
func (e *SharedEngine) Health() SharedNodeHealth
Health reads the node's witnesses without starting it and never waits on a start in progress.
func (*SharedEngine) Start ¶
func (e *SharedEngine) Start(ctx context.Context, id string, config FullStartConfig, emit func(RawFullVerdict)) (FullInstance, error)
Start binds the trusted binding to a route slot; Activate publishes.
type SharedEngineConfig ¶
type SharedEngineConfig struct {
// Image names the trusted shared image in Store (an explicit OCI target
// is pretrusted by IG, not signature-verified here; the product start
// also binds its manifest digest).
// ContainerdAddress is the containerd socket as seen by the agent (empty:
// no image index, FromImage policies are refused by IG). ImageProcRoot and
// ImageHostRoot default to SharedDefaultImageProcRoot/HostRoot.
SharedEngineConfig is administrator configuration, never policy input.
type SharedNodeHealth ¶
type SharedNodeHealth struct {
Qualification bool
// fullruntime.ErrSharedNativeUnavailable); nothing was started.
Unavailable error
StartErr error
// a node start is still retrying (nil once cleared, or once the start
// ended). Status only.
AttachRefusal error
// BindingFaults joins the bindings' latched commit-time protocol faults
// (Degraded here; each one also fails its binding's Check).
SharedNodeHealth is one reading of the node's health witnesses.
type SharedProductConfig ¶
type SharedProductConfig struct {
Images map[string]SharedProductImage
Store oras.ReadOnlyTarget
// ContainerdAddress, ImageProcRoot and ImageHostRoot as in
// SharedEngineConfig.
SharedProductConfig is the product engine's administrator configuration.
type SharedProductImage ¶
type SharedProductImage struct {
SharedProductImage is one kernel build's product image: the image reference in Store, the profile it was built with (Profile when set, else the JSON at ProfileFile) and the digest of its manifest for this architecture.