From c06599cdd7d11f8d3fd25f8d3249e5bb1a3d5d73 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Mon, 13 Jan 2020 12:09:23 -0800 Subject: [PATCH] Initial commit of google.cloud.policytroubleshooter API, The API helps in troubleshooting GCP policies. Refer https://cloud.google.com/iam/docs/troubleshooting-access for more information PiperOrigin-RevId: 289491444 --- .../policytroubleshooter/v1/checker.proto | 71 +++++ .../v1/checker_grpc_service_config.json | 19 ++ .../v1/explanations.proto | 242 ++++++++++++++++++ .../v1/policytroubleshooter_v1.yaml | 19 ++ 4 files changed, 351 insertions(+) create mode 100644 google/cloud/policytroubleshooter/v1/checker.proto create mode 100644 google/cloud/policytroubleshooter/v1/checker_grpc_service_config.json create mode 100644 google/cloud/policytroubleshooter/v1/explanations.proto create mode 100644 google/cloud/policytroubleshooter/v1/policytroubleshooter_v1.yaml diff --git a/google/cloud/policytroubleshooter/v1/checker.proto b/google/cloud/policytroubleshooter/v1/checker.proto new file mode 100644 index 00000000..6fae32d1 --- /dev/null +++ b/google/cloud/policytroubleshooter/v1/checker.proto @@ -0,0 +1,71 @@ +// Copyright 2019 Google LLC. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +syntax = "proto3"; + +package google.cloud.policytroubleshooter.v1; + +import public "google/cloud/policytroubleshooter/v1/explanations.proto"; +import "google/api/annotations.proto"; +import "google/api/client.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/policytroubleshooter/v1;policytroubleshooter"; +option java_multiple_files = true; +option java_outer_classname = "IAMCheckerProto"; +option java_package = "com.google.cloud.policytroubleshooter.v1"; + +// IAM Policy Troubleshooter service. +// +// This service helps you troubleshoot access issues for Google Cloud resources. +service IamChecker { + option (google.api.default_host) = "policytroubleshooter.googleapis.com"; + option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform"; + + // Checks whether a member has a specific permission for a specific resource, + // and explains why the member does or does not have that permission. + rpc TroubleshootIamPolicy(TroubleshootIamPolicyRequest) returns (TroubleshootIamPolicyResponse) { + option (google.api.http) = { + post: "/v1/iam:troubleshoot" + body: "*" + }; + } +} + +// Request for [TroubleshootIamPolicy][google.cloud.policytroubleshooter.v1.IamChecker.TroubleshootIamPolicy]. +message TroubleshootIamPolicyRequest { + // The information to use for checking whether a member has a permission for a + // resource. + AccessTuple access_tuple = 1; +} + +// Response for [TroubleshootIamPolicy][google.cloud.policytroubleshooter.v1.IamChecker.TroubleshootIamPolicy]. +message TroubleshootIamPolicyResponse { + // Indicates whether the member has the specified permission for the specified + // resource, based on evaluating all of the applicable IAM policies. + AccessState access = 1; + + // List of IAM policies that were evaluated to check the member's permissions, + // with annotations to indicate how each policy contributed to the final + // result. + // + // The list of policies can include the policy for the resource itself. It can + // also include policies that are inherited from higher levels of the resource + // hierarchy, including the organization, the folder, and the project. + // + // To learn more about the resource hierarchy, see + // https://cloud.google.com/iam/help/resource-hierarchy. + repeated ExplainedPolicy explained_policies = 2; +} diff --git a/google/cloud/policytroubleshooter/v1/checker_grpc_service_config.json b/google/cloud/policytroubleshooter/v1/checker_grpc_service_config.json new file mode 100644 index 00000000..10d589ba --- /dev/null +++ b/google/cloud/policytroubleshooter/v1/checker_grpc_service_config.json @@ -0,0 +1,19 @@ +{ + "methodConfig": [{ + "name": [{ "service": "google.cloud.policytroubleshooter.v1.IamChecker" }], + "timeout": "60s", + "retryPolicy": { + "maxAttempts": 5, + "initialBackoff": "1s", + "maxBackoff": "60s", + "backoffMultiplier": 1.3, + "retryableStatusCodes": ["UNAVAILABLE", "UNKNOWN"] + } + }, + { + "name": [ + { "service": "google.cloud.policytroubleshooter.v1.IamChecker", "method": "TroubleshootIamPolicy" } + ], + "timeout": "60s" + }] +} diff --git a/google/cloud/policytroubleshooter/v1/explanations.proto b/google/cloud/policytroubleshooter/v1/explanations.proto new file mode 100644 index 00000000..7fe73689 --- /dev/null +++ b/google/cloud/policytroubleshooter/v1/explanations.proto @@ -0,0 +1,242 @@ +// Copyright 2019 Google LLC. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +syntax = "proto3"; + +package google.cloud.policytroubleshooter.v1; + +import "google/api/field_behavior.proto"; +import "google/iam/v1/policy.proto"; +import "google/type/expr.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/policytroubleshooter/v1;policytroubleshooter"; + +// Information about the member, resource, and permission to check. +message AccessTuple { + // Required. The member, or principal, whose access you want to check, in the form of + // the email address that represents that member. For example, + // `alice@example.com` or + // `my-service-account@my-project.iam.gserviceaccount.com`. + // + // The member must be a Google Account or a service account. Other types of + // members are not supported. + string principal = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. The full resource name that identifies the resource. For example, + // `//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/my-instance`. + // + // For examples of full resource names for Google Cloud services, see + // https://cloud.google.com/iam/help/troubleshooter/full-resource-names. + string full_resource_name = 2 [(google.api.field_behavior) = REQUIRED]; + + // Required. The IAM permission to check for the specified member and resource. + // + // For a complete list of IAM permissions, see + // https://cloud.google.com/iam/help/permissions/reference. + // + // For a complete list of predefined IAM roles and the permissions in each + // role, see https://cloud.google.com/iam/help/roles/reference. + string permission = 3 [(google.api.field_behavior) = REQUIRED]; +} + +// Details about how a specific IAM [Policy][google.iam.v1.Policy] contributed +// to the access check. +message ExplainedPolicy { + // Indicates whether _this policy_ provides the specified permission to the + // specified member for the specified resource. + // + // This field does _not_ indicate whether the member actually has the + // permission for the resource. There might be another policy that overrides + // this policy. To determine whether the member actually has the permission, + // use the `access` field in the + // [TroubleshootIamPolicyResponse][IamChecker.TroubleshootIamPolicyResponse]. + AccessState access = 1; + + // The full resource name that identifies the resource. For example, + // `//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/my-instance`. + // + // If the sender of the request does not have access to the policy, this field + // is omitted. + // + // For examples of full resource names for Google Cloud services, see + // https://cloud.google.com/iam/help/troubleshooter/full-resource-names. + string full_resource_name = 2; + + // The IAM policy attached to the resource. + // + // If the sender of the request does not have access to the policy, this field + // is empty. + google.iam.v1.Policy policy = 3; + + // Details about how each binding in the policy affects the member's ability, + // or inability, to use the permission for the resource. + // + // If the sender of the request does not have access to the policy, this field + // is omitted. + repeated BindingExplanation binding_explanations = 4; + + // The relevance of this policy to the overall determination in the + // [TroubleshootIamPolicyResponse][IamChecker.TroubleshootIamPolicyResponse]. + // + // If the sender of the request does not have access to the policy, this field + // is omitted. + HeuristicRelevance relevance = 5; +} + +// Details about how a binding in a policy affects a member's ability to use a +// permission. +message BindingExplanation { + // Details about whether the binding includes the member. + message AnnotatedMembership { + // Indicates whether the binding includes the member. + Membership membership = 1; + + // The relevance of the member's status to the overall determination for the + // binding. + HeuristicRelevance relevance = 2; + } + + // Whether a role includes a specific permission. + enum RolePermission { + // Reserved for future use. + ROLE_PERMISSION_UNSPECIFIED = 0; + + // The permission is included in the role. + ROLE_PERMISSION_INCLUDED = 1; + + // The permission is not included in the role. + ROLE_PERMISSION_NOT_INCLUDED = 2; + + // The sender of the request is not allowed to access the binding. + ROLE_PERMISSION_UNKNOWN_INFO_DENIED = 3; + } + + // Whether the binding includes the member. + enum Membership { + // Reserved for future use. + MEMBERSHIP_UNSPECIFIED = 0; + + // The binding includes the member. The member can be included directly + // or indirectly. For example: + // + // * A member is included directly if that member is listed in the binding. + // * A member is included indirectly if that member is in a Google group or + // G Suite domain that is listed in the binding. + MEMBERSHIP_INCLUDED = 1; + + // The binding does not include the member. + MEMBERSHIP_NOT_INCLUDED = 2; + + // The sender of the request is not allowed to access the binding. + MEMBERSHIP_UNKNOWN_INFO_DENIED = 3; + + // The member is an unsupported type. Only Google Accounts and service + // accounts are supported. + MEMBERSHIP_UNKNOWN_UNSUPPORTED = 4; + } + + // Required. Indicates whether _this binding_ provides the specified permission to the + // specified member for the specified resource. + // + // This field does _not_ indicate whether the member actually has the + // permission for the resource. There might be another binding that overrides + // this binding. To determine whether the member actually has the permission, + // use the `access` field in the + // [TroubleshootIamPolicyResponse][IamChecker.TroubleshootIamPolicyResponse]. + AccessState access = 1 [(google.api.field_behavior) = REQUIRED]; + + // The role that this binding grants. For example, + // `roles/compute.serviceAgent`. + // + // For a complete list of predefined IAM roles, as well as the permissions in + // each role, see https://cloud.google.com/iam/help/roles/reference. + string role = 2; + + // Indicates whether the role granted by this binding contains the specified + // permission. + RolePermission role_permission = 3; + + // The relevance of the permission's existence, or nonexistence, in the role + // to the overall determination for the entire policy. + HeuristicRelevance role_permission_relevance = 4; + + // Indicates whether each member in the binding includes the member specified + // in the request, either directly or indirectly. Each key identifies a member + // in the binding, and each value indicates whether the member in the binding + // includes the member in the request. + // + // For example, suppose that a binding includes the following members: + // + // * `user:alice@example.com` + // * `group:product-eng@example.com` + // + // You want to troubleshoot access for `user:bob@example.com`. This user is a + // member of the group `group:product-eng@example.com`. + // + // For the first member in the binding, the key is `user:alice@example.com`, + // and the `membership` field in the value is set to + // `MEMBERSHIP_NOT_INCLUDED`. + // + // For the second member in the binding, the key is + // `group:product-eng@example.com`, and the `membership` field in the value is + // set to `MEMBERSHIP_INCLUDED`. + map memberships = 5; + + // The relevance of this binding to the overall determination for the entire + // policy. + HeuristicRelevance relevance = 6; + + // A condition expression that prevents access unless the expression evaluates + // to `true`. + // + // To learn about IAM Conditions, see + // http://cloud.google.com/iam/help/conditions/overview. + google.type.Expr condition = 7; +} + +// Whether a member has a permission for a resource. +enum AccessState { + // Reserved for future use. + ACCESS_STATE_UNSPECIFIED = 0; + + // The member has the permission. + GRANTED = 1; + + // The member does not have the permission. + NOT_GRANTED = 2; + + // The member has the permission only if a condition expression evaluates to + // `true`. + UNKNOWN_CONDITIONAL = 3; + + // The sender of the request does not have access to all of the policies that + // Policy Troubleshooter needs to evaluate. + UNKNOWN_INFO_DENIED = 4; +} + +// The extent to which a single data point contributes to an overall +// determination. +enum HeuristicRelevance { + // Reserved for future use. + HEURISTIC_RELEVANCE_UNSPECIFIED = 0; + + // The data point has a limited effect on the result. Changing the data point + // is unlikely to affect the overall determination. + NORMAL = 1; + + // The data point has a strong effect on the result. Changing the data point + // is likely to affect the overall determination. + HIGH = 2; +} diff --git a/google/cloud/policytroubleshooter/v1/policytroubleshooter_v1.yaml b/google/cloud/policytroubleshooter/v1/policytroubleshooter_v1.yaml new file mode 100644 index 00000000..ea5bbb47 --- /dev/null +++ b/google/cloud/policytroubleshooter/v1/policytroubleshooter_v1.yaml @@ -0,0 +1,19 @@ +type: google.api.Service +config_version: 3 +name: policytroubleshooter.googleapis.com +title: Policy Troubleshooter API + +apis: +- name: google.cloud.policytroubleshooter.v1.IamChecker + +backend: + rules: + - selector: google.cloud.policytroubleshooter.v1.IamChecker.TroubleshootIamPolicy + deadline: 20.0 + +authentication: + rules: + - selector: google.cloud.policytroubleshooter.v1.IamChecker.TroubleshootIamPolicy + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform