Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 66 additions & 23 deletions docs/logging-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,29 +199,72 @@ run at `--verbosity=1` or higher.

## Fields that can hold personal data

These keys can carry user identities, group memberships, namespace names or
client IP addresses. Treat logs that contain them as personal data.
`go test ./hack/logref` fails when a logged key that looks like one of these
is missing here. Free-text values such as `reason`, `error` and `msg` can
also quote a user or namespace.

| Key | Content |
|-----|---------|
| `user` | Requesting user name (authorization decisions, SAR logs, CRD validation webhook context) |
| `username` | Requesting user name (namespace admission webhooks) |
| `groups` | Requesting user's groups (capped at 10) |
| `impersonatedUser` | ServiceAccount identity used for impersonated applies |
| `serviceAccount` | ServiceAccount name |
| `saName` | ServiceAccount name |
| `namespace` | Namespace name, which can name a team or person |
| `saNamespace` | ServiceAccount namespace |
| `targetNamespace` | Target namespace name |
| `bindingNamespace` | Namespace of a generated RoleBinding |
| `explicitNamespace` | Namespace named explicitly in a BindDefinition |
| `objectNamespace` | Namespace of the object that triggered a reconcile |
| `activeNamespaceNames` | Namespace names a BindDefinition selects |
| `path` | Non-resource URL path |
| `remoteAddr` | Client IP address and port of `/authorize` callers (`V(2)`) |
These keys can carry user identities, group memberships, namespace, object or
node names, label values or client IP addresses. Treat logs that contain them
as personal data. Each key has the personal-data class and the data subject of
the platform logging contract; a key that can hold data of several subjects
names the highest (`end-customer` > `tenant-user` > `operator`). *From level*
is the least verbose level that logs the key, so the key is absent below it
(`error` lines are always written). `go test ./hack/logref` fails when a logged
key is neither in this table nor in `notPersonalKeys` in
`hack/logref/logref_test.go` (the keys without personal data), either list names
a key that is not logged, a class or subject is not one of these values, or the
level is wrong.

Tenants create `RestrictedBindDefinition` and `RestrictedRoleDefinition`
objects and choose their names and target names, so keys that can hold these
names, or the names of the Roles and RoleBindings generated from them, are
listed. Keys that name only platform-defined resources (`bindDefinition`,
`roleDefinition`, `policy`, ...) hold platform configuration and are in
`notPersonalKeys`.

| Key | Class | Data subject | From level | Content |
|-----|-------|--------------|------------|---------|
| `user` | `tenant-pii` | `tenant-user` | `error` | Requesting user name, can be an e-mail address (authorization decisions, SAR logs, CRD validation webhook context) |
| `username` | `tenant-pii` | `tenant-user` | `V(0)` | Requesting user name (namespace admission webhooks) |
| `groups` | `tenant-pii` | `tenant-user` | `V(0)` | Requesting user's groups (capped at 10) |
| `impersonatedUser` | `tenant-pii` | `tenant-user` | `V(2)` | ServiceAccount identity used for impersonated applies |
| `serviceAccount` | `tenant-pii` | `tenant-user` | `error` | ServiceAccount name |
| `saName` | `tenant-pii` | `tenant-user` | `V(3)` | ServiceAccount name |
| `namespace` | `tenant-pii` | `tenant-user` | `error` | Namespace name, which can name a team or person |
| `saNamespace` | `tenant-pii` | `tenant-user` | `error` | ServiceAccount namespace |
| `targetNamespace` | `tenant-pii` | `tenant-user` | `error` | Target namespace name |
| `bindingNamespace` | `tenant-pii` | `tenant-user` | `V(0)` | Namespace of a generated RoleBinding |
| `explicitNamespace` | `tenant-pii` | `tenant-user` | `V(4)` | Namespace named explicitly in a BindDefinition |
| `objectNamespace` | `tenant-pii` | `tenant-user` | `V(2)` | Namespace of the object that triggered a reconcile |
| `activeNamespaceNames` | `tenant-pii` | `tenant-user` | `V(2)` | Namespace names a BindDefinition selects |
| `name` | `tenant-pii` | `tenant-user` | `error` | Name of the object a line is about: a tenant's namespace or pod, an auth-operator resource, or a flag |
| `objectName` | `tenant-pii` | `tenant-user` | `V(2)` | Name of the namespace that triggered a BindDefinition reconcile |
| `node` | `tenant-pii` | `tenant-user` | `V(0)` | Node of the pod the pod deletion guard decided on |
| `targetNode` | `tenant-pii` | `tenant-user` | `V(0)` | Node named in the pod deletion guard ConfigMap |
| `value` | `tenant-pii` | `tenant-user` | `V(2)` | Namespace label value (namespace mutating webhook); flag value in the `V(3)` flag dump, redacted for credentials |
| `existingValue` | `tenant-pii` | `tenant-user` | `V(1)` | Conflicting label value already on the target namespace |
| `inheritedValue` | `tenant-pii` | `tenant-user` | `V(1)` | Label value a ServiceAccount's namespace would pass on |
| `oldValue` | `tenant-pii` | `tenant-user` | `V(2)` | Namespace label value before a change |
| `newValue` | `tenant-pii` | `tenant-user` | `V(2)` | Namespace label value after a change |
| `removedValue` | `tenant-pii` | `tenant-user` | `V(1)` | Value of a removed namespace label |
| `rbd` | `tenant-pii` | `tenant-user` | `V(0)` | RestrictedBindDefinition name, chosen by a tenant |
| `restrictedBindDefinition` | `tenant-pii` | `tenant-user` | `V(1)` | RestrictedBindDefinition name, chosen by a tenant |
| `currentName` | `tenant-pii` | `tenant-user` | `V(0)` | Name of a RestrictedBindDefinition that conflicts with an owner |
| `ownerName` | `tenant-pii` | `tenant-user` | `V(0)` | Name of the RestrictedBindDefinition that owns a binding |
| `rrd` | `tenant-pii` | `tenant-user` | `V(0)` | RestrictedRoleDefinition name, chosen by a tenant |
| `restrictedRoleDefinition` | `tenant-pii` | `tenant-user` | `V(1)` | RestrictedRoleDefinition name, chosen by a tenant |
| `owner` | `tenant-pii` | `tenant-user` | `V(0)` | Name of the BindDefinition, RoleDefinition or restricted definition that owns a generated object |
| `existingOwner` | `tenant-pii` | `tenant-user` | `V(0)` | Name of the object that already owns a generated Role or binding |
| `targetName` | `tenant-pii` | `tenant-user` | `error` | Name of the Role or binding a definition generates; a tenant chooses it for restricted definitions |
| `roleName` | `tenant-pii` | `tenant-user` | `error` | Name of a generated or referenced Role or ClusterRole |
| `role` | `tenant-pii` | `tenant-user` | `error` | Name of a Role, including Roles generated from RestrictedRoleDefinitions |
| `clusterRole` | `tenant-pii` | `tenant-user` | `error` | Name of a ClusterRole, including ClusterRoles generated from RestrictedRoleDefinitions |
| `bindingName` | `tenant-pii` | `tenant-user` | `V(0)` | Name of a generated RoleBinding or ClusterRoleBinding |
| `roleBinding` | `tenant-pii` | `tenant-user` | `error` | Name of a RoleBinding in a namespace being deleted, which a tenant can have created |
| `roleBindingName` | `tenant-pii` | `tenant-user` | `error` | Name of a generated RoleBinding, or of a tenant's RoleBinding in a namespace being deleted |
| `reference` | `tenant-pii` | `tenant-user` | `V(1)` | External ServiceAccount reference (`namespace/name`) |
| `violations` | `tenant-pii` | `tenant-user` | `V(0)` | Policy violation texts; they quote namespace and role names |
| `reason` | `tenant-pii` | `tenant-user` | `V(0)` | Free text; can quote a user, group or namespace |
| `detail` | `tenant-pii` | `tenant-user` | `V(1)` | Free text; can quote a user, group or namespace |
| `error` | `tenant-pii` | `tenant-user` | `V(0)` | Error text; can quote a user, group, namespace or object name |
| `path` | `customer-data` | `tenant-user` | `V(0)` | Non-resource URL path a user requested |
| `remoteAddr` | `customer-data` | `end-customer` | `V(2)` | Client IP address and port of `/authorize` callers: the API server, or any client that reaches the endpoint |

## Never logged

Expand Down
120 changes: 106 additions & 14 deletions hack/logref/logref_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -376,14 +376,36 @@ func catalog(entries []entry, withValues map[string][]string) string {
return b.String()
}

var (
// personalData matches log keys that can hold a user identity, group,
// namespace name, URL path or client address.
personalData = regexp.MustCompile(`(?i)user|groups$|namespace|addr|^path$|serviceaccount$|^saname$`)
// notPersonalData excludes counts, flags, listen addresses and
// configuration among them (userKey: the name of a ConfigMap data key).
notPersonalData = regexp.MustCompile(`Count$|^total|^is[A-Z]|^userKey$|(?i:tenant|selector|ownership|-bind-address$|^matchingnamespaces$)`)
)
// notPersonalKeys lists every logged key that holds no personal data: counts,
// flags, configuration, kinds, platform resource names and RBAC object names
// the platform defines. A logged key must be here or in the table under
// "## Fields that can hold personal data", so a new key fails the test until
// it is classified.
var notPersonalKeys = strings.Fields(`
activeNamespaceCount allowProtectedLabelChanges allowed apiGroup apiGroupCount authorizer bdIndex
bindDefinition bindDefinitionConcurrency bindDefinitionCount bindDefinitionName
bindDefinitionNamespaceSelectorLabelGroups bindingKind blockingResourceCount burst bypassReason
cacheAge cacheSyncTimeout capiOperatorUpdateBypass certsDir clusterRoleBindingName clusterRoleName
clusterRoleRef clusterRoleRefCount clusterRoleRefs commit concurrency conflictsWith count crbCount
crd currentUID decision deletionTimestamp disableCertRotation duration emergencyNamespaceCrossTenant
emergencyNamespaceTenant enableHTTP2 enableLeaderElection endpoint evaluatedCount existingOwnerKind
existingOwnerUID externalCount externalSAs extraKey fieldManagers generatedCount generatedSACount
generatedSAs generation got gracefulShutdownTimeout group groupCount groupVersion gvk gvr
health-probe-bind-address index isAggregating isDeleting isServiceAccount itemCount kind label
labelCount latency legacyOwner logFormat matchedField matchedRule matchingNamespaces method
metrics-bind-address missingCount missingRoleRefCount missingRoles mode namespaceCount newOwner
nodeKey observedGeneration oldOwner operation ownerError ownerUID phase policy policyRef port
rateLimit rbCount rbIndex rbacPolicy rbacPolicyConcurrency removedLabel requestCount requeueAfter
requiredGVKs resource resourceType resourceVersion resourcesChecked resourcesSkipped
restrictedBindDefinitionConcurrency restrictedBindDefinitions restrictedRoleDefinitionConcurrency
restrictedRoleDefinitions result roleBindingCount roleBindingIndex roleBindingSpecCount roleBindings
roleDefinition roleDefinitionConcurrency roleDefinitionCount roleDefinitionName ruleCount rulesCount
samplingRate selectedPolicy selector selectorCount selectorIndex serverVersion skipUpdateLabelChecks
skippedCount status strictSANamespaceOwnership subjectCount subjects targetConfigMap targetRole
tdgMigration timeout totalBindDefinitions totalBound totalNamespaces trackerResyncInterval
trackerSyncInterval usage userKey verb verbosity version violationCount webhook webhookAuthorizer
webhookAuthorizerConcurrency
`)

// assertSameKeys fails unless the documented keys equal the code keys.
func assertSameKeys(t *testing.T, heading string, documented []string, code map[string]bool) {
Expand Down Expand Up @@ -454,6 +476,7 @@ func TestLoggingReference(t *testing.T) {
checkLevels(t, doc, entries)
checkDecisions(t, doc, entries)
checkPersonalData(t, doc, codeKeys)
checkPersonalDataColumns(t, doc, entries, withValues)

// Nothing that names a credential is logged.
secret := regexp.MustCompile(`(?i)token|password|passphrase|secret|credential|bearer|private`)
Expand Down Expand Up @@ -601,15 +624,84 @@ func TestRejectionRowsCheckLevels(t *testing.T) {
}
}

// checkPersonalData compares the personal-data table exactly with the logged
// keys that can hold an identity, group, namespace name, path or address.
// checkPersonalData requires every logged key to be either in the
// personal-data table or in notPersonalKeys, and neither list to name a key
// that is not logged.
func checkPersonalData(t *testing.T, doc string, codeKeys map[string]bool) {
t.Helper()
pii := map[string]bool{}
const heading = "## Fields that can hold personal data"
table := tableKeys(t, doc, heading)
for k := range codeKeys {
if personalData.MatchString(k) && !notPersonalData.MatchString(k) {
pii[k] = true
if !slices.Contains(table, k) && !slices.Contains(notPersonalKeys, k) {
t.Errorf("log key %q is neither under %q nor in notPersonalKeys (hack/logref/logref_test.go): classify it", k, heading)
}
}
for _, k := range table {
if !codeKeys[k] {
t.Errorf("%q under %q is not logged", k, heading)
}
if slices.Contains(notPersonalKeys, k) {
t.Errorf("%q is both under %q and in notPersonalKeys", k, heading)
}
}
for _, k := range notPersonalKeys {
if !codeKeys[k] {
t.Errorf("notPersonalKeys lists %q, which no log call uses: remove it", k)
}
}
}

// checkPersonalDataColumns requires every row of the personal-data table to
// name a personal-data class and data subject of the platform logging
// contract, and the least verbose level that logs the key.
func checkPersonalDataColumns(t *testing.T, doc string, entries []entry, withValues map[string][]string) {
t.Helper()
const heading = "## Fields that can hold personal data"
section := doc[strings.Index(doc, heading):]
section = section[:strings.Index(section, "\n## ")]
rows := 0
for _, row := range strings.Split(section, "\n") {
cells := strings.Split(row, "|")
if !strings.HasPrefix(row, "| `") {
continue
}
rows++
if len(cells) != 7 {
t.Errorf("row %q under %q needs the columns Key, Class, Data subject, From level and Content", row, heading)
continue
}
key, class, subject, level := strings.Trim(strings.TrimSpace(cells[1]), "`"), strings.TrimSpace(cells[2]),
strings.TrimSpace(cells[3]), strings.Trim(strings.TrimSpace(cells[4]), "`")
if class != "`tenant-pii`" && class != "`customer-data`" {
t.Errorf("%q under %q: class %s is not `tenant-pii` or `customer-data`", key, heading, class)
}
if !slices.Contains([]string{"`operator`", "`tenant-user`", "`end-customer`"}, subject) {
t.Errorf("%q under %q: data subject %s is not `operator`, `tenant-user` or `end-customer`", key, heading, subject)
}
if want := leastVerboseLevel(key, entries, withValues); level != want {
t.Errorf("%q under %q: level is %s, but the least verbose level that logs it is %s", key, heading, level, want)
}
}
if rows == 0 {
t.Fatalf("%s: no rows under %q", docPath, heading)
}
}

// leastVerboseLevel returns the least verbose level of the lines that carry
// key, as a call key or through WithValues in the file of the line.
func leastVerboseLevel(key string, entries []entry, withValues map[string][]string) string {
best, bestRank := "", 1<<30
for _, e := range entries {
if !slices.Contains(e.keys, key) && !slices.Contains(withValues[e.file], key) {
continue
}
rank := -1 // error
if e.level != "error" {
rank, _ = strconv.Atoi(strings.TrimSuffix(strings.TrimPrefix(e.level, "V("), ")"))
}
if rank < bestRank {
best, bestRank = e.level, rank
}
}
assertSameKeys(t, "## Fields that can hold personal data", tableKeys(t, doc, "## Fields that can hold personal data"), pii)
return best
}
Loading