Categorygithub.com/Microsoft/hcsshimpkgsecuritypolicy
package
0.13.0-rc.2
Repository: https://github.com/microsoft/hcsshim.git
Documentation: pkg.go.dev
Versions
1
Dependencies
15
Dependents
6
Files
2.1k SLOC

# README

Security Policy

This package contains the logic for enabling users to express an attested security policy. This policy provides a series of enforcement points. Each enforcement point contrains one action that the host requests of the guest. The security policies are expressed in Rego, a policy language designed for use in scenarios like this one.

We provide a framework that users can employ to make writing policies easier, but there is no requirement for this framework to be used. Valid policies only need to define the enforcement points which are enumerated in the API namespace.

Adding a New Enforcement Point

When adding a new enforcement point, care must be taken to ensure that it is correctly connected to the rest of the codebase and properly supported. Here is a helpful checklist:

  1. Add the enforcment point to the SecurityPolicyEnforcer interface.
  2. Add stub implementations of the enforcement point to all classes which implement the interface. Some files to look at:
  3. Wrap the call in uvm.go so that it will not happen unless the security policy says it is OK.
  4. Add the enforcement point to api.rego and bump one minor version.
  5. Add the enforcement point rule to policy.rego and open_door.rego.
  6. Add the enforcement point rule logic to framework.rego
  7. Add useful error messages to framework.rego. Be sure to gate them with the rule name.
  8. Update the internal representations of the policy in securitypolicy_internal.go to contain any constraint objects which are needed by the framework logic.
  9. Update the Rego marshalling code in securitypolicy_marshal.go to emit the constraint objects which you added in the previous step.
  10. In securitypolicyenforcer_rego.go, fill out the stub with the input needed for the framework logic.
  11. Add tests to regopolicy_test.go. As a rule, you should add one test which verifies that the rule enforces things correctly, and then at least one test per error condition. Be sure to test that the error messages you are emitting are present in the error message.

# Functions

CreateContainerPolicy creates a new Container policy instance from the provided constraints or an error if parameter validation fails.
CreateSecurityPolicyEnforcer returns an appropriate enforcer for input parameters.
NewEnvVarRules creates slice of EnvRuleConfig's from environment variables strings slice.
NewOpenDoorPolicy creates a new SecurityPolicy with AllowAll set to `true`.
NewSecurityPolicy creates a new SecurityPolicy from the provided values.
NewSecurityPolicyDigest decodes base64 encoded policy string, computes and returns sha256 digest.
WithAllowElevated allows container to run in an elevated/privileged mode.
WithAllowPrivilegeEscalation allows escalating of privileges by clearing the NoNewPrivileges flag.
WithAllowStdioAccess enables or disables container init process stdio.
WithCapabilities sets capabilities in container policy config.
WithCommand sets ContainerConfig.Command in container policy config.
WithContainers adds containers to security policy.
WithEnvVarRules adds environment variable constraints to container policy config.
WithExecProcesses allows specified exec processes.
WithMountConstraints extends ContainerConfig.Mounts with provided mount constraints.
WithPrivilegedMounts converts the input mounts to internal mount constraints and extends existing internal mount constraints if the container is allowed to be executed in elevated mode.
WithSeccompProfilePath sets seccomp profile path in container policy config.
WithUser sets user in container policy config.
WithWorkingDir sets working directory in container policy config.

# Constants

# Variables

# Structs

AuthConfig contains toml or JSON config for registry authentication.
CapabilitiesConfig contains the toml or JSON config for capabilies security polict constraint description.
ContainerConfig contains toml or JSON config for container described in security policy.
EncodedSecurityPolicy is a JSON representation of SecurityPolicy that has been base64 encoded for storage in an annotation embedded within another JSON configuration.
EnvRuleConfig contains toml or JSON config for environment variable security policy enforcement.
ExecProcessConfig contains toml or JSON config for exec process security policy constraint description.
ExternalProcessConfig contains toml or JSON config for running external processes in the UVM.
FragmentConfig contains toml or JSON config for including elements from fragments.
MountConfig contains toml or JSON config for mount security policy constraint description.
PolicyConfig contains toml or JSON config for security policy.
StandardSecurityPolicyEnforcer implements SecurityPolicyEnforcer interface and is responsible for enforcing various SecurityPolicy constraints.
StringArrayMap wraps an array of strings as a string map.

# Interfaces

# Type aliases