Adding object references security considerations

Clarifying practices around object references that help
prevent against privilege escalation.

1 files changed, 32 insertions, 0 deletions

diff --git a/contributors/devel/sig-architecture/api-conventions.md b/contributors/devel/sig-architecture/api-conventions.md
index 5c4c4a21..02ddfd7f 100644
--- a/contributors/devel/sig-architecture/api-conventions.md
+++ b/contributors/devel/sig-architecture/api-conventions.md
@@ -924,6 +924,38 @@ There are multiple scenarios where a desired resource may not exist. Examples in
 Controllers should be authored with the assumption that the referenced resource may not exist, and include
 error handling to make the issue clear to the user.
 
+### Validation of fields
+
+Many of the values used in an object reference are used as part of the API path. For example,
+the object name is used in the path to identify the object. Unsanitized, these values can be used to
+attempt to retrieve other resources, such as by using values with semantic meanings such as  `..` or `/`.
+
+Have the controller validate the field before using it as a reference, and emit an event to
+tell the user that the validation has failed.
+
+See [Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
+for more information on legal object names.
+
+### Do not modify the referred object
+
+To minimize potential privilege escalation vectors, do not modify the object that is being referred to.
+
+### Minimize copying or printing values to the referrer object
+
+As the permissions of the controller can differ from the permissions of the author of the object
+the controller is managing, it is possible that the author of the object may not have permissions to
+view the referred object. As a result, the copying of any values about the referred object to the
+referrer object can be considered permissions escalations, enabling a user to read values that they
+would not have access to previously.
+
+The same scenario applies to writing information about the referred object to events.
+
+In general, do not write or print information about the referred object to the spec, other objects, or logs.
+
+When it is necessary, consider whether these values would be ones that the
+author of the referrer object would have access to via other means (e.g. already required to
+correctly populate the object reference).
+
 ### Object References Examples
 
 The following sections illustrate recommended schemas for various object references scenarios.