1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.cloud.policysimulator.v1; 18 19import "google/api/field_behavior.proto"; 20import "google/iam/v1/policy.proto"; 21import "google/type/expr.proto"; 22 23option cc_enable_arenas = true; 24option csharp_namespace = "Google.Cloud.PolicySimulator.V1"; 25option go_package = "cloud.google.com/go/policysimulator/apiv1/policysimulatorpb;policysimulatorpb"; 26option java_multiple_files = true; 27option java_outer_classname = "ExplanationsProto"; 28option java_package = "com.google.cloud.policysimulator.v1"; 29option php_namespace = "Google\\Cloud\\PolicySimulator\\V1"; 30option ruby_package = "Google::Cloud::PolicySimulator::V1"; 31 32// Whether a principal has a permission for a resource. 33enum AccessState { 34 // Default value. This value is unused. 35 ACCESS_STATE_UNSPECIFIED = 0; 36 37 // The principal has the permission. 38 GRANTED = 1; 39 40 // The principal does not have the permission. 41 NOT_GRANTED = 2; 42 43 // The principal has the permission only if a condition expression evaluates 44 // to `true`. 45 UNKNOWN_CONDITIONAL = 3; 46 47 // The user who created the 48 // [Replay][google.cloud.policysimulator.v1.Replay] does not have 49 // access to all of the policies that Policy Simulator needs to evaluate. 50 UNKNOWN_INFO_DENIED = 4; 51} 52 53// The extent to which a single data point, such as the existence of a binding 54// or whether a binding includes a specific principal, contributes to an overall 55// determination. 56enum HeuristicRelevance { 57 // Default value. This value is unused. 58 HEURISTIC_RELEVANCE_UNSPECIFIED = 0; 59 60 // The data point has a limited effect on the result. Changing the data point 61 // is unlikely to affect the overall determination. 62 NORMAL = 1; 63 64 // The data point has a strong effect on the result. Changing the data point 65 // is likely to affect the overall determination. 66 HIGH = 2; 67} 68 69// Information about the principal, resource, and permission to check. 70message AccessTuple { 71 // Required. The principal whose access you want to check, in the form of 72 // the email address that represents that principal. For example, 73 // `alice@example.com` or 74 // `my-service-account@my-project.iam.gserviceaccount.com`. 75 // 76 // The principal must be a Google Account or a service account. Other types of 77 // principals are not supported. 78 string principal = 1 [(google.api.field_behavior) = REQUIRED]; 79 80 // Required. The full resource name that identifies the resource. For example, 81 // `//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/my-instance`. 82 // 83 // For examples of full resource names for Google Cloud services, see 84 // https://cloud.google.com/iam/help/troubleshooter/full-resource-names. 85 string full_resource_name = 2 [(google.api.field_behavior) = REQUIRED]; 86 87 // Required. The IAM permission to check for the specified principal and 88 // resource. 89 // 90 // For a complete list of IAM permissions, see 91 // https://cloud.google.com/iam/help/permissions/reference. 92 // 93 // For a complete list of predefined IAM roles and the permissions in each 94 // role, see https://cloud.google.com/iam/help/roles/reference. 95 string permission = 3 [(google.api.field_behavior) = REQUIRED]; 96} 97 98// Details about how a specific IAM [Policy][google.iam.v1.Policy] contributed 99// to the access check. 100message ExplainedPolicy { 101 // Indicates whether _this policy_ provides the specified permission to the 102 // specified principal for the specified resource. 103 // 104 // This field does _not_ indicate whether the principal actually has the 105 // permission for the resource. There might be another policy that overrides 106 // this policy. To determine whether the principal actually has the 107 // permission, use the `access` field in the 108 // [TroubleshootIamPolicyResponse][IamChecker.TroubleshootIamPolicyResponse]. 109 AccessState access = 1; 110 111 // The full resource name that identifies the resource. For example, 112 // `//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/my-instance`. 113 // 114 // If the user who created the 115 // [Replay][google.cloud.policysimulator.v1.Replay] does not have 116 // access to the policy, this field is omitted. 117 // 118 // For examples of full resource names for Google Cloud services, see 119 // https://cloud.google.com/iam/help/troubleshooter/full-resource-names. 120 string full_resource_name = 2; 121 122 // The IAM policy attached to the resource. 123 // 124 // If the user who created the 125 // [Replay][google.cloud.policysimulator.v1.Replay] does not have 126 // access to the policy, this field is empty. 127 google.iam.v1.Policy policy = 3; 128 129 // Details about how each binding in the policy affects the principal's 130 // ability, or inability, to use the permission for the resource. 131 // 132 // If the user who created the 133 // [Replay][google.cloud.policysimulator.v1.Replay] does not have 134 // access to the policy, this field is omitted. 135 repeated BindingExplanation binding_explanations = 4; 136 137 // The relevance of this policy to the overall determination in the 138 // [TroubleshootIamPolicyResponse][IamChecker.TroubleshootIamPolicyResponse]. 139 // 140 // If the user who created the 141 // [Replay][google.cloud.policysimulator.v1.Replay] does not have 142 // access to the policy, this field is omitted. 143 HeuristicRelevance relevance = 5; 144} 145 146// Details about how a binding in a policy affects a principal's ability to use 147// a permission. 148message BindingExplanation { 149 // Details about whether the binding includes the principal. 150 message AnnotatedMembership { 151 // Indicates whether the binding includes the principal. 152 Membership membership = 1; 153 154 // The relevance of the principal's status to the overall determination for 155 // the binding. 156 HeuristicRelevance relevance = 2; 157 } 158 159 // Whether a role includes a specific permission. 160 enum RolePermission { 161 // Default value. This value is unused. 162 ROLE_PERMISSION_UNSPECIFIED = 0; 163 164 // The permission is included in the role. 165 ROLE_PERMISSION_INCLUDED = 1; 166 167 // The permission is not included in the role. 168 ROLE_PERMISSION_NOT_INCLUDED = 2; 169 170 // The user who created the 171 // [Replay][google.cloud.policysimulator.v1.Replay] is not 172 // allowed to access the binding. 173 ROLE_PERMISSION_UNKNOWN_INFO_DENIED = 3; 174 } 175 176 // Whether the binding includes the principal. 177 enum Membership { 178 // Default value. This value is unused. 179 MEMBERSHIP_UNSPECIFIED = 0; 180 181 // The binding includes the principal. The principal can be included 182 // directly or indirectly. For example: 183 // 184 // * A principal is included directly if that principal is listed in the 185 // binding. 186 // * A principal is included indirectly if that principal is in a Google 187 // group or Google Workspace domain that is listed in the binding. 188 MEMBERSHIP_INCLUDED = 1; 189 190 // The binding does not include the principal. 191 MEMBERSHIP_NOT_INCLUDED = 2; 192 193 // The user who created the 194 // [Replay][google.cloud.policysimulator.v1.Replay] is not 195 // allowed to access the binding. 196 MEMBERSHIP_UNKNOWN_INFO_DENIED = 3; 197 198 // The principal is an unsupported type. Only Google Accounts and service 199 // accounts are supported. 200 MEMBERSHIP_UNKNOWN_UNSUPPORTED = 4; 201 } 202 203 // Required. Indicates whether _this binding_ provides the specified 204 // permission to the specified principal for the specified resource. 205 // 206 // This field does _not_ indicate whether the principal actually has the 207 // permission for the resource. There might be another binding that overrides 208 // this binding. To determine whether the principal actually has the 209 // permission, use the `access` field in the 210 // [TroubleshootIamPolicyResponse][IamChecker.TroubleshootIamPolicyResponse]. 211 AccessState access = 1 [(google.api.field_behavior) = REQUIRED]; 212 213 // The role that this binding grants. For example, 214 // `roles/compute.serviceAgent`. 215 // 216 // For a complete list of predefined IAM roles, as well as the permissions in 217 // each role, see https://cloud.google.com/iam/help/roles/reference. 218 string role = 2; 219 220 // Indicates whether the role granted by this binding contains the specified 221 // permission. 222 RolePermission role_permission = 3; 223 224 // The relevance of the permission's existence, or nonexistence, in the role 225 // to the overall determination for the entire policy. 226 HeuristicRelevance role_permission_relevance = 4; 227 228 // Indicates whether each principal in the binding includes the principal 229 // specified in the request, either directly or indirectly. Each key 230 // identifies a principal in the binding, and each value indicates whether the 231 // principal in the binding includes the principal in the request. 232 // 233 // For example, suppose that a binding includes the following principals: 234 // 235 // * `user:alice@example.com` 236 // * `group:product-eng@example.com` 237 // 238 // The principal in the replayed access tuple is `user:bob@example.com`. This 239 // user is a principal of the group `group:product-eng@example.com`. 240 // 241 // For the first principal in the binding, the key is 242 // `user:alice@example.com`, and the `membership` field in the value is set to 243 // `MEMBERSHIP_NOT_INCLUDED`. 244 // 245 // For the second principal in the binding, the key is 246 // `group:product-eng@example.com`, and the `membership` field in the value is 247 // set to `MEMBERSHIP_INCLUDED`. 248 map<string, AnnotatedMembership> memberships = 5; 249 250 // The relevance of this binding to the overall determination for the entire 251 // policy. 252 HeuristicRelevance relevance = 6; 253 254 // A condition expression that prevents this binding from granting access 255 // unless the expression evaluates to `true`. 256 // 257 // To learn about IAM Conditions, see 258 // https://cloud.google.com/iam/docs/conditions-overview. 259 google.type.Expr condition = 7; 260} 261