Add remarks to rework to the schema

audit/api/api_common.go

@@ -109,7 +109,7 @@ func validateAndSerializePartially(
 	}
 
 	routableEvent := auditV1.RoutableAuditEvent{
-		EventName:  event.EventName,
+		EventName:  event.LogName,
 		Visibility: visibility,
 		Data:       &auditV1.RoutableAuditEvent_UnencryptedData{UnencryptedData: &payload},
 	}

audit/api/api_legacy.go

@@ -139,23 +139,23 @@ func (a *LegacyAuditApi) convertAndSerializeIntoLegacyFormat(
 	// Source IP & User agent
 	var sourceIpAddress string
 	var userAgent string
-	if event.Request == nil {
+	if event.ProtoPayload == nil || event.ProtoPayload.RequestMetadata == nil {
 		sourceIpAddress = "0.0.0.0"
 		userAgent = "none"
 	} else {
-		sourceIpAddress = event.Request.GetSourceIpAddress()
+		sourceIpAddress = event.ProtoPayload.RequestMetadata.CallerIp
-		userAgent = event.Request.GetUserAgent()
+		userAgent = event.ProtoPayload.RequestMetadata.CallerSuppliedUserAgent
 	}
 
 	// Principals
 	var serviceAccountDelegationInfo *LegacyAuditEventServiceAccountDelegationInfo = nil
-	if len(event.Principals) > 0 {
+	if len(event.ProtoPayload.AuthenticationInfo.ServiceAccountDelegationInfo) > 0 {
 		var principals []LegacyAuditEventPrincipal
-		for _, principal := range event.Principals {
+		for _, principal := range event.ProtoPayload.AuthenticationInfo.ServiceAccountDelegationInfo {
 			if principal != nil {
 				p := LegacyAuditEventPrincipal{
-					Id:    principal.Id,
+					Id:    principal.GetFirstPartyPrincipal().Id,
-					Email: principal.Email,
+					Email: &principal.GetFirstPartyPrincipal().PrincipalEmail,
 				}
 				principals = append(principals, p)
 			}

proto/audit/v1/audit_event.proto

@@ -13,9 +13,11 @@ option go_package = "./audit;auditV1";
 option java_multiple_files = true;
 option java_package = "com.schwarz.stackit.audit.v1";
 
-// The data within all Cloud Audit Logs log entry events.
+// TODO update numbers of elements in messages
-// Equivalent to Google's LogEntryData.
+
-message AuditEvent {
+// 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;
 
@@ -26,8 +28,7 @@ message AuditEvent {
   // the error.
   MonitoredResource resource = 8;
 
-  // The log entry payload, which is always an AuditLog for Cloud Audit Log
+  // The log entry payload, which is always an AuditLog for STACKIT Audit Log events.
-  // events.
   AuditLog proto_payload = 2;
 
   // A unique identifier for the log entry.
@@ -37,25 +38,26 @@ message AuditEvent {
   // information about the log entry.
   map<string, string> labels = 11;
 
-  // Information about an operation associated with the log entry, if
+  // Information about an operation associated with the log entry, if applicable.
-  // 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;
 
-  // Resource name of the trace associated with the log entry, if any. If it
+  // TODO check example
-  // contains a relative resource name, the name is assumed to be relative to
+  // Resource name of the trace associated with the log entry, if any. It
-  // `//tracing.googleapis.com`. Example:
+  // 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
@@ -63,20 +65,22 @@ message AuditEvent {
   // `000000000000004a`.
   string span_id = 27;
 
-  // Information indicating this LogEntry is part of a sequence of multiple logs
+  // Information indicating this log entry is part of a sequence of multiple logs
-  // split from a single LogEntry.
+  // 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
-  // Compute Engine VM instance is `gce_instance`.
+  // 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, Compute Engine VM instances use the
+  // resource descriptor. For example, STACKIT Server instances use the
   // labels `"project_id"`, `"instance_id"`, and `"zone"`.
   map<string, string> labels = 2;
 }
@@ -84,10 +88,12 @@ message MonitoredResource {
 // 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"`.
@@ -100,6 +106,7 @@ message LogEntryOperation {
   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
@@ -107,6 +114,7 @@ message LogEntryOperation {
 // 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;
 
@@ -136,15 +144,19 @@ enum LogSeverity {
   EMERGENCY = 800;
 }
 
-// Common audit log format for Google Cloud Platform API operations.
+// 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,
@@ -153,6 +165,7 @@ message AuditLog {
   //     "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:
@@ -164,6 +177,7 @@ message AuditLog {
   // 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
@@ -191,6 +205,7 @@ message AuditLog {
   // 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.
@@ -199,6 +214,7 @@ message AuditLog {
   // 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.
@@ -210,17 +226,12 @@ message AuditLog {
   // Other service-specific data about the request, response, and other
   // information associated with the current audited event.
   google.protobuf.Struct metadata = 18;
-
-  // Deprecated: Use `metadata` field instead.
-  // Other service-specific data about the request, response, and other
-  // activities.
-  // When the JSON object represented here has a proto equivalent, the proto
-  // name will be indicated in the `@type` property.
-  google.protobuf.Struct service_data = 15;
 }
 
 // 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.
@@ -233,12 +244,14 @@ message AuthenticationInfo {
   // 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:
@@ -248,7 +261,7 @@ message AuthenticationInfo {
 
   // Identity delegation history of an authenticated service account that makes
   // the request. It contains information on the real authorities that try to
-  // access GCP resources by delegating on a service account. When multiple
+  // 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;
@@ -260,6 +273,8 @@ message AuthenticationInfo {
 
 // 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
@@ -277,11 +292,12 @@ message AuthorizationInfo {
   //
   // To get the whole view of the attributes used in IAM
   // condition evaluation, the user must also look into
-  // `AuditLogData.request_metadata.request_attributes`.
+  // `AuditLog.request_metadata.request_attributes`.
   AttributeContext.Resource resource_attributes = 5;
 }
 
-// This message defines the standard attribute vocabulary for Google APIs.
+// 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
@@ -299,11 +315,13 @@ message AuthorizationInfo {
 // 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;
 
@@ -315,7 +333,7 @@ message AttributeContext {
 
     // The identity of this peer. Similar to `Request.auth.principal`, but
     // relative to the peer instead of the request. For example, the
-    // idenity associated with a load balancer that forwared the request.
+    // identity associated with a load balancer that forwarded the request.
     string principal = 7;
 
     // The CLDR country/region code associated with the above IP address.
@@ -328,6 +346,8 @@ message AttributeContext {
   // 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
@@ -335,6 +355,7 @@ message AttributeContext {
     // "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
@@ -351,12 +372,14 @@ message AttributeContext {
     // 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
@@ -374,6 +397,7 @@ message AttributeContext {
     // 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:
@@ -388,6 +412,7 @@ message AttributeContext {
   // 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.
@@ -439,6 +464,7 @@ message AttributeContext {
   // 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;
 
@@ -459,11 +485,14 @@ message AttributeContext {
   // 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:
@@ -478,12 +507,14 @@ message AttributeContext {
     // 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;
@@ -492,6 +523,8 @@ message AttributeContext {
 
 // 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
@@ -503,6 +536,7 @@ message RequestMetadata {
   // 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:
@@ -516,6 +550,7 @@ message RequestMetadata {
   //     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.
@@ -525,16 +560,17 @@ message RequestMetadata {
   //     "//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
@@ -545,14 +581,13 @@ message RequestMetadata {
 
 // 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:
   //
-  //     "europe-west1-a"
+  //     "eu01"
-  //     "us-east1"
-  //     "nam3"
   repeated string current_locations = 1;
 
   // The locations of a resource prior to the execution of the operation.
@@ -560,12 +595,11 @@ message ResourceLocation {
   // 'original_locations' as well as the 'current_locations' fields.
   // For example:
   //
-  //     "europe-west1-a"
+  //     "eu01"
-  //     "us-east1"
-  //     "nam3"
   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
@@ -574,14 +608,17 @@ message ResourceLocation {
 // 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
-  // [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
+  // 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;
@@ -589,17 +626,32 @@ message RpcStatus {
 
 // Identity delegation history of an authenticated service account.
 message ServiceAccountDelegationInfo {
-  // First party identity principal.
+
-  message FirstPartyPrincipal {
+  // TODO Introduce but check if needed
-    // The email address of a Google account.
+  message SystemPrincipal {
-    string principal_email = 1;
 
     // Metadata about the service that uses the service account.
-    google.protobuf.Struct service_metadata = 2;
+    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;
   }
@@ -607,27 +659,32 @@ message ServiceAccountDelegationInfo {
   // Entity that creates credentials for service account and assumes its
   // identity for authentication.
   oneof Authority {
-    // First party (Google) identity as the real authority.
+
-    FirstPartyPrincipal first_party_principal = 1;
+    // 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 = 2;
+    ThirdPartyPrincipal third_party_principal = 3;
   }
 }
 
 // Additional information used to correlate multiple LogEntries. Used when a
-// single LogEntry would exceed the Google Cloud Logging size limit and is split
+// single log entry would exceed the STACKIT logging size limit and is split
 // across multiple entries.
 message LogSplit {
-  // A globally unique identifier for all LogEntries in a sequence of split
+
-  // logs. All LogEntries with the same |LogSplit.uid| are assumed to be part of
+  // 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 LogEntry in the sequence of split logs. LogEntries are
+  // 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 LogEntry was split into.
+  // The total number of logs that the original log entry was split into.
   int32 total_splits = 3;
 }