Skip to documentation
Documentation navigation

Documentation navigation

Documentation / guides

Compilation Reports

Use CompileReport entries to distinguish enforced, narrowed, and unavailable policy features.

developer

The backend compiles a policy into a reusable spawn specification. The result carries a sandbox.CompileReport alongside the level and guarantee bits. Each ReportEntry has a Feature, Status, and Detail. The report is the explanation for why a feature was enforced, narrowed, or left unenforced.

Read the report as a contract

StatusMeaningCaller response
EnforcedThe backend installed an enforcement mechanism for this feature.The corresponding guarantee may be usable, subject to the feature’s exact scope.
narrowed or NarrowedThe backend made a sound, narrower approximation.Read Detail; decide whether the narrower behavior is acceptable.
unenforcedThe requested feature is not enforced by this backend.Do not claim the requested boundary. Require another backend/profile or stop.

The status strings are backend report vocabulary rather than a new exported enum. Some native reports also use widened or vacuous to disclose a platform baseline or an axis with no applicable request. Treat those entries as a reason to read Detail, never as permission to widen the caller’s policy. A report entry is not itself an admission grant. It describes the compiled executor after the profile and platform checks have run.

Compile once, inspect once

package example

import (
	"fmt"
	"strings"

	"github.com/looprig/sandbox"
)

func requireNetwork(executor *sandbox.Executor) error {
	for _, entry := range executor.Report().Entries {
		if entry.Feature == "address-network" &&
			strings.EqualFold(entry.Status, "unenforced") {
			return fmt.Errorf("address network is unavailable: %s", entry.Detail)
		}
	}
	if !executor.Guarantees().NetworkBoundary {
		return fmt.Errorf("network boundary was not achieved")
	}
	return nil
}

The profile’s required mask catches mandatory missing bits during executor construction. The report remains useful for optional features and for diagnostics. A caller that wants to log the report should preserve the detail, because “narrowed” can mean materially different things: Linux Rung 2 can enforce TCP ports while leaving address scoping unenforced; DNS may be forced over TCP only for resolvers that honor RES_OPTIONS=use-vc.

Compile reports and grants

Grant issuance and redemption bind tokens to the profile fingerprint and achieved guarantee bits. If a profile or route changes, the old token cannot be reused as if it were a grant for the new compiled authority. A target-scoped grant can also require GuaranteeTargetNetwork and GuaranteeNetworkBoundary; otherwise the executor refuses it with ErrGrantGuaranteeMismatch or ErrGrantUnsupported.

Source

Proof

← back to documentation