path: root/third_party/googleapis/google/cloud/policytroubleshooter/v1/explanations.proto

// 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 csharp_namespace = "Google.Cloud.PolicyTroubleshooter.V1";
option go_package = "google.golang.org/genproto/googleapis/cloud/policytroubleshooter/v1;policytroubleshooter";
option php_namespace = "Google\\Cloud\\PolicyTroubleshooter\\V1";
option ruby_package = "Google::Cloud::PolicyTroubleshooter::V1";

// 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<string, AnnotatedMembership> 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;
}