package securitypolicy

import "github.com/Microsoft/hcsshim/pkg/securitypolicy"

Index

Constants

const (
	SecurityContextDirTemplate = "security-context-*"
	PolicyFilename             = "security-policy-base64"
	HostAMDCertFilename        = "host-amd-cert-base64"
	ReferenceInfoFilename      = "reference-info-base64"
)

Variables

var APICode = strings.Replace(apiCodeTemplate, "@@API_VERSION@@", apiVersion, 1)
var ErrInvalidOpenDoorPolicy = errors.New("allow_all cannot be set to 'true' when Containers are non-empty")
var FrameworkCode = strings.Replace(frameworkCodeTemplate, "@@FRAMEWORK_VERSION@@", frameworkVersion, 1)

Functions

func DefaultPrivilegedCapabilities

func DefaultPrivilegedCapabilities() []string

func DefaultUnprivilegedCapabilities

func DefaultUnprivilegedCapabilities() []string

func EmptyCapabiltiesSet

func EmptyCapabiltiesSet() []string

func ExtractPolicyDecision

func ExtractPolicyDecision(errorMessage string) (string, error)

func MarshalFragment

func MarshalFragment(
	namespace string,
	svn string,
	containers []*Container,
	externalProcesses []ExternalProcessConfig,
	fragments []FragmentConfig) (string, error)

func MarshalPolicy

func MarshalPolicy(
	marshaller string,
	allowAll bool,
	containers []*Container,
	externalProcesses []ExternalProcessConfig,
	fragments []FragmentConfig,
	allowPropertiesAccess bool,
	allowDumpStacks bool,
	allowRuntimeLogging bool,
	allowEnvironmentVariableDropping bool,
	allowUnencryptedScratch bool,
	allowCapbilitiesDropping bool,
) (string, error)

func MeasureSeccompProfile

func MeasureSeccompProfile(seccomp *specs.LinuxSeccomp) (string, error)

func NewSecurityPolicyDigest

func NewSecurityPolicyDigest(base64policy string) ([]byte, error)

NewSecurityPolicyDigest decodes base64 encoded policy string, computes and returns sha256 digest

Types

type AuthConfig

type AuthConfig struct {
	Username string `json:"username" toml:"username"`
	Password string `json:"password" toml:"password"`
}

AuthConfig contains toml or JSON config for registry authentication.

type CapabilitiesConfig

type CapabilitiesConfig struct {
	Bounding    []string `json:"bounding" toml:"bounding"`
	Effective   []string `json:"effective" toml:"effective"`
	Inheritable []string `json:"inheritable" toml:"inheritable"`
	Permitted   []string `json:"permitted" toml:"permitted"`
	Ambient     []string `json:"ambient" toml:"ambient"`
}

CapabilitiesConfig contains the toml or JSON config for capabilies security polict constraint description

type CommandArgs

type CommandArgs StringArrayMap

func (CommandArgs) MarshalJSON

func (c CommandArgs) MarshalJSON() ([]byte, error)

type Container

type Container struct {
	Command              CommandArgs         `json:"command"`
	EnvRules             EnvRules            `json:"env_rules"`
	Layers               Layers              `json:"layers"`
	WorkingDir           string              `json:"working_dir"`
	Mounts               Mounts              `json:"mounts"`
	AllowElevated        bool                `json:"allow_elevated"`
	ExecProcesses        []ExecProcessConfig `json:"-"`
	Signals              []syscall.Signal    `json:"-"`
	AllowStdioAccess     bool                `json:"-"`
	NoNewPrivileges      bool                `json:"-"`
	User                 UserConfig          `json:"-"`
	Capabilities         *CapabilitiesConfig `json:"-"`
	SeccompProfileSHA256 string              `json:"-"`
}

func CreateContainerPolicy

func CreateContainerPolicy(
	command, layers []string,
	envRules []EnvRuleConfig,
	workingDir string,
	mounts []MountConfig,
	allowElevated bool,
	execProcesses []ExecProcessConfig,
	signals []syscall.Signal,
	allowStdioAccess bool,
	noNewPrivileges bool,
	user UserConfig,
	capabilities *CapabilitiesConfig,
	seccompProfileSHA256 string,
) (*Container, error)

CreateContainerPolicy creates a new Container policy instance from the provided constraints or an error if parameter validation fails.

type ContainerConfig

type ContainerConfig struct {
	ImageName                string              `json:"image_name" toml:"image_name"`
	Command                  []string            `json:"command" toml:"command"`
	Auth                     AuthConfig          `json:"auth" toml:"auth"`
	EnvRules                 []EnvRuleConfig     `json:"env_rules" toml:"env_rule"`
	WorkingDir               string              `json:"working_dir" toml:"working_dir"`
	Mounts                   []MountConfig       `json:"mounts" toml:"mount"`
	AllowElevated            bool                `json:"allow_elevated" toml:"allow_elevated"`
	ExecProcesses            []ExecProcessConfig `json:"exec_processes" toml:"exec_process"`
	Signals                  []syscall.Signal    `json:"signals" toml:"signals"`
	AllowStdioAccess         bool                `json:"allow_stdio_access" toml:"allow_stdio_access"`
	AllowPrivilegeEscalation bool                `json:"allow_privilege_escalation" toml:"allow_privilege_escalation"`
	User                     *UserConfig         `json:"user" toml:"user"`
	Capabilities             *CapabilitiesConfig `json:"capabilities" toml:"capabilities"`
	SeccompProfilePath       string              `json:"seccomp_profile_path" toml:"seccomp_profile_path"`
}

ContainerConfig contains toml or JSON config for container described in security policy.

type ContainerConfigOpt

type ContainerConfigOpt func(config *ContainerConfig) error

func WithAllowElevated

func WithAllowElevated(elevated bool) ContainerConfigOpt

WithAllowElevated allows container to run in an elevated/privileged mode.

func WithAllowPrivilegeEscalation

func WithAllowPrivilegeEscalation(allow bool) ContainerConfigOpt

WithAllowPrivilegeEscalation allows escalating of privileges by clearing the NoNewPrivileges flag

func WithAllowStdioAccess

func WithAllowStdioAccess(stdio bool) ContainerConfigOpt

WithAllowStdioAccess enables or disables container init process stdio.

func WithCapabilities

func WithCapabilities(capabilities *CapabilitiesConfig) ContainerConfigOpt

WithCapabilities sets capabilities in container policy config.

func WithCommand

func WithCommand(cmd []string) ContainerConfigOpt

WithCommand sets ContainerConfig.Command in container policy config.

func WithEnvVarRules

func WithEnvVarRules(envs []EnvRuleConfig) ContainerConfigOpt

WithEnvVarRules adds environment variable constraints to container policy config.

func WithExecProcesses

func WithExecProcesses(execs []ExecProcessConfig) ContainerConfigOpt

WithExecProcesses allows specified exec processes.

func WithMountConstraints

func WithMountConstraints(mc []MountConfig) ContainerConfigOpt

WithMountConstraints extends ContainerConfig.Mounts with provided mount constraints.

func WithSeccompProfilePath

func WithSeccompProfilePath(path string) ContainerConfigOpt

WithSeccompProfilePath sets seccomp profile path in container policy config.

func WithUser

func WithUser(user UserConfig) ContainerConfigOpt

WithUser sets user in container policy config.

func WithWorkingDir

func WithWorkingDir(wd string) ContainerConfigOpt

WithWorkingDir sets working directory in container policy config.

type Containers

type Containers struct {
	Length   int                  `json:"length"`
	Elements map[string]Container `json:"elements"`
}

func (Containers) MarshalJSON

func (c Containers) MarshalJSON() ([]byte, error)

type EncodedSecurityPolicy

type EncodedSecurityPolicy struct {
	SecurityPolicy string `json:"SecurityPolicy,omitempty"`
}

EncodedSecurityPolicy is a JSON representation of SecurityPolicy that has been base64 encoded for storage in an annotation embedded within another JSON configuration

type EnvRuleConfig

type EnvRuleConfig struct {
	Strategy EnvVarRule `json:"strategy" toml:"strategy"`
	Rule     string     `json:"rule" toml:"rule"`
	Required bool       `json:"required" toml:"required"`
}

EnvRuleConfig contains toml or JSON config for environment variable security policy enforcement.

func NewEnvVarRules

func NewEnvVarRules(envVars []string, required bool) []EnvRuleConfig

NewEnvVarRules creates slice of EnvRuleConfig's from environment variables strings slice.

type EnvRules

type EnvRules struct {
	Length   int                      `json:"length"`
	Elements map[string]EnvRuleConfig `json:"elements"`
}

func (EnvRules) MarshalJSON

func (e EnvRules) MarshalJSON() ([]byte, error)

type EnvVarRule

type EnvVarRule string
const (
	EnvVarRuleString EnvVarRule = "string"
	EnvVarRuleRegex  EnvVarRule = "re2"
)

type ExecProcessConfig

type ExecProcessConfig struct {
	Command []string         `json:"command" toml:"command"`
	Signals []syscall.Signal `json:"signals" toml:"signals"`
}

ExecProcessConfig contains toml or JSON config for exec process security policy constraint description

type ExternalProcessConfig

type ExternalProcessConfig struct {
	Command          []string `json:"command" toml:"command"`
	WorkingDir       string   `json:"working_dir" toml:"working_dir"`
	AllowStdioAccess bool     `json:"allow_stdio_access" toml:"allow_stdio_access"`
}

ExternalProcessConfig contains toml or JSON config for running external processes in the UVM.

type FragmentConfig

type FragmentConfig struct {
	Issuer     string   `json:"issuer" toml:"issuer"`
	Feed       string   `json:"feed" toml:"feed"`
	MinimumSVN string   `json:"minimum_svn" toml:"minimum_svn"`
	Includes   []string `json:"includes" toml:"include"`
}

FragmentConfig contains toml or JSON config for including elements from fragments.

type IDName

type IDName struct {
	ID   string
	Name string
}

type IDNameConfig

type IDNameConfig struct {
	Strategy IDNameStrategy `json:"strategy" toml:"strategy"`
	Rule     string         `json:"rule" toml:"rule"`
}

type IDNameStrategy

type IDNameStrategy string
const (
	IDNameStrategyName  IDNameStrategy = "name"
	IDNameStrategyID    IDNameStrategy = "id"
	IDNameStrategyRegex IDNameStrategy = "re2"
	IDNameStrategyAny   IDNameStrategy = "any"
)

type Layers

type Layers StringArrayMap

func (Layers) MarshalJSON

func (l Layers) MarshalJSON() ([]byte, error)

type Mount

type Mount struct {
	Source      string  `json:"source"`
	Destination string  `json:"destination"`
	Type        string  `json:"type"`
	Options     Options `json:"options"`
}

type MountConfig

type MountConfig struct {
	HostPath      string `json:"host_path" toml:"host_path"`
	ContainerPath string `json:"container_path" toml:"container_path"`
	Readonly      bool   `json:"readonly" toml:"readonly"`
}

MountConfig contains toml or JSON config for mount security policy constraint description.

type Mounts

type Mounts struct {
	Length   int              `json:"length"`
	Elements map[string]Mount `json:"elements"`
}

func (Mounts) MarshalJSON

func (m Mounts) MarshalJSON() ([]byte, error)

type Options

type Options StringArrayMap

func (Options) MarshalJSON

func (o Options) MarshalJSON() ([]byte, error)

type PolicyConfig

type PolicyConfig struct {
	AllowAll                         bool                    `json:"allow_all" toml:"allow_all"`
	Containers                       []ContainerConfig       `json:"containers" toml:"container"`
	ExternalProcesses                []ExternalProcessConfig `json:"external_processes" toml:"external_process"`
	Fragments                        []FragmentConfig        `json:"fragments" toml:"fragment"`
	AllowPropertiesAccess            bool                    `json:"allow_properties_access" toml:"allow_properties_access"`
	AllowDumpStacks                  bool                    `json:"allow_dump_stacks" toml:"allow_dump_stacks"`
	AllowRuntimeLogging              bool                    `json:"allow_runtime_logging" toml:"allow_runtime_logging"`
	AllowEnvironmentVariableDropping bool                    `json:"allow_environment_variable_dropping" toml:"allow_environment_variable_dropping"`
	// AllowUnencryptedScratch is a global policy configuration that allows
	// all containers within a pod to be run without scratch encryption.
	AllowUnencryptedScratch bool `json:"allow_unencrypted_scratch" toml:"allow_unencrypted_scratch"`
	AllowCapabilityDropping bool `json:"allow_capability_dropping" toml:"allow_capability_dropping"`
}

PolicyConfig contains toml or JSON config for security policy.

func NewPolicyConfig

func NewPolicyConfig(opts ...PolicyConfigOpt) (*PolicyConfig, error)

type PolicyConfigOpt

type PolicyConfigOpt func(config *PolicyConfig) error

func WithAllowCapabilityDropping

func WithAllowCapabilityDropping(allow bool) PolicyConfigOpt

func WithAllowDumpStacks

func WithAllowDumpStacks(allow bool) PolicyConfigOpt

func WithAllowEnvVarDropping

func WithAllowEnvVarDropping(allow bool) PolicyConfigOpt

func WithAllowPropertiesAccess

func WithAllowPropertiesAccess(allow bool) PolicyConfigOpt

func WithAllowRuntimeLogging

func WithAllowRuntimeLogging(allow bool) PolicyConfigOpt

func WithAllowUnencryptedScratch

func WithAllowUnencryptedScratch(allow bool) PolicyConfigOpt

func WithContainers

func WithContainers(containers []ContainerConfig) PolicyConfigOpt

WithContainers adds containers to security policy.

func WithExternalProcesses

func WithExternalProcesses(processes []ExternalProcessConfig) PolicyConfigOpt

type SecurityPolicy

type SecurityPolicy struct {
	// Flag that when set to true allows for all checks to pass. Currently, used
	// to run with security policy enforcement "running dark"; checks can be in
	// place but the default policy that is created on startup has AllowAll set
	// to true, thus making policy enforcement effectively "off" from a logical
	// standpoint. Policy enforcement isn't actually off as the policy is "allow
	// everything".
	AllowAll bool `json:"allow_all"`
	// One or more containers that are allowed to run
	Containers Containers `json:"containers"`
}

func NewOpenDoorPolicy

func NewOpenDoorPolicy() *SecurityPolicy

NewOpenDoorPolicy creates a new SecurityPolicy with AllowAll set to `true`

func NewSecurityPolicy

func NewSecurityPolicy(allowAll bool, containers []*Container) *SecurityPolicy

NewSecurityPolicy creates a new SecurityPolicy from the provided values.

func (*SecurityPolicy) EncodeToString

func (sp *SecurityPolicy) EncodeToString() (string, error)

EncodeToString returns base64 encoded string representation of SecurityPolicy.

type StringArrayMap

type StringArrayMap struct {
	Length   int               `json:"length"`
	Elements map[string]string `json:"elements"`
}

StringArrayMap wraps an array of strings as a string map.

func (StringArrayMap) MarshalJSON

func (s StringArrayMap) MarshalJSON() ([]byte, error)

type UserConfig

type UserConfig struct {
	UserIDName   IDNameConfig   `json:"user_idname" toml:"user_idname"`
	GroupIDNames []IDNameConfig `json:"group_idnames" toml:"group_idname"`
	Umask        string         `json:"umask" toml:"umask"`
}

Source Files

opts.go securitypolicy.go securitypolicy_internal.go securitypolicy_marshal.go

Version
v0.13.0 (latest)
Published
Apr 21, 2025
Platform
windows/amd64
Imports
12 packages
Last checked
10 hours ago

Tools for package owners.