suguo
/
googleapis
0
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat: add AnalyzeIamPolicy and AnalyzeIamPolicyLongrunning RPCs 

PiperOrigin-RevId: 339708980
This commit is contained in:
Google APIs 2020-10-29 11:23:44 -07:00 committed by Copybara-Service
parent ab0498dc4b
commit 00bbad4dfd
3 changed files with 461 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

315
google/cloud/asset/v1/asset_service.proto
View File

@ -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:
// * <table_prefix>_analysis table will contain export operation's metadata.
// * <table_prefix>_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.

145
google/cloud/asset/v1/assets.proto
View File

@ -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;
}

2
google/cloud/asset/v1/cloudasset_grpc_service_config.json
View File

@ -16,7 +16,7 @@
},
{
"service": "google.cloud.asset.v1.AssetService",
"method": "ExportIamPolicyAnalysis"
"method": "AnalyzeIamPolicyLongrunning"
}
],
"timeout": "60s"