diff --git a/google/cloud/asset/v1/asset_service.proto b/google/cloud/asset/v1/asset_service.proto index 6b66d444..c5873958 100644 --- a/google/cloud/asset/v1/asset_service.proto +++ b/google/cloud/asset/v1/asset_service.proto @@ -138,6 +138,34 @@ service AssetService { }; option (google.api.method_signature) = "scope,query"; } + + // Analyzes IAM policies to answer which identities have what accesses on + // which resources. + rpc AnalyzeIamPolicy(AnalyzeIamPolicyRequest) returns (AnalyzeIamPolicyResponse) { + option (google.api.http) = { + get: "/v1/{analysis_query.scope=*/*}:analyzeIamPolicy" + }; + } + + // Analyzes IAM policies asynchronously to answer which identities have what + // accesses on which resources, and writes the analysis results to a Google + // Cloud Storage or a BigQuery destination. For Cloud Storage destination, the + // output format is the JSON format that represents a + // [AnalyzeIamPolicyResponse][google.cloud.asset.v1.AnalyzeIamPolicyResponse]. This method implements the + // [google.longrunning.Operation][google.longrunning.Operation], which allows you to track the operation + // status. We recommend intervals of at least 2 seconds with exponential + // backoff retry to poll the operation result. The metadata contains the + // request to help callers to map responses to requests. + rpc AnalyzeIamPolicyLongrunning(AnalyzeIamPolicyLongrunningRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{analysis_query.scope=*/*}:analyzeIamPolicyLongrunning" + body: "*" + }; + option (google.longrunning.operation_info) = { + response_type: "google.cloud.asset.v1.AnalyzeIamPolicyLongrunningResponse" + metadata_type: "google.cloud.asset.v1.AnalyzeIamPolicyLongrunningRequest" + }; + } } // Export asset request. @@ -715,6 +743,293 @@ message SearchAllIamPoliciesResponse { string next_page_token = 2; } +// IAM policy analysis query message. +message IamPolicyAnalysisQuery { + // Specifies the resource to analyze for access policies, which may be set + // directly on the resource, or on ancestors such as organizations, folders or + // projects. + message ResourceSelector { + // Required. The [full resource name] + // (https://cloud.google.com/asset-inventory/docs/resource-name-format) + // of a resource of [supported resource + // types](https://cloud.google.com/asset-inventory/docs/supported-asset-types#analyzable_asset_types). + string full_resource_name = 1 [(google.api.field_behavior) = REQUIRED]; + } + + // Specifies an identity for which to determine resource access, based on + // roles assigned either directly to them or to the groups they belong to, + // directly or indirectly. + message IdentitySelector { + // Required. The identity appear in the form of members in + // [IAM policy + // binding](https://cloud.google.com/iam/reference/rest/v1/Binding). + // + // The examples of supported forms are: + // "user:mike@example.com", + // "group:admins@example.com", + // "domain:google.com", + // "serviceAccount:my-project-id@appspot.gserviceaccount.com". + // + // Notice that wildcard characters (such as * and ?) are not supported. + // You must give a specific identity. + string identity = 1 [(google.api.field_behavior) = REQUIRED]; + } + + // Specifies roles and/or permissions to analyze, to determine both the + // identities possessing them and the resources they control. If multiple + // values are specified, results will include roles or permissions matching + // any of them. The total number of roles and permissions should be equal or + // less than 10. + message AccessSelector { + // Optional. The roles to appear in result. + repeated string roles = 1 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. The permissions to appear in result. + repeated string permissions = 2 [(google.api.field_behavior) = OPTIONAL]; + } + + // Contains query options. + message Options { + // Optional. If true, the identities section of the result will expand any + // Google groups appearing in an IAM policy binding. + // + // If [IamPolicyAnalysisQuery.identity_selector][google.cloud.asset.v1.IamPolicyAnalysisQuery.identity_selector] is specified, the + // identity in the result will be determined by the selector, and this flag + // is not allowed to set. + // + // Default is false. + bool expand_groups = 1 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. If true, the access section of result will expand any roles + // appearing in IAM policy bindings to include their permissions. + // + // If [IamPolicyAnalysisQuery.access_selector][google.cloud.asset.v1.IamPolicyAnalysisQuery.access_selector] is specified, the access + // section of the result will be determined by the selector, and this flag + // is not allowed to set. + // + // Default is false. + bool expand_roles = 2 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. If true and [IamPolicyAnalysisQuery.resource_selector][google.cloud.asset.v1.IamPolicyAnalysisQuery.resource_selector] is not + // specified, the resource section of the result will expand any resource + // attached to an IAM policy to include resources lower in the resource + // hierarchy. + // + // For example, if the request analyzes for which resources user A has + // permission P, and the results include an IAM policy with P on a GCP + // folder, the results will also include resources in that folder with + // permission P. + // + // If true and [IamPolicyAnalysisQuery.resource_selector][google.cloud.asset.v1.IamPolicyAnalysisQuery.resource_selector] is specified, + // the resource section of the result will expand the specified resource to + // include resources lower in the resource hierarchy. Only project or + // lower resources are supported. Folder and organization resource cannot be + // used together with this option. + // + // For example, if the request analyzes for which users have permission P on + // a GCP project with this option enabled, the results will include all + // users who have permission P on that project or any lower resource. + // + // Default is false. + bool expand_resources = 3 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. If true, the result will output resource edges, starting + // from the policy attached resource, to any expanded resources. + // Default is false. + bool output_resource_edges = 4 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. If true, the result will output group identity edges, starting + // from the binding's group members, to any expanded identities. + // Default is false. + bool output_group_edges = 5 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. If true, the response will include access analysis from identities to + // resources via service account impersonation. This is a very expensive + // operation, because many derived queries will be executed. We highly + // recommend you use [AssetService.AnalyzeIamPolicyLongrunning][google.cloud.asset.v1.AssetService.AnalyzeIamPolicyLongrunning] rpc + // instead. + // + // For example, if the request analyzes for which resources user A has + // permission P, and there's an IAM policy states user A has + // iam.serviceAccounts.getAccessToken permission to a service account SA, + // and there's another IAM policy states service account SA has permission P + // to a GCP folder F, then user A potentially has access to the GCP folder + // F. And those advanced analysis results will be included in + // [AnalyzeIamPolicyResponse.service_account_impersonation_analysis][google.cloud.asset.v1.AnalyzeIamPolicyResponse.service_account_impersonation_analysis]. + // + // Another example, if the request analyzes for who has + // permission P to a GCP folder F, and there's an IAM policy states user A + // has iam.serviceAccounts.actAs permission to a service account SA, and + // there's another IAM policy states service account SA has permission P to + // the GCP folder F, then user A potentially has access to the GCP folder + // F. And those advanced analysis results will be included in + // [AnalyzeIamPolicyResponse.service_account_impersonation_analysis][google.cloud.asset.v1.AnalyzeIamPolicyResponse.service_account_impersonation_analysis]. + // + // Default is false. + bool analyze_service_account_impersonation = 6 [(google.api.field_behavior) = OPTIONAL]; + } + + // Required. The relative name of the root asset. Only resources and IAM policies within + // the scope will be analyzed. + // + // This can only be an organization number (such as "organizations/123"), a + // folder number (such as "folders/123"), a project ID (such as + // "projects/my-project-id"), or a project number (such as "projects/12345"). + // + // To know how to get organization id, visit [here + // ](https://cloud.google.com/resource-manager/docs/creating-managing-organization#retrieving_your_organization_id). + // + // To know how to get folder or project id, visit [here + // ](https://cloud.google.com/resource-manager/docs/creating-managing-folders#viewing_or_listing_folders_and_projects). + string scope = 1 [(google.api.field_behavior) = REQUIRED]; + + // Optional. Specifies a resource for analysis. + ResourceSelector resource_selector = 2 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Specifies an identity for analysis. + IdentitySelector identity_selector = 3 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Specifies roles or permissions for analysis. This is optional. + AccessSelector access_selector = 4 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. The query options. + Options options = 5 [(google.api.field_behavior) = OPTIONAL]; +} + +// A request message for [AssetService.AnalyzeIamPolicy][google.cloud.asset.v1.AssetService.AnalyzeIamPolicy]. +message AnalyzeIamPolicyRequest { + // Required. The request query. + IamPolicyAnalysisQuery analysis_query = 1 [(google.api.field_behavior) = REQUIRED]; + + // Optional. Amount of time executable has to complete. See JSON representation of + // [Duration](https://developers.google.com/protocol-buffers/docs/proto3#json). + // + // If this field is set with a value less than the RPC deadline, and the + // execution of your query hasn't finished in the specified + // execution timeout, you will get a response with partial result. + // Otherwise, your query's execution will continue until the RPC deadline. + // If it's not finished until then, you will get a DEADLINE_EXCEEDED error. + // + // Default is empty. + google.protobuf.Duration execution_timeout = 2 [(google.api.field_behavior) = OPTIONAL]; +} + +// A response message for [AssetService.AnalyzeIamPolicy][google.cloud.asset.v1.AssetService.AnalyzeIamPolicy]. +message AnalyzeIamPolicyResponse { + // An analysis message to group the query and results. + message IamPolicyAnalysis { + // The analysis query. + IamPolicyAnalysisQuery analysis_query = 1; + + // A list of [IamPolicyAnalysisResult][google.cloud.asset.v1.IamPolicyAnalysisResult] that matches the analysis query, or + // empty if no result is found. + repeated IamPolicyAnalysisResult analysis_results = 2; + + // Represents whether all entries in the [analysis_results][google.cloud.asset.v1.AnalyzeIamPolicyResponse.IamPolicyAnalysis.analysis_results] have been + // fully explored to answer the query. + bool fully_explored = 3; + + // A list of non-critical errors happened during the query handling. + repeated IamPolicyAnalysisState non_critical_errors = 5; + } + + // The main analysis that matches the original request. + IamPolicyAnalysis main_analysis = 1; + + // The service account impersonation analysis if + // [AnalyzeIamPolicyRequest.analyze_service_account_impersonation][] is + // enabled. + repeated IamPolicyAnalysis service_account_impersonation_analysis = 2; + + // Represents whether all entries in the [main_analysis][google.cloud.asset.v1.AnalyzeIamPolicyResponse.main_analysis] and + // [service_account_impersonation_analysis][google.cloud.asset.v1.AnalyzeIamPolicyResponse.service_account_impersonation_analysis] have been fully explored to + // answer the query in the request. + bool fully_explored = 3; +} + +// Output configuration for export IAM policy analysis destination. +message IamPolicyAnalysisOutputConfig { + // A Cloud Storage location. + message GcsDestination { + // Required. The uri of the Cloud Storage object. It's the same uri that is used by + // gsutil. For example: "gs://bucket_name/object_name". See + // [Quickstart: Using the gsutil tool] + // (https://cloud.google.com/storage/docs/quickstart-gsutil) for examples. + string uri = 1 [(google.api.field_behavior) = REQUIRED]; + } + + // A BigQuery destination. + message BigQueryDestination { + // This enum determines the partition key column for the bigquery tables. + // Partitioning can improve query performance and reduce query cost by + // filtering partitions. Refer to + // https://cloud.google.com/bigquery/docs/partitioned-tables for details. + enum PartitionKey { + // Unspecified partition key. Tables won't be partitioned using this + // option. + PARTITION_KEY_UNSPECIFIED = 0; + + // The time when the request is received. If specified as partition key, + // the result table(s) is partitoned by the RequestTime column, an + // additional timestamp column representing when the request was received. + REQUEST_TIME = 1; + } + + // Required. The BigQuery dataset in format "projects/projectId/datasets/datasetId", + // to which the analysis results should be exported. If this dataset does + // not exist, the export call will return an INVALID_ARGUMENT error. + string dataset = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. The prefix of the BigQuery tables to which the analysis results will be + // written. Tables will be created based on this table_prefix if not exist: + // * _analysis table will contain export operation's metadata. + // * _analysis_result will contain all the + // [IamPolicyAnalysisResult][google.cloud.asset.v1.IamPolicyAnalysisResult]. + // When [partition_key] is specified, both tables will be partitioned based + // on the [partition_key]. + string table_prefix = 2 [(google.api.field_behavior) = REQUIRED]; + + // The partition key for BigQuery partitioned table. + PartitionKey partition_key = 3; + + // Optional. Specifies the action that occurs if the destination table or partition + // already exists. The following values are supported: + // + // * WRITE_TRUNCATE: If the table or partition already exists, BigQuery + // overwrites the entire table or all the partitions data. + // * WRITE_APPEND: If the table or partition already exists, BigQuery + // appends the data to the table or the latest partition. + // * WRITE_EMPTY: If the table already exists and contains data, an error is + // returned. + // + // The default value is WRITE_APPEND. Each action is atomic and only occurs + // if BigQuery is able to complete the job successfully. Details are at + // https://cloud.google.com/bigquery/docs/loading-data-local#appending_to_or_overwriting_a_table_using_a_local_file. + string write_disposition = 4 [(google.api.field_behavior) = OPTIONAL]; + } + + // IAM policy analysis export destination. + oneof destination { + // Destination on Cloud Storage. + GcsDestination gcs_destination = 1; + + // Destination on BigQuery. + BigQueryDestination bigquery_destination = 2; + } +} + +// A request message for [AssetService.AnalyzeIamPolicyLongrunning][google.cloud.asset.v1.AssetService.AnalyzeIamPolicyLongrunning]. +message AnalyzeIamPolicyLongrunningRequest { + // Required. The request query. + IamPolicyAnalysisQuery analysis_query = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. Output configuration indicating where the results will be output to. + IamPolicyAnalysisOutputConfig output_config = 2 [(google.api.field_behavior) = REQUIRED]; +} + +// A response message for [AssetService.AnalyzeIamPolicyLongrunning][google.cloud.asset.v1.AssetService.AnalyzeIamPolicyLongrunning]. +message AnalyzeIamPolicyLongrunningResponse {} + // Asset content type. enum ContentType { // Unspecified content type. diff --git a/google/cloud/asset/v1/assets.proto b/google/cloud/asset/v1/assets.proto index b9d56744..c06caf71 100644 --- a/google/cloud/asset/v1/assets.proto +++ b/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; +} diff --git a/google/cloud/asset/v1/cloudasset_grpc_service_config.json b/google/cloud/asset/v1/cloudasset_grpc_service_config.json index 64cb6d21..48db7c33 100755 --- a/google/cloud/asset/v1/cloudasset_grpc_service_config.json +++ b/google/cloud/asset/v1/cloudasset_grpc_service_config.json @@ -16,7 +16,7 @@ }, { "service": "google.cloud.asset.v1.AssetService", - "method": "ExportIamPolicyAnalysis" + "method": "AnalyzeIamPolicyLongrunning" } ], "timeout": "60s"