audit-go/proto/audit/v1/audit_event.proto

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
// TODO decide which fields should be optional

// 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.
  // Example: projects/<identifier>/logs/<eventType>
  string log_name = 12;

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

  // TODO can we specify how the format should look like?
  // TODO Encode sequence number into it?
  // https://softwaremind.com/blog/the-unique-features-of-snowflake-id-and-its-comparison-to-uuid/
  // A unique identifier for the log entry.
  // Is generated and set by the SDK.
  // Format:
  // <timestamp>/<region>/<worker-id>/<sequence-number>
  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;

  // Correlate multiple audit logs by setting the same id
  string correlation_id = 15;

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

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

  // W3C conform trace parent header:
  // https://www.w3.org/TR/trace-context/#traceparent-header
  //
  // Example:
  // `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01`
  string trace_parent = 22;

  // W3C conform trace state header:
  // https://www.w3.org/TR/trace-context/#tracestate-header
  //
  // Example:
  // `rojo=00f067aa0ba902b7,congo=t61rcWkgMzE`.
  string trace_state = 27;
}

// 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;
}

// Common audit log format for STACKIT API operations.
message AuditLog {

  // The name of the API service performing the operation. For example,
  // `"resource-manager"`.
  string service_name = 7;

  // TODO: Add extra field to open api spec for the method_name
  // The name of the service method or operation.
  // The format should is:
  // stackit.<product>.<version>.<object>.<operation>
  //
  // For example,
  //
  //     "stackit.resourcemanager.v1.organization.created"
  //     "stackit.authorization.v2.organization.moved"
  //     "stackit.authorization.v2.folder.moved"
  optional string method_name = 8;

  // 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:
  //
  //     "projects/<id>/zones/<region-zone>/vms/<vm-id>"
  //     "projects/<id>/zones/<region-zone>/vms/<vm-id>/ports/<port-id>"
  //     "projects/<id>/zones/<region-zone>/instances/instance-20240723-184227
  string resource_name = 11;

  // 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;

  // 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.
  google.protobuf.Struct request = 16;

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

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

  // 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.
  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 {

  // Principal id
  string principal_id = 1;

  // The email address of the authenticated user
  string principal_email = 2;

  // The name of the service account used to create or exchange
  // credentials for authenticating the service account making the request.
  // Example:
  //
  // "projects/{PROJECT_ID}/serviceAccounts/{ACCOUNT}"
  optional string service_account_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;
}

// Authorization information for the operation.
message AuthorizationInfo {

  // The resource being accessed, as a REST-style string.
  //
  // For example:
  //     Project scoped resource: projects/test-project-123/zones/us-central1-b/instances/instance-20240723-174217
  //     Global Resource: projects/_/buckets/adfeaf
  string resource = 1;

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

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

// 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 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;
  }

  // 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 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;

    // 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;
  }
}

// Metadata about the request.
message RequestMetadata {

  // The IP address of the caller.
  // For caller from internet, this will be public IPv4 or IPv6 address.
  // For caller from a VM / K8s Service / etc, this
  // will be the SIT proxy's IPv4 address.
  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
  // 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;
}

// The `Status` type defines a logical error model that is suitable for
// different programming environments, including REST APIs and RPC APIs.
// Each `ResponseStatus` message contains three pieces of data:
// error code, error message, and error details.
message ResponseStatus {

  // The http or gRPC status code.
  int32 code = 1;

  // Short description of the error
  string message = 2;

  // Error details
  repeated google.protobuf.Struct details = 3;
}

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

  // Anonymous system principal to be used when no user identity is available.
  message SystemPrincipal {

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

  // STACKIT idp principal.
  message IdpPrincipal {

    // STACKIT principal id
    string principal_id = 1;

    // Optional email address
    optional string principal_email = 2;

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

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

    // System identity
    SystemPrincipal system_principal = 1;

    // STACKIT IDP identity
    IdpPrincipal idp_principal = 2;
  }
}