feat: add AnalyzeIamPolicy and AnalyzeIamPolicyLongrunning RPCs (#412)

PiperOrigin-RevId: 339708980

Source-Author: Google APIs <noreply@google.com>
Source-Date: Thu Oct 29 11:23:44 2020 -0700
Source-Repo: googleapis/googleapis
Source-Sha: 00bbad4dfd6633cf4b5f9596c1f93b756bb5c776
Source-Link: googleapis/googleapis@00bbad4

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

@@ -378,3 +378,148 @@ 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 {
+  // A Google Cloud resource under analysis.
+  message Resource {
+    // The [full resource
+    // name](https://cloud.google.com/asset-inventory/docs/resource-name-format)
+    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.
+  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][google.cloud.asset.v1.IamPolicyAnalysisResult.Edge.source_node] contains
+    // the full resource name of a parent resource and [Edge.target_node][google.cloud.asset.v1.IamPolicyAnalysisResult.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 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][google.cloud.asset.v1.IamPolicyAnalysisResult.IdentityList.identities]. The [Edge.source_node][google.cloud.asset.v1.IamPolicyAnalysisResult.Edge.source_node]
+    // contains a group, such as `group:parent@google.com`. The
+    // [Edge.target_node][google.cloud.asset.v1.IamPolicyAnalysisResult.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 [full resource
+  // name](https://cloud.google.com/asset-inventory/docs/resource-name-format)
+  // of the resource to which the [iam_binding][google.cloud.asset.v1.IamPolicyAnalysisResult.iam_binding] policy attaches.
+  string attached_resource_full_name = 1;
+
+  // The Cloud IAM policy binding under analysis.
+  google.iam.v1.Binding iam_binding = 2;
+
+  // The access control lists derived from the [iam_binding][google.cloud.asset.v1.IamPolicyAnalysisResult.iam_binding] that match or
+  // potentially match resource and access selectors specified in the request.
+  repeated AccessControlList access_control_lists = 3;
+
+  // The identity list derived from members of the [iam_binding][google.cloud.asset.v1.IamPolicyAnalysisResult.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][google.cloud.asset.v1.IamPolicyAnalysisResult.iam_binding] have successfully
+  // finished.
+  bool fully_explored = 5;
+}