// 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/longrunning/operations.proto";
import "google/protobuf/timestamp.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 = "AuditProto";
option java_package = "com.google.cloud.cloudsecuritycompliance.v1";
option php_namespace = "Google\\Cloud\\CloudSecurityCompliance\\V1";
option ruby_package = "Google::Cloud::CloudSecurityCompliance::V1";

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

  // Generates an audit scope report for a framework.
  rpc GenerateFrameworkAuditScopeReport(
      GenerateFrameworkAuditScopeReportRequest)
      returns (GenerateFrameworkAuditScopeReportResponse) {
    option (google.api.http) = {
      post: "/v1/{scope=folders/*/locations/*}/frameworkAuditScopeReports:generateFrameworkAuditScopeReport"
      body: "*"
      additional_bindings {
        post: "/v1/{scope=projects/*/locations/*}/frameworkAuditScopeReports:generateFrameworkAuditScopeReport"
        body: "*"
      }
      additional_bindings {
        post: "/v1/{scope=organizations/*/locations/*}/frameworkAuditScopeReports:generateFrameworkAuditScopeReport"
        body: "*"
      }
    };
    option (google.api.method_signature) =
        "scope,report_format,compliance_framework";
  }

  // Creates an audit scope report for a framework.
  rpc CreateFrameworkAudit(CreateFrameworkAuditRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1/{parent=organizations/*/locations/*}/frameworkAudits"
      body: "framework_audit"
      additional_bindings {
        post: "/v1/{parent=folders/*/locations/*}/frameworkAudits"
        body: "framework_audit"
      }
      additional_bindings {
        post: "/v1/{parent=projects/*/locations/*}/frameworkAudits"
        body: "framework_audit"
      }
    };
    option (google.api.method_signature) =
        "parent,framework_audit,framework_audit_id";
    option (google.longrunning.operation_info) = {
      response_type: "FrameworkAudit"
      metadata_type: "google.cloud.cloudsecuritycompliance.v1.OperationMetadata"
    };
  }

  // Lists the framework audits for a given organization, folder, or project.
  rpc ListFrameworkAudits(ListFrameworkAuditsRequest)
      returns (ListFrameworkAuditsResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=organizations/*/locations/*}/frameworkAudits"
      additional_bindings {
        get: "/v1/{parent=folders/*/locations/*}/frameworkAudits"
      }
      additional_bindings {
        get: "/v1/{parent=projects/*/locations/*}/frameworkAudits"
      }
    };
    option (google.api.method_signature) = "parent";
  }

  // Gets the details for a framework audit.
  rpc GetFrameworkAudit(GetFrameworkAuditRequest) returns (FrameworkAudit) {
    option (google.api.http) = {
      get: "/v1/{name=organizations/*/locations/*/frameworkAudits/*}"
      additional_bindings {
        get: "/v1/{name=folders/*/locations/*/frameworkAudits/*}"
      }
      additional_bindings {
        get: "/v1/{name=projects/*/locations/*/frameworkAudits/*}"
      }
    };
    option (google.api.method_signature) = "name";
  }
}

// The state of compliance after evaluation is complete.
enum ComplianceState {
  // Default value. This value is unused.
  COMPLIANCE_STATE_UNSPECIFIED = 0;

  // The resource is compliant.
  COMPLIANT = 1;

  // The resource has a violation.
  VIOLATION = 2;

  // The resource requires manual review from you.
  MANUAL_REVIEW_NEEDED = 3;

  // An error occurred while computing the resource status.
  ERROR = 4;

  // The resource can't be audited.
  AUDIT_NOT_SUPPORTED = 5;
}

// The request message for [GenerateFrameworkAuditScopeReport][].
message GenerateFrameworkAuditScopeReportRequest {
  // The set of options for the audit scope report format.
  enum Format {
    // Default value. This value is unused.
    FORMAT_UNSPECIFIED = 0;

    // The report format is the Open Document Format (ODF).
    ODF = 1;
  }

  // Required. The organization, folder or project for the audit report.
  //
  // Supported formats are the following:
  //
  // * `projects/{project_id}/locations/{location}`
  // * `folders/{folder_id}/locations/{location}`
  // * `organizations/{organization_id}/locations/{location}`
  string scope = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The format that the scope report bytes is returned in.
  Format report_format = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The compliance framework that the scope report is generated for.
  string compliance_framework = 3 [(google.api.field_behavior) = REQUIRED];
}

// The response message for [GenerateFrameworkAuditScopeReport][].
message GenerateFrameworkAuditScopeReportResponse {
  option (google.api.resource) = {
    type: "cloudsecuritycompliance.googleapis.com/GenerateFrameworkAuditScopeReportResponse"
    pattern: "projects/{project}/locations/{location}/frameworkAuditScopeReports/{generate_framework_audit_scope_report_response}"
    pattern: "organizations/{organization}/locations/{location}/frameworkAuditScopeReports/{generate_framework_audit_scope_report_response}"
    plural: "frameworkAuditScopeReports"
    singular: "generateFrameworkAuditScopeReportResponse"
  };

  // The set of options that the audit scope report is exported in.
  oneof audit_report {
    // The audit scope report content in byte format.
    bytes scope_report_contents = 3;
  }

  // Identifier. The name of the audit report, in the format that was
  // given in the request.
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Required. The compliance framework that the audit scope report is generated
  // for.
  string compliance_framework = 2 [(google.api.field_behavior) = REQUIRED];
}

// Additional information for an audit operation.
message ReportSummary {
  // Output only. The total number of checks.
  int32 total_count = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The number of compliant checks.
  int32 compliant_count = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The number of checks with violations.
  int32 violation_count = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The number of checks with "manual review needed" status.
  int32 manual_review_needed_count = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The number of checks that can't be performed due to errors.
  int32 error_count = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The request message for [CreateFrameworkAudit][].
message CreateFrameworkAuditRequest {
  // Required. The parent resource where this framework audit is created.
  //
  // Supported formats are the following:
  //
  // * `organizations/{organization_id}/locations/{location}`
  // * `folders/{folder_id}/locations/{location}`
  // * `projects/{project_id}/locations/{location}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "cloudsecuritycompliance.googleapis.com/FrameworkAudit"
    }
  ];

  // Optional. The ID to use for the framework audit. The ID becomes the final
  // component of the framework audit's full resource name.
  //
  // The ID must be between 4-63 characters, and valid characters
  // are `\[a-z][0-9]-\`.
  string framework_audit_id = 2 [(google.api.field_behavior) = OPTIONAL];

  // Required. The framework audit to create.
  FrameworkAudit framework_audit = 3 [(google.api.field_behavior) = REQUIRED];
}

// A destination for the framework audit.
message FrameworkAuditDestination {
  // The type of destination.
  oneof destination_type {
    // The Cloud Storage bucket destination.
    BucketDestination bucket = 1;
  }
}

// A Cloud Storage bucket destination.
message BucketDestination {
  // The set of options for the framework audit format.
  enum Format {
    // Default value. This value is unused.
    FORMAT_UNSPECIFIED = 0;

    // The format for the framework audit report is Open Document.
    ODF = 1;
  }

  // Required. The URI of the Cloud Storage bucket.
  string bucket_uri = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The format of the framework audit.
  Format framework_audit_format = 3 [(google.api.field_behavior) = OPTIONAL];
}

// A framework audit.
message FrameworkAudit {
  option (google.api.resource) = {
    type: "cloudsecuritycompliance.googleapis.com/FrameworkAudit"
    pattern: "projects/{project}/locations/{location}/frameworkAudits/{framework_audit}"
    pattern: "organizations/{organization}/locations/{location}/frameworkAudits/{framework_audit}"
    plural: "frameworkAudits"
    singular: "frameworkAudit"
  };

  // The state of the framework audit.
  enum State {
    // Default value. This value is unused.
    STATE_UNSPECIFIED = 0;

    // The audit is scheduled.
    SCHEDULED = 1;

    // The audit is running.
    RUNNING = 2;

    // The audit results are being uploaded.
    UPLOADING = 3;

    // The audit failed.
    FAILED = 4;

    // The audit completed successfully.
    SUCCEEDED = 5;
  }

  // Output only. Identifier. The name of the framework audit.
  string name = 1 [
    (google.api.field_behavior) = IDENTIFIER,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];

  // Output only. The ID of the framework audit.
  string framework_audit_id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The compliance framework used for the audit.
  string compliance_framework = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The scope of the audit.
  string scope = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. The destination for the audit reports.
  FrameworkAuditDestination framework_audit_destination = 5
      [(google.api.field_behavior) = REQUIRED];

  // Output only. The time that the audit started.
  google.protobuf.Timestamp start_time = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time that the audit finished.
  google.protobuf.Timestamp finish_time = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The overall compliance state of the audit.
  ComplianceState compliance_state = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The summary of the report.
  ReportSummary report_summary = 9 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The details for the cloud control groups within this audit.
  repeated CloudControlGroupAuditDetails cloud_control_group_audit_details = 10
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The details for the cloud controls within this audit.
  repeated CloudControlAuditDetails cloud_control_audit_details = 11
      [(google.api.field_behavior) = OPTIONAL];

  // Output only. The ID of the long-running operation.
  string operation_id = 12 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The framework audit state of the audit.
  State state = 13 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The request message for [ListFrameworkAudits][].
message ListFrameworkAuditsRequest {
  // Required. The parent resource where the framework audits are listed.
  //
  // Supported formats are the following:
  //
  // * `organizations/{organization_id}/locations/{location}`
  // * `folders/{folder_id}/locations/{location}`
  // * `projects/{project_id}/locations/{location}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "cloudsecuritycompliance.googleapis.com/FrameworkAudit"
    }
  ];

  // Optional. The maximum number of framework audits to return. The service
  // might return fewer audits than this value. If unspecified, a maximum of 10
  // framework audits are returned. The maximum value is 50; values above 50 are
  // limited to 50.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The `next_page_token` value that's returned from a previous list
  // request, if any.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The filters to apply to the framework audits.
  // Supported filters are `compliance_framework`, `compliance_state`,
  // `create_time,` and `framework_audit_name`. If the filter is invalid, an
  // invalid argument error is returned.
  // For syntax details, see [AIP-160][https://google.aip.dev/160].
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
}

// The response message for [ListFrameworkAudits][].
message ListFrameworkAuditsResponse {
  // The framework audits.
  repeated FrameworkAudit framework_audits = 1;

  // A token, which you can send as the `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

// The request message for [GetFrameworkAudit][].
message GetFrameworkAuditRequest {
  // Required. The name of the framework audit to retrieve.
  //
  // Supported formats are the following:
  //
  // * `organizations/{organization_id}/locations/{location}/frameworkAudits/{frameworkAuditName}`
  // * `folders/{folder_id}/locations/{location}/frameworkAudits/{frameworkAuditName}`
  // * `projects/{project_id}/locations/{location}/frameworkAudits/{frameworkAuditName}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudsecuritycompliance.googleapis.com/FrameworkAudit"
    }
  ];
}

// The details for a cloud control group.
message CloudControlGroupAuditDetails {
  // Output only. The ID of the cloud control group.
  string cloud_control_group_id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The display name of the cloud control group.
  string display_name = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The description of the cloud control group.
  string description = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The responsibility type.
  string responsibility_type = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The description of Google's responsibility.
  string google_responsibility_description = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The implementation of Google's responsibility.
  string google_responsibility_implementation = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The description of your responsibility.
  string customer_responsibility_description = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The implementation of your responsibility.
  string customer_responsibility_implementation = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The compliance state of the control group.
  ComplianceState compliance_state = 9
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The ID of the regulatory control.
  string control_id = 10 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The control family.
  ControlFamily control_family = 11 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The details for the cloud controls within this group.
  repeated CloudControlAuditDetails cloud_control_details = 12
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The summary of the report.
  ReportSummary report_summary = 13 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The details for a finding.
message FindingDetails {
  // Output only. The name of the finding.
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The compliance state of the finding.
  ComplianceState compliance_state = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The observation details for the finding.
  ObservationDetails observation = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The evidence details for the finding.
  EvidenceDetails evidence = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The observation details for a finding.
message ObservationDetails {
  // Output only. The current value.
  string current_value = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The expected value.
  string expected_value = 2 [(google.api.field_behavior) = OPTIONAL];

  // Output only. Any guidance for the observation.
  string guidance = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The evidence details for a finding.
message EvidenceDetails {
  // Output only. The resource identifier.
  string resource = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The service identifier.
  string service = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The path to the evidence.
  string evidence_path = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The details for a cloud control audit.
message CloudControlAuditDetails {
  // Output only. The name of the cloud control.
  string cloud_control = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The ID of the cloud control.
  string cloud_control_id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The description of the cloud control.
  string cloud_control_description = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The overall status of the findings for the control.
  ComplianceState compliance_state = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The summary of the report.
  ReportSummary report_summary = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The findings for the control.
  repeated FindingDetails findings = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];
}