feat: add AnalyzeIamPolicy and ExportIamPolicyAnalysis RPCs (#386)

PiperOrigin-RevId: 328059685

Source-Author: Google APIs <noreply@google.com>
Source-Date: Sun Aug 23 17:12:48 2020 -0700
Source-Repo: googleapis/googleapis
Source-Sha: 72eb54c45231d84266ca059473bc1793c394fcb2
Source-Link: googleapis/googleapis@72eb54c

packages/google-cloud-asset/protos/google/cloud/asset/v1/assets.proto

@@ -22,11 +22,9 @@ import "google/iam/v1/policy.proto";
 import "google/identity/accesscontextmanager/v1/access_level.proto";
 import "google/identity/accesscontextmanager/v1/access_policy.proto";
 import "google/identity/accesscontextmanager/v1/service_perimeter.proto";
-import "google/protobuf/any.proto";
 import "google/protobuf/struct.proto";
 import "google/protobuf/timestamp.proto";
 import "google/rpc/code.proto";
-import "google/api/annotations.proto";
 
 option cc_enable_arenas = true;
 option csharp_namespace = "Google.Cloud.Asset.V1";
@@ -150,7 +148,8 @@ message Asset {
 
     // Please also refer to the [service perimeter user
     // guide](https://cloud.google.com/vpc-service-controls/docs/overview).
-    google.identity.accesscontextmanager.v1.ServicePerimeter service_perimeter = 9;
+    google.identity.accesscontextmanager.v1.ServicePerimeter service_perimeter =
+        9;
   }
 
   // The ancestry path of an asset in Google Cloud [resource
@@ -378,3 +377,158 @@ message IamPolicySearchResult {
   // information to explain why the search result matches the query.
   Explanation explanation = 4;
 }
+
+// Represents the detailed state of an entity under analysis, such as a
+// resource, an identity or an access.
+message IamPolicyAnalysisState {
+  // The Google standard error code that best describes the state.
+  // For example:
+  // - OK means the analysis on this entity has been successfully finished;
+  // - PERMISSION_DENIED means an access denied error is encountered;
+  // - DEADLINE_EXCEEDED means the analysis on this entity hasn't been started
+  // in time;
+  google.rpc.Code code = 1;
+
+  // The human-readable description of the cause of failure.
+  string cause = 2;
+}
+
+// IAM Policy analysis result, consisting of one IAM policy binding and derived
+// access control lists.
+message IamPolicyAnalysisResult {
+  // The [full resource
+  // name](https://cloud.google.com/asset-inventory/docs/resource-name-format)
+  // of the resource to which the [iam_binding][iam_binding] policy attaches.
+  // (-- api-linter: core::0122::name-suffix=disabled
+  //     aip.dev/not-precedent: full_resource_name is a public notion in GCP.
+  //     --)
+  string attached_resource_full_name = 1;
+
+  // The Cloud IAM policy binding under analysis.
+  google.iam.v1.Binding iam_binding = 2;
+
+  // A Google Cloud resource under analysis.
+  message Resource {
+    // The [full resource
+    // name](https://cloud.google.com/asset-inventory/docs/resource-name-format)
+    // (-- api-linter: core::0122::name-suffix=disabled
+    //     aip.dev/not-precedent: full_resource_name is a public notion in GCP.
+    //     --)
+    string full_resource_name = 1;
+
+    // The analysis state of this resource.
+    IamPolicyAnalysisState analysis_state = 2;
+  }
+
+  // An IAM role or permission under analysis.
+  message Access {
+    oneof oneof_access {
+      // The role.
+      string role = 1;
+
+      // The permission.
+      string permission = 2;
+    }
+
+    // The analysis state of this access.
+    IamPolicyAnalysisState analysis_state = 3;
+  }
+
+  // An identity under analysis.
+  // (-- api-linter: core::0123::resource-annotation=disabled
+  //     aip.dev/not-precedent: Identity name is not a resource. --)
+  message Identity {
+    // The identity name in any form of members appear in
+    // [IAM policy
+    // binding](https://cloud.google.com/iam/reference/rest/v1/Binding), such
+    // as:
+    // - user:foo@google.com
+    // - group:group1@google.com
+    // - serviceAccount:s1@prj1.iam.gserviceaccount.com
+    // - projectOwner:some_project_id
+    // - domain:google.com
+    // - allUsers
+    // - etc.
+    //
+    string name = 1;
+
+    // The analysis state of this identity.
+    IamPolicyAnalysisState analysis_state = 2;
+  }
+
+  // A directional edge.
+  message Edge {
+    // The source node of the edge. For example, it could be a full resource
+    // name for a resource node or an email of an identity.
+    string source_node = 1;
+
+    // The target node of the edge. For example, it could be a full resource
+    // name for a resource node or an email of an identity.
+    string target_node = 2;
+  }
+
+  // An access control list, derived from the above IAM policy binding, which
+  // contains a set of resources and accesses. May include one
+  // item from each set to compose an access control entry.
+  //
+  // NOTICE that there could be multiple access control lists for one IAM policy
+  // binding. The access control lists are created based on resource and access
+  // combinations.
+  //
+  // For example, assume we have the following cases in one IAM policy binding:
+  // - Permission P1 and P2 apply to resource R1 and R2;
+  // - Permission P3 applies to resource R2 and R3;
+  //
+  // This will result in the following access control lists:
+  // - AccessControlList 1: [R1, R2], [P1, P2]
+  // - AccessControlList 2: [R2, R3], [P3]
+  message AccessControlList {
+    // The resources that match one of the following conditions:
+    // - The resource_selector, if it is specified in request;
+    // - Otherwise, resources reachable from the policy attached resource.
+    repeated Resource resources = 1;
+
+    // The accesses that match one of the following conditions:
+    // - The access_selector, if it is specified in request;
+    // - Otherwise, access specifiers reachable from the policy binding's role.
+    repeated Access accesses = 2;
+
+    // Resource edges of the graph starting from the policy attached
+    // resource to any descendant resources. The [Edge.source_node][] contains
+    // the full resource name of a parent resource and [Edge.target_node][]
+    // contains the full resource name of a child resource. This field is
+    // present only if the output_resource_edges option is enabled in request.
+    repeated Edge resource_edges = 3;
+  }
+
+  // The access control lists derived from the [iam_binding][iam_binding] that
+  // match or potentially match resource and access selectors specified in the
+  // request.
+  repeated AccessControlList access_control_lists = 3;
+
+  // The identities and group edges.
+  message IdentityList {
+    // Only the identities that match one of the following conditions will be
+    // presented:
+    // - The identity_selector, if it is specified in request;
+    // - Otherwise, identities reachable from the policy binding's members.
+    repeated Identity identities = 1;
+
+    // Group identity edges of the graph starting from the binding's
+    // group members to any node of the [identities][]. The [Edge.source_node][]
+    // contains a group, such as `group:parent@google.com`. The
+    // [Edge.target_node][] contains a member of the group,
+    // such as `group:child@google.com` or `user:foo@google.com`.
+    // This field is present only if the output_group_edges option is enabled in
+    // request.
+    repeated Edge group_edges = 2;
+  }
+
+  // The identity list derived from members of the [iam_binding][iam_binding]
+  // that match or potentially match identity selector specified in the request.
+  IdentityList identity_list = 4;
+
+  // Represents whether all analyses on the [iam_binding][iam_binding] have
+  // successfully finished.
+  bool fully_explored = 5;
+}