1# Security Policy
2
3This package contains the logic for enabling users to express an attested
4security policy. This policy provides a series of enforcement points. Each
5enforcement point contrains one action that the host requests of the guest.
6The security policies are expressed in
7[Rego](https://www.openpolicyagent.org/docs/latest/policy-language/),
8a policy language designed for use in scenarios like this one.
9
10We provide a [framework](./framework.rego) that users can employ to make
11writing policies easier, but there is no requirement for this framework
12to be used. Valid policies only need to define the enforcement points which
13are enumerated in the [API](./api.rego) namespace.
14
15## Adding a New Enforcement Point
16
17When adding a new enforcement point, care must be taken to ensure that it is
18correctly connected to the rest of the codebase and properly supported.
19Here is a helpful checklist:
20
211. Add the enforcment point to the
22 [`SecurityPolicyEnforcer`](./securitypolicyenforcer.go) interface.
232. Add stub implementations of the enforcement point to all classes which
24 implement the interface. Some files to look at:
25 - [`mountmonitoringsecuritypolicyenforcer.go`](../../internal/guest/storage/test/policy/mountmonitoringsecuritypolicyenforcer.go)
26 - [`securitypolicyenforcer.go`](./securitypolicyenforcer.go)
27 - [`securitypolicyenforcer_rego.go`](./securitypolicyenforcer_rego.go)
283. Wrap the call in [`uvm.go`](../../internal/guest/runtime/hcsv2/uvm.go)
29 so that it will not happen unless the security policy says it is OK.
304. Add the enforcement point to [`api.rego`](./api.rego) and bump one minor
31 version.
325. Add the enforcement point rule to [`policy.rego`](./policy.rego) and
33 [`open_door.rego`](./open_door.rego).
346. Add the enforcement point rule logic to [`framework.rego`](./framework.rego)
357. Add useful error messages to [`framework.rego`](./framework.rego). Be sure
36 to gate them with the rule name.
378. Update the internal representations of the policy in
38 [`securitypolicy_internal.go`](./securitypolicy_internal.go) to contain any
39 constraint objects which are needed by the framework logic.
409. Update the Rego marshalling code in
41 [`securitypolicy_marshal.go`](./securitypolicy_marshal.go) to emit the
42 constraint objects which you added in the previous step.
4310. In [`securitypolicyenforcer_rego.go`](./securitypolicyenforcer_rego.go), fill
44 out the stub with the input needed for the framework logic.
4511. Add tests to [`regopolicy_test.go`](./regopolicy_test.go). As a rule, you
46 should add one test which verifies that the rule enforces things correctly,
47 and then at least one test per error condition. Be sure to test that the
48 error messages you are emitting are present in the error message.
View as plain text