secagentd/proto/security_xdr_events.proto

// Copyright 2022 The ChromiumOS Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto2";

option optimize_for = LITE_RUNTIME;

// Used for annotating sensitive fields in google3.
// ${COPYBARA_DATAPOL_IMPORT}

package cros_xdr.reporting;

// The building blocks for the event types.

// Attributes that are common to the entire event.
message CommonEventDataFields {
  optional string local_timezone = 1;
  optional int64 device_boot_time = 2;
}

// Trusted Computing Base attributes.
message TcbAttributes {
  enum FirmwareSecureBoot {
    NONE = 0;
    CROS_FLEX_UEFI_SECURE_BOOT = 1;
    CROS_VERIFIED_BOOT = 2;
  }
  optional string system_firmware_version = 1;
  optional FirmwareSecureBoot firmware_secure_boot = 2;
  // Attributes of the security chip.
  message SecurityChip {
    enum Kind {
      NONE = 0;
      TPM = 1;
      GOOGLE_SECURITY_CHIP = 2;
    }
    optional Kind kind = 1;
    optional string chip_version = 2;
    optional string spec_family = 3;
    optional string spec_level = 4;
    optional string manufacturer = 5;
    optional string vendor_id = 6;
    optional string tpm_model = 7;
    optional string firmware_version = 8;
  }
  optional SecurityChip security_chip = 3;
  optional string linux_kernel_version = 4;
}

// The attributes of a file image.
message FileImage {
  optional string pathname = 1;
  optional uint64 mnt_ns = 2;
  optional uint64 inode_device_id = 3;
  optional uint64 inode = 4;
  optional string sha256 = 5;
  optional uint64 canonical_uid = 6;
  optional uint64 canonical_gid = 7;
  optional uint32 mode = 8;
}

// The attributes of a process.
message Process {
  optional string process_uuid = 1;
  optional uint64 canonical_pid = 2;
  optional uint64 canonical_uid = 3;
  optional string commandline = 4;
  optional FileImage image = 5;
  optional int64 rel_start_time_s = 6;
  optional bool meta_first_appearance = 7;
}

// Namespaces for a process.
message Namespaces {
  optional uint64 cgroup_ns = 1;
  optional uint64 ipc_ns = 2;
  optional uint64 pid_ns = 3;
  optional uint64 user_ns = 4;
  optional uint64 uts_ns = 5;
  optional uint64 mnt_ns = 6;
  optional uint64 net_ns = 7;
}

// The composed event types.

// Encapsulates fields that are common to each message in a
// batch.
message CommonEventVariantDataFields {
  optional int64 create_timestamp_us = 1;
  // ${COPYBARA_DATAPOL_ST_USERNAME}
  optional string device_user = 2;
  // Possible values of device_user:
  // User’s email (affiliated)
  // "UnaffiliatedUser-" prepended to Random UUID (unaffiliated)
  // "" (empty string when no user signed in)
  // "Unknown" (The user is unknown because of internal error) or
  //     the user's affiliation cannot be determined because they have
  //     never previously signed into the device or removed account from device.
  // "GuestUser" (logged in as guest user)
  // "ManagedGuest" (logged in as managed guest set by organization)
  // "KioskApp" (Any kiosk app being used)
  // "SAML-PublicSession" (https://support.google.com/a/answer/6262987?hl=en)
}

// Agent Events.

// Event emitted at the start of execution of an agent process.
message AgentStartEvent {
  optional TcbAttributes tcb = 1;
}

// Periodic event to indicate that an agent is running.
message AgentHeartbeatEvent {
  optional TcbAttributes tcb = 1;
}

message AgentEventAtomicVariant {
  optional CommonEventVariantDataFields common = 1;
  oneof variant_type {
    AgentStartEvent agent_start = 2;
    AgentHeartbeatEvent agent_heartbeat = 3;
  }
}

// Agent Events wrapper.
message XdrAgentEvent {
  optional CommonEventDataFields common = 1;
  oneof message_type {
    AgentStartEvent agent_start = 2 [deprecated = true];
    AgentHeartbeatEvent agent_heartbeat = 3 [deprecated = true];
  }
  repeated AgentEventAtomicVariant batched_events = 4;
}

// Process Events.

// Acting process (forked and) exec'd a new child process.
message ProcessExecEvent {
  optional Process parent_process = 1;
  optional Process process = 2;
  optional Process spawn_process = 3;
  optional Namespaces spawn_namespaces = 4;
  optional int64 terminate_timestamp_us = 5;
}

// Acting process (was) terminated.
message ProcessTerminateEvent {
  optional Process parent_process = 1;
  optional Process process = 2;
}

// Singular Process event.
message ProcessEventAtomicVariant {
  optional CommonEventVariantDataFields common = 1;
  oneof variant_type {
    ProcessExecEvent process_exec = 2;
    ProcessTerminateEvent process_terminate = 3;
  }
}

// Process Events wrapper.
message XdrProcessEvent {
  optional CommonEventDataFields common = 1;
  oneof message_type {
    ProcessExecEvent process_exec = 2 [deprecated = true];
    ProcessTerminateEvent process_terminate = 3 [deprecated = true];
  }
  repeated ProcessEventAtomicVariant batched_events = 4;
}

// Network Events.

// Singular network event.
message NetworkEventAtomicVariant {
  optional CommonEventVariantDataFields common = 1;
  oneof variant_type {
    NetworkFlowEvent network_flow = 2;
    NetworkSocketListenEvent network_socket_listen = 3;
  }
}

// Network Event wrapper.
message XdrNetworkEvent {
  optional CommonEventDataFields common = 1;
  repeated NetworkEventAtomicVariant batched_events = 2;
}

// Used for Network Events.
enum NetworkProtocol {
  NETWORK_PROTOCOL_UNKNOWN = 0;
  TCP = 1;
  UDP = 2;
  ICMP = 3;
  RAW = 4;
}

enum SocketType {
  SOCK_STREAM = 1;
  SOCK_DGRAM = 2;
  SOCK_SEQPACKET = 3;
  SOCK_RAW = 4;
  SOCK_RDM = 5;
  SOCK_PACKET = 6;  // According to socket(2) is obsolete.
}

message NetworkFlow {
  enum Direction {
    DIRECTION_UNKNOWN = 0;
    INCOMING = 1;
    OUTGOING = 2;
  }
  enum ApplicationProtocol {
    APPLICATION_PROTOCOL_UNKNOWN = 0;
    HTTP = 1;
    HTTPS = 2;
    DNS = 3;
  }
  optional string community_id_v1 = 1;
  // ${COPYBARA_DATAPOL_ST_IP_ADDRESS}
  optional string local_ip = 2;
  optional uint64 local_port = 3;
  // ${COPYBARA_DATAPOL_ST_IP_ADDRESS}
  optional string remote_ip = 4;
  // ${COPYBARA_DATAPOL_ST_NOT_REQUIRED}
  optional uint64 remote_port = 5;
  optional NetworkProtocol protocol = 6;
  optional Direction direction = 7;
  // ${COPYBARA_DATAPOL_ST_NETWORK_ENDPOINT}
  optional string remote_hostname = 8;
  optional uint64 rx_bytes = 9;
  optional uint64 tx_bytes = 10;
  optional ApplicationProtocol application_protocol = 11;
  // ${COPYBARA_DATAPOL_ST_NETWORK_ENDPOINT}
  optional string http_host = 12;
  // ${COPYBARA_DATAPOL_ST_NETWORK_ENDPOINT}
  optional string sni_host = 13;
}

// Acting process communicated externally over the network.
message NetworkFlowEvent {
  optional Process parent_process = 1;
  optional Process process = 2;
  optional NetworkFlow network_flow = 3;
}

message Socket {
  optional NetworkProtocol protocol = 1;
  // ${COPYBARA_DATAPOL_ST_IP_ADDRESS}
  optional string bind_addr = 2;
  optional uint64 bind_port = 3;
  optional SocketType socket_type = 4;
}

// Acting process is listening for connections on a socket.
message NetworkSocketListenEvent {
  optional Process parent_process = 1;
  optional Process process = 2;
  optional Socket socket = 3;
}

// User Events.

// User Event Wrapper.
message XdrUserEvent {
  optional CommonEventDataFields common = 1;
  repeated UserEventAtomicVariant batched_events = 2;
}

// Singular User event.
message UserEventAtomicVariant {
  optional CommonEventVariantDataFields common = 1;
  oneof variant_type {
    AuthenticateEvent logon = 2;
    AuthenticateEvent logoff = 3;
    AuthenticateEvent unlock = 4;
    AuthenticateEvent lock = 5;
    AuthenticateEvent failure = 6;
  }
}

// Authentication Events.

// authentication field only used for entry events.
message AuthenticateEvent {
  optional Authentication authentication = 1;
}

// num_failed_attempts only used for the "failure" AuthenticateEvent.
message Authentication {
  // This should follow the Cryptohome AuthFactorType.
  // https://chromium.googlesource.com/chromiumos/platform2/+/main/cryptohome/auth_factor/auth_factor_type.h#13
  enum AuthenticationType {
    AUTH_TYPE_UNKNOWN = 0;
    AUTH_PASSWORD = 1;
    AUTH_PIN = 2;
    AUTH_ONLINE_RECOVERY = 3;
    AUTH_KIOSK = 4;
    AUTH_SMART_CARD = 5;
    AUTH_FINGERPRINT = 6;
    AUTH_NEW_USER = 7;
  }
  repeated AuthenticationType auth_factor = 1 [packed = true];
  optional uint64 num_failed_attempts = 2;
}