syntax = "proto3";

import "buf/validate/validate.proto";
import "google/protobuf/any.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

import "audit/v1/common.proto";

package audit.v1;

option go_package = "./audit;auditV1";
option java_multiple_files = true;
option java_package = "com.schwarz.stackit.audit.v1";

// TODO update numbers of elements in messages

// The audit log entry can be used to record an incident in the audit log.
message AuditLogEntry {

  // The resource name of the log to which this log entry belongs.
  string log_name = 12;

  // The monitored resource that produced this log entry.
  //
  // Example: a log entry that reports a database error would be associated with
  // the monitored resource designating the particular database that reported
  // the error.
  MonitoredResource resource = 8;

  // The log entry payload, which is always an AuditLog for STACKIT Audit Log events.
  AuditLog proto_payload = 2;

  // A unique identifier for the log entry.
  string insert_id = 4;

  // A set of user-defined (key, value) data that provides additional
  // information about the log entry.
  map<string, string> labels = 11;

  // Information about an operation associated with the log entry, if applicable.
  LogEntryOperation operation = 15;

  // The time the event described by the log entry occurred.
  google.protobuf.Timestamp timestamp = 9;

  // TODO do we need it? where will we set it?
  // The time the log entry was received by Logging.
  google.protobuf.Timestamp receive_timestamp = 24;

  // The severity of the log entry.
  LogSeverity severity = 10;

  // TODO check example
  // Resource name of the trace associated with the log entry, if any. It
  // contains a relative resource name. Example:
  // `projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824`
  string trace = 22;

  // TODO check format and description
  // The span ID within the trace associated with the log entry, if any.
  //
  // For Trace spans, this is the same format that the Trace API v2 uses: a
  // 16-character hexadecimal encoding of an 8-byte array, such as
  // `000000000000004a`.
  string span_id = 27;

  // Information indicating this log entry is part of a sequence of multiple logs
  // split from a single log entry.
  LogSplit split = 35;
}

// An object representing a resource that can be used for monitoring, logging,
// billing, or other purposes.
message MonitoredResource {

  // Required. The monitored resource type. For example, the type of a
  // STACKIT Server instance is `gce_instance`.
  string type = 1;

  // TODO check the label values
  // Values for all of the labels listed in the associated monitored
  // resource descriptor. For example, STACKIT Server instances use the
  // labels `"project_id"`, `"instance_id"`, and `"zone"`.
  map<string, string> labels = 2;
}

// Additional information about a potentially long-running operation with which
// a log entry is associated.
message LogEntryOperation {

  // An arbitrary operation identifier. Log entries with the same
  // identifier are assumed to be part of the same operation.
  string id = 1;

  // TODO check examples
  // An arbitrary producer identifier. The combination of `id` and
  // `producer` must be globally unique. Examples for `producer`:
  // `"MyDivision.MyBigCompany.com"`, `"github.com/MyProject/MyApplication"`.
  string producer = 2;

  // True if this is the first log entry in the operation.
  bool first = 3;

  // True if this is the last log entry in the operation.
  bool last = 4;
}

// TODO check description and levels
// The severity of the event described in a log entry, expressed as one of the
// standard severity levels listed below.  For your reference, the levels are
// assigned the listed numeric values. The effect of using numeric values other
// than those listed is undefined.
// Copied from
// https://github.com/googleapis/googleapis/blob/master/google/logging/type/log_severity.proto
enum LogSeverity {

  // (0) The log entry has no assigned severity level.
  DEFAULT = 0;

  // (100) Debug or trace information.
  DEBUG = 100;

  // (200) Routine information, such as ongoing status or performance.
  INFO = 200;

  // (300) Normal but significant events, such as start up, shut down, or
  // a configuration change.
  NOTICE = 300;

  // (400) Warning events might cause problems.
  WARNING = 400;

  // (500) Error events are likely to cause problems.
  ERROR = 500;

  // (600) Critical events cause more severe problems or outages.
  CRITICAL = 600;

  // (700) A person must take an action immediately.
  ALERT = 700;

  // (800) One or more systems are unusable.
  EMERGENCY = 800;
}

// TODO check description
// Common audit log format for STACKIT API operations.
// Copied from
// https://github.com/googleapis/googleapis/blob/master/google/cloud/audit/audit_log.proto,
// but changing service_data from Any to Struct.
message AuditLog {

  // TODO check example
  // The name of the API service performing the operation. For example,
  // `"datastore.googleapis.com"`.
  string service_name = 7;

  // TODO check example
  // The name of the service method or operation.
  // For API calls, this should be the name of the API method.
  // For example,
  //
  //     "google.datastore.v1.Datastore.RunQuery"
  //     "google.logging.v1.LoggingService.DeleteLog"
  string method_name = 8;

  // TODO check example
  // The resource or collection that is the target of the operation.
  // The name is a scheme-less URI, not including the API service name.
  // For example:
  //
  //     "shelves/SHELF_ID/books"
  //     "shelves/SHELF_ID/books/BOOK_ID"
  string resource_name = 11;

  // The resource location information.
  ResourceLocation resource_location = 20;

  // TODO check what's meant with @type property
  // The resource's original state before mutation. Present only for
  // operations which have successfully modified the targeted resource(s).
  // In general, this field should contain all changed fields, except those
  // that are already been included in `request`, `response`, `metadata` or
  // `service_data` fields.
  // When the JSON object represented here has a proto equivalent,
  // the proto name will be indicated in the `@type` property.
  google.protobuf.Struct resource_original_state = 19;

  // The number of items returned from a List or Query API method,
  // if applicable.
  int64 num_response_items = 12;

  // The status of the overall operation.
  RpcStatus status = 2;

  // Authentication information.
  AuthenticationInfo authentication_info = 3;

  // Authorization information. If there are multiple
  // resources or permissions involved, then there is
  // one AuthorizationInfo element for each {resource, permission} tuple.
  repeated AuthorizationInfo authorization_info = 9;

  // Metadata about the operation.
  RequestMetadata request_metadata = 4;

  // TODO check what's meant with @type property
  // The operation request. This may not include all request parameters,
  // such as those that are too large, privacy-sensitive, or duplicated
  // elsewhere in the log record.
  // It should never include user-generated data, such as file contents.
  // When the JSON object represented here has a proto equivalent, the proto
  // name will be indicated in the `@type` property.
  google.protobuf.Struct request = 16;

  // TODO check what's meant with @type property
  // The operation response. This may not include all response elements,
  // such as those that are too large, privacy-sensitive, or duplicated
  // elsewhere in the log record.
  // It should never include user-generated data, such as file contents.
  // When the JSON object represented here has a proto equivalent, the proto
  // name will be indicated in the `@type` property.
  google.protobuf.Struct response = 17;

  // Other service-specific data about the request, response, and other
  // information associated with the current audited event.
  google.protobuf.Struct metadata = 18;
}

// Authentication information for the operation.
message AuthenticationInfo {

  // TODO check description - do we need the id as well?
  // The email address of the authenticated user (or service account on behalf
  // of third party principal) making the request. For third party identity
  // callers, the `principal_subject` field is populated instead of this field.
  // For privacy reasons, the principal email address is sometimes redacted.
  // For more information, see [Caller identities in audit
  // logs](https://cloud.google.com/logging/docs/audit#user-id).
  string principal_email = 1;

  // The authority selector specified by the requestor, if any.
  // It is not guaranteed that the principal was allowed to use this authority.
  string authority_selector = 2;

  // TODO check @type
  // The third party identification (if any) of the authenticated user making
  // the request.
  // When the JSON object represented here has a proto equivalent, the proto
  // name will be indicated in the `@type` property.
  google.protobuf.Struct third_party_principal = 4;

  // TODO check example
  // The name of the service account key used to create or exchange
  // credentials for authenticating the service account making the request.
  // This is a scheme-less URI full resource name. For example:
  //
  // "//iam.googleapis.com/projects/{PROJECT_ID}/serviceAccounts/{ACCOUNT}/keys/{key}"
  string service_account_key_name = 5;

  // Identity delegation history of an authenticated service account that makes
  // the request. It contains information on the real authorities that try to
  // access STACKIT resources by delegating on a service account. When multiple
  // authorities present, they are guaranteed to be sorted based on the original
  // ordering of the identity delegation events.
  repeated ServiceAccountDelegationInfo service_account_delegation_info = 6;

  // String representation of identity of requesting party.
  // Populated for both first and third party identities.
  string principal_subject = 8;
}

// Authorization information for the operation.
message AuthorizationInfo {

  // TODO check example
  // The resource being accessed, as a REST-style string. For example:
  //
  //     bigquery.googleapis.com/projects/PROJECTID/datasets/DATASETID
  string resource = 1;

  // The required IAM permission.
  string permission = 2;

  // Whether or not authorization for `resource` and `permission`
  // was granted.
  bool granted = 3;

  // Resource attributes used in IAM condition evaluation. This field contains
  // resource attributes like resource type and resource name.
  //
  // To get the whole view of the attributes used in IAM
  // condition evaluation, the user must also look into
  // `AuditLog.request_metadata.request_attributes`.
  AttributeContext.Resource resource_attributes = 5;
}

// TODO check description
// This message defines the standard attribute vocabulary for STACKIT APIs.
//
// An attribute is a piece of metadata that describes an activity on a network
// service. For example, the size of an HTTP request, or the status code of
// an HTTP response.
//
// Each attribute has a type and a name, which is logically defined as
// a proto message field in `AttributeContext`. The field type becomes the
// attribute type, and the field path becomes the attribute name. For example,
// the attribute `source.ip` maps to field `AttributeContext.source.ip`.
//
// This message definition is guaranteed not to have any wire breaking change.
// So you can use it directly for passing attributes across different systems.
//
// NOTE: Different system may generate different subset of attributes. Please
// verify the system specification before relying on an attribute generated
// a system.
message AttributeContext {

  // This message defines attributes for a node that handles a network request.
  // The node can be either a service or an application that sends, forwards,
  // or receives the request. Service peers should fill in
  // `principal` and `labels` as appropriate.
  message Peer {

    // The IP address of the peer.
    string ip = 1;

    // The network port of the peer.
    int64 port = 2;

    // The labels associated with the peer.
    map<string, string> labels = 6;

    // The identity of this peer. Similar to `Request.auth.principal`, but
    // relative to the peer instead of the request. For example, the
    // identity associated with a load balancer that forwarded the request.
    string principal = 7;

    // The CLDR country/region code associated with the above IP address.
    // If the IP address is private, the `region_code` should reflect the
    // physical location where this peer is running.
    string region_code = 8;
  }

  // This message defines request authentication attributes. Terminology is
  // based on the JSON Web Token (JWT) standard, but the terms also
  // correlate to concepts in other standards.
  message Auth {

    // TODO check description
    // The authenticated principal. Reflects the issuer (`iss`) and subject
    // (`sub`) claims within a JWT. The issuer and subject should be `/`
    // delimited, with `/` percent-encoded within the subject fragment. For
    // Google accounts, the principal format is:
    // "https://accounts.google.com/{id}"
    string principal = 1;

    // TODO check description
    // The intended audience(s) for this authentication information. Reflects
    // the audience (`aud`) claim within a JWT. The audience
    // value(s) depends on the `issuer`, but typically include one or more of
    // the following pieces of information:
    //
    // *  The services intended to receive the credential such as
    //    ["pubsub.googleapis.com", "storage.googleapis.com"]
    // *  A set of service-based scopes. For example,
    //    ["https://www.googleapis.com/auth/cloud-platform"]
    // *  The client id of an app, such as the Firebase project id for JWTs
    //    from Firebase Auth.
    //
    // Consult the documentation for the credential issuer to determine the
    // information provided.
    repeated string audiences = 2;

    // TODO check description
    // The authorized presenter of the credential. Reflects the optional
    // Authorized Presenter (`azp`) claim within a JWT or the
    // OAuth client id. For example, a Google Cloud Platform client id looks
    // as follows: "123456789012.apps.googleusercontent.com".
    string presenter = 3;

    // TODO check description
    // Structured claims presented with the credential. JWTs include
    // `{key: value}` pairs for standard and private claims. The following
    // is a subset of the standard required and optional claims that would
    // typically be presented for a Google-based JWT:
    //
    //    {'iss': 'accounts.google.com',
    //     'sub': '113289723416554971153',
    //     'aud': ['123456789012', 'pubsub.googleapis.com'],
    //     'azp': '123456789012.apps.googleusercontent.com',
    //     'email': 'jsmith@example.com',
    //     'iat': 1353601026,
    //     'exp': 1353604926}
    //
    // SAML assertions are similarly specified, but with an identity provider
    // dependent structure.
    google.protobuf.Struct claims = 4;

    // TODO check description
    // A list of access level resource names that allow resources to be
    // accessed by authenticated requester. It is part of Secure GCP processing
    // for the incoming request. An access level string has the format:
    // "//{api_service_name}/accessPolicies/{policy_id}/accessLevels/{short_name}"
    //
    // Example:
    // "//accesscontextmanager.googleapis.com/accessPolicies/MY_POLICY_ID/accessLevels/MY_LEVEL"
    repeated string access_levels = 5;
  }

  // This message defines attributes for an HTTP request. If the actual
  // request is not an HTTP request, the runtime system should try to map
  // the actual request to an equivalent HTTP request.
  message Request {

    // The unique ID for a request, which can be propagated to downstream
    // systems. The ID should have low probability of collision
    // within a single day for a specific service.
    string id = 1;

    // The HTTP request method, such as `GET`, `POST`.
    string method = 2;

    // The HTTP request headers. If multiple headers share the same key, they
    // must be merged according to the HTTP spec. All header keys must be
    // lowercased, because HTTP header keys are case-insensitive.
    map<string, string> headers = 3;

    // The HTTP URL path.
    string path = 4;

    // The HTTP request `Host` header value.
    string host = 5;

    // The HTTP URL scheme, such as `http` and `https`.
    string scheme = 6;

    // The HTTP URL query in the format of `name1=value1&name2=value2`, as it
    // appears in the first line of the HTTP request. No decoding is performed.
    string query = 7;

    // The timestamp when the `destination` service receives the first byte of
    // the request.
    google.protobuf.Timestamp time = 9;

    // The HTTP request size in bytes. If unknown, it must be -1.
    int64 size = 10;

    // The network protocol used with the request, such as "http/1.1",
    // "spdy/3", "h2", "h2c", "webrtc", "tcp", "udp", "quic". See
    // https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
    // for details.
    string protocol = 11;

    // A special parameter for request reason. It is used by security systems
    // to associate auditing information with a request.
    string reason = 12;

    // The request authentication. May be absent for unauthenticated requests.
    // Derived from the HTTP request `Authorization` header or equivalent.
    Auth auth = 13;
  }

  // This message defines attributes for a typical network response. It
  // generally models semantics of an HTTP response.
  message Response {

    // The HTTP response status code, such as `200` and `404`.
    int64 code = 1;

    // The HTTP response size in bytes. If unknown, it must be -1.
    int64 size = 2;

    // The HTTP response headers. If multiple headers share the same key, they
    // must be merged according to HTTP spec. All header keys must be
    // lowercased, because HTTP header keys are case-insensitive.
    map<string, string> headers = 3;

    // The timestamp when the `destination` service generates the first byte of
    // the response.
    google.protobuf.Timestamp time = 4;
  }

  // This message defines core attributes for a resource. A resource is an
  // addressable (named) entity provided by the destination service. For
  // example, a file stored on a network storage service.
  message Resource {

    // TODO check description
    // The name of the service that this resource belongs to, such as
    // `pubsub.googleapis.com`. The service may be different from the DNS
    // hostname that actually serves the request.
    string service = 1;

    // TODO check description
    // The stable identifier (name) of a resource on the `service`. A resource
    // can be logically identified as "//{resource.service}/{resource.name}".
    // The differences between a resource name and a URI are:
    //
    // *   Resource name is a logical identifier, independent of network
    //     protocol and API version. For example,
    //     `//pubsub.googleapis.com/projects/123/topics/news-feed`.
    // *   URI often includes protocol and version information, so it can
    //     be used directly by applications. For example,
    //     `https://pubsub.googleapis.com/v1/projects/123/topics/news-feed`.
    //
    // See https://cloud.google.com/apis/design/resource_names for details.
    string name = 2;

    // TODO check description
    // The type of the resource. The syntax is platform-specific because
    // different platforms define their resources differently.
    //
    // For Google APIs, the type format must be "{service}/{kind}".
    string type = 3;

    // TODO check description (AWS)
    // The labels or tags on the resource, such as AWS resource tags and
    // Kubernetes resource labels.
    map<string, string> labels = 4;
  }
}

// Metadata about the request.
message RequestMetadata {

  // TODO check description
  // The IP address of the caller.
  // For caller from internet, this will be public IPv4 or IPv6 address.
  // For caller from a Compute Engine VM with external IP address, this
  // will be the VM's external IP address. For caller from a Compute
  // Engine VM without external IP address, if the VM is in the same
  // organization (or project) as the accessed resource, `caller_ip` will
  // be the VM's internal IPv4 address, otherwise the `caller_ip` will be
  // redacted to "gce-internal-ip".
  // See https://cloud.google.com/compute/docs/vpc/ for more information.
  string caller_ip = 1;

  // TODO check description
  // The user agent of the caller.
  // This information is not authenticated and should be treated accordingly.
  // For example:
  //
  // +   `google-api-python-client/1.4.0`:
  //     The request was made by the Google API client for Python.
  // +   `Cloud SDK Command Line Tool apitools-client/1.0 gcloud/0.9.62`:
  //     The request was made by the Google Cloud SDK CLI (gcloud).
  // +   `AppEngine-Google; (+http://code.google.com/appengine; appid:
  // s~my-project`:
  //     The request was made from the `my-project` App Engine app.
  string caller_supplied_user_agent = 2;

  // TODO check description
  // The network of the caller.
  // Set only if the network host project is part of the same GCP organization
  // (or project) as the accessed resource.
  // See https://cloud.google.com/compute/docs/vpc/ for more information.
  // This is a scheme-less URI full resource name. For example:
  //
  //     "//compute.googleapis.com/projects/PROJECT_ID/global/networks/NETWORK_ID"
  string caller_network = 3;

  // TODO check description
  // Request attributes used in IAM condition evaluation. This field contains
  // request attributes like request time and access levels associated with
  // the request.
  //
  // To get the whole view of the attributes used in IAM
  // condition evaluation, the user must also look into
  // `AuditLog.authentication_info.resource_attributes`.
  AttributeContext.Request request_attributes = 7;

  // TODO check description
  // The destination of a network activity, such as accepting a TCP connection.
  // In a multi hop network activity, the destination represents the receiver of
  // the last hop. Only two fields are used in this message, Peer.port and
  // Peer.ip. These fields are optionally populated by those services utilizing
  // the IAM condition feature.
  AttributeContext.Peer destination_attributes = 8;
}

// Location information about a resource.
message ResourceLocation {

  // The locations of a resource after the execution of the operation.
  // Requests to create or delete a location based resource must populate
  // the 'current_locations' field and not the 'original_locations' field.
  // For example:
  //
  //     "eu01"
  repeated string current_locations = 1;

  // The locations of a resource prior to the execution of the operation.
  // Requests that mutate the resource's location must populate both the
  // 'original_locations' as well as the 'current_locations' fields.
  // For example:
  //
  //     "eu01"
  repeated string original_locations = 2;
}

// TODO check description
// The `Status` type defines a logical error model that is suitable for
// different programming environments, including REST APIs and RPC APIs. It is
// used by [gRPC](https://github.com/grpc). Each `Status` message contains
// three pieces of data: error code, error message, and error details.
//
// You can find out more about this error model and how to work with it in the
// [API Design Guide](https://cloud.google.com/apis/design/errors).
message RpcStatus {

  // TODO check description
  // The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
  int32 code = 1;

  // A developer-facing error message, which should be in English. Any
  // user-facing error message should be localized and sent in the
  // RpcStatus.details field, or localized by the client.
  string message = 2;

  // TODO replace any with something different (e.g. struct) and update description
  // A list of messages that carry the error details.  There is a common set of
  // message types for APIs to use.
  repeated google.protobuf.Any details = 3;
}

// Identity delegation history of an authenticated service account.
message ServiceAccountDelegationInfo {

  // TODO Introduce but check if needed
  message SystemPrincipal {

    // Metadata about the service that uses the service account.
    google.protobuf.Struct service_metadata = 3;
  }

  // First party identity principal.
  message FirstPartyPrincipal {

    // TODO was added - check if correct
    // STACKIT principal id
    string id = 1;

    // The email address
    optional string principal_email = 2;

    // Metadata about the service that uses the service account.
    google.protobuf.Struct service_metadata = 3;
  }

  // TODO check if needed
  // Third party identity principal.
  message ThirdPartyPrincipal {

    // Metadata about third party identity.
    google.protobuf.Struct third_party_claims = 1;
  }

  // Entity that creates credentials for service account and assumes its
  // identity for authentication.
  oneof Authority {

    // System identity
    SystemPrincipal system_principal = 1;

    // First party (STACKIT) identity as the real authority.
    FirstPartyPrincipal first_party_principal = 2;

    // Third party identity as the real authority.
    ThirdPartyPrincipal third_party_principal = 3;
  }
}

// Additional information used to correlate multiple LogEntries. Used when a
// single log entry would exceed the STACKIT logging size limit and is split
// across multiple entries.
message LogSplit {

  // A globally unique identifier for all log entries in a sequence of split
  // logs. All log entries with the same |LogSplit.uid| are assumed to be part of
  // the same sequence of split logs.
  string uid = 1;

  // The index of this log entry in the sequence of split logs. Log entries are
  // given |index| values 0, 1, ..., n-1 for a sequence of n entries.
  int32 index = 2;

  // The total number of logs that the original log entry was split into.
  int32 total_splits = 3;
}