Package land.oras.policy

Class ContainersPolicy

java.lang.Object
land.oras.policy.ContainersPolicy
@NullMarked public class ContainersPolicy extends Object
Represents the containers trust policy loaded from a policy.json file.

This class loads and models the containers-policy.json format used by Podman, Skopeo, Buildah, and other containers/image-based tools to control which images may be pulled and what level of verification is required.

See Also:

  • Method Details

    • newPolicy

      public static ContainersPolicy newPolicy()
      Load the containers policy from the standard locations.
      Returns:
      a ContainersPolicy instance.
      Throws:
      OrasException - if a candidate file exists but cannot be read or parsed.

    • newPolicy

      public static ContainersPolicy newPolicy(Path path)
      Load the containers policy from the given path.
      Parameters:
      path - the path to the policy.json file.
      Returns:
      a ContainersPolicy instance.
      Throws:
      OrasException - if the file cannot be read or parsed.

    • acceptAll

      public static ContainersPolicy acceptAll()
      Create a policy that accepts any image unconditionally.
      Returns:
      a permissive ContainersPolicy.

    • rejectAll

      public static ContainersPolicy rejectAll()
      Create a policy that rejects every image unconditionally.
      Returns:
      a rejecting ContainersPolicy.

    • isAllowed

      public boolean isAllowed(Transport transport, String scope)
      Determine whether an image is allowed under this policy using the lightweight, content-free scope gate.

      All requirements in the resolved list must pass (logical AND). Because no image content is available, signature-based requirements (signedBy, sigstoreSigned) allow the operation to proceed here; their cryptographic check runs in verify(PolicyContext) once the image has been resolved during a pull.

      Parameters:
      transport - the transport, e.g. Transport.DOCKER.
      scope - the image scope, e.g. "docker.io/library/nginx".
      Returns:
      true if all resolved requirements pass.

    • verify

      public void verify(PolicyContext context)
      Verify a resolved image against this policy, performing content-based checks (such as Sigstore signature verification) that isAllowed(Transport, String) cannot perform.

      All resolved requirements must pass (logical AND). If any requirement fails, an OrasException is thrown describing the failure.

      Parameters:
      context - the policy context carrying the resolved digest and a signature fetcher.
      Throws:
      OrasException - if any resolved requirement rejects the image.

    • resolveRequirements

      public List<PolicyRequirement> resolveRequirements(Transport transport, String scope)
      Resolve the list of PolicyRequirement objects that apply to the given transport and scope, following the precedence rules described in isAllowed(land.oras.policy.Transport, java.lang.String).
      Parameters:
      transport - the transport, e.g. Transport.DOCKER.
      scope - the image scope, e.g. "docker.io/library/nginx".
      Returns:
      the non-null, possibly empty list of requirements (empty means global default was used and it too was empty — treat as reject-by-default for safety).

    • getDefaultRequirements

      public List<PolicyRequirement> getDefaultRequirements()
      Return the global default requirements.
      Returns:
      an unmodifiable view of the default requirement list.

    • getTransports

      public Map<Transport,Map<String,List<PolicyRequirement>>> getTransports()
      Return all transport-scoped requirements as an unmodifiable map.
      Returns:
      a map from Transport to a map of scope → requirements.