grpc_3rd/googleapis/google/cloud/asset/v1p4beta1/asset_service.proto

// Copyright 2020 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.asset.v1p4beta1;

import "google/api/annotations.proto";
import "google/api/field_behavior.proto";
import "google/cloud/asset/v1p4beta1/assets.proto";
import "google/iam/v1/policy.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/duration.proto";
import "google/api/client.proto";

option csharp_namespace = "Google.Cloud.Asset.V1P4Beta1";
option go_package = "google.golang.org/genproto/googleapis/cloud/asset/v1p4beta1;asset";
option java_multiple_files = true;
option java_outer_classname = "AssetServiceProto";
option java_package = "com.google.cloud.asset.v1p4beta1";
option php_namespace = "Google\\Cloud\\Asset\\V1p4beta1";

// Asset service definition.
service AssetService {
  option (google.api.default_host) = "cloudasset.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";

  // Analyzes IAM policies based on the specified request. Returns
  // a list of [IamPolicyAnalysisResult][google.cloud.asset.v1p4beta1.IamPolicyAnalysisResult] matching the request.
  rpc AnalyzeIamPolicy(AnalyzeIamPolicyRequest) returns (AnalyzeIamPolicyResponse) {
    option (google.api.http) = {
      get: "/v1p4beta1/{analysis_query.parent=*/*}:analyzeIamPolicy"
    };
  }

  // Exports IAM policy analysis based on the specified request. This API
  // implements the [google.longrunning.Operation][google.longrunning.Operation] API allowing you to keep
  // track of the export. The metadata contains the request to help callers to
  // map responses to requests.
  rpc ExportIamPolicyAnalysis(ExportIamPolicyAnalysisRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1p4beta1/{analysis_query.parent=*/*}:exportIamPolicyAnalysis"
      body: "*"
    };
    option (google.longrunning.operation_info) = {
      response_type: "google.cloud.asset.v1p4beta1.ExportIamPolicyAnalysisResponse"
      metadata_type: "google.cloud.asset.v1p4beta1.ExportIamPolicyAnalysisRequest"
    };
  }
}

// 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. At least one of [ResourceSelector][google.cloud.asset.v1p4beta1.IamPolicyAnalysisQuery.ResourceSelector], [IdentitySelector][google.cloud.asset.v1p4beta1.IamPolicyAnalysisQuery.IdentitySelector] or
  // [AccessSelector][google.cloud.asset.v1p4beta1.IamPolicyAnalysisQuery.AccessSelector] must be specified in a request.
  message ResourceSelector {
    // Required. The [full resource
    // name](https://cloud.google.com/apis/design/resource_names#full_resource_name)
    // .
    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).
    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 identities and resources
  // matching any of them.
  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];
  }

  // Required. The relative name of the root asset. Only resources and IAM policies within
  // the parent will be analyzed. This can only be an organization number (such
  // as "organizations/123") or a folder number (such as "folders/123").
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Specifies a resource for analysis. Leaving it empty means ANY.
  ResourceSelector resource_selector = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Specifies an identity for analysis. Leaving it empty means ANY.
  IdentitySelector identity_selector = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Specifies roles or permissions for analysis. Leaving it empty
  // means ANY.
  AccessSelector access_selector = 4 [(google.api.field_behavior) = OPTIONAL];
}

// A request message for [AssetService.AnalyzeIamPolicy][google.cloud.asset.v1p4beta1.AssetService.AnalyzeIamPolicy].
message AnalyzeIamPolicyRequest {
  // Contains request options.
  message Options {
    // Optional. If true, the identities section of the result will expand any
    // Google groups appearing in an IAM policy binding.
    //
    // If [identity_selector][] is specified, the identity in the result will
    // be determined by the selector, and this flag will have no effect.
    //
    // 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 [access_selector][] is specified, the access section of the result
    // will be determined by the selector, and this flag will have no effect.
    //
    // Default is false.
    bool expand_roles = 2 [(google.api.field_behavior) = OPTIONAL];

    // Optional. If true, 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 [resource_selector][] is specified, the resource section of the result
    // will be determined by the selector, and this flag will have no effect.
    // 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 ExportIamPolicyAnalysis 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.v1p4beta1.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.v1p4beta1.AnalyzeIamPolicyResponse.service_account_impersonation_analysis].
    //
    // Default is false.
    bool analyze_service_account_impersonation = 6 [(google.api.field_behavior) = OPTIONAL];

    // 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 = 7 [(google.api.field_behavior) = OPTIONAL];
  }

  // Required. The request query.
  IamPolicyAnalysisQuery analysis_query = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The request options.
  Options options = 2 [(google.api.field_behavior) = OPTIONAL];
}

// A response message for [AssetService.AnalyzeIamPolicy][google.cloud.asset.v1p4beta1.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.v1p4beta1.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.v1p4beta1.AnalyzeIamPolicyResponse.IamPolicyAnalysis.analysis_results] have been
    // fully explored to answer the query.
    bool fully_explored = 3;
  }

  // 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.v1p4beta1.AnalyzeIamPolicyResponse.main_analysis] and
  // [service_account_impersonation_analysis][google.cloud.asset.v1p4beta1.AnalyzeIamPolicyResponse.service_account_impersonation_analysis] have been fully explored to
  // answer the query in the request.
  bool fully_explored = 3;

  // A list of non-critical errors happened during the request handling to
  // explain why `fully_explored` is false, or empty if no error happened.
  repeated IamPolicyAnalysisResult.AnalysisState non_critical_errors = 4;
}

// 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 [Viewing and
    // Editing Object
    // Metadata](https://cloud.google.com/storage/docs/viewing-editing-metadata)
    // for more information.
    string uri = 1 [(google.api.field_behavior) = REQUIRED];
  }

  // IAM policy analysis export destination.
  oneof destination {
    // Destination on Cloud Storage.
    GcsDestination gcs_destination = 1;
  }
}

// A request message for [AssetService.ExportIamPolicyAnalysis][google.cloud.asset.v1p4beta1.AssetService.ExportIamPolicyAnalysis].
message ExportIamPolicyAnalysisRequest {
  // Contains request options.
  message Options {
    // Optional. If true, the identities section of the result will expand any
    // Google groups appearing in an IAM policy binding.
    //
    // If [identity_selector][] is specified, the identity in the result will
    // be determined by the selector, and this flag will have no effect.
    //
    // 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 [access_selector][] is specified, the access section of the result
    // will be determined by the selector, and this flag will have no effect.
    //
    // Default is false.
    bool expand_roles = 2 [(google.api.field_behavior) = OPTIONAL];

    // Optional. If true, 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 [resource_selector][] is specified, the resource section of the result
    // will be determined by the selector, and this flag will have no effect.
    // 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.
    //
    // 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.v1p4beta1.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.v1p4beta1.AnalyzeIamPolicyResponse.service_account_impersonation_analysis].
    //
    // Default is false.
    bool analyze_service_account_impersonation = 6 [(google.api.field_behavior) = OPTIONAL];
  }

  // Required. The request query.
  IamPolicyAnalysisQuery analysis_query = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The request options.
  Options options = 2 [(google.api.field_behavior) = OPTIONAL];

  // Required. Output configuration indicating where the results will be output to.
  IamPolicyAnalysisOutputConfig output_config = 3 [(google.api.field_behavior) = REQUIRED];
}

// The export IAM policy analysis response. This message is returned by the
// [google.longrunning.Operations.GetOperation][] method in the returned
// [google.longrunning.Operation.response][] field.
message ExportIamPolicyAnalysisResponse {
  // Output configuration indicating where the results were output to.
  IamPolicyAnalysisOutputConfig output_config = 1;
}