libentitlement

README

libentitlement

libentitlement is currently WIP for a proof-of-concept that implements this proposal but would also handle on the long term a broader scope of constraints on different containers management platforms.

A detailed documentation about this proposal and its rationale can be found here.

What is an entitlement?

Entitlements enable or disable different security features in a configuration profile. The list of entitlements in a configuration profile specify the exact privilege and capabilities that a container is allowed to access.

The entitlement manager should be the source of truth regarding security configuration.

Design

libentitlement is designed to be a library managing container security profiles. It provides a way to register specific grants that add or remove constraints on those profiles.

A platform using libentitlement should initialize a set of entitlements with the following types:

• VoidEntitlement: entitlements without parameters
• IntEntitlement: entitlements with an int parameter
• StringEntitlement: entitlements with a string parameter

Entitlements can be initialize with two parameters:

• fullName: a string with the following format domain-name.identifier[=argument]
• callback: a entitlement enforcement callback that takes the following arguments:
  • a security profile honoring the security_profile.Profile interface (for now we use the specialized OCIProfile type)
  • an entitlement parameter if the entitlement needs one (other than VoidEntitlement)

Example

A quick example on how to use entitlements in your container manager:

/* security_profile.Profile is an abstract interface and
 * security_profile.OCIProfile is an implementation with OCI specs config.
 * We'll add abstract API access management in it. This is the security
 * profile to modify in your entitlement.
 * You should provide your own initialized OCI config to the entitlement manager.
 */
ociProfile := security_profile.NewOCIProfile(OCI_config)

/* Initialize an entitlement manager which manages entitlements and provide them with
 * an updated security profile
 */
entMgr := NewEntitlementsManager(ociProfile)

/* We can call our entitlement "cap-sys-admin" and have it under the "security.custom.caps" domain
 * Note: "security.custom.caps.cap-sys-admin" is different from "foobar.cap-sys-admin" as they are
 * in two different domains.
 */
capSysAdminEntFullName := "security.custom.cap-sys-admin"

/* This is where you implement your entitlements.
 * We can  for example initialize a void entitlement callback which adds the "CAP_SYS_ADMIN"
 * capability to a security profile.
 */
capSysAdminEntCallback := func (profile secprofile.Profile) (secprofile.Profile, error) {
    ociProfile, ok := profile.(*secprofile.OCIProfile)
    if !ok {
        return nil, fmt.Errorf("%s: error converting to OCI profile", capSysAdminEntFullName)
    }

    ociProfile.AddCaps("CAP_SYS_ADMIN")

    return ociProfile, nil
}

/* We create a void entitlement (no parameter) with the name and the callback */
capSysAdminVoidEnt := entitlement.NewVoidEntitlement(capSysAdminEntFullName, capSysAdminEntCallback)

/* Ask the entitlement manager to add it, entitlements are enforced when added */
err := entMgr.Add(capSysAdminVoidEnt)

This is as simple as that.

Default entitlements

Default entitlements can be found in defaults. They implement the entitlements in the proposal's table.

Currently implemented:

• network.none, network.user, network.proxy,network.admin
• security.confined, security.view, security.admin, security.memory-lock
• security.fs-read-only
• host.devices.none, host.devices.admin
• host.processes.none, host.processes.admin

Missing entitlements:

• debug

• resources limits/constraints: TBD

For Docker:

• engine.api

For Kubernetes: TBD

What's left

• Implement missing default entitlements for Moby and Kubernetes
• Provide more helper functions to configure security profiles in security_profile package
• Provide abstract API access management

Copyright and license

Code and documentation copyright 2017 Docker, inc. - All rights reserved.

Documentation

Index

• type EntitlementsManager
  • func NewEntitlementsManager(profile secprofile.Profile) *EntitlementsManager
  • func (m *EntitlementsManager) Add(entitlements ...entitlement.Entitlement) error
  • func (m *EntitlementsManager) AddDefault(entName string) error
  • func (m *EntitlementsManager) Enforce() error
  • func (m *EntitlementsManager) GetProfile() (secprofile.Profile, error)
  • func (m *EntitlementsManager) HasEntitlement(ent entitlement.Entitlement) (bool, error)
  • func (m *EntitlementsManager) SetProfile(profile secprofile.Profile) error

Types

type EntitlementsManager

type EntitlementsManager struct {
	// contains filtered or unexported fields
}

EntitlementsManager generates enforceable profiles from its entitlements and domains state

func NewEntitlementsManager

func NewEntitlementsManager(profile secprofile.Profile) *EntitlementsManager

NewEntitlementsManager instantiates an EntitlementsManager object with the given profile default

func (*EntitlementsManager) Add

func (m *EntitlementsManager) Add(entitlements ...entitlement.Entitlement) error

Add adds the given entitlements to the current entitlements list, updates the domain name system and enforce the entitlement on the security profile

func (*EntitlementsManager) AddDefault

func (m *EntitlementsManager) AddDefault(entName string) error

AddDefault adds a default entitlement identified by entName which must be a default identifier.

func (*EntitlementsManager) Enforce

func (m *EntitlementsManager) Enforce() error

Enforce applies the constraints on the security profile and updates it to be used for the container

func (*EntitlementsManager) GetProfile

func (m *EntitlementsManager) GetProfile() (secprofile.Profile, error)

GetProfile returns the current state of the security profile

func (*EntitlementsManager) HasEntitlement

func (m *EntitlementsManager) HasEntitlement(ent entitlement.Entitlement) (bool, error)

HasEntitlement returns whether the given entitlement is registered in the current entitlements list

func (*EntitlementsManager) SetProfile

func (m *EntitlementsManager) SetProfile(profile secprofile.Profile) error

SetProfile sets the entitlement manager's security profile