googleapis/google/cloud/cloudsecuritycompliance/v1/monitoring.proto

// Copyright 2025 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.cloudsecuritycompliance.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/cloudsecuritycompliance/v1/common.proto";
import "google/protobuf/timestamp.proto";
import "google/type/interval.proto";

option csharp_namespace = "Google.Cloud.CloudSecurityCompliance.V1";
option go_package = "cloud.google.com/go/cloudsecuritycompliance/apiv1/cloudsecuritycompliancepb;cloudsecuritycompliancepb";
option java_multiple_files = true;
option java_outer_classname = "MonitoringProto";
option java_package = "com.google.cloud.cloudsecuritycompliance.v1";
option php_namespace = "Google\\Cloud\\CloudSecurityCompliance\\V1";
option ruby_package = "Google::Cloud::CloudSecurityCompliance::V1";
option (google.api.resource_definition) = {
  type: "cloudsecuritycompliance.googleapis.com/FolderLocation"
  pattern: "folders/{folder}/locations/{location}"
};

// Service describing handlers for resources
service Monitoring {
  option (google.api.default_host) = "cloudsecuritycompliance.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Lists the framework compliance summary for a given scope.
  rpc ListFrameworkComplianceSummaries(ListFrameworkComplianceSummariesRequest)
      returns (ListFrameworkComplianceSummariesResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=organizations/*/locations/*}/frameworkComplianceSummaries"
      additional_bindings {
        get: "/v1/{parent=folders/*/locations/*}/frameworkComplianceSummaries"
      }
      additional_bindings {
        get: "/v1/{parent=projects/*/locations/*}/frameworkComplianceSummaries"
      }
    };
    option (google.api.method_signature) = "parent";
  }

  // Lists the finding summary by category for a given scope.
  rpc ListFindingSummaries(ListFindingSummariesRequest)
      returns (ListFindingSummariesResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=organizations/*/locations/*}/findingSummaries"
      additional_bindings {
        get: "/v1/{parent=folders/*/locations/*}/findingSummaries"
      }
      additional_bindings {
        get: "/v1/{parent=projects/*/locations/*}/findingSummaries"
      }
    };
    option (google.api.method_signature) = "parent";
  }

  // Fetches the framework compliance report for a given scope.
  rpc FetchFrameworkComplianceReport(FetchFrameworkComplianceReportRequest)
      returns (FrameworkComplianceReport) {
    option (google.api.http) = {
      get: "/v1/{name=organizations/*/locations/*/frameworkComplianceReports/*}:fetch"
      additional_bindings {
        get: "/v1/{name=folders/*/locations/*/frameworkComplianceReports/*}:fetch"
      }
      additional_bindings {
        get: "/v1/{name=projects/*/locations/*/frameworkComplianceReports/*}:fetch"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Lists the control compliance summary for a given scope.
  rpc ListControlComplianceSummaries(ListControlComplianceSummariesRequest)
      returns (ListControlComplianceSummariesResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=organizations/*/locations/*/frameworkComplianceReports/*}/controlComplianceSummaries"
      additional_bindings {
        get: "/v1/{parent=folders/*/locations/*/frameworkComplianceReports/*}/controlComplianceSummaries"
      }
      additional_bindings {
        get: "/v1/{parent=projects/*/locations/*/frameworkComplianceReports/*}/controlComplianceSummaries"
      }
    };
    option (google.api.method_signature) = "parent";
  }

  // Gets the aggregated compliance report over time for a given scope.
  rpc AggregateFrameworkComplianceReport(
      AggregateFrameworkComplianceReportRequest)
      returns (AggregateFrameworkComplianceReportResponse) {
    option (google.api.http) = {
      get: "/v1/{name=organizations/*/locations/*/frameworkComplianceReports/*}:aggregate"
      additional_bindings {
        get: "/v1/{name=folders/*/locations/*/frameworkComplianceReports/*}:aggregate"
      }
      additional_bindings {
        get: "/v1/{name=projects/*/locations/*/frameworkComplianceReports/*}:aggregate"
      }
    };
    option (google.api.method_signature) = "name";
  }
}

// The evaluation state of the control.
enum EvaluationState {
  // Default value. This value is unused.
  EVALUATION_STATE_UNSPECIFIED = 0;

  // The control is passing.
  EVALUATION_STATE_PASSED = 1;

  // The control is failing.
  EVALUATION_STATE_FAILED = 2;

  // The control is not assessed.
  EVALUATION_STATE_NOT_ASSESSED = 3;
}

// A finding is a record of assessment data like security, risk, health, or
// privacy.
enum FindingClass {
  // Default value. This value is unused.
  FINDING_CLASS_UNSPECIFIED = 0;

  // The activity is unwanted or malicious.
  THREAT = 1;

  // A potential weakness in software that increases risk to
  // confidentiality, integrity, and availability.
  VULNERABILITY = 2;

  // A potential weakness in a cloud resource or asset configuration that
  // increases risk.
  MISCONFIGURATION = 3;

  // A security observation that is for informational purposes.
  OBSERVATION = 4;

  // An error that prevents Security Command Center from functioning properly.
  SCC_ERROR = 5;

  // A potential security risk that's due to a change in the security
  // posture.
  POSTURE_VIOLATION = 6;

  // A combination of security issues that represent a more severe
  // security problem when taken together.
  TOXIC_COMBINATION = 7;

  // A potential security risk to data assets that contain sensitive
  // data.
  SENSITIVE_DATA_RISK = 8;

  // A resource or resource group where high risk attack paths
  // converge, based on attack path simulations (APS).
  CHOKEPOINT = 9;
}

// The request message for
// [ListFrameworkComplianceSummariesRequest][google.cloud.cloudsecuritycompliance.v1.ListFrameworkComplianceSummariesRequest].
message ListFrameworkComplianceSummariesRequest {
  // Required. The parent scope for the framework compliance summary.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "cloudsecuritycompliance.googleapis.com/FrameworkComplianceSummary"
    }
  ];

  // Optional. The requested page size. The server might return fewer items than
  // requested. If unspecified, the server picks an appropriate default.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A token that identifies the page of results that the server
  // should return.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The filtering results.
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
}

// The response message for
// [ListFrameworkComplianceSummariesResponse][google.cloud.cloudsecuritycompliance.v1.ListFrameworkComplianceSummariesResponse].
message ListFrameworkComplianceSummariesResponse {
  // The list of framework compliance summaries.
  repeated FrameworkComplianceSummary framework_compliance_summaries = 1;

  // Output only. The token to retrieve the next page of results.
  string next_page_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The response message for [GetFrameworkComplianceReport][].
message FrameworkComplianceReport {
  option (google.api.resource) = {
    type: "cloudsecuritycompliance.googleapis.com/FrameworkComplianceReport"
    pattern: "projects/{project}/locations/{location}/frameworkComplianceReports/{framework_compliance_report}"
    pattern: "folders/{folder}/locations/{location}/frameworkComplianceReports/{framework_compliance_report}"
    pattern: "organizations/{organization}/locations/{location}/frameworkComplianceReports/{framework_compliance_report}"
    plural: "frameworkComplianceReports"
    singular: "frameworkComplianceReport"
  };

  // The name of the framework.
  string framework = 1;

  // The description of the framework.
  string framework_description = 2;

  // Output only. The last updated time of the report.
  google.protobuf.Timestamp update_time = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // The control assessment details of the framework.
  ControlAssessmentDetails control_assessment_details = 4;

  // The type of framework.
  Framework.FrameworkType framework_type = 5;

  // The list of cloud providers supported by the framework.
  repeated CloudProvider supported_cloud_providers = 6;

  // The list of framework categories supported.
  repeated FrameworkCategory framework_categories = 7;

  // Optional. The display name for the framework.
  string framework_display_name = 8 [(google.api.field_behavior) = OPTIONAL];

  // Identifier. The name of the framework compliance report.
  string name = 9 [(google.api.field_behavior) = IDENTIFIER];

  // The latest major revision ID of the framework.
  int64 major_revision_id = 10;

  // The latest minor revision ID of the latest major revision of the framework.
  int64 minor_revision_id = 11;

  // The target resource details of the framework.
  repeated TargetResourceDetails target_resource_details = 12;
}

// The request message for [FetchFrameworkComplianceReport][].
message FetchFrameworkComplianceReportRequest {
  // Required. The name of the framework compliance report to retrieve.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudsecuritycompliance.googleapis.com/FrameworkComplianceReport"
    }
  ];

  // Optional. The end time of the report.
  google.protobuf.Timestamp end_time = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// The request message for [ListFindingSummaries][].
message ListFindingSummariesRequest {
  // Required. The parent scope for the framework overview page.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "cloudsecuritycompliance.googleapis.com/FindingSummary"
    }
  ];

  // Optional. The requested page size. The server might return fewer items than
  //  requested. If unspecified, the server picks an appropriate default.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A token that identifies the page of results that the server
  // should return.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The filtering results.
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The end time of the finding summary.
  google.protobuf.Timestamp end_time = 5
      [deprecated = true, (google.api.field_behavior) = OPTIONAL];
}

// The response message for [ListFindingSummaries][].
message ListFindingSummariesResponse {
  // List of finding summary by category.
  repeated FindingSummary finding_summaries = 1;

  // Output only. The token to retrieve the next page of results.
  string next_page_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The request message for [ListControlComplianceSummaries][].
message ListControlComplianceSummariesRequest {
  // Required. The parent scope for the framework overview page.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "cloudsecuritycompliance.googleapis.com/ControlComplianceSummary"
    }
  ];

  // Optional. The end time of the control compliance summary.
  google.protobuf.Timestamp end_time = 2
      [deprecated = true, (google.api.field_behavior) = OPTIONAL];

  // Optional. The requested page size. The server might return fewer items than
  // requested. If unspecified, the server picks an appropriate default.
  int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A token that identifies the page of results that the server
  // should return.
  string page_token = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The filtering results.
  string filter = 5 [(google.api.field_behavior) = OPTIONAL];
}

// The response message for [ListControlComplianceSummaries][].
message ListControlComplianceSummariesResponse {
  // The list of control compliance details.
  repeated ControlComplianceSummary control_compliance_summaries = 1;

  // Output only. The token to retrieve the next page of results.
  string next_page_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The request message for [AggregateFrameworkComplianceReport][].
message AggregateFrameworkComplianceReportRequest {
  // Required. The name of the aggregated compliance report over time to
  // retrieve.
  //
  // The supported format is:
  // `organizations/{organization_id}/locations/{location}/frameworkComplianceReports/{framework_compliance_report}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudsecuritycompliance.googleapis.com/FrameworkComplianceReport"
    }
  ];

  // Optional. The start and end time range for the aggregated compliance
  // report.
  google.type.Interval interval = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The filtering results.
  string filter = 3 [(google.api.field_behavior) = OPTIONAL];
}

// The response message for [AggregateFrameworkComplianceReport][].
message AggregateFrameworkComplianceReportResponse {
  // The list of aggregated compliance reports.
  repeated AggregatedComplianceReport aggregated_compliance_reports = 1;
}

// The details for a control assessment.
message ControlAssessmentDetails {
  // The number of controls that are passing or not assessed.
  int32 passing_controls = 1;

  // The number of controls that are failing.
  int32 failing_controls = 2;

  // The number of controls that were assessed and are passing.
  int32 assessed_passing_controls = 3;

  // The number of controls that aren't assessed because they require manual
  // review.
  int32 not_assessed_controls = 4;
}

// The details for a framework compliance summary.
message FrameworkComplianceSummary {
  option (google.api.resource) = {
    type: "cloudsecuritycompliance.googleapis.com/FrameworkComplianceSummary"
    pattern: "projects/{project}/locations/{location}/frameworkComplianceSummaries/{framework_compliance_summary}"
    pattern: "folders/{folder}/locations/{location}/frameworkComplianceSummaries/{framework_compliance_summary}"
    pattern: "organizations/{organization}/locations/{location}/frameworkComplianceSummaries/{framework_compliance_summary}"
    plural: "frameworkComplianceSummaries"
    singular: "frameworkComplianceSummary"
  };

  // The name of the framework.
  string framework = 1;

  // The control assessment details of the framework.
  ControlAssessmentDetails control_assessment_details = 2;

  // The type of framework.
  Framework.FrameworkType framework_type = 3;

  // The list of cloud providers supported by the framework.
  repeated CloudProvider supported_cloud_providers = 4;

  // The list of framework categories supported by the framework.
  repeated FrameworkCategory framework_categories = 5;

  // Optional. The display name for the framework.
  string framework_display_name = 6 [(google.api.field_behavior) = OPTIONAL];

  // Identifier. The name of the framework compliance summary.
  string name = 7 [(google.api.field_behavior) = IDENTIFIER];

  // The major revision ID of the framework.
  int64 major_revision_id = 8;

  // The minor revision ID of the framework.
  int64 minor_revision_id = 9;

  // The target resource details for the framework.
  repeated TargetResourceDetails target_resource_details = 10;
}

// The details for a finding.
message FindingSummary {
  option (google.api.resource) = {
    type: "cloudsecuritycompliance.googleapis.com/FindingSummary"
    pattern: "projects/{project}/locations/{location}/findingSummaries/{finding_summary}"
    pattern: "folders/{folder}/locations/{location}/findingSummaries/{finding_summary}"
    pattern: "organizations/{organization}/locations/{location}/findingSummaries/{finding_summary}"
    plural: "findingSummaries"
    singular: "findingSummary"
  };

  // The category of the finding.
  string finding_category = 1;

  // The class of the finding.
  FindingClass finding_class = 2;

  // The severity of the finding.
  Severity severity = 3;

  // The count of the finding.
  int64 finding_count = 4;

  // Output only. The last updated time of the finding.
  google.protobuf.Timestamp update_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The list of compliance frameworks that the finding belongs to.
  repeated string related_frameworks = 6
      [(google.api.field_behavior) = OPTIONAL];

  // Identifier. The name of the finding summary.
  string name = 7 [(google.api.field_behavior) = IDENTIFIER];
}

// The details for control compliance.
message ControlComplianceSummary {
  option (google.api.resource) = {
    type: "cloudsecuritycompliance.googleapis.com/ControlComplianceSummary"
    pattern: "projects/{project}/locations/{location}/frameworkComplianceReports/{framework_compliance_report}/controlComplianceSummaries/{control_compliance_summary}"
    pattern: "folders/{folder}/locations/{location}/frameworkComplianceReports/{framework_compliance_report}/controlComplianceSummaries/{control_compliance_summary}"
    pattern: "organizations/{organization}/locations/{location}/frameworkComplianceReports/{framework_compliance_report}/controlComplianceSummaries/{control_compliance_summary}"
    plural: "controlComplianceSummaries"
    singular: "controlComplianceSummary"
  };

  // The name of the control.
  string control = 1;

  // The display name of the control.
  string display_name = 2;

  // The description of the control.
  string description = 3;

  // Output only. The overall evaluation status of the control.
  EvaluationState overall_evaluation_state = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // The total number of findings for the control.
  int32 total_findings_count = 5;

  // The list of compliance frameworks that the control belongs to.
  repeated string compliance_frameworks = 6;

  // The list of similar controls.
  repeated SimilarControls similar_controls = 7;

  // The list of cloud control reports.
  repeated CloudControlReport cloud_control_reports = 8;

  // The responsibility type for the control.
  RegulatoryControlResponsibilityType control_responsibility_type = 9;

  // Whether the control is a fake control. Fake controls are created
  // and mapped to cloud controls that don't belong to a control group.
  bool is_fake_control = 10;

  // Identifier. The name of the control compliance summary.
  string name = 11 [(google.api.field_behavior) = IDENTIFIER];
}

// The cloud control report.
message CloudControlReport {
  // The assessment details of the cloud control.
  oneof assessment_details {
    // The details of a manual cloud control assessment.
    ManualCloudControlAssessmentDetails
        manual_cloud_control_assessment_details = 13;

    // The details of a cloud control assessment.
    CloudControlAssessmentDetails cloud_control_assessment_details = 14;
  }

  // The name of the cloud control.
  string cloud_control = 1;

  // The display name of the cloud control.
  string display_name = 2;

  // The description of the cloud control.
  string description = 3;

  // The list of categories for the cloud control.
  repeated string categories = 6;

  // The list of similar controls.
  repeated SimilarControls similar_controls = 9;

  // The type of the cloud control.
  CloudControl.Type cloud_control_type = 10;

  // The category of the finding.
  string finding_category = 11;

  // The list of rules that correspond to the cloud control.
  repeated Rule rules = 12;

  // The severity of the finding.
  Severity finding_severity = 15;

  // The enforcement mode of the cloud control.
  EnforcementMode enforcement_mode = 16;

  // The name of the cloud control deployment.
  string cloud_control_deployment = 17;

  // The major revision ID of the cloud control.
  int64 major_revision_id = 18;

  // The minor revision ID of the cloud control.
  int64 minor_revision_id = 19;

  // The major revision IDs of the frameworks that the cloud control belongs to.
  repeated int64 framework_major_revision_ids = 20;
}

// The details for a manual cloud control assessment.
message ManualCloudControlAssessmentDetails {
  // The guide for assessing a cloud control manually.
  repeated string manual_cloud_control_guide = 1;
}

// The cloud control assessment details for non-manual cloud controls.
message CloudControlAssessmentDetails {
  // The number of findings for the cloud control.
  int32 findings_count = 1;

  // Output only. The evaluation status of the cloud control.
  EvaluationState evaluation_state = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The similar controls.
message SimilarControls {
  // The name of the framework.
  string framework = 1;

  // The ID of the control.
  string control_id = 2;
}

// The aggregated compliance report.
message AggregatedComplianceReport {
  // The control assessment details of the framework.
  ControlAssessmentDetails control_assessment_details = 1;

  // The report time of the aggregated compliance report.
  google.protobuf.Timestamp report_time = 2;
}

// The details for a target resource.
message TargetResourceDetails {
  // The framework deployment name for the target resource.
  //
  // For example,
  // `organizations/{organization_id}/locations/{location}/frameworkDeployments/{framework_deployment_id}`
  string framework_deployment = 1;

  // The display name of the target resource. For example, `google.com`,
  // `staging-project`, or `development-folder`.
  string target_resource_display_name = 2;

  // The target resource. For example, `organizations/1234567890`,
  // `projects/1234567890`, or `folders/1234567890`.
  string target_resource = 3;

  // The create time of the target resource.
  google.protobuf.Timestamp create_time = 4;

  // The update time of the target resource.
  google.protobuf.Timestamp update_time = 5;

  // The major revision ID of the framework for the target resource.
  int64 major_revision_id = 6;

  // The minor revision ID of the framework for the target resource.
  int64 minor_revision_id = 7;
}